source: GTP/trunk/App/Demos/Vis/KdTreeDemo/README.txt @ 1516

MANPAGE FOR TestKdTree

NAME
  TestKdTree.exe

SYNOPSIS
  TestKdTree [options]

COMMAND LINE OPTIONS
  -o <filename>, --outfile <filename>
    Save a recorded demo to file <filename>.
    See DEMOS for details

  -i <filename>, --infile <filename>
    Load a demo created by the application from file <filename>.
    See DEMOS for details.

  -l <filename>, --logfile <filename>
    Save the FPS log of a demo benchmark in file <filename>. The log is saved
    as a CSV text file. See DEMOS for details.
    To have any effect, requires --demomode.
    
  -f, --faststart
    Skip Ogre startup dialog. A valid ogre.cfg file must exist in the working
    directory, otherwise the program will abort.

  -d, --demomode
    Start the application in demomode. See DEMOS for details.
    Requires --infile, otherwise no benchmark is run.
    
  -b, --burnin
    Run a burn-in demo, i.e. loop the demo until ESC is pressed. Requires
    --demomode. When --logfile is specified, the result of each run will be
    saved.

  -s <sm_id>, --scenemgr <sm_id>
    Use specified scene manager. So far, the following scene managers are
    supported:
      KdTreeSceneManager            sm_id=KDT (DEFAULT)
      KdTerrainSceneManager         sm_id=KTE
      BvHierarchSceneMananger                           sm_id=BVH
      OcclusionCullingSceneManager  sm_id=OCM
      OctreeSceneManager            sm_id=OCT
      TerrainSceneManager           sm_id=TER
      DefaultSceneManager           sm_id=GEN

  -r <rm_id>, --rendermode <rm_id>
    Use specified rendermode within the scene manager, if supported:
      Internal Frustum Culling      rm_id=INT (KDT, KTE, BVH)
      View Frustum Culling          rm_id=VFC (KDT, KTE, BVH, OCM)
      Stop and Wait Culling         rm_id=SWC (KDT, KTE, BVH, OCM)
      Coherent Hierarchical Culling rm_id=CHC (KDT, KTE, BVH, OCM) (DEFAULT)
    Setting a rendermode for a scene manager that does not support it has
    no effect. For supported scene managers, render mode switching is also
    available ingame (see INGAME COMMANDS).
    
  -v [mode], --viewcells [mode]
    Set view cell mode. Applies only to scenes where view cells can be loaded
    (see CONFIG FILE), otherwise has no effect. [mode] is optional.
    Valid values for [mode] are:
      0 ... do not use view cells for visibility (same as ommiting -v)
      1 ... use view cells for visibility (same as -v without parameter)
      2 ... use view cells and visibility filter
    These setting can also be changeg ingame (see INGAME COMMANDS).
    
  --nodelrq
    Do not delete render queue after each frame (which actually is normal
    Ogre behavior). Deleting the render queue significantly improves framerates
    when using occlusion culling.

  --comment
    Append a comment to the logfile. Requires --logfile to have any effect.
    (see DEMOS).
    
  --savesceneto <filename>
    Specifies file name (with .txt extension) to which the positions of all
    entities in the scene will be saved. If the filename is appended to
    the scene parameter in the config file, the entities are loaded at
    startup

  The following options apply only to the KDT and KTE scene managers. They have
  no effect when another scene manager is selected. Besides --enhancevis, they
  influenc how the KdTree which organizes the scene is built.

  -e, --enhancevis
    Enable enhanced visibility test (which, sadly, has little or no effect).
    Only supported with INT render mode.
    Enhanced visibility tries to abort tree traversal as early as possible by
    determining if a tree node is fully visible. Then it renders all objects
    contained within with no further traversal or visibility tests. This
    setting can also be changed ingame (see INGAME COMMANDS).

  --buildmode <bm_id>
    Select the mode of building the KdTree.
      Priority Queue    bm_id=PQ
      Recursive         bm_id=RE (DEFAULT)
    This setting can also be changed ingame (see INGAME COMMANDS).

  --maxdepth <n>
    Limit the maximum depth of the kdtree. The default n is 12. A complete
    KdTree with depth n has 2^n leaves and 2^(n+1)-1 total nodes. However,
    depending on the structure of the underying scene, a typical KdTree has
    far less nodes.

  --kt
  --ki
    These parameters define the two "magic numbers" used by the SAH algorithm
    to determine the cost of splitting a node. In simple terms, KT is the cost
    of traversing a node on the way down while KI is the cost of intersecting
    (rendering) a leaf node. KI is multiplied with the number and size of
    objects within the leaf. The default values are KT=2.0 and KI=1.0, since
    they seem to produce acceptable trees.

CONFIG FILE
  The config file must have the name "testKdTree.cfg" and be found in the same
  directory as the TestKdTree executable. It is used mainly for configuring
  the simple test scene details. The config file has the following options:
    scene:  Select the scene which shall be loaded.
            If the parameter is empty or missing, the simple test scene is
            loaded (spaceships & robots on a plane).
            Otherwise the parameter is interpreted as a semicolon-separated
            list of scene files to load. So far the application supports the
            following formats:
              .iv, .wrl:  Mesh files like the vienna scene.
              .cfg:       Config files for terrain creation. You need to
                          specify an appropriate scene manager which supports
                          terrain world geometry rendering (KTE, OCM, TER).
              .txt:       Text file created by the application which store
                          positions of entites (small movable objects)
    viewcells:
            Load preprocessed PVS from file. Has no effect for terrain and
            simple scenes.
    movespeed, rotatespeed:
            Set the speed of movement and rotation for the player camera.
            Movespeed is world units per second, rotatespeed is degrees per
            second.
  The following options apply only to the simple test scene:
    planedim:
            Size of the base plane
    randomcount:
            Number of randomly placed object of each class to generate
    count, spacing:
            Number of robots placed in a grid in the center of the scene.
            Actual number is count^2. Spacing denotes the distance between two
            robots in a row or column.
    radius, period:
            Distance from scene origin and time to complete one circle for the
            moving robot.
    shadows:
            on enables shadows
    selectentities:
            Sum up the following numbers to select which entities will appear
            in the scene:
              1  robots in grid
              2  randomly placed robots
              4  randomly placed spaceships
              8  moving robot
              16 base plane
            So, e.g., 22 is plane with random robots and space ships

INGAME COMMANDS

  ESC   Exit the program

  The following commands can be used from within the game when --demomode
  is NOT specified:

  Visualisation:
    F2  Toggle Visualisation camera (lower right): Boxes-Objects-Off-...
        Works diffently, depending on selected scene manager
    F3  Toggle Node Visualisation:  Highlighted-All-Off-...
        Works diffently, depending on selected scene manager
    F4  Toggle between nodes and bounding box heirarchy (KDT and KTE only)
    3,4 Decrease/Increase KdTree level which to highlight (KDT and KTE only)
    B   Show bounding boxes of all objects

  Demos:
    F5  Start/Stop recoring demo
    F6  Save recorded demo
    F9  Start/Stop demo playback

  KdTree building:
    1,2         Decrease/Increase maximum depth
    5,6         Decrease/Increase KT
    7,8         Decrease/Increase KI
    0           Toggle build mode (Recursive, Priorty Queue)
    BACKSPACE   Rebuild KdTree with the settings from above.

  Movement:
    U           Toggle free move, stick to ground
    W,A,S,D     Forward, Strafe Left, Back, Strafe Right
    UP,DOWN     Forward, Back
    LEFT,RIGHT  Turn Left, Turn Right
    PGUP,PGDOWN Up, Down (when in free move mode)
    I           Toggle Vis Camera follow, free
    NUM+,NUM-   Zoom Vis Camera
    NUM{8,2,4,6}Move vis camera up, down, left right (when free)

  Rendering:
    SPACE Toggle render mode for (KDT, KTE, BVH, OCM), see --rendermode
    V     Toggle enhanced visibility for (KDT, KTE), see --enhancevis
    R     Toggle OpenGL/Direct3D render mode (Full, Line, Point)
    T     Toggle OpenGL/Direct3D texture filtering (Bilinear, Trilinear, Aniso)
    C     Toggle use view cells from PVS (load on demand)
    X     Toggle use visibility filter (whatever that is)

  Other:
    M     Toggle between buffered and unbuffered mouse input
    K     Toggle between buffered and unbuffered keyboard input
    F     Show/Hide overlays
    P     Show/Hide player cam position
    PRINT Save sceen shot
    F7    Save Entities in the scene to file
    F8    Generate random entities for terrain scene

DEMOS
  The program has the ability to record, save and load demos, i.e. a path
  through the scene. The program can save demos in two formats:
  ASCII (extension .txt) and binary (extension .bin). The file name must
  have one of these extensions and the format is selected by the program
  accordingly.
  Within the program, a demo can be recorded at any time (except when playing
  back another demo) by pressing the F5 button. A record indicator appears on
  the top of the screen. By pressing F5 again, the recording is stopped.
  Pressing F9 will play back the recorded demo and return the player camera to
  the previous position when it's done. The playback can be stopped by pressing
  F9.
  If the demo shall be permanently stored, the program must be launched with
  the --outfile option, specifying a file to which the demo will be saved. The
  file name must have on of the above mentioned extensions. If the file
  allready exists and a demo is saved, it will be overwritten. To save a
  recorded demo, simply press F6 to store it in the file. If a demo has been
  allready stored in this session, it will be overwritten.
  It is recommended to limit the framerate of the application (e.g. by enabling
  vsync) when recording a demo, since it will produce smaller files.
  To load a demo from a file, specify it with the --infile command line option.
  To run a benchmark, a prerecorded demo must be loaded. Also, a logfile has to
  be specified using the --logfile option. Finally the --demomode option must
  be set. The program starts with disabled user input and no overlays. After an
  initial 5 second delay, to stabilize the framerate and preload the scene, the
  demo is played back and the framerate and other statistics are recored. Then
  the program exits and writes the stats to the logfile. The benchmark can be
  interrupted with the ESC key, but then no statistics are recorded.
  The logfile is in CSV format for easy evaluation in spreadsheet applications.
  The first row is the header consisting of:
    The name of the demo file which was used for this benchmark
    Timestamps of each FPS capture (starting with 0, in seconds)
    Min, Avg, Max FPS headers
    Total frames and total time headers
    Comment header
  The consecutive rows are filled with demo data, one row per benchmark run,
  with the settings used for building and rendering in the first column.
  If the specified logfile does not exist, it is created including the headers.
  If a log file with the specified name does exists, it is checked if the demo
  file used in the logfile corresponds with the demo file used in this
  benchmark run. If the names do not match, or if the logfile cannot be read or
  written to, the demo is executed but no stats are written. Additionaly, an
  error message is written to "Ogre.log". However, if the log file exists and
  the demo name matches, the resulst are appended to the existing logfile,
  allowing for easy comparison of different settings and options.

BUGS
  Mysterious and serious (sometimes bluescreen) crashes due to an error in the
  nVidia display driver (nv4_disp.dll). Occur with the following combination:
  Direct3D Render Manager + terrain rendering with OCM or KTE + 
  hardware occlusion culling enabled (CHC, possibly also SWC) + demo playback.
  Not tested on other hardware (e.g. ATI cards). Not exactly repeatable,
  crashes in different places during playback or not at all.

AUTHOR
  Martin Szydlowski <msz@seclab.tuwien.ac.at>
  
LICENSE
  GameTools