goat3d

annotate libs/openctm/openctm.h @ 14:188c697b3b49

find changesets by author, revision, files, or words in the commit message
- 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
rev   line source
nuclear@14 1 //-----------------------------------------------------------------------------
nuclear@14 2 // Product: OpenCTM
nuclear@14 3 // File: openctm.h
nuclear@14 4 // Description: OpenCTM API definition.
nuclear@14 5 //-----------------------------------------------------------------------------
nuclear@14 6 // Copyright (c) 2009-2010 Marcus Geelnard
nuclear@14 7 //
nuclear@14 8 // This software is provided 'as-is', without any express or implied
nuclear@14 9 // warranty. In no event will the authors be held liable for any damages
nuclear@14 10 // arising from the use of this software.
nuclear@14 11 //
nuclear@14 12 // Permission is granted to anyone to use this software for any purpose,
nuclear@14 13 // including commercial applications, and to alter it and redistribute it
nuclear@14 14 // freely, subject to the following restrictions:
nuclear@14 15 //
nuclear@14 16 // 1. The origin of this software must not be misrepresented; you must not
nuclear@14 17 // claim that you wrote the original software. If you use this software
nuclear@14 18 // in a product, an acknowledgment in the product documentation would be
nuclear@14 19 // appreciated but is not required.
nuclear@14 20 //
nuclear@14 21 // 2. Altered source versions must be plainly marked as such, and must not
nuclear@14 22 // be misrepresented as being the original software.
nuclear@14 23 //
nuclear@14 24 // 3. This notice may not be removed or altered from any source
nuclear@14 25 // distribution.
nuclear@14 26 //-----------------------------------------------------------------------------
nuclear@14 27
nuclear@14 28 #ifndef __OPENCTM_H_
nuclear@14 29 #define __OPENCTM_H_
nuclear@14 30
nuclear@14 31 /*! @mainpage OpenCTM API Reference
nuclear@14 32 *
nuclear@14 33 * @section intro_sec Introduction
nuclear@14 34 *
nuclear@14 35 * OpenCTM is an open file format for storing compressed triangle meshes.
nuclear@14 36 * In order to easily read and write OpenCTM files (usually suffixed .ctm) an
nuclear@14 37 * API (Application Program Interface) is provided that can easily be used from
nuclear@14 38 * most modern programming languages.
nuclear@14 39 *
nuclear@14 40 * The OpenCTM functionality itself is written in highly portable standard C
nuclear@14 41 * (C99).
nuclear@14 42 *
nuclear@14 43 * @section usage_sec Usage
nuclear@14 44 *
nuclear@14 45 * For information about how to use the OpenCTM API, see openctm.h.
nuclear@14 46 *
nuclear@14 47 * For information about the C++ wrapper classes, see CTMimporter and
nuclear@14 48 * CTMexporter.
nuclear@14 49 *
nuclear@14 50 * @section example_sec Example usage
nuclear@14 51 *
nuclear@14 52 * @subsection example_load_sec Loading a CTM file
nuclear@14 53 *
nuclear@14 54 * Here is a simple example of loading a CTM file:
nuclear@14 55 *
nuclear@14 56 * @code
nuclear@14 57 * CTMcontext context;
nuclear@14 58 * CTMuint vertCount, triCount, * indices;
nuclear@14 59 * CTMfloat * vertices;
nuclear@14 60 *
nuclear@14 61 * // Create a new context
nuclear@14 62 * context = ctmNewContext(CTM_IMPORT);
nuclear@14 63 *
nuclear@14 64 * // Load the OpenCTM file
nuclear@14 65 * ctmLoad(context, "mymesh.ctm");
nuclear@14 66 * if(ctmGetError(context) == CTM_NONE)
nuclear@14 67 * {
nuclear@14 68 * // Access the mesh data
nuclear@14 69 * vertCount = ctmGetInteger(context, CTM_VERTEX_COUNT);
nuclear@14 70 * vertices = ctmGetFloatArray(context, CTM_VERTICES);
nuclear@14 71 * triCount = ctmGetInteger(context, CTM_TRIANGLE_COUNT);
nuclear@14 72 * indices = ctmGetIntegerArray(context, CTM_INDICES);
nuclear@14 73 *
nuclear@14 74 * // Deal with the mesh (e.g. transcode it to our internal representation)
nuclear@14 75 * // ...
nuclear@14 76 * }
nuclear@14 77 *
nuclear@14 78 * // Free the context
nuclear@14 79 * ctmFreeContext(context);
nuclear@14 80 * @endcode
nuclear@14 81 *
nuclear@14 82 * @subsection example_create_sec Creating a CTM file
nuclear@14 83 *
nuclear@14 84 * Here is a simple example of creating a CTM file:
nuclear@14 85 *
nuclear@14 86 * @code
nuclear@14 87 * CTMcontext context;
nuclear@14 88 * CTMuint vertCount, triCount, * indices;
nuclear@14 89 * CTMfloat * vertices;
nuclear@14 90 *
nuclear@14 91 * // Create our mesh in memory
nuclear@14 92 * vertCount = 100;
nuclear@14 93 * triCount = 120;
nuclear@14 94 * vertices = (CTMfloat *) malloc(3 * sizeof(CTMfloat) * vertCount);
nuclear@14 95 * indices = (CTMuint *) malloc(3 * sizeof(CTMuint) * triCount);
nuclear@14 96 * // ...
nuclear@14 97 *
nuclear@14 98 * // Create a new context
nuclear@14 99 * context = ctmNewContext(CTM_EXPORT);
nuclear@14 100 *
nuclear@14 101 * // Define our mesh representation to OpenCTM (store references to it in
nuclear@14 102 * // the context)
nuclear@14 103 * ctmDefineMesh(context, vertices, vertCount, indices, triCount, NULL);
nuclear@14 104 *
nuclear@14 105 * // Save the OpenCTM file
nuclear@14 106 * ctmSave(context, "mymesh.ctm");
nuclear@14 107 *
nuclear@14 108 * // Free the context
nuclear@14 109 * ctmFreeContext(context);
nuclear@14 110 *
nuclear@14 111 * // Free our mesh
nuclear@14 112 * free(indices);
nuclear@14 113 * free(vertices);
nuclear@14 114 * @endcode
nuclear@14 115 */
nuclear@14 116
nuclear@14 117 #ifdef __cplusplus
nuclear@14 118 extern "C" {
nuclear@14 119 #endif
nuclear@14 120
nuclear@14 121
nuclear@14 122 // Declare calling conventions etc.
nuclear@14 123 #if defined(WIN32) || defined(_WIN32)
nuclear@14 124 // Windows
nuclear@14 125 #if defined(OPENCTM_STATIC)
nuclear@14 126 #define CTMEXPORT
nuclear@14 127 #else
nuclear@14 128 #if defined(OPENCTM_BUILD)
nuclear@14 129 #define CTMEXPORT __declspec(dllexport)
nuclear@14 130 #else
nuclear@14 131 #define CTMEXPORT __declspec(dllimport)
nuclear@14 132 #endif
nuclear@14 133 #endif
nuclear@14 134 #if defined(__MINGW32__)
nuclear@14 135 #define CTMCALL __attribute__ ((__stdcall__))
nuclear@14 136 #elif (defined(_M_MRX000) || defined(_M_IX86) || defined(_M_ALPHA) || defined(_M_PPC)) && !defined(MIDL_PASS)
nuclear@14 137 #define CTMCALL __stdcall
nuclear@14 138 #else
nuclear@14 139 #define CTMCALL
nuclear@14 140 #endif
nuclear@14 141 #else
nuclear@14 142 // Unix
nuclear@14 143 #if !defined(OPENCTM_STATIC) && !defined(OPENCTM_BUILD)
nuclear@14 144 #define CTMEXPORT extern
nuclear@14 145 #else
nuclear@14 146 #if defined(OPENCTM_BUILD) && defined(__GNUC__) && (__GNUC__ >= 4)
nuclear@14 147 #define CTMEXPORT __attribute__ ((visibility("default")))
nuclear@14 148 #else
nuclear@14 149 #define CTMEXPORT
nuclear@14 150 #endif
nuclear@14 151 #endif
nuclear@14 152 #define CTMCALL
nuclear@14 153 #endif
nuclear@14 154
nuclear@14 155
nuclear@14 156 // Get system specific type definitions for sized integers. We use the C99
nuclear@14 157 // standard stdint.h for this.
nuclear@14 158 #ifdef _MSC_VER
nuclear@14 159 // MS Visual Studio does not support C99
nuclear@14 160 typedef int int32_t;
nuclear@14 161 typedef unsigned int uint32_t;
nuclear@14 162 #else
nuclear@14 163 #include <stdint.h>
nuclear@14 164 #endif
nuclear@14 165
nuclear@14 166
nuclear@14 167 /// OpenCTM API version (1.0).
nuclear@14 168 #define CTM_API_VERSION 0x00000100
nuclear@14 169
nuclear@14 170 /// Boolean TRUE.
nuclear@14 171 #define CTM_TRUE 1
nuclear@14 172
nuclear@14 173 /// Boolean FALSE.
nuclear@14 174 #define CTM_FALSE 0
nuclear@14 175
nuclear@14 176 /// Single precision floating point type (IEEE 754 32 bits wide).
nuclear@14 177 typedef float CTMfloat;
nuclear@14 178
nuclear@14 179 /// Signed integer (32 bits wide).
nuclear@14 180 typedef int32_t CTMint;
nuclear@14 181
nuclear@14 182 /// Unsigned integer (32 bits wide).
nuclear@14 183 typedef uint32_t CTMuint;
nuclear@14 184
nuclear@14 185 /// OpenCTM context handle.
nuclear@14 186 typedef void * CTMcontext;
nuclear@14 187
nuclear@14 188 /// OpenCTM specific enumerators.
nuclear@14 189 /// @note For the information query functions, it is an error to query a value
nuclear@14 190 /// of the wrong type (e.g. to query a string value with the
nuclear@14 191 /// ctmGetInteger() function).
nuclear@14 192 typedef enum {
nuclear@14 193 // Error codes (see ctmGetError())
nuclear@14 194 CTM_NONE = 0x0000, ///< No error has occured (everything is OK).
nuclear@14 195 /// Also used as an error return value for
nuclear@14 196 /// functions that should return a CTMenum
nuclear@14 197 /// value.
nuclear@14 198 CTM_INVALID_CONTEXT = 0x0001, ///< The OpenCTM context was invalid (e.g. NULL).
nuclear@14 199 CTM_INVALID_ARGUMENT = 0x0002, ///< A function argument was invalid.
nuclear@14 200 CTM_INVALID_OPERATION = 0x0003, ///< The operation is not allowed.
nuclear@14 201 CTM_INVALID_MESH = 0x0004, ///< The mesh was invalid (e.g. no vertices).
nuclear@14 202 CTM_OUT_OF_MEMORY = 0x0005, ///< Not enough memory to proceed.
nuclear@14 203 CTM_FILE_ERROR = 0x0006, ///< File I/O error.
nuclear@14 204 CTM_BAD_FORMAT = 0x0007, ///< File format error (e.g. unrecognized format or corrupted file).
nuclear@14 205 CTM_LZMA_ERROR = 0x0008, ///< An error occured within the LZMA library.
nuclear@14 206 CTM_INTERNAL_ERROR = 0x0009, ///< An internal error occured (indicates a bug).
nuclear@14 207 CTM_UNSUPPORTED_FORMAT_VERSION = 0x000A, ///< Unsupported file format version.
nuclear@14 208
nuclear@14 209 // OpenCTM context modes
nuclear@14 210 CTM_IMPORT = 0x0101, ///< The OpenCTM context will be used for importing data.
nuclear@14 211 CTM_EXPORT = 0x0102, ///< The OpenCTM context will be used for exporting data.
nuclear@14 212
nuclear@14 213 // Compression methods
nuclear@14 214 CTM_METHOD_RAW = 0x0201, ///< Just store the raw data.
nuclear@14 215 CTM_METHOD_MG1 = 0x0202, ///< Lossless compression (floating point).
nuclear@14 216 CTM_METHOD_MG2 = 0x0203, ///< Lossless compression (fixed point).
nuclear@14 217
nuclear@14 218 // Context queries
nuclear@14 219 CTM_VERTEX_COUNT = 0x0301, ///< Number of vertices in the mesh (integer).
nuclear@14 220 CTM_TRIANGLE_COUNT = 0x0302, ///< Number of triangles in the mesh (integer).
nuclear@14 221 CTM_HAS_NORMALS = 0x0303, ///< CTM_TRUE if the mesh has normals (integer).
nuclear@14 222 CTM_UV_MAP_COUNT = 0x0304, ///< Number of UV coordinate sets (integer).
nuclear@14 223 CTM_ATTRIB_MAP_COUNT = 0x0305, ///< Number of custom attribute sets (integer).
nuclear@14 224 CTM_VERTEX_PRECISION = 0x0306, ///< Vertex precision - for MG2 (float).
nuclear@14 225 CTM_NORMAL_PRECISION = 0x0307, ///< Normal precision - for MG2 (float).
nuclear@14 226 CTM_COMPRESSION_METHOD = 0x0308, ///< Compression method (integer).
nuclear@14 227 CTM_FILE_COMMENT = 0x0309, ///< File comment (string).
nuclear@14 228
nuclear@14 229 // UV/attribute map queries
nuclear@14 230 CTM_NAME = 0x0501, ///< Unique name (UV/attrib map string).
nuclear@14 231 CTM_FILE_NAME = 0x0502, ///< File name reference (UV map string).
nuclear@14 232 CTM_PRECISION = 0x0503, ///< Value precision (UV/attrib map float).
nuclear@14 233
nuclear@14 234 // Array queries
nuclear@14 235 CTM_INDICES = 0x0601, ///< Triangle indices (integer array).
nuclear@14 236 CTM_VERTICES = 0x0602, ///< Vertex point coordinates (float array).
nuclear@14 237 CTM_NORMALS = 0x0603, ///< Per vertex normals (float array).
nuclear@14 238 CTM_UV_MAP_1 = 0x0700, ///< Per vertex UV map 1 (float array).
nuclear@14 239 CTM_UV_MAP_2 = 0x0701, ///< Per vertex UV map 2 (float array).
nuclear@14 240 CTM_UV_MAP_3 = 0x0702, ///< Per vertex UV map 3 (float array).
nuclear@14 241 CTM_UV_MAP_4 = 0x0703, ///< Per vertex UV map 4 (float array).
nuclear@14 242 CTM_UV_MAP_5 = 0x0704, ///< Per vertex UV map 5 (float array).
nuclear@14 243 CTM_UV_MAP_6 = 0x0705, ///< Per vertex UV map 6 (float array).
nuclear@14 244 CTM_UV_MAP_7 = 0x0706, ///< Per vertex UV map 7 (float array).
nuclear@14 245 CTM_UV_MAP_8 = 0x0707, ///< Per vertex UV map 8 (float array).
nuclear@14 246 CTM_ATTRIB_MAP_1 = 0x0800, ///< Per vertex attribute map 1 (float array).
nuclear@14 247 CTM_ATTRIB_MAP_2 = 0x0801, ///< Per vertex attribute map 2 (float array).
nuclear@14 248 CTM_ATTRIB_MAP_3 = 0x0802, ///< Per vertex attribute map 3 (float array).
nuclear@14 249 CTM_ATTRIB_MAP_4 = 0x0803, ///< Per vertex attribute map 4 (float array).
nuclear@14 250 CTM_ATTRIB_MAP_5 = 0x0804, ///< Per vertex attribute map 5 (float array).
nuclear@14 251 CTM_ATTRIB_MAP_6 = 0x0805, ///< Per vertex attribute map 6 (float array).
nuclear@14 252 CTM_ATTRIB_MAP_7 = 0x0806, ///< Per vertex attribute map 7 (float array).
nuclear@14 253 CTM_ATTRIB_MAP_8 = 0x0807 ///< Per vertex attribute map 8 (float array).
nuclear@14 254 } CTMenum;
nuclear@14 255
nuclear@14 256 /// Stream read() function pointer.
nuclear@14 257 /// @param[in] aBuf Pointer to the memory buffer to which data should be read.
nuclear@14 258 /// @param[in] aCount The number of bytes to read.
nuclear@14 259 /// @param[in] aUserData The custom user data that was passed to the
nuclear@14 260 /// ctmLoadCustom() function.
nuclear@14 261 /// @return The number of bytes actually read (if this is less than aCount, it
nuclear@14 262 /// indicates that an error occured or the end of file was reached
nuclear@14 263 /// before all bytes were read).
nuclear@14 264 typedef CTMuint (CTMCALL * CTMreadfn)(void * aBuf, CTMuint aCount, void * aUserData);
nuclear@14 265
nuclear@14 266 /// Stream write() function pointer.
nuclear@14 267 /// @param[in] aBuf Pointer to the memory buffer from which data should be written.
nuclear@14 268 /// @param[in] aCount The number of bytes to write.
nuclear@14 269 /// @param[in] aUserData The custom user data that was passed to the
nuclear@14 270 /// ctmSaveCustom() function.
nuclear@14 271 /// @return The number of bytes actually written (if this is less than aCount, it
nuclear@14 272 /// indicates that an error occured).
nuclear@14 273 typedef CTMuint (CTMCALL * CTMwritefn)(const void * aBuf, CTMuint aCount, void * aUserData);
nuclear@14 274
nuclear@14 275 /// Create a new OpenCTM context. The context is used for all subsequent
nuclear@14 276 /// OpenCTM function calls. Several contexts can coexist at the same time.
nuclear@14 277 /// @param[in] aMode An OpenCTM context mode. Set this to CTM_IMPORT if the
nuclear@14 278 /// context will be used for importing data, or set it to CTM_EXPORT
nuclear@14 279 /// if it will be used for exporting data.
nuclear@14 280 /// @return An OpenCTM context handle (or NULL if no context could be created).
nuclear@14 281 CTMEXPORT CTMcontext CTMCALL ctmNewContext(CTMenum aMode);
nuclear@14 282
nuclear@14 283 /// Free an OpenCTM context.
nuclear@14 284 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 285 /// ctmNewContext().
nuclear@14 286 /// @see ctmNewContext()
nuclear@14 287 CTMEXPORT void CTMCALL ctmFreeContext(CTMcontext aContext);
nuclear@14 288
nuclear@14 289 /// Returns the latest error. Calling this function will return the last
nuclear@14 290 /// produced error code, or CTM_NO_ERROR (zero) if no error has occured since
nuclear@14 291 /// the last call to ctmGetError(). When this function is called, the internal
nuclear@14 292 /// error varibale will be reset to CTM_NONE.
nuclear@14 293 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 294 /// ctmNewContext().
nuclear@14 295 /// @return An OpenCTM error code.
nuclear@14 296 /// @see CTMenum
nuclear@14 297 CTMEXPORT CTMenum CTMCALL ctmGetError(CTMcontext aContext);
nuclear@14 298
nuclear@14 299 /// Converts an OpenCTM error code to a zero-terminated string.
nuclear@14 300 /// @param[in] aError An OpenCTM error code, as returned by ctmGetError().
nuclear@14 301 /// @return A zero terminated string that describes the error. For instance,
nuclear@14 302 /// if \c aError is CTM_INVALID_OPERATION, then the return value will
nuclear@14 303 /// be "CTM_INVALID_OPERATION".
nuclear@14 304 /// @see CTMenum
nuclear@14 305 CTMEXPORT const char * CTMCALL ctmErrorString(CTMenum aError);
nuclear@14 306
nuclear@14 307 /// Get information about an OpenCTM context.
nuclear@14 308 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 309 /// ctmNewContext().
nuclear@14 310 /// @param[in] aProperty Which property to return.
nuclear@14 311 /// @return An integer value, representing the OpenCTM context property given
nuclear@14 312 /// by \c aProperty.
nuclear@14 313 /// @see CTMenum
nuclear@14 314 CTMEXPORT CTMuint CTMCALL ctmGetInteger(CTMcontext aContext, CTMenum aProperty);
nuclear@14 315
nuclear@14 316 /// Get information about an OpenCTM context.
nuclear@14 317 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 318 /// ctmNewContext().
nuclear@14 319 /// @param[in] aProperty Which property to return.
nuclear@14 320 /// @return A floating point value, representing the OpenCTM context property
nuclear@14 321 /// given by \c aProperty.
nuclear@14 322 /// @see CTMenum
nuclear@14 323 CTMEXPORT CTMfloat CTMCALL ctmGetFloat(CTMcontext aContext, CTMenum aProperty);
nuclear@14 324
nuclear@14 325 /// Get an integer array from an OpenCTM context.
nuclear@14 326 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 327 /// ctmNewContext().
nuclear@14 328 /// @param[in] aProperty Which array to return.
nuclear@14 329 /// @return An integer array. If the requested array does not exist, or
nuclear@14 330 /// if \c aProperty does not indicate an integer array, the function
nuclear@14 331 /// returns NULL.
nuclear@14 332 /// @note The array is only valid as long as the OpenCTM context is valid, or
nuclear@14 333 /// until the corresponding array changes within the OpenCTM context.
nuclear@14 334 /// Trying to access an invalid array will result in undefined
nuclear@14 335 /// behaviour. Therefor it is recommended that the array is copied to
nuclear@14 336 /// a new variable if it is to be used other than directly after the call
nuclear@14 337 /// to ctmGetIntegerArray().
nuclear@14 338 /// @see CTMenum
nuclear@14 339 CTMEXPORT const CTMuint * CTMCALL ctmGetIntegerArray(CTMcontext aContext,
nuclear@14 340 CTMenum aProperty);
nuclear@14 341
nuclear@14 342 /// Get a floating point array from an OpenCTM context.
nuclear@14 343 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 344 /// ctmNewContext().
nuclear@14 345 /// @param[in] aProperty Which array to return.
nuclear@14 346 /// @return A floating point array. If the requested array does not exist, or
nuclear@14 347 /// if \c aProperty does not indicate a float array, the function
nuclear@14 348 /// returns NULL.
nuclear@14 349 /// @note The array is only valid as long as the OpenCTM context is valid, or
nuclear@14 350 /// until the corresponding array changes within the OpenCTM context.
nuclear@14 351 /// Trying to access an invalid array will result in undefined
nuclear@14 352 /// behaviour. Therefor it is recommended that the array is copied to
nuclear@14 353 /// a new variable if it is to be used other than directly after the call
nuclear@14 354 /// to ctmGetFloatArray().
nuclear@14 355 /// @see CTMenum
nuclear@14 356 CTMEXPORT const CTMfloat * CTMCALL ctmGetFloatArray(CTMcontext aContext,
nuclear@14 357 CTMenum aProperty);
nuclear@14 358
nuclear@14 359 /// Get a reference to the named UV map.
nuclear@14 360 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 361 /// ctmNewContext().
nuclear@14 362 /// @param[in] aName The name of the UV map that should be returned.
nuclear@14 363 /// @return A reference to a UV map. If the UV map was found, a value of
nuclear@14 364 /// CTM_UV_MAP_1 or higher is returned, otherwise CTM_NONE is
nuclear@14 365 /// returned.
nuclear@14 366 CTMEXPORT CTMenum CTMCALL ctmGetNamedUVMap(CTMcontext aContext,
nuclear@14 367 const char * aName);
nuclear@14 368
nuclear@14 369 /// Get information about a UV map.
nuclear@14 370 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 371 /// ctmNewContext().
nuclear@14 372 /// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher).
nuclear@14 373 /// @param[in] aProperty Which UV map property to return.
nuclear@14 374 /// @return A string value, representing the UV map property given
nuclear@14 375 /// by \c aProperty.
nuclear@14 376 /// @note The string is only valid as long as the UV map within the OpenCTM
nuclear@14 377 /// context is valid. Trying to access an invalid string will result in
nuclear@14 378 /// undefined behaviour. Therefor it is recommended that the string is
nuclear@14 379 /// copied to a new variable if it is to be used other than directly after
nuclear@14 380 /// the call to ctmGetUVMapString().
nuclear@14 381 /// @see CTMenum
nuclear@14 382 CTMEXPORT const char * CTMCALL ctmGetUVMapString(CTMcontext aContext,
nuclear@14 383 CTMenum aUVMap, CTMenum aProperty);
nuclear@14 384
nuclear@14 385 /// Get information about a UV map.
nuclear@14 386 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 387 /// ctmNewContext().
nuclear@14 388 /// @param[in] aUVMap Which UV map to query (CTM_UV_MAP_1 or higher).
nuclear@14 389 /// @param[in] aProperty Which UV map property to return.
nuclear@14 390 /// @return A floating point value, representing the UV map property given
nuclear@14 391 /// by \c aProperty.
nuclear@14 392 /// @see CTMenum
nuclear@14 393 CTMEXPORT CTMfloat CTMCALL ctmGetUVMapFloat(CTMcontext aContext,
nuclear@14 394 CTMenum aUVMap, CTMenum aProperty);
nuclear@14 395
nuclear@14 396 /// Get a reference to the named vertex attribute map.
nuclear@14 397 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 398 /// ctmNewContext().
nuclear@14 399 /// @param[in] aName The name of the attribute map that should be returned.
nuclear@14 400 /// @return A reference to an attribute map. If the attribute map was found,
nuclear@14 401 /// a value of CTM_ATTRIB_MAP_1 or higher is returned, otherwise
nuclear@14 402 /// CTM_NONE is returned.
nuclear@14 403 CTMEXPORT CTMenum CTMCALL ctmGetNamedAttribMap(CTMcontext aContext,
nuclear@14 404 const char * aName);
nuclear@14 405
nuclear@14 406 /// Get information about a vertex attribute map.
nuclear@14 407 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 408 /// ctmNewContext().
nuclear@14 409 /// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1
nuclear@14 410 /// or higher).
nuclear@14 411 /// @param[in] aProperty Which vertex attribute map property to return.
nuclear@14 412 /// @return A string value, representing the vertex attribute map property given
nuclear@14 413 /// by \c aProperty.
nuclear@14 414 /// @note The string is only valid as long as the vertex attribute map within
nuclear@14 415 /// the OpenCTM context is valid. Trying to access an invalid string will
nuclear@14 416 /// result in undefined behaviour. Therefor it is recommended that the
nuclear@14 417 /// string is copied to a new variable if it is to be used other than
nuclear@14 418 /// directly after the call to ctmGetAttribMapString().
nuclear@14 419 /// @see CTMenum
nuclear@14 420 CTMEXPORT const char * CTMCALL ctmGetAttribMapString(CTMcontext aContext,
nuclear@14 421 CTMenum aAttribMap, CTMenum aProperty);
nuclear@14 422
nuclear@14 423 /// Get information about a vertex attribute map.
nuclear@14 424 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 425 /// ctmNewContext().
nuclear@14 426 /// @param[in] aAttribMap Which vertex attribute map to query (CTM_ATTRIB_MAP_1
nuclear@14 427 /// or higher).
nuclear@14 428 /// @param[in] aProperty Which vertex attribute map property to return.
nuclear@14 429 /// @return A floating point value, representing the vertex attribute map
nuclear@14 430 /// property given by \c aProperty.
nuclear@14 431 /// @see CTMenum
nuclear@14 432 CTMEXPORT CTMfloat CTMCALL ctmGetAttribMapFloat(CTMcontext aContext,
nuclear@14 433 CTMenum aAttribMap, CTMenum aProperty);
nuclear@14 434
nuclear@14 435 /// Get information about an OpenCTM context.
nuclear@14 436 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 437 /// ctmNewContext().
nuclear@14 438 /// @param[in] aProperty Which property to return.
nuclear@14 439 /// @return A string value, representing the OpenCTM context property given
nuclear@14 440 /// by \c aProperty.
nuclear@14 441 /// @note The string is only valid as long as the OpenCTM context is valid, or
nuclear@14 442 /// until the corresponding string changes within the OpenCTM context
nuclear@14 443 /// (e.g. calling ctmFileComment() invalidates the CTM_FILE_COMMENT
nuclear@14 444 /// string). Trying to access an invalid string will result in undefined
nuclear@14 445 /// behaviour. Therefor it is recommended that the string is copied to
nuclear@14 446 /// a new variable if it is to be used other than directly after the call
nuclear@14 447 /// to ctmGetString().
nuclear@14 448 /// @see CTMenum
nuclear@14 449 CTMEXPORT const char * CTMCALL ctmGetString(CTMcontext aContext,
nuclear@14 450 CTMenum aProperty);
nuclear@14 451
nuclear@14 452 /// Set which compression method to use for the given OpenCTM context.
nuclear@14 453 /// The selected compression method will be used when calling the ctmSave()
nuclear@14 454 /// function.
nuclear@14 455 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 456 /// ctmNewContext().
nuclear@14 457 /// @param[in] aMethod Which compression method to use: CTM_METHOD_RAW,
nuclear@14 458 /// CTM_METHOD_MG1 or CTM_METHOD_MG2 (the default method is
nuclear@14 459 /// CTM_METHOD_MG1).
nuclear@14 460 /// @see CTM_METHOD_RAW, CTM_METHOD_MG1, CTM_METHOD_MG2
nuclear@14 461 CTMEXPORT void CTMCALL ctmCompressionMethod(CTMcontext aContext,
nuclear@14 462 CTMenum aMethod);
nuclear@14 463
nuclear@14 464 /// Set which LZMA compression level to use for the given OpenCTM context.
nuclear@14 465 /// The compression level can be between 0 (fastest) and 9 (best). The higher
nuclear@14 466 /// the compression level, the more memory is required for compression and
nuclear@14 467 /// decompression. The default compression level is 1.
nuclear@14 468 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 469 /// ctmNewContext().
nuclear@14 470 /// @param[in] aLevel Which compression level to use (0 to 9).
nuclear@14 471 CTMEXPORT void CTMCALL ctmCompressionLevel(CTMcontext aContext,
nuclear@14 472 CTMuint aLevel);
nuclear@14 473
nuclear@14 474 /// Set the vertex coordinate precision (only used by the MG2 compression
nuclear@14 475 /// method).
nuclear@14 476 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 477 /// ctmNewContext().
nuclear@14 478 /// @param[in] aPrecision Fixed point precision. For instance, if this value is
nuclear@14 479 /// 0.001, all vertex coordinates will be rounded to three decimals.
nuclear@14 480 /// The default vertex coordinate precision is 2^-10 ~= 0.00098.
nuclear@14 481 CTMEXPORT void CTMCALL ctmVertexPrecision(CTMcontext aContext,
nuclear@14 482 CTMfloat aPrecision);
nuclear@14 483
nuclear@14 484 /// Set the vertex coordinate precision, relative to the mesh dimensions (only
nuclear@14 485 /// used by the MG2 compression method).
nuclear@14 486 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 487 /// ctmNewContext().
nuclear@14 488 /// @param[in] aRelPrecision Relative precision. This factor is multiplied by the
nuclear@14 489 /// average triangle edge length in the mesh in order to obtain the
nuclear@14 490 /// final, fixed point precision. For instance, if aRelPrecision is
nuclear@14 491 /// 0.01, and the average edge length is 3.7, then the fixed point
nuclear@14 492 /// precision is set to 0.037.
nuclear@14 493 /// @note The mesh must have been defined using the ctmDefineMesh() function
nuclear@14 494 /// before calling this function.
nuclear@14 495 /// @see ctmVertexPrecision().
nuclear@14 496 CTMEXPORT void CTMCALL ctmVertexPrecisionRel(CTMcontext aContext,
nuclear@14 497 CTMfloat aRelPrecision);
nuclear@14 498
nuclear@14 499 /// Set the normal precision (only used by the MG2 compression method). The
nuclear@14 500 /// normal is represented in spherical coordinates in the MG2 compression
nuclear@14 501 /// method, and the normal precision controls the angular and radial resolution.
nuclear@14 502 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 503 /// ctmNewContext().
nuclear@14 504 /// @param[in] aPrecision Fixed point precision. For the angular information,
nuclear@14 505 /// this value represents the angular precision. For the radial
nuclear@14 506 /// information, this value is the linear resolution. For instance,
nuclear@14 507 /// 0.01 means that the circle is divided into 100 steps, and the
nuclear@14 508 /// normal magnitude is rounded to 2 decimals. The default normal
nuclear@14 509 /// precision is 2^-8 ~= 0.0039.
nuclear@14 510 CTMEXPORT void CTMCALL ctmNormalPrecision(CTMcontext aContext,
nuclear@14 511 CTMfloat aPrecision);
nuclear@14 512
nuclear@14 513 /// Set the coordinate precision for the specified UV map (only used by the
nuclear@14 514 /// MG2 compression method).
nuclear@14 515 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 516 /// ctmNewContext().
nuclear@14 517 /// @param[in] aUVMap A UV map specifier for a defined UV map
nuclear@14 518 /// (CTM_UV_MAP_1, ...).
nuclear@14 519 /// @param[in] aPrecision Fixed point precision. For instance, if this value is
nuclear@14 520 /// 0.001, all UV coordinates will be rounded to three decimals.
nuclear@14 521 /// The default UV coordinate precision is 2^-12 ~= 0.00024.
nuclear@14 522 /// @see ctmAddUVMap().
nuclear@14 523 CTMEXPORT void CTMCALL ctmUVCoordPrecision(CTMcontext aContext,
nuclear@14 524 CTMenum aUVMap, CTMfloat aPrecision);
nuclear@14 525
nuclear@14 526 /// Set the attribute value precision for the specified attribute map (only
nuclear@14 527 /// used by the MG2 compression method).
nuclear@14 528 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 529 /// ctmNewContext().
nuclear@14 530 /// @param[in] aAttribMap An attribute map specifier for a defined attribute map
nuclear@14 531 /// (CTM_ATTRIB_MAP_1, ...).
nuclear@14 532 /// @param[in] aPrecision Fixed point precision. For instance, if this value is
nuclear@14 533 /// 0.001, all attribute values will be rounded to three decimals.
nuclear@14 534 /// If the attributes represent integer values, set the precision
nuclear@14 535 /// to 1.0. The default attribute precision is 2^-8 ~= 0.0039.
nuclear@14 536 /// @see ctmAddAttribMap().
nuclear@14 537 CTMEXPORT void CTMCALL ctmAttribPrecision(CTMcontext aContext,
nuclear@14 538 CTMenum aAttribMap, CTMfloat aPrecision);
nuclear@14 539
nuclear@14 540 /// Set the file comment for the given OpenCTM context.
nuclear@14 541 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 542 /// ctmNewContext().
nuclear@14 543 /// @param[in] aFileComment The file comment (zero terminated UTF-8 string).
nuclear@14 544 CTMEXPORT void CTMCALL ctmFileComment(CTMcontext aContext,
nuclear@14 545 const char * aFileComment);
nuclear@14 546
nuclear@14 547 /// Define a triangle mesh.
nuclear@14 548 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 549 /// ctmNewContext().
nuclear@14 550 /// @param[in] aVertices An array of vertices (three consecutive floats make
nuclear@14 551 /// one vertex).
nuclear@14 552 /// @param[in] aVertexCount The number of vertices in \c aVertices (and
nuclear@14 553 /// optionally \c aTexCoords).
nuclear@14 554 /// @param[in] aIndices An array of vertex indices (three consecutive integers
nuclear@14 555 /// make one triangle).
nuclear@14 556 /// @param[in] aTriangleCount The number of triangles in \c aIndices (there
nuclear@14 557 /// must be exactly 3 x \c aTriangleCount indices in \c aIndices).
nuclear@14 558 /// @param[in] aNormals An array of per-vertex normals (or NULL if there are
nuclear@14 559 /// no normals). Each normal is made up by three consecutive floats,
nuclear@14 560 /// and there must be \c aVertexCount normals.
nuclear@14 561 /// @see ctmAddUVMap(), ctmAddAttribMap(), ctmSave(), ctmSaveCustom().
nuclear@14 562 CTMEXPORT void CTMCALL ctmDefineMesh(CTMcontext aContext,
nuclear@14 563 const CTMfloat * aVertices, CTMuint aVertexCount, const CTMuint * aIndices,
nuclear@14 564 CTMuint aTriangleCount, const CTMfloat * aNormals);
nuclear@14 565
nuclear@14 566 /// Define a UV map. There can be several UV maps in a mesh. A UV map is
nuclear@14 567 /// typically used for 2D texture mapping.
nuclear@14 568 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 569 /// ctmNewContext().
nuclear@14 570 /// @param[in] aUVCoords An array of UV coordinates. Each UV coordinate is made
nuclear@14 571 /// up by two consecutive floats, and there must be as many
nuclear@14 572 /// coordinates as there are vertices in the mesh.
nuclear@14 573 /// @param[in] aName A unique name for this UV map (zero terminated UTF-8
nuclear@14 574 /// string).
nuclear@14 575 /// @param[in] aFileName A reference to a image file (zero terminated
nuclear@14 576 /// UTF-8 string). If no file name reference exists, pass NULL.
nuclear@14 577 /// @return A UV map index (CTM_UV_MAP_1 and higher). If the function
nuclear@14 578 /// failed, it will return the zero valued CTM_NONE (use ctmGetError()
nuclear@14 579 /// to determine the cause of the error).
nuclear@14 580 /// @note A triangle mesh must have been defined before calling this function,
nuclear@14 581 /// since the number of vertices is defined by the triangle mesh.
nuclear@14 582 /// @see ctmDefineMesh().
nuclear@14 583 CTMEXPORT CTMenum CTMCALL ctmAddUVMap(CTMcontext aContext,
nuclear@14 584 const CTMfloat * aUVCoords, const char * aName, const char * aFileName);
nuclear@14 585
nuclear@14 586 /// Define a custom vertex attribute map. Custom vertex attributes can be used
nuclear@14 587 /// for defining special per-vertex attributes, such as color, weight, ambient
nuclear@14 588 /// occlusion factor, etc.
nuclear@14 589 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 590 /// ctmNewContext().
nuclear@14 591 /// @param[in] aAttribValues An array of attribute values. Each attribute value
nuclear@14 592 /// is made up by four consecutive floats, and there must be as many
nuclear@14 593 /// values as there are vertices in the mesh.
nuclear@14 594 /// @param[in] aName A unique name for this attribute map (zero terminated UTF-8
nuclear@14 595 /// string).
nuclear@14 596 /// @return A attribute map index (CTM_ATTRIB_MAP_1 and higher). If the function
nuclear@14 597 /// failed, it will return the zero valued CTM_NONE (use ctmGetError()
nuclear@14 598 /// to determine the cause of the error).
nuclear@14 599 /// @note A triangle mesh must have been defined before calling this function,
nuclear@14 600 /// since the number of vertices is defined by the triangle mesh.
nuclear@14 601 /// @see ctmDefineMesh().
nuclear@14 602 CTMEXPORT CTMenum CTMCALL ctmAddAttribMap(CTMcontext aContext,
nuclear@14 603 const CTMfloat * aAttribValues, const char * aName);
nuclear@14 604
nuclear@14 605 /// Load an OpenCTM format file into the context. The mesh data can be retrieved
nuclear@14 606 /// with the various ctmGet functions.
nuclear@14 607 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 608 /// ctmNewContext().
nuclear@14 609 /// @param[in] aFileName The name of the file to be loaded.
nuclear@14 610 CTMEXPORT void CTMCALL ctmLoad(CTMcontext aContext, const char * aFileName);
nuclear@14 611
nuclear@14 612 /// Load an OpenCTM format file using a custom stream read function. The mesh
nuclear@14 613 /// data can be retrieved with the various ctmGet functions.
nuclear@14 614 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 615 /// ctmNewContext().
nuclear@14 616 /// @param[in] aReadFn Pointer to a custom stream read function.
nuclear@14 617 /// @param[in] aUserData Custom user data, which can be a C language FILE
nuclear@14 618 /// handle, C++ istream object, or a custom object pointer
nuclear@14 619 /// of any type. The user data pointer will be passed to the
nuclear@14 620 /// custom stream read function.
nuclear@14 621 /// @see CTMreadfn.
nuclear@14 622 CTMEXPORT void CTMCALL ctmLoadCustom(CTMcontext aContext, CTMreadfn aReadFn,
nuclear@14 623 void * aUserData);
nuclear@14 624
nuclear@14 625 /// Save an OpenCTM format file. The mesh must have been defined by
nuclear@14 626 /// ctmDefineMesh().
nuclear@14 627 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 628 /// ctmNewContext().
nuclear@14 629 /// @param[in] aFileName The name of the file to be saved.
nuclear@14 630 CTMEXPORT void CTMCALL ctmSave(CTMcontext aContext, const char * aFileName);
nuclear@14 631
nuclear@14 632 /// Save an OpenCTM format file using a custom stream write function. The mesh
nuclear@14 633 /// must have been defined by ctmDefineMesh().
nuclear@14 634 /// @param[in] aContext An OpenCTM context that has been created by
nuclear@14 635 /// ctmNewContext().
nuclear@14 636 /// @param[in] aWriteFn Pointer to a custom stream write function.
nuclear@14 637 /// @param[in] aUserData Custom user data, which can be a C language FILE
nuclear@14 638 /// handle, C++ ostream object, or a custom object pointer
nuclear@14 639 /// of any type. The user data pointer will be passed to the
nuclear@14 640 /// custom stream write function.
nuclear@14 641 /// @see CTMwritefn.
nuclear@14 642 CTMEXPORT void CTMCALL ctmSaveCustom(CTMcontext aContext, CTMwritefn aWriteFn,
nuclear@14 643 void * aUserData);
nuclear@14 644
nuclear@14 645 #ifdef __cplusplus
nuclear@14 646 }
nuclear@14 647 #endif
nuclear@14 648
nuclear@14 649
nuclear@14 650 // C++ extensions to the API (to disable C++ extensions, define OPENCTM_NO_CPP)
nuclear@14 651 #if defined(__cplusplus) && !defined(OPENCTM_NO_CPP)
nuclear@14 652 #include "openctmpp.h"
nuclear@14 653 #endif
nuclear@14 654
nuclear@14 655 #endif // __OPENCTM_H_