diff --git a/README.md b/README.md index cec0f27..bd3ce8b 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,10 @@ In addition, the STL module has the following advatanges: * [x] The user keeps its own geometry data structures, no mesh conversion needed * [x] Fixed memory consumption and independant of the mesh size - * [x] Seamless use of [OpenCascade StlMesh_Mesh](http://dev.opencascade.org/doc/refman/html/class_stl_mesh___mesh.html) - in gmio(see gmio_support) + * [x] Seamless use of OpenCascade + [StlMesh_Mesh](http://dev.opencascade.org/doc/refman/html/class_stl_mesh___mesh.html) + and [MeshVS_DataSource](http://dev.opencascade.org/doc/refman/html/class_mesh_v_s___data_source.html) + in gmio Building gmio diff --git a/doc/Doxyfile.cmake b/doc/Doxyfile.cmake index 55195e1..c921930 100644 --- a/doc/Doxyfile.cmake +++ b/doc/Doxyfile.cmake @@ -45,7 +45,7 @@ PROJECT_BRIEF = "Fast, portable C library for geometry input/output" # exceed 55 pixels and the maximum width should not exceed 200 pixels. # Doxygen will copy the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = @CMAKE_CURRENT_SOURCE_DIR@/../doc/gmio.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. @@ -867,13 +867,13 @@ HTML_FILE_EXTENSION = .html # have to redo this when upgrading to a newer version of doxygen or when # changing the value of configuration settings such as GENERATE_TREEVIEW! -HTML_HEADER = +HTML_HEADER = @CMAKE_CURRENT_SOURCE_DIR@/../doc/header.html # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a # standard footer. -HTML_FOOTER = +HTML_FOOTER = @CMAKE_CURRENT_SOURCE_DIR@/../doc/footer.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading # style sheet that is used by each HTML page. It can be used to diff --git a/doc/footer.html b/doc/footer.html new file mode 100644 index 0000000..1e42d32 --- /dev/null +++ b/doc/footer.html @@ -0,0 +1,26 @@ + + + + + + + +
+ + + + +
Fougue © 2016 +
Last Update: $date
+
+ + + + diff --git a/doc/header.html b/doc/header.html new file mode 100644 index 0000000..90370dc --- /dev/null +++ b/doc/header.html @@ -0,0 +1,55 @@ + + + + + + + +$projectname: $title +$title + + + +$treeview +$search +$mathjax + +$extrastylesheet + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + +
+
+  v$projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
+
+ + diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 5a2ef86..091b166 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -9,7 +9,7 @@ portable (C90 conformance) and feature-rich. Main highlights: - \li "Abstract" streams that does not tie the user to C stream (\c FILE*) + \li Abstract streams that does not tie the user to C stream (\c FILE*) \li Buffering of input/ouput for efficient device usage \li Operations can be easily aborted \li Progress report about the I/O operation @@ -21,7 +21,7 @@ Current version only supports the STL file format (STereoLithography), but support is complete : \li ASCII format: Case-insensitive reading - \li ASCII format: Output format(%f, %e, ...) and precision of floats support + \li ASCII format: Output format(\%f, \%e, ...) and precision of floats support \li Binary format: Little/big endian support \li Binary format: 80-byte header and facet "attribute byte count" support \li Detection of the input format @@ -32,7 +32,8 @@ In addition, the STL module has the following advatanges: \li The user keeps its own geometry data structures, no conversion needed \li Fixed memory consumption and independant of the mesh size - \li Seamless use of OpenCascade StlMesh_Mesh in gmio(see gmio_support) + \li Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in + gmio(see \c gmio_support) \section build Building gmio diff --git a/src/gmio_core/global.h b/src/gmio_core/global.h index a107ee3..bc058a8 100644 --- a/src/gmio_core/global.h +++ b/src/gmio_core/global.h @@ -188,7 +188,7 @@ enum gmio_bool_value /*! MSVC specific macro that disable the compiler warning of code \p __code__ * * With Visual C++, expands to : - * \code + * \code{.c} * #pragma warning(push) * #pragma warning(disable: __code__) * \endcode @@ -197,7 +197,7 @@ enum gmio_bool_value /*! MSVC specific macro that pop the changes made after last warning(pop) * * With Visual C++, expands to : - * \code + * \code{.c} * #pragma warning(pop) * \endcode */ diff --git a/src/gmio_core/internal/string.h b/src/gmio_core/internal/string.h index b7dcda7..a8e6efd 100644 --- a/src/gmio_core/internal/string.h +++ b/src/gmio_core/internal/string.h @@ -45,7 +45,7 @@ struct gmio_string /*! Expands to bracket initialization of a gmio_const_string from const char[] * * Example: - * \code + * \code{.c} * static const char token[] = "woops"; * struct gmio_const_string token_s = GMIO_CONST_STRING_FROM_ARRAY(token); * \endcode diff --git a/src/gmio_core/memblock.h b/src/gmio_core/memblock.h index 71e19d4..10369e2 100644 --- a/src/gmio_core/memblock.h +++ b/src/gmio_core/memblock.h @@ -68,7 +68,7 @@ GMIO_API void gmio_memblock_deallocate(struct gmio_memblock* mblock); /*! Typedef for a pointer to a function that creates an allocated mblock * * Signature: - * \code struct gmio_memblock mblock_ctor(); \endcode + * \code{.c} struct gmio_memblock mblock_ctor(); \endcode */ typedef struct gmio_memblock (*gmio_memblock_constructor_func_t)(); diff --git a/src/gmio_stl/stl_global.h b/src/gmio_stl/stl_global.h index 9a9036e..28ae252 100644 --- a/src/gmio_stl/stl_global.h +++ b/src/gmio_stl/stl_global.h @@ -19,6 +19,29 @@ * \defgroup gmio_stl gmioSTL * Provides API to handle input/output operations with the STL file format * + * Support of the STL file format (STereoLithography) is complete : + * + * \li ASCII format: Case-insensitive reading + * \li ASCII format: Output format(\%f, \%e, ...) and precision of floats support + * \li Binary format: Little/big endian support + * \li Binary format: 80-byte header and facet "attribute byte count" support + * \li Detection of the input format + * \li Retrieval of infomations about contents(facet count, solid name, ...) + * \li Multiple solids from stream(eg. 4 solids in STL ascii file) + * + * In addition, the gmioSTL module has the following advatanges: + * + * \li The user keeps its own geometry data structures, no conversion needed + * \li Fixed memory consumption and independant of the mesh size + * \li Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in + * gmio(see \c gmioSupport module) + * + * In this module, the name of all entities(structures, functions, ...) are + * prefixed either with : + * \li \c gmio_stl + * \li gmio_stla, this applies only for STL ascii + * \li gmio_stlb, this applies only for STL binary(little/big endian) + * * \addtogroup gmio_stl * @{ */ diff --git a/src/gmio_stl/stl_infos.h b/src/gmio_stl/stl_infos.h index 6dff983..e17536e 100644 --- a/src/gmio_stl/stl_infos.h +++ b/src/gmio_stl/stl_infos.h @@ -48,12 +48,15 @@ struct gmio_stl_infos /*! STL ascii only: name of the solid * - * The pointer has to be set before calling gmio_stl_infos_get() */ + * The pointer has to be set before calling gmio_stl_infos_get() + * \sa stla_solidname_maxlen + */ char* stla_solidname; /*! STL ascii only: maximum length(capacity) of stla_solidname * * The value has to be set before calling gmio_stl_infos_get() + * \sa stla_solidname */ size_t stla_solidname_maxlen; @@ -108,10 +111,15 @@ GMIO_C_LINKAGE_BEGIN /*! Finds informations about STL contents * - * \p infos is an output parameter that will hold the retrieved infos + * \p infos is an output parameter that will hold the retrieved informations * * \p flags is a bitor combination of \c gmio_stl_info_flag values and is used - * to select the infos to retrieve. + * to select the informations to retrieve. + * + * \pre infos != NULL + * \pre stream != NULL + * + * \p options can be safely set to \c NULL in this case default values are used * * \return Error code (see gmio_core/error.h and stl_error.h) */ @@ -129,6 +137,9 @@ GMIO_API int gmio_stl_infos_get( * gmio_stl_read_options::func_stla_get_streamsize() and is useful when * reading in sequence multi solids in STL ascii. The stream can be cleanly * advanced solid by solid after each call to gmio_stl_read() + * + * \pre stream != NULL + * \pre stream_memblock != NULL */ GMIO_API gmio_streamsize_t gmio_stla_infos_get_streamsize( struct gmio_stream* stream, diff --git a/src/gmio_stl/stl_io.h b/src/gmio_stl/stl_io.h index 3ca23b4..85c2e4d 100644 --- a/src/gmio_stl/stl_io.h +++ b/src/gmio_stl/stl_io.h @@ -36,8 +36,13 @@ GMIO_C_LINKAGE_BEGIN /*! Reads STL mesh from stream, format is automatically guessed * - * It does nothing on the triangles read : no checking(eg. for Nan), normals - * are given as they are. + * It does nothing on the triangles read : no checking(eg. for Nan values), + * normals are given as they are. + * + * \pre stream != NULL + * \pre mesh_creator != NULL + * + * \p options may be \c NULL in this case default values are used * * \return Error code (see gmio_core/error.h and stl_error.h) */ @@ -51,8 +56,14 @@ GMIO_API int gmio_stl_read( * This is just a facility function over gmio_stl_read(). The internal stream * object is created to read file at \p filepath. * - * The file is opened with \c fopen() so \p filepath shall follow the file name - * specifications of the running environment + * \pre filepath != \c NULL \n + * The file is opened with \c fopen() so \p filepath shall follow the file + * name specifications of the running environment + * \pre mesh_creator != NULL + * + * \p options may be \c NULL in this case default values are used + * + * \return Error code (see gmio_core/error.h and stl_error.h) * * \sa gmio_stream_stdio(FILE*) */ @@ -62,6 +73,11 @@ GMIO_API int gmio_stl_read_file( const struct gmio_stl_read_options* options); /*! Reads mesh from STL ascii stream + * + * \pre stream != NULL + * \pre mesh_creator != NULL + * + * \p options may be \c NULL in this case default values are used * * \return Error code (see gmio_core/error.h and stl_error.h) */ @@ -71,6 +87,11 @@ GMIO_API int gmio_stla_read( const struct gmio_stl_read_options* options); /*! Reads mesh from STL binary stream + * + * \pre stream != NULL + * \pre mesh_creator != NULL + * + * \p options may be \c NULL in this case default values are used * * \return Error code (see gmio_core/error.h and stl_error.h) * \retval GMIO_ERROR_INVALID_MEMBLOCK_SIZE @@ -83,6 +104,11 @@ GMIO_API int gmio_stlb_read( const struct gmio_stl_read_options* options); /*! Writes STL mesh to stream + * + * \pre stream != NULL + * \pre mesh != NULL + * + * \p options may be \c NULL in this case default values are used * * \return Error code (see gmio_core/error.h and stl_error.h) */ @@ -97,8 +123,10 @@ GMIO_API int gmio_stl_write( * This is just a facility function over gmio_stl_write(). The internal stream * object is created to read file at \p filepath * - * The file is opened with \c fopen() so \p filepath shall follow the file name - * specifications of the running environment + * \pre filepath != \c NULL \n + * The file is opened with \c fopen() so \p filepath shall follow the file + * name specifications of the running environment + * \pre mesh != NULL * * \return Error code (see gmio_core/error.h and stl_error.h) * @@ -113,11 +141,13 @@ GMIO_API int gmio_stl_write_file( /*! Writes STL binary header data to stream * * This functions only writes the 80-bytes header array and the count of facets - * in the mesh(with respect of the specified byte order). + * of the mesh(with respect of the specified byte order). + * + * \pre stream != NULL * * \p header Can be safely set to \c NULL to generate an array of zeroes * - * \return Error code (see error.h and stl_error.h) + * \return Error code (see gmio_core/error.h and stl_error.h) */ GMIO_API int gmio_stlb_header_write( struct gmio_stream* stream, diff --git a/src/gmio_stl/stl_mesh.h b/src/gmio_stl/stl_mesh.h index e05a478..d97a83e 100644 --- a/src/gmio_stl/stl_mesh.h +++ b/src/gmio_stl/stl_mesh.h @@ -39,7 +39,9 @@ struct gmio_stl_mesh /*! Pointer on a 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, struct gmio_stl_triangle* triangle); + const void* cookie, + uint32_t tri_id, + struct gmio_stl_triangle* triangle); }; #endif /* GMIO_STL_MESH_H */ diff --git a/src/gmio_stl/stl_mesh_creator.h b/src/gmio_stl/stl_mesh_creator.h index 0d4c74d..82d74f0 100644 --- a/src/gmio_stl/stl_mesh_creator.h +++ b/src/gmio_stl/stl_mesh_creator.h @@ -67,7 +67,7 @@ struct gmio_stl_mesh_creator_infos }; /*! Provides an interface for the creation of the underlying(hidden) - * user mesh */ + * user mesh */ struct gmio_stl_mesh_creator { /*! Opaque pointer on the user mesh, passed as first argument to hook @@ -93,9 +93,9 @@ struct gmio_stl_mesh_creator uint32_t tri_id, const struct gmio_stl_triangle* triangle); - /*! Pointer on a function that finalizes creation of the user mesh + /*! Optional pointer on a function that finalizes creation of the user mesh * - * Optional function 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 */ void (*func_end_solid)(void* cookie); diff --git a/src/gmio_stl/stlb_header.c b/src/gmio_stl/stlb_header.c index 9af17ae..4357df7 100644 --- a/src/gmio_stl/stlb_header.c +++ b/src/gmio_stl/stlb_header.c @@ -33,8 +33,9 @@ void gmio_stlb_header_to_printable_str( { size_t i; for (i = 0; i < GMIO_STLB_HEADER_SIZE; ++i) { - const int header_char = (int)header->data[i]; - str[i] = isprint(header_char) ? (char)header_char : replacement; + const char hc = header->data[i]; + const int hi = (int)hc; + str[i] = isprint(hi) ? hc : replacement; } str[GMIO_STLB_HEADER_SIZE] = 0; } diff --git a/src/gmio_stl/stlb_header.h b/src/gmio_stl/stlb_header.h index 46918ad..f279b68 100644 --- a/src/gmio_stl/stlb_header.h +++ b/src/gmio_stl/stlb_header.h @@ -46,6 +46,7 @@ GMIO_API struct gmio_stlb_header gmio_stlb_header_str(const char* str); /*! Copies \p header into C string \p str * * It replaces non-printable bytes with \p replacement char. + * * \p str must be at least \c GMIO_STLB_HEADER_SIZE+1 long, a terminating null * character ('\0') is copied at position \c GMIO_STLB_HEADER_SIZE */ diff --git a/src/gmio_support/stl_occ.h b/src/gmio_support/stl_occ.h index 105fd35..1a82522 100644 --- a/src/gmio_support/stl_occ.h +++ b/src/gmio_support/stl_occ.h @@ -50,7 +50,7 @@ class MeshVS_DataSource; * It is used to iterate efficiently over the triangles of all domains within * a StlMesh_Mesh object. * - * You don't have to use API of this class, it's intended to gmio_stl_mesh() + * Don't use API of this class, it's intended to gmio_stl_mesh() */ struct gmio_stl_occmesh_iterator { @@ -76,12 +76,13 @@ private: uint32_t m_domain_last_tri_id; }; -/*! Returns a gmio_stl_mesh mapped to the OCC mesh in iterator \p it +/*! Returns a gmio_stl_mesh mapped to the OpenCascade mesh in iterator \p it * * The mesh's cookie will point to \c &it so the lifescope of the corresponding * object must be at least as longer as the returned gmio_stl_mesh. + * * Example of use: - * \code + * \code{.cpp} * Handle_StlMesh_Mesh occmesh = ...; * const gmio_stl_occmesh_iterator it(occmesh); * const gmio_stl_mesh mesh = gmio_stl_occmesh(it); @@ -97,7 +98,7 @@ gmio_stl_mesh gmio_stl_occmesh(const gmio_stl_occmesh_iterator& it); * object.\n * Each element should be of type MeshVS_ET_Face and made of 3 nodes. * - * You don't have to use API of this class, it's intended to gmio_stl_mesh() + * Don't use API of this class, it's intended to gmio_stl_mesh() */ struct gmio_stl_occmesh_datasource_iterator { @@ -116,12 +117,14 @@ private: TColStd_Array1OfReal m_element_coords; }; -/*! Returns a gmio_stl_mesh mapped to the OCC mesh data-source in iterator \p it +/*! Returns a gmio_stl_mesh mapped to the OpenCascade mesh data-source in + * iterator \p it * * The mesh's cookie will point to \c &it so the lifescope of the corresponding * object must be at least as longer as the returned gmio_stl_mesh. + * * Example of use: - * \code + * \code{.cpp} * Handle_MeshVS_Mesh mesh = ...; * const gmio_stl_occmesh_datasource_iterator it(mesh->GetDataSource()); * const gmio_stl_mesh mesh = gmio_stl_occmesh(it); diff --git a/src/gmio_support/support_global.h b/src/gmio_support/support_global.h index 0022048..09bb889 100644 --- a/src/gmio_support/support_global.h +++ b/src/gmio_support/support_global.h @@ -19,6 +19,15 @@ * \defgroup gmio_support gmioSupport * Provides seamless integration with other 3rd-party libraries * + * \c gmioSupport is the bridge between \c gmio and other 3rd-party libraries + * (eg. OpenCascade, Qt, ...)\n + * Nonetheless, to avoid the \c gmio library being dependent of some other + * binaries, compilation of \c gmioSupport is left to the developer.\n + * For example if Qt streams are needed then the target project must build + * somehow gmio_support/stream_qt.cpp\n + * All \c gmio_support source files are copied with install target (ie by doing + * (n)make install) to PREFIX/src/gmio_support + * * \addtogroup gmio_support * @{ */