commit 0cfcbf06b500927adb1a61098424f8dd79aa84af
parent 0c80fa721c868c765d55ae665508f9333fbf141e
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date: Tue, 4 Mar 2025 15:19:19 +0100
Improve comments throughout the code for better clarity
Diffstat:
5 files changed, 80 insertions(+), 19 deletions(-)
diff --git a/src/sphin.h b/src/sphin.h
@@ -69,13 +69,18 @@ enum sphin_source_direction_distribution_type {
SPHIN_SOURCE_DIRECTION_ISOTROPIC,
SPHIN_SOURCE_DIRECTION_NONE__
};
-
struct sphin_create_args {
struct logger* logger; /* May be NULL <=> default logger */
struct mem_allocator* allocator; /* NULL <=> use default allocator */
- int verbose; /* Verbosity level */
+ int verbose; /* Verbosity level. Bigger values => more verbosity */
};
-#define SPHIN_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0}
+
+/* Public structs are provided with default values to simplify initialization
+ * and ensure consistent behavior. Users can either use the default settings or
+ * override specific fields as needed. If the struct is created by sphin, it
+ * will be initialized to its default value and the fields will be overwritten
+ * during the parsing */
+#define SPHIN_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0} /* We define a constant to */
static const struct sphin_create_args SPHIN_CREATE_ARGS_DEFAULT =
SPHIN_CREATE_ARGS_DEFAULT__;
@@ -137,9 +142,18 @@ static const struct sphin_source_direction_distribution
SPHIN_SOURCE_DIRECTION_DISTRIBUTION_NULL =
SPHIN_SOURCE_DIRECTION_DISTRIBUTION_NULL__;
+/* This structure, by design, describe a mesh in the simplest possible way,
+ * without making assumptions about how it will be used. It provides only the
+ * essential data: a flat array of vertex coordinates and an index array
+ * defining triangles.
+ *
+ * The responsibility for interpreting or structuring this data lies with the
+ * user or the functions that load the mesh. */
struct sphin_mesh {
- const double* coords; //TODO comment
- const size_t* indices;
+ const double *coords; /* A sequence of triplets (x, y, z):
+ * [x0, y0, z0, x1, y1, z1, ...] */
+ const size_t *indices; /* A sequence of indices that represents each triangle
+ * in the coords array */
size_t triangle_count;
size_t vertex_count;
};
@@ -149,7 +163,14 @@ static const struct sphin_mesh SPHIN_MESH_NULL = SPHIN_MESH_NULL__;
struct sphin_geometry_descriptor {
const char* filename;
- enum sphin_side side; // TODO comment
+ enum sphin_side side; /* FRONT: The structure is concerned with the same
+ * direction as the normal.
+ * BACK: The structure is concerned with the opposite
+ * direction of the normal.
+ * It determines which of the sides of a given geometry
+ * must be decorated with physical properties.
+ * Moreover, when used in a sphin_volume, it determine how the
+ * enclosure is formed. */
struct sphin_mesh mesh;
};
#define SPHIN_GEOMETRY_DESCRIPTOR_NULL__ { \
@@ -161,11 +182,14 @@ static const struct sphin_geometry_descriptor
SPHIN_GEOMETRY_DESCRIPTOR_NULL =
SPHIN_GEOMETRY_DESCRIPTOR_NULL__;
-
-/* Forward declaration
- * We declare the structure sphin, but its representation remains opaque to the
- * users of the programming interface exposed by star-phor-input. Thus, the user
- * must use the functions exposed by the library to manipulate this structure. */
+/* Forward declarations
+ *
+ * These structures are declared but remain opaque to users of the
+ * star-phor-input programming interface. Their internal representation
+ * is hidden to ensure encapsulation and modularity.
+ *
+ * Users must interact with these structures exclusively through the
+ * functions provided by the library (e.g., those prefixed with sphin_get).*/
struct sphin; /* Library handler */
struct sphin_brdf;
struct sphin_config; /* Physical configuration */
@@ -269,7 +293,7 @@ sphin_surface_ref_put
SPHIN_API res_T
sphin_surface_get_brdf
(const struct sphin_surface* surface,
- struct sphin_brdf** brdf);
+ struct sphin_brdf** brdf); /* May be NULL <=> no brdf */
SPHIN_API res_T
sphin_surface_get_source
diff --git a/src/sphin_geometry.h b/src/sphin_geometry.h
@@ -53,11 +53,38 @@ geometry_parse
char* value,
struct sphin_geometry** out_geom);
-/* Generate the dynamic array for the structure geometry and its API */
-#define DARRAY_NAME sphin_geometry_ptr /* Prefix for api functions and structures:
- darray_geometry */
+/* Generate a dynamic array for storing sphin_geometry* elements and its API
+ * using the API provided by rsys/dynamic_array.h
+ *
+ * Define the prefix used for API functions and structures related to this
+ * dynamic array. This prefix will be used to generate function and type names,
+ * such as:
+ * - darray_sphin_surface_ptr_release
+ * - darray_sphin_surface_ptr_init
+ * - darray_sphin_surface_ptr_push_back => append element to the end of the dynamic array
+ * - darray_sphin_surface_ptr_size_get => returns the number of elements
+ * (size_t) of the dynamic array
+ * - darray_sphin_surface_ptr_data_get => returns the array itself
+ * - darray_sphin_surface_ptr_resize
+ * Among other functions
+ */
+#define DARRAY_NAME sphin_geometry_ptr
+
+/* Define the type of data stored in the dynamic array: pointers to sphin_geometry */
#define DARRAY_DATA struct sphin_geometry*
-/* Generate the code */
+
+/*
+ * Include the dynamic array implementation from rsys/dynamic_array.h.
+ *
+ * Note that this header is included twice in the source code:
+ * 1. At the beginning of the file (with other #include statements):
+ * - This ensures access to general definitions, utility functions, or
+ * declarations needed throughout the codebase.
+ *
+ * 2. Here, after defining DARRAY_NAME and DARRAY_DATA:
+ * - This triggers the preprocessor to generate a type-specific implementation
+ * of the dynamic array for 'struct sphin_geometry*' based on the provided macros.
+ */
#include <rsys/dynamic_array.h>
#endif /* SPHIN_GEOMETRY_H */
diff --git a/src/sphin_surface.h b/src/sphin_surface.h
@@ -37,7 +37,9 @@ parse_surface
struct txtrdr* txtrdr,
const char* name);
-/* Generate the dynamic array of pointers for the structure sphin_surface */
+/* Generate the dynamic array of pointers for the structure sphin_surface
+ *
+ * Refer to sphin_geometry.h to a more detailed explanation on this */
#define DARRAY_NAME sphin_surface_ptr /* Prefix for api functions and structures:
darray_sphin_surface_ptr */
#define DARRAY_DATA struct sphin_surface*
diff --git a/src/sphin_volume.h b/src/sphin_volume.h
@@ -37,7 +37,9 @@ parse_volume
struct txtrdr* txtrdr,
const char* name);
-/* Generate the dynamic array of pointers for the structure sphin_volume */
+/* Generate the dynamic array of pointers for the structure sphin_volume
+ *
+ * Refer to sphin_geometry.h to a more detailed explanation on this */
#define DARRAY_NAME sphin_volume_ptr /* Prefix for api functions and structures:
darray_sphin_volume_ptr */
#define DARRAY_DATA struct sphin_volume*
diff --git a/src/test_sphin.c b/src/test_sphin.c
@@ -27,6 +27,7 @@
#include <rsys/logger.h>
#include <stdio.h>
+
static void
log_stream(const char* msg, void* ctx)
{
@@ -54,7 +55,12 @@ main(int argc, char** argv)
CHK(sphin_ref_get(sphin) == RES_OK);
CHK(sphin_ref_put(NULL) == RES_BAD_ARG);
CHK(sphin_ref_put(sphin) == RES_OK);
- CHK(sphin_ref_put(sphin) == RES_OK); /* Call ref_put twice to ensure release sphin is called * == RES_OK */
+ /* Call ref_put twice to ensure release sphin is called */
+ CHK(sphin_ref_put(sphin) == RES_OK);
+ /* At this point, the memory for the sphin instance has been released. It is
+ * no longer valid to interact with the sphin object or to use any functions
+ * that manipulate it. Any attempts to do so will result in undefined
+ * behavior, as the underlying memory no longer exists. */
/* Test sphin_create with default allocator */
mem_init_proxy_allocator(&allocator, &mem_default_allocator);
