v4games
/
assimp
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Some documentation fixes. 

git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@449 67173fc5-114c-0410-ac8e-9d2fd5bffc1f
pull/1/head
aramis_acg 2009-07-20 18:50:51 +00:00
parent d7f7e40adb
commit 8b3b63a5b3
6 changed files with 54 additions and 2539 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/AssimpCmdDoc_Html/AssimpCmdDoc.chm
View File

Binary file not shown.

BIN
doc/AssimpDoc_Html/AssimpDoc.chm
View File

Binary file not shown.

1244
doc/Doxyfile
View File

File diff suppressed because it is too large Load Diff

1246
doc/Doxyfile_Cmd
View File

File diff suppressed because it is too large Load Diff

69
doc/dox.h
View File

@ -251,8 +251,8 @@ worth a try if the library is too slow for you.
@section access_cpp Access by C++ class interface @section access_cpp Access by C++ class interface
The ASSIMP library can be accessed by both a class or flat function interface. The C++ class The ASSIMP library can be accessed by both a class or flat function interface. The C++ class
interface is the preferred way of interaction: you create an instance of class ASSIMP::Importer, interface is the preferred way of interaction: you create an instance of class Assimp::Importer,
maybe adjust some settings of it and then call ASSIMP::Importer::ReadFile(). The class will maybe adjust some settings of it and then call Assimp::Importer::ReadFile(). The class will
read the files and process its data, handing back the imported data as a pointer to an aiScene read the files and process its data, handing back the imported data as a pointer to an aiScene
to you. You can now extract the data you need from the file. The importer manages all the resources to you. You can now extract the data you need from the file. The importer manages all the resources
for itsself. If the importer is destroyed, all the data that was created/read by it will be for itsself. If the importer is destroyed, all the data that was created/read by it will be
@ -262,14 +262,13 @@ results and then simply let it go out of scope.
C++ example: C++ example:
@code @code
#include <assimp.hpp> // C++ importer interface #include <assimp.hpp> // C++ importer interface
#include <aiScene.h> // Outptu data structure #include <aiScene.h> // Output data structure
#include <aiPostProcess.h> // Post processing flags #include <aiPostProcess.h> // Post processing flags
bool DoTheImportThing( const std::string& pFile) bool DoTheImportThing( const std::string& pFile)
{ {
// Create an instance of the Importer class // Create an instance of the Importer class
ASSIMP::Importer importer; Assimp::Importer importer;
// And have it read the given file with some example postprocessing // And have it read the given file with some example postprocessing
// Usually - if speed is not the most important aspect for you - you'll // Usually - if speed is not the most important aspect for you - you'll
@ -301,7 +300,7 @@ imported data are listed at #aiPostProcessSteps. See the @link pp Post proccessi
Note that the aiScene data structure returned is declared 'const'. Yes, you can get rid of Note that the aiScene data structure returned is declared 'const'. Yes, you can get rid of
these 5 letters with a simple cast. Yes, you may do that. No, it's not recommended (and it's these 5 letters with a simple cast. Yes, you may do that. No, it's not recommended (and it's
suicide in DLL builds ...). suicide in DLL builds if you try to use new or delete on any of the arrays in the scene).
@section access_c Access by plain-c function interface @section access_c Access by plain-c function interface
@ -345,7 +344,7 @@ bool DoTheImportThing( const char* pFile)
} }
@endcode @endcode
@section custom_io Using custom IO logic @section custom_io Using custom IO logic with the C++ class interface
The ASSIMP library needs to access files internally. This of course applies to the file you want The ASSIMP library needs to access files internally. This of course applies to the file you want
to read, but also to additional files in the same folder for certain file formats. By default, to read, but also to additional files in the same folder for certain file formats. By default,
@ -387,7 +386,7 @@ class MyIOSystem : public ASSIMP::IOSystem
.. ..
} }
// Get the path delimiter character we'd like to get // Get the path delimiter character we'd like to see
char GetOsSeparator() const { char GetOsSeparator() const {
return '/'; return '/';
} }
@ -402,12 +401,12 @@ class MyIOSystem : public ASSIMP::IOSystem
@endcode @endcode
Now that your IO system is implemented, supply an instance of it to the Importer object by calling Now that your IO system is implemented, supply an instance of it to the Importer object by calling
ASSIMP::Importer::SetIOHandler(). Assimp::Importer::SetIOHandler().
@code @code
void DoTheImportThing( const std::string& pFile) void DoTheImportThing( const std::string& pFile)
{ {
ASSIMP::Importer importer; Assimp::Importer importer;
// put my custom IO handling in place // put my custom IO handling in place
importer.SetIOHandler( new MyIOSystem()); importer.SetIOHandler( new MyIOSystem());
@ -419,7 +418,14 @@ void DoTheImportThing( const std::string& pFile)
@section custom_io_c Using custom IO logic with the plain-c function interface @section custom_io_c Using custom IO logic with the plain-c function interface
// TODO The C interface also provides a way to override the file system. Control is not as fine-grained as for C++ although
surely enough for almost any purpose. The process is simple:
<ul>
<li> Include aiFileIO.h
<li> Fill an aiFileIO structure with custom file system callbacks (they're self-explanatory as they work similar to the CRT's fXXX functions)
<li> .. and pass it as last parameter to #aiImportFileEx
</ul>
@section threadsafety Thread-safety and internal multi-threading @section threadsafety Thread-safety and internal multi-threading
@ -432,12 +438,13 @@ following prerequisites are fulfilled:
load as many models as you want).</li> load as many models as you want).</li>
<li> The C-API is threadsafe as long as AI_C_THREADSAFE is defined. That's the default. </li> <li> The C-API is threadsafe as long as AI_C_THREADSAFE is defined. That's the default. </li>
<li> When supplying custom IO logic, make sure your underyling implementation is thead-safe.</li> <li> When supplying custom IO logic, make sure your underyling implementation is thead-safe.</li>
<li> Custom log streams or logger replacements have to be thread-safe, too.</li>
</ul> </ul>
See the @link assimp_st Single-threaded build section @endlink to learn how to build a lightweight variant See the @link assimp_st Single-threaded build section @endlink to learn how to build a lightweight variant
of ASSIMP which is not thread-safe and does not utilize multiple threads for loading. of ASSIMP which is not thread-safe and does not utilize multiple threads for loading.
@section logging Logging in the AssetImporter @section logging Logging
The ASSIMP library provides an easy mechanism to log messages. For instance if you want to check the state of your The ASSIMP library provides an easy mechanism to log messages. For instance if you want to check the state of your
import and you just want to see, after which preprocessing step the import-process was aborted you can take a look import and you just want to see, after which preprocessing step the import-process was aborted you can take a look
@ -446,15 +453,16 @@ Per default the ASSIMP-library provides a default log implementation, where you
by calling it as a singleton with the requested logging-type. To see how this works take a look to this: by calling it as a singleton with the requested logging-type. To see how this works take a look to this:
@code @code
using namespace Assimp;
// Create a logger instance // Create a logger instance
ASSIMP::DefaultLogger::create("",ASSIMP::Logger::VERBOSE); DefaultLogger::create("",Logger::VERBOSE);
// Now I am ready for logging my stuff // Now I am ready for logging my stuff
ASSIMP::DefaultLogger::get()->info("this is my info-call"); DefaultLogger::get()->info("this is my info-call");
// Kill it after the work is done // Kill it after the work is done
ASSIMP::DefaultLogger::kill(); DefaultLogger::kill();
@endcode @endcode
At first you have to create the default-logger-instance (create). Now you are ready to rock and can log a At first you have to create the default-logger-instance (create). Now you are ready to rock and can log a
@ -490,15 +498,11 @@ public:
} }
}; };
// Attaching it to the default logger instance: // Select the kinds of messages you want to receive on this log stream
unsigned int severity = 0; const unsigned int severity = Logger::DEBUGGING|Logger::INFO|Logger::ERR|Logger::WARN;
severity |= Logger::DEBUGGING;
severity |= Logger::INFO;
severity |= Logger::WARN;
severity |= Logger::ERR;
// Attaching it to the default logger // Attaching it to the default logger
ASSIMP::DefaultLogger::get()->attachStream( new myStream(), severity ); Assimp::DefaultLogger::get()->attachStream( new myStream(), severity );
@endcode @endcode
@ -514,25 +518,25 @@ unsigned int severity = 0;
severity |= Logger::DEBUGGING; severity |= Logger::DEBUGGING;
// Detach debug messages from you self defined stream // Detach debug messages from you self defined stream
ASSIMP::DefaultLogger::get()->attachStream( new myStream(), severity ); Assimp::DefaultLogger::get()->attachStream( new myStream(), severity );
@endcode @endcode
If you want to implement your own logger just build a derivate from the abstract base class If you want to implement your own logger just derive from the abstract base class
Logger and overwrite the methods debug, info, warn and error. #Logger and overwrite the methods debug, info, warn and error.
If you want to see the debug-messages in a debug-configured build, the Logger-interface If you want to see the debug-messages in a debug-configured build, the Logger-interface
provides a logging-severity. You can set it calling the following method: provides a logging-severity. You can set it calling the following method:
@code @code
Logger::setLogSeverity( LogSeverity log_severity ); Assimp::DefaultLogger::get()->setLogSeverity( LogSeverity log_severity );
@endcode @endcode
The normal logging severity supports just the basic stuff like, info, warnings and errors. The normal logging severity supports just the basic stuff like, info, warnings and errors.
In the verbose level debug messages will be logged, too. In the verbose level very fine-grained debug messages will be logged, too. Note that this
kind kind of logging might decrease import performance.
*/ */
/** /**
@ -744,14 +748,14 @@ both Direct3D and OpenGL (swizzling the order of the color components might be n
RGBA8888 has been chosen because it is well-known, easy to use and natively RGBA8888 has been chosen because it is well-known, easy to use and natively
supported by nearly all graphics APIs. supported by nearly all graphics APIs.
<br> <br>
<b>2)</b> This is the case for aiTexture::mHeight == 0. The texture is stored in a <b>2)</b> This applies if aiTexture::mHeight == 0 is fullfilled. Then, texture is stored in a
"compressed" format such as DDS or PNG. The term "compressed" does not mean that the "compressed" format such as DDS or PNG. The term "compressed" does not mean that the
texture data must actually be compressed, however the texture was stored in the texture data must actually be compressed, however the texture was found in the
model file as if it was stored in a separate file on the harddisk. Appropriate model file as if it was stored in a separate file on the harddisk. Appropriate
decoders (such as libjpeg, libpng, D3DX, DevIL) are required to load theses textures. decoders (such as libjpeg, libpng, D3DX, DevIL) are required to load theses textures.
aiTexture::mWidth specifies the size of the texture data in bytes, aiTexture::pcData is aiTexture::mWidth specifies the size of the texture data in bytes, aiTexture::pcData is
a pointer to the raw image data and aiTexture::achFormatHint is either zeroed or a pointer to the raw image data and aiTexture::achFormatHint is either zeroed or
containing the file extension of the format of the embedded texture. This is only contains the most common file extension of the embedded texture's format. This value is only
set if ASSIMP is able to determine the file format. set if ASSIMP is able to determine the file format.
*/ */
@ -759,8 +763,7 @@ set if ASSIMP is able to determine the file format.
@page materials Material System @page materials Material System
@section General Overview @section General Overview
All materials are stored in an array of aiMaterial inside the aiScene.
Warn, WIP. All materials are stored in an array of aiMaterial inside the aiScene.
Each aiMesh refers to one Each aiMesh refers to one
material by its index in the array. Due to the vastly diverging definitions and usages of material material by its index in the array. Due to the vastly diverging definitions and usages of material

34
doc/dox_cmd.h
View File

@ -98,7 +98,7 @@ See the @link wildcard wildcards page @endlink for more information.
<tt> <tt>
out<br></tt><br> out<br></tt><br>
Optional. Relative or absolute path to write the output dump to. If it is ommitted, Optional. Relative or absolute path to write the output dump to. If it is ommitted,
the dump is written to <tt><model>-dump.txt</tt> the dump is written to <tt>&lt;model&gt;-dump.txt</tt>
</p> </p>
<p> <p>
@ -109,12 +109,12 @@ The long form of this parameter is <tt>--binary</tt>.
</p> </p>
<p> <p>
<tt>-s<n><br> <tt>-s&lt;n&gt;<br>
</tt><br> </tt><br>
Optional. If this switch is specified, the dumb is shortened to include only Optional. If this switch is specified, the dumb is shortened to include only
min/max values for all vertex components and animation channels. The resulting 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 file is much smaller, but the original model can't be reconstructed from it. This is
used by Assimp's regression test suite,comapring those minidumps provides used by Assimp's regression test suite, comparing those minidumps provides
a fast way to verify whether a loader works correctly or not. a fast way to verify whether a loader works correctly or not.
The long form of this parameter is <tt>--short</tt>. The long form of this parameter is <tt>--short</tt>.
</p> </p>
@ -176,8 +176,8 @@ See the @link wildcard wildcards page @endlink for more information.
out<br></tt><br> out<br></tt><br>
Optional. Relative or absolute path to write the output images to. If the file name is Optional. Relative or absolute path to write the output images to. If the file name is
ommitted the output images are named <tt><model-filename></tt><br> ommitted 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 The suffix <tt>_img&lt;n&gt;</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> (where <tt>&lt;n&gt;</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 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, formats are BMP and TGA. If the file format can't be determined,
@ -188,34 +188,34 @@ written in their native file format (e.g. jpg).
</p> </p>
<p> <p>
<tt>-t<n><br> <tt>-t&lt;n&gt;<br>
</tt><br> </tt><br>
Optional. Specifies the (zero-based) index of the embedded texture to be extracted from 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 model. If this option is *not* specified all textures found are exported.
The long form of this parameter is <tt>--texture=<n></tt>. The long form of this parameter is <tt>--texture=&lt;n&gt;</tt>.
</p> </p>
<p> <p>
<tt>-t<n><br> <tt>-ba&lt;n&gt;<br>
</tt><br> </tt><br>
Optional. Specifies whether output BMPs contain an alpha channel or not. Optional. Specifies whether output BMPs contain an alpha channel or not.
The long form of this parameter is <tt>--bmp-with-alpha=<n></tt>. The long form of this parameter is <tt>--bmp-with-alpha=&lt;n&gt;</tt>.
</p> </p>
<p> <p>
<tt>-f<n><br> <tt>-f&lt;n&gt;<br>
</tt><br> </tt><br>
Optional. Specifies the output file format. Supported Optional. Specifies the output file format. Supported
formats are BMP and TGA. The default value is BMP (if a full output filename is 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). specified, the output file format is taken from its extension, not from here).
The long form of this parameter is <tt>--format=<n></tt>. The long form of this parameter is <tt>--format=&lt;n&gt;</tt>.
</p> </p>
<p> <p>
<tt>-s<n><br> <tt>-s&lt;n&gt;<br>
</tt><br> </tt><br>
Optional. Prevents the tool from adding the <tt>_img<n></tt> suffix to all filenames. This option Optional. Prevents the tool from adding the <tt>_img&lt;n&gt;</tt> suffix to all filenames. This option
must be specified together with -t to ensure that just one image is written. must be specified together with -t to ensure that just one image is written.
The long form of this parameter is <tt>--nosuffix</tt>. The long form of this parameter is <tt>--nosuffix</tt>.
</p> </p>
@ -306,7 +306,7 @@ more information can be found in the <tt>aiPostProcess.h</tt> header.
</tr> </tr>
<tr> <tr>
<td><tt>-slm</tt></td> <td><tt>-slm</tt></td>
<td>--split-large-meshes</tt></td> <td><tt>--split-large-meshes</tt></td>
<td>Split large meshes over a specific treshold in smaller sub meshes. The default vertex & face limit is 1000000</td> <td>Split large meshes over a specific treshold in smaller sub meshes. The default vertex & face limit is 1000000</td>
</tr> </tr>
<tr> <tr>
@ -389,7 +389,7 @@ more information can be found in the <tt>aiPostProcess.h</tt> header.
</table> </table>
For convenience some default postprocessing configurations are provided. For convenience some default postprocessing configurations are provided.
The corresponding command line parameter is <tt>-c<name></tt> (or <tt>--config=<name></tt>). The corresponding command line parameter is <tt>-c&lt;name&gt;</tt> (or <tt>--config=&lt;name&gt;</tt>).
<table border="1"> <table border="1">
@ -430,8 +430,8 @@ There are also some common flags to customize Assimp's logging behaviour:
<td>Show log file on console window (stderr)</td> <td>Show log file on console window (stderr)</td>
</tr> </tr>
<tr> <tr>
<td><tt>-lo<file></tt> or <tt>--log-out=<file></tt></td> <td><tt>-lo&lt;file&gt;</tt> or <tt>--log-out=&lt;file&gt;</tt></td>
<td>Streams the log to <file></td> <td>Streams the log to &lt;file&gt;</td>
</tr> </tr>
<tr> <tr>
<td><tt>-v</tt> or <tt>--verbose</tt></td> <td><tt>-v</tt> or <tt>--verbose</tt></td>