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

More doc

Browse Source
This commit is contained in:
Hugues Delorme 2016-04-06 17:33:05 +02:00
parent 4a2322132d
commit 911825e1c3
17 changed files with 199 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -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

6
doc/Doxyfile.cmake
View File

@ -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

26
doc/footer.html Normal file
View File

@ -0,0 +1,26 @@
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
$navpath
<li class="footer">$generatedby
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
</ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<table style="width:100%">
<hr class="footer"/>
<tr>
<td align="left">Fougue © 2016</td>
<td>
<address class="footer"><small>Last Update: $date</small></address>
</td>
</tr>
</table>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>

55
doc/header.html Normal file
View File

@ -0,0 +1,55 @@
<!-- HTML header for doxygen 1.8.8-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<!--BEGIN PROJECT_LOGO-->
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
<!--END PROJECT_LOGO-->
<!--BEGIN PROJECT_NAME-->
<td style="padding-left: 0.5em;">
<div id="projectname">
<!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">v$projectnumber</span><!--END PROJECT_NUMBER-->
</div>
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
</td>
<!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME-->
<!--BEGIN PROJECT_BRIEF-->
<td style="padding-left: 0.5em;">
<div id="projectbrief">$projectbrief</div>
</td>
<!--END PROJECT_BRIEF-->
<!--END !PROJECT_NAME-->
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN SEARCHENGINE-->
<td>$searchbox</td>
<!--END SEARCHENGINE-->
<!--END DISABLE_INDEX-->
</tr>
</tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->

7
doc/mainpage.dox
View File

@ -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 <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
@ -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

4
src/gmio_core/global.h
View File

@ -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
*/

2
src/gmio_core/internal/string.h
View File

@ -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

2
src/gmio_core/memblock.h
View File

@ -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)();

23
src/gmio_stl/stl_global.h
View File

@ -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 <tt>gmio_stla</tt>, this applies only for STL ascii
* \li <tt>gmio_stlb</tt>, this applies only for STL binary(little/big endian)
*
* \addtogroup gmio_stl
* @{
*/

17
src/gmio_stl/stl_infos.h
View File

@ -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 <tt> infos != NULL </tt>
* \pre <tt> stream != NULL </tt>
*
* \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 <tt> stream != NULL </tt>
* \pre <tt> stream_memblock != NULL </tt>
*/
GMIO_API gmio_streamsize_t gmio_stla_infos_get_streamsize(
struct gmio_stream* stream,

46
src/gmio_stl/stl_io.h
View File

@ -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 <tt> stream != NULL </tt>
* \pre <tt> mesh_creator != NULL </tt>
*
* \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 <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
* \pre <tt> mesh_creator != NULL </tt>
*
* \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 <tt> stream != NULL </tt>
* \pre <tt> mesh_creator != NULL </tt>
*
* \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 <tt> stream != NULL </tt>
* \pre <tt> mesh_creator != NULL </tt>
*
* \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 <tt> stream != NULL </tt>
* \pre <tt> mesh != NULL </tt>
*
* \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 <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
* \pre <tt> mesh != NULL </tt>
*
* \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 <tt> stream != NULL </tt>
*
* \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,

4
src/gmio_stl/stl_mesh.h
View File

@ -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 */

6
src/gmio_stl/stl_mesh_creator.h
View File

@ -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);

5
src/gmio_stl/stlb_header.c
View File

@ -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;
}

1
src/gmio_stl/stlb_header.h
View File

@ -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
*/

15
src/gmio_support/stl_occ.h
View File

@ -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);

9
src/gmio_support/support_global.h
View File

@ -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 <tt>gmio_support/stream_qt.cpp</tt>\n
* All \c gmio_support source files are copied with install target (ie by doing
* <tt>(n)make install</tt>) to <tt>PREFIX/src/gmio_support</tt>
*
* \addtogroup gmio_support
* @{
*/