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
# 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
# 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>
struct gmio_amf_metadata
{
struct gmio_amf_metadata {
const char* type; /*!< UTF8-encoded */
const char* data; /*!< UTF8-encoded */
};
struct gmio_amf_color
{
struct gmio_amf_color {
double r; /*!< Red channel in [0,1] */
double g; /*!< Green channel in [0,1] */
double b; /*!< Blue channel in [0,1] */
@ -62,8 +60,7 @@ struct gmio_amf_color
const char* a_formula;
};
struct gmio_amf_material
{
struct gmio_amf_material {
uint32_t id; /* XML:integer */
struct gmio_amf_color color;
uint32_t composite_count;
@ -73,18 +70,15 @@ struct gmio_amf_material
/*! Proportion of the composition of another material
*
* The proportion can be specified as a formula(with \c value_formula) or as a
* constant mixing(with \c value).
*/
struct gmio_amf_composite
{
* constant mixing(with \c value) */
struct gmio_amf_composite {
uint32_t materialid; /* XML:nonNegativeInteger, required */
double value; /*!< governs the percent of material */
double value; /*!< Governs the percent of material */
const char* value_formula;
};
/*! Vertex within an AMF mesh */
struct gmio_amf_vertex
{
struct gmio_amf_vertex {
struct gmio_vec3d coords;
bool has_normal;
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 */
struct gmio_amf_edge
{
struct gmio_amf_edge {
uint32_t v1; /* XML:nonNegativeInteger */
uint32_t v2; /* XML:nonNegativeInteger */
/* Direction vectors */
@ -103,8 +96,7 @@ struct gmio_amf_edge
struct gmio_vec3d d2; /* XML:NegOneToOne: -1 <= coord <= 1 */
};
struct gmio_amf_texmap
{
struct gmio_amf_texmap {
uint32_t rtexid; /* XML:nonNegativeInteger */
uint32_t gtexid; /* 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_amf_triangle
{
struct gmio_amf_triangle {
uint32_t v1; /* XML:nonNegativeInteger */
uint32_t v2; /* XML:nonNegativeInteger */
uint32_t v3; /* XML:nonNegativeInteger */
@ -126,15 +117,13 @@ struct gmio_amf_triangle
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_SUPPORT
};
/*! Volume within an AMF mesh */
struct gmio_amf_volume
{
struct gmio_amf_volume {
uint32_t materialid; /* XML:nonNegativeInteger */
enum gmio_amf_volume_type type;
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_mesh
{
struct gmio_amf_mesh {
uint32_t vertex_count;
uint32_t edge_count;
uint32_t volume_count;
};
struct gmio_amf_object
{
struct gmio_amf_object {
uint32_t id; /* XML:integer */
uint32_t mesh_count;
uint32_t metadata_count;
@ -159,8 +146,7 @@ struct gmio_amf_object
struct gmio_amf_color color; /* XML:Color */
};
struct gmio_amf_constellation
{
struct gmio_amf_constellation {
uint32_t id; /* XML:integer */
uint32_t instance_count; /*!< Should be >= 2 */
uint32_t metadata_count;
@ -171,16 +157,14 @@ struct gmio_amf_instance
{
uint32_t objectid; /* XML:nonNegativeInteger */
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
};
struct gmio_amf_texture
{
struct gmio_amf_texture {
uint32_t id; /* XML:integer */
uint32_t width; /* XML:nonNegativeInteger */
uint32_t height; /* XML:nonNegativeInteger */
@ -191,8 +175,7 @@ struct gmio_amf_texture
};
/*! Units supported by AMF */
enum gmio_amf_unit
{
enum gmio_amf_unit {
GMIO_AMF_UNIT_UNKNOWN,
GMIO_AMF_UNIT_MILLIMETER,
GMIO_AMF_UNIT_INCH,
@ -201,9 +184,8 @@ enum gmio_amf_unit
GMIO_AMF_UNIT_MICRON
};
/*! The direct elements of an AMF document(ie. inside <tt><amf>...</amf></tt>) */
enum gmio_amf_document_element
{
/*! The direct elements of an AMF document(ie inside <tt><amf>...</amf></tt>) */
enum gmio_amf_document_element {
GMIO_AMF_DOCUMENT_ELEMENT_OBJECT,
GMIO_AMF_DOCUMENT_ELEMENT_MATERIAL,
GMIO_AMF_DOCUMENT_ELEMENT_TEXTURE,
@ -211,58 +193,59 @@ enum gmio_amf_document_element
GMIO_AMF_DOCUMENT_ELEMENT_METADATA
};
/*! The direct elements of an AMF mesh(ie. inside <tt><mesh>...</mesh></tt>) */
enum gmio_amf_mesh_element
{
/*! The direct elements of an AMF mesh(ie inside <tt><mesh>...</mesh></tt>) */
enum gmio_amf_mesh_element {
GMIO_AMF_MESH_ELEMENT_VERTEX,
GMIO_AMF_MESH_ELEMENT_EDGE,
GMIO_AMF_MESH_ELEMENT_VOLUME
};
struct gmio_amf_object_mesh_element_index
{
uint32_t object_index;
uint32_t mesh_index;
uint32_t value;
/*! Index of an element(vertex, edge or volume) within a mesh */
struct gmio_amf_object_mesh_element_index {
uint32_t object_index; /*!< Index of the object that owns the mesh */
uint32_t mesh_index; /*!< Index of the mesh that owns element */
uint32_t value; /*!< Index of the inner element */
};
/* Note: version is 1.2 */
struct gmio_amf_document
{
/*! Provides an interface for accessing the underlying(hidden) user AMF data
*
* \note version is 1.2
*/
struct gmio_amf_document {
/*! Opaque pointer on the user AMF document, passed as first argument to
* hook functions */
const void* cookie;
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;
/*! Number of textures in the document */
uint32_t texture_count;
/*! Number of constellations in the document */
uint32_t constellation_count;
/*! Number of direct metadata attached to the document */
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_index is the index of the sub-element within the AMF
* document.\n
* The domain of this index depends on \p element :
* <table>
* <tr> <th>Element type</th> <th>Domain of index</th> </tr>
* <tr> <td>OBJECT</td> <td><tt>[0 .. object_count[</tt></td>
* <tr> <td>MATERIAL</td> <td><tt>[0 .. material_count[</tt></td>
* <tr> <td>TEXTURE</td> <td><tt>[0 .. texture_count[</tt></td>
* <tr> <td>CONSTELLATION</td> <td><tt>[0 .. constellation_count[</tt></td>
* <tr> <td>METADATA</td> <td><tt>[0 .. metadata_count[</tt></td>
* </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>
* Element type | Domain of index | gmio type
* --------------|---------------------------------------|----------------
* OBJECT | <tt> [0 .. object_count[ </tt> | gmio_amf_object
* MATERIAL | <tt> [0 .. material_count[ </tt> | gmio_amf_material
* TEXTURE | <tt> [0 .. texture_count[ </tt> | gmio_amf_texture
* CONSTELLATION | <tt> [0 .. constellation_count[ </tt> | gmio_amf_constellation
* METADATA | <tt> [0 .. metadata_count[ </tt> | gmio_amf_metadata
*/
void (*func_get_document_element)(
const void* cookie,
@ -270,51 +253,46 @@ struct gmio_amf_document
uint32_t element_index,
void* ptr_element);
/*! Pointer on a function that retrieves the i-th \c composite within a
* \c material element */
/*! Optional function that retrieves the i-th \c composite within a
* \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)(
const void* cookie,
uint32_t material_index,
uint32_t composite_index,
struct gmio_amf_composite* ptr_composite);
/*! Pointer on a function that retrieves the i-th \c instance within a
* \c constellation element */
/*! Optional function that retrieves the i-th \c instance within a
* \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)(
const void* cookie,
uint32_t constellation_index,
uint32_t instance_index,
struct gmio_amf_instance* ptr_instance);
/*! Pointer on a function that retrieves the i-th \c mesh within an
* \c object element */
/*! Function that retrieves the i-th \c mesh within an \c object element */
void (*func_get_object_mesh)(
const void* cookie,
uint32_t object_index,
uint32_t mesh_index,
struct gmio_amf_mesh* ptr_mesh);
/*! Pointer on a function that retrieves the i-th sub-element of a \c mesh
* element
/*! Function that retrieves the i-th sub-element of a \c mesh element
*
* \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
* element.\n
* The domain of this index(ie. \c value field) depends on \p element :
* <table>
* <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>
* <tr> <td>EDGE</td> <td><tt>[0 .. gmio_amf_mesh::edge_count[</tt></td>
* <tr> <td>VOLUME</td> <td><tt>[0 .. gmio_amf_mesh::volume_count[</tt></td>
* </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>
* Element type | Domain of index | gmio type
* --------------|-----------------------------------------------|----------------
* VERTEX | <tt> [0 .. gmio_amf_mesh::vertex_count[ </tt> | gmio_amf_vertex
* EDGE | <tt> [0 .. gmio_amf_mesh::edge_count[ </tt> | gmio_amf_edge
* VOLUME | <tt> [0 .. gmio_amf_mesh::volume_count[ </tt> | gmio_amf_volume
*/
void (*func_get_object_mesh_element)(
const void* cookie,
@ -322,8 +300,8 @@ struct gmio_amf_document
const struct gmio_amf_object_mesh_element_index* element_index,
void* ptr_element);
/*! Pointer on a function that retrieves the i-th \c triangle within a
* mesh \c volume element */
/*! Function that retrieves the i-th \c triangle within a mesh \c volume
* element */
void (*func_get_object_mesh_volume_triangle)(
const void* cookie,
const struct gmio_amf_object_mesh_element_index* volume_index,
@ -332,25 +310,21 @@ struct gmio_amf_document
/* Function pointers to retrieve metadata */
/*! Pointer on a function that retrieves the i-th metadata assigned to a
* document sub-element(being \c material, \c object or \c constellation )
*
* \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
/*! Optional function that retrieves the i-th metadata assigned to a
* document sub-element
*
* \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
* document.\n
* The domain of this index depends on \p element :
* <table>
* <tr> <th>Element type</th> <th>Domain of index</th> </tr>
* <tr> <td>MATERIAL</td> <td><tt>[0 .. material_count[</tt></td>
* <tr> <td>OBJECT</td> <td><tt>[0 .. object_count[</tt></td>
* <tr> <td>CONSTELLATION</td> <td><tt>[0 .. constellation_count[</tt></td>
* </table>
*/
* Element type | Domain of index | gmio type
* --------------|---------------------------------------|----------------
* MATERIAL | <tt> [0 .. material_count[ </tt> | gmio_amf_material
* OBJECT | <tt> [0 .. object_count[ </tt> | gmio_amf_object
* CONSTELLATION | <tt> [0 .. constellation_count[ </tt> | gmio_amf_constellation
*
* 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)(
const void* cookie,
enum gmio_amf_document_element element,
@ -358,16 +332,22 @@ struct gmio_amf_document
uint32_t metadata_index,
struct gmio_amf_metadata* ptr_metadata);
/*! Pointer on a function that retrieves the i-th metadata assigned to a
* mesh vertex */
/*! Optional function that retrieves the i-th metadata assigned to a mesh
* 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)(
const void* cookie,
const struct gmio_amf_object_mesh_element_index* vertex_index,
uint32_t metadata_index,
struct gmio_amf_metadata* ptr_metadata);
/*! Pointer on a function that retrieves the i-th metadata assigned to a
* mesh volume */
/*! Optional function that retrieves the i-th metadata assigned to a mesh
* 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)(
const void* cookie,
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
/*! 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> 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
* 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
* The file is opened with \c fopen() so \p filepath shall follow the file
* 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 */
/*! Flag to write AMF geometry in a ZIP archive containing one file entry.
* Options below have no effect if <tt>create_zip_archive==false</tt> */
/*! Flag to write AMF document in ZIP archive containing one file entry */
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;
/*! 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;
/*! 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;
/*! 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;
};

18
src/gmio_core/error.h
View File

@ -40,17 +40,15 @@
/*! Common errors
*
* Format:
* <code>
* 4-bytes signed integer (ISO C restricts enumerator value to 'int')
* max value: 0x7FFFFFFF
* bits 0x00FFFFFF..0x7FFFFFFF: tag identifying the error category
* bits 0x001FFFFF..0x00FFFFFF: tag identifying an error sub-category
* bits 0x00000000..0x000FFFFF: error value in the (sub)category
* Max count of categories : 128 (2^7)
* Max count of sub-categories : 15 (2^4 - 1)
* Format: \n
* 4-bytes signed integer (ISO C restricts enumerator value to 'int') \n
* max value: 0x7FFFFFFF \n
* bits 0x00FFFFFF..0x7FFFFFFF: tag identifying the error category \n
* bits 0x001FFFFF..0x00FFFFFF: tag identifying an error sub-category \n
* bits 0x00000000..0x000FFFFF: error value in the (sub)category \n
* Max count of categories : 128 (2^7) \n
* Max count of sub-categories : 15 (2^4 - 1) \n
* Max count of error values : 1048576 (2^20)
* <encode>
*/
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_t size;
/*! Optional pointer on a function that deallocates the memory block
* beginning at \p ptr
*
* \sa gmio_memblock_deallocate()
*/
/*! Optional function that deallocates the memory block beginning at \p ptr
* \sa gmio_memblock_deallocate() */
void (*func_deallocate)(void* ptr);
};
@ -76,24 +73,20 @@ GMIO_C_LINKAGE_BEGIN
GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
/*! 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(
void* ptr, size_t size, void (*func_deallocate)(void*));
/*! 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);
/*! 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);
/*! 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);
/*! 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
*
* 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)();
/*! 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
* 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_memblock_constructor_func_t ctor);
/*! 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();
/*! Returns a memblock created with the function
* gmio_memblock_default_constructor()
*/
* gmio_memblock_default_constructor() */
GMIO_API struct gmio_memblock gmio_memblock_default();
GMIO_C_LINKAGE_END

14
src/gmio_core/stream.h
View File

@ -81,7 +81,7 @@ struct gmio_stream
* hook functions */
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
* pointed by \p cookie is set, returning true if it is.
@ -91,7 +91,7 @@ struct gmio_stream
*/
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
* \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);
/*! 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
* \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);
/*! 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
* \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);
/*! 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);
/*! 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 error
*/
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
*
* \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 */
void* cookie;
/*! Optional pointer on a function that says if the currently running
* task must stop
/*! Optional function that says if the currently running task must stop
*
* 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);
/*! Optional pointer on a function that is called anytime some new progress
* was done
/*! Optional function that is called anytime some new progress was done
*
* \param cookie The cookie set inside the gmio_task_iface object
* \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* 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) */
GMIO_FLOAT_TEXT_FORMAT_DECIMAL_LOWERCASE = 0,
/*! Decimal floating point, uppercase (ex: 392.65) */
GMIO_FLOAT_TEXT_FORMAT_DECIMAL_UPPERCASE,
/*! Scientific notation, lowercase (ex: 3.9265e+2) */
GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_LOWERCASE,
/*! Scientific notation, uppercase (ex: 3.9265E+2) */
GMIO_FLOAT_TEXT_FORMAT_SCIENTIFIC_UPPERCASE,
/*! Use the shortest representation: decimal or scientific lowercase */
GMIO_FLOAT_TEXT_FORMAT_SHORTEST_LOWERCASE,
/*! Use the shortest representation: decimal or scientific uppercase */
GMIO_FLOAT_TEXT_FORMAT_SHORTEST_UPPERCASE
};

37
src/gmio_core/zlib_compress.h
View File

@ -39,22 +39,20 @@
#include "global.h"
/*! zlib compression level, specific values */
enum gmio_zlib_compress_level
{
GMIO_ZLIB_COMPRESS_LEVEL_NONE = -1, /*! -> Z_NO_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_SIZE = 9 /*! -> Z_BEST_COMPRESSION */
enum gmio_zlib_compress_level {
GMIO_ZLIB_COMPRESS_LEVEL_NONE = -1, /*!< -> Z_NO_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_SIZE = 9 /*!< -> Z_BEST_COMPRESSION */
};
/*! zlib compression strategy */
enum gmio_zlib_compress_strategy
{
GMIO_ZLIB_COMPRESSION_STRATEGY_DEFAULT = 0, /*! -> Z_DEFAULT_STRATEGY */
GMIO_ZLIB_COMPRESSION_STRATEGY_FILTERED = 1, /*! -> Z_FILTERED */
GMIO_ZLIB_COMPRESSION_STRATEGY_HUFFMAN_ONLY = 2, /*! -> Z_HUFFMAN_ONLY */
GMIO_ZLIB_COMPRESSION_STRATEGY_RLE = 3, /*! -> Z_RLE */
GMIO_ZLIB_COMPRESSION_STRATEGY_FIXED = 4 /*! -> Z_FIXED */
enum gmio_zlib_compress_strategy {
GMIO_ZLIB_COMPRESSION_STRATEGY_DEFAULT = 0, /*!< -> Z_DEFAULT_STRATEGY */
GMIO_ZLIB_COMPRESSION_STRATEGY_FILTERED = 1, /*!< -> Z_FILTERED */
GMIO_ZLIB_COMPRESSION_STRATEGY_HUFFMAN_ONLY = 2, /*!< -> Z_HUFFMAN_ONLY */
GMIO_ZLIB_COMPRESSION_STRATEGY_RLE = 3, /*!< -> Z_RLE */
GMIO_ZLIB_COMPRESSION_STRATEGY_FIXED = 4 /*!< -> Z_FIXED */
};
/*! zlib compression options
@ -62,8 +60,7 @@ enum gmio_zlib_compress_strategy
* Initialising gmio_zlib_compress_options with \c {0} (or \c {} in C++) is the
* convenient way to set default values.
*/
struct gmio_zlib_compress_options
{
struct gmio_zlib_compress_options {
/*! Compression level.
* Use enum value from \c gmio_zlib_compress_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
* 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 */
uint8_t memory_usage;
/*! Optional pointer to a function used to allocate the internal state
* within \c z_stream structure.
/*! Optional function used to allocate the internal state within \c z_stream
* \sa z_stream::zalloc */
void* (*func_alloc)(void* opaque, unsigned int items, unsigned int size);
/*! Optional pointer to a function used to free the internal state within
* \c z_stream structure.
/*! Optional function used to free the internal state within \c z_stream
* \sa z_stream::zfree */
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 */
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 */
uint32_t triangle_count;
/*! Pointer on a function that stores the mesh triangle of index \p tri_id
* into \p triangle */
/*! Function that stores the mesh triangle of index \p tri_id into
* \p triangle */
void (*func_get_triangle)(
const void* cookie,
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) */
/*! Optional pointer on a function that handles declaration of a solid */
/*! Optional function that handles declaration of a solid */
void (*func_begin_solid)(
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
* struct gmio_stl_triangle::attribute_byte_count is meaningless for STL
@ -100,7 +100,7 @@ struct gmio_stl_mesh_creator
uint32_t tri_id,
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
* triangles have been added */