Blender V5.3
intersect_filter.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5/* Intersection and filtering functions for hardware ray-trace style of API.
6 *
7 * Filter functions are invoked for an intersection to give BVH traversal hints whether
8 * traversal is to continue. Returning true from filter functions means the intersection is
9 * filtered (ignored) and the traversal is to continue.
10 *
11 * Note on the template parameters
12 * ===============================
13 *
14 * perform_intersection_tests controls whether checks that are typically are performed during
15 * intersection are to be done in the filter function. Intersection checks that are done by the
16 * hardware do not perform self-intersection and shadow-linking checks: they are done in the
17 * filter function instead. However, if the intersection check uses custom function it performs
18 * these checks early on, so skipping them in the filter function will lead to a better
19 * performance. */
20
21#pragma once
22
23#include "kernel/bvh/util.h"
24#include "kernel/globals.h"
27#include "kernel/types.h"
28
30
41
42/* Special tricks to subclass payload.
43 * The issue here is Metal does not support subclassing, but HIP-RT had performance issues with
44 * composition in the past (see !136823). */
45#if defined(__KERNEL_HIPRT__)
46# define BVH_PAYLOAD_SUBCLASS(cls, base_cls) struct cls : base_cls
47# define BVH_PAYLOAD_SUBCLASS_DEFINE(base_cls)
48# define BVH_PAYLOAD_BASE(obj) (obj)
49#else
50# define BVH_PAYLOAD_SUBCLASS(cls, base_cls) struct cls
51# define BVH_PAYLOAD_SUBCLASS_DEFINE(base_cls) base_cls base;
52# define BVH_PAYLOAD_BASE(obj) ((obj).base)
53#endif
54
55struct BVHPayload {
56 /* In OptiX, self-intersection information and ray visibility are passed via Ray's pointer as
57 * extra payload data. */
58#if !defined(__KERNEL_OPTIX__)
59 /* Primitives for the self-intersections. */
61
62 /* Ray visibility flags and time. */
64#endif
65
66#if defined(__KERNEL_HIPRT__)
67 float ray_time;
68#endif
69};
70
71/* OptiX passes various parameters via registers to the tracing calls. No need to store duplicate
72 * data for OptiX. This will essentially make it so BVHPayload contains data which is strictly
73 * needed for intersection recording and for tracking curve transparency. */
74#if defined(__KERNEL_OPTIX__)
75# define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS(cls, base_cls) struct cls
76# define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS_DEFINE(base_cls)
77#else
78# define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS(cls, base_cls) BVH_PAYLOAD_SUBCLASS(cls, base_cls)
79# define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS_DEFINE(base_cls) BVH_PAYLOAD_SUBCLASS_DEFINE(base_cls)
80#endif
81
83{
85
86 /* Using uint16_t is slower on HIP, while it is similar performance but potentially lower memory
87 * footprint on other backends. */
88#if defined(__KERNEL_HIPRT__)
89 using UIntType = uint;
90#else
91 using UIntType = uint16_t;
92#endif
93
95
96 /* The maximum number of transparent intersections to consider: if there are more intersections
97 * than this value, all light is considered blocked. */
98 UIntType max_transparent_hits;
99 /* The number of transparent intersections tested during BVH traversal. It might be higher than
100 * the number of recorded intersections. */
101 UIntType num_transparent_hits = 0;
102
103 /* Maximum intersection distance t for intersections that are to be recorded.
104 * If intersection's distance exceeds this value, it is not recoded. */
105 float max_record_isect_t;
106
107 /* An index within the shadow_isect array at which the next intersection will be recorded. */
108 UIntType record_isect_index = 0;
109
110 /* The number of intersections that has been attempted to be recorded.
111 * It might be higher than the shadow_isect size, indicating that more invocations of the
112 * intersection kernel are needed. It is different from the num_transparent_hits as it does not
113 * include transparent curve intersections that are handled by accumulating throughput in the
114 * filter function. */
115 UIntType num_recorded_hits = 0;
116
117 /* Accumulated throughput of transparent curve intersections.
118 * Curves are using special optimization by baking their transparency and handling it in the
119 * filter function. */
120 float3 throughput = one_float3();
121};
122
123/* Filter intersection with possibly transparent surface.
124 *
125 * Designed to be used from the any-hit type of traversal:
126 * - If an opaque surface is hit, returns false, stopping traversal. The scene intersection
127 * function will consider the shadow ray to be blocked.
128 * - If a transparent surface is hit, the intersection is recorded into the shadow_isect array in
129 * the state. The closest N intersections are recorded. */
130template<uint perform_intersection_tests, uint enabled_primitive_types = PRIMITIVE_ALL>
132 KernelGlobals kg,
134 ccl_ray_data BVHShadowAllPayload &ccl_restrict payload,
136 const uint ray_visibility,
137 const Intersection isect)
138
139{
140#if defined(__VISIBILITY_FLAG__)
141 if constexpr ((perform_intersection_tests & ISECT_TEST_VISIBILITY_FLAG) != 0) {
142 if ((kernel_data_fetch(objects, isect.object).visibility & ray_visibility) == 0) {
143 return true;
144 }
145 }
146#endif
147
148#if defined(__SHADOW_LINKING__)
149 if constexpr ((perform_intersection_tests & ISECT_TEST_SHADOW_LINKING) != 0) {
150 if (intersection_skip_shadow_link(kg, ray_self, isect.object)) {
151 return true;
152 }
153 }
154#endif
155
156 if constexpr ((perform_intersection_tests & ISECT_TEST_SELF_SHADOW) != 0) {
157 if (intersection_skip_self_shadow(ray_self, isect.object, isect.prim)) {
158 return true;
159 }
160 }
161
162#if !defined(__TRANSPARENT_SHADOWS__)
163 /* No transparent shadows in the scene, all light is blocked and we can stop immediately. */
164 payload.throughput = zero_float3();
165 return false;
166#else
167 /* Detect if this surface has a shader with transparent shadows. */
168 /* TODO: optimize so primitive visibility flag indicates if the primitive has a transparent
169 * shadow shader? */
170 const int shader_flags = intersection_get_shader_flags(kg, isect.prim, isect.type);
171 if ((shader_flags & SD_HAS_TRANSPARENT_SHADOW) == 0) {
172 /* No transparent shadows for the shader, all light is blocked, and we can stop immediately. */
173 payload.throughput = zero_float3();
174 return false;
175 }
176
177 /* Fetch commonly accessed payload data, ensuring that it is used from either register to a
178 * stack, without going to the global memory. */
179 uint num_recorded_hits = payload.num_recorded_hits;
180
181 /* If the intersection is already recorded, ignore it completely: don't update throughput as it
182 * has already been updated. But also don't count it for num_hits as that could result in a
183 * situation when the same ray will be considered transparent when spatial split is off and be
184 * opaque when spatial split is on. Since curves do not record intersections, there is
185 * a possibility for optimization:
186 * - Don't compile this code if the filter is only used for curve primitives.
187 * - Don't run the check if the current intersection comes from the curve, as it will not match
188 * any recorded intersection anyway.
189 *
190 * NOTE: Currently, spatial splits are not used with OptiX, so there is no need to check whether
191 * the intersection has been already recorded. */
192# if !defined(__KERNEL_OPTIX__)
193 if constexpr ((enabled_primitive_types & (PRIMITIVE_ALL & ~PRIMITIVE_CURVE)) != 0) {
194 if ((isect.type & PRIMITIVE_CURVE) == 0) {
196 state, isect.object, isect.prim, num_recorded_hits))
197 {
198 return true;
199 }
200 }
201 }
202# endif
203
204 /* Only count transparent bounces, volume bounds bounces are counted when shading. */
205 payload.num_transparent_hits += !(shader_flags & SD_HAS_ONLY_VOLUME);
206 if (payload.num_transparent_hits > payload.max_transparent_hits) {
207 /* The maximum number of intersections has been reached, consider that all light has been
208 * blocked. */
209 payload.throughput = zero_float3();
210 return false;
211 }
212
213# if defined(__HAIR__)
214 if constexpr ((enabled_primitive_types & PRIMITIVE_CURVE) != 0) {
215 /* Always use baked shadow transparency for curves. */
216 if (isect.type & PRIMITIVE_CURVE) {
217 payload.throughput *= intersection_curve_shadow_transparency(
218 kg, isect.object, isect.prim, isect.type, isect.u);
219
220 if (reduce_max(payload.throughput) < CURVE_SHADOW_TRANSPARENCY_CUTOFF) {
221 /* Light attenuated too much through the curve intersections, assume all light is blocked
222 * and do early output. */
223 payload.throughput = zero_float3();
224 return false;
225 }
226
227 /* Don't record the intersection as the throughput has been already modified here.
228 * Simply continue BVH traversal for other intersections. */
229 return true;
230 }
231 }
232# endif
233
234 /* If the filter function only handles curves, it is known for the fact that nothing is to be
235 * recorded: curves accumulated baked transparency. Skip this code for a curve-only case. */
236 if constexpr ((enabled_primitive_types & (PRIMITIVE_ALL & ~PRIMITIVE_CURVE)) != 0) {
237 /* Always increase the number of recorded hits, even beyond the maximum, so that we can detect
238 * this and trace another ray if needed. */
239 num_recorded_hits += 1;
240 payload.num_recorded_hits = num_recorded_hits;
241
242 constexpr uint max_record_hits = INTEGRATOR_SHADOW_ISECT_SIZE;
243 if (num_recorded_hits <= max_record_hits || isect.t < payload.max_record_isect_t) {
244 integrator_state_write_shadow_isect(state, &isect, payload.record_isect_index);
245
246 if (num_recorded_hits >= max_record_hits) {
247 /* If the maximum number of hits is reached, find the furthest intersection to replace it
248 * with the next closer one. We want the N closest intersections. */
249 uint record_isect_index = 0;
250 float tmax_hits = INTEGRATOR_STATE_ARRAY(state, shadow_isect, 0, t);
251 for (uint i = 1; i < max_record_hits; ++i) {
252 const float isect_t = INTEGRATOR_STATE_ARRAY(state, shadow_isect, i, t);
253 if (isect_t > tmax_hits) {
254 record_isect_index = i;
255 tmax_hits = isect_t;
256 }
257 }
258 payload.max_record_isect_t = tmax_hits;
259 payload.record_isect_index = record_isect_index;
260 }
261 else {
262 payload.record_isect_index = num_recorded_hits;
263 }
264 }
265 }
266
267 return true;
268#endif
269}
270
271/* Filter intersection to intersections with only primitives with volume shader.
272 *
273 * Expected to be called only on a triangle primitive. The caller is to filter out intersections
274 * with non-triangle primitives.
275 *
276 * Returns false if the primitive is not to be filtered out (accepted), true if the primitive is to
277 * be ignored. */
278template<bool do_visibility_check = true>
280 KernelGlobals kg,
281 const int object,
282 const int prim,
284 const uint ray_visibility)
285{
286#ifdef __VISIBILITY_FLAG__
287 if constexpr (do_visibility_check) {
288 if ((kernel_data_fetch(objects, object).visibility & ray_visibility) == 0) {
289 return true;
290 }
291 }
292#endif
293
294 if ((kernel_data_fetch(object_flag, object) & SD_OBJECT_HAS_VOLUME) == 0) {
295 return true;
296 }
297
298 if (intersection_skip_self(ray_self, object, prim)) {
299 return true;
300 }
301
302 const int shader = kernel_data_fetch(tri_shader, prim);
303 const int shader_flag = kernel_data_fetch(shaders, (shader & SHADER_MASK)).flags;
304 if (!(shader_flag & SD_HAS_VOLUME)) {
305 return true;
306 }
307
308 return false;
309}
310
ccl_device_forceinline int intersection_get_shader_flags(KernelGlobals kg, const int prim, const int type)
ccl_device_inline bool intersection_skip_shadow_link(KernelGlobals kg, const ccl_ray_data RaySelfPrimitives &self, const int isect_object)
ccl_device_inline bool intersection_skip_self_shadow(const ccl_ray_data RaySelfPrimitives &self, const int object, const int prim)
ccl_device_inline bool intersection_skip_self(const ccl_ray_data RaySelfPrimitives &self, const int object, const int prim)
#define CURVE_SHADOW_TRANSPARENCY_CUTOFF
ccl_device_forceinline bool intersection_skip_shadow_already_recoded(IntegratorShadowState state, const int object, const int prim, const uint num_hits)
ccl_device_inline float3 intersection_curve_shadow_transparency(KernelGlobals kg, const int object, const int prim, const int type, const float u)
#define ccl_ray_data
#define ccl_restrict
#define ccl_device_forceinline
#define kernel_data_fetch(name, index)
#define INTEGRATOR_SHADOW_ISECT_SIZE
#define CCL_NAMESPACE_END
float reduce_max(float2 a)
ccl_device_forceinline bool bvh_shadow_all_anyhit_filter(KernelGlobals kg, IntegratorShadowState state, ccl_ray_data BVHShadowAllPayload &ccl_restrict payload, const ccl_ray_data RaySelfPrimitives &ccl_restrict ray_self, const uint ray_visibility, const Intersection isect)
#define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS_DEFINE(base_cls)
ccl_device_forceinline bool bvh_volume_anyhit_triangle_filter(KernelGlobals kg, const int object, const int prim, const ccl_ray_data RaySelfPrimitives &ccl_restrict ray_self, const uint ray_visibility)
IntersectionTest
@ ISECT_TEST_VISIBILITY_FLAG
@ ISECT_TEST_NONE
@ ISECT_TEST_SELF_SHADOW
@ ISECT_TEST_SHADOW_LINKING
@ ISECT_TEST_ALL
#define BVH_SHADOW_ALL_PAYLOAD_SUBCLASS(cls, base_cls)
const int state
@ SD_HAS_TRANSPARENT_SHADOW
@ SD_HAS_ONLY_VOLUME
@ SD_HAS_VOLUME
@ PRIMITIVE_ALL
@ PRIMITIVE_CURVE
@ SD_OBJECT_HAS_VOLUME
@ SHADER_MASK
ccl_device_inline float3 one_float3()
Definition math_float3.h:26
CCL_NAMESPACE_BEGIN ccl_device_inline float3 zero_float3()
Definition math_float3.h:17
IntegratorShadowStateCPU * IntegratorShadowState
Definition state.h:229
#define INTEGRATOR_STATE_ARRAY(state, nested_struct, array_index, member)
Definition state.h:237
ccl_device_forceinline void integrator_state_write_shadow_isect(IntegratorShadowState state, const ccl_private Intersection *ccl_restrict isect, const int index)
Definition state_util.h:284
RaySelfPrimitives ray_self