star-enclosures-3d

commit e0d453d8c2f2705e709e697c612ca1338f125dbe
parent 7e386804f5ab15dc7b725d8b39fe0947b4191b54
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date:   Thu, 15 Feb 2018 11:13:57 +0100

Improve API documentation.

Diffstat:
M
src/senc.h
 | 
29
+++++++++++++++++++++--------

1 file changed, 21 insertions(+), 8 deletions(-)
diff --git a/src/senc.h b/src/senc.h
@@ -58,7 +58,7 @@ struct senc_enclosure;
 
 /* Enclosure header type */
 struct enclosure_header {
-  /* The ID of the enclosure; guaranteed to be compact */
+  /* The ID of the enclosure; 0, 1, ... */
   unsigned enclosure_id;
   /* Number of triangles; a triangle can be accounted for twice, once by side */
   unsigned triangle_count;
@@ -66,9 +66,10 @@ struct enclosure_header {
   unsigned unique_triangle_count;
   /* Number of vertices */
   unsigned vertices_count;
-  /* The medium in the enclosure */
+  /* The medium inside the enclosure */
   unsigned enclosed_medium;
-  /* Is the enclosure infinite? */
+  /* Is the enclosure open/infinite?
+   * Only the outermost enclosure is infinite. */
   char is_infinite;
 };
 
@@ -82,7 +83,7 @@ SENC_API res_T
 senc_device_create
   (struct logger* logger, /* May be NULL <=> use default logger */
    struct mem_allocator* allocator, /* May be NULL <=> use default allocator */
-   const unsigned nthreads_hint, /* Hint on the number of threads to use (UNUSED) */
+   const unsigned nthreads_hint, /* UNUSED */
    const int verbose,
    struct senc_device** device);
 
@@ -104,6 +105,10 @@ senc_scene_create
    const unsigned mediums_count,
    struct senc_scene** scene);
 
+/* Add a new set of vertices and triangles to the scene.
+ * Vertices can be duplicates and are deduplicated on the fly.
+ * Triangles can be duplicates as long as they constantly define the same
+ * medium on both sides (or an error will be reported) and are deduplicated. */
 SENC_API res_T
 senc_scene_add_geometry
   (struct senc_scene* scene,
@@ -144,12 +149,12 @@ senc_descriptor_get_enclosure
 SENC_API res_T
 senc_descriptor_get_global_triangles_count
   (const struct senc_descriptor* descriptor,
-   unsigned* count);
+   unsigned* count); /* Number of unique triangles. */
 
 SENC_API res_T
 senc_descriptor_get_global_vertices_count
   (const struct senc_descriptor* descriptor,
-   unsigned* count);
+   unsigned* count); /* Number of unique vertices. */
 
 SENC_API res_T
 senc_descriptor_get_global_triangle
@@ -184,8 +189,16 @@ senc_descriptor_ref_put
   (struct senc_descriptor* descriptor);
 
 /*******************************************************************************
-* StarEnclosures enclosure. It is an handle toward an enclosure.
-******************************************************************************/
+ * StarEnclosures enclosure. It is an handle toward an enclosure.
+ * Counts and other information on enclosures are not individually accessible,
+ * but as a whole through header access.
+ * An enclosure can list the "same" triangle twice if both sides are in. In this
+ * case the 2 occurences of the triangle have reversed vertices order and
+ * unique_triangle_count and triangle_count differ.
+ * By-index API accesses of triangles (or properties) visit unique triangles
+ * for indexes in the [0 unique_triangle_count[ and back-faces of the
+ * doubly-listed triangles in the [unique_triangle_count triangle_count[ range.
+ ******************************************************************************/
 SENC_API res_T
 senc_enclosure_get_header
   (const struct senc_enclosure* enclosure,