commit eeedb0f518dfc680957b5cee927fedad2f5d1a38
parent ecb09f3bf2d9ef63334c1bd58a447e518d64ea2c
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Mon, 11 Feb 2019 19:06:03 +0100
Add a description on most of the API calls.
Diffstat:
| M | src/senc.h | | | 56 | +++++++++++++++++++++++++++++++++++++++++++++++++++----- |
1 file changed, 51 insertions(+), 5 deletions(-)
diff --git a/src/senc.h b/src/senc.h
@@ -144,6 +144,7 @@ senc_device_ref_put
* StarEnclosures scene. A scene is a collection of triangles. Each triangle is
* defined with a medium on each side.
******************************************************************************/
+/* Creates an empty scene */
SENC_API res_T
senc_scene_create
(struct senc_device* device,
@@ -155,7 +156,8 @@ senc_scene_create
* 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.
* When deduplicating triangles, the first occurence is kept (with it original
- * global_id). */
+ * global_id). Users can provide their own global ids for triangles; these ids
+ * are not used by the library but are returned as-is by some API calls. */
SENC_API res_T
senc_scene_add_geometry
(struct senc_scene* scene,
@@ -168,31 +170,39 @@ senc_scene_add_geometry
void(*position)(const unsigned ivert, double pos[3], void* context),
void* context);
+/* Returns a descriptor of the scene that holds the analysis' result. */
SENC_API res_T
senc_scene_analyze
(struct senc_scene* scene,
struct senc_descriptor** descriptor);
+/* Returns the convention flags in use with the scene. */
SENC_API res_T
senc_scene_get_convention
(const struct senc_scene* scene,
enum senc_convention* convention);
+/* Returns the number of triangles in the scene. */
SENC_API res_T
senc_scene_get_triangles_count
(const struct senc_scene* scene,
unsigned* count);
+/* Returns the number of unique triangles in the scene (remaining
+ * triangles after deduplication). */
SENC_API res_T
senc_scene_get_unique_triangles_count
(const struct senc_scene* scene,
unsigned* count);
+/* Returns the number of vertices in the scene. */
SENC_API res_T
senc_scene_get_vertices_count
(const struct senc_scene* scene,
unsigned* count);
+/* Returns the number of unique vertices in the scene (remaining
+ * vertices after deduplication). */
SENC_API res_T
senc_scene_get_unique_vertices_count
(const struct senc_scene* scene,
@@ -209,28 +219,36 @@ senc_scene_ref_put
/*******************************************************************************
* StarEnclosures descriptor. It is an handle toward an analyze result.
******************************************************************************/
+/* Returns the greater medium id found in added geometry. In API calls using a
+ * medium, any value in the [0 max_medium_id[ range is valid. However there can
+ * be unused ids (no geometry refered to this medium id). */
SENC_API res_T
senc_descriptor_get_max_medium
(const struct senc_descriptor* descriptor,
unsigned* max_medium_id);
+/* Returns the number of enclosures. */
SENC_API res_T
senc_descriptor_get_enclosure_count
(const struct senc_descriptor* descriptor,
unsigned* count);
+/* Returns the number of enclosures that have some geometry refering to the
+ * imed_th medium. */
SENC_API res_T
senc_descriptor_get_enclosure_count_by_medium
(const struct senc_descriptor* descriptor,
- const unsigned imed, /* Must be in [0 max_medium_id] */
+ const unsigned imed,
unsigned* count);
+/* Returns the idx_th enclosure. */
SENC_API res_T
senc_descriptor_get_enclosure
(struct senc_descriptor* descriptor,
const unsigned idx,
struct senc_enclosure** enclosure);
+/* Returns the idx_th enclosure using the imed_th medium. */
SENC_API res_T
senc_descriptor_get_enclosure_by_medium
(struct senc_descriptor* descriptor,
@@ -238,51 +256,69 @@ senc_descriptor_get_enclosure_by_medium
const unsigned idx,
struct senc_enclosure** enclosure);
+/* Returns the number of unique triangles (no duplicates here) in the whole
+ * geometry. */
SENC_API res_T
senc_descriptor_get_global_triangles_count
(const struct senc_descriptor* descriptor,
- unsigned* count); /* Number of unique triangles. */
+ unsigned* count);
+/* Returns the number of unique vertices (no duplicates here) in the whole
+ * geometry. */
SENC_API res_T
senc_descriptor_get_global_vertices_count
(const struct senc_descriptor* descriptor,
unsigned* count); /* Number of unique vertices. */
+/* Returns the itri_th global unique triangles; the returned indices are global
+ * unique vertex indices. */
SENC_API res_T
senc_descriptor_get_global_triangle
(const struct senc_descriptor* descriptor,
const unsigned itri,
unsigned indices[3]);
+/* Returns the coordinates of the ivert_th global unique vertex. */
SENC_API res_T
senc_descriptor_get_global_vertex
(const struct senc_descriptor* descriptor,
const unsigned ivert,
double coord[3]);
+/* Returns the front and back media ids of the itri_th global unique
+ * triangles. */
SENC_API res_T
senc_descriptor_get_global_triangle_media
(const struct senc_descriptor* descriptor,
const unsigned itri,
unsigned media[2]);
+/* Returns the enclosures the itri_th global unique triangles front and back
+ * sides are member of. */
SENC_API res_T
senc_descriptor_get_global_triangle_enclosures
(const struct senc_descriptor* descriptor,
const unsigned itri,
unsigned enclosures[2]);
+/* Returns the global id of the itri_th global unique triangles, either the
+ * user provided one or the default one. */
SENC_API res_T
senc_descriptor_get_global_triangle_global_id
(const struct senc_descriptor* descriptor,
const unsigned itri,
unsigned* gid);
+/* Returns the number of segments that are frontier segments:
+ * - that have arity 1 (single triangle using the segment)
+ * - that connect 2 different media */
SENC_API res_T
senc_descriptor_get_frontier_segments_count
(const struct senc_descriptor* descriptor,
- unsigned* count); /* Number of frontiers segments. */
+ unsigned* count);
+/* Returns the iseg_th frontier segment; the returned indices are global unique
+ * vertex indices. */
SENC_API res_T
senc_descriptor_get_frontier_segment
(const struct senc_descriptor* descriptor,
@@ -304,39 +340,49 @@ senc_descriptor_ref_put
* 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.
+ * Vertices and triangles numbering schemes are specific to each enclosure:
+ * the "same" item appearing in 2 different enclosures has no reason to get the
+ * same index twice or to have the same index in the global numbering scheme.
* By-index API accesses of triangles (or properties) visit unique triangles
* for indices in the [0 unique_triangle_count[ range and back-faces of the
- * doubly-listed triangles in the [unique_triangle_count triangle_count[ range.
+ * doubly-included triangles in the [unique_triangle_count triangle_count[ range.
******************************************************************************/
+/* Returns the header of an enclosure. */
SENC_API res_T
senc_enclosure_get_header
(const struct senc_enclosure* enclosure,
struct senc_enclosure_header* header);
+/* Returns the itri_th triangle of an enclosure. */
SENC_API res_T
senc_enclosure_get_triangle
(const struct senc_enclosure* enclosure,
const unsigned itri,
unsigned indices[3]);
+/* Returns the coordinates of the ivert_th vertex of an enclosure. */
SENC_API res_T
senc_enclosure_get_vertex
(const struct senc_enclosure* enclosure,
const unsigned ivert,
double coord[3]);
+/* Returns the front and back side media ids of the itri_th triangle of an
+ * enclosure. */
SENC_API res_T
senc_enclosure_get_triangle_media
(const struct senc_enclosure* enclosure,
const unsigned itri,
unsigned medium[2]);
+/* Returns the global id of the itri_th triangle of an enclosure. */
SENC_API res_T
senc_enclosure_get_triangle_global_id
(const struct senc_enclosure* enclosure,
const unsigned itri,
unsigned* gid);
+/* Returns the id of the imed_th medium of an enclosure. */
SENC_API res_T
senc_enclosure_get_medium
(const struct senc_enclosure* enclosure,
