============
FractureTool
============

FractureTool is a command-utility for generating destructible assets from regular mesh assets.
It exposes a subset of options provided by the DestructibleAssetAuthoring API, and can be used
for batch processing of simple fracture configurations or as basic alternative to PhysXLab.

Running **FractureTool.exe -h**, or simply **FractureTool.exe** without any arguments, results in a
full usage description.

..  code-block:: none


Usage: FractureToolDEBUG.exe [OPTIONS]

     Fracture and save a mesh given [OPTIONS] control parameters.
    
      -m   	-mesh                	path to an unfractured mesh (required)
      -o   	-output              	name of output file, placed in same directory as input mesh
      -x   	-xml                 	when specified, save the output as xml (default is binary)
      -f   	-fracture-config     	name of the fracture config file
      -vb  	-verbose             	when specified, enable maximum verbosity
      -d   	-depth               	number of depth levels for fracturing (default = 3)
      -s   	-slices              	number of slices to make at each depth level (default = 1)
      -sl  	-slice-linear        	slice angular variation (relative to mesh size, default = 0)
      -sa  	-slice-angular       	slice angular variation (radians, default = 0.1)
      -na  	-noise-amplitude     	noise amplitude (relative to mesh size, default = 0)
      -nf  	-noise-frequency     	noise frequency (relative to 1/(grid spacing, default = 0.25)
      -ng  	-noise-grid-size     	noise field grid size (# elements across mesh, default = 10)
      -nm  	-noise-mode          	noise mode (0 = planewave (default), 1 = 2d perlin, 2 = 3d perlin
      -v   	-voronoi             	when specified, use voronoi fracture in place of slice fracture
      -vs  	-voronoi-sites       	number of cell sites used in voronoi fracture (default = 15)
      -se  	-seed                	random seed (default = 0)
      -iu  	-interior-u          	interior u scale (default = 1.0)
      -iv  	-interior-v          	interior v scale (default = 1.0)
      -im  	-interior-material   	interior material name
      -om  	-override-material   	when specified, mesh materials will be overridden with defaults
      -ot  	-override-texture    	when specified, mesh textures will be overridden with defaults
      -em  	-export-material     	when specified, export materials in addition to the asset
      -dm  	-disp-maps           	when specified, use displacement maps in place of geometric noise
      -edm 	-export-disp-maps    	when specified, export displacement maps as texture
      -p   	-profile             	when specified, display basic timing profile of fracture tool
      -sn  	-smooth-normals      	when specified, smooth normals of interior vertices
    
    Examples:
    
    FractureTool.exe -m block.obj -x -d 2 -s 1 -sa 0   -na 0.2 -em -dm -edm 
      Fracture block.obj with tessellated noise and export materials, displacement maps and xml asset.
    
    FractureTool.exe -m block.obj    -d 1 -s 5 -sa 0.2 -na 0.2 -em 
      Fracture block.obj with noise and export materials and binary asset.
    
    FractureTool.exe -m block.obj    -d 3 -s 2 -sa 0.2
      Fracture block.obj without noise and export binary asset.
    
    FractureTool.exe -m block.obj -v -vs=15
      Fracture block.obj using voronoi splitting and export binary asset.

    Supported input mesh formats:
      apx (APEX Xml    - must be a render mesh asset)
      apb (APEX Binary - must be a render mesh asset)
      obj
      fbx
      ezm

    Supported output asset formats:
      apx
      apb

    Supported fracture modes:
      slice
      voronoi

For instance, a session to produce a Voronoi-fractured OBJ mesh using 100 Voronoi sites would look as follows:

.. code-block:: none

  FractureTool.exe -m block.obj -v -vs=100

  APEX Fracture Tool  (Press any key to cancel...)

  Loaded     \ [==================================================]  100%
  Fractured  | [==================================================]  100%
  Saved      | [==================================================]  100%

  Success!

  Files exported to PATH/TO/OUTPUT/
    Asset:                block.apb

Again, all of the command-line options are fully described by simply running FractureTool.

Tessellation
============

A natural way to extend the detail of destructible assets is with hardware-accelarated
tessellation.  As a purely graphical effect, run-time tessellation provides additional
visual fidelity without sacrificing simulation performance; it's a great way to add
roughness and realism to fractured chunks.

By design, the core APEX destruction module provides very little in the way of explicit
tessellation support.  However, FractureTool (and in the future, PhysXLab) offers a simple
way to augment destructible assets with tessellated materials. Together with the
SimpleDestruction example, it provides a rough template of how tessellation can work in a
destructible pipeline.

The following command-line sequence illustrates one such example:

.. code-block:: none

   FractureTool.exe -mesh block.obj -output block.apb -noise-amplitude .5 -export-material -disp-maps -export-disp-maps

Run with shorthand, we have the following:

.. code-block:: none

  FractureTool.exe -m block.obj -o block.apb -na .5 -em -dm -edm

  APEX Fracture Tool  (Press any key to cancel...)

  Loaded     \ [==================================================]  100%
  Fractured  | [==================================================]  100%
  Saved      | [==================================================]  100%

  Success!

  Files exported to PATH/TO/OUTPUT/
    Displacement Map:     blockDisplacementMap.dds
    Material:             blockMaterial0.xml
    Material:             blockMaterial1.xml
    Asset:                block.apb

This command will perform a slice fracture of *block.obj*.  However, rather than adding
actual geometric noise, by specifying **-disp-maps** and **-export-disp-maps**, and providing a non-zero
**-noise-amplitude**, FractureTool generates and stores the noise in a 3D texture (*blockDisplacementMap.dds*).
The **-export-material** flag outputs materials for the asset that are compatible with SimpleDestruction.

We can view the tessellated result by running

.. code-block:: none

  SimpleDestruction.exe -loadasset block.apb -d3d11

The **-d3d11** flag loads the DX11 renderer, which is required for tessellation in SimpleDestruction.

	Note: For SimpleDestruction to properly import the asset, the exported texture and material files must be in a directory accessible to SimpleDestruction (typically **APEX_INSTALL_DIR/media/APEX/1.4/SimpleDestruction**)

In the end, most of the tessellation work is performed in the actual domain and hull shaders.  Two such implemenations are included in the Sample framework:

.. code-block:: none

  shaders/tessellation/texture_noise.cg
  shaders/tessellation/procedural_noise.cg

*texture_noise.cg* will use the 3D displacement map texture provided by FractureTool.  If the **-export-disp-maps** option is removed when using FractureTool, the generated material will instead use *procedural_noise.cg*.  This shader uses a simple 3D Perlin noise generator to add tessellated detail at run-time.
