caiyu/gmio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

gmio_amf: more documentation

Browse Source
This commit is contained in:
Hugues Delorme 2017-03-01 10:31:50 +01:00
parent 5214718a2b
commit 5f31fcddf7
12 changed files with 170 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Doxyfile.cmake
View File

@ -451,7 +451,7 @@ INLINE_INFO = YES
# alphabetically by member name. If set to NO the members will appear in # alphabetically by member name. If set to NO the members will appear in
# declaration order. # declaration order.
SORT_MEMBER_DOCS = YES SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
# brief documentation of file, namespace and class members alphabetically # brief documentation of file, namespace and class members alphabetically

204
src/gmio_amf/amf_document.h
View File

@ -44,14 +44,12 @@
#include <stddef.h> #include <stddef.h>
struct gmio_amf_metadata struct gmio_amf_metadata {
{
const char* type; /*!< UTF8-encoded */ const char* type; /*!< UTF8-encoded */
const char* data; /*!< UTF8-encoded */ const char* data; /*!< UTF8-encoded */
}; };
struct gmio_amf_color struct gmio_amf_color {
{
double r; /*!< Red channel in [0,1] */ double r; /*!< Red channel in [0,1] */
double g; /*!< Green channel in [0,1] */ double g; /*!< Green channel in [0,1] */
double b; /*!< Blue channel in [0,1] */ double b; /*!< Blue channel in [0,1] */
@ -62,8 +60,7 @@ struct gmio_amf_color
const char* a_formula; const char* a_formula;
}; };
struct gmio_amf_material struct gmio_amf_material {
{
uint32_t id; /* XML:integer */ uint32_t id; /* XML:integer */
struct gmio_amf_color color; struct gmio_amf_color color;
uint32_t composite_count; uint32_t composite_count;
@ -73,18 +70,15 @@ struct gmio_amf_material
/*! Proportion of the composition of another material /*! Proportion of the composition of another material
* *
* The proportion can be specified as a formula(with \c value_formula) or as a * The proportion can be specified as a formula(with \c value_formula) or as a
* constant mixing(with \c value). * constant mixing(with \c value) */
*/ struct gmio_amf_composite {
struct gmio_amf_composite
{
uint32_t materialid; /* XML:nonNegativeInteger, required */ uint32_t materialid; /* XML:nonNegativeInteger, required */
double value; /*!< governs the percent of material */ double value; /*!< Governs the percent of material */
const char* value_formula; const char* value_formula;
}; };
/*! Vertex within an AMF mesh */ /*! Vertex within an AMF mesh */
struct gmio_amf_vertex struct gmio_amf_vertex {
{
struct gmio_vec3d coords; struct gmio_vec3d coords;
bool has_normal; bool has_normal;
struct gmio_vec3d normal; /* XML:NegOneToOne: -1 <= coord <= 1 */ struct gmio_vec3d normal; /* XML:NegOneToOne: -1 <= coord <= 1 */
@ -94,8 +88,7 @@ struct gmio_amf_vertex
}; };
/*! Edge within an AMF mesh, for curved triangles */ /*! Edge within an AMF mesh, for curved triangles */
struct gmio_amf_edge struct gmio_amf_edge {
{
uint32_t v1; /* XML:nonNegativeInteger */ uint32_t v1; /* XML:nonNegativeInteger */
uint32_t v2; /* XML:nonNegativeInteger */ uint32_t v2; /* XML:nonNegativeInteger */
/* Direction vectors */ /* Direction vectors */
@ -103,8 +96,7 @@ struct gmio_amf_edge
struct gmio_vec3d d2; /* XML:NegOneToOne: -1 <= coord <= 1 */ struct gmio_vec3d d2; /* XML:NegOneToOne: -1 <= coord <= 1 */
}; };
struct gmio_amf_texmap struct gmio_amf_texmap {
{
uint32_t rtexid; /* XML:nonNegativeInteger */ uint32_t rtexid; /* XML:nonNegativeInteger */
uint32_t gtexid; /* XML:nonNegativeInteger */ uint32_t gtexid; /* XML:nonNegativeInteger */
uint32_t btexid; /* XML:nonNegativeInteger */ uint32_t btexid; /* XML:nonNegativeInteger */
@ -115,8 +107,7 @@ struct gmio_amf_texmap
struct gmio_vec3d wtex; /* XML:Coords : any value */ struct gmio_vec3d wtex; /* XML:Coords : any value */
}; };
struct gmio_amf_triangle struct gmio_amf_triangle {
{
uint32_t v1; /* XML:nonNegativeInteger */ uint32_t v1; /* XML:nonNegativeInteger */
uint32_t v2; /* XML:nonNegativeInteger */ uint32_t v2; /* XML:nonNegativeInteger */
uint32_t v3; /* XML:nonNegativeInteger */ uint32_t v3; /* XML:nonNegativeInteger */
@ -126,15 +117,13 @@ struct gmio_amf_triangle
struct gmio_amf_color color; /* XML:Color */ struct gmio_amf_color color; /* XML:Color */
}; };
enum gmio_amf_volume_type enum gmio_amf_volume_type {
{
GMIO_AMF_VOLUME_TYPE_OBJECT = 0, GMIO_AMF_VOLUME_TYPE_OBJECT = 0,
GMIO_AMF_VOLUME_TYPE_SUPPORT GMIO_AMF_VOLUME_TYPE_SUPPORT
}; };
/*! Volume within an AMF mesh */ /*! Volume within an AMF mesh */
struct gmio_amf_volume struct gmio_amf_volume {
{
uint32_t materialid; /* XML:nonNegativeInteger */ uint32_t materialid; /* XML:nonNegativeInteger */
enum gmio_amf_volume_type type; enum gmio_amf_volume_type type;
uint32_t triangle_count; /*!< Should be >= 4 */ uint32_t triangle_count; /*!< Should be >= 4 */
@ -143,15 +132,13 @@ struct gmio_amf_volume
struct gmio_amf_color color; /* XML:Color */ struct gmio_amf_color color; /* XML:Color */
}; };
struct gmio_amf_mesh struct gmio_amf_mesh {
{
uint32_t vertex_count; uint32_t vertex_count;
uint32_t edge_count; uint32_t edge_count;
uint32_t volume_count; uint32_t volume_count;
}; };
struct gmio_amf_object struct gmio_amf_object {
{
uint32_t id; /* XML:integer */ uint32_t id; /* XML:integer */
uint32_t mesh_count; uint32_t mesh_count;
uint32_t metadata_count; uint32_t metadata_count;
@ -159,8 +146,7 @@ struct gmio_amf_object
struct gmio_amf_color color; /* XML:Color */ struct gmio_amf_color color; /* XML:Color */
}; };
struct gmio_amf_constellation struct gmio_amf_constellation {
{
uint32_t id; /* XML:integer */ uint32_t id; /* XML:integer */
uint32_t instance_count; /*!< Should be >= 2 */ uint32_t instance_count; /*!< Should be >= 2 */
uint32_t metadata_count; uint32_t metadata_count;
@ -171,16 +157,14 @@ struct gmio_amf_instance
{ {
uint32_t objectid; /* XML:nonNegativeInteger */ uint32_t objectid; /* XML:nonNegativeInteger */
struct gmio_vec3d delta; /* Any value */ struct gmio_vec3d delta; /* Any value */
struct gmio_vec3d rot; /* XML:Degrees: -360 <= coord < 360 */ struct gmio_vec3d rot; /*!< Coordinates in degrees (-360 <= coord < 360) */
}; };
enum gmio_amf_texture_type enum gmio_amf_texture_type {
{
GMIO_AMF_TEXTURE_TYPE_GRAYSCALE GMIO_AMF_TEXTURE_TYPE_GRAYSCALE
}; };
struct gmio_amf_texture struct gmio_amf_texture {
{
uint32_t id; /* XML:integer */ uint32_t id; /* XML:integer */
uint32_t width; /* XML:nonNegativeInteger */ uint32_t width; /* XML:nonNegativeInteger */
uint32_t height; /* XML:nonNegativeInteger */ uint32_t height; /* XML:nonNegativeInteger */
@ -191,8 +175,7 @@ struct gmio_amf_texture
}; };
/*! Units supported by AMF */ /*! Units supported by AMF */
enum gmio_amf_unit enum gmio_amf_unit {
{
GMIO_AMF_UNIT_UNKNOWN, GMIO_AMF_UNIT_UNKNOWN,
GMIO_AMF_UNIT_MILLIMETER, GMIO_AMF_UNIT_MILLIMETER,
GMIO_AMF_UNIT_INCH, GMIO_AMF_UNIT_INCH,
@ -201,9 +184,8 @@ enum gmio_amf_unit
GMIO_AMF_UNIT_MICRON GMIO_AMF_UNIT_MICRON
}; };
/*! The direct elements of an AMF document(ie. inside <tt><amf>...</amf></tt>) */ /*! The direct elements of an AMF document(ie inside <tt><amf>...</amf></tt>) */
enum gmio_amf_document_element enum gmio_amf_document_element {
{
GMIO_AMF_DOCUMENT_ELEMENT_OBJECT, GMIO_AMF_DOCUMENT_ELEMENT_OBJECT,
GMIO_AMF_DOCUMENT_ELEMENT_MATERIAL, GMIO_AMF_DOCUMENT_ELEMENT_MATERIAL,
GMIO_AMF_DOCUMENT_ELEMENT_TEXTURE, GMIO_AMF_DOCUMENT_ELEMENT_TEXTURE,
@ -211,58 +193,59 @@ enum gmio_amf_document_element
GMIO_AMF_DOCUMENT_ELEMENT_METADATA GMIO_AMF_DOCUMENT_ELEMENT_METADATA
}; };
/*! The direct elements of an AMF mesh(ie. inside <tt><mesh>...</mesh></tt>) */ /*! The direct elements of an AMF mesh(ie inside <tt><mesh>...</mesh></tt>) */
enum gmio_amf_mesh_element enum gmio_amf_mesh_element {
{
GMIO_AMF_MESH_ELEMENT_VERTEX, GMIO_AMF_MESH_ELEMENT_VERTEX,
GMIO_AMF_MESH_ELEMENT_EDGE, GMIO_AMF_MESH_ELEMENT_EDGE,
GMIO_AMF_MESH_ELEMENT_VOLUME GMIO_AMF_MESH_ELEMENT_VOLUME
}; };
struct gmio_amf_object_mesh_element_index /*! Index of an element(vertex, edge or volume) within a mesh */
{ struct gmio_amf_object_mesh_element_index {
uint32_t object_index; uint32_t object_index; /*!< Index of the object that owns the mesh */
uint32_t mesh_index; uint32_t mesh_index; /*!< Index of the mesh that owns element */
uint32_t value; uint32_t value; /*!< Index of the inner element */
}; };
/* Note: version is 1.2 */ /*! Provides an interface for accessing the underlying(hidden) user AMF data
struct gmio_amf_document *
{ * \note version is 1.2
*/
struct gmio_amf_document {
/*! Opaque pointer on the user AMF document, passed as first argument to /*! Opaque pointer on the user AMF document, passed as first argument to
* hook functions */ * hook functions */
const void* cookie; const void* cookie;
enum gmio_amf_unit unit; enum gmio_amf_unit unit;
uint32_t object_count; /*!< Must be >= 1 */
/*! Number of objects in the document, must be >= 1 */
uint32_t object_count;
/*! Number of materials in the document */
uint32_t material_count; uint32_t material_count;
/*! Number of textures in the document */
uint32_t texture_count; uint32_t texture_count;
/*! Number of constellations in the document */
uint32_t constellation_count; uint32_t constellation_count;
/*! Number of direct metadata attached to the document */
uint32_t metadata_count; uint32_t metadata_count;
/*! Pointer on a function that retrieves the i-th document sub-element /*! Function that retrieves the i-th document sub-element
* *
* \p element is the type of the sub-element of interest.\n * \p element is the type of the sub-element of interest.\n
* \p element_index is the index of the sub-element within the AMF * \p element_index is the index of the sub-element within the AMF
* document.\n * document.\n
* The domain of this index depends on \p element : * The domain of this index depends on \p element :
* <table> * Element type | Domain of index | gmio type
* <tr> <th>Element type</th> <th>Domain of index</th> </tr> * --------------|---------------------------------------|----------------
* <tr> <td>OBJECT</td> <td><tt>[0 .. object_count[</tt></td> * OBJECT | <tt> [0 .. object_count[ </tt> | gmio_amf_object
* <tr> <td>MATERIAL</td> <td><tt>[0 .. material_count[</tt></td> * MATERIAL | <tt> [0 .. material_count[ </tt> | gmio_amf_material
* <tr> <td>TEXTURE</td> <td><tt>[0 .. texture_count[</tt></td> * TEXTURE | <tt> [0 .. texture_count[ </tt> | gmio_amf_texture
* <tr> <td>CONSTELLATION</td> <td><tt>[0 .. constellation_count[</tt></td> * CONSTELLATION | <tt> [0 .. constellation_count[ </tt> | gmio_amf_constellation
* <tr> <td>METADATA</td> <td><tt>[0 .. metadata_count[</tt></td> * METADATA | <tt> [0 .. metadata_count[ </tt> | gmio_amf_metadata
* </table>
*
* <table>
* <tr> <th>Element type</th> <th>gmio type</th> </tr>
* <tr> <td>OBJECT</td> <td>gmio_amf_object</td>
* <tr> <td>MATERIAL</td> <td>gmio_amf_material</td>
* <tr> <td>TEXTURE</td> <td>gmio_amf_texture</td>
* <tr> <td>CONSTELLATION</td> <td>gmio_amf_constellation</td>
* <tr> <td>METADATA</td> <td>gmio_amf_metadata</td>
* </table>
*/ */
void (*func_get_document_element)( void (*func_get_document_element)(
const void* cookie, const void* cookie,
@ -270,51 +253,46 @@ struct gmio_amf_document
uint32_t element_index, uint32_t element_index,
void* ptr_element); void* ptr_element);
/*! Pointer on a function that retrieves the i-th \c composite within a /*! Optional function that retrieves the i-th \c composite within a
* \c material element */ * \c material element
*
* Function not required(can be set to \c NULL) if there is no material
* composite in the document to write */
void (*func_get_material_composite)( void (*func_get_material_composite)(
const void* cookie, const void* cookie,
uint32_t material_index, uint32_t material_index,
uint32_t composite_index, uint32_t composite_index,
struct gmio_amf_composite* ptr_composite); struct gmio_amf_composite* ptr_composite);
/*! Pointer on a function that retrieves the i-th \c instance within a /*! Optional function that retrieves the i-th \c instance within a
* \c constellation element */ * \c constellation element
*
* Function not required(can be set to \c NULL) if there is no
* constellation in the document to write */
void (*func_get_constellation_instance)( void (*func_get_constellation_instance)(
const void* cookie, const void* cookie,
uint32_t constellation_index, uint32_t constellation_index,
uint32_t instance_index, uint32_t instance_index,
struct gmio_amf_instance* ptr_instance); struct gmio_amf_instance* ptr_instance);
/*! Pointer on a function that retrieves the i-th \c mesh within an /*! Function that retrieves the i-th \c mesh within an \c object element */
* \c object element */
void (*func_get_object_mesh)( void (*func_get_object_mesh)(
const void* cookie, const void* cookie,
uint32_t object_index, uint32_t object_index,
uint32_t mesh_index, uint32_t mesh_index,
struct gmio_amf_mesh* ptr_mesh); struct gmio_amf_mesh* ptr_mesh);
/*! Pointer on a function that retrieves the i-th sub-element of a \c mesh /*! Function that retrieves the i-th sub-element of a \c mesh element
* element
* *
* \p element is the type of the sub-element of interest.\n * \p element is the type of the sub-element of interest.\n
* \p element_index is the index of the sub-element within the \c mesh * \p element_index is the index of the sub-element within the \c mesh
* element.\n * element.\n
* The domain of this index(ie. \c value field) depends on \p element : * The domain of this index(ie. \c value field) depends on \p element :
* <table> * Element type | Domain of index | gmio type
* <tr> <th>Element type</th> <th>Domain of index</th> </tr> * --------------|-----------------------------------------------|----------------
* <tr> <td>VERTEX</td> <td><tt>[0 .. gmio_amf_mesh::vertex_count[</tt></td> * VERTEX | <tt> [0 .. gmio_amf_mesh::vertex_count[ </tt> | gmio_amf_vertex
* <tr> <td>EDGE</td> <td><tt>[0 .. gmio_amf_mesh::edge_count[</tt></td> * EDGE | <tt> [0 .. gmio_amf_mesh::edge_count[ </tt> | gmio_amf_edge
* <tr> <td>VOLUME</td> <td><tt>[0 .. gmio_amf_mesh::volume_count[</tt></td> * VOLUME | <tt> [0 .. gmio_amf_mesh::volume_count[ </tt> | gmio_amf_volume
* </table>
*
* The concrete type of \p ptr_struct_element depends on \p element :
* <table>
* <tr> <th>Element type</th> <th>gmio type</th> </tr>
* <tr> <td>VERTEX</td> <td>gmio_amf_vertex</td>
* <tr> <td>EDGE</td> <td>gmio_amf_edge</td>
* <tr> <td>VOLUME</td> <td>gmio_amf_volume</td>
* </table>
*/ */
void (*func_get_object_mesh_element)( void (*func_get_object_mesh_element)(
const void* cookie, const void* cookie,
@ -322,8 +300,8 @@ struct gmio_amf_document
const struct gmio_amf_object_mesh_element_index* element_index, const struct gmio_amf_object_mesh_element_index* element_index,
void* ptr_element); void* ptr_element);
/*! Pointer on a function that retrieves the i-th \c triangle within a /*! Function that retrieves the i-th \c triangle within a mesh \c volume
* mesh \c volume element */ * element */
void (*func_get_object_mesh_volume_triangle)( void (*func_get_object_mesh_volume_triangle)(
const void* cookie, const void* cookie,
const struct gmio_amf_object_mesh_element_index* volume_index, const struct gmio_amf_object_mesh_element_index* volume_index,
@ -332,25 +310,21 @@ struct gmio_amf_document
/* Function pointers to retrieve metadata */ /* Function pointers to retrieve metadata */
/*! Pointer on a function that retrieves the i-th metadata assigned to a /*! Optional function that retrieves the i-th metadata assigned to a
* document sub-element(being \c material, \c object or \c constellation ) * document sub-element
*
* \p element is the type of the sub-element of interest, it can
* take one of this value :
* \li GMIO_AMF_DOCUMENT_ELEMENT_MATERIAL
* \li GMIO_AMF_DOCUMENT_ELEMENT_OBJECT
* \li GMIO_AMF_DOCUMENT_ELEMENT_CONSTELLATION
* *
* \p element is the type of the sub-element of interest.\n
* \p element_index is the index of the sub-element within the AMF * \p element_index is the index of the sub-element within the AMF
* document.\n * document.\n
* The domain of this index depends on \p element : * The domain of this index depends on \p element :
* <table> * Element type | Domain of index | gmio type
* <tr> <th>Element type</th> <th>Domain of index</th> </tr> * --------------|---------------------------------------|----------------
* <tr> <td>MATERIAL</td> <td><tt>[0 .. material_count[</tt></td> * MATERIAL | <tt> [0 .. material_count[ </tt> | gmio_amf_material
* <tr> <td>OBJECT</td> <td><tt>[0 .. object_count[</tt></td> * OBJECT | <tt> [0 .. object_count[ </tt> | gmio_amf_object
* <tr> <td>CONSTELLATION</td> <td><tt>[0 .. constellation_count[</tt></td> * CONSTELLATION | <tt> [0 .. constellation_count[ </tt> | gmio_amf_constellation
* </table> *
*/ * Function not required(can be set to \c NULL) if there is no metadata in
* the document to write */
void (*func_get_document_element_metadata)( void (*func_get_document_element_metadata)(
const void* cookie, const void* cookie,
enum gmio_amf_document_element element, enum gmio_amf_document_element element,
@ -358,16 +332,22 @@ struct gmio_amf_document
uint32_t metadata_index, uint32_t metadata_index,
struct gmio_amf_metadata* ptr_metadata); struct gmio_amf_metadata* ptr_metadata);
/*! Pointer on a function that retrieves the i-th metadata assigned to a /*! Optional function that retrieves the i-th metadata assigned to a mesh
* mesh vertex */ * vertex
*
* Function not required(can be set to \c NULL) if there is no mesh vertex
* metadata in the document to write */
void (*func_get_object_mesh_vertex_metadata)( void (*func_get_object_mesh_vertex_metadata)(
const void* cookie, const void* cookie,
const struct gmio_amf_object_mesh_element_index* vertex_index, const struct gmio_amf_object_mesh_element_index* vertex_index,
uint32_t metadata_index, uint32_t metadata_index,
struct gmio_amf_metadata* ptr_metadata); struct gmio_amf_metadata* ptr_metadata);
/*! Pointer on a function that retrieves the i-th metadata assigned to a /*! Optional function that retrieves the i-th metadata assigned to a mesh
* mesh volume */ * volume
*
* Function not required(can be set to \c NULL) if there is no mesh volume
* metadata in the document to write */
void (*func_get_object_mesh_volume_metadata)( void (*func_get_object_mesh_volume_metadata)(
const void* cookie, const void* cookie,
const struct gmio_amf_object_mesh_element_index* volume_index, const struct gmio_amf_object_mesh_element_index* volume_index,

12
src/gmio_amf/amf_io.h
View File

@ -44,6 +44,14 @@
GMIO_C_LINKAGE_BEGIN GMIO_C_LINKAGE_BEGIN
/*! Writes AMF document to stream /*! Writes AMF document to stream
*
* When gmio_amf_write_options::create_zip_archive is \c ON then a compressed
* ZIP archive is written on the fly. At the end it will contains a single file
* entry containing the AMF document.\n
* In case of compression the first half of the memory pointed to by
* gmio_amf_write_options::stream_memblock is used internally as a <i>stream
* buffer</i> and the second half is employed as a <i>compression buffer</i>
* for zlib.
* *
* \pre <tt> stream != NULL </tt> * \pre <tt> stream != NULL </tt>
* \pre <tt> doc != NULL </tt> * \pre <tt> doc != NULL </tt>
@ -64,6 +72,10 @@ GMIO_API int gmio_amf_write(
* This is just a facility function over gmio_amf_write(). The internal stream * This is just a facility function over gmio_amf_write(). The internal stream
* object is created to read file at \p filepath * object is created to read file at \p filepath
* *
* In case gmio_amf_write_options::create_zip_archive is \c ON and
* \c zip_entry_filename is \c NULL or empty then the ZIP entry filename is
* automatically set to the basename of \p filepath suffixed by <tt>.amf</tt>
*
* \pre <tt> filepath != \c NULL </tt>\n * \pre <tt> filepath != \c NULL </tt>\n
* The file is opened with \c fopen() so \p filepath shall follow the file * The file is opened with \c fopen() so \p filepath shall follow the file
* name specifications of the running environment * name specifications of the running environment

15
src/gmio_amf/amf_io_options.h
View File

@ -71,20 +71,23 @@ struct gmio_amf_write_options
/* ZIP/Deflate compression */ /* ZIP/Deflate compression */
/*! Flag to write AMF geometry in a ZIP archive containing one file entry. /*! Flag to write AMF document in ZIP archive containing one file entry */
* Options below have no effect if <tt>create_zip_archive==false</tt> */
bool create_zip_archive; bool create_zip_archive;
/*! Filename of the single AMF entry within the ZIP archive */ /*! Filename of the single AMF entry within the ZIP archive.
* Applicable only if <tt>create_zip_archive==true</tt> */
const char* zip_entry_filename; const char* zip_entry_filename;
/*! Filename length of the single AMF entry within the ZIP archive */ /*! Filename length of the single AMF entry within the ZIP archive.
* Applicable only if <tt>create_zip_archive==true</tt> */
uint16_t zip_entry_filename_len; uint16_t zip_entry_filename_len;
/*! Flag to disable use of the Zip64 format extensions */ /*! Flag to disable use of the Zip64 format extensions.
* Applicable only if <tt>create_zip_archive==true</tt> */
bool dont_use_zip64_extensions; bool dont_use_zip64_extensions;
/*! Options for the zlib(deflate) compression */ /*! Options for the zlib(deflate) compression.
* Applicable only if <tt>create_zip_archive==true</tt> */
struct gmio_zlib_compress_options z_compress_options; struct gmio_zlib_compress_options z_compress_options;
}; };

18
src/gmio_core/error.h
View File

@ -40,17 +40,15 @@
/*! Common errors /*! Common errors
* *
* Format: * Format: \n
* <code> * 4-bytes signed integer (ISO C restricts enumerator value to 'int') \n
* 4-bytes signed integer (ISO C restricts enumerator value to 'int') * max value: 0x7FFFFFFF \n
* max value: 0x7FFFFFFF * bits 0x00FFFFFF..0x7FFFFFFF: tag identifying the error category \n
* bits 0x00FFFFFF..0x7FFFFFFF: tag identifying the error category * bits 0x001FFFFF..0x00FFFFFF: tag identifying an error sub-category \n
* bits 0x001FFFFF..0x00FFFFFF: tag identifying an error sub-category * bits 0x00000000..0x000FFFFF: error value in the (sub)category \n
* bits 0x00000000..0x000FFFFF: error value in the (sub)category * Max count of categories : 128 (2^7) \n
* Max count of categories : 128 (2^7) * Max count of sub-categories : 15 (2^4 - 1) \n
* Max count of sub-categories : 15 (2^4 - 1)
* Max count of error values : 1048576 (2^20) * Max count of error values : 1048576 (2^20)
* <encode>
*/ */
enum gmio_error enum gmio_error
{ {

31
src/gmio_core/memblock.h
View File

@ -62,11 +62,8 @@ struct gmio_memblock
/*! Size (in bytes) of the memory block */ /*! Size (in bytes) of the memory block */
size_t size; size_t size;
/*! Optional pointer on a function that deallocates the memory block /*! Optional function that deallocates the memory block beginning at \p ptr
* beginning at \p ptr * \sa gmio_memblock_deallocate() */
*
* \sa gmio_memblock_deallocate()
*/
void (*func_deallocate)(void* ptr); void (*func_deallocate)(void* ptr);
}; };
@ -76,24 +73,20 @@ GMIO_C_LINKAGE_BEGIN
GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock); GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
/*! Returns an initialized memblock object. /*! Returns an initialized memblock object.
* If \p ptr is NULL then gmio_memblock::size is forced to \c 0 * If \p ptr is NULL then gmio_memblock::size is forced to \c 0 */
*/
GMIO_API struct gmio_memblock gmio_memblock( GMIO_API struct gmio_memblock gmio_memblock(
void* ptr, size_t size, void (*func_deallocate)(void*)); void* ptr, size_t size, void (*func_deallocate)(void*));
/*! Returns a memblock allocated with standard \c malloc(). /*! Returns a memblock allocated with standard \c malloc().
* gmio_memblock::func_deallocate is set to standard \c free() * gmio_memblock::func_deallocate is set to standard \c free() */
*/
GMIO_API struct gmio_memblock gmio_memblock_malloc(size_t size); GMIO_API struct gmio_memblock gmio_memblock_malloc(size_t size);
/*! Returns a memblock allocated with standard \c calloc(). /*! Returns a memblock allocated with standard \c calloc().
* gmio_memblock::func_deallocate is set to standard \c free() * gmio_memblock::func_deallocate is set to standard \c free() */
*/
GMIO_API struct gmio_memblock gmio_memblock_calloc(size_t num, size_t size); GMIO_API struct gmio_memblock gmio_memblock_calloc(size_t num, size_t size);
/*! Returns a memblock allocated with standard \c realloc(). /*! Returns a memblock allocated with standard \c realloc().
* gmio_memblock::func_deallocate is set to standard \c free() * gmio_memblock::func_deallocate is set to standard \c free() */
*/
GMIO_API struct gmio_memblock gmio_memblock_realloc(void* ptr, size_t size); GMIO_API struct gmio_memblock gmio_memblock_realloc(void* ptr, size_t size);
/*! Safe and convenient call to gmio_memblock::func_deallocate() */ /*! Safe and convenient call to gmio_memblock::func_deallocate() */
@ -102,8 +95,7 @@ GMIO_API void gmio_memblock_deallocate(struct gmio_memblock* mblock);
/*! Typedef for a pointer to a function that creates an allocated memblock /*! Typedef for a pointer to a function that creates an allocated memblock
* *
* Signature: * Signature:
* \code{.c} struct gmio_memblock mblock_ctor(); \endcode * \code{.c} struct gmio_memblock mblock_ctor(); \endcode */
*/
typedef struct gmio_memblock (*gmio_memblock_constructor_func_t)(); typedef struct gmio_memblock (*gmio_memblock_constructor_func_t)();
/*! Installs a global function to construct gmio_memblock objects /*! Installs a global function to construct gmio_memblock objects
@ -111,19 +103,16 @@ typedef struct gmio_memblock (*gmio_memblock_constructor_func_t)();
* The constructor function allocates a memblock on demand, to be used when a * The constructor function allocates a memblock on demand, to be used when a
* temporary memblock is needed. * temporary memblock is needed.
* *
* This function is not thread-safe. * This function is not thread-safe. */
*/
GMIO_API void gmio_memblock_set_default_constructor( GMIO_API void gmio_memblock_set_default_constructor(
gmio_memblock_constructor_func_t ctor); gmio_memblock_constructor_func_t ctor);
/*! Returns the currently installed function to construct memblock objects. /*! Returns the currently installed function to construct memblock objects.
* It is initialized to <tt>gmio_memblock_malloc(128KB)</tt> * It is initialized to <tt>gmio_memblock_malloc(128KB)</tt> */
*/
GMIO_API gmio_memblock_constructor_func_t gmio_memblock_default_constructor(); GMIO_API gmio_memblock_constructor_func_t gmio_memblock_default_constructor();
/*! Returns a memblock created with the function /*! Returns a memblock created with the function
* gmio_memblock_default_constructor() * gmio_memblock_default_constructor() */
*/
GMIO_API struct gmio_memblock gmio_memblock_default(); GMIO_API struct gmio_memblock gmio_memblock_default();
GMIO_C_LINKAGE_END GMIO_C_LINKAGE_END

14
src/gmio_core/stream.h
View File

@ -81,7 +81,7 @@ struct gmio_stream
* hook functions */ * hook functions */
void* cookie; void* cookie;
/*! Pointer on a function that checks end-of-stream indicator /*! Function that checks end-of-stream indicator
* *
* Checks whether the end-of-stream indicator associated with stream * Checks whether the end-of-stream indicator associated with stream
* pointed by \p cookie is set, returning true if it is. * pointed by \p cookie is set, returning true if it is.
@ -91,7 +91,7 @@ struct gmio_stream
*/ */
bool (*func_at_end)(void* cookie); bool (*func_at_end)(void* cookie);
/*! Pointer on a function that checks error indicator /*! Function that checks error indicator
* *
* Checks if the error indicator associated with stream pointed by * Checks if the error indicator associated with stream pointed by
* \p cookie is set, returning a value different from zero if it is. * \p cookie is set, returning a value different from zero if it is.
@ -101,7 +101,7 @@ struct gmio_stream
*/ */
int (*func_error)(void* cookie); int (*func_error)(void* cookie);
/*! Pointer on a function that reads block of data from stream /*! Function that reads block of data from stream
* *
* Reads an array of \p count elements, each one with a size of * Reads an array of \p count elements, each one with a size of
* \p size bytes, from the stream pointed by \p cookie and stores them in * \p size bytes, from the stream pointed by \p cookie and stores them in
@ -114,7 +114,7 @@ struct gmio_stream
*/ */
size_t (*func_read)(void* cookie, void* ptr, size_t size, size_t count); size_t (*func_read)(void* cookie, void* ptr, size_t size, size_t count);
/*! Pointer on a function that writes block of data to stream /*! Function that writes block of data to stream
* *
* Writes an array of \p count elements, each one with a size of * Writes an array of \p count elements, each one with a size of
* \p size bytes, from the block of memory pointed by \p ptr to the current * \p size bytes, from the block of memory pointed by \p ptr to the current
@ -127,17 +127,17 @@ struct gmio_stream
*/ */
size_t (*func_write)(void* cookie, const void* ptr, size_t size, size_t count); size_t (*func_write)(void* cookie, const void* ptr, size_t size, size_t count);
/*! Pointer on a function that returns the size(in bytes) of the stream */ /*! Function that returns the size(in bytes) of the stream */
gmio_streamsize_t (*func_size)(void* cookie); gmio_streamsize_t (*func_size)(void* cookie);
/*! Pointer on a function that retrieves the current position in the stream /*! Function that retrieves the current position in the stream
* *
* \retval 0 on success * \retval 0 on success
* \retval !=0 on error * \retval !=0 on error
*/ */
int (*func_get_pos)(void* cookie, struct gmio_streampos* pos); int (*func_get_pos)(void* cookie, struct gmio_streampos* pos);
/*! Pointer on a function that restores the current position in the stream /*! Function that restores the current position in the stream
* to \p pos * to \p pos
* *
* \retval 0 on success * \retval 0 on success

12
src/gmio_core/task_iface.h
View File

@ -45,21 +45,17 @@ struct gmio_task_iface
* argument to hook functions */ * argument to hook functions */
void* cookie; void* cookie;
/*! Optional pointer on a function that says if the currently running /*! Optional function that says if the currently running task must stop
* task must stop
* *
* If \c true is returned then the current task should abort as * If \c true is returned then the current task should abort as
* soon as possible, otherwise it can continue execution. * soon as possible, otherwise it can continue execution */
*/
bool (*func_is_stop_requested)(void* cookie); bool (*func_is_stop_requested)(void* cookie);
/*! Optional pointer on a function that is called anytime some new progress /*! Optional function that is called anytime some new progress was done
* was done
* *
* \param cookie The cookie set inside the gmio_task_iface object * \param cookie The cookie set inside the gmio_task_iface object
* \param value Current value of the task progress (<= \p max_value ) * \param value Current value of the task progress (<= \p max_value )
* \param max_value Maximum value of the task progress * \param max_value Maximum value of the task progress */
*/
void (*func_handle_progress)( void (*func_handle_progress)(
void* cookie, intmax_t value, intmax_t max_value); void* cookie, intmax_t value, intmax_t max_value);
}; };

5
src/gmio_core/text_format.h
View File

@ -41,14 +41,19 @@ enum gmio_float_text_format
{ {
/*! Decimal floating point, lowercase (ex: 392.65) */ /*! Decimal floating point, lowercase (ex: 392.65) */
GMIO_FLOAT_TEXT_FORMAT_DECIMAL_LOWERCASE = 0, GMIO_FLOAT_TEXT_FORMAT_DECIMAL_LOWERCASE = 0,
/*! Decimal floating point, uppercase (ex: 392.65) */ /*! Decimal floating point, uppercase (ex: 392.65) */
GMIO_FLOAT_TEXT_FORMAT_DECIMAL_UPPERCASE, GMIO_FLOAT_TEXT_FORMAT_DECIMAL_UPPERCASE,
/*! Scientific notation, lowercase (ex: 3.9265e+2) */ /*! Scientific notation, lowercase (ex: 3.9265e+2) */
GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_LOWERCASE, GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_LOWERCASE,
/*! Scientific notation, uppercase (ex: 3.9265E+2) */ /*! Scientific notation, uppercase (ex: 3.9265E+2) */
GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_UPPERCASE, GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_UPPERCASE,
/*! Use the shortest representation: decimal or scientific lowercase */ /*! Use the shortest representation: decimal or scientific lowercase */
GMIO_FLOAT_TEXT_FORMAT_SHORTEST_LOWERCASE, GMIO_FLOAT_TEXT_FORMAT_SHORTEST_LOWERCASE,
/*! Use the shortest representation: decimal or scientific uppercase */ /*! Use the shortest representation: decimal or scientific uppercase */
GMIO_FLOAT_TEXT_FORMAT_SHORTEST_UPPERCASE GMIO_FLOAT_TEXT_FORMAT_SHORTEST_UPPERCASE
}; };

39
src/gmio_core/zlib_compress.h
View File

@ -39,31 +39,28 @@
#include "global.h" #include "global.h"
/*! zlib compression level, specific values */ /*! zlib compression level, specific values */
enum gmio_zlib_compress_level enum gmio_zlib_compress_level {
{ GMIO_ZLIB_COMPRESS_LEVEL_NONE = -1, /*!< -> Z_NO_COMPRESSION */
GMIO_ZLIB_COMPRESS_LEVEL_NONE = -1, /*! -> Z_NO_COMPRESSION */ GMIO_ZLIB_COMPRESS_LEVEL_DEFAULT = 0, /*!< -> Z_DEFAULT_COMPRESSION */
GMIO_ZLIB_COMPRESS_LEVEL_DEFAULT = 0, /*! -> Z_DEFAULT_COMPRESSION */ GMIO_ZLIB_COMPRESS_LEVEL_BEST_SPEED = 1, /*!< -> Z_BEST_SPEED */
GMIO_ZLIB_COMPRESS_LEVEL_BEST_SPEED = 1, /*! -> Z_BEST_SPEED */ GMIO_ZLIB_COMPRESS_LEVEL_BEST_SIZE = 9 /*!< -> Z_BEST_COMPRESSION */
GMIO_ZLIB_COMPRESS_LEVEL_BEST_SIZE = 9 /*! -> Z_BEST_COMPRESSION */
}; };
/*! zlib compression strategy */ /*! zlib compression strategy */
enum gmio_zlib_compress_strategy enum gmio_zlib_compress_strategy {
{ GMIO_ZLIB_COMPRESSION_STRATEGY_DEFAULT = 0, /*!< -> Z_DEFAULT_STRATEGY */
GMIO_ZLIB_COMPRESSION_STRATEGY_DEFAULT = 0, /*! -> Z_DEFAULT_STRATEGY */ GMIO_ZLIB_COMPRESSION_STRATEGY_FILTERED = 1, /*!< -> Z_FILTERED */
GMIO_ZLIB_COMPRESSION_STRATEGY_FILTERED = 1, /*! -> Z_FILTERED */ GMIO_ZLIB_COMPRESSION_STRATEGY_HUFFMAN_ONLY = 2, /*!< -> Z_HUFFMAN_ONLY */
GMIO_ZLIB_COMPRESSION_STRATEGY_HUFFMAN_ONLY = 2, /*! -> Z_HUFFMAN_ONLY */ GMIO_ZLIB_COMPRESSION_STRATEGY_RLE = 3, /*!< -> Z_RLE */
GMIO_ZLIB_COMPRESSION_STRATEGY_RLE = 3, /*! -> Z_RLE */ GMIO_ZLIB_COMPRESSION_STRATEGY_FIXED = 4 /*!< -> Z_FIXED */
GMIO_ZLIB_COMPRESSION_STRATEGY_FIXED = 4 /*! -> Z_FIXED */
}; };
/*! zlib compression options /*! zlib compression options
* *
* Initialising gmio_zlib_compress_options with \c {0} (or \c {} in C++) is the * Initialising gmio_zlib_compress_options with \c {0} (or \c {} in C++) is the
* convenient way to set default values. * convenient way to set default values.
*/ */
struct gmio_zlib_compress_options struct gmio_zlib_compress_options {
{
/*! Compression level. /*! Compression level.
* Use enum value from \c gmio_zlib_compress_level */ * Use enum value from \c gmio_zlib_compress_level */
uint8_t level; uint8_t level;
@ -77,21 +74,19 @@ struct gmio_zlib_compress_options
* The value must belongs to \c [1..9] or equals to \c 0 which maps to the * The value must belongs to \c [1..9] or equals to \c 0 which maps to the
* default usage. * default usage.
* *
* \c 1 uses minimum memory but is slow and reduces compression ratio * \c 1 uses minimum memory but is slow and reduces compression ratio\n
* \c 9 uses maximum memory for optimal speed */ * \c 9 uses maximum memory for optimal speed */
uint8_t memory_usage; uint8_t memory_usage;
/*! Optional pointer to a function used to allocate the internal state /*! Optional function used to allocate the internal state within \c z_stream
* within \c z_stream structure.
* \sa z_stream::zalloc */ * \sa z_stream::zalloc */
void* (*func_alloc)(void* opaque, unsigned int items, unsigned int size); void* (*func_alloc)(void* opaque, unsigned int items, unsigned int size);
/*! Optional pointer to a function used to free the internal state within /*! Optional function used to free the internal state within \c z_stream
* \c z_stream structure.
* \sa z_stream::zfree */ * \sa z_stream::zfree */
void (*func_free)(void* opaque, void* address); void (*func_free)(void* opaque, void* address);
/*! Optional private data object passed to func_alloc and func_free. /*! Optional private data object passed to func_alloc() and func_free()
* \sa z_stream::opaque */ * \sa z_stream::opaque */
void* opaque; void* opaque;
}; };

4
src/gmio_stl/stl_mesh.h
View File

@ -49,8 +49,8 @@ struct gmio_stl_mesh
/*! Number of triangles in the mesh */ /*! Number of triangles in the mesh */
uint32_t triangle_count; uint32_t triangle_count;
/*! Pointer on a function that stores the mesh triangle of index \p tri_id /*! Function that stores the mesh triangle of index \p tri_id into
* into \p triangle */ * \p triangle */
void (*func_get_triangle)( void (*func_get_triangle)(
const void* cookie, const void* cookie,
uint32_t tri_id, uint32_t tri_id,

6
src/gmio_stl/stl_mesh_creator.h
View File

@ -83,11 +83,11 @@ struct gmio_stl_mesh_creator
/* All function pointers are optional (ie can be set to NULL) */ /* All function pointers are optional (ie can be set to NULL) */
/*! Optional pointer on a function that handles declaration of a solid */ /*! Optional function that handles declaration of a solid */
void (*func_begin_solid)( void (*func_begin_solid)(
void* cookie, const struct gmio_stl_mesh_creator_infos* infos); void* cookie, const struct gmio_stl_mesh_creator_infos* infos);
/*! Pointer on a function that adds a triangle to the user mesh /*! Function that adds a triangle to the user mesh
* *
* The argument \p triangle is the triangle to be added, note that * The argument \p triangle is the triangle to be added, note that
* struct gmio_stl_triangle::attribute_byte_count is meaningless for STL * struct gmio_stl_triangle::attribute_byte_count is meaningless for STL
@ -100,7 +100,7 @@ struct gmio_stl_mesh_creator
uint32_t tri_id, uint32_t tri_id,
const struct gmio_stl_triangle* triangle); const struct gmio_stl_triangle* triangle);
/*! Optional pointer on a function that finalizes creation of the user mesh /*! Optional function that finalizes creation of the user mesh
* *
* The function is called at the end of the read process, ie. after all * The function is called at the end of the read process, ie. after all
* triangles have been added */ * triangles have been added */