scratchfoundation/bgfx
1
0
Fork 0
mirror of https://github.com/scratchfoundation/bgfx.git synced 2024-11-29 11:05:36 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
bgfx/3rdparty/openctm/lib/openctm.h
bkaradzic cfac3feb85 Added more examples.
2012-10-07 20:41:18 -07:00

655 lines
30 KiB
C
Raw Blame History

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