commit d9d2dcf73685c32b1a6346e5153e8cbf8426622f
parent 45d498b2c6ac70555264597a0f7e30c26321b0c4
Author: Vincent Forest <vincent.forest@meso-star.fr>
Date: Thu, 5 Mar 2015 14:39:32 +0100
Update the s3d API
A shape is no more created from a scene and can be freely
attached/detached to a scene.
Diffstat:
| M | src/s3d.h | | | 102 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------- |
1 file changed, 78 insertions(+), 24 deletions(-)
diff --git a/src/s3d.h b/src/s3d.h
@@ -59,6 +59,17 @@ enum s3d_shape_attrib {
S3D_SHAPE_UV /* Parametric coordinates */
};
+enum s3d_type {
+ S3D_FLOAT,
+ S3D_FLOAT2,
+ S3D_FLOAT3
+};
+
+struct s3d_attrib {
+ float value[4];
+ enum s3d_type type;
+};
+
/* Descriptor of a triangular mesh */
struct s3d_trimesh_desc {
unsigned (*get_tricount)(void*); /* # triangles */
@@ -82,27 +93,42 @@ struct s3d_hit {
const float distance; /* Hit distance from the ray origin */
};
-/* Constant defining a NULL intersection. May be used to initialize a hit */
+/* Constant defining a NULL intersection. Should be used to initialize a hit */
static const struct S3D_HIT_NULL = {NULL, 0, {0.f,0.f,0.f}, {0.f,0.f}, FLT_MAX};
-/* Helper macro that defines whether or not the hit is valid, i.e. a given ray
- * intersected something or not */
+/* Helper macro that defines whether or not the hit is valid, i.e. the ray
+ * intersects a shape or not */
#define S3D_HIT_NONE(Hit) ((Hit)->shape == NULL)
-/* Forward declaration of opaque data types */
+/* Forward declaration of s3d opaque data types */
struct s3d_device; /* Entry point of the library */
struct s3d_scene; /* Collection of shapes */
-struct s3d_shape; /* Untyped shape */
+struct s3d_shape; /* Untyped geometry */
+
+/* Forward declaration of external data types */
+struct logger;
+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
+ * decrement the reference counter, respectively. When this counter reach 0 the
+ * object is silently destroyed and should not be used anymore.
+ */
BEGIN_DECLS
/*******************************************************************************
- * Device API - The device is the entry point of the s3d library. It performs
- * resource and specific s3d library data management
+ * Device API - A device is the entry point of the s3d library. Applications
+ * use a s3d_device to create others s3d ressources.
******************************************************************************/
S3D_API res_T
s3d_device_create
- (struct s3d_device** dev);
+ (struct logger* logger, /* Maye be NULL <=> use default logger */
+ struct mem_allocator* allocator, /* May be NULL <=> use default allocator */
+ struct s3d_device** dev);
S3D_API res_T
s3d_device_ref_get
@@ -112,36 +138,51 @@ S3D_API res_T
s3d_device_ref_put
(struct s3d_device* dev);
+/*******************************************************************************
+ * Scene API - A scene is a collection of untyped shapes. It can be ray-traced
+ * and/or "instantiated" through a shape.
+ ******************************************************************************/
S3D_API res_T
s3d_scene_create
(struct s3d_device* dev,
- struct s3d_scene* scene);
+ struct s3d_scene* scn);
S3D_API res_T
s3d_scene_ref_get
- (struct s3d_scene* scene);
+ (struct s3d_scene* scn);
S3D_API res_T
s3d_scene_ref_put
- (struct s3d_scene* scene);
+ (struct s3d_scene* scn);
+/* 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 */
S3D_API res_T
-s3d_scene_create_shape
- (struct s3d_scene* scene,
- struct s3d_shape** shape);
+s3d_scene_attach_shape
+ (struct s3d_scene* scn,
+ struct s3d_shape* shp);
/* 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 */
+ * 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 */
S3D_API res_T
s3d_scene_trace_ray
- (struct s3d_scene* scene,
+ (struct s3d_scene* scn,
const float origin[3], /* Ray origin */
const float direction[3], /* Ray direction. Must be normalized */
const float range[2], /* In [0, INF)^2 */
struct s3d_hit* hit);
+/*******************************************************************************
+ * Shape API - A shape defines a geometry that can be attached to *one* scene.
+ ******************************************************************************/
+S3D_API res_T
+s3d_shape_create
+ (struct s3d_device* dev,
+ struct s3d_shape** shape);
+
S3D_API res_T
s3d_shape_ref_get
(struct s3d_shape* shape);
@@ -150,36 +191,49 @@ S3D_API res_T
s3d_shape_ref_put
(struct s3d_shape* shape);
+/* Enable/disable the shape, i.e. it cannot be hit when its associated scene is
+ * ray-traced or sampled */
S3D_API res_T
-s3d_shape_enable /* Enable/disable the shape. A disabled shape is not hit */
+s3d_shape_enable
(struct s3d_shape* shape,
const char enable);
+/* Setup the shape from a triangular mesh descriptor. The data retrieved
+ * through the mesh descriptor must be valid until the end of the function
+ * call */
S3D_API res_T
s3d_shape_setup_trimesh
(struct s3d_shape* shape,
const struct s3d_trimesh_desc* desc);
+/* Setup the shape from a scene. Actually the resulting shape is an instance of
+ * the scene */
S3D_API res_T
s3d_shape_setup_scene
(struct s3d_shape* shape,
struct s3d_scene* scene);
+/* Remove the shape from the scene on which it is attached. No error is
+ * reported if the shape is not attached to a scene. After its detachment, the
+ * scene release its reference on the shape */
+S3D_API res_T
+s3d_shape_detach
+ (struct s3d_shape* shape);
+
S3D_API res_T
s3d_shape_set_transform
(struct s3d_shape* shape,
- const enum s3d_matrix_layout layout,
- float transform[12]); /* 3x4 transform matrix */
+ const float transform[12]); /* 3x4 column major matrix */
/* Retrieve the attribute of the shape prim `iprim' at the barycentric
* coordinates `uv' */
S3D_API res_T
s3d_shape_get_attrib
(struct s3d_shape* shape,
- const enum s3d_shape_attrib attrib, /* Attribute to retrieve */
- const unsigned iprim, /* Index of the primitive */
- const float uv[2], /* Barycentric coordiataes */
- float attrib[3]);
+ const enum s3d_shape_attrib attr, /* Attribute to retrieve */
+ const unsigned iprim, /* Id of the primitive on which `attr' is retrieved */
+ const float uv[2], /* Barycentric coordinates of `attr' on `iprim' */
+ struct s3d_attrib* attrib); /* Resulting attrib */
/* Sample the shape with respect to 3 uniform random variables */
S3D_API res_T
