commit e0607f53e7504f28014533bd5969de00a24dc085
parent 101c1308013d7694d3cd1b95132d11bfd4c39e60
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Mon, 11 Feb 2019 18:39:28 +0100
Add a description on most of the API calls.
Diffstat:
| M | src/senc2d.h | | | 57 | +++++++++++++++++++++++++++++++++++++++++++++++++++------ |
1 file changed, 51 insertions(+), 6 deletions(-)
diff --git a/src/senc2d.h b/src/senc2d.h
@@ -143,6 +143,7 @@ senc2d_device_ref_put
* StarEnclosures2D scene. A scene is a collection of segments. Each segment is
* defined with a medium on each side.
******************************************************************************/
+/* Creates an empty scene */
SENC2D_API res_T
senc2d_scene_create
(struct senc2d_device* device,
@@ -154,7 +155,8 @@ senc2d_scene_create
* Segments 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 segments, the first occurence is kept (with it original
- * global_id). */
+ * global_id). Users can provide their own global ids for segments; these ids
+ * are not used by the library but are returned as-is by some API calls. */
SENC2D_API res_T
senc2d_scene_add_geometry
(struct senc2d_scene* scene,
@@ -167,31 +169,39 @@ senc2d_scene_add_geometry
void(*position)(const unsigned ivert, double pos[2], void* context),
void* context);
+/* Returns a descriptor of the scene that holds the analysis' result. */
SENC2D_API res_T
senc2d_scene_analyze
(struct senc2d_scene* scene,
struct senc2d_descriptor** descriptor);
+/* Returns the convention flags in use with the scene. */
SENC2D_API res_T
senc2d_scene_get_convention
(const struct senc2d_scene* scene,
enum senc2d_convention* convention);
+/* Returns the number of segments in the scene. */
SENC2D_API res_T
senc2d_scene_get_segments_count
(const struct senc2d_scene* scene,
unsigned* count);
+/* Returns the number of unique segments in the scene (remaining
+ * segments after deduplication). */
SENC2D_API res_T
senc2d_scene_get_unique_segments_count
(const struct senc2d_scene* scene,
unsigned* count);
+/* Returns the number of vertices in the scene. */
SENC2D_API res_T
senc2d_scene_get_vertices_count
(const struct senc2d_scene* scene,
unsigned* count);
+/* Returns the number of unique vertices in the scene (remaining
+ * vertices after deduplication). */
SENC2D_API res_T
senc2d_scene_get_unique_vertices_count
(const struct senc2d_scene* scene,
@@ -208,28 +218,36 @@ senc2d_scene_ref_put
/*******************************************************************************
* StarEnclosures2D 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). */
SENC2D_API res_T
senc2d_descriptor_get_max_medium
(const struct senc2d_descriptor* descriptor,
unsigned* max_medium_id);
+/* Returns the number of enclosures. */
SENC2D_API res_T
senc2d_descriptor_get_enclosure_count
(const struct senc2d_descriptor* descriptor,
unsigned* count);
+/* Returns the number of enclosures that have some geometry refering to the
+ * imed_th medium. */
SENC2D_API res_T
senc2d_descriptor_get_enclosure_count_by_medium
(const struct senc2d_descriptor* descriptor,
- const unsigned imed, /* Must be in [0 max_medium_id] */
+ const unsigned imed,
unsigned* count);
+/* Returns the idx_th enclosure. */
SENC2D_API res_T
senc2d_descriptor_get_enclosure
(struct senc2d_descriptor* descriptor,
const unsigned idx,
struct senc2d_enclosure** enclosure);
+/* Returns the idx_th enclosure using the imed_th medium. */
SENC2D_API res_T
senc2d_descriptor_get_enclosure_by_medium
(struct senc2d_descriptor* descriptor,
@@ -237,51 +255,68 @@ senc2d_descriptor_get_enclosure_by_medium
const unsigned idx,
struct senc2d_enclosure** enclosure);
+/* Returns the number of unique segments (no duplicates here) in the whole
+ * geometry. */
SENC2D_API res_T
senc2d_descriptor_get_global_segments_count
(const struct senc2d_descriptor* descriptor,
- unsigned* count); /* Number of unique segments. */
+ unsigned* count);
+/* Returns the number of unique vertices (no duplicates here) in the whole
+ * geometry. */
SENC2D_API res_T
senc2d_descriptor_get_global_vertices_count
(const struct senc2d_descriptor* descriptor,
- unsigned* count); /* Number of unique vertices. */
+ unsigned* count);
+/* Returns the iseg_th global unique segment; the returned indices are global
+ * unique vertex indices. */
SENC2D_API res_T
senc2d_descriptor_get_global_segment
(const struct senc2d_descriptor* descriptor,
const unsigned iseg,
unsigned indices[2]);
+/* Returns the coordinates of the ivert_th global unique vertex. */
SENC2D_API res_T
senc2d_descriptor_get_global_vertex
(const struct senc2d_descriptor* descriptor,
const unsigned ivert,
double coord[2]);
+/* Returns the front and back media ids of the iseg_th global unique segment. */
SENC2D_API res_T
senc2d_descriptor_get_global_segment_media
(const struct senc2d_descriptor* descriptor,
const unsigned iseg,
unsigned media[2]);
+/* Returns the enclosures the iseg_th global unique segment front and back
+ * sides are member of. */
SENC2D_API res_T
senc2d_descriptor_get_global_segment_enclosures
(const struct senc2d_descriptor* descriptor,
const unsigned iseg,
unsigned enclosures[2]);
+/* Returns the global id of the iseg_th global unique segment, either the user
+ * provided one or the default one. */
SENC2D_API res_T
senc2d_descriptor_get_global_segment_global_id
(const struct senc2d_descriptor* descriptor,
const unsigned iseg,
unsigned* gid);
+/* Returns the number of vertices that are frontier vertices:
+ * - that have arity 1 (single segment using the vertex)
+ * - that connect 2 different media */
SENC2D_API res_T
senc2d_descriptor_get_frontier_vertices_count
(const struct senc2d_descriptor* descriptor,
- unsigned* count); /* Number of frontier vertices. */
+ unsigned* count);
+/* Returns the iver_th frontier vertex; the returned index is an global unique
+ * vertex index. */
SENC2D_API res_T
senc2d_descriptor_get_frontier_vertex
(const struct senc2d_descriptor* descriptor,
@@ -303,39 +338,49 @@ senc2d_descriptor_ref_put
* An enclosure can list the "same" segment twice if both sides are in. In this
* case the 2 occurences of the segment have reversed vertices order and
* unique_segment_count and segment_count differ.
+ * Vertices and segments 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 segments (or properties) visit unique segments
* for indices in the [0 unique_segment_count[ range and back-faces of the
- * doubly-listed segments in the [unique_segment_count segment_count[ range.
+ * doubly-included segments in the [unique_segment_count segment_count[ range.
******************************************************************************/
+/* Returns the header of an enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_header
(const struct senc2d_enclosure* enclosure,
struct senc2d_enclosure_header* header);
+/* Returns the iseg_th segment of an enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_segment
(const struct senc2d_enclosure* enclosure,
const unsigned iseg,
unsigned indices[2]);
+/* Returns the coordinates of the ivert_th vertex of an enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_vertex
(const struct senc2d_enclosure* enclosure,
const unsigned ivert,
double coord[2]);
+/* Returns the front and back side media ids of the iseg_th segment of an
+ * enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_segment_media
(const struct senc2d_enclosure* enclosure,
const unsigned iseg,
unsigned medium[2]);
+/* Returns the global id of the iseg_th segment of an enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_segment_global_id
(const struct senc2d_enclosure* enclosure,
const unsigned iseg,
unsigned* gid);
+/* Returns the id of the imed_th medium of an enclosure. */
SENC2D_API res_T
senc2d_enclosure_get_medium
(const struct senc2d_enclosure* enclosure,
