From d137aac506e0704d1602b3a436b556a23c69541b Mon Sep 17 00:00:00 2001 From: Hugues Delorme Date: Fri, 13 Mar 2015 12:19:19 +0100 Subject: [PATCH] gmio_stl: more doc --- src/gmio_stl/stl_global.h | 26 ++++++++----- src/gmio_stl/stl_io.h | 77 +++++++++++++++++++++++++++++-------- src/gmio_stl/stl_triangle.h | 23 ++++++----- 3 files changed, 91 insertions(+), 35 deletions(-) diff --git a/src/gmio_stl/stl_global.h b/src/gmio_stl/stl_global.h index 494a03c..1766ab6 100644 --- a/src/gmio_stl/stl_global.h +++ b/src/gmio_stl/stl_global.h @@ -23,17 +23,25 @@ #include "../gmio_core/global.h" #ifdef GMIO_LIBSTL_DLL -# ifdef GMIO_LIBSTL_MAKE_DLL -# define GMIO_LIBSTL_EXPORT GMIO_DECL_EXPORT -# else -# define GMIO_LIBSTL_EXPORT GMIO_DECL_IMPORT -# endif /* GMIO_DATAX_LIBSTL_MAKE_DLL */ +# ifdef GMIO_LIBSTL_MAKE_DLL +# define GMIO_LIBSTL_EXPORT GMIO_DECL_EXPORT +# else +# define GMIO_LIBSTL_EXPORT GMIO_DECL_IMPORT +# endif /* GMIO_DATAX_LIBSTL_MAKE_DLL */ #else -# define GMIO_LIBSTL_EXPORT +/*! Expands either to GMIO_DECL_EXPORT or GMIO_DECL_IMPORT when respectively + * compiling/using the DLL */ +# define GMIO_LIBSTL_EXPORT #endif /* GMIO_LIBSTL_DLL */ -/* STLB */ -enum { GMIO_STLB_HEADER_SIZE = 80 }; -enum { GMIO_STLB_MIN_CONTENTS_SIZE = 284 }; +/*! Constants for the STL binary format */ +enum { + /*! Size(in bytes) of the header data for STL binary */ + GMIO_STLB_HEADER_SIZE = 80, + + /*! Size(in bytes) of the minimum contents possible with the STL binary + * format */ + GMIO_STLB_MIN_CONTENTS_SIZE = 284 +}; #endif /* GMIO_LIBSTL_GLOBAL_H */ diff --git a/src/gmio_stl/stl_io.h b/src/gmio_stl/stl_io.h index 74b50b2..85d9aed 100644 --- a/src/gmio_stl/stl_io.h +++ b/src/gmio_stl/stl_io.h @@ -46,8 +46,7 @@ struct gmio_stla_read_options * \p stream_size is passed to gmio_transfer::handle_progress_func() as * the \p max_value argument. * - * It's defaulted to \c 0 if options argument is set to NULL (when - * calling gmio_stla_read()) + * Defaulted to \c 0 when calling gmio_stla_read() with \c options==NULL */ size_t stream_size; }; @@ -55,20 +54,34 @@ typedef struct gmio_stla_read_options gmio_stla_read_options_t; /*! Reads geometry from STL ascii stream * - * \p options should be always set to NULL (not used for the moment) + * \param mesh Defines the callbacks for the mesh creation + * \param trsf Defines needed objects for the read operation + * \param options Options for the operation, can be \c NULL to use default + * values + * + * \return Error code (see error.h and stl_error.h) */ GMIO_LIBSTL_EXPORT int gmio_stla_read(gmio_stl_mesh_creator_t* creator, gmio_transfer_t* trsf, const gmio_stla_read_options_t* options); + /*! Options for gmio_stla_write() */ struct gmio_stla_write_options { - /*! May be NULL to generate default name */ + /*! Name of the solid to appear in "solid \n facet normal ..." + * + * Defaulted to an empty string "" when : + * \li calling gmio_stla_write() with options == NULL + * \li OR solid_name == NULL + */ const char* solid_name; - /*! The maximum number of significant digits(set to 9 if options == NULL) */ + /*! The maximum number of significant digits to write float values + * + * Defaulted to \c 9 when calling gmio_stla_write() with \c options==NULL + */ uint8_t float32_prec; }; typedef struct gmio_stla_write_options gmio_stla_write_options_t; @@ -76,13 +89,12 @@ typedef struct gmio_stla_write_options gmio_stla_write_options_t; /*! Writes geometry in the STL ascii format * * \param mesh Defines the mesh to write - * \param trsf Defines needed objects (stream, buffer, ...) for the writing - * operation - * \param options Options for the writing operation, can be set to NULL to - * use default values + * \param trsf Defines needed objects for the write operation + * \param options Options for the operation, can be \c NULL to use default + * values * - * \return Error code - * \retval GMIO_NO_ERROR If operation successful + * \return Error code (see error.h and stl_error.h) + * \retval GMIO_INVALID_BUFFER_SIZE_ERROR if \c trs->buffer_size < 512 */ GMIO_LIBSTL_EXPORT int gmio_stla_write(const gmio_stl_mesh_t* mesh, @@ -96,12 +108,26 @@ int gmio_stla_write(const gmio_stl_mesh_t* mesh, /*! Options for gmio_stlb_read() */ struct gmio_stlb_read_options { - /*! Set to host byte order if not specified (ie. options == NULL) */ + /*! Byte order of the input STL binary data + * + * Defaulted to host's endianness when calling gmio_stlb_read() + * with \c options==NULL + */ gmio_endianness_t byte_order; }; typedef struct gmio_stlb_read_options gmio_stlb_read_options_t; -/*! Reads geometry from STL binary stream */ +/*! Reads geometry from STL binary stream + * + * \param mesh Defines the callbacks for the mesh creation + * \param trsf Defines needed objects for the read operation + * \param options Options for the operation, can be \c NULL to use default + * values + * + * \return Error code (see error.h and stl_error.h) + * \retval GMIO_INVALID_BUFFER_SIZE_ERRO + * if \c trs->buffer_size < GMIO_STLB_MIN_CONTENTS_SIZE + */ GMIO_LIBSTL_EXPORT int gmio_stlb_read(gmio_stl_mesh_creator_t* creator, gmio_transfer_t* trsf, @@ -111,15 +137,34 @@ int gmio_stlb_read(gmio_stl_mesh_creator_t* creator, /*! Options for gmio_stlb_write() */ struct gmio_stlb_write_options { - /*! Header data consisting of 80 bytes */ + /*! Header data consisting of 80 bytes + * + * Defaulted to an array containing 0 when : + * \li calling gmio_stlb_write() with options == NULL + * \li OR header_data == NULL + */ const uint8_t* header_data; - /*! Set to host byte order if not specified (ie. options == NULL) */ + /*! Byte order of the output STL binary data + * + * Defaulted to host's endianness when calling gmio_stlb_write() + * with \c options==NULL + */ gmio_endianness_t byte_order; }; typedef struct gmio_stlb_write_options gmio_stlb_write_options_t; -/*! Writes geometry in the STL binary format */ +/*! Writes geometry in the STL binary format + * + * \param mesh Defines the mesh to write + * \param trsf Defines needed objects for the write operation + * \param options Options for the operation, can be \c NULL to use default + * values + * + * \return Error code (see error.h and stl_error.h) + * \retval GMIO_INVALID_BUFFER_SIZE_ERRO + * if \c trs->buffer_size < GMIO_STLB_MIN_CONTENTS_SIZE + */ GMIO_LIBSTL_EXPORT int gmio_stlb_write(const gmio_stl_mesh_t* mesh, gmio_transfer_t* trsf, diff --git a/src/gmio_stl/stl_triangle.h b/src/gmio_stl/stl_triangle.h index 67538af..d7e4682 100644 --- a/src/gmio_stl/stl_triangle.h +++ b/src/gmio_stl/stl_triangle.h @@ -37,22 +37,25 @@ typedef struct gmio_stl_coords gmio_stl_coords_t; * orientation(normal) */ struct gmio_stl_triangle { - gmio_stl_coords_t normal; - gmio_stl_coords_t v1; - gmio_stl_coords_t v2; - gmio_stl_coords_t v3; + gmio_stl_coords_t normal; /*!< Normal vector */ + gmio_stl_coords_t v1; /*!< Vertex 1 */ + gmio_stl_coords_t v2; /*!< Vertex 2 */ + gmio_stl_coords_t v3; /*!< Vertex 3 */ uint16_t attribute_byte_count; /*!< Useful only for STL binary format */ }; typedef struct gmio_stl_triangle gmio_stl_triangle_t; -/*! Compact size of a gmio_stl_coords_t object */ -enum { GMIO_STL_COORDS_RAWSIZE = (3 * sizeof(gmio_float32_t)) }; +/*! Constants for STL triangles */ +enum { + /*! Compact size of a gmio_stl_coords_t object */ + GMIO_STL_COORDS_RAWSIZE = (3 * sizeof(gmio_float32_t)), -/*! Compact size of a gmio_stl_triangle_t object for STL ascii format */ -enum { GMIO_STLA_TRIANGLE_RAWSIZE = (4 * GMIO_STL_COORDS_RAWSIZE) }; + /*! Compact size of a gmio_stl_triangle_t object for STL ascii format */ + GMIO_STLA_TRIANGLE_RAWSIZE = (4 * GMIO_STL_COORDS_RAWSIZE), -/*! Compact size of a gmio_stl_triangle_t object for STL binary format */ -enum { GMIO_STLB_TRIANGLE_RAWSIZE = (GMIO_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t)) }; + /*! Compact size of a gmio_stl_triangle_t object for STL binary format */ + GMIO_STLB_TRIANGLE_RAWSIZE = (GMIO_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t)) +}; #endif /* GMIO_LIBSTL_TRIANGLE_H */