diff --git a/src/c/libstl/stla_write.c b/src/c/libstl/stla_write.c index ea99922..d7daeb1 100644 --- a/src/c/libstl/stla_write.c +++ b/src/c/libstl/stla_write.c @@ -88,9 +88,26 @@ static foug_bool_t foug_tansfer_flush_buffer(foug_transfer_t* trsf, size_t n) return foug_stream_write(&trsf->stream, trsf->buffer, sizeof(char), n) == n; } +/*! \brief Write geometry in the STL ascii format + * + * \param geom Defines the custom geometry to write + * \param trsf Defines needed objects (stream, buffer, ...) for the writing operation + * \param real32_prec The maximum number of significant digits + * + * \return Error code + * + * \retval FOUG_DATAX_NO_ERROR If operation successful + * \retval FOUG_DATAX_NULL_BUFFER_ERROR If trsf->buffer is NULL + * \retval FOUG_DATAX_INVALID_BUFFER_SIZE_ERROR If trsf->buffer_size is less than 512 bytes + * \retval FOUG_STLA_WRITE_INVALID_REAL32_PRECISION If \p real_prec is not inside [1..9] + * \retval FOUG_STLA_WRITE_NULL_GET_TRIANGLE_COUNT_FUNC If geom->get_triangle_count_func is NULL + * \retval FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC If geom->get_triangle_func is NULL + * \retval FOUG_DATAX_STREAM_ERROR For any writing error + * \retval FOUG_DATAX_TASK_STOPPED_ERROR If the operation was interrupted foug_task_control + */ int foug_stla_write(foug_stla_geom_output_t* geom, foug_transfer_t* trsf, - uint8_t real32_precision) + uint8_t real32_prec) { size_t solid_count = 0; size_t total_facet_count = 0; @@ -101,7 +118,7 @@ int foug_stla_write(foug_stla_geom_output_t* geom, char coords_format[64]; int error = FOUG_DATAX_NO_ERROR; - if (real32_precision == 0 || real32_precision > 9) + if (real32_prec == 0 || real32_prec > 9) return FOUG_STLA_WRITE_INVALID_REAL32_PRECISION; if (buffer_iterator == NULL) return FOUG_DATAX_NULL_BUFFER_ERROR; @@ -114,11 +131,11 @@ int foug_stla_write(foug_stla_geom_output_t* geom, { char* coords_format_iterator = coords_format; - coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision); + coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec); coords_format_iterator = foug_write_nspaces(coords_format_iterator, 2); - coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision); + coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec); coords_format_iterator = foug_write_nspaces(coords_format_iterator, 2); - coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision); + coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec); /* TODO: check the "format" string can contain the given precision */ } diff --git a/src/c/libstl/stla_write.h b/src/c/libstl/stla_write.h index 67f91b8..739afce 100644 --- a/src/c/libstl/stla_write.h +++ b/src/c/libstl/stla_write.h @@ -5,25 +5,26 @@ #include "stl_triangle.h" #include "../transfer.h" -/* foug_stla_geom_output */ +/* Custom geometry expressed with STL ascii interface */ typedef struct foug_stla_geom_output foug_stla_geom_output_t; struct foug_stla_geom_output { void* cookie; - size_t (*get_solid_count_func) (foug_stla_geom_output_t*); /* Optional */ + + size_t (*get_solid_count_func) (foug_stla_geom_output_t*); /* Optional (if NULL solid_count == 1) */ void (*get_solid_name) (foug_stla_geom_output_t*, size_t, char*); /* Optional */ size_t (*get_triangle_count_func)(foug_stla_geom_output_t*, size_t); void (*get_triangle_func) (foug_stla_geom_output_t*, size_t, size_t, foug_stl_triangle_t*); }; -/* foug_stla_write() */ +/* Write geometry in the STL ascii format */ FOUG_DATAX_LIBSTL_EXPORT int foug_stla_write(foug_stla_geom_output_t* geom, foug_transfer_t* trsf, - uint8_t real32_precision); + uint8_t real32_prec); /* Specific error codes returned by foug_stla_write() */ -#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_COUNT_FUNC 1 -#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC 2 -#define FOUG_STLA_WRITE_INVALID_REAL32_PRECISION 3 +#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_COUNT_FUNC 1 /*!< get_triangle_count_func is null */ +#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC 2 /*!< get_triangle_func is null */ +#define FOUG_STLA_WRITE_INVALID_REAL32_PRECISION 3 /*!< real32_prec is not in [1..9] */ #endif /* FOUG_DATAX_C_LIBSTL_STLA_WRITE_H */ diff --git a/src/c/libstl/stlb_read.h b/src/c/libstl/stlb_read.h index fedfb2c..1b63f67 100644 --- a/src/c/libstl/stlb_read.h +++ b/src/c/libstl/stlb_read.h @@ -11,10 +11,10 @@ typedef struct foug_stlb_geom_input foug_stlb_geom_input_t; struct foug_stlb_geom_input { void* cookie; - void (*process_header_func) (foug_stlb_geom_input_t*, const uint8_t*); - void (*begin_triangles_func) (foug_stlb_geom_input_t*, uint32_t); + void (*process_header_func) (foug_stlb_geom_input_t*, const uint8_t*); /* Optional */ + void (*begin_triangles_func) (foug_stlb_geom_input_t*, uint32_t); /* Optional */ void (*process_next_triangle_func)(foug_stlb_geom_input_t*, const foug_stlb_triangle_t*); - void (*end_triangles_func) (foug_stlb_geom_input_t*); + void (*end_triangles_func) (foug_stlb_geom_input_t*); /* Optional */ }; /* foug_stlb_read() */ diff --git a/src/c/memory.h b/src/c/memory.h index 4d99a7e..c08c3d6 100644 --- a/src/c/memory.h +++ b/src/c/memory.h @@ -3,7 +3,10 @@ #include +/*! Type alias for "pointer on function that allocates memory" (like standard malloc()) */ typedef void* (*foug_malloc_func_t)(size_t); + +/*! Type alias for "pointer on function that frees memory" (like standard free()) */ typedef void (*foug_free_func_t)(void*); #endif /* FOUG_C_MEMORY_H */ diff --git a/src/c/stream.c b/src/c/stream.c index 9d6ff58..d139091 100644 --- a/src/c/stream.c +++ b/src/c/stream.c @@ -5,7 +5,7 @@ #include /*! - * \brief Install a null stream + * \brief Installs a null stream */ void foug_stream_set_null(foug_stream_t* stream) { @@ -39,7 +39,7 @@ static size_t foug_stream_stdio_write(foug_stream_t* stream, } /*! - * \brief Create a stream for standard FILE* + * \brief Configures \p stream for standard FILE* */ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file) { @@ -50,6 +50,9 @@ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file) stream->write_func = foug_stream_stdio_write; } +/*! + * \brief Returns true if the current read and write position is at the end of the stream + */ foug_bool_t foug_stream_at_end(foug_stream_t* stream) { if (stream != NULL && stream->at_end_func != NULL) @@ -58,7 +61,7 @@ foug_bool_t foug_stream_at_end(foug_stream_t* stream) } /*! - * \brief Check error indicator + * \brief Checks error indicator * * Checks if the error indicator associated with \p stream is set, returning a value different from * zero if it is. @@ -73,7 +76,7 @@ int foug_stream_error(foug_stream_t* stream) } /*! - * \brief Read block of data from stream + * \brief Reads block of data from stream * * Reads an array of \p item_count elements, each one with a \p item_size of size bytes, from the * \p stream and stores them in the block of memory specified by \p ptr. @@ -95,7 +98,7 @@ size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t item_size, size } /*! - * \brief Write block of data to stream + * \brief Writes block of data to stream * * Writes an array of \p item_count elements, each one with a \p item_size of size bytes, from the * block of memory pointed by \p ptr to the current position in the \p stream. diff --git a/src/c/stream.h b/src/c/stream.h index 96a3345..098a88a 100644 --- a/src/c/stream.h +++ b/src/c/stream.h @@ -5,11 +5,23 @@ #include "memory.h" #include -/* foug_stream */ typedef struct foug_stream foug_stream_t; + +/*! \brief Stream that can get input from an arbitrary data source or can write output to an + * arbitrary data sink + * + * This is pretty much the same as + * + * custom streams in the GNU C Library + * + * It uses a cookie being basically an opaque pointer on a hidden data type. The custom stream is + * implemented by defining hook functions that know how to read/write the data. + * + */ struct foug_stream { void* cookie; + foug_bool_t (*at_end_func)(foug_stream_t*); int32_t (*error_func)(foug_stream_t*); size_t (*read_func)(foug_stream_t*, void*, size_t, size_t); diff --git a/src/c/task_control.c b/src/c/task_control.c index 1315dec..37f6046 100644 --- a/src/c/task_control.c +++ b/src/c/task_control.c @@ -3,6 +3,13 @@ #include #include +/*! + * \brief Calls a function that does something with progress value \p progress_pc (eg. update + * a progress bar in the UI) + * + * The return value is important : it is used as an interruption request status. If \c true then the + * corresponding task can continue, otherwise it should abort as soon as possible. + */ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t progress_pc) { if (ctrl != NULL && ctrl->handle_progress_func != NULL) @@ -10,6 +17,12 @@ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t return 1; } +/*! + * \brief Converts \p value as a percentage + * + * \p value is assumed to be relative to the interval (range) defined by + * [ \p range_min , \p range_max ] + */ uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value) { if (value >= range_max)