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