commit 1bd5a776351aa1e583232659702f062ee3dcdb0c
parent 912c1e6946146693e3ecbf622a8e63573903db0c
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 9 Mar 2018 12:08:18 +0100
Update comments of the svx_hit_<challenge|filter>_T data types
Diffstat:
2 files changed, 29 insertions(+), 14 deletions(-)
diff --git a/src/svx.h b/src/svx.h
@@ -120,24 +120,38 @@ typedef void
const size_t ileaf, /* Identifier of the leaf in [0, #leafs[ */
void* context);
-/* Hit filter function data type. One can define such function to discard
- * intersections along a ray with respect to user defined criteria, e.g.:
- * masked/transparent voxel, etc. Return 0 or the intersection is not
- * discarded and a value not equal to zero otherwise. */
+/* Hit challenge data type. The caller can implement a function of this type to
+ * control the traversal of the octree hierarchy. If the function returns 1,
+ * the octree traversal will not go deeper into the hierarchy and the traversed
+ * voxel will be treated as a leaf. Note that this function is not invoked on
+ * intersected leaves */
typedef int
-(*svx_hit_filter_function_T)
+(*svx_hit_challenge_T)
+ (const struct svx_hit* hit,
+ void* context);
+
+/* Hit filter function data type. The caller can define a function of this type
+ * to control the treatment at each "leaf" intersected during the octree ray
+ * tracing. A intersected voxel is considered as a "leaf" if it is really a
+ * leaf, or if the svx_hit_challenge_T function returns a not null value. If
+ * the filter function returns 0, the octree traversal is stopped while a value
+ * !=0 lets the ray to pursue its traversal. Such functions can be used to
+ * discard specific voxels, to accumulate voxels data, to list the traversed
+ * voxels, etc. */
+ typedef int
+(*svx_hit_filter_T)
(const struct svx_hit* hit,
const double ray_org[3],
const double ray_dir[3],
const double ray_range[2],
void* context); /* User data submitted on trace ray invocation */
-/* Hit filter function data type. One can define such function to discard
- * voxels during the traversal of the octree with respect to user defined
- * criteria, eg, depth or size of the voxel, etc. Return 0 if the voxel is not
- * discarded and a value not equal to zero otherwise. */
+/* At filter function data type. One can define such function to discard voxels
+ * during the traversal of the octree with respect to user defined criteria,
+ * eg, depth or size of the voxel, etc. Return 0 if the voxel is not discarded
+ * and a value not equal to zero otherwise. */
typedef int
-(*svx_at_filter_function_T)
+(*svx_at_filter_T)
(const struct svx_voxel* voxel,
const double position[3],
void* context);
@@ -199,7 +213,7 @@ SVX_API res_T
svx_octree_for_each_leaf
(struct svx_octree* octree,
svx_leaf_function_T functor,
- void* context); /* Client data sent as the last argument of the callback */
+ void* context); /* Client data sent as the last argument of the functor */
SVX_API res_T
svx_octree_trace_ray
@@ -207,7 +221,8 @@ svx_octree_trace_ray
const double ray_origin[3],
const double ray_direction[3],
const double ray_range[2],
- svx_hit_filter_function_T filter,
+ const svx_hit_challenge_T challenge, /* NULL <=> Traversed up to the leaves */
+ const svx_hit_filter_T filter, /* NULL <=> Stop RT at the 1st hit voxel */
void* context, /* Data sent to the filter functor */
struct svx_hit* hit);
@@ -215,7 +230,7 @@ SVX_API res_T
svx_octree_at
(struct svx_octree* octree,
const double position[3],
- svx_at_filter_function_T filter,
+ svx_at_filter_T filter,
void* context, /* Client data sent as the last argument of the filter func */
struct svx_voxel* voxel);
diff --git a/src/svx_octree.c b/src/svx_octree.c
@@ -720,7 +720,7 @@ res_T
svx_octree_at
(struct svx_octree* oct,
const double position[3],
- svx_at_filter_function_T filter,
+ svx_at_filter_T filter,
void* context,
struct svx_voxel* voxel)
{
