source: GTP/trunk/App/Demos/Illum/pathmap/README.txt @ 2197

GameTools standalone tool:

Command line options
#############################
> pathmap.exe [s|p/v] -D <media input directory> -L <level file> -M <materials file> -O <mesh output dir>
-P <prm out put dir> -E <number of entry points> -C <number of clusters> -S <shadow map resolution>

operations
        s -     Segment input meshes: creates new versions of input meshes, and outputs them to the <mesh output dir>.
                These processed meshes will contain smaller submeshes, to which PRM textures will be assigned.
        p - Precompute PRM textures. Outputs textures (hdr format), a new level file (with cluster assigment info), 
                and an entry point file.
        sp-     Do both of the above.
        v - Do neither of the above, only visualize results.
        
switches
        D       directory for input files (level file, material file, meshes in .x or OGRE xml format, texture images)
        L       file name of level file (txt file listing meshes and entities)
        M       file name for material file (txt file listing material name - color texture pairs)
        O       output directory for segmented meshes and the new level file
                (this is also the input directory for the same files if operation 's' is not specified)
        P       output directory for PRM textures and the entry point file.
                (this is also the input directory for the same if operation 'p' is not specified)
        E       number of entry points. Must be 4096*n.
        C       number of entry point clusters overall. How many of them influences a single entity is given in the level file.
        S       depth map resolution used for indirect illumination precomputation.


File formats
#############################
Level file [media\*.level]
        Lists meshes and entities.
        Mesh attributes:
                ogrefile                        Binary OGRE file.       (output as input, not used in tool)
                ogreXMLfile                     XML OGRE file.          (loaded in tool)
                xfile                           DirectX mesh file.      (loaded if no OGRE xml specified)
                patmapresolution        PRM tile resolution. (also influences UV map generation)
                divide                          Number of desired mesh segments. (a PRM texture is assigned to a segment)
        Entity attributes
                mesh                            mesh name
                transformation          modeling trnasformation as a 4x4 matrix
                pathmapclusters         number of clusters relevant to subentities of this entity (recommended:32)
                pathmapfile                     output texture file name stub

Material file [media/*.materials]
        XML file that describes materials OGRE for the pathmap tool.
        For every material name, a texture name or a solid color is given.

Entry points file [prm\prmEntryPoints.text]     
        Lists entry points with position, normal and generation probability,
        plus number of entry points per cluster.
        

Real-time global illumination
#############################


Provided effect:
#################

Indirect illumination with Precomputed Radiance Maps (PRM)

Standalone final rendering (real time GI) application without or with [if
GENERATE_PATH_MAPS is defined in PathMapEffect.cpp] PRM precomputing


Algorithm benefits:
###################
Provides real-time indirect illumination. As opposed to static light maps,
actual lighting conditions influence indirect illumination. The effect is
achieved by combining multiple 'PRM panes' (partial "light maps") according to
current illumination of 'entry point clusters'.

As opposed to PRT (precomputed radiance transfer), no tessellation (finite
elements) is needed, and near light sources are handled. (We do not assume
infinitely distant
environment lighting.)

Accuracy of PRMs depends on the number of entry points used, influencing
preocessing time only.

Final rendering requires a compositing of PRMs, where performance depends on the
number of 'entry point clusters' considered for an object. As many texture
fetches as clusters are needed. A lower number of clusters will result in
indirect illumination which is less responsive to actual lighting, but still
plausible. (A single cluster would reproduce a static light map which is scaled
according to the total direct illumination.)


Build:
######
This is a standalone DirectX 9.0 application, compiles under Visual C++ 2003
with DirectX SDK April 2006 (identical to June 2006).

Parameters (PRM resolution, shadow map resolution, #entry points, #clusters,
etc.) are hardcoded as #define directives in PathMapEffect.h.

GENERATE_PATH_MAPS in PathMapEffect.cpp must be defined to perform precomputing,
outputting textures to the PRM subfolder. Otherwise, PRM textures are loaded
from the PRM subfolder.


Usage notes:
############
- as precomputing is used, this tool should be used for static level geometry
- multiple static objects are supported and encouraged: every object will use a
set of most important PRM panes
- models must have unique texture mapping (just like light maps)

- there is no support for any particular 'level geometry' discription format.
DirectX .x files and referenced textures are loaded from code.
- To include the method in a particular engine, the level geometry should be
used to compose the scene which is used to generate the PRM textures. Final
compositing must be implemented in the shader system of the game engine,
assigning the computed PRMs to the respective objects as textures.