diff options
Diffstat (limited to 'src/mesh/assimp-master/doc/dox_cmd.h')
| -rw-r--r-- | src/mesh/assimp-master/doc/dox_cmd.h | 565 |
1 files changed, 565 insertions, 0 deletions
diff --git a/src/mesh/assimp-master/doc/dox_cmd.h b/src/mesh/assimp-master/doc/dox_cmd.h new file mode 100644 index 0000000..79ea3a8 --- /dev/null +++ b/src/mesh/assimp-master/doc/dox_cmd.h @@ -0,0 +1,565 @@ +/** @file dox_cmd.h + * @brief General documentation for assimp_cmd + */ + + +//---------------------------------------------------------------------------------------------- +// ASSIMP CMD MAINPAGE +/** +@mainpage ASSIMP Command-line tools + +<img src="dragonsplash.png"></img> + +@section intro Introduction + +This document describes the usage of assimp's command line tools. +This is *not* the SDK reference and programming-related stuff is not covered here. +<br><br> +<b>NOTE</b>: For simplicity, the following sections are written with Windows in mind. However +it's not different for Linux/Mac at all, except there's probably no assimp.exe ... + +@section basic_use Basic use + +Open a command prompt and navigate to the directory where assimp.exe resides. The basic command line is: + +@code +assimp [command] [parameters] +@endcode + +The following commands are available: + +<table border="1"> + + <tr> + <td><b>@link version version @endlink</b></td> + <td>Retrieve the current version of assimp</td> + </tr> + <tr> + <td><b>@link help help @endlink</b></td> + <td>Get a list of all commands (yes, it's this list ...)</td> + </tr> + <tr> + <td><b>@link dump dump @endlink</b></td> + <td>Generate a human-readable text dump of a model</td> + </tr> + <tr> + <td><b>@link extract extract @endlink</b></td> + <td>Extract an embedded texture image</td> + </tr> + <tr> + <td><b>@link iinfo info @endlink</b></td> + <td>Load a model and print basic statistics</td> + </tr> + <tr> + <td><b>@link cmpdump cmpdump @endlink</b></td> + <td>Regression checking tool</td> + </tr> +</table> + +If you use assimp's command line frequently, consider adding assimp to your PATH +environment. + + */ + + +/** +@page version 'version'-Command + +Display the version/revision of Assimp used. + */ + +/** +@page help 'help'-Command + +Display a really helpful text. + */ + +//---------------------------------------------------------------------------------------------- +// ASSIMP INFO + +/** +@page iinfo 'info'-Command + +Load a model file and print basic statistics. Full postprocessing is applied unless the <tt>-r</tt> switch is specified. Sample output (<tt>assimp info ./test/models/3DS/mar_rifle.3ds</tt>): + +@verbatim +Launching model import ... OK +Validating postprocessing flags ... OK +Importing file ... OK + import took approx. 0.02400 seconds + +Memory consumption: 69444 B +Nodes: 2 +Maximum depth 2 +Meshes: 1 +Animations: 0 +Textures (embed.): 0 +Materials: 1 +Cameras: 0 +Lights: 0 +Vertices: 843 +Faces: 572 +Bones: 0 +Animation Channels: 0 +Primitive Types: triangles +Average faces/mesh 572 +Average verts/mesh 843 +Minimum point (-3.522588 -11.573204 -40.340359) +Maximum point (3.522622 30.196556 75.941292) +Center point (0.000017 9.311676 17.800467) + +Named Materials: + 'mat1' + +Texture Refs: + 'm_rifl.bmp' + +Node hierarchy: +'<3DSRoot>', meshes: 0 +-- 'm_rifle', meshes: 1 +<-- +@endverbatim + +<h3>Syntax:</h3> + +@code +assimp info file [-r] +@endcode + + +<h3>Parameters:</h3> + +<p> +<tt> +file<br></tt><br> +Required. Input file. +</p> +<p> +<tt> +-r</tt><br> +Optional. Don't perform any postprocessing. The long form of this parameter is <tt>--raw</tt>. +</p> + +*/ +//---------------------------------------------------------------------------------------------- +// ASSIMP CMPDUMP + +/** +@page cmpdump 'cmpdump'-Command + +<b>Used for Assimp's internal regression testing.</b> Compare two mini dumps (produced using <tt>assimp dump .. -b -s</tt>) and +report any differences. In the regression test suite, this facility is used to build a database of +'known-to-be-fine' mini dumps, which are regularly compared against current results to detect regressions. + +<h3>Syntax:</h3> + +@code +assimp cmpdmp actual expected +@endcode + + +<h3>Parameters:</h3> + +<p> +<tt> +actual<br></tt><br> +Required. Mini dump now. +</p> +<p> +<tt> +expected<br></tt><br> +Required. Archived dump from some point in the past. +</p> + +*/ + + +//---------------------------------------------------------------------------------------------- +// ASSIMP DUMP + +/** +@page dump 'dump'-Command + +Generate a text or binary dump of a model. This is the core component of Assimp's internal +regression test suite but it could also be useful for other developers to quickly +examine the contents of a model. Note that text dumps are not intended to be used as +intermediate format, Assimp is not able to read them again, nor is the file format +stable or well-defined. It may change with every revision without notice. +Binary dumps (*.assbin) are backwards- and forwards-compatible. + +<h3>Syntax:</h3> + +@code +assimp dump <model> [<out>] [-b] [-s] [common parameters] +@endcode + + +<h3>Parameters:</h3> + +<p> +<tt> +model<br></tt><br> +Required. Relative or absolute path to the input model. +</p> +<p> +<tt> +out<br></tt><br> +Optional. Relative or absolute path to write the output dump to. If it is omitted, +the dump is written to <tt><model>-dump.txt</tt> +</p> + +<p> +<tt>-b<br> +</tt><br> +Optional. If this switch is specified, the dump is written in binary format. +The long form of this parameter is <tt>--binary</tt>. +</p> + +<p> +<tt>-s<n><br> +</tt><br> +Optional. If this switch is specified, the dump is shortened to include only +min/max values for all vertex components and animation channels. The resulting +file is much smaller, but the original model can't be reconstructed from it. This is +used by Assimp's regression test suite, comparing those minidumps provides +a fast way to verify whether a loader works correctly or not. +The long form of this parameter is <tt>--short</tt>. +</p> + +<p> +<tt> +common parameters<br></tt><br> +Optional. Import configuration & postprocessing. +See the @link common common parameters page @endlink for more information. +</p> + +<hr> + +<h3>Sample:</h3> + +@code +assimp dump test.3ds test.txt -l -cfull +assimp dump test.3ds test.txt -include-log -config=full +@endcode + +Dumps 'test.3ds' to 'test.txt' after executing full post-processing on tehe imported data. +The log output is included with the dump. + + +@code +assimp dump files\*.* +assimp dump files\*.* +@endcode + +Dumps all loadable model files in the 'files' subdir. The output dumps are named +<tt><mode-file>-dump.txt</tt>. The log is not included. + */ + +//---------------------------------------------------------------------------------------------- +// ASSIMP EXTRACT + +/** +@page extract 'extract'-Command + +Extracts one or more embedded texture images from models. + +<h3>Syntax:</h3> + +@code +assimp extract <model> [<out>] [-t<n>] [-f<fmt>] [-ba] [-s] [common parameters] +@endcode + + +<h3>Parameters:</h3> + +<p> +<tt> +model<br></tt><br> +Required. Relative or absolute path to the input model. +</p> +<p> +<tt> +out<br></tt><br> +Optional. Relative or absolute path to write the output images to. If the file name is +omitted the output images are named <tt><model-filename></tt><br> +The suffix <tt>_img<n></tt> is appended to the file name if the -s switch is not specified +(where <tt><n></tt> is the zero-based index of the texture in the model file).<br> + +The output file format is determined from the given file extension. Supported +formats are BMP and TGA. If the file format can't be determined, +the value specified with the -f switch is taken. +<br> +Format settings are ignored for compressed embedded textures. They're always +written in their native file format (e.g. jpg). +</p> + +<p> +<tt>-t<n><br> +</tt><br> +Optional. Specifies the (zero-based) index of the embedded texture to be extracted from +the model. If this option is *not* specified all textures found are exported. +The long form of this parameter is <tt>--texture=<n></tt>. +</p> + +<p> +<tt>-ba<n><br> +</tt><br> +Optional. Specifies whether output BMPs contain an alpha channel or not. +The long form of this parameter is <tt>--bmp-with-alpha=<n></tt>. +</p> + + +<p> +<tt>-f<n><br> +</tt><br> +Optional. Specifies the output file format. Supported +formats are BMP and TGA. The default value is BMP (if a full output filename is +specified, the output file format is taken from its extension, not from here). +The long form of this parameter is <tt>--format=<n></tt>. +</p> + +<p> +<tt>-s<n><br> +</tt><br> +Optional. Prevents the tool from adding the <tt>_img<n></tt> suffix to all filenames. This option +must be specified together with -t to ensure that just one image is written. +The long form of this parameter is <tt>--nosuffix</tt>. +</p> + +<p> +<tt> +common parameters<br></tt><br> +Optional. Import configuration & postprocessing. Most postprocessing-steps don't affect +embedded texture images, configuring too much is probably senseless here. +See the @link common common parameters page @endlink for more information. +</p> + +<hr> + +<h3>Sample:</h3> + +@code +assimp extract test.mdl test.bmp --texture=0 --validate-data-structure +assimp extract test.mdl test.bmp -t=0 -vds +@endcode + +Extracts the first embedded texture (if any) from test.mdl after validating the +imported data structure and writes it to <tt>test_img0.bmp</tt>. + + +@code +assimp extract files\*.mdl *.bmp +assimp extract files\*.mdl *.bmp +@endcode + +Extracts all embedded textures from all loadable .mdl files in the 'files' subdirectory +and writes them to bitmaps which are named <tt><model-file>_img<image-index>.bmp</tt> + */ + +//---------------------------------------------------------------------------------------------- +// ASSIMP COMMON PARAMETERS +/** +@page common Common parameters + +The parameters described on this page are commonly used by almost every assimp command. They +specify how the library will postprocess the imported data. This is done by several +configurable pipeline stages, called 'post processing steps'. Below you can find a list +of all supported steps along with short descriptions of what they're doing. <br><b>Programmers</b>: +more information can be found in the <tt>aiPostProcess.h</tt> header. + +<table border="1"> + <tr> + <th>Parameter</th> + <th>Long parameter</th> + <th>Description</th> + </tr> + <tr> + <td><tt>-ptv</tt></td> + <td><tt>--pretransform-vertices</tt></td> + <td>Move all vertices into worldspace and collapse the scene graph. Animation data is lost. + This is intended for applications which don't support scenegraph-oriented rendering.</td> + </tr> + <tr> + <td><tt>-gsn</tt></td> + <td><tt>--gen-smooth-normals</tt></td> + <td>Computes 'smooth' per-vertex normal vectors if necessary. Mutually exclusive with -gn</td> + </tr> + <tr> + <td><tt>-gn</tt></td> + <td><tt>--gen-normals</tt></td> + <td>Computes 'hard' per-face normal vectors if necessary. Mutually exclusive with -gsn</td> + </tr> + <tr> + <td><tt>-cts</tt></td> + <td><tt>--calc-tangent-space</tt></td> + <td>If one UV channel and normal vectors are given, compute tangents and bitangents</td> + </tr> + <tr> + <td><tt>-jiv</tt></td> + <td><tt>--join-identical-vertices</tt></td> + <td>Optimize the index buffer. If this flag is not specified all vertices are referenced once.</td> + </tr> + <tr> + <td><tt>-rrm</tt></td> + <td><tt>--remove-redundant-materials</tt></td> + <td>Remove redundant materials from the imported data.</td> + </tr> + <tr> + <td><tt>-fd</tt></td> + <td><tt>--find-degenerates</tt></td> + <td>Find and process degenerates primitives.</td> + </tr> + <tr> + <td><tt>-slm</tt></td> + <td><tt>--split-large-meshes</tt></td> + <td>Split large meshes over a specific threshold in smaller sub meshes. The default vertex & face limit is 1000000</td> + </tr> + <tr> + <td><tt>-lbw</tt></td> + <td><tt>--limit-bone-weights</tt></td> + <td>Limit the number of bones influencing a single vertex. The default limit is 4.</td> + </tr> + <tr> + <td><tt>-vds</tt></td> + <td><tt>--validate-data-structure</tt></td> + <td>Performs a full validation of the imported data structure. Recommended to avoid crashes if + an import plugin produces rubbish</td> + </tr> + <tr> + <td><tt>-icl</tt></td> + <td><tt>--improve-cache-locality</tt></td> + <td>Improve the cache locality of the vertex buffer by reordering the index buffer + to achieve a lower ACMR (average post-transform vertex cache miss ratio)</td> + </tr> + <tr> + <td><tt>-sbpt</tt></td> + <td><tt>--sort-by-ptype</tt></td> + <td>Splits meshes which consist of more than one kind of primitives (e.g. lines and triangles mixed up) + in 'clean' submeshes. </td> + </tr> + <tr> + <td><tt>-lh</tt></td> + <td><tt>--convert-to-lh</tt></td> + <td>Converts the imported data to left-handed coordinate space</td> + </tr> + <tr> + <td><tt>-fuv</tt></td> + <td><tt>--flip-uv</tt></td> + <td>Flip UV coordinates from upper-left origin to lower-left origin</td> + </tr> + <tr> + <td><tt>-fwo</tt></td> + <td><tt>--flip-winding-order</tt></td> + <td>Flip face winding order from CCW to CW</td> + </tr> + <tr> + <td><tt>-ett</tt></td> + <td><tt>--evaluate-texture-transform</tt></td> + <td>Evaluate per-texture UV transformations (e.g scaling, offset) and build pretransformed UV channels</td> + </tr> + <tr> + <td><tt>-guv</tt></td> + <td><tt>--gen-uvcoords</tt></td> + <td>Replace abstract mapping descriptions, such as 'spherical' or 'cylindrical' with proper UV channels</td> + </tr> + <tr> + <td><tt>-fixn</tt></td> + <td><tt>--fix-normals</tt></td> + <td>Run a heuristic algorithm to detect meshes with wrong face winding order/normals. </td> + </tr> + <tr> + <td><tt>-tri</tt></td> + <td><tt>--triangulate</tt></td> + <td>Triangulate poylgons with 4 and more points. Lines, points and triangles are not affected. </td> + </tr> + <tr> + <td><tt>-fi</tt></td> + <td><tt>--find-instances</tt></td> + <td>Search the data structure for instanced meshes and replace them by references. This can + reduce vertex/face counts but the postprocessing-step takes some time.</td> + </tr> + <tr> + <td><tt>-og</tt></td> + <td><tt>--optimize-graph</tt></td> + <td>Simplify and optimize the scenegraph. Use it with care, all hierarchy information could be lost. + Animations remain untouched. </td> + </tr> + <tr> + <td><tt>-om</tt></td> + <td><tt>--optimize-meshes</tt></td> + <td>Optimize mesh usage. Meshes are merged, if possible. Very effective in combination with <tt>--optimize-graph</tt></td> + </tr> + <tr> + <td><tt>-tuv</tt></td> + <td><tt>--transform-uv-coords</tt></td> + <td>Will transform uv-coordinates if possible.</td> + </tr> + <tr> + <td><tt>-fid</tt></td> + <td><tt>--find-invalid-data</tt></td> + <td>Will look for invalid data in the imported model structure.</td> + </tr> + <tr> + <td><tt>-db</tt></td> + <td><tt>--debone</tt></td> + <td>Removes nearly losslessly or according to a configured threshold bones from the model.</td> + </tr> + <tr> + <td><tt>-sbc</tt></td> + <td><tt>--split-by-bone-count</tt></td> + <td>Split meshes with too many bones. Necessary for our (limited) hardware skinning shader.</td> + </tr> +</table> + +For convenience some default postprocessing configurations are provided. +The corresponding command line parameter is <tt>-c<name></tt> (or <tt>--config=<name></tt>). + +<table border="1"> + + <tr> + <th>Name</th> + <th>Description</th> + <th>List of steps executed</th> + </tr> + <tr> + <td>fast</td> + <td>Fast post processing config, performs some essential optimizations and computes tangents</td> + <td><tt>-cts, -gn, -jiv, -tri, -guv, -sbpt</tt></td> + </tr> + <tr> + <td>default</td> + <td>Balanced post processing config; performs most optimizations</td> + <td><tt>-cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv</tt></td> + </tr> + <tr> + <td>full</td> + <td>Full post processing. May take a while but results in best output quality for most purposes</td> + <td><tt>-cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv, -fi, -vds -om</tt></td> + </tr> + </table> + + The <tt>-tuv, -ptv, -og</tt> flags always need to be enabled manually. + +There are also some common flags to customize Assimp's logging behaviour: + +<table border="1"> + + <tr> + <th>Name</th> + <th>Description</th> + </tr> + <tr> + <td><tt>-l</tt> or <tt>--show-log</tt></td> + <td>Show log file on console window (stderr)</td> + </tr> + <tr> + <td><tt>-lo<file></tt> or <tt>--log-out=<file></tt></td> + <td>Streams the log to <file></td> + </tr> + <tr> + <td><tt>-v</tt> or <tt>--verbose</tt></td> + <td>Enables verbose logging. Debug messages will be produced too. This might + decrease loading performance and result in *very* long logs ... use with caution if you experience strange issues.</td> + </tr> + </table> + */ |