Blender V5.3
eevee_light_culling.bsl.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#pragma once
6
8#include "draw_shape.bsl.hh"
9#include "draw_view.bsl.hh"
10#include "eevee_hiz.bsl.hh"
13#include "eevee_light_shared.hh"
17
19
23struct Cull {
24 [[uniform(0)]] const LightData (&sunlight_buf)[2];
25
26 [[storage(0, read_write)]] LightCullingData &light_cull_buf;
27 [[storage(1, read)]] const LightData (&in_light_buf)[];
28
29 [[storage(2, write)]] LightData (&out_light_buf)[];
30 [[storage(3, write)]] float (&out_zdist_buf)[];
31 [[storage(4, write)]] uint (&out_key_buf)[];
32};
33
34[[compute, local_size(CULLING_SELECT_GROUP_SIZE)]]
36 [[resource_table]] const draw::View &views,
38 [[global_invocation_id]] const uint3 global_id)
39{
40 uint l_idx = global_id.x;
41 if (l_idx >= srt.light_cull_buf.items_count) {
42 return;
43 }
44
45 LightData light = srt.in_light_buf[l_idx];
46
47 /* Sun lights are packed at the end of the array. Perform early copy. */
48 if (is_sun_light(light.type)) {
49 /* Some sun-lights are reserved for world light. Perform copy from dedicated buffer. */
50 bool is_world_sun_light = light.color.r < 0.0f;
51 if (is_world_sun_light) {
52 light.color = srt.sunlight_buf[l_idx].color;
53 light.object_to_world = srt.sunlight_buf[l_idx].object_to_world;
54
55 LightSunData sun_data = light.sun;
56 sun_data.direction = srt.sunlight_buf[l_idx].object_to_world.z_axis();
57 light.sun = sun_data;
58 /* NOTE: Use the radius from UI instead of auto sun size for now. */
59 }
60 /* NOTE: We know the index because sun lights are packed at the start of the input buffer. */
61 srt.out_light_buf[srt.light_cull_buf.local_lights_len + l_idx] = light;
62 return;
63 }
64
65 /* Do not select 0 power lights. */
66 if (light.local.local.influence_radius_max < 1e-8f) {
67 return;
68 }
69
70 Sphere sphere;
71 switch (light.type) {
72 case LIGHT_SPOT_SPHERE:
73 case LIGHT_SPOT_DISK: {
74 LightSpotData spot = light.spot;
75 /* Only for < ~170 degree Cone due to plane extraction precision. */
76 if (spot.spot_tan < 10.0f) {
77 float3 x_axis = light.x_axis();
78 float3 y_axis = light.y_axis();
79 float3 z_axis = light.z_axis();
81 light.position(),
82 light.position() - z_axis * spot.local.influence_radius_max,
83 x_axis * spot.local.influence_radius_max * spot.spot_tan / spot.spot_size_inv.x,
84 y_axis * spot.local.influence_radius_max * spot.spot_tan / spot.spot_size_inv.y);
85 if (!culling.intersect_view(pyramid, 0)) {
86 return;
87 }
88 }
89 [[fallthrough]];
90 }
91 case LIGHT_RECT:
92 case LIGHT_ELLIPSE:
93 case LIGHT_OMNI_SPHERE:
94 case LIGHT_OMNI_DISK:
95 sphere.center = light.position();
96 sphere.radius = light.local.local.influence_radius_max;
97 break;
98 default:
99 break;
100 }
101
102 /* TODO(fclem): HiZ culling? Could be quite beneficial given the nature of the 2.5D culling. */
103
104 /* TODO(fclem): Small light culling / fading? */
105
106 if (culling.intersect_view(sphere, 0)) {
107 const ViewMatrices view = views.get(0);
108 uint index = atomicAdd(srt.light_cull_buf.visible_count, 1u);
109
110 float z_dist = dot(view.forward(), light.position()) - dot(view.forward(), view.position());
111 srt.out_zdist_buf[index] = z_dist;
112 srt.out_key_buf[index] = l_idx;
113 }
114}
115
121struct Sort {
122 [[shared]] float zdists_cache[CULLING_SORT_GROUP_SIZE];
123
124 [[storage(0, read)]] const LightCullingData &light_cull_buf;
125
126 [[storage(1, read)]] const LightData (&in_light_buf)[];
127 [[storage(2, read)]] const float (&in_zdist_buf)[];
128 [[storage(3, read)]] const uint (&in_key_buf)[];
129
130 [[storage(4, write)]] LightData (&out_light_buf)[];
131};
132
133[[compute, local_size(CULLING_SORT_GROUP_SIZE)]]
135 [[global_invocation_id]] const uint3 global_id,
136 [[local_invocation_id]] const uint3 local_id)
137{
138 /* Early exit if no lights are present to prevent out of bounds buffer read. */
139 if (srt.light_cull_buf.visible_count == 0) {
140 return;
141 }
142
143 const uint group_size = CULLING_SORT_GROUP_SIZE;
144 uint src_index = global_id.x;
145 bool valid_thread = true;
146
147 if (src_index >= srt.light_cull_buf.visible_count) {
148 /* Do not return because we use barriers later on (which need uniform control flow).
149 * Just process the same last item but avoid insertion. */
150 src_index = srt.light_cull_buf.visible_count - 1;
151 valid_thread = false;
152 }
153
154 float local_zdist = srt.in_zdist_buf[src_index];
155
156 int prefix_sum = 0;
157 /* Iterate over the whole key buffer. */
158 uint iter = divide_ceil(srt.light_cull_buf.visible_count, group_size);
159 for (uint i = 0u; i < iter; i++) {
160 uint index = group_size * i + local_id.x;
161 /* NOTE: This will load duplicated values, but they will be discarded. */
162 index = min(index, srt.light_cull_buf.visible_count - 1);
163 srt.zdists_cache[local_id.x] = srt.in_zdist_buf[index];
164
165 barrier();
166
167 /* Iterate over the cache line. */
168 uint line_end = min(group_size, srt.light_cull_buf.visible_count - group_size * i);
169 for (uint j = 0u; j < line_end; j++) {
170 if (srt.zdists_cache[j] < local_zdist) {
171 prefix_sum++;
172 }
173 else if (srt.zdists_cache[j] == local_zdist) {
174 /* Same depth, use index to order and avoid same prefix for 2 different lights. */
175 if ((group_size * i + j) < src_index) {
176 prefix_sum++;
177 }
178 }
179 }
180
181 barrier();
182 }
183
184 if (valid_thread) {
185 /* Copy sorted light to render light buffer. */
186 uint input_index = srt.in_key_buf[src_index];
187 srt.out_light_buf[prefix_sum] = srt.in_light_buf[input_index];
188 }
189}
190
196
197struct ZBinning {
198 /* Fits the limit of 32KB. */
199 [[shared]] uint zbin_max[CULLING_ZBIN_COUNT];
200 [[shared]] uint zbin_min[CULLING_ZBIN_COUNT];
201
202 [[storage(0, read)]] const LightCullingData &light_cull_buf;
203 [[storage(1, read)]] const LightData (&light_buf)[];
204 [[storage(2, write)]] uint (&out_zbin_buf)[];
205};
206
207[[compute, local_size(CULLING_ZBIN_GROUP_SIZE)]]
209 [[resource_table]] const draw::View &views,
210 [[local_invocation_id]] const uint3 local_id)
211{
212 constexpr uint zbin_iter = uint(CULLING_ZBIN_COUNT / CULLING_ZBIN_GROUP_SIZE);
213 const uint zbin_local = local_id.x * zbin_iter;
214
215 for (uint i = 0u, l = zbin_local; i < zbin_iter; i++, l++) {
216 srt.zbin_max[l] = 0x0u;
217 srt.zbin_min[l] = ~0x0u;
218 }
219 barrier();
220
221 const ViewMatrices view = views.get(0);
222
223 uint light_iter = divide_ceil(srt.light_cull_buf.visible_count, uint(CULLING_ZBIN_GROUP_SIZE));
224 for (uint i = 0u; i < light_iter; i++) {
225 uint index = i * CULLING_ZBIN_GROUP_SIZE + local_id.x;
226 if (index >= srt.light_cull_buf.visible_count) {
227 continue;
228 }
229 LightData light = srt.light_buf[index];
230 float3 P = light.position();
231 /* TODO(fclem): Could have better bounds for spot and area lights. */
232 float radius = light.local.local.influence_radius_max;
233 float z_dist = dot(view.forward(), P) - dot(view.forward(), view.position());
234 int z_min = culling_z_to_zbin(
235 srt.light_cull_buf.zbin_scale, srt.light_cull_buf.zbin_bias, z_dist + radius);
236 int z_max = culling_z_to_zbin(
237 srt.light_cull_buf.zbin_scale, srt.light_cull_buf.zbin_bias, z_dist - radius);
238 z_min = clamp(z_min, 0, CULLING_ZBIN_COUNT - 1);
239 z_max = clamp(z_max, 0, CULLING_ZBIN_COUNT - 1);
240 /* Register to Z bins. */
241 for (int z = z_min; z <= z_max; z++) {
242 atomicMin(srt.zbin_min[z], index);
243 atomicMax(srt.zbin_max[z], index);
244 }
245 }
246 barrier();
247
248 /* Write result to Z-bins buffer. Pack min & max into 1 `uint`. */
249 for (uint i = 0u, l = zbin_local; i < zbin_iter; i++, l++) {
250 srt.out_zbin_buf[l] = (srt.zbin_max[l] << 16u) | (srt.zbin_min[l] & 0xFFFFu);
251 }
252}
253
259
263
264 static CullingTile from_corners(bool is_persp, float3 corners[8])
265 {
267 tile.bounds = (is_persp) ? tile_bound_cone(corners[0], corners[4], corners[7], corners[3]) :
268 tile_bound_cylinder(corners[0], corners[4], corners[7], corners[3]);
269
270 tile.frustum = isect_frustum_setup(shape_frustum(corners));
271 return tile;
272 }
273
274 bool intersect(const ViewMatrices view, Sphere sphere)
275 {
276 bool isect = true;
277 /* Test tile intersection using bounding cone or bounding cylinder.
278 * This has less false positive cases when the sphere is large. */
279 if (view.is_perspective()) {
280 isect = ::intersect(shape_cone(this->bounds.xyz, this->bounds.w), sphere);
281 }
282 else {
283 /* Simplify to a 2D circle test on the view Z axis plane. */
284 isect = ::intersect(shape_circle(this->bounds.xy, this->bounds.w),
285 shape_circle(sphere.center.xy, sphere.radius));
286 }
287 /* Refine using frustum test. If the sphere is small it avoids intersection
288 * with a neighbor tile. */
289 if (isect) {
290 isect = ::intersect(this->frustum, sphere);
291 }
292 return isect;
293 }
294
295 bool intersect(Box bbox)
296 {
297 return ::intersect(this->frustum, bbox);
298 }
299
300 bool intersect(Pyramid pyramid)
301 {
302 return ::intersect(this->frustum, pyramid);
303 }
304
305 private:
306 /* Corners are expected to be in view-space so that the cone is starting from the origin.
307 * Corner order does not matter. */
308 static float4 tile_bound_cone(float3 v00, float3 v01, float3 v10, float3 v11)
309 {
310 v00 = normalize(v00);
311 v01 = normalize(v01);
312 v10 = normalize(v10);
313 v11 = normalize(v11);
314 float3 center = normalize(v00 + v01 + v10 + v11);
315 float angle_cosine = dot(center, v00);
316 angle_cosine = min(angle_cosine, dot(center, v01));
317 angle_cosine = min(angle_cosine, dot(center, v10));
318 angle_cosine = min(angle_cosine, dot(center, v11));
319 /* Widen by moving to next representable float to account for float rounding. */
320 angle_cosine = uintBitsToFloat(floatBitsToUint(angle_cosine) - 1u);
321 return float4(center, angle_cosine);
322 }
323
324 /* Corners are expected to be in view-space. Returns Z-aligned bounding cylinder.
325 * Corner order does not matter. */
326 static float4 tile_bound_cylinder(float3 v00, float3 v01, float3 v10, float3 v11)
327 {
328 float3 center = (v00 + v01 + v10 + v11) * 0.25f;
329 float dist_sqr = distance_squared(center, v00);
330 dist_sqr = max(dist_sqr, distance_squared(center, v01));
331 dist_sqr = max(dist_sqr, distance_squared(center, v10));
332 dist_sqr = max(dist_sqr, distance_squared(center, v11));
333 /* Return a cone. Later converted to cylinder. */
334 return float4(center, sqrt(dist_sqr));
335 }
336};
337
338struct Tile {
339 [[storage(0, read)]] const LightCullingData &light_cull_buf;
340 [[storage(1, read)]] const LightData (&light_buf)[];
341
342 [[storage(2, write)]] uint (&out_light_tile_buf)[];
343
345 {
346 /* Add a margin to prevent culling too much if the frustum becomes too much unstable. */
347 constexpr float margin = 0.02f;
348 tile_co += margin * (offset * 2.0f - 1.0f);
349
350 tile_co += offset;
351 return tile_co * light_cull_buf.tile_to_uv_fac * 2.0f - 1.0f;
352 }
353
355 {
356 float2 ftile = float2(tile_co);
357 /* Culling frustum corners for this tile. */
358 float3 corners[8];
359 /* Follow same corners order as view frustum. */
360 corners[1].xy = corners[0].xy = tile_to_ndc(ftile, float2(0, 0));
361 corners[5].xy = corners[4].xy = tile_to_ndc(ftile, float2(1, 0));
362 corners[6].xy = corners[7].xy = tile_to_ndc(ftile, float2(1, 1));
363 corners[2].xy = corners[3].xy = tile_to_ndc(ftile, float2(0, 1));
364 corners[1].z = corners[5].z = corners[6].z = corners[2].z = -1.0f;
365 corners[0].z = corners[4].z = corners[7].z = corners[3].z = 1.0f;
366
367 for (int i = 0; i < 8; i++) [[unroll]] {
368 /* Culling in view space for precision. */
369 corners[i] = project_point(view.wininv, corners[i]);
370 }
371
372 bool is_persp = view.winmat[3][3] == 0.0f;
373 return CullingTile::from_corners(is_persp, corners);
374 }
375};
376
377[[compute, local_size(CULLING_TILE_GROUP_SIZE)]]
378void tile_main([[resource_table]] const draw::View &views,
379 [[resource_table]] Tile &srt,
380 [[global_invocation_id]] const uint3 global_id)
381{
382 uint word_idx = global_id.x % srt.light_cull_buf.tile_word_len;
383 uint tile_idx = global_id.x / srt.light_cull_buf.tile_word_len;
384 uint2 tile_co = uint2(tile_idx % srt.light_cull_buf.tile_x_len,
385 tile_idx / srt.light_cull_buf.tile_x_len);
386
387 if (tile_co.y >= srt.light_cull_buf.tile_y_len) {
388 return;
389 }
390
391 const ViewMatrices view = views.get(0);
392
393 /* TODO(fclem): We could stop the tile at the HiZ depth. */
394 CullingTile tile = srt.tile_culling_get(view, tile_co);
395
396 uint l_idx = word_idx * 32u;
397 uint l_end = min(l_idx + 32u, srt.light_cull_buf.visible_count);
398 uint word = 0u;
399 for (; l_idx < l_end; l_idx++) {
400 LightData light = srt.light_buf[l_idx];
401
402 /* Culling in view space for precision and simplicity. */
403 float3 vP = view.point_world_to_view(light.position());
404 float3 v_right = view.normal_world_to_view(light.x_axis());
405 float3 v_up = view.normal_world_to_view(light.y_axis());
406 float3 v_back = view.normal_world_to_view(light.z_axis());
407 float radius = light.local.local.influence_radius_max;
408
409 if (srt.light_cull_buf.view_is_flipped) {
410 v_right = -v_right;
411 }
412
413 Sphere sphere = shape_sphere(vP, radius);
414 bool intersect_tile = tile.intersect(view, sphere);
415
416 switch (light.type) {
417 case LIGHT_SPOT_SPHERE:
418 case LIGHT_SPOT_DISK: {
419 LightSpotData spot = light.spot;
420 /* Only for < ~170 degree Cone due to plane extraction precision. */
421 if (spot.spot_tan < 10.0f) {
423 vP,
424 vP - v_back * radius,
425 v_right * radius * spot.spot_tan / spot.spot_size_inv.x,
426 v_up * radius * spot.spot_tan / spot.spot_size_inv.y);
427 intersect_tile = intersect_tile && tile.intersect(pyramid);
428 break;
429 }
430 /* Fall-through to the hemispheric case. */
431 [[fallthrough]];
432 }
433 case LIGHT_RECT:
434 case LIGHT_ELLIPSE: {
435 float3 v000 = vP - v_right * radius - v_up * radius;
436 float3 v100 = v000 + v_right * (radius * 2.0f);
437 float3 v010 = v000 + v_up * (radius * 2.0f);
438 float3 v001 = v000 - v_back * radius;
439 Box bbox = shape_box(v000, v100, v010, v001);
440 intersect_tile = intersect_tile && tile.intersect(bbox);
441 break;
442 }
443 default:
444 break;
445 }
446
447 if (intersect_tile) {
448 word |= 1u << (l_idx % 32u);
449 }
450 }
451
452 srt.out_light_tile_buf[global_id.x] = word;
453}
454
459
463
468
469[[vertex]]
470void debug_vert([[vertex_id]] const int vert_id,
471 [[position]] float4 &out_position,
472 [[out]] DebugVertOut &v_out)
473{
474 fullscreen_vertex(vert_id, out_position, v_out.screen_uv);
475}
476
477struct NoCullCtx {
480
481 void eval_directional(LightRenderData & /*lrd*/, uint /*l_idx*/, LightData /*light*/) {}
482
483 void eval_local(LightRenderData & /*lrd*/, uint l_idx, LightData /*light*/)
484 {
485 light_bits |= 1u << l_idx;
486 light_count += 1.0f;
487 }
488};
489
493
494 void eval_directional(LightRenderData & /*lrd*/, uint /*l_idx*/, LightData /*light*/) {}
495
496 void eval_local(LightRenderData & /*lrd*/, uint l_idx, LightData light)
497 {
498 LightVector lv = LightVector::get(light, false, P);
500 light_bits |= 1u << l_idx;
501 }
502 }
503};
504
505} // namespace eevee::light::culling
506
507namespace eevee::light {
508
512
515
516} // namespace eevee::light
517
518namespace eevee::light::culling {
519[[fragment]]
522 [[resource_table]] const HiZ &hiz,
523 [[frag_coord]] const float4 frag_co,
524 [[in]] const DebugVertOut &v_out,
525 [[out]] DebugFragOut &frag_out)
526{
527 int2 texel = int2(frag_co.xy);
528
529 const ViewMatrices view = views.get(0);
530
531 float depth = texelFetch(hiz.hiz_tx, texel, 0).r;
532 float vP_z = view.depth_screen_to_view(depth);
533 float3 P = view.point_screen_to_world(float3(v_out.screen_uv, depth));
534
535 NoCullCtx no_cull = {};
536 light::foreach(lrd, no_cull, lrd);
537
538 WithCullCtx with_cull = {.P = P};
539 light::foreach_visible(lrd, frag_co.xy, vP_z, with_cull, lrd);
540
541 float4 color = float4(heatmap_gradient(no_cull.light_count / 4.0f), 1.0f);
542
543 if ((with_cull.light_bits & no_cull.light_bits) != no_cull.light_bits) {
544 /* ERROR. Some lights were culled incorrectly. */
545 color = float4(0.0f, 1.0f, 0.0f, 1.0f);
546 }
547
548 frag_out.out_debug_color_add = float4(color.rgb, 0.0f) * 0.2f;
549 frag_out.out_debug_color_mul = color;
550}
551
553
554} // namespace eevee::light::culling
btScalar max
SIMD_FORCE_INLINE const btScalar & z() const
Return the z value.
Definition btQuadWord.h:117
IsectFrustum isect_frustum_setup(Frustum shape)
Sphere shape_sphere(float3 center, float radius)
Cone shape_cone(float3 direction, float angle_cosine)
Frustum shape_frustum(float3 corners[8])
Box shape_box(float3 v000, float3 v100, float3 v010, float3 v001)
Pyramid shape_pyramid_non_oblique(float3 apex, float3 base_center, float3 base_center_pos_x, float3 base_center_pos_y)
Circle shape_circle(float2 center, float radius)
#define LIGHT_ATTENUATION_THRESHOLD
float light_attenuation_surface(LightData light, const bool is_directional, LightVector lv)
#define shared
#define uniform(slot)
#define storage(slot, qualifiers)
#define position
#define index(i)
#define frag_coord
#define smooth
#define resource_table
#define global_invocation_id
#define fragment
#define local_invocation_id
#define vertex_id
#define unroll
#define compute
#define vertex
#define frag_color(slot)
#define local_size(...)
int atomicMin(int &, int) RET
int atomicMax(int &, int) RET
VecBase< float, D > normalize(VecOp< float, D >) RET
float dot(VecOp< float, D >, VecOp< float, D >) RET
VecBase< uint, D > floatBitsToUint(VecOp< float, D >) RET
int atomicAdd(int &, int) RET
#define sqrt
VecBase< float, D > uintBitsToFloat(VecOp< uint, D >) RET
void barrier()
constexpr T clamp(T, U, U) RET
TEX_TEMPLATE DataVec texelFetch(T, IntCoord, int) RET
float3 heatmap_gradient(float t)
void fullscreen_vertex(int vertex_id, float4 &out_position)
int divide_ceil(int a, int b)
float2 project_point(float3x3 mat, float2 point)
float distance_squared(VecT a, VecT b)
void cull_main(Cull &srt, const draw::View &views, const draw::ViewCulling &culling, const uint3 global_id)
void debug_frag(const draw::View &views, LightRenderData &lrd, const HiZ &hiz, const float4 frag_co, const DebugVertOut &v_out, DebugFragOut &frag_out)
void debug_vert(const int vert_id, float4 &out_position, DebugVertOut &v_out)
PipelineCompute tile(tile_main)
PipelineGraphic debug(debug_vert, debug_frag)
PipelineCompute sort(sort_main)
PipelineCompute cull(cull_main)
void sort_main(Sort &srt, const uint3 global_id, const uint3 local_id)
PipelineCompute zbin(zbin_main)
void zbin_main(ZBinning &srt, const draw::View &views, const uint3 local_id)
void tile_main(const draw::View &views, Tile &srt, const uint3 global_id)
void foreach(const LightRenderData &srt, CallbackT &cb, ResourceT &res)
template void light::foreach_visible< culling::WithCullCtx, LightRenderData >(const LightRenderData &, float2, float, culling::WithCullCtx &, LightRenderData &)
int culling_z_to_zbin(float scale, float bias, float z)
void foreach_visible(const LightRenderData &srt, float2 pixel, float linear_view_z, CallbackT &cb, ResourceT &res)
template void light::foreach< culling::NoCullCtx, LightRenderData >(const LightRenderData &, culling::NoCullCtx &, LightRenderData &)
KERNEL_FEATURE_LIGHT_PASSES KERNEL_FEATURE_PATH_GUIDING float
#define min(a, b)
Definition sort.cc:38
static LightVector get(LightData light, const bool is_directional, float3 P)
float3 center
float radius
bool is_perspective() const
float3 point_world_to_view(float3 P) const
float3 forward() const
float depth_screen_to_view(float ss_depth) const
float3 point_screen_to_world(float3 ssP) const
float3 position() const
static CullingTile from_corners(bool is_persp, float3 corners[8])
bool intersect(const ViewMatrices view, Sphere sphere)
void eval_local(LightRenderData &, uint l_idx, LightData)
void eval_directional(LightRenderData &, uint, LightData)
const LightCullingData & light_cull_buf
float zdists_cache[CULLING_SORT_GROUP_SIZE]
const LightCullingData & light_cull_buf
CullingTile tile_culling_get(const ViewMatrices view, uint2 tile_co)
float2 tile_to_ndc(float2 tile_co, float2 offset)
void eval_local(LightRenderData &, uint l_idx, LightData light)
void eval_directional(LightRenderData &, uint, LightData)
float y
Definition sky_math.h:136
float x
Definition sky_math.h:136
float w
Definition sky_math.h:225
uint y
Definition types_uint2.h:13