diff --git a/src/libstl/stl_error.h b/src/libstl/stl_error.h index ac0809c..c9fcf30 100644 --- a/src/libstl/stl_error.h +++ b/src/libstl/stl_error.h @@ -1,20 +1,32 @@ #ifndef FOUG_LIBSTL_STL_ERROR_H #define FOUG_LIBSTL_STL_ERROR_H +/*! A byte-mask to tag(identify) STL-specific error codes */ #define FOUG_STL_ERROR_TAG 0x11000000 +/*! This enum defines the various error codes reported by STL read/write functions */ enum foug_stl_rw_error { /*! Common STL write error indicating foug_stl_geom::get_triangle_func() pointer is NULL */ FOUG_STL_WRITE_NULL_GET_TRIANGLE_FUNC_ERROR = FOUG_STL_ERROR_TAG + 1, /* Specific error codes returned by STL_ascii read function */ + + /*! Parsing error occured in foug_stla_read() due to malformed STL ascii input */ FOUG_STLA_READ_PARSE_ERROR = FOUG_STL_ERROR_TAG + 100, + + /*! Invalid max number of decimal significants digits for foug_stla_write(), must be in [1..9] */ FOUG_STLA_WRITE_INVALID_REAL32_PREC_ERROR = FOUG_STL_ERROR_TAG + 101, /* Specific error codes returned by STL_binary read/write functions */ + + /*! The byte order argument supplied is not supported, must be little or big endian */ FOUG_STLB_UNSUPPORTED_BYTE_ORDER_ERROR = FOUG_STL_ERROR_TAG + 300, + + /*! Error occured when reading header data in foug_stlb_read() */ FOUG_STLB_READ_HEADER_WRONG_SIZE_ERROR = FOUG_STL_ERROR_TAG + 301, + + /*! Error occured when reading facet count in foug_stlb_read() */ FOUG_STLB_READ_FACET_COUNT_ERROR = FOUG_STL_ERROR_TAG + 302 }; diff --git a/src/libstl/stl_geom.h b/src/libstl/stl_geom.h index 0504334..1ad0f45 100644 --- a/src/libstl/stl_geom.h +++ b/src/libstl/stl_geom.h @@ -4,11 +4,17 @@ #include "stl_global.h" #include "stl_triangle.h" +/*! Provides an interface for accessing the underlying(hidden) user mesh */ struct foug_stl_geom { + /*! Opaque pointer on the user mesh, passed as first argument to hook functions */ const void* cookie; + + /*! Number of triangles in the mesh */ uint32_t triangle_count; - void (*get_triangle_func)(const void*, uint32_t, foug_stl_triangle_t*); + + /*! Pointer on a function that stores the mesh triangle of index \p tri_id into \p triangle */ + void (*get_triangle_func)(const void* cookie, uint32_t tri_id, foug_stl_triangle_t* triangle); }; typedef struct foug_stl_geom foug_stl_geom_t; diff --git a/src/libstl/stl_geom_creator.h b/src/libstl/stl_geom_creator.h index 4113171..ad7e17c 100644 --- a/src/libstl/stl_geom_creator.h +++ b/src/libstl/stl_geom_creator.h @@ -4,16 +4,43 @@ #include "stl_global.h" #include "stl_triangle.h" +/*! Provides an interface for the creation of the underlying(hidden) user mesh */ struct foug_stl_geom_creator { + /*! Opaque pointer on the user mesh, passed as first argument to hook functions */ void* cookie; - void (*ascii_begin_solid_func)(void*, const char*); /* Optional */ - void (*binary_begin_solid_func)(void*, uint32_t, const uint8_t*); /* Optional */ + /* All function pointers are optional (ie can be set to NULL) */ - void (*add_triangle_func)(void*, uint32_t, const foug_stl_triangle_t*); /* Optional */ + /*! Pointer on a function that handles declaration of a solid of name \p solid_name . + * + * This optional function is useful only with STL ascii (ie. foug_stla_read()) + */ + void (*ascii_begin_solid_func)(void* cookie, const char* solid_name); - void (*end_solid_func) (void*); /* Optional */ + /*! Pointer on a function that handles declaration of a mesh with \p tri_count number of triangles. + * + * This optional function is useful only with STL binary (ie. foug_stlb_read()). + * + * The argument \p header contains the header data(80 bytes) + */ + void (*binary_begin_solid_func)(void* cookie, uint32_t tri_count, const uint8_t* header); + + /*! Pointer on a function that adds a triangle to the user mesh. + * + * The argument \p triangle is the triangle to be added, note that + * foug_stl_triangle_t::attribute_byte_count is meaningless for STL ascii. + * + * The argument \p tri_id is the index of the mesh triangle + */ + void (*add_triangle_func)(void* cookie, uint32_t tri_id, const foug_stl_triangle_t* triangle); + + /*! Pointer on a function that finalizes creation of the user mesh. + * + * This optional function is called at the end of the read process, ie. after all triangles have + * been added + */ + void (*end_solid_func)(void* cookie); }; typedef struct foug_stl_geom_creator foug_stl_geom_creator_t; diff --git a/src/libstl/stl_triangle.h b/src/libstl/stl_triangle.h index f1767f3..c44c516 100644 --- a/src/libstl/stl_triangle.h +++ b/src/libstl/stl_triangle.h @@ -3,6 +3,7 @@ #include "stl_global.h" +/*! Cartesian coordinate entity in 3D space, specifically tailored for STL needs (single-float) */ struct foug_stl_coords { foug_real32_t x; @@ -11,19 +12,26 @@ struct foug_stl_coords }; typedef struct foug_stl_coords foug_stl_coords_t; -#define FOUG_STL_COORDS_RAWSIZE (3 * sizeof(foug_real32_t)) +/*! STL mesh triangle defined three geometric vertices and an orientation(normal) */ struct foug_stl_triangle { foug_stl_coords_t normal; foug_stl_coords_t v1; foug_stl_coords_t v2; foug_stl_coords_t v3; - uint16_t attribute_byte_count; /* Useful only for STL binary format */ + uint16_t attribute_byte_count; /*!< Useful only for STL binary format */ }; typedef struct foug_stl_triangle foug_stl_triangle_t; + +/*! Compact size of a foug_stl_coords_t object */ +#define FOUG_STL_COORDS_RAWSIZE (3 * sizeof(foug_real32_t)) + +/*! Compact size of a foug_stl_triangle_t object for STL ascii format */ #define FOUG_STLA_TRIANGLE_RAWSIZE (4 * FOUG_STL_COORDS_RAWSIZE) + +/*! Compact size of a foug_stl_triangle_t object for STL binary format */ #define FOUG_STLB_TRIANGLE_RAWSIZE (FOUG_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t)) #endif /* FOUG_DATAX_C_LIBSTL_TRIANGLE_H */ diff --git a/src/transfer.h b/src/transfer.h index c788513..86abb3b 100644 --- a/src/transfer.h +++ b/src/transfer.h @@ -5,11 +5,19 @@ #include "stream.h" #include "task_control.h" +/*! Defines data required for any transfer(read/write) operation */ struct foug_transfer { + /*! The stream to be used for I/O */ foug_stream_t stream; + + /*! The optional control object used to handle progress of the transfer */ foug_task_control_t task_control; + + /*! Pointer on a user memory area used by the transfer as a buffer for stream optimization */ void* buffer; + + /*! Size (in bytes) of the buffer memoru */ size_t buffer_size; };