commit 1d52623d71d06baaff9c5bc182db71c6ab75e6c6
parent 969bbf55d3833753fbdd4d9dc62641d66015b3eb
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 27 Mar 2015 12:45:28 +0100
Update the API comments
Diffstat:
2 files changed, 31 insertions(+), 30 deletions(-)
diff --git a/src/s3d.h b/src/s3d.h
@@ -37,9 +37,9 @@
#include <float.h>
/* Library symbol management */
-#if defined(S3D_SHARED_BUILD)
+#if defined(S3D_SHARED_BUILD) /* Build shared library */
#define S3D_API extern EXPORT_SYM
-#elif defined(S3D_STATIC)
+#elif defined(S3D_STATIC) /* Use/build static library */
#define S3D_API extern LOCAL_SYM
#else /* Use shared library */
#define S3D_API extern IMPORT_SYM
@@ -47,7 +47,7 @@
/* Helper macro that asserts if the invocation of the s3d function `Func'
* returns an error. One should use this macro on s3d function calls for which
- * no explicit error checking is performed */
+ * no explicit error checking is performed */
#ifndef NDEBUG
#define S3D(Func) ASSERT(s3d_ ## Func == RES_OK)
#else
@@ -67,7 +67,7 @@ enum s3d_attrib_usage {
S3D_ATTRIB_3, /* Generic attrib 3 */
S3D_ATTRIBS_COUNT__,
/* Unormalized world space face normal. Outward orientation defined with
- * respect to the Counter Clock Wise vertex ordering */
+ * respect to the Clock Wise vertex ordering */
S3D_GEOMETRY_NORMAL
};
@@ -79,8 +79,8 @@ enum s3d_type {
};
enum s3d_transform_space {
- S3D_LOCAL_TRANSFORM,
- S3D_WORLD_TRANSFORM
+ S3D_LOCAL_TRANSFORM, /* The transformation is local to the shape space */
+ S3D_WORLD_TRANSFORM /* The transformation is expressed in world space */
};
struct s3d_primitive {
@@ -90,6 +90,7 @@ struct s3d_primitive {
unsigned igeom__;
};
+/* Untyped vertex attribute */
struct s3d_attrib {
float value[4];
enum s3d_type type;
@@ -117,7 +118,7 @@ static const struct s3d_vertex_data S3D_VERTEX_DATA_NULL =
/* Intersection point */
struct s3d_hit {
struct s3d_primitive prim; /* Intersected primitive */
- float normal[3]; /* Unormalized geometry normal */
+ float normal[3]; /* Unnormalized geometry normal */
float uv[2]; /* Barycentric coordinates of the hit onto `prim' */
float distance; /* Hit distance from the ray origin */
};
@@ -143,16 +144,16 @@ struct mem_allocator;
* All the s3d structures are ref counted. Once created with the appropriated
* `s3d_<TYPE>_create' function, the caller implicitly owns the created data,
* i.e. its reference counter is set to 1. The s3d_<TYPE>_ref_<get|put>
- * functions take or release a reference on the data, i.e. they increment or
+ * functions get or release a reference on the data, i.e. they increment or
* decrement the reference counter, respectively. When this counter reach 0 the
- * object is silently destroyed and should not be used anymore.
+ * object is silently destroyed and cannot be used anymore.
*/
BEGIN_DECLS
/*******************************************************************************
* Device API - A device is the entry point of the s3d library. Applications
- * use a s3d_device to create others s3d ressources.
+ * use a s3d_device to create others s3d resources.
******************************************************************************/
S3D_API res_T
s3d_device_create
@@ -192,7 +193,7 @@ s3d_scene_instantiate
/* Attach the shape to the scene. If the shape is already attached to the same
* or another scene, nothing is performed and a RES_BAD_ARG error is returned.
- * On success, the scene takes a reference onto the attached shape */
+ * On success, the scene gets a reference onto the attached shape */
S3D_API res_T
s3d_scene_attach_shape
(struct s3d_scene* scn,
@@ -212,25 +213,25 @@ s3d_scene_clear
(struct s3d_scene* scn);
/* Synchronize the scene geometry with the geometry of its attached shapes. If
- * a s3d_scene_begin_trace call is currently active on an attached instance a
- * RES_BAD_OP error is returned. On success no other begin trace can be invoked
- * on `scn' and its instances until s3d_scene_end_trace is called. A
- * s3d_scene_trace_ray operation can be invoked on scn only between a
- * s3d_scene_begin_trace and s3d_scene_end_trace call. */
+ * a s3d_scene_begin_trace is already active on `scn' or one of its attached
+ * instance a RES_BAD_OP error is returned. On success no other begin trace can
+ * be invoked on `scn' and its attached instances until s3d_scene_end_trace is
+ * called. A s3d_scene_trace_ray operation can be invoked on `scn' only between
+ * a s3d_scene_begin_trace and s3d_scene_end_trace call. */
S3D_API res_T
s3d_scene_begin_trace
(struct s3d_scene* scn);
-/* End the trace operation on the scene */
+/* End the trace operation on the `scn' */
S3D_API res_T
s3d_scene_end_trace
(struct s3d_scene* scn);
-/* Trace a ray into the scene and return the closest intersection. The ray is
+/* Trace a ray into the `scn' and return the closest intersection. The ray is
* defined by `origin' + t*`direction' = 0 with t in [`range[0]', `range[1]').
* Note that if range is degenerated (i.e. `range[0]' >= `range[1]') then the
- * ray is not traced and `hit' is set to S3D_HIT_NULL. If `scn' is building it
- * waits for the end of the scene construction to trace the ray */
+ * ray is not traced and `hit' is set to S3D_HIT_NULL. This function can be
+ * called only if a s3d_scene_begin_trace operation is active on `scn' */
S3D_API res_T
s3d_scene_trace_ray
(struct s3d_scene* scn,
@@ -268,7 +269,8 @@ s3d_shape_is_attached
(struct s3d_shape* shape,
char* is_attached);
-/* Sample the shape with respect to 3 uniform random variables */
+/* Sample the shape with respect to 3 uniform random variables. TODO not
+ * implemented yet */
S3D_API res_T
s3d_shape_sample
(struct s3d_shape* shape,
@@ -280,7 +282,7 @@ s3d_shape_sample
/*******************************************************************************
* Primitive API - Define a geometric primitive of a shape
******************************************************************************/
-/* Retrieve the attribute of the shape prim `iprim' at the barycentric
+/* Retrieve the attribute of the shape primitive `iprim' at the barycentric
* coordinates `uv' */
S3D_API res_T
s3d_primitive_get_attrib
@@ -290,7 +292,7 @@ s3d_primitive_get_attrib
struct s3d_attrib* attrib); /* Resulting attrib */
/*******************************************************************************
- * Mesh API - Define a triangluar meshes
+ * Mesh API - Define a triangular meshes
******************************************************************************/
/* Set/update the data of the indexed triangular meshes */
S3D_API res_T
@@ -304,21 +306,19 @@ s3d_mesh_setup_indexed_vertices
* S3D_POSITION usage. The last element of the list must be
* S3D_VERTEX_DATA_NULL */
struct s3d_vertex_data attribs[],
- void* data); /* Client data set as the last param of the vertex callbacks */
+ void* data); /* Client data set as the last param of the callbacks */
/*******************************************************************************
- * Instance API - An instance is a shape that encapsulates a scene. One can
- * define a specific local to world transformation to an instance. Since the
- * scene geometry is stored only a single time even though it is instantiated
- * in several positions, one can use this feature to create extremerly large
- * scene
+ * Instance API - An instance is a shape that encapsulates a scene and that
+ * supports a local to world transformation. Since the scene geometry is stored
+ * only a single time even though it is instantiated in several positions, one
+ * can use this feature to create extremely large scene
* ******************************************************************************/
S3D_API res_T
s3d_instance_set_position
(struct s3d_shape* shape,
const float position[3]);
-/* Can be invoked only on a shape instantioed with s3d_scene_instantiate */
S3D_API res_T
s3d_instance_translate
(struct s3d_shape* shape,
diff --git a/src/test_s3d_trace_ray.c b/src/test_s3d_trace_ray.c
@@ -213,6 +213,7 @@ main(int argc, char** argv)
CHECK(s3d_scene_end_trace(scn), RES_OK);
CHECK(s3d_scene_begin_trace(scn2), RES_OK);
CHECK(s3d_scene_begin_trace(scn), RES_BAD_OP);
+ CHECK(s3d_scene_end_trace(scn), RES_BAD_OP);
camera_init(&cam);
FOR_EACH(iy, 0, IMG_HEIGHT) {
