commit ce8846ae7989089765c40e2e2cceb8d1664ffb8e
parent 7782d93139d91e2f48d449dc67ac02908b10c168
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Wed, 11 Jun 2025 17:45:23 +0200
Improvements to the scad.h header file
Move declarations accross, fix and add comments, rename args, etc.
Diffstat:
| M | src/scad.h | | | 284 | ++++++++++++++++++++++++++++++++++++++++++++++--------------------------------- |
1 file changed, 166 insertions(+), 118 deletions(-)
diff --git a/src/scad.h b/src/scad.h
@@ -170,38 +170,64 @@ scad_initialize
2 = errors and warnings,
3 = errors, warnings, and informative messages */
+/* Close the session and release any geometry not yet released.
+ * Once finalized, scad can be initialized again. */
SCAD_API res_T
scad_finalize
(void);
+/* Set global options `options' for scad. */
SCAD_API res_T
scad_set_options
(const struct scad_options* options); /* May be NULL: set default */
+/* Get global options for scad. */
SCAD_API res_T
scad_get_options
(struct scad_options* options);
/*******************************************************************************
+ * Scene API -
+ * All these calls process the scene (i.e. all the existing geomeries) at once.
+ ******************************************************************************/
+
+/* Clear the scene from all its geometries */
+SCAD_API res_T
+scad_scene_clear
+ (void);
+
+/* Write the whole scene in a format that depends on the file name extension.
+ * Available formats include "brep", "msh" (gmsh-specific format), "step",
+ * "stl", "vtk", etc. */
+SCAD_API res_T
+scad_scene_write
+ (const char* name);
+
+/* 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);
+
+/*******************************************************************************
* Geometry API - A geometry is a primitive, a group of primitives, or the
* result of an operation on geometries.
- * If provided, name must be unique.
+ * If provided, names must be unique.
******************************************************************************/
+/* Ref counting of geometries: get a new reference to goemetry `geom'. */
SCAD_API res_T
scad_geometry_ref_get
(struct scad_geometry* geom);
+/* Ref counting of geometries: release a reference to goemetry `geom'. */
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);
-
-/* Get the number of components of the geometry `geom' */
+/* Get the number of components of the geometry `geom'. */
SCAD_API res_T
scad_geometry_get_count
(const struct scad_geometry* geom,
@@ -225,16 +251,16 @@ scad_geometry_get_custom_data
/* Get a pointer to `geom's name.
* Note that this reference is only valid during the lifetime of `geom' (don't
- * use name after deleting `geom') */
+ * use name after deleting `geom'). */
SCAD_API res_T
scad_geometry_get_name
(const struct scad_geometry* geom,
const char** name);
/* 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. */
+ * (i.e. swap internals of 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,
@@ -249,23 +275,25 @@ scad_geometry_get_mass
(struct scad_geometry* geom,
double* mass);
-/* Get the center of mass of the various components of the geometry.
+/* Get the center of mass of the various components of geometry `geom'.
* Note that `center' must be allocated by the caller with enough room for (at
- * least) 3 times the count of geom (scad_geometry_get_count) doubles */
+ * least) 3 times the count of geom (scad_geometry_get_count) doubles. */
SCAD_API res_T
scad_geometry_get_centerofmass
(struct scad_geometry* geom,
double* center);
-/* Get the closest point on geometry `geom' from point `from' */
+/* Get the `closest- point on geometry `geom' from point `from' and its
+ * `distance'. */
SCAD_API res_T
scad_geometry_get_closest_point
(struct scad_geometry* geom,
const double from[3],
double closest[3],
- double* closest_distance);
+ double* distance);
-/* Get the Boundig Box of geometry `geom' */
+/* Get the Boundig Box of geometry `geom' in the form of `min' and `max'
+ * vectors. */
SCAD_API res_T
scad_geometry_get_bounding_box
(struct scad_geometry* geom,
@@ -273,7 +301,8 @@ scad_geometry_get_bounding_box
double max[3]);
/* Add a rectangle to the scene, defined by a point `xyz' and
- * `dxdy' the extents along the x-, y-axes. */
+ * `dxdy' the extents along the x-, y-axes.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_rectangle
(const char* name, /* Can be NULL */
@@ -282,7 +311,8 @@ scad_add_rectangle
struct scad_geometry** rectangle);
/* Add a disk in (xy) plane to the scene, defined by a the center `xyz' and
- * `radius'. */
+ * `radius'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_disk
(const char* name, /* Can be NULL */
@@ -290,18 +320,22 @@ scad_add_disk
const double radius,
struct scad_geometry** disk);
-/* Add a polygonal surface in (xy) plane to the scene at elevation z */
+/* Add a polygon in the (xy) plane to the scene.
+ * The `polygon' has `count' vertice and is at elevation `z', the vertice are
+ * defined by calls to user-provided function `get_position'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_polygon
(const char* name, /* Can be NULL */
void (*get_position)(const size_t ivert, double pos[2], void* data),
void* data, /* Custom data; can be NULL if get_position don't use it */
const double z,
- const size_t count, /* size of x and y arrays */
+ const size_t count,
struct scad_geometry** polygon);
-/* Add a parallelepipedic box to the scene, defined by a point `xyz' and
- * `dxdydz' the extents along the x-, y- and z-axes. */
+/* Add a parallelepipedic `box' to the scene, defined by a point `xyz' and
+ * `dxdydz' the extents along the x-, y- and z-axes.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_box
(const char* name, /* Can be NULL */
@@ -309,9 +343,10 @@ scad_add_box
const double dxdydz[3],
struct scad_geometry** box);
-/* Add a cylinder to the scene, defined by the center `xyz' of its first
+/* Add a `cylinder' to the scene, defined by the center `xyz' of its first
* circular face, the vector `axis' defining its axis and its radius `rad'. The
- * `angle' argument defines the angular opening (from 0 to 2*Pi). */
+ * `angle' argument defines the angular opening (from 0 to 2*PI).
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_cylinder
(const char* name, /* Can be NULL */
@@ -321,7 +356,8 @@ scad_add_cylinder
const double angle,
struct scad_geometry** cylinder);
-/* Add a sphere of center `xyz' and radius `rad' to the scene. */
+/* Add a `sphere' of center `xyz' and radius `rad' to the scene.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_add_sphere
(const char* name, /* Can be NULL */
@@ -329,10 +365,9 @@ scad_add_sphere
const double radius,
struct scad_geometry** sphere);
-/* Check if geometries `geom1' and `geom2' have the same content, that is:
- * are the same scad_geometries (trivial case),
- * or:
- * contain the same internal entities.
+/* Check if geometries `geom1' and `geom2' have the same content, that is
+ * 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
@@ -350,7 +385,9 @@ scad_geometry_is_included
const size_t geometries_count,
int* included);
-/* Create a new geometry made from all the entities from `geometries'. */
+/* Create a new geometry `out_geometry' made from all the entities from
+ * `geometries'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometries_collect
(const char* name, /* Can be NULL */
@@ -359,7 +396,8 @@ scad_geometries_collect
struct scad_geometry** out_geometry);
/* Compute the boolean union (the fusion) of the geometries in `geometries' and
- * `tools'. */
+ * `tools'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometries_fuse
(const char* name, /* Can be NULL */
@@ -370,7 +408,8 @@ scad_geometries_fuse
struct scad_geometry** out_geometry);
/* Compute the boolean difference between the geometries in `geometries' and
- * `tools'. */
+ * `tools'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometries_cut
(const char* name, /* Can be NULL */
@@ -381,7 +420,8 @@ scad_geometries_cut
struct scad_geometry** out_geometry);
/* Compute the boolean intersection (the common parts) of the geometries
- * in `geometries' and `tools'. */
+ * in `geometries' and `tools'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometries_intersect
(const char* name, /* Can be NULL */
@@ -411,6 +451,7 @@ scad_geometries_partition
* `geometries' and `tools'.
* If `prefix_name' is not NULL, the output geometries are named
* <prefix_name>_<rank>, <rank> counting from 0. Otherwise they remain unnamed.
+ * If `prefix_name' is provided, the resulting names must be unique.
* The result `out_boundaries' being allocated using the allocator provided when
* initializing star-cad, it should be freed accordingly.
* If there is no common boundary, `out_boundaries' is set to NULL and
@@ -430,6 +471,7 @@ scad_geometries_common_boundaries
/* Get the boundary of the geometries in `geometries', considered as a whole.
* If `prefix_name' is not NULL, the output geometries are named
* <prefix_name>_<rank>, <rank> counting from 0. Otherwise they remain unnamed.
+ * If `prefix_name' is provided, the resulting names must be unique.
* The result `out_boundaries' being allocated using the allocator provided when
* initializing star-cad, it should be freed accordingly. */
SCAD_API res_T
@@ -440,28 +482,34 @@ scad_geometries_boundary
struct scad_geometry*** out_boundaries,
size_t *out_count);
-/* copy the geometry `geom'. */
+/* Copy the geometry `geom'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_copy
(const struct scad_geometry* geom,
const char* name, /* Can be NULL */
struct scad_geometry** out_copy);
-/* copy the geometry `geom'. */
+/* Change the visibility of the geometry `geom'.
+ * If `recursive' is set, constituents of `geom' are recursively affected down
+ * to dim 0 (vertices).
+ * Can be used in conjunction with option MeshOnlyVisible. */
SCAD_API res_T
scad_geometry_set_visibility
(const struct scad_geometry* geom,
int visible,
int recursive);
-/* Change the name of geometry `geom'. */
+/* Rename geometry `geom'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_rename
(struct scad_geometry* geom,
const char* name); /* Can be NULL */
-/* Scale the geometry by * factors `scale' along the three coordinate axes;
- * use `center', as the center of the homothetic transformation. */
+/* Scale the geometry `geom' by factors `scale' along the three coordinate axes;
+ * Use `center', as the center of the homothetic transformation.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_dilate
(const struct scad_geometry* geom,
@@ -470,7 +518,8 @@ scad_geometry_dilate
const char* name, /* Can be NULL */
struct scad_geometry** out_geometry);
-/* Translate the geometry `geom' along (`dx', `dy', `dz'). */
+/* Translate the geometry `geom' along (`dx', `dy', `dz').
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_translate
(const struct scad_geometry* geom,
@@ -479,7 +528,8 @@ scad_geometry_translate
struct scad_geometry** out_geometry);
/* Rotate the geometry `geom' by `angle' radians around the axis of revolution
- * defined by the point `pt' and the direction `dir'. */
+ * defined by the point `pt' and the direction `dir'.
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_rotate
(const struct scad_geometry* geom,
@@ -489,7 +539,8 @@ scad_geometry_rotate
const char* name, /* Can be NULL */
struct scad_geometry** out_geometry);
-/* Extrude the geometry `geom' using a translation along (`dx', `dy', `dz'). */
+/* Extrude the geometry `geom' using a translation along (`dx', `dy', `dz').
+ * If provided, `name' must be unique. */
SCAD_API res_T
scad_geometry_extrude
(const struct scad_geometry* geom,
@@ -499,7 +550,10 @@ scad_geometry_extrude
/* Return a list of geometries which form the geometry `geom'.
* The output geometries are named <base>_<rank>, where <base> is either
- * prefix_name or geom's name, and <rank> counting from 0.
+ * prefix_name (first choice) or geom's name, and <rank> * counting from 0.
+ * If neither `prefix_name' nor `geom's name are defined, the geometries are
+ * created unamed.
+ * Whatever the names, if defined they must be unique.
* The result `out_geometries' being allocated using the allocator provided when
* initializing star-cad, it should be freed accordingly. */
SCAD_API res_T
@@ -507,18 +561,84 @@ scad_geometry_explode
(const struct scad_geometry* geom,
const char* prefix_name, /* Can be NULL */
struct scad_geometry*** out_geometries,
- size_t* out_geometry_n);
+ size_t* out_count);
+
+/* Flag `target' geometries as being the result of applying the `affine'
+ * 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 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,
+ const size_t source_count,
+ struct scad_geometry** target,
+ const size_t target_count,
+ double affine[16]);
+
+/* Set a size modifier for geometries in `geometries'.
+ * When meshing these geometries, triangles' size will be either size*modifier,
+ * or modifier where size would be the size of the triangle in the absence of a
+ * size modifier.
+ * The size modifier is applied recursively down to dimension 0 (points).
+ * If multiple size modifiers are applied, the order matters as the last applied
+ * size modifier remains.
+ * To reset a size modifier, just apply a new Scad_size_factor modifier of 1. */
+SCAD_API res_T
+scad_geometries_set_mesh_size_modifier
+ (struct scad_geometry** geometries,
+ const size_t geometries_count,
+ enum scad_size_modifier_type type,
+ double modifier);
+
+/* Set a specific mesh algorithm for geometries in `geometries'.
+ * Only apply to surfaces (dimension 2). If called on a volume, it applies to
+ * its 2D constituents. */
+SCAD_API res_T
+scad_geometries_set_mesh_algorithm
+ (struct scad_geometry** geometries,
+ const size_t geometries_count,
+ enum scad_mesh_algorithm algorithm);
+
+/* Clear the mesh of the geometries in `geometries'.
+ * Note that the mesh of a geometry can only be cleared if it is not on the
+ * boundary of another geometry with a non-empty mesh. */
+SCAD_API res_T
+scad_geometries_clear_mesh
+ (struct scad_geometry** geometries,
+ const size_t geometries_count);
+
+/* Get the normal of the geometry `geom' at position `p'.
+ * The normal is set in `N' and the underlying 2D entity to which `p' belongs is
+ * returned as a new geometry in `out_geometry'. */
+SCAD_API res_T
+scad_geometry_normal
+ (struct scad_geometry* geom,
+ double p[3],
+ double N[3],
+ const char* name, /* Can be NULL */
+ struct scad_geometry** out_geometry);
+
+/*******************************************************************************
+ * I/O API
+ ******************************************************************************/
/* 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. */
+ * initializing star-cad and should be freed accordingly.
+ * If `prefix_name' is not NULL, the output geometries are named
+ * <prefix_name>_<rank>, <rank> counting from 0. Otherwise they remain unnamed.
+ * If `prefix_name' is provided, the resulting names must be unique. */
SCAD_API res_T
scad_step_import
(const char* filename, /* name of step file */
- const char* name, /* Can be NULL */
+ const char* prefix_name, /* Can be NULL */
struct scad_geometry*** out_geometries,
- size_t* out_geometry_n);
+ size_t* out_count);
/* Export the mesh of geometry `geom' to an STL file.
* In order to get a mesh, one has to call scad_scene_mesh before calling this.
@@ -580,78 +700,6 @@ scad_stl_data_write
const enum scad_normals_orientation orientation,
const int binary);
-/* Write the whole scene in a format that depends on the file name extension. */
-SCAD_API res_T
-scad_scene_write
- (const char* name);
-
-/* 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);
-
-/* Flag `target' geometries as being the result of applying the `affine'
- * 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 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,
- const size_t source_count,
- struct scad_geometry** target,
- const size_t target_count,
- double affine[16]);
-
-/* Set a size modifier for geometries in `geometries'.
- * When meshing these geometries, triangles' size will be either size*modifier,
- * or modifier where size would be the size of the triangle in the absence of a
- * size modifier.
- * The size modifier is applied recursively down to dimension 0 (points).
- * If multiple size modifiers are applied, the order matters as the last applied
- * size modifier remains.
- * To reset a size modifier, just apply a new Scad_size_factor modifier of 1. */
-SCAD_API res_T
-scad_geometries_set_mesh_size_modifier
- (struct scad_geometry** geometries,
- const size_t geometries_count,
- enum scad_size_modifier_type type,
- double modifier);
-
-/* Set a specific mesh algorithm for geometries in `geometries'.
- * Only apply to surfaces (dimension 2). If called on a volume, it applies to
- * its 2D constituents. */
-SCAD_API res_T
-scad_geometries_set_mesh_algorithm
- (struct scad_geometry** geometries,
- const size_t geometries_count,
- enum scad_mesh_algorithm algorithm);
-
-/* Clear the mesh of the geometries in `geometries'.
- * Note that the mesh of a geometry can only be cleared if it is not on the
- * boundary of another geometry with a non-empty mesh. */
-SCAD_API res_T
-scad_geometries_clear_mesh
- (struct scad_geometry** geometries,
- const size_t geometries_count);
-
-/* Get the normal of the geometry `geom' at position `p'.
- * The normal is set in `N' and the underlying 2D entity to which `p' belongs is
- * returned as a new geometry in `out_geometry'. */
-SCAD_API res_T
-scad_geometry_normal
- (struct scad_geometry* geom,
- double p[3],
- double N[3],
- const char* name, /* Can be NULL */
- struct scad_geometry** out_geometry);
-
/* The following API calls are meant for debugging purposes.
* They can be called from gdb. */
