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

Improve doc

Browse Source
This commit is contained in:
Hugues Delorme 2016-04-27 16:11:00 +02:00
parent 109e3143d6
commit ee5c908bb7
9 changed files with 172 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -15,10 +15,10 @@ C library for geometry input/output
=========================================== ===========================================
gmio is a reusable C library providing complete I/O support for various CAD file gmio is a reusable C library providing complete I/O support for various CAD file
formats (eg. [STL](https://en.wikipedia.org/wiki/STL_%28file_format%29)) formats(eg. [STL](https://en.wikipedia.org/wiki/STL_%28file_format%29))
gmio aims to be [fast](https://github.com/fougue/gmio/wiki/4.-Benchmarks), gmio aims to be [fast](https://github.com/fougue/gmio/wiki/4.-Benchmarks),
portable (C90 conformance) and feature-rich. portable(C90 conformance) and feature-rich.
Main highlights: Main highlights:
@ -32,25 +32,9 @@ Main highlights:
Supported CAD files format Supported CAD files format
========================== ==========================
Current version only supports the STL file format (STereoLithography), but Current version only supports the STL file format(STereoLithography) but
support is complete : support is complete, see module
[gmio_stl](http://www.fougue.pro/docs/gmio/group__gmio__stl.html#details)
* [x] ASCII format: Case-insensitive reading
* [x] ASCII format: Output format(%f, %e, ...) and precision of floats support
* [x] Binary format: Little/big endian support
* [x] Binary format: 80-byte header and facet "attribute byte count" support
* [x] Detection of the input format
* [x] Retrieval of infomations about contents(facet count, solid name, ...)
* [x] Multiple solids from stream(eg. 4 solids in STL ascii file)
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)
and [MeshVS_DataSource](http://dev.opencascade.org/doc/refman/html/class_mesh_v_s___data_source.html)
in gmio
Building gmio Building gmio
@ -102,4 +86,4 @@ as circulated by CEA, CNRS and INRIA
Credits Credits
======= =======
"gmio" logo rendered with Prism font (thanks to Erik Yin !) "gmio" logo rendered with Prism font(thanks to Erik Yin !)

2
doc/Doxyfile.cmake
View File

@ -674,7 +674,7 @@ RECURSIVE = YES
# Note that relative paths are relative to the directory from which doxygen is # Note that relative paths are relative to the directory from which doxygen is
# run. # run.
EXCLUDE = EXCLUDE = @CMAKE_CURRENT_SOURCE_DIR@/../src/gmio_support/stl_occ_utils.h
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded # directories that are symbolic links (a Unix file system feature) are excluded

27
doc/mainpage.dox
View File

@ -3,13 +3,13 @@
\section intro Introduction \section intro Introduction
gmio is a reusable C library providing complete I/O support for various CAD gmio is a reusable C library providing complete I/O support for various CAD
file formats (eg. <a href="https://en.wikipedia.org/wiki/STL_%28file_format%29">STL</a>) file formats(eg. <a href="https://en.wikipedia.org/wiki/STL_%28file_format%29">STL</a>)
gmio aims to be <a href="https://github.com/fougue/gmio/wiki/4.-Benchmarks">fast</a>, gmio aims to be <a href="https://github.com/fougue/gmio/wiki/4.-Benchmarks">fast</a>,
portable (C90 conformance) and feature-rich. portable(C90 conformance) and feature-rich.
Main highlights: Main highlights:
\li <i>Abstract</i> streams that does not tie the user to C stream (\c FILE*) \li <i>Abstract</i> streams that does not tie the user to C stream(\c FILE*)
\li Buffering of input/ouput for efficient device usage \li Buffering of input/ouput for efficient device usage
\li Operations can be easily aborted \li Operations can be easily aborted
\li Progress report about the I/O operation \li Progress report about the I/O operation
@ -17,23 +17,8 @@
\section sup_cadf Supported CAD files format \section sup_cadf Supported CAD files format
Current version only supports the STL file format (STereoLithography), but Current version only supports the STL file format(STereoLithography) but
support is complete : support is complete, see module \ref gmio_stl
\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 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 \c StlMesh_Mesh and \c MeshVS_DataSource in
gmio(see \c gmio_support)
\section build Building gmio \section build Building gmio
@ -66,7 +51,7 @@ license as circulated by CEA, CNRS and INRIA at this
\section creds Credits \section creds Credits
"gmio" logo rendered with Prism font (thanks to Erik Yin !) "gmio" logo rendered with Prism font(thanks to Erik Yin !)
*/ */

38
src/gmio_core/memblock.h
View File

@ -27,7 +27,21 @@
#include <stddef.h> #include <stddef.h>
/*! Basic memory block */ /*! Basic memory block
*
* gmio_memblock comes with convenient constructors that binds to
* <tt><stdlib.h></tt> allocation functions, like gmio_memblock_malloc(), ...
*
* Binding gmio_memblock to some statically-allocated memory is done through
* gmio_memblock() :
* \code{.c}
* char buff[512] = {};
* struct gmio_memblock blk =
* gmio_memblock(buff, GMIO_ARRAY_SIZE(buff), NULL);
* \endcode
*
* Any gmio_memblock object can be safely freed with gmio_memblock_deallocate()
*/
struct gmio_memblock struct gmio_memblock
{ {
/*! Pointer to the beginning of the memory block */ /*! Pointer to the beginning of the memory block */
@ -37,7 +51,10 @@ struct gmio_memblock
size_t size; size_t size;
/*! Optional pointer on a function that deallocates the memory block /*! Optional pointer on a function that deallocates the memory block
* beginning at \p ptr */ * beginning at \p ptr
*
* \sa gmio_memblock_deallocate()
*/
void (*func_deallocate)(void* ptr); void (*func_deallocate)(void* ptr);
}; };
@ -53,13 +70,22 @@ GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
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 gmio_memblock object allocated with standard \c malloc() */ /*! Returns a gmio_memblock object allocated with standard \c malloc()
*
* 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 gmio_memblock object allocated with standard \c calloc() */ /*! Returns a gmio_memblock object allocated with standard \c calloc()
*
* 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 gmio_memblock object allocated with standard \c realloc() */ /*! Returns a gmio_memblock object allocated with standard \c realloc()
*
* 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() */
@ -75,7 +101,7 @@ 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
* *
* The constructor function allocates a gmio_memblock object on demand, to be * The constructor function allocates a gmio_memblock object on demand, to be
* used when a temporary mblock is needed. * used when a temporary memblock is needed.
* *
* This function is not thread-safe. * This function is not thread-safe.
*/ */

66
src/gmio_stl/stl_global.h
View File

@ -19,22 +19,20 @@
* \defgroup gmio_stl gmioSTL * \defgroup gmio_stl gmioSTL
* Provides API to handle input/output operations with the STL file format * Provides API to handle input/output operations with the STL file format
* *
* Support of the STL file format (STereoLithography) is complete : * Support of the STL file format(STereoLithography) is complete :
*
* \li ASCII format: Case-insensitive reading * \li ASCII format: Case-insensitive reading
* \li ASCII format: Output format(\%f, \%e, ...) and precision of floats support * \li ASCII format: Support of output format(<tt>\%f</tt>, <tt>\%e</tt>, ...)
* \li Binary format: Little/big endian support * and precision of floats
* \li Binary format: 80-byte header and facet "attribute byte count" support * \li Binary format: Support of little/big endian
* \li Binary format: Support of 80-byte header and facet "attribute byte count"
* \li Support of multiple solids from stream(eg. 4 solids in STL ascii file)
* \li Detection of the input format * \li Detection of the input format
* \li Retrieval of infomations about contents(facet count, solid name, ...) * \li Retrieval of infomations about contents
* \li Multiple solids from stream(eg. 4 solids in STL ascii file)
* *
* In addition, the gmioSTL module has the following advatanges: * In addition, the gmioSTL module has the following advatanges:
* * \li The user keeps its own geometry data structures, no conversion needed.
* \li The user keeps its own geometry data structures, no conversion needed
* \li Fixed memory consumption and independant of the mesh size * \li Fixed memory consumption and independant of the mesh size
* \li Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in * \li Seamless use of OpenCascade in gmio(see \ref gmio_support module)
* gmio(see \c gmioSupport module)
* *
* In this module, the name of all entities(structures, functions, ...) are * In this module, the name of all entities(structures, functions, ...) are
* prefixed either with : * prefixed either with :
@ -42,6 +40,52 @@
* \li <tt>gmio_stla</tt>, this applies only for STL ascii * \li <tt>gmio_stla</tt>, this applies only for STL ascii
* \li <tt>gmio_stlb</tt>, this applies only for STL binary(little/big endian) * \li <tt>gmio_stlb</tt>, this applies only for STL binary(little/big endian)
* *
* <table>
* <tr>
* <th></th> <th>Functions</th> <th>Structures</th>
* </tr>
* <tr>
* <td>Read</td>
* <td>gmio_stl_read()<br/>
* gmio_stl_read_file()<br/>
* gmio_stla_read()<br/>
* gmio_stlb_read()</td>
* <td>gmio_stl_read_options<br/>
* gmio_stl_mesh_creator<br/>
* gmio_stl_mesh_creator_infos<br/>
* gmio_stlb_header</td>
* </tr>
* <tr>
* <td>Write</td>
* <td>gmio_stl_write()<br/>
* gmio_stl_write_file()<br/>
* gmio_stlb_header_write()</td>
* <td>gmio_stl_write_options<br/>
* gmio_stl_mesh<br/>
* gmio_stlb_header</td>
* </tr>
* <tr>
* <td>Infos on contents</td>
* <td>gmio_stl_infos_get()<br/>
* gmio_stla_infos_get_streamsize()</td>
* <td>gmio_stl_infos<br/>
* gmio_stl_infos_get_options</td>
* </tr>
* <tr>
* <td>Detect format</td>
* <td>gmio_stl_format_probe()<br/>
* gmio_stl_format_probe_file()</td>
* <td></td>
* </tr>
* <tr>
* <td>Utilities</td>
* <td>gmio_stl_triangle_compute_normal()<br/>
* gmio_stlb_header_str()<br/>
* gmio_stlb_header_to_printable_str()</td>
* <td>gmio_stl_triangle</td>
* </tr>
* </table>
*
* \addtogroup gmio_stl * \addtogroup gmio_stl
* @{ * @{
*/ */

2
src/gmio_stl/stl_infos.h
View File

@ -93,7 +93,7 @@ enum gmio_stl_info_flag
/*! Options of function gmio_stl_infos_get() */ /*! Options of function gmio_stl_infos_get() */
struct gmio_stl_infos_get_options struct gmio_stl_infos_get_options
{ {
/*! See gmio_core_readwrite_options::stream_memblock */ /*! See gmio_stl_read_options::stream_memblock */
struct gmio_memblock stream_memblock; struct gmio_memblock stream_memblock;
/*! Assume STL input format, if GMIO_STL_FORMAT_UNKNOWN then it is /*! Assume STL input format, if GMIO_STL_FORMAT_UNKNOWN then it is

4
src/gmio_stl/stl_io.h
View File

@ -35,6 +35,10 @@
GMIO_C_LINKAGE_BEGIN GMIO_C_LINKAGE_BEGIN
/*! Reads STL mesh from stream, format is automatically guessed /*! Reads STL mesh from stream, format is automatically guessed
*
* The user mesh is created sequentially by calling
* gmio_stl_mesh_creator::func_add_triangle() with each triangle read from
* the stream.
* *
* It does nothing on the triangles read : no checking(eg. for Nan values), * It does nothing on the triangles read : no checking(eg. for Nan values),
* normals are given as they are. * normals are given as they are.

2
src/gmio_support/stl_occ_meshvs.h
View File

@ -61,7 +61,7 @@ gmio_stl_mesh gmio_stl_occmesh(const gmio_stl_occmesh_datasource_iterator& it);
struct gmio_stl_occmesh_datasource_iterator struct gmio_stl_occmesh_datasource_iterator
{ {
gmio_stl_occmesh_datasource_iterator(); gmio_stl_occmesh_datasource_iterator();
explicit gmio_stl_occmesh_datasource_iterator(const MeshVS_DataSource* data_src); explicit gmio_stl_occmesh_datasource_iterator(const MeshVS_DataSource* ds);
explicit gmio_stl_occmesh_datasource_iterator(const Handle_MeshVS_DataSource& hnd); explicit gmio_stl_occmesh_datasource_iterator(const Handle_MeshVS_DataSource& hnd);
inline const MeshVS_DataSource* data_src() const { return m_data_src; } inline const MeshVS_DataSource* data_src() const { return m_data_src; }

73
src/gmio_support/support_global.h
View File

@ -22,14 +22,55 @@
* \c gmioSupport is the bridge between \c gmio and other 3rd-party libraries * \c gmioSupport is the bridge between \c gmio and other 3rd-party libraries
* (eg. OpenCascade, Qt, ...)\n * (eg. OpenCascade, Qt, ...)\n
* *
* STL * <table> <caption>OpenCascade support</caption>
* import | export * <tr> <th></th> <th colspan="3">STL</th> </tr>
* StlMesh_Mesh yes yes * <tr> <td></td> <th>import</th> <th>export</th> <th>header</th> </tr>
* MeshVS_DataSource no yes * <tr>
* TopoDS_Shape no yes * <td>StlMesh_Mesh</td>
* <td style="color:green">yes</td>
* <td style="color:green">yes</td>
* <td>stl_occ_mesh.h</td>
* </tr>
* <tr>
* <td>MeshVS_DataSource</td>
* <td style="color:red">no</td>
* <td style="color:green">yes</td>
* <td>stl_occ_meshvs.h</td>
* </tr>
* <tr>
* <td>TopoDS_Shape</td>
* <td style="color:red">no</td>
* <td style="color:green">yes</td>
* <td>stl_occ_brep.h</td>
* </tr>
* </table>
* *
* Nonetheless, to avoid the \c gmio library being dependent of some other * \n
* binaries, compilation of \c gmioSupport is left to the developer.\n *
* <table> <caption>I/O stream support</caption>
* <tr> <th></th> <th>read</th> <th>write</th> <th>header</th> </tr>
* <tr>
* <td>Qt QIODevice</td>
* <td style="color:green">yes</td>
* <td style="color:green">yes</td>
* <td>stream_qt.h</td>
* </tr>
* <tr>
* <td>std::basic_istream<></td>
* <td style="color:green">yes</td>
* <td style="color:red">no</td>
* <td>stream_cpp.h</td>
* </tr>
* <tr>
* <td>std::basic_ostream<></td>
* <td style="color:red">no</td>
* <td style="color:green">yes</td>
* <td>stream_cpp.h</td>
* </tr>
* </table>
*
* To avoid the dependency of \c gmio library on 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 * For example if Qt streams are needed then the target project must build
* somehow <tt>gmio_support/stream_qt.cpp</tt>\n * somehow <tt>gmio_support/stream_qt.cpp</tt>\n
* All \c gmio_support source files are copied with install target (ie by doing * All \c gmio_support source files are copied with install target (ie by doing
@ -39,6 +80,24 @@
* @{ * @{
*/ */
/*
* OpenCascade support :
* | | STL |
* | | import | export |
* |-------------------|--------|--------|
* | StlMesh_Mesh | yes | yes |
* | MeshVS_DataSource | no | yes |
* | TopoDS_Shape | no | yes |
*
* I/O stream support :
* | | read | write |
* |----------------------|------|-------|
* | Qt QIODevice | yes | yes |
* | std::basic_istream<> | yes | no |
* | std::basic_ostream<> | no | yes |
*
*/
#ifndef GMIO_SUPPORT_GLOBAL_H #ifndef GMIO_SUPPORT_GLOBAL_H
#define GMIO_SUPPORT_GLOBAL_H #define GMIO_SUPPORT_GLOBAL_H