nuclear@14: //----------------------------------------------------------------------------- nuclear@14: // Product: OpenCTM nuclear@14: // File: openctm.h nuclear@14: // Description: OpenCTM API definition. nuclear@14: //----------------------------------------------------------------------------- nuclear@14: // Copyright (c) 2009-2010 Marcus Geelnard nuclear@14: // nuclear@14: // This software is provided 'as-is', without any express or implied nuclear@14: // warranty. In no event will the authors be held liable for any damages nuclear@14: // arising from the use of this software. nuclear@14: // nuclear@14: // Permission is granted to anyone to use this software for any purpose, nuclear@14: // including commercial applications, and to alter it and redistribute it nuclear@14: // freely, subject to the following restrictions: nuclear@14: // nuclear@14: // 1. The origin of this software must not be misrepresented; you must not nuclear@14: // claim that you wrote the original software. If you use this software nuclear@14: // in a product, an acknowledgment in the product documentation would be nuclear@14: // appreciated but is not required. nuclear@14: // nuclear@14: // 2. Altered source versions must be plainly marked as such, and must not nuclear@14: // be misrepresented as being the original software. nuclear@14: // nuclear@14: // 3. This notice may not be removed or altered from any source nuclear@14: // distribution. nuclear@14: //----------------------------------------------------------------------------- nuclear@14: nuclear@14: #ifndef __OPENCTM_H_ nuclear@14: #define __OPENCTM_H_ nuclear@14: nuclear@14: /*! @mainpage OpenCTM API Reference nuclear@14: * nuclear@14: * @section intro_sec Introduction nuclear@14: * nuclear@14: * OpenCTM is an open file format for storing compressed triangle meshes. nuclear@14: * In order to easily read and write OpenCTM files (usually suffixed .ctm) an nuclear@14: * API (Application Program Interface) is provided that can easily be used from nuclear@14: * most modern programming languages. nuclear@14: * nuclear@14: * The OpenCTM functionality itself is written in highly portable standard C nuclear@14: * (C99). nuclear@14: * nuclear@14: * @section usage_sec Usage nuclear@14: * nuclear@14: * For information about how to use the OpenCTM API, see openctm.h. nuclear@14: * nuclear@14: * For information about the C++ wrapper classes, see CTMimporter and nuclear@14: * CTMexporter. nuclear@14: * nuclear@14: * @section example_sec Example usage nuclear@14: * nuclear@14: * @subsection example_load_sec Loading a CTM file nuclear@14: * nuclear@14: * Here is a simple example of loading a CTM file: nuclear@14: * nuclear@14: * @code nuclear@14: * CTMcontext context; nuclear@14: * CTMuint vertCount, triCount, * indices; nuclear@14: * CTMfloat * vertices; nuclear@14: * nuclear@14: * // Create a new context nuclear@14: * context = ctmNewContext(CTM_IMPORT); nuclear@14: * nuclear@14: * // Load the OpenCTM file nuclear@14: * ctmLoad(context, "mymesh.ctm"); nuclear@14: * if(ctmGetError(context) == CTM_NONE) nuclear@14: * { nuclear@14: * // Access the mesh data nuclear@14: * vertCount = ctmGetInteger(context, CTM_VERTEX_COUNT); nuclear@14: * vertices = ctmGetFloatArray(context, CTM_VERTICES); nuclear@14: * triCount = ctmGetInteger(context, CTM_TRIANGLE_COUNT); nuclear@14: * indices = ctmGetIntegerArray(context, CTM_INDICES); nuclear@14: * nuclear@14: * // Deal with the mesh (e.g. transcode it to our internal representation) nuclear@14: * // ... nuclear@14: * } nuclear@14: * nuclear@14: * // Free the context nuclear@14: * ctmFreeContext(context); nuclear@14: * @endcode nuclear@14: * nuclear@14: * @subsection example_create_sec Creating a CTM file nuclear@14: * nuclear@14: * Here is a simple example of creating a CTM file: nuclear@14: * nuclear@14: * @code nuclear@14: * CTMcontext context; nuclear@14: * CTMuint vertCount, triCount, * indices; nuclear@14: * CTMfloat * vertices; nuclear@14: * nuclear@14: * // Create our mesh in memory nuclear@14: * vertCount = 100; nuclear@14: * triCount = 120; nuclear@14: * vertices = (CTMfloat *) malloc(3 * sizeof(CTMfloat) * vertCount); nuclear@14: * indices = (CTMuint *) malloc(3 * sizeof(CTMuint) * triCount); nuclear@14: * // ... nuclear@14: * nuclear@14: * // Create a new context nuclear@14: * context = ctmNewContext(CTM_EXPORT); nuclear@14: * nuclear@14: * // Define our mesh representation to OpenCTM (store references to it in nuclear@14: * // the context) nuclear@14: * ctmDefineMesh(context, vertices, vertCount, indices, triCount, NULL); nuclear@14: * nuclear@14: * // Save the OpenCTM file nuclear@14: * ctmSave(context, "mymesh.ctm"); nuclear@14: * nuclear@14: * // Free the context nuclear@14: * ctmFreeContext(context); nuclear@14: * nuclear@14: * // Free our mesh nuclear@14: * free(indices); nuclear@14: * free(vertices); nuclear@14: * @endcode nuclear@14: */ nuclear@14: nuclear@14: #ifdef __cplusplus nuclear@14: extern "C" { nuclear@14: #endif nuclear@14: nuclear@14: nuclear@14: // Declare calling conventions etc. nuclear@14: #if defined(WIN32) || defined(_WIN32) nuclear@14: // Windows nuclear@14: #if defined(OPENCTM_STATIC) nuclear@14: #define CTMEXPORT nuclear@14: #else nuclear@14: #if defined(OPENCTM_BUILD) nuclear@14: #define CTMEXPORT __declspec(dllexport) nuclear@14: #else nuclear@14: #define CTMEXPORT __declspec(dllimport) nuclear@14: #endif nuclear@14: #endif nuclear@14: #if defined(__MINGW32__) nuclear@14: #define CTMCALL __attribute__ ((__stdcall__)) nuclear@14: #elif (defined(_M_MRX000) || defined(_M_IX86) || defined(_M_ALPHA) || defined(_M_PPC)) && !defined(MIDL_PASS) nuclear@14: #define CTMCALL __stdcall nuclear@14: #else nuclear@14: #define CTMCALL nuclear@14: #endif nuclear@14: #else nuclear@14: // Unix nuclear@14: #if !defined(OPENCTM_STATIC) && !defined(OPENCTM_BUILD) nuclear@14: #define CTMEXPORT extern nuclear@14: #else nuclear@14: #if defined(OPENCTM_BUILD) && defined(__GNUC__) && (__GNUC__ >= 4) nuclear@14: #define CTMEXPORT __attribute__ ((visibility("default"))) nuclear@14: #else nuclear@14: #define CTMEXPORT nuclear@14: #endif nuclear@14: #endif nuclear@14: #define CTMCALL nuclear@14: #endif nuclear@14: nuclear@14: nuclear@14: // Get system specific type definitions for sized integers. We use the C99 nuclear@14: // standard stdint.h for this. nuclear@14: #ifdef _MSC_VER nuclear@14: // MS Visual Studio does not support C99 nuclear@14: typedef int int32_t; nuclear@14: typedef unsigned int uint32_t; nuclear@14: #else nuclear@14: #include nuclear@14: #endif nuclear@14: nuclear@14: nuclear@14: /// OpenCTM API version (1.0). nuclear@14: #define CTM_API_VERSION 0x00000100 nuclear@14: nuclear@14: /// Boolean TRUE. nuclear@14: #define CTM_TRUE 1 nuclear@14: nuclear@14: /// Boolean FALSE. nuclear@14: #define CTM_FALSE 0 nuclear@14: nuclear@14: /// Single precision floating point type (IEEE 754 32 bits wide). nuclear@14: typedef float CTMfloat; nuclear@14: nuclear@14: /// Signed integer (32 bits wide). nuclear@14: typedef int32_t CTMint; nuclear@14: nuclear@14: /// Unsigned integer (32 bits wide). nuclear@14: typedef uint32_t CTMuint; nuclear@14: nuclear@14: /// OpenCTM context handle. nuclear@14: typedef void * CTMcontext; nuclear@14: nuclear@14: /// OpenCTM specific enumerators. nuclear@14: /// @note For the information query functions, it is an error to query a value nuclear@14: /// of the wrong type (e.g. to query a string value with the nuclear@14: /// ctmGetInteger() function). nuclear@14: typedef enum { nuclear@14: // Error codes (see ctmGetError()) nuclear@14: CTM_NONE = 0x0000, ///< No error has occured (everything is OK). nuclear@14: /// Also used as an error return value for nuclear@14: /// functions that should return a CTMenum nuclear@14: /// value. nuclear@14: CTM_INVALID_CONTEXT = 0x0001, ///< The OpenCTM context was invalid (e.g. NULL). nuclear@14: CTM_INVALID_ARGUMENT = 0x0002, ///< A function argument was invalid. nuclear@14: CTM_INVALID_OPERATION = 0x0003, ///< The operation is not allowed. nuclear@14: CTM_INVALID_MESH = 0x0004, ///< The mesh was invalid (e.g. no vertices). nuclear@14: CTM_OUT_OF_MEMORY = 0x0005, ///< Not enough memory to proceed. nuclear@14: CTM_FILE_ERROR = 0x0006, ///< File I/O error. nuclear@14: CTM_BAD_FORMAT = 0x0007, ///< File format error (e.g. unrecognized format or corrupted file). nuclear@14: CTM_LZMA_ERROR = 0x0008, ///< An error occured within the LZMA library. nuclear@14: CTM_INTERNAL_ERROR = 0x0009, ///< An internal error occured (indicates a bug). nuclear@14: CTM_UNSUPPORTED_FORMAT_VERSION = 0x000A, ///< Unsupported file format version. nuclear@14: nuclear@14: // OpenCTM context modes nuclear@14: CTM_IMPORT = 0x0101, ///< The OpenCTM context will be used for importing data. nuclear@14: CTM_EXPORT = 0x0102, ///< The OpenCTM context will be used for exporting data. nuclear@14: nuclear@14: // Compression methods nuclear@14: CTM_METHOD_RAW = 0x0201, ///< Just store the raw data. nuclear@14: CTM_METHOD_MG1 = 0x0202, ///< Lossless compression (floating point). nuclear@14: CTM_METHOD_MG2 = 0x0203, ///< Lossless compression (fixed point). nuclear@14: nuclear@14: // Context queries nuclear@14: CTM_VERTEX_COUNT = 0x0301, ///< Number of vertices in the mesh (integer). nuclear@14: CTM_TRIANGLE_COUNT = 0x0302, ///< Number of triangles in the mesh (integer). nuclear@14: CTM_HAS_NORMALS = 0x0303, ///< CTM_TRUE if the mesh has normals (integer). nuclear@14: CTM_UV_MAP_COUNT = 0x0304, ///< Number of UV coordinate sets (integer). nuclear@14: CTM_ATTRIB_MAP_COUNT = 0x0305, ///< Number of custom attribute sets (integer). nuclear@14: CTM_VERTEX_PRECISION = 0x0306, ///< Vertex precision - for MG2 (float). nuclear@14: CTM_NORMAL_PRECISION = 0x0307, ///< Normal precision - for MG2 (float). nuclear@14: CTM_COMPRESSION_METHOD = 0x0308, ///< Compression method (integer). nuclear@14: CTM_FILE_COMMENT = 0x0309, ///< File comment (string). nuclear@14: nuclear@14: // UV/attribute map queries nuclear@14: CTM_NAME = 0x0501, ///< Unique name (UV/attrib map string). nuclear@14: CTM_FILE_NAME = 0x0502, ///< File name reference (UV map string). nuclear@14: CTM_PRECISION = 0x0503, ///< Value precision (UV/attrib map float). nuclear@14: nuclear@14: // Array queries nuclear@14: CTM_INDICES = 0x0601, ///< Triangle indices (integer array). nuclear@14: CTM_VERTICES = 0x0602, ///< Vertex point coordinates (float array). nuclear@14: CTM_NORMALS = 0x0603, ///< Per vertex normals (float array). nuclear@14: CTM_UV_MAP_1 = 0x0700, ///< Per vertex UV map 1 (float array). nuclear@14: CTM_UV_MAP_2 = 0x0701, ///< Per vertex UV map 2 (float array). nuclear@14: CTM_UV_MAP_3 = 0x0702, ///< Per vertex UV map 3 (float array). nuclear@14: CTM_UV_MAP_4 = 0x0703, ///< Per vertex UV map 4 (float array). nuclear@14: CTM_UV_MAP_5 = 0x0704, ///< Per vertex UV map 5 (float array). nuclear@14: CTM_UV_MAP_6 = 0x0705, ///< Per vertex UV map 6 (float array). nuclear@14: CTM_UV_MAP_7 = 0x0706, ///< Per vertex UV map 7 (float array). nuclear@14: CTM_UV_MAP_8 = 0x0707, ///< Per vertex UV map 8 (float array). nuclear@14: CTM_ATTRIB_MAP_1 = 0x0800, ///< Per vertex attribute map 1 (float array). nuclear@14: CTM_ATTRIB_MAP_2 = 0x0801, ///< Per vertex attribute map 2 (float array). nuclear@14: CTM_ATTRIB_MAP_3 = 0x0802, ///< Per vertex attribute map 3 (float array). nuclear@14: CTM_ATTRIB_MAP_4 = 0x0803, ///< Per vertex attribute map 4 (float array). nuclear@14: CTM_ATTRIB_MAP_5 = 0x0804, ///< Per vertex attribute map 5 (float array). nuclear@14: CTM_ATTRIB_MAP_6 = 0x0805, ///< Per vertex attribute map 6 (float array). nuclear@14: CTM_ATTRIB_MAP_7 = 0x0806, ///< Per vertex attribute map 7 (float array). nuclear@14: CTM_ATTRIB_MAP_8 = 0x0807 ///< Per vertex attribute map 8 (float array). nuclear@14: } CTMenum; nuclear@14: nuclear@14: /// Stream read() function pointer. nuclear@14: /// @param[in] aBuf Pointer to the memory buffer to which data should be read. nuclear@14: /// @param[in] aCount The number of bytes to read. nuclear@14: /// @param[in] aUserData The custom user data that was passed to the nuclear@14: /// ctmLoadCustom() function. nuclear@14: /// @return The number of bytes actually read (if this is less than aCount, it nuclear@14: /// indicates that an error occured or the end of file was reached nuclear@14: /// before all bytes were read). nuclear@14: typedef CTMuint (CTMCALL * CTMreadfn)(void * aBuf, CTMuint aCount, void * aUserData); nuclear@14: nuclear@14: /// Stream write() function pointer. nuclear@14: /// @param[in] aBuf Pointer to the memory buffer from which data should be written. nuclear@14: /// @param[in] aCount The number of bytes to write. nuclear@14: /// @param[in] aUserData The custom user data that was passed to the nuclear@14: /// ctmSaveCustom() function. nuclear@14: /// @return The number of bytes actually written (if this is less than aCount, it nuclear@14: /// indicates that an error occured). nuclear@14: typedef CTMuint (CTMCALL * CTMwritefn)(const void * aBuf, CTMuint aCount, void * aUserData); nuclear@14: nuclear@14: /// Create a new OpenCTM context. The context is used for all subsequent nuclear@14: /// OpenCTM function calls. Several contexts can coexist at the same time. nuclear@14: /// @param[in] aMode An OpenCTM context mode. Set this to CTM_IMPORT if the nuclear@14: /// context will be used for importing data, or set it to CTM_EXPORT nuclear@14: /// if it will be used for exporting data. nuclear@14: /// @return An OpenCTM context handle (or NULL if no context could be created). nuclear@14: CTMEXPORT CTMcontext CTMCALL ctmNewContext(CTMenum aMode); nuclear@14: nuclear@14: /// Free an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @see ctmNewContext() nuclear@14: CTMEXPORT void CTMCALL ctmFreeContext(CTMcontext aContext); nuclear@14: nuclear@14: /// Returns the latest error. Calling this function will return the last nuclear@14: /// produced error code, or CTM_NO_ERROR (zero) if no error has occured since nuclear@14: /// the last call to ctmGetError(). When this function is called, the internal nuclear@14: /// error varibale will be reset to CTM_NONE. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @return An OpenCTM error code. nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT CTMenum CTMCALL ctmGetError(CTMcontext aContext); nuclear@14: nuclear@14: /// Converts an OpenCTM error code to a zero-terminated string. nuclear@14: /// @param[in] aError An OpenCTM error code, as returned by ctmGetError(). nuclear@14: /// @return A zero terminated string that describes the error. For instance, nuclear@14: /// if \c aError is CTM_INVALID_OPERATION, then the return value will nuclear@14: /// be "CTM_INVALID_OPERATION". nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const char * CTMCALL ctmErrorString(CTMenum aError); nuclear@14: nuclear@14: /// Get information about an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aProperty Which property to return. nuclear@14: /// @return An integer value, representing the OpenCTM context property given nuclear@14: /// by \c aProperty. nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT CTMuint CTMCALL ctmGetInteger(CTMcontext aContext, CTMenum aProperty); nuclear@14: nuclear@14: /// Get information about an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aProperty Which property to return. nuclear@14: /// @return A floating point value, representing the OpenCTM context property nuclear@14: /// given by \c aProperty. nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT CTMfloat CTMCALL ctmGetFloat(CTMcontext aContext, CTMenum aProperty); nuclear@14: nuclear@14: /// Get an integer array from an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aProperty Which array to return. nuclear@14: /// @return An integer array. If the requested array does not exist, or nuclear@14: /// if \c aProperty does not indicate an integer array, the function nuclear@14: /// returns NULL. nuclear@14: /// @note The array is only valid as long as the OpenCTM context is valid, or nuclear@14: /// until the corresponding array changes within the OpenCTM context. nuclear@14: /// Trying to access an invalid array will result in undefined nuclear@14: /// behaviour. Therefor it is recommended that the array is copied to nuclear@14: /// a new variable if it is to be used other than directly after the call nuclear@14: /// to ctmGetIntegerArray(). nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const CTMuint * CTMCALL ctmGetIntegerArray(CTMcontext aContext, nuclear@14: CTMenum aProperty); nuclear@14: nuclear@14: /// Get a floating point array from an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aProperty Which array to return. nuclear@14: /// @return A floating point array. If the requested array does not exist, or nuclear@14: /// if \c aProperty does not indicate a float array, the function nuclear@14: /// returns NULL. nuclear@14: /// @note The array is only valid as long as the OpenCTM context is valid, or nuclear@14: /// until the corresponding array changes within the OpenCTM context. nuclear@14: /// Trying to access an invalid array will result in undefined nuclear@14: /// behaviour. Therefor it is recommended that the array is copied to nuclear@14: /// a new variable if it is to be used other than directly after the call nuclear@14: /// to ctmGetFloatArray(). nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const CTMfloat * CTMCALL ctmGetFloatArray(CTMcontext aContext, nuclear@14: CTMenum aProperty); nuclear@14: nuclear@14: /// Get a reference to the named UV map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aName The name of the UV map that should be returned. nuclear@14: /// @return A reference to a UV map. If the UV map was found, a value of nuclear@14: /// CTM_UV_MAP_1 or higher is returned, otherwise CTM_NONE is nuclear@14: /// returned. nuclear@14: CTMEXPORT CTMenum CTMCALL ctmGetNamedUVMap(CTMcontext aContext, nuclear@14: const char * aName); nuclear@14: nuclear@14: /// Get information about a UV map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher). nuclear@14: /// @param[in] aProperty Which UV map property to return. nuclear@14: /// @return A string value, representing the UV map property given nuclear@14: /// by \c aProperty. nuclear@14: /// @note The string is only valid as long as the UV map within the OpenCTM nuclear@14: /// context is valid. Trying to access an invalid string will result in nuclear@14: /// undefined behaviour. Therefor it is recommended that the string is nuclear@14: /// copied to a new variable if it is to be used other than directly after nuclear@14: /// the call to ctmGetUVMapString(). nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const char * CTMCALL ctmGetUVMapString(CTMcontext aContext, nuclear@14: CTMenum aUVMap, CTMenum aProperty); nuclear@14: nuclear@14: /// Get information about a UV map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher). nuclear@14: /// @param[in] aProperty Which UV map property to return. nuclear@14: /// @return A floating point value, representing the UV map property given nuclear@14: /// by \c aProperty. nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT CTMfloat CTMCALL ctmGetUVMapFloat(CTMcontext aContext, nuclear@14: CTMenum aUVMap, CTMenum aProperty); nuclear@14: nuclear@14: /// Get a reference to the named vertex attribute map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aName The name of the attribute map that should be returned. nuclear@14: /// @return A reference to an attribute map. If the attribute map was found, nuclear@14: /// a value of CTM_ATTRIB_MAP_1 or higher is returned, otherwise nuclear@14: /// CTM_NONE is returned. nuclear@14: CTMEXPORT CTMenum CTMCALL ctmGetNamedAttribMap(CTMcontext aContext, nuclear@14: const char * aName); nuclear@14: nuclear@14: /// Get information about a vertex attribute map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1 nuclear@14: /// or higher). nuclear@14: /// @param[in] aProperty Which vertex attribute map property to return. nuclear@14: /// @return A string value, representing the vertex attribute map property given nuclear@14: /// by \c aProperty. nuclear@14: /// @note The string is only valid as long as the vertex attribute map within nuclear@14: /// the OpenCTM context is valid. Trying to access an invalid string will nuclear@14: /// result in undefined behaviour. Therefor it is recommended that the nuclear@14: /// string is copied to a new variable if it is to be used other than nuclear@14: /// directly after the call to ctmGetAttribMapString(). nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const char * CTMCALL ctmGetAttribMapString(CTMcontext aContext, nuclear@14: CTMenum aAttribMap, CTMenum aProperty); nuclear@14: nuclear@14: /// Get information about a vertex attribute map. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1 nuclear@14: /// or higher). nuclear@14: /// @param[in] aProperty Which vertex attribute map property to return. nuclear@14: /// @return A floating point value, representing the vertex attribute map nuclear@14: /// property given by \c aProperty. nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT CTMfloat CTMCALL ctmGetAttribMapFloat(CTMcontext aContext, nuclear@14: CTMenum aAttribMap, CTMenum aProperty); nuclear@14: nuclear@14: /// Get information about an OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aProperty Which property to return. nuclear@14: /// @return A string value, representing the OpenCTM context property given nuclear@14: /// by \c aProperty. nuclear@14: /// @note The string is only valid as long as the OpenCTM context is valid, or nuclear@14: /// until the corresponding string changes within the OpenCTM context nuclear@14: /// (e.g. calling ctmFileComment() invalidates the CTM_FILE_COMMENT nuclear@14: /// string). Trying to access an invalid string will result in undefined nuclear@14: /// behaviour. Therefor it is recommended that the string is copied to nuclear@14: /// a new variable if it is to be used other than directly after the call nuclear@14: /// to ctmGetString(). nuclear@14: /// @see CTMenum nuclear@14: CTMEXPORT const char * CTMCALL ctmGetString(CTMcontext aContext, nuclear@14: CTMenum aProperty); nuclear@14: nuclear@14: /// Set which compression method to use for the given OpenCTM context. nuclear@14: /// The selected compression method will be used when calling the ctmSave() nuclear@14: /// function. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aMethod Which compression method to use: CTM_METHOD_RAW, nuclear@14: /// CTM_METHOD_MG1 or CTM_METHOD_MG2 (the default method is nuclear@14: /// CTM_METHOD_MG1). nuclear@14: /// @see CTM_METHOD_RAW, CTM_METHOD_MG1, CTM_METHOD_MG2 nuclear@14: CTMEXPORT void CTMCALL ctmCompressionMethod(CTMcontext aContext, nuclear@14: CTMenum aMethod); nuclear@14: nuclear@14: /// Set which LZMA compression level to use for the given OpenCTM context. nuclear@14: /// The compression level can be between 0 (fastest) and 9 (best). The higher nuclear@14: /// the compression level, the more memory is required for compression and nuclear@14: /// decompression. The default compression level is 1. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aLevel Which compression level to use (0 to 9). nuclear@14: CTMEXPORT void CTMCALL ctmCompressionLevel(CTMcontext aContext, nuclear@14: CTMuint aLevel); nuclear@14: nuclear@14: /// Set the vertex coordinate precision (only used by the MG2 compression nuclear@14: /// method). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aPrecision Fixed point precision. For instance, if this value is nuclear@14: /// 0.001, all vertex coordinates will be rounded to three decimals. nuclear@14: /// The default vertex coordinate precision is 2^-10 ~= 0.00098. nuclear@14: CTMEXPORT void CTMCALL ctmVertexPrecision(CTMcontext aContext, nuclear@14: CTMfloat aPrecision); nuclear@14: nuclear@14: /// Set the vertex coordinate precision, relative to the mesh dimensions (only nuclear@14: /// used by the MG2 compression method). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aRelPrecision Relative precision. This factor is multiplied by the nuclear@14: /// average triangle edge length in the mesh in order to obtain the nuclear@14: /// final, fixed point precision. For instance, if aRelPrecision is nuclear@14: /// 0.01, and the average edge length is 3.7, then the fixed point nuclear@14: /// precision is set to 0.037. nuclear@14: /// @note The mesh must have been defined using the ctmDefineMesh() function nuclear@14: /// before calling this function. nuclear@14: /// @see ctmVertexPrecision(). nuclear@14: CTMEXPORT void CTMCALL ctmVertexPrecisionRel(CTMcontext aContext, nuclear@14: CTMfloat aRelPrecision); nuclear@14: nuclear@14: /// Set the normal precision (only used by the MG2 compression method). The nuclear@14: /// normal is represented in spherical coordinates in the MG2 compression nuclear@14: /// method, and the normal precision controls the angular and radial resolution. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aPrecision Fixed point precision. For the angular information, nuclear@14: /// this value represents the angular precision. For the radial nuclear@14: /// information, this value is the linear resolution. For instance, nuclear@14: /// 0.01 means that the circle is divided into 100 steps, and the nuclear@14: /// normal magnitude is rounded to 2 decimals. The default normal nuclear@14: /// precision is 2^-8 ~= 0.0039. nuclear@14: CTMEXPORT void CTMCALL ctmNormalPrecision(CTMcontext aContext, nuclear@14: CTMfloat aPrecision); nuclear@14: nuclear@14: /// Set the coordinate precision for the specified UV map (only used by the nuclear@14: /// MG2 compression method). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aUVMap A UV map specifier for a defined UV map nuclear@14: /// (CTM_UV_MAP_1, ...). nuclear@14: /// @param[in] aPrecision Fixed point precision. For instance, if this value is nuclear@14: /// 0.001, all UV coordinates will be rounded to three decimals. nuclear@14: /// The default UV coordinate precision is 2^-12 ~= 0.00024. nuclear@14: /// @see ctmAddUVMap(). nuclear@14: CTMEXPORT void CTMCALL ctmUVCoordPrecision(CTMcontext aContext, nuclear@14: CTMenum aUVMap, CTMfloat aPrecision); nuclear@14: nuclear@14: /// Set the attribute value precision for the specified attribute map (only nuclear@14: /// used by the MG2 compression method). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aAttribMap An attribute map specifier for a defined attribute map nuclear@14: /// (CTM_ATTRIB_MAP_1, ...). nuclear@14: /// @param[in] aPrecision Fixed point precision. For instance, if this value is nuclear@14: /// 0.001, all attribute values will be rounded to three decimals. nuclear@14: /// If the attributes represent integer values, set the precision nuclear@14: /// to 1.0. The default attribute precision is 2^-8 ~= 0.0039. nuclear@14: /// @see ctmAddAttribMap(). nuclear@14: CTMEXPORT void CTMCALL ctmAttribPrecision(CTMcontext aContext, nuclear@14: CTMenum aAttribMap, CTMfloat aPrecision); nuclear@14: nuclear@14: /// Set the file comment for the given OpenCTM context. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aFileComment The file comment (zero terminated UTF-8 string). nuclear@14: CTMEXPORT void CTMCALL ctmFileComment(CTMcontext aContext, nuclear@14: const char * aFileComment); nuclear@14: nuclear@14: /// Define a triangle mesh. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aVertices An array of vertices (three consecutive floats make nuclear@14: /// one vertex). nuclear@14: /// @param[in] aVertexCount The number of vertices in \c aVertices (and nuclear@14: /// optionally \c aTexCoords). nuclear@14: /// @param[in] aIndices An array of vertex indices (three consecutive integers nuclear@14: /// make one triangle). nuclear@14: /// @param[in] aTriangleCount The number of triangles in \c aIndices (there nuclear@14: /// must be exactly 3 x \c aTriangleCount indices in \c aIndices). nuclear@14: /// @param[in] aNormals An array of per-vertex normals (or NULL if there are nuclear@14: /// no normals). Each normal is made up by three consecutive floats, nuclear@14: /// and there must be \c aVertexCount normals. nuclear@14: /// @see ctmAddUVMap(), ctmAddAttribMap(), ctmSave(), ctmSaveCustom(). nuclear@14: CTMEXPORT void CTMCALL ctmDefineMesh(CTMcontext aContext, nuclear@14: const CTMfloat * aVertices, CTMuint aVertexCount, const CTMuint * aIndices, nuclear@14: CTMuint aTriangleCount, const CTMfloat * aNormals); nuclear@14: nuclear@14: /// Define a UV map. There can be several UV maps in a mesh. A UV map is nuclear@14: /// typically used for 2D texture mapping. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aUVCoords An array of UV coordinates. Each UV coordinate is made nuclear@14: /// up by two consecutive floats, and there must be as many nuclear@14: /// coordinates as there are vertices in the mesh. nuclear@14: /// @param[in] aName A unique name for this UV map (zero terminated UTF-8 nuclear@14: /// string). nuclear@14: /// @param[in] aFileName A reference to a image file (zero terminated nuclear@14: /// UTF-8 string). If no file name reference exists, pass NULL. nuclear@14: /// @return A UV map index (CTM_UV_MAP_1 and higher). If the function nuclear@14: /// failed, it will return the zero valued CTM_NONE (use ctmGetError() nuclear@14: /// to determine the cause of the error). nuclear@14: /// @note A triangle mesh must have been defined before calling this function, nuclear@14: /// since the number of vertices is defined by the triangle mesh. nuclear@14: /// @see ctmDefineMesh(). nuclear@14: CTMEXPORT CTMenum CTMCALL ctmAddUVMap(CTMcontext aContext, nuclear@14: const CTMfloat * aUVCoords, const char * aName, const char * aFileName); nuclear@14: nuclear@14: /// Define a custom vertex attribute map. Custom vertex attributes can be used nuclear@14: /// for defining special per-vertex attributes, such as color, weight, ambient nuclear@14: /// occlusion factor, etc. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aAttribValues An array of attribute values. Each attribute value nuclear@14: /// is made up by four consecutive floats, and there must be as many nuclear@14: /// values as there are vertices in the mesh. nuclear@14: /// @param[in] aName A unique name for this attribute map (zero terminated UTF-8 nuclear@14: /// string). nuclear@14: /// @return A attribute map index (CTM_ATTRIB_MAP_1 and higher). If the function nuclear@14: /// failed, it will return the zero valued CTM_NONE (use ctmGetError() nuclear@14: /// to determine the cause of the error). nuclear@14: /// @note A triangle mesh must have been defined before calling this function, nuclear@14: /// since the number of vertices is defined by the triangle mesh. nuclear@14: /// @see ctmDefineMesh(). nuclear@14: CTMEXPORT CTMenum CTMCALL ctmAddAttribMap(CTMcontext aContext, nuclear@14: const CTMfloat * aAttribValues, const char * aName); nuclear@14: nuclear@14: /// Load an OpenCTM format file into the context. The mesh data can be retrieved nuclear@14: /// with the various ctmGet functions. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aFileName The name of the file to be loaded. nuclear@14: CTMEXPORT void CTMCALL ctmLoad(CTMcontext aContext, const char * aFileName); nuclear@14: nuclear@14: /// Load an OpenCTM format file using a custom stream read function. The mesh nuclear@14: /// data can be retrieved with the various ctmGet functions. nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aReadFn Pointer to a custom stream read function. nuclear@14: /// @param[in] aUserData Custom user data, which can be a C language FILE nuclear@14: /// handle, C++ istream object, or a custom object pointer nuclear@14: /// of any type. The user data pointer will be passed to the nuclear@14: /// custom stream read function. nuclear@14: /// @see CTMreadfn. nuclear@14: CTMEXPORT void CTMCALL ctmLoadCustom(CTMcontext aContext, CTMreadfn aReadFn, nuclear@14: void * aUserData); nuclear@14: nuclear@14: /// Save an OpenCTM format file. The mesh must have been defined by nuclear@14: /// ctmDefineMesh(). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aFileName The name of the file to be saved. nuclear@14: CTMEXPORT void CTMCALL ctmSave(CTMcontext aContext, const char * aFileName); nuclear@14: nuclear@14: /// Save an OpenCTM format file using a custom stream write function. The mesh nuclear@14: /// must have been defined by ctmDefineMesh(). nuclear@14: /// @param[in] aContext An OpenCTM context that has been created by nuclear@14: /// ctmNewContext(). nuclear@14: /// @param[in] aWriteFn Pointer to a custom stream write function. nuclear@14: /// @param[in] aUserData Custom user data, which can be a C language FILE nuclear@14: /// handle, C++ ostream object, or a custom object pointer nuclear@14: /// of any type. The user data pointer will be passed to the nuclear@14: /// custom stream write function. nuclear@14: /// @see CTMwritefn. nuclear@14: CTMEXPORT void CTMCALL ctmSaveCustom(CTMcontext aContext, CTMwritefn aWriteFn, nuclear@14: void * aUserData); nuclear@14: nuclear@14: #ifdef __cplusplus nuclear@14: } nuclear@14: #endif nuclear@14: nuclear@14: nuclear@14: // C++ extensions to the API (to disable C++ extensions, define OPENCTM_NO_CPP) nuclear@14: #if defined(__cplusplus) && !defined(OPENCTM_NO_CPP) nuclear@14: #include "openctmpp.h" nuclear@14: #endif nuclear@14: nuclear@14: #endif // __OPENCTM_H_