star-cpr

commit 7df4a3579aa15d12d568df25da28918613e42e45
parent 38edead9ae83b97103959663eb24cc5b8c650a9f
Author: Vincent Forest <vincent.forest@meso-star.com>
Date:   Wed, 31 Aug 2016 09:14:59 +0200

Add comments

Diffstat:
M
src/scpr.h
 | 
35
++++++++++++++++++-----------------
M
src/scpr_mesh.c
 | 
30
++++++++++++++++--------------

2 files changed, 34 insertions(+), 31 deletions(-)
diff --git a/src/scpr.h b/src/scpr.h
@@ -18,14 +18,17 @@
 
 #include <rsys/rsys.h>
 
-#ifdef SCPR_SHARED_BUILD
+/* Library symbol management */
+#if defined(SCPR_SHARED_BUILD) /* Build shared library */
   #define SCPR_API extern EXPORT_SYM
-#elif defined(SCPR_STATIC_BUILD)
+#elif defined(SCPR_STATIC_BUILD) /* Use/build static library */
   #define SCPR_API extern LOCAL_SYM
-#else
+#else /* Use shared library */
   #define SCPR_API extern IMPORT_SYM
 #endif
 
+/* Helper macro that asserts if the invocation of the scpr function `Func'
+ * returns an error. */
 #ifndef NDEBUG
   #define SCPR(Func) ASSERT(scpr_##Func == RES_OK)
 #else
@@ -33,8 +36,8 @@
 #endif
 
 enum scpr_operation {
-  SCPR_AND,
-  SCPR_SUB,
+  SCPR_AND, /* Keep the mesh part that intersects the clip polygon */
+  SCPR_SUB, /* Remove the mesh part that intersects the clip polygon */
   SCPR_OPERATIONS_COUNT__
 };
 
@@ -42,20 +45,18 @@ enum scpr_operation {
 struct scpr_polygon {
   void (*get_position)(const size_t ivert, double pos[2], void* ctx);
   size_t nvertices; /* #vertices */
-  /* User defined data provided as the last argument of the get_position
-   * functor */
+  /* User data provided as the last argument of the get_position functor */
   void* context;
 };
-
 #define SCPR_POLYGON_NULL__ { NULL, 0, NULL }
 static const struct scpr_polygon SCPR_POLYGON_NULL = SCPR_POLYGON_NULL__;
 
-/* Opaque 2 dimensionnal mesh data type */
-struct scpr_mesh;
-
-/* Forward declarations */
+/* Forward declaration */
 struct mem_allocator;
 
+/* Opaque 2D mesh data type */
+struct scpr_mesh;
+
 BEGIN_DECLS
 
 SCPR_API res_T
@@ -74,18 +75,18 @@ scpr_mesh_ref_put
 SCPR_API res_T
 scpr_mesh_setup_indexed_vertices
   (struct scpr_mesh* mesh,
-   const size_t ntris,
+   const size_t ntris, /* #triangles */
    void (*get_indices)(const size_t itri, size_t ids[3], void* ctx),
-   const size_t nverts,
+   const size_t nverts, /* #vertices */
    void (*get_position)(const size_t ivert, double pos[2], void* ctx),
    void* data); /* Client data set as the last param of the callbacks */
 
 /* Clip the mesh against the polygon contour */
 SCPR_API res_T
 scpr_mesh_clip
-  (struct scpr_mesh* mesh,
-   const enum scpr_operation op,
-   struct scpr_polygon* polygon);
+  (struct scpr_mesh* mesh, /* Candidate mesh to clip */
+   const enum scpr_operation op, /* Clip operation */
+   struct scpr_polygon* polygon); /* Clip polygon */
 
 SCPR_API res_T
 scpr_mesh_get_triangles_count
diff --git a/src/scpr_mesh.c b/src/scpr_mesh.c
@@ -451,8 +451,8 @@ res_T
 scpr_mesh_get_vertices_count(const struct scpr_mesh* mesh, size_t* nverts)
 {
   if(!mesh || !nverts) return RES_BAD_ARG;
-  ASSERT((darray_double_size_get(&mesh->coords) % 2) == 0);
-  *nverts = darray_double_size_get(&mesh->coords) / 2;
+  ASSERT((darray_double_size_get(&mesh->coords) % 2/*#coords per vertex*/)==0);
+  *nverts = darray_double_size_get(&mesh->coords) / 2/*#coords per vertex*/;
   return RES_OK;
 }
 
@@ -460,8 +460,8 @@ res_T
 scpr_mesh_get_triangles_count(const struct scpr_mesh* mesh, size_t* ntris)
 {
   if(!mesh || !ntris) return RES_BAD_ARG;
-  ASSERT((darray_size_t_size_get(&mesh->indices)%3) == 0);
-  *ntris = darray_size_t_size_get(&mesh->indices) / 3;
+  ASSERT((darray_size_t_size_get(&mesh->indices)%3/*#vertices per triangle*/)==0);
+  *ntris = darray_size_t_size_get(&mesh->indices) / 3/*#vertices per triangle*/;
   return RES_OK;
 }
 
@@ -470,12 +470,13 @@ scpr_mesh_get_indices
   (const struct scpr_mesh* mesh, const size_t itri, size_t ids[3])
 {
   size_t ntris;
+  const size_t i = itri * 3/*#vertices per triangle*/;
   if(!mesh || !ids) return RES_BAD_ARG;
   SCPR(mesh_get_triangles_count(mesh, &ntris));
   if(itri >= ntris) return RES_BAD_ARG;
-  ids[0] = darray_size_t_cdata_get(&mesh->indices)[itri*3 + 0];
-  ids[1] = darray_size_t_cdata_get(&mesh->indices)[itri*3 + 1];
-  ids[2] = darray_size_t_cdata_get(&mesh->indices)[itri*3 + 2];
+  ids[0] = darray_size_t_cdata_get(&mesh->indices)[i+0];
+  ids[1] = darray_size_t_cdata_get(&mesh->indices)[i+1];
+  ids[2] = darray_size_t_cdata_get(&mesh->indices)[i+2];
   return RES_OK;
 }
 
@@ -484,11 +485,12 @@ scpr_mesh_get_position
   (const struct scpr_mesh* mesh, const size_t ivert, double pos[2])
 {
   size_t nverts;
+  const size_t i = ivert * 2/*#coords per vertex*/;
   if(!mesh || !pos) return RES_BAD_ARG;
   SCPR(mesh_get_vertices_count(mesh, &nverts));
   if(ivert >= nverts) return RES_BAD_ARG;
-  pos[0] = darray_double_cdata_get(&mesh->coords)[ivert*2+0];
-  pos[1] = darray_double_cdata_get(&mesh->coords)[ivert*2+1];
+  pos[0] = darray_double_cdata_get(&mesh->coords)[i+0];
+  pos[1] = darray_double_cdata_get(&mesh->coords)[i+1];
   return RES_OK;
 }
 
@@ -505,10 +507,10 @@ scpr_mesh_clip
   struct darray_size_t indices; /* Indices of the clipped mesh */
   struct htable_vertex vertices; /* Map a coordinate to its index */
   ClipperLib::Clipper clipper(ClipperLib::ioStrictlySimple);
-  ClipperLib::Paths output;
-  ClipperLib::Path cand_path;
-  ClipperLib::Path clip_path;
-  ClipperLib::ClipType clip_type;
+  ClipperLib::Paths output; /* Contour of the clipped polgyon */
+  ClipperLib::Path cand_path; /* Contour of the candidate polygon */
+  ClipperLib::Path clip_path; /* Contour of the clip polygon */
+  ClipperLib::ClipType clip_type; /* Type of clipping to perform */
   size_t ivert, nverts;
   size_t itri, ntris;
 
@@ -587,7 +589,7 @@ scpr_mesh_clip
     clipper.AddPath(clip_path, ClipperLib::ptClip, 1);
     clipper.Execute(clip_type, output);
 
-    /* Register the polygons */
+    /* Register the resulting clipped polygons */
     res = register_paths
       (output, &coords, &indices, &vertices, extend, polygon);
     if(res != RES_OK) goto error;