From 058f98a63658dc1a2579826ba167fd61bed1e21f Mon Sep 17 00:00:00 2001 From: sanine Date: Fri, 4 Mar 2022 10:47:15 -0600 Subject: add assimp submodule --- src/mesh/assimp-master/doc/dox_cmd.h | 565 +++++++++++++++++++++++++++++++++++ 1 file changed, 565 insertions(+) create mode 100644 src/mesh/assimp-master/doc/dox_cmd.h (limited to 'src/mesh/assimp-master/doc/dox_cmd.h') 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 + + + +@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. +

+NOTE: 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
@link version version @endlinkRetrieve the current version of assimp
@link help help @endlinkGet a list of all commands (yes, it's this list ...)
@link dump dump @endlinkGenerate a human-readable text dump of a model
@link extract extract @endlinkExtract an embedded texture image
@link iinfo info @endlinkLoad a model and print basic statistics
@link cmpdump cmpdump @endlinkRegression checking tool
+ +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 -r switch is specified. Sample output (assimp info ./test/models/3DS/mar_rifle.3ds): + +@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 + +

Syntax:

+ +@code +assimp info file [-r] +@endcode + + +

Parameters:

+ +

+ +file

+Required. Input file. +

+

+ +-r
+Optional. Don't perform any postprocessing. The long form of this parameter is --raw. +

+ +*/ +//---------------------------------------------------------------------------------------------- +// ASSIMP CMPDUMP + +/** +@page cmpdump 'cmpdump'-Command + +Used for Assimp's internal regression testing. Compare two mini dumps (produced using assimp dump .. -b -s) 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. + +

Syntax:

+ +@code +assimp cmpdmp actual expected +@endcode + + +

Parameters:

+ +

+ +actual

+Required. Mini dump now. +

+

+ +expected

+Required. Archived dump from some point in the past. +

+ +*/ + + +//---------------------------------------------------------------------------------------------- +// 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. + +

Syntax:

+ +@code +assimp dump [] [-b] [-s] [common parameters] +@endcode + + +

Parameters:

+ +

+ +model

+Required. Relative or absolute path to the input model. +

+

+ +out

+Optional. Relative or absolute path to write the output dump to. If it is omitted, +the dump is written to <model>-dump.txt +

+ +

+-b
+
+Optional. If this switch is specified, the dump is written in binary format. +The long form of this parameter is --binary. +

+ +

+-s<n>
+
+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 --short. +

+ +

+ +common parameters

+Optional. Import configuration & postprocessing. +See the @link common common parameters page @endlink for more information. +

+ +
+ +

Sample:

+ +@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 +-dump.txt. The log is not included. + */ + +//---------------------------------------------------------------------------------------------- +// ASSIMP EXTRACT + +/** +@page extract 'extract'-Command + +Extracts one or more embedded texture images from models. + +

Syntax:

+ +@code +assimp extract [] [-t] [-f] [-ba] [-s] [common parameters] +@endcode + + +

Parameters:

+ +

+ +model

+Required. Relative or absolute path to the input model. +

+

+ +out

+Optional. Relative or absolute path to write the output images to. If the file name is +omitted the output images are named
+The suffix _img<n> is appended to the file name if the -s switch is not specified +(where <n> is the zero-based index of the texture in the model file).
+ +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. +
+Format settings are ignored for compressed embedded textures. They're always +written in their native file format (e.g. jpg). +

+ +

+-t<n>
+
+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 --texture=<n>. +

+ +

+-ba<n>
+
+Optional. Specifies whether output BMPs contain an alpha channel or not. +The long form of this parameter is --bmp-with-alpha=<n>. +

+ + +

+-f<n>
+
+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 --format=<n>. +

+ +

+-s<n>
+
+Optional. Prevents the tool from adding the _img<n> 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 --nosuffix. +

+ +

+ +common parameters

+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. +

+ +
+ +

Sample:

+ +@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 test_img0.bmp. + + +@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 _img.bmp + */ + +//---------------------------------------------------------------------------------------------- +// 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.
Programmers: +more information can be found in the aiPostProcess.h header. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterLong parameterDescription
-ptv--pretransform-verticesMove 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.
-gsn--gen-smooth-normalsComputes 'smooth' per-vertex normal vectors if necessary. Mutually exclusive with -gn
-gn--gen-normalsComputes 'hard' per-face normal vectors if necessary. Mutually exclusive with -gsn
-cts--calc-tangent-spaceIf one UV channel and normal vectors are given, compute tangents and bitangents
-jiv--join-identical-verticesOptimize the index buffer. If this flag is not specified all vertices are referenced once.
-rrm--remove-redundant-materialsRemove redundant materials from the imported data.
-fd--find-degeneratesFind and process degenerates primitives.
-slm--split-large-meshesSplit large meshes over a specific threshold in smaller sub meshes. The default vertex & face limit is 1000000
-lbw--limit-bone-weightsLimit the number of bones influencing a single vertex. The default limit is 4.
-vds--validate-data-structurePerforms a full validation of the imported data structure. Recommended to avoid crashes if + an import plugin produces rubbish
-icl--improve-cache-localityImprove the cache locality of the vertex buffer by reordering the index buffer + to achieve a lower ACMR (average post-transform vertex cache miss ratio)
-sbpt--sort-by-ptypeSplits meshes which consist of more than one kind of primitives (e.g. lines and triangles mixed up) + in 'clean' submeshes.
-lh--convert-to-lhConverts the imported data to left-handed coordinate space
-fuv--flip-uvFlip UV coordinates from upper-left origin to lower-left origin
-fwo--flip-winding-orderFlip face winding order from CCW to CW
-ett--evaluate-texture-transformEvaluate per-texture UV transformations (e.g scaling, offset) and build pretransformed UV channels
-guv--gen-uvcoordsReplace abstract mapping descriptions, such as 'spherical' or 'cylindrical' with proper UV channels
-fixn--fix-normalsRun a heuristic algorithm to detect meshes with wrong face winding order/normals.
-tri--triangulateTriangulate poylgons with 4 and more points. Lines, points and triangles are not affected.
-fi--find-instancesSearch the data structure for instanced meshes and replace them by references. This can + reduce vertex/face counts but the postprocessing-step takes some time.
-og--optimize-graphSimplify and optimize the scenegraph. Use it with care, all hierarchy information could be lost. + Animations remain untouched.
-om--optimize-meshesOptimize mesh usage. Meshes are merged, if possible. Very effective in combination with --optimize-graph
-tuv--transform-uv-coordsWill transform uv-coordinates if possible.
-fid--find-invalid-dataWill look for invalid data in the imported model structure.
-db--deboneRemoves nearly losslessly or according to a configured threshold bones from the model.
-sbc--split-by-bone-countSplit meshes with too many bones. Necessary for our (limited) hardware skinning shader.
+ +For convenience some default postprocessing configurations are provided. +The corresponding command line parameter is -c<name> (or --config=<name>). + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionList of steps executed
fastFast post processing config, performs some essential optimizations and computes tangents-cts, -gn, -jiv, -tri, -guv, -sbpt
defaultBalanced post processing config; performs most optimizations-cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv
fullFull post processing. May take a while but results in best output quality for most purposes-cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv, -fi, -vds -om
+ + The -tuv, -ptv, -og flags always need to be enabled manually. + +There are also some common flags to customize Assimp's logging behaviour: + + + + + + + + + + + + + + + + + + + +
NameDescription
-l or --show-logShow log file on console window (stderr)
-lo<file> or --log-out=<file>Streams the log to <file>
-v or --verboseEnables 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.
+ */ -- cgit v1.2.1