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
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),
portable (C90 conformance) and feature-rich.
portable(C90 conformance) and feature-rich.
Main highlights:
@ -32,25 +32,9 @@ Main highlights:
Supported CAD files format
==========================
Current version only supports the STL file format (STereoLithography), but
support is complete :
* [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
Current version only supports the STL file format(STereoLithography) but
support is complete, see module
[gmio_stl](http://www.fougue.pro/docs/gmio/group__gmio__stl.html#details)
Building gmio
@ -102,4 +86,4 @@ as circulated by CEA, CNRS and INRIA
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
# 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
# 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
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>,
portable (C90 conformance) and feature-rich.
portable(C90 conformance) and feature-rich.
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 Operations can be easily aborted
\li Progress report about the I/O operation
@ -17,23 +17,8 @@
\section sup_cadf Supported CAD files format
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 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)
Current version only supports the STL file format(STereoLithography) but
support is complete, see module \ref gmio_stl
\section build Building gmio
@ -66,7 +51,7 @@ license as circulated by CEA, CNRS and INRIA at this
\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>
/*! 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
{
/*! Pointer to the beginning of the memory block */
@ -37,7 +51,10 @@ struct gmio_memblock
size_t size;
/*! 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);
};
@ -53,13 +70,22 @@ GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
GMIO_API struct gmio_memblock gmio_memblock(
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);
/*! 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);
/*! 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);
/*! 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
*
* 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.
*/

66
src/gmio_stl/stl_global.h
View File

@ -19,22 +19,20 @@
* \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 :
*
* 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 ASCII format: Support of output format(<tt>\%f</tt>, <tt>\%e</tt>, ...)
* and precision of floats
* \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 Retrieval of infomations about contents(facet count, solid name, ...)
* \li Multiple solids from stream(eg. 4 solids in STL ascii file)
* \li Retrieval of infomations about contents
*
* 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 Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in
* gmio(see \c gmioSupport module)
* \li Seamless use of OpenCascade in gmio(see \ref gmio_support module)
*
* In this module, the name of all entities(structures, functions, ...) are
* prefixed either with :
@ -42,6 +40,52 @@
* \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)
*
* <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
* @{
*/

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() */
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;
/*! 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
/*! 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),
* 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
{
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);
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
* (eg. OpenCascade, Qt, ...)\n
*
* STL
* import | export
* StlMesh_Mesh yes yes
* MeshVS_DataSource no yes
* TopoDS_Shape no yes
* <table> <caption>OpenCascade support</caption>
* <tr> <th></th> <th colspan="3">STL</th> </tr>
* <tr> <td></td> <th>import</th> <th>export</th> <th>header</th> </tr>
* <tr>
* <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
* binaries, compilation of \c gmioSupport is left to the developer.\n
* \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
* somehow <tt>gmio_support/stream_qt.cpp</tt>\n
* 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
#define GMIO_SUPPORT_GLOBAL_H