goat3d
diff libs/openctm/openctm.h @ 14:188c697b3b49
- added a document describing the goat3d file format chunk hierarchy
- started an alternative XML-based file format
- added the openctm library
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Thu, 26 Sep 2013 04:47:05 +0300 |
| parents | |
| children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/libs/openctm/openctm.h Thu Sep 26 04:47:05 2013 +0300 1.3 @@ -0,0 +1,655 @@ 1.4 +//----------------------------------------------------------------------------- 1.5 +// Product: OpenCTM 1.6 +// File: openctm.h 1.7 +// Description: OpenCTM API definition. 1.8 +//----------------------------------------------------------------------------- 1.9 +// Copyright (c) 2009-2010 Marcus Geelnard 1.10 +// 1.11 +// This software is provided 'as-is', without any express or implied 1.12 +// warranty. In no event will the authors be held liable for any damages 1.13 +// arising from the use of this software. 1.14 +// 1.15 +// Permission is granted to anyone to use this software for any purpose, 1.16 +// including commercial applications, and to alter it and redistribute it 1.17 +// freely, subject to the following restrictions: 1.18 +// 1.19 +// 1. The origin of this software must not be misrepresented; you must not 1.20 +// claim that you wrote the original software. If you use this software 1.21 +// in a product, an acknowledgment in the product documentation would be 1.22 +// appreciated but is not required. 1.23 +// 1.24 +// 2. Altered source versions must be plainly marked as such, and must not 1.25 +// be misrepresented as being the original software. 1.26 +// 1.27 +// 3. This notice may not be removed or altered from any source 1.28 +// distribution. 1.29 +//----------------------------------------------------------------------------- 1.30 + 1.31 +#ifndef __OPENCTM_H_ 1.32 +#define __OPENCTM_H_ 1.33 + 1.34 +/*! @mainpage OpenCTM API Reference 1.35 + * 1.36 + * @section intro_sec Introduction 1.37 + * 1.38 + * OpenCTM is an open file format for storing compressed triangle meshes. 1.39 + * In order to easily read and write OpenCTM files (usually suffixed .ctm) an 1.40 + * API (Application Program Interface) is provided that can easily be used from 1.41 + * most modern programming languages. 1.42 + * 1.43 + * The OpenCTM functionality itself is written in highly portable standard C 1.44 + * (C99). 1.45 + * 1.46 + * @section usage_sec Usage 1.47 + * 1.48 + * For information about how to use the OpenCTM API, see openctm.h. 1.49 + * 1.50 + * For information about the C++ wrapper classes, see CTMimporter and 1.51 + * CTMexporter. 1.52 + * 1.53 + * @section example_sec Example usage 1.54 + * 1.55 + * @subsection example_load_sec Loading a CTM file 1.56 + * 1.57 + * Here is a simple example of loading a CTM file: 1.58 + * 1.59 + * @code 1.60 + * CTMcontext context; 1.61 + * CTMuint vertCount, triCount, * indices; 1.62 + * CTMfloat * vertices; 1.63 + * 1.64 + * // Create a new context 1.65 + * context = ctmNewContext(CTM_IMPORT); 1.66 + * 1.67 + * // Load the OpenCTM file 1.68 + * ctmLoad(context, "mymesh.ctm"); 1.69 + * if(ctmGetError(context) == CTM_NONE) 1.70 + * { 1.71 + * // Access the mesh data 1.72 + * vertCount = ctmGetInteger(context, CTM_VERTEX_COUNT); 1.73 + * vertices = ctmGetFloatArray(context, CTM_VERTICES); 1.74 + * triCount = ctmGetInteger(context, CTM_TRIANGLE_COUNT); 1.75 + * indices = ctmGetIntegerArray(context, CTM_INDICES); 1.76 + * 1.77 + * // Deal with the mesh (e.g. transcode it to our internal representation) 1.78 + * // ... 1.79 + * } 1.80 + * 1.81 + * // Free the context 1.82 + * ctmFreeContext(context); 1.83 + * @endcode 1.84 + * 1.85 + * @subsection example_create_sec Creating a CTM file 1.86 + * 1.87 + * Here is a simple example of creating a CTM file: 1.88 + * 1.89 + * @code 1.90 + * CTMcontext context; 1.91 + * CTMuint vertCount, triCount, * indices; 1.92 + * CTMfloat * vertices; 1.93 + * 1.94 + * // Create our mesh in memory 1.95 + * vertCount = 100; 1.96 + * triCount = 120; 1.97 + * vertices = (CTMfloat *) malloc(3 * sizeof(CTMfloat) * vertCount); 1.98 + * indices = (CTMuint *) malloc(3 * sizeof(CTMuint) * triCount); 1.99 + * // ... 1.100 + * 1.101 + * // Create a new context 1.102 + * context = ctmNewContext(CTM_EXPORT); 1.103 + * 1.104 + * // Define our mesh representation to OpenCTM (store references to it in 1.105 + * // the context) 1.106 + * ctmDefineMesh(context, vertices, vertCount, indices, triCount, NULL); 1.107 + * 1.108 + * // Save the OpenCTM file 1.109 + * ctmSave(context, "mymesh.ctm"); 1.110 + * 1.111 + * // Free the context 1.112 + * ctmFreeContext(context); 1.113 + * 1.114 + * // Free our mesh 1.115 + * free(indices); 1.116 + * free(vertices); 1.117 + * @endcode 1.118 + */ 1.119 + 1.120 +#ifdef __cplusplus 1.121 +extern "C" { 1.122 +#endif 1.123 + 1.124 + 1.125 +// Declare calling conventions etc. 1.126 +#if defined(WIN32) || defined(_WIN32) 1.127 + // Windows 1.128 + #if defined(OPENCTM_STATIC) 1.129 + #define CTMEXPORT 1.130 + #else 1.131 + #if defined(OPENCTM_BUILD) 1.132 + #define CTMEXPORT __declspec(dllexport) 1.133 + #else 1.134 + #define CTMEXPORT __declspec(dllimport) 1.135 + #endif 1.136 + #endif 1.137 + #if defined(__MINGW32__) 1.138 + #define CTMCALL __attribute__ ((__stdcall__)) 1.139 + #elif (defined(_M_MRX000) || defined(_M_IX86) || defined(_M_ALPHA) || defined(_M_PPC)) && !defined(MIDL_PASS) 1.140 + #define CTMCALL __stdcall 1.141 + #else 1.142 + #define CTMCALL 1.143 + #endif 1.144 +#else 1.145 + // Unix 1.146 + #if !defined(OPENCTM_STATIC) && !defined(OPENCTM_BUILD) 1.147 + #define CTMEXPORT extern 1.148 + #else 1.149 + #if defined(OPENCTM_BUILD) && defined(__GNUC__) && (__GNUC__ >= 4) 1.150 + #define CTMEXPORT __attribute__ ((visibility("default"))) 1.151 + #else 1.152 + #define CTMEXPORT 1.153 + #endif 1.154 + #endif 1.155 + #define CTMCALL 1.156 +#endif 1.157 + 1.158 + 1.159 +// Get system specific type definitions for sized integers. We use the C99 1.160 +// standard stdint.h for this. 1.161 +#ifdef _MSC_VER 1.162 + // MS Visual Studio does not support C99 1.163 + typedef int int32_t; 1.164 + typedef unsigned int uint32_t; 1.165 +#else 1.166 + #include <stdint.h> 1.167 +#endif 1.168 + 1.169 + 1.170 +/// OpenCTM API version (1.0). 1.171 +#define CTM_API_VERSION 0x00000100 1.172 + 1.173 +/// Boolean TRUE. 1.174 +#define CTM_TRUE 1 1.175 + 1.176 +/// Boolean FALSE. 1.177 +#define CTM_FALSE 0 1.178 + 1.179 +/// Single precision floating point type (IEEE 754 32 bits wide). 1.180 +typedef float CTMfloat; 1.181 + 1.182 +/// Signed integer (32 bits wide). 1.183 +typedef int32_t CTMint; 1.184 + 1.185 +/// Unsigned integer (32 bits wide). 1.186 +typedef uint32_t CTMuint; 1.187 + 1.188 +/// OpenCTM context handle. 1.189 +typedef void * CTMcontext; 1.190 + 1.191 +/// OpenCTM specific enumerators. 1.192 +/// @note For the information query functions, it is an error to query a value 1.193 +/// of the wrong type (e.g. to query a string value with the 1.194 +/// ctmGetInteger() function). 1.195 +typedef enum { 1.196 + // Error codes (see ctmGetError()) 1.197 + CTM_NONE = 0x0000, ///< No error has occured (everything is OK). 1.198 + /// Also used as an error return value for 1.199 + /// functions that should return a CTMenum 1.200 + /// value. 1.201 + CTM_INVALID_CONTEXT = 0x0001, ///< The OpenCTM context was invalid (e.g. NULL). 1.202 + CTM_INVALID_ARGUMENT = 0x0002, ///< A function argument was invalid. 1.203 + CTM_INVALID_OPERATION = 0x0003, ///< The operation is not allowed. 1.204 + CTM_INVALID_MESH = 0x0004, ///< The mesh was invalid (e.g. no vertices). 1.205 + CTM_OUT_OF_MEMORY = 0x0005, ///< Not enough memory to proceed. 1.206 + CTM_FILE_ERROR = 0x0006, ///< File I/O error. 1.207 + CTM_BAD_FORMAT = 0x0007, ///< File format error (e.g. unrecognized format or corrupted file). 1.208 + CTM_LZMA_ERROR = 0x0008, ///< An error occured within the LZMA library. 1.209 + CTM_INTERNAL_ERROR = 0x0009, ///< An internal error occured (indicates a bug). 1.210 + CTM_UNSUPPORTED_FORMAT_VERSION = 0x000A, ///< Unsupported file format version. 1.211 + 1.212 + // OpenCTM context modes 1.213 + CTM_IMPORT = 0x0101, ///< The OpenCTM context will be used for importing data. 1.214 + CTM_EXPORT = 0x0102, ///< The OpenCTM context will be used for exporting data. 1.215 + 1.216 + // Compression methods 1.217 + CTM_METHOD_RAW = 0x0201, ///< Just store the raw data. 1.218 + CTM_METHOD_MG1 = 0x0202, ///< Lossless compression (floating point). 1.219 + CTM_METHOD_MG2 = 0x0203, ///< Lossless compression (fixed point). 1.220 + 1.221 + // Context queries 1.222 + CTM_VERTEX_COUNT = 0x0301, ///< Number of vertices in the mesh (integer). 1.223 + CTM_TRIANGLE_COUNT = 0x0302, ///< Number of triangles in the mesh (integer). 1.224 + CTM_HAS_NORMALS = 0x0303, ///< CTM_TRUE if the mesh has normals (integer). 1.225 + CTM_UV_MAP_COUNT = 0x0304, ///< Number of UV coordinate sets (integer). 1.226 + CTM_ATTRIB_MAP_COUNT = 0x0305, ///< Number of custom attribute sets (integer). 1.227 + CTM_VERTEX_PRECISION = 0x0306, ///< Vertex precision - for MG2 (float). 1.228 + CTM_NORMAL_PRECISION = 0x0307, ///< Normal precision - for MG2 (float). 1.229 + CTM_COMPRESSION_METHOD = 0x0308, ///< Compression method (integer). 1.230 + CTM_FILE_COMMENT = 0x0309, ///< File comment (string). 1.231 + 1.232 + // UV/attribute map queries 1.233 + CTM_NAME = 0x0501, ///< Unique name (UV/attrib map string). 1.234 + CTM_FILE_NAME = 0x0502, ///< File name reference (UV map string). 1.235 + CTM_PRECISION = 0x0503, ///< Value precision (UV/attrib map float). 1.236 + 1.237 + // Array queries 1.238 + CTM_INDICES = 0x0601, ///< Triangle indices (integer array). 1.239 + CTM_VERTICES = 0x0602, ///< Vertex point coordinates (float array). 1.240 + CTM_NORMALS = 0x0603, ///< Per vertex normals (float array). 1.241 + CTM_UV_MAP_1 = 0x0700, ///< Per vertex UV map 1 (float array). 1.242 + CTM_UV_MAP_2 = 0x0701, ///< Per vertex UV map 2 (float array). 1.243 + CTM_UV_MAP_3 = 0x0702, ///< Per vertex UV map 3 (float array). 1.244 + CTM_UV_MAP_4 = 0x0703, ///< Per vertex UV map 4 (float array). 1.245 + CTM_UV_MAP_5 = 0x0704, ///< Per vertex UV map 5 (float array). 1.246 + CTM_UV_MAP_6 = 0x0705, ///< Per vertex UV map 6 (float array). 1.247 + CTM_UV_MAP_7 = 0x0706, ///< Per vertex UV map 7 (float array). 1.248 + CTM_UV_MAP_8 = 0x0707, ///< Per vertex UV map 8 (float array). 1.249 + CTM_ATTRIB_MAP_1 = 0x0800, ///< Per vertex attribute map 1 (float array). 1.250 + CTM_ATTRIB_MAP_2 = 0x0801, ///< Per vertex attribute map 2 (float array). 1.251 + CTM_ATTRIB_MAP_3 = 0x0802, ///< Per vertex attribute map 3 (float array). 1.252 + CTM_ATTRIB_MAP_4 = 0x0803, ///< Per vertex attribute map 4 (float array). 1.253 + CTM_ATTRIB_MAP_5 = 0x0804, ///< Per vertex attribute map 5 (float array). 1.254 + CTM_ATTRIB_MAP_6 = 0x0805, ///< Per vertex attribute map 6 (float array). 1.255 + CTM_ATTRIB_MAP_7 = 0x0806, ///< Per vertex attribute map 7 (float array). 1.256 + CTM_ATTRIB_MAP_8 = 0x0807 ///< Per vertex attribute map 8 (float array). 1.257 +} CTMenum; 1.258 + 1.259 +/// Stream read() function pointer. 1.260 +/// @param[in] aBuf Pointer to the memory buffer to which data should be read. 1.261 +/// @param[in] aCount The number of bytes to read. 1.262 +/// @param[in] aUserData The custom user data that was passed to the 1.263 +/// ctmLoadCustom() function. 1.264 +/// @return The number of bytes actually read (if this is less than aCount, it 1.265 +/// indicates that an error occured or the end of file was reached 1.266 +/// before all bytes were read). 1.267 +typedef CTMuint (CTMCALL * CTMreadfn)(void * aBuf, CTMuint aCount, void * aUserData); 1.268 + 1.269 +/// Stream write() function pointer. 1.270 +/// @param[in] aBuf Pointer to the memory buffer from which data should be written. 1.271 +/// @param[in] aCount The number of bytes to write. 1.272 +/// @param[in] aUserData The custom user data that was passed to the 1.273 +/// ctmSaveCustom() function. 1.274 +/// @return The number of bytes actually written (if this is less than aCount, it 1.275 +/// indicates that an error occured). 1.276 +typedef CTMuint (CTMCALL * CTMwritefn)(const void * aBuf, CTMuint aCount, void * aUserData); 1.277 + 1.278 +/// Create a new OpenCTM context. The context is used for all subsequent 1.279 +/// OpenCTM function calls. Several contexts can coexist at the same time. 1.280 +/// @param[in] aMode An OpenCTM context mode. Set this to CTM_IMPORT if the 1.281 +/// context will be used for importing data, or set it to CTM_EXPORT 1.282 +/// if it will be used for exporting data. 1.283 +/// @return An OpenCTM context handle (or NULL if no context could be created). 1.284 +CTMEXPORT CTMcontext CTMCALL ctmNewContext(CTMenum aMode); 1.285 + 1.286 +/// Free an OpenCTM context. 1.287 +/// @param[in] aContext An OpenCTM context that has been created by 1.288 +/// ctmNewContext(). 1.289 +/// @see ctmNewContext() 1.290 +CTMEXPORT void CTMCALL ctmFreeContext(CTMcontext aContext); 1.291 + 1.292 +/// Returns the latest error. Calling this function will return the last 1.293 +/// produced error code, or CTM_NO_ERROR (zero) if no error has occured since 1.294 +/// the last call to ctmGetError(). When this function is called, the internal 1.295 +/// error varibale will be reset to CTM_NONE. 1.296 +/// @param[in] aContext An OpenCTM context that has been created by 1.297 +/// ctmNewContext(). 1.298 +/// @return An OpenCTM error code. 1.299 +/// @see CTMenum 1.300 +CTMEXPORT CTMenum CTMCALL ctmGetError(CTMcontext aContext); 1.301 + 1.302 +/// Converts an OpenCTM error code to a zero-terminated string. 1.303 +/// @param[in] aError An OpenCTM error code, as returned by ctmGetError(). 1.304 +/// @return A zero terminated string that describes the error. For instance, 1.305 +/// if \c aError is CTM_INVALID_OPERATION, then the return value will 1.306 +/// be "CTM_INVALID_OPERATION". 1.307 +/// @see CTMenum 1.308 +CTMEXPORT const char * CTMCALL ctmErrorString(CTMenum aError); 1.309 + 1.310 +/// Get information about an OpenCTM context. 1.311 +/// @param[in] aContext An OpenCTM context that has been created by 1.312 +/// ctmNewContext(). 1.313 +/// @param[in] aProperty Which property to return. 1.314 +/// @return An integer value, representing the OpenCTM context property given 1.315 +/// by \c aProperty. 1.316 +/// @see CTMenum 1.317 +CTMEXPORT CTMuint CTMCALL ctmGetInteger(CTMcontext aContext, CTMenum aProperty); 1.318 + 1.319 +/// Get information about an OpenCTM context. 1.320 +/// @param[in] aContext An OpenCTM context that has been created by 1.321 +/// ctmNewContext(). 1.322 +/// @param[in] aProperty Which property to return. 1.323 +/// @return A floating point value, representing the OpenCTM context property 1.324 +/// given by \c aProperty. 1.325 +/// @see CTMenum 1.326 +CTMEXPORT CTMfloat CTMCALL ctmGetFloat(CTMcontext aContext, CTMenum aProperty); 1.327 + 1.328 +/// Get an integer array from an OpenCTM context. 1.329 +/// @param[in] aContext An OpenCTM context that has been created by 1.330 +/// ctmNewContext(). 1.331 +/// @param[in] aProperty Which array to return. 1.332 +/// @return An integer array. If the requested array does not exist, or 1.333 +/// if \c aProperty does not indicate an integer array, the function 1.334 +/// returns NULL. 1.335 +/// @note The array is only valid as long as the OpenCTM context is valid, or 1.336 +/// until the corresponding array changes within the OpenCTM context. 1.337 +/// Trying to access an invalid array will result in undefined 1.338 +/// behaviour. Therefor it is recommended that the array is copied to 1.339 +/// a new variable if it is to be used other than directly after the call 1.340 +/// to ctmGetIntegerArray(). 1.341 +/// @see CTMenum 1.342 +CTMEXPORT const CTMuint * CTMCALL ctmGetIntegerArray(CTMcontext aContext, 1.343 + CTMenum aProperty); 1.344 + 1.345 +/// Get a floating point array from an OpenCTM context. 1.346 +/// @param[in] aContext An OpenCTM context that has been created by 1.347 +/// ctmNewContext(). 1.348 +/// @param[in] aProperty Which array to return. 1.349 +/// @return A floating point array. If the requested array does not exist, or 1.350 +/// if \c aProperty does not indicate a float array, the function 1.351 +/// returns NULL. 1.352 +/// @note The array is only valid as long as the OpenCTM context is valid, or 1.353 +/// until the corresponding array changes within the OpenCTM context. 1.354 +/// Trying to access an invalid array will result in undefined 1.355 +/// behaviour. Therefor it is recommended that the array is copied to 1.356 +/// a new variable if it is to be used other than directly after the call 1.357 +/// to ctmGetFloatArray(). 1.358 +/// @see CTMenum 1.359 +CTMEXPORT const CTMfloat * CTMCALL ctmGetFloatArray(CTMcontext aContext, 1.360 + CTMenum aProperty); 1.361 + 1.362 +/// Get a reference to the named UV map. 1.363 +/// @param[in] aContext An OpenCTM context that has been created by 1.364 +/// ctmNewContext(). 1.365 +/// @param[in] aName The name of the UV map that should be returned. 1.366 +/// @return A reference to a UV map. If the UV map was found, a value of 1.367 +/// CTM_UV_MAP_1 or higher is returned, otherwise CTM_NONE is 1.368 +/// returned. 1.369 +CTMEXPORT CTMenum CTMCALL ctmGetNamedUVMap(CTMcontext aContext, 1.370 + const char * aName); 1.371 + 1.372 +/// Get information about a UV map. 1.373 +/// @param[in] aContext An OpenCTM context that has been created by 1.374 +/// ctmNewContext(). 1.375 +/// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher). 1.376 +/// @param[in] aProperty Which UV map property to return. 1.377 +/// @return A string value, representing the UV map property given 1.378 +/// by \c aProperty. 1.379 +/// @note The string is only valid as long as the UV map within the OpenCTM 1.380 +/// context is valid. Trying to access an invalid string will result in 1.381 +/// undefined behaviour. Therefor it is recommended that the string is 1.382 +/// copied to a new variable if it is to be used other than directly after 1.383 +/// the call to ctmGetUVMapString(). 1.384 +/// @see CTMenum 1.385 +CTMEXPORT const char * CTMCALL ctmGetUVMapString(CTMcontext aContext, 1.386 + CTMenum aUVMap, CTMenum aProperty); 1.387 + 1.388 +/// Get information about a UV map. 1.389 +/// @param[in] aContext An OpenCTM context that has been created by 1.390 +/// ctmNewContext(). 1.391 +/// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher). 1.392 +/// @param[in] aProperty Which UV map property to return. 1.393 +/// @return A floating point value, representing the UV map property given 1.394 +/// by \c aProperty. 1.395 +/// @see CTMenum 1.396 +CTMEXPORT CTMfloat CTMCALL ctmGetUVMapFloat(CTMcontext aContext, 1.397 + CTMenum aUVMap, CTMenum aProperty); 1.398 + 1.399 +/// Get a reference to the named vertex attribute map. 1.400 +/// @param[in] aContext An OpenCTM context that has been created by 1.401 +/// ctmNewContext(). 1.402 +/// @param[in] aName The name of the attribute map that should be returned. 1.403 +/// @return A reference to an attribute map. If the attribute map was found, 1.404 +/// a value of CTM_ATTRIB_MAP_1 or higher is returned, otherwise 1.405 +/// CTM_NONE is returned. 1.406 +CTMEXPORT CTMenum CTMCALL ctmGetNamedAttribMap(CTMcontext aContext, 1.407 + const char * aName); 1.408 + 1.409 +/// Get information about a vertex attribute map. 1.410 +/// @param[in] aContext An OpenCTM context that has been created by 1.411 +/// ctmNewContext(). 1.412 +/// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1 1.413 +/// or higher). 1.414 +/// @param[in] aProperty Which vertex attribute map property to return. 1.415 +/// @return A string value, representing the vertex attribute map property given 1.416 +/// by \c aProperty. 1.417 +/// @note The string is only valid as long as the vertex attribute map within 1.418 +/// the OpenCTM context is valid. Trying to access an invalid string will 1.419 +/// result in undefined behaviour. Therefor it is recommended that the 1.420 +/// string is copied to a new variable if it is to be used other than 1.421 +/// directly after the call to ctmGetAttribMapString(). 1.422 +/// @see CTMenum 1.423 +CTMEXPORT const char * CTMCALL ctmGetAttribMapString(CTMcontext aContext, 1.424 + CTMenum aAttribMap, CTMenum aProperty); 1.425 + 1.426 +/// Get information about a vertex attribute map. 1.427 +/// @param[in] aContext An OpenCTM context that has been created by 1.428 +/// ctmNewContext(). 1.429 +/// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1 1.430 +/// or higher). 1.431 +/// @param[in] aProperty Which vertex attribute map property to return. 1.432 +/// @return A floating point value, representing the vertex attribute map 1.433 +/// property given by \c aProperty. 1.434 +/// @see CTMenum 1.435 +CTMEXPORT CTMfloat CTMCALL ctmGetAttribMapFloat(CTMcontext aContext, 1.436 + CTMenum aAttribMap, CTMenum aProperty); 1.437 + 1.438 +/// Get information about an OpenCTM context. 1.439 +/// @param[in] aContext An OpenCTM context that has been created by 1.440 +/// ctmNewContext(). 1.441 +/// @param[in] aProperty Which property to return. 1.442 +/// @return A string value, representing the OpenCTM context property given 1.443 +/// by \c aProperty. 1.444 +/// @note The string is only valid as long as the OpenCTM context is valid, or 1.445 +/// until the corresponding string changes within the OpenCTM context 1.446 +/// (e.g. calling ctmFileComment() invalidates the CTM_FILE_COMMENT 1.447 +/// string). Trying to access an invalid string will result in undefined 1.448 +/// behaviour. Therefor it is recommended that the string is copied to 1.449 +/// a new variable if it is to be used other than directly after the call 1.450 +/// to ctmGetString(). 1.451 +/// @see CTMenum 1.452 +CTMEXPORT const char * CTMCALL ctmGetString(CTMcontext aContext, 1.453 + CTMenum aProperty); 1.454 + 1.455 +/// Set which compression method to use for the given OpenCTM context. 1.456 +/// The selected compression method will be used when calling the ctmSave() 1.457 +/// function. 1.458 +/// @param[in] aContext An OpenCTM context that has been created by 1.459 +/// ctmNewContext(). 1.460 +/// @param[in] aMethod Which compression method to use: CTM_METHOD_RAW, 1.461 +/// CTM_METHOD_MG1 or CTM_METHOD_MG2 (the default method is 1.462 +/// CTM_METHOD_MG1). 1.463 +/// @see CTM_METHOD_RAW, CTM_METHOD_MG1, CTM_METHOD_MG2 1.464 +CTMEXPORT void CTMCALL ctmCompressionMethod(CTMcontext aContext, 1.465 + CTMenum aMethod); 1.466 + 1.467 +/// Set which LZMA compression level to use for the given OpenCTM context. 1.468 +/// The compression level can be between 0 (fastest) and 9 (best). The higher 1.469 +/// the compression level, the more memory is required for compression and 1.470 +/// decompression. The default compression level is 1. 1.471 +/// @param[in] aContext An OpenCTM context that has been created by 1.472 +/// ctmNewContext(). 1.473 +/// @param[in] aLevel Which compression level to use (0 to 9). 1.474 +CTMEXPORT void CTMCALL ctmCompressionLevel(CTMcontext aContext, 1.475 + CTMuint aLevel); 1.476 + 1.477 +/// Set the vertex coordinate precision (only used by the MG2 compression 1.478 +/// method). 1.479 +/// @param[in] aContext An OpenCTM context that has been created by 1.480 +/// ctmNewContext(). 1.481 +/// @param[in] aPrecision Fixed point precision. For instance, if this value is 1.482 +/// 0.001, all vertex coordinates will be rounded to three decimals. 1.483 +/// The default vertex coordinate precision is 2^-10 ~= 0.00098. 1.484 +CTMEXPORT void CTMCALL ctmVertexPrecision(CTMcontext aContext, 1.485 + CTMfloat aPrecision); 1.486 + 1.487 +/// Set the vertex coordinate precision, relative to the mesh dimensions (only 1.488 +/// used by the MG2 compression method). 1.489 +/// @param[in] aContext An OpenCTM context that has been created by 1.490 +/// ctmNewContext(). 1.491 +/// @param[in] aRelPrecision Relative precision. This factor is multiplied by the 1.492 +/// average triangle edge length in the mesh in order to obtain the 1.493 +/// final, fixed point precision. For instance, if aRelPrecision is 1.494 +/// 0.01, and the average edge length is 3.7, then the fixed point 1.495 +/// precision is set to 0.037. 1.496 +/// @note The mesh must have been defined using the ctmDefineMesh() function 1.497 +/// before calling this function. 1.498 +/// @see ctmVertexPrecision(). 1.499 +CTMEXPORT void CTMCALL ctmVertexPrecisionRel(CTMcontext aContext, 1.500 + CTMfloat aRelPrecision); 1.501 + 1.502 +/// Set the normal precision (only used by the MG2 compression method). The 1.503 +/// normal is represented in spherical coordinates in the MG2 compression 1.504 +/// method, and the normal precision controls the angular and radial resolution. 1.505 +/// @param[in] aContext An OpenCTM context that has been created by 1.506 +/// ctmNewContext(). 1.507 +/// @param[in] aPrecision Fixed point precision. For the angular information, 1.508 +/// this value represents the angular precision. For the radial 1.509 +/// information, this value is the linear resolution. For instance, 1.510 +/// 0.01 means that the circle is divided into 100 steps, and the 1.511 +/// normal magnitude is rounded to 2 decimals. The default normal 1.512 +/// precision is 2^-8 ~= 0.0039. 1.513 +CTMEXPORT void CTMCALL ctmNormalPrecision(CTMcontext aContext, 1.514 + CTMfloat aPrecision); 1.515 + 1.516 +/// Set the coordinate precision for the specified UV map (only used by the 1.517 +/// MG2 compression method). 1.518 +/// @param[in] aContext An OpenCTM context that has been created by 1.519 +/// ctmNewContext(). 1.520 +/// @param[in] aUVMap A UV map specifier for a defined UV map 1.521 +/// (CTM_UV_MAP_1, ...). 1.522 +/// @param[in] aPrecision Fixed point precision. For instance, if this value is 1.523 +/// 0.001, all UV coordinates will be rounded to three decimals. 1.524 +/// The default UV coordinate precision is 2^-12 ~= 0.00024. 1.525 +/// @see ctmAddUVMap(). 1.526 +CTMEXPORT void CTMCALL ctmUVCoordPrecision(CTMcontext aContext, 1.527 + CTMenum aUVMap, CTMfloat aPrecision); 1.528 + 1.529 +/// Set the attribute value precision for the specified attribute map (only 1.530 +/// used by the MG2 compression method). 1.531 +/// @param[in] aContext An OpenCTM context that has been created by 1.532 +/// ctmNewContext(). 1.533 +/// @param[in] aAttribMap An attribute map specifier for a defined attribute map 1.534 +/// (CTM_ATTRIB_MAP_1, ...). 1.535 +/// @param[in] aPrecision Fixed point precision. For instance, if this value is 1.536 +/// 0.001, all attribute values will be rounded to three decimals. 1.537 +/// If the attributes represent integer values, set the precision 1.538 +/// to 1.0. The default attribute precision is 2^-8 ~= 0.0039. 1.539 +/// @see ctmAddAttribMap(). 1.540 +CTMEXPORT void CTMCALL ctmAttribPrecision(CTMcontext aContext, 1.541 + CTMenum aAttribMap, CTMfloat aPrecision); 1.542 + 1.543 +/// Set the file comment for the given OpenCTM context. 1.544 +/// @param[in] aContext An OpenCTM context that has been created by 1.545 +/// ctmNewContext(). 1.546 +/// @param[in] aFileComment The file comment (zero terminated UTF-8 string). 1.547 +CTMEXPORT void CTMCALL ctmFileComment(CTMcontext aContext, 1.548 + const char * aFileComment); 1.549 + 1.550 +/// Define a triangle mesh. 1.551 +/// @param[in] aContext An OpenCTM context that has been created by 1.552 +/// ctmNewContext(). 1.553 +/// @param[in] aVertices An array of vertices (three consecutive floats make 1.554 +/// one vertex). 1.555 +/// @param[in] aVertexCount The number of vertices in \c aVertices (and 1.556 +/// optionally \c aTexCoords). 1.557 +/// @param[in] aIndices An array of vertex indices (three consecutive integers 1.558 +/// make one triangle). 1.559 +/// @param[in] aTriangleCount The number of triangles in \c aIndices (there 1.560 +/// must be exactly 3 x \c aTriangleCount indices in \c aIndices). 1.561 +/// @param[in] aNormals An array of per-vertex normals (or NULL if there are 1.562 +/// no normals). Each normal is made up by three consecutive floats, 1.563 +/// and there must be \c aVertexCount normals. 1.564 +/// @see ctmAddUVMap(), ctmAddAttribMap(), ctmSave(), ctmSaveCustom(). 1.565 +CTMEXPORT void CTMCALL ctmDefineMesh(CTMcontext aContext, 1.566 + const CTMfloat * aVertices, CTMuint aVertexCount, const CTMuint * aIndices, 1.567 + CTMuint aTriangleCount, const CTMfloat * aNormals); 1.568 + 1.569 +/// Define a UV map. There can be several UV maps in a mesh. A UV map is 1.570 +/// typically used for 2D texture mapping. 1.571 +/// @param[in] aContext An OpenCTM context that has been created by 1.572 +/// ctmNewContext(). 1.573 +/// @param[in] aUVCoords An array of UV coordinates. Each UV coordinate is made 1.574 +/// up by two consecutive floats, and there must be as many 1.575 +/// coordinates as there are vertices in the mesh. 1.576 +/// @param[in] aName A unique name for this UV map (zero terminated UTF-8 1.577 +/// string). 1.578 +/// @param[in] aFileName A reference to a image file (zero terminated 1.579 +/// UTF-8 string). If no file name reference exists, pass NULL. 1.580 +/// @return A UV map index (CTM_UV_MAP_1 and higher). If the function 1.581 +/// failed, it will return the zero valued CTM_NONE (use ctmGetError() 1.582 +/// to determine the cause of the error). 1.583 +/// @note A triangle mesh must have been defined before calling this function, 1.584 +/// since the number of vertices is defined by the triangle mesh. 1.585 +/// @see ctmDefineMesh(). 1.586 +CTMEXPORT CTMenum CTMCALL ctmAddUVMap(CTMcontext aContext, 1.587 + const CTMfloat * aUVCoords, const char * aName, const char * aFileName); 1.588 + 1.589 +/// Define a custom vertex attribute map. Custom vertex attributes can be used 1.590 +/// for defining special per-vertex attributes, such as color, weight, ambient 1.591 +/// occlusion factor, etc. 1.592 +/// @param[in] aContext An OpenCTM context that has been created by 1.593 +/// ctmNewContext(). 1.594 +/// @param[in] aAttribValues An array of attribute values. Each attribute value 1.595 +/// is made up by four consecutive floats, and there must be as many 1.596 +/// values as there are vertices in the mesh. 1.597 +/// @param[in] aName A unique name for this attribute map (zero terminated UTF-8 1.598 +/// string). 1.599 +/// @return A attribute map index (CTM_ATTRIB_MAP_1 and higher). If the function 1.600 +/// failed, it will return the zero valued CTM_NONE (use ctmGetError() 1.601 +/// to determine the cause of the error). 1.602 +/// @note A triangle mesh must have been defined before calling this function, 1.603 +/// since the number of vertices is defined by the triangle mesh. 1.604 +/// @see ctmDefineMesh(). 1.605 +CTMEXPORT CTMenum CTMCALL ctmAddAttribMap(CTMcontext aContext, 1.606 + const CTMfloat * aAttribValues, const char * aName); 1.607 + 1.608 +/// Load an OpenCTM format file into the context. The mesh data can be retrieved 1.609 +/// with the various ctmGet functions. 1.610 +/// @param[in] aContext An OpenCTM context that has been created by 1.611 +/// ctmNewContext(). 1.612 +/// @param[in] aFileName The name of the file to be loaded. 1.613 +CTMEXPORT void CTMCALL ctmLoad(CTMcontext aContext, const char * aFileName); 1.614 + 1.615 +/// Load an OpenCTM format file using a custom stream read function. The mesh 1.616 +/// data can be retrieved with the various ctmGet functions. 1.617 +/// @param[in] aContext An OpenCTM context that has been created by 1.618 +/// ctmNewContext(). 1.619 +/// @param[in] aReadFn Pointer to a custom stream read function. 1.620 +/// @param[in] aUserData Custom user data, which can be a C language FILE 1.621 +/// handle, C++ istream object, or a custom object pointer 1.622 +/// of any type. The user data pointer will be passed to the 1.623 +/// custom stream read function. 1.624 +/// @see CTMreadfn. 1.625 +CTMEXPORT void CTMCALL ctmLoadCustom(CTMcontext aContext, CTMreadfn aReadFn, 1.626 + void * aUserData); 1.627 + 1.628 +/// Save an OpenCTM format file. The mesh must have been defined by 1.629 +/// ctmDefineMesh(). 1.630 +/// @param[in] aContext An OpenCTM context that has been created by 1.631 +/// ctmNewContext(). 1.632 +/// @param[in] aFileName The name of the file to be saved. 1.633 +CTMEXPORT void CTMCALL ctmSave(CTMcontext aContext, const char * aFileName); 1.634 + 1.635 +/// Save an OpenCTM format file using a custom stream write function. The mesh 1.636 +/// must have been defined by ctmDefineMesh(). 1.637 +/// @param[in] aContext An OpenCTM context that has been created by 1.638 +/// ctmNewContext(). 1.639 +/// @param[in] aWriteFn Pointer to a custom stream write function. 1.640 +/// @param[in] aUserData Custom user data, which can be a C language FILE 1.641 +/// handle, C++ ostream object, or a custom object pointer 1.642 +/// of any type. The user data pointer will be passed to the 1.643 +/// custom stream write function. 1.644 +/// @see CTMwritefn. 1.645 +CTMEXPORT void CTMCALL ctmSaveCustom(CTMcontext aContext, CTMwritefn aWriteFn, 1.646 + void * aUserData); 1.647 + 1.648 +#ifdef __cplusplus 1.649 +} 1.650 +#endif 1.651 + 1.652 + 1.653 +// C++ extensions to the API (to disable C++ extensions, define OPENCTM_NO_CPP) 1.654 +#if defined(__cplusplus) && !defined(OPENCTM_NO_CPP) 1.655 + #include "openctmpp.h" 1.656 +#endif 1.657 + 1.658 +#endif // __OPENCTM_H_