commit 1c993002b2c9e957cbc0271290aa6a0778b1cd8a
parent 9dae4823d07e3b0435001a0e53b370ac54303a85
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 18 Mar 2015 15:40:58 +0100
Rename the s3d_scene_pull function in s3d_scene_build
Add some comments to the API header
Diffstat:
3 files changed, 38 insertions(+), 12 deletions(-)
diff --git a/src/s3d.h b/src/s3d.h
@@ -54,6 +54,8 @@
#define S3D(Func) s3d_ ## Func
#endif
+/* Syntactic sugar use during the setup of the shape. Setting a vertex data
+ * functor to S3D_KEEP means that this vertex data will not be updated */
#define S3D_KEEP NULL
/* Attributes of a shape */
@@ -80,15 +82,21 @@ struct s3d_attrib {
enum s3d_attrib_usage usage;
};
+/* Describe a per vertex data */
struct s3d_vertex_data {
+ /* Semantic of the data. Note that the S3D_GEOMETRY_NORMAL is not a valid
+ * vertex usage */
enum s3d_attrib_usage usage;
enum s3d_type type;
+ /* Retreive the vertex data value of `ivert'. Set it to S3D_KEEP, to keep the
+ * previously set data */
void (*get)
(const unsigned ivert, /* Index of the vertex */
float* value, /* Retrieved attrib value */
void* ctx); /* Pointer to user data */
};
+/* Invalid vertex data */
static const struct s3d_vertex_data S3D_VERTEX_DATA_NULL =
{ S3D_ATTRIBS_COUNT__, S3D_FLOAT, NULL };
@@ -125,6 +133,9 @@ struct mem_allocator;
* functions take 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.
+ *
+ * The s3d API is thread safe, i.e. the functions can be invoked concurrently
+ * by all threads that have a reference onto the function parameters
*/
BEGIN_DECLS
@@ -178,14 +189,18 @@ S3D_API res_T
s3d_scene_clear
(struct s3d_scene* scn);
+/* Synchronize the scene geometry with the geometry of its attached shapes. If
+ * one is tracing rays into the scene, it waits for the end of the ray-tracing
+ * to effectively update the scene representation */
S3D_API res_T
-s3d_scene_pull
+s3d_scene_build
(struct s3d_scene* scn);
/* Trace a ray into the scene 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 */
+ * 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 */
S3D_API res_T
s3d_scene_trace_ray
(struct s3d_scene* scn,
@@ -259,17 +274,24 @@ s3d_shape_sample
unsigned* iprim, /* Sampled primitive */
float uv[2]); /* Sampled barycentric coordinate onto `iprim' */
+/* Set/update the data of the triangular meshes. Can be invoked only on shape
+ * created with the s3d_shape_create_mesh function */
S3D_API res_T
s3d_shape_mesh_setup_indexed_vertices
(struct s3d_shape* shape,
const unsigned ntris,
- void (*get_indices)(const unsigned itri, unsigned ids[3], void* ctx),
+ void (*get_indices) /* May be S3D_KEEP, i.e. do not update the indices */
+ (const unsigned itri, unsigned ids[3], void* ctx),
const unsigned nverts,
+ /* List of the shape vertex data. Must have at least an attrib with the
+ * S3D_POSITION usage. The last element of the list must be
+ * S3D_VERTEX_DATA_NULL */
struct s3d_vertex_data attribs[],
- void* data);
+ void* data); /* Client data set as the last param of the vertex callbacks */
/* Setup the shape from a scene. Actually the resulting shape is an instance of
- * the scene */
+ * the scene. Can be invoked only on a shape created with the
+ * s3d_shape_create_group function */
S3D_API res_T
s3d_shape_group_setup_scene
(struct s3d_shape* shape,
diff --git a/src/s3d_scene.c b/src/s3d_scene.c
@@ -194,7 +194,7 @@ s3d_scene_create(struct s3d_device* dev, struct s3d_scene** out_scn)
res = RES_MEM_ERR;
goto error;
}
- /* Commit empty scene => the scene can be ray traced whithout any pull */
+ /* Commit empty scene => the scene can be ray traced whithout any build */
rtcCommit(scn->rtc_scn);
exit:
@@ -230,7 +230,7 @@ s3d_scene_attach_shape(struct s3d_scene* scn, struct s3d_shape* shape)
if(!scn || !shape)
return RES_BAD_ARG;
- /* Prevent the scene_<clear|pull|remove_shape> oprations */
+ /* Prevent the scene_<clear|build|remove_shape> oprations */
mutex_lock(scn->lock);
/* Prevent the shape_<attach|detach|setup> operations */
mutex_rw_wlock(shape->lock);
@@ -263,7 +263,7 @@ s3d_scene_clear(struct s3d_scene* scn)
if(!scn)
return RES_BAD_ARG;
- /* Prevent the scene_<attach_shape|remove_shape|pull> operations */
+ /* Prevent the scene_<attach_shape|remove_shape|build> operations */
mutex_lock(scn->lock);
LIST_FOR_EACH_SAFE(node, tmp, &scn->shapes) {
struct s3d_shape* shape = CONTAINER_OF
@@ -275,14 +275,14 @@ s3d_scene_clear(struct s3d_scene* scn)
}
res_T
-s3d_scene_pull(struct s3d_scene* scn)
+s3d_scene_build(struct s3d_scene* scn)
{
res_T res = RES_OK;
if(!scn)
return RES_BAD_ARG;
- /* Prevent the scene_<attach/remove_shape|clear|pull> operations */
+ /* Prevent the scene_<attach/remove_shape|clear|build> operations */
mutex_lock(scn->lock);
/* Prevent concurrent ray tracing */
mutex_rw_wlock(scn->lock_rtc);
@@ -313,8 +313,12 @@ s3d_scene_trace_ray
res_T res = RES_OK;
if(!scn || !org || !dir || !range || !hit)
return RES_BAD_ARG;
- if(!f3_is_normalized(dir) || range[0] < 0.f || range[0] > range[1])
+ if(!f3_is_normalized(dir))
return RES_BAD_ARG;
+ if(range[0] > range[1]) {
+ *hit = S3D_HIT_NULL;
+ return RES_OK;
+ }
f3_set(ray.org, org);
f3_set(ray.dir, dir);
diff --git a/src/test_s3d_trace_ray.c b/src/test_s3d_trace_ray.c
@@ -150,7 +150,7 @@ main(int argc, char** argv)
CHECK(s3d_scene_trace_ray(scn, NULL, dir, range, &hit), RES_BAD_ARG);
CHECK(s3d_scene_trace_ray(NULL, org, dir, range, &hit), RES_BAD_ARG);
CHECK(s3d_scene_trace_ray(scn, org, dir, range, &hit), RES_OK);
- CHECK(s3d_scene_pull(scn), RES_OK);
+ CHECK(s3d_scene_build(scn), RES_OK);
CHECK(s3d_scene_trace_ray(scn, org, dir, range, &hit), RES_OK);
f3(dir, 1.f, 1.f, 1.f);
CHECK(s3d_scene_trace_ray(scn, org, dir, range, &hit), RES_BAD_ARG);
