commit cd0836db06b78b9786c19924052eaafdcda242f2
parent c3c11da27e95da5baa18ddfdcfb3f32648994dcd
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Fri, 6 Jun 2025 10:44:11 +0200
Fix API
Add or rewrite comments.
Diffstat:
| M | src/scad.h | | | 36 | +++++++++++++++++++++++------------- |
1 file changed, 23 insertions(+), 13 deletions(-)
diff --git a/src/scad.h b/src/scad.h
@@ -196,6 +196,7 @@ SCAD_API res_T
scad_geometry_ref_put
(struct scad_geometry* geom);
+/* Clear the scene from all its geometries */
SCAD_API res_T
scad_scene_clear
(void);
@@ -230,8 +231,10 @@ scad_geometry_get_name
(const struct scad_geometry* geom,
const char** name);
-/* Swap the internals of geometry pools (swap pool1[i] and pool2[i]); what is
- * swapped is set usig flags. Pools must have the same count. */
+/* Swap the internals of geometry pools `pool1' and `pool2'
+ * (i.e. swap pool1[i] and pool2[i]).
+ * What is swapped is set using flags.
+ * Pools must have the same count. */
SCAD_API res_T
scad_geometries_swap
(struct scad_geometry** pool1,
@@ -327,8 +330,9 @@ scad_add_sphere
struct scad_geometry** sphere);
/* Check if geometries `geom1' and `geom2' have the same content, that is:
- * - are the same scad_geometries (trivial case),
- * - contain the same internal entities.
+ * are the same scad_geometries (trivial case),
+ * or:
+ * contain the same internal entities.
* To check if 2 geometries are "equivalent", one as to apply boolean operators
* (e.g. cut) and check the result accordingly (e.g. empty result). */
SCAD_API res_T
@@ -337,7 +341,7 @@ scad_geometries_equal
struct scad_geometry* geom2,
int* equal);
-/* Check if all the entities of `geometry' are part of the geometries in
+/* Check if all the entities of `geometry' are part of one of the geometries in
* `geometries'. */
SCAD_API res_T
scad_geometry_is_included
@@ -491,8 +495,8 @@ scad_geometry_explode
struct scad_geometry*** out_geometries,
size_t* out_geometry_n);
-/* Import a step model from file `filename'. The imported geometries are
- * recorded in `out_geometries'.
+/* Import a step model from file `filename'.
+ * The imported geometries are recorded in `out_geometries'.
* Note that `out_geometries' is allocated using the allocator provided when
* initializing star-cad and should be freed accordingly. */
SCAD_API res_T
@@ -567,7 +571,10 @@ SCAD_API res_T
scad_scene_write
(const char* name);
-/* Create the mesh of the whole scene. */
+/* Create the mesh of the whole scene.
+ * Note that, due to gmsh capabilities, there is no way to mesh a given list of
+ * geometries. To avoid meshing useless geometries you can release them using
+ * scad_geometry_ref_put before meshing. */
SCAD_API res_T
scad_scene_mesh
(void);
@@ -576,9 +583,10 @@ scad_scene_mesh
* tranform to `source' geometries.
* The result is that the mesh generated for `target' is the image on the mesh
* generated for `source' through the `affine' transform.
- * Only apply to surfaces (dimension 2). If called on a volume, it applies to
- * its 2D constituents.
- * The two sets of surfaces must match exactly (same number of points, etc.). */
+ * Only meaningful for surfaces. If called on a volume, it applies to its 2D
+ * constituents.
+ * The two sets of surfaces must match topologically (same number of points,
+ * etc.). */
SCAD_API res_T
scad_geometries_set_periodic
(struct scad_geometry** source,
@@ -664,7 +672,8 @@ scad_get_dimtag_refcount
(const int dim,
const int tag);
-/* Dump geometry `geom' with address/name, ref count and tags.
+/* Dump geometry `geom' with address/name, ref count and its OCC internal
+ * dim.tag list.
* To use it from gdb:
* (gdb) call scad_dump_geometry( <geom_ptr> )
*/
@@ -672,7 +681,8 @@ SCAD_API res_T
scad_dump_geometry
(const struct scad_geometry* geom);
-/* Dump all the geometries with address/name, ref count and tags.
+/* Dump all the geometries with address/name, ref count and and their OCC
+ * internal dim.tag lists.
* To use it from gdb:
* (gdb) call scad_dump_geometries()
*/
