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

doc: effort to make it complete

Browse Source
This commit is contained in:
Hugues Delorme 2015-03-04 18:25:51 +01:00
parent bb236cad3b
commit 85481e2e89
20 changed files with 152 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@ -1,27 +1,50 @@
GeomIO: C library for geometry input/output
==============================
===========================================
This is GeomIO v0.1dev
GeomIO is a reusable ANSI C library whose purpose is to provide complete
I/O support for various CAD file formats (eg. STL)
GeomIO is a reusable C library whose purpose is to provide complete I/O
support for various CAD file formats (eg. STL)
GeomIO aims to be fast, portable (ISO-C90 conformance) and feature-rich.
Main highlights:
* "Abstract" streams that does not tie the user to C stream (`FILE*`).
GeomIO provides a general stream structure based on callbacks, so that
any kind of device can be used (memory, file, socket, ...)
* Operations can be easily aborted
* Buffering of input/ouput for efficient device usage
* Available under the CeCILL-B license, which is fully BSD compatible
Current version only supports STL file format (STereoLithgraphy). Support of
STL is complete:
* Binary(little/big endian) and ASCII formats
* Header data and "attribute byte count" for binary format
* Name of solid for ASCII format
* Detection of the input data format
In addition, the STL module has the following advatanges:
* The user keeps its own geometry data structures, no conversion needed.
This reduces the effort so that the user just specifies callbacks for
retrieval/creation of geometry data
* No dynamic memory allocations
* Extended support of OpenCascade's `StlMesh_Mesh`
Building GeomIO
==================
===============
GeomIO can be built with CMake, by default a shared library is generated.
1. For an out-of-source build, create a directory where the build will take
place (say build/)
2. Call cmake, passing as argument the directory where is located
place (say `build/`)
2. Call `cmake`, passing as argument the directory where is located
CMakeLists.txt
3. (n)make
4. (n)make install
3. `(n)make`
4. `(n)make install`
Read CMakeLists.txt to figure out how to build debug and release libraries.
For the first use of GeomIO, you should run unit tests:
(n)make check
`(n)make check`
How to report a bug

16
doc/Doxyfile
View File

@ -128,7 +128,7 @@ FULL_PATH_NAMES = YES
# If left blank the directory from which doxygen is run is used as the
# path to strip.
STRIP_FROM_PATH = /home/cerf/dev/projects/fougue/gmio/src
STRIP_FROM_PATH = ../src
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
# the path mentioned in the documentation of a class, which tells
@ -657,7 +657,8 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = ../src
INPUT = ../README.md \
../src
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@ -689,7 +690,9 @@ RECURSIVE = YES
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE =
EXCLUDE = \
../src/gmio_core/memory.h \ # Not used
../src/gmio_support/support_global.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
@ -1470,7 +1473,7 @@ ENABLE_PREPROCESSING = YES
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
MACRO_EXPANSION = YES
MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
@ -1507,9 +1510,8 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = GMIO_LIB_EXPORT= \
GMIO_LIBSUPPORT_EXPORT= \
GMIO_LIBSTL_EXPORT= \
GMIO_C_LINKAGE_BEGIN= \
GMIO_C_LINKAGE_END= \
GMIO_HAVE_STDINT_H=1
GMIO_HAVE_STDINT_H=1 \
DOXYGEN
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.

4
src/gmio_core/endian.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file endian.h
* Architecture endianness
*/
#ifndef GMIO_ENDIAN_H
#define GMIO_ENDIAN_H

4
src/gmio_core/error.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file error.h
* List of common errors, reported by I/O functions
*/
#ifndef GMIO_ERROR_H
#define GMIO_ERROR_H

33
src/gmio_core/global.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file global.h
* Fundamental global declarations, included by almost all other header files
*/
#ifndef GMIO_GLOBAL_H
#define GMIO_GLOBAL_H
@ -22,7 +26,9 @@
# define GMIO_DECL_EXPORT __declspec(dllexport)
# define GMIO_DECL_IMPORT __declspec(dllimport)
#else
/*! Expands to the C compiler extension to export functions to a DLL */
# define GMIO_DECL_EXPORT
/*! Expands to the C compiler extension to import functions from a DLL */
# define GMIO_DECL_IMPORT
#endif /* WIN */
@ -33,6 +39,8 @@
# define GMIO_LIB_EXPORT GMIO_DECL_IMPORT
# endif /* GMIO_LIB_MAKE_DLL */
#else
/*! Expands either to GMIO_DECL_EXPORT or GMIO_DECL_IMPORT when respectively
* compiling/using the DLL */
# define GMIO_LIB_EXPORT
#endif /* GMIO_LIB_DLL */
@ -68,23 +76,31 @@ typedef unsigned long long uint64_t;
#ifdef GMIO_HAVE_STDBOOL_H
# include <stdbool.h>
/*! Typedef for boolean type */
typedef bool gmio_bool_t;
# define GMIO_FALSE false
# define GMIO_TRUE true
#elif !defined(DOXYGEN)
typedef int gmio_bool_t;
#else
/*! Typedef for boolean type */
typedef int gmio_bool_t;
/*! This enum defines true/false boolean values */
enum gmio_bool_value
{
GMIO_FALSE = 0,
GMIO_TRUE = 1
};
#else
/* For documentation only */
/*! Boolean type alias
*
* If strict ISO-C90 or if \c <stdbool.h> does not exists then:
* \li \c gmio_bool_t is an alias of \c int
* \li <tt>GMIO_FALSE == 0</tt> and <tt>GMIO_TRUE == 1</tt>
*
* Otherwise:
* \li \c gmio_bool_t is an alias of \c bool
* \li \c GMIO_FALSE expands to \c false and \c GMIO_TRUE to \c true
*/
typedef int_or_bool gmio_bool_t;
#endif /* GMIO_HAVE_STDBOOL_H */
/*! Typedef for 32bit real type (float) */
@ -102,6 +118,7 @@ typedef double gmio_float64_t;
# elif defined(_MSC_VER)
# define GMIO_INLINE __inline
# else
/*! Expands to the C compiler specific inline keyword (if any) */
# define GMIO_INLINE
# endif
#endif /* !GMIO_INLINE */
@ -110,7 +127,9 @@ typedef double gmio_float64_t;
# define GMIO_C_LINKAGE_BEGIN extern "C" {
# define GMIO_C_LINKAGE_END }
#else
/*! Expands to <tt>extern "C" {</tt> when building with a C++ compiler */
# define GMIO_C_LINKAGE_BEGIN
/*! Expands to \c } when building with a C++ compiler */
# define GMIO_C_LINKAGE_END
#endif /* __cplusplus */

19
src/gmio_core/internal/string_parse.h
View File

@ -19,6 +19,11 @@
#include "../global.h"
#include "../stream.h"
/*! Stores traditional 8-bit strings
*
* For faster length lookups, it knowns the length of its contents. It must
* never exceeds the maximum length of the buffer.
*/
struct gmio_string_buffer
{
char* ptr; /*!< Buffer contents */
@ -28,6 +33,12 @@ struct gmio_string_buffer
typedef struct gmio_string_buffer gmio_string_buffer_t;
/*! Forward iterator over a stream
*
* To be used with API below.
* It allows to iterate over a stream (until end is reached) as if it was a
* string.
*/
struct gmio_string_stream_fwd_iterator
{
gmio_stream_t* stream;
@ -45,7 +56,13 @@ const char* gmio_current_char(const gmio_string_stream_fwd_iterator_t* it);
void gmio_skip_spaces(gmio_string_stream_fwd_iterator_t* it);
int gmio_eat_word(gmio_string_stream_fwd_iterator_t* it, gmio_string_buffer_t* buffer);
/*! Move on next char in stream */
const char* gmio_next_char(gmio_string_stream_fwd_iterator_t* it);
/*! Iterate over stream while it matches input string \p str
*
* Returns GMIO_TRUE if \p str was fully matched
*/
gmio_bool_t gmio_checked_next_chars(gmio_string_stream_fwd_iterator_t* it, const char* str);
/*! Converts the string pointed to by \p str to gmio_float32_t representation
@ -53,6 +70,6 @@ gmio_bool_t gmio_checked_next_chars(gmio_string_stream_fwd_iterator_t* it, const
* \retval 0 On success
* \retval -1 On error(check \c errno to see what happened)
*/
int gmio_get_float32(const char* str, gmio_float32_t* value_ptr);
int gmio_get_float32(const char* str, gmio_float32_t* value_ptr);
#endif /* GMIO_INTERNAL_STRING_PARSE_H */

4
src/gmio_core/stream.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stream.h
* Declaration of gmio_stream and utility functions
*/
#ifndef GMIO_STREAM_H
#define GMIO_STREAM_H

4
src/gmio_core/task_control.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file task_control.h
* Declaration of gmio_task_control and utility functions
*/
#ifndef GMIO_TASK_CONTROL_H
#define GMIO_TASK_CONTROL_H

4
src/gmio_core/transfer.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file transfer.h
* Declaration of gmio_transfer
*/
#ifndef GMIO_TRANSFER_H
#define GMIO_TRANSFER_H

2
src/gmio_stl/internal/stl_rw_common.h
View File

@ -13,6 +13,8 @@
** "http://www.cecill.info".
****************************************************************************/
/* TODO : documentation */
#ifndef GMIO_INTERNAL_STL_RW_COMMON_H
#define GMIO_INTERNAL_STL_RW_COMMON_H

5
src/gmio_stl/internal/stlb_byte_swap.h
View File

@ -19,6 +19,11 @@
#include "../../gmio_core/global.h"
#include "../stl_triangle.h"
/*! Specific byte-swap of the memory occupied by a gmio_stl_triangle object
*
* Each XYZ coord (float32) is individually reversed (byte-swap) as well as
* the "attribute byte count" member.
*/
void gmio_stl_triangle_bswap(gmio_stl_triangle_t* triangle);
#endif /* GMIO_INTERNAL_STLB_BYTE_SWAP_H */

4
src/gmio_stl/stl_error.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_error.h
* List of errors specific to STL I/O functions
*/
#ifndef GMIO_LIBSTL_STL_ERROR_H
#define GMIO_LIBSTL_STL_ERROR_H

4
src/gmio_stl/stl_format.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_format.h
* Detection of STL format from input stream
*/
#ifndef GMIO_LIBSTL_FORMAT_H
#define GMIO_LIBSTL_FORMAT_H

4
src/gmio_stl/stl_global.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_global.h
* Global declarations for the STL module
*/
#ifndef GMIO_LIBSTL_GLOBAL_H
#define GMIO_LIBSTL_GLOBAL_H

4
src/gmio_stl/stl_io.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_io.h
* STL read/write functions
*/
#ifndef GMIO_LIBSTL_STL_IO_H
#define GMIO_LIBSTL_STL_IO_H

4
src/gmio_stl/stl_mesh.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_mesh.h
* Declaration of gmio_stl_mesh
*/
#ifndef GMIO_LIBSTL_STL_MESH_H
#define GMIO_LIBSTL_STL_MESH_H

4
src/gmio_stl/stl_mesh_creator.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_mesh_creator.h
* Declaration of gmio_stl_mesh_creator
*/
#ifndef GMIO_LIBSTL_STL_MESH_CREATOR_H
#define GMIO_LIBSTL_STL_MESH_CREATOR_H

4
src/gmio_stl/stl_triangle.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file stl_triangle.h
* Declaration of gmio_stl_coords and gmio_stl_triangle
*/
#ifndef GMIO_LIBSTL_TRIANGLE_H
#define GMIO_LIBSTL_TRIANGLE_H

10
src/gmio_support/occ_libstl.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file occ_libstl.h
* Support of OpenCascade's StlMesh_Mesh
*/
#ifndef GMIO_SUPPORT_OCC_LIBSTL_H
#define GMIO_SUPPORT_OCC_LIBSTL_H
@ -21,7 +25,7 @@
struct gmio_stl_mesh;
struct gmio_stl_mesh_creator;
/*! \brief Domain in a StlMesh_Mesh object
/*! Domain in a StlMesh_Mesh object
*
* The domain is indicated with its index within the STL mesh
*/
@ -41,14 +45,14 @@ private:
int m_domainId;
};
/*! \brief Initializes \p mesh so it maps to a domain in StlMesh_Mesh
/*! Initializes \p mesh so it maps to a domain in StlMesh_Mesh
*
* \c mesh->cookie will point to \p meshCookie
*/
GMIO_LIBSUPPORT_EXPORT
void gmio_stl_occmesh(gmio_stl_mesh* mesh, const gmio_OccStlMeshDomain& meshCookie);
/*! \brief Initializes \p creator to build a new domain in a StlMesh_Mesh object
/*! Initializes \p creator to build a new domain in a StlMesh_Mesh object
*
* \c creator->cookie will point to the internal data(ie. StlMesh_Mesh*) of handle \p mesh
*/

7
src/gmio_support/qt_stream.h
View File

@ -13,6 +13,10 @@
** "http://www.cecill.info".
****************************************************************************/
/*! \file qt_stream.h
* Support of Qt's QIODevice (requires at least Qt4)
*/
#ifndef GMIO_SUPPORT_QT_STREAM_H
#define GMIO_SUPPORT_QT_STREAM_H
@ -20,8 +24,7 @@
struct gmio_stream;
class QIODevice;
/*! \brief Configures \p stream for \c QIODevice* (cookie will hold \p device)
*/
/*! Configures \p stream for \c QIODevice* (cookie will hold \p device) */
GMIO_LIBSUPPORT_EXPORT
void gmio_stream_set_qiodevice(struct gmio_stream* stream, QIODevice* device);