Blender V5.3
draw_gsplat_lib.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
36
37#pragma once
38
39#include "draw_defines.hh"
40#include "draw_shader_shared.hh"
41
42#include "gpu_shader_compat.hh"
50
51namespace draw::gsplat {
52
53namespace detail {
54
55/* TODO(not_mark): Move to a `gpu_shader_*` header? */
56template<typename T> void swap(T &a, T &b)
57{
58 T c = a;
59 a = b;
60 b = c;
61}
62template void swap<float>(float &, float &);
63template void swap<float2>(float2 &, float2 &);
64
65/* TODO(not_mark): use or update `eevee_octahedron_lib` instead? */
68{
69 N /= reduce_add(abs(N));
70 N.xy = N.z >= 0.0f ? N.xy :
71 (1.0f - abs(N.yx)) *
72 mix(float2(-1.0f), float2(1.0f), greaterThanEqual(N.xy, float2(0)));
73 N.xy = N.xy * 0.5f + 0.5f;
74 return N.xy;
75}
76
77/* TODO(not_mark): use or update `eevee_octahedron_lib` instead? */
80{
81 p = p * 2.0f - 1.0f;
82 float3 N = float3(p.xy, 1.0f - reduce_add(abs(p.xy)));
83 float t = clamp(-N.z, 0.0f, 1.0f);
84 N.xy += mix(float2(-t), float2(t), greaterThanEqual(N.xy, float2(0.0f)));
85 return normalize(N);
86}
87
94{
95 float d = dot(v, v);
96 float t = inversesqrt(d + 1.0e-8f);
97 float a = M_PI_2 * t * d;
98 float s = sin(a);
99 float c = cos(a);
100 float k = s * t;
101 return float4(k * v, c);
102}
103
110{
111 uint3 pu;
112 pu.x = /* 22b */ pack.x & 0x3FFFFFu;
113 pu.y = /* 10b */ ((pack.x >> 22) & 0x0003FFu) |
114 /* 12b */ ((pack.y & 0x000FFFu) << 10);
115 pu.z = /* 20b */ ((pack.y >> 12) & 0x0FFFFFu) |
116 /* 02b */ ((pack.z & 0x000003u) << 20);
117 float3 p = float3(pu) / float((1 << 22) - 1u);
118 return data_range.scale_from_unit(p);
119}
120
127{
128 uint3 ru;
129 ru.x = /* 9b */ (pack.z >> 2) & 0x0001FFu;
130 ru.y = /* 9b */ (pack.z >> 11u) & 0x0001FFu;
131 ru.z = /* 9b */ (pack.z >> 20u) & 0x0001FFu;
132 float3 r = float3(ru) / 511.0f;
133 return Quaternion::from_float4(unpack_quaternion_3_to_4(r * 2.0f - 1.0f));
134}
135
142{
143 uint3 su;
144 su.x = /* 3b */ ((pack.z >> 29) & 0x000007u) |
145 /* 6b */ ((pack.w & 0x00003Fu) << 3);
146 su.y = /* 9b */ (pack.w >> 6) & 0x0001FFu;
147 su.z = /* 9b */ (pack.w >> 15) & 0x0001FFu;
148 if (all(equal(su, uint3(0u)))) {
149 /* Value 0 is reserved for zero scale, and not the quantized minimum. */
150 return float3(0.0f);
151 }
152 float3 s = (float3(su) - 1.0f) / 510.0f;
153 return exp(data_range.scale_from_unit(s));
154}
155
162{
163 uint au = (pack.w >> 24) & 0x0000FFu;
164 float a = float(au) / 255.0f;
165 return a;
166}
167
173{
174 return uint3(t, t >> 8, t >> 16) & 0xFFu;
175}
177{
178 return uint3(t >> 8, t >> 16, t >> 24) & 0xFFu;
179}
180uint3 slice_tuple_xnyz(uint t1, uint t2)
181{
182 return uint3(t1 >> 24, t2, t2 >> 8) & 0xFFu;
183}
184uint3 slice_tuple_xynz(uint t1, uint t2)
185{
186 return uint3(t1 >> 16, t1 >> 24, t2) & 0xFFu;
187}
188
190uint get_shape_id(uint vert_id)
191{
192 return int(vert_id / uint(DRW_GSPLAT_STRIP_TILE_SIZE));
193}
194
196bool get_shape_winding_ccw(uint vert_id)
197{
198 return bool((vert_id / DRW_GSPLAT_STRIP_TILE_SIZE) % 2u);
199}
200
203{
204 /* Flip vertices 1,2 for ccw winding order by flipping their sign. */
205 const float winding_order_mult = get_shape_winding_ccw(vert_id) ? -1.0f : 1.0f;
206 switch (vert_id % DRW_GSPLAT_STRIP_TILE_SIZE) {
207 case 0:
208 return float2(-1.0, -1.0);
209 case 1:
210 return float2(1.0, -1.0) * winding_order_mult;
211 case 2:
212 return float2(-1.0, 1.0) * winding_order_mult;
213 case 3:
214 return float2(1.0, 1.0);
215 default:
216 return float2(NAN_FLT);
217 };
218}
219
220} // namespace detail
221
226struct AxisTuple {
229
231 {
232 /* Flip/swap so axis_0 lies in the 1st and axis_1 in the 2nd quadrant of a hemicircle. */
233 axis_0 = (axis_0.y < 0) ? -axis_0 : axis_0;
234 axis_1 = (axis_1.y < 0) ? -axis_1 : axis_1;
235 if (axis_0.x < 0.0f) {
237 }
238 return AxisTuple{.axis_0 = axis_0, .axis_1 = axis_1};
239 }
240
241 uint pack() const
242 {
243
244 float axis_0_len;
245 float2 axis_0_dir = normalize_and_get_length(axis_0, axis_0_len);
246 float axis_1_len = length(axis_1);
247 if (axis_0_len == 0.0f && axis_1_len == 0.0f) {
248 return 0u;
249 }
250
251 axis_0_len = clamp(axis_0_len, 0.0f, 1.0f);
252 axis_1_len = clamp(axis_1_len, 0.0f, 1.0f);
253
254 /* NOTE(not_mark): do not reduce packing size further; already causes jittering on zoom. */
255 uint data = /* 10 bits */ uint(clamp(axis_0_dir.x, 0.0f, 1.0f) * 1023.0f) |
256 /* 11 bits */ (uint(clamp(axis_0_len, 0.0f, 1.0f) * 2047.0f) << 10u) |
257 /* 11 bits */ (uint(clamp(axis_1_len, 0.0f, 1.0f) * 2047.0f) << 21u);
258 return data;
259 }
260
261 static AxisTuple unpack(uint data)
262 {
263 /* NOTE(not_mark): do not reduce packing size further; already causes jittering on zoom. */
264 float axis_0_dir = /* 10 bits */ float(data & 0x3FFu) / 1023.0f;
265 float axis_0_len = /* 11 bits */ float((data >> 10u) & 0x7FFu) / 2047.0f;
266 float axis_1_len = /* 11 bits */ float((data >> 21u) & 0x7FFu) / 2047.0f;
267
268 const float2 axis = normalize(float2(axis_0_dir, cos_from_sin(axis_0_dir)));
269
270 AxisTuple tuple;
271 tuple.axis_0 = axis * axis_0_len;
272 tuple.axis_1 = float2(-axis.y, axis.x) * axis_1_len;
273 return tuple;
274 }
275};
276
281{
284 return R * S;
285}
286
291{
292 float3x3 M = get_rot_scale_mat(rotation, scale);
293 return M * transpose(M);
294}
295
299struct Gaussian {
300 /* Index stored for further attribute loading. */
301 uint id;
302 /* Gaussian local centroid and covariance data. */
306 /* Gaussian opacity, applied in alpha resolve. */
307 float opacity;
308
310 static Gaussian unpack(uint gs_id, uint4 data, ScalingRange mean_range, ScalingRange scale_range)
311 {
312 Gaussian gs;
313 gs.id = gs_id;
314 gs.mean = detail::unpack_gaussian_mean(data, mean_range);
316 gs.scale = detail::unpack_gaussian_scale(data, scale_range);
318 return gs;
319 }
320};
321
329{
330 /* Compute viewport parameters. */
331 const float tan_fov_x = 1.0f / view.winmat[0][0];
332 const float tan_fov_y = 1.0f / view.winmat[1][1];
333 const float lim_x = 1.3f * tan_fov_x;
334 const float lim_y = 1.3f * tan_fov_y;
335 const float focal_x = 0.5f * view.winmat[0][0];
336 const float focal_y = 0.5f * view.winmat[1][1];
337 const float4x4 model_to_view = view.viewmat * object.model;
338
339 /* Parameter `t` in [ewas2002], effectively projected point. */
340 float3 vP = transform_point(model_to_view, gs.mean);
341 vP.x = clamp(vP.x / vP.z, -lim_x, lim_x) * vP.z;
342 vP.y = clamp(vP.y / vP.z, -lim_y, lim_y) * vP.z;
343
344 /* Eq. 29: construct Jacobian matrix. */
345 float3x3 J;
346 if (view.is_perspective()) {
347 J = float3x3(float3(focal_x / vP.z, 0.0f, -(focal_x * vP.x) / (vP.z * vP.z)),
348 float3(0.0f, focal_y / vP.z, -(focal_y * vP.y) / (vP.z * vP.z)),
349 float3(0.0f));
350 }
351 else {
352 /* For orthographic matrices, the Jacobian is slightly different. */
353 J = float3x3(float3(focal_x, 0.0f, 0.0f), float3(0.0f, focal_y, 0.0f), float3(0.0f));
354 }
355
356 /* Eq. 31: construct covariance matrix in screen space. */
357 float3x3 covmat_3d = get_covmat(gs.rotation, gs.scale);
358 float3x3 V = float3x3(float3(covmat_3d[0][0], covmat_3d[0][1], covmat_3d[0][2]),
359 float3(covmat_3d[0][1], covmat_3d[1][1], covmat_3d[1][2]),
360 float3(covmat_3d[0][2], covmat_3d[1][2], covmat_3d[2][2]));
361 float3x3 W = to_float3x3(model_to_view); /* Extract rotational part of matrix. */
362 float3x3 T = transpose(W) * J;
363 float3x3 covmat_2d = transpose(T) * V * T;
364
365 /* Low-pass filter applied in [3dgs2023] as 0.3, though I believe this is 1.0 in [ewas2002]. */
366 /* NOTE(not_mark): disabled for now, better matches Cycles results. */
367 // covmat_2d[0][0] += 0.3f;
368 // covmat_2d[1][1] += 0.3f;
369
370 /* The 2d covariance matrix is of form [[x, y], [y, z]], and returned as [x, y, z]. */
371 float3 covmat_2d_v = float3(covmat_2d[0][0], covmat_2d[0][1], covmat_2d[1][1]);
372 return covmat_2d_v;
373}
374
380{
381 constexpr float std_dev = 3.0f;
382
383 const float mid = 0.5f * (covmat_2d_v.x + covmat_2d_v.z);
384 const float radius = length(float2((covmat_2d_v.x - covmat_2d_v.z) * 0.5f, covmat_2d_v.y));
385
386 const float lambda_1 = mid + radius;
387 const float lambda_2 = max(mid - radius, 1e-8f);
388
389 const float2 diag = normalize(float2(covmat_2d_v.y, lambda_1 - covmat_2d_v.x));
390 const float2 axis_0 = min(std_dev * sqrt(lambda_1), 1.0) * diag;
391 const float2 axis_1 = min(std_dev * sqrt(lambda_2), 1.0) * float2(diag.y, -diag.x);
392 return AxisTuple::from(axis_0, axis_1);
393}
394
401{
402#if 0
403 /* Reference implementation. */
405 if ((scale.x <= scale.y) && (scale.x <= scale.z)) {
406 return R * float3(1.0f, 0.0f, 0.0f);
407 }
408 if ((scale.y < scale.x) && (scale.y <= scale.z)) {
409 return R * float3(0.0f, 1.0f, 0.0f);
410 }
411 return R * float3(0.0f, 0.0f, 1.0f);
412#else
413 const float norm = 1.0f / (rotation.x * rotation.x + rotation.y * rotation.y +
414 rotation.z * rotation.z + rotation.w * rotation.w);
415
416 const float a = rotation.w;
417 const float b = rotation.x;
418 const float c = rotation.y;
419 const float d = rotation.z;
420
421 if ((scale.x <= scale.y) && (scale.x <= scale.z)) {
422 return float3(a * a + b * b - c * c - d * d, 2.0f * (a * d + b * c), 2.0f * (b * d - a * c)) *
423 norm;
424 }
425 if ((scale.y < scale.x) && (scale.y <= scale.z)) {
426 return float3(2.0f * (b * c - a * d), a * a - b * b + c * c - d * d, 2.0f * (a * b + c * d)) *
427 norm;
428 }
429 return float3(2.0f * (a * c + b * d), 2.0f * (c * d - a * b), a * a - b * b - c * c + d * d) *
430 norm;
431#endif
432}
433
438 /* Index stored for further attribute loading. */
439 uint id;
440 /* Gaussian local centroid. */
442 /* Billboard vertex. */
444 /* Vertex output data. */
448
450 {
451 return SplatShape{.id = ~0u};
452 }
453
454 bool is_culled() const
455 {
456 return id == (~0u);
457 }
458};
459
464 /* Index stored for further attribute loading. */
465 uint id;
466 /* Gaussian local centroid. */
468 /* Vertex output data. */
471
473 {
474 return PointShape{.id = ~0u};
475 }
476
477 bool is_culled() const
478 {
479 return id == (~0u);
480 }
481};
482
489
493
494 private:
495 Gaussian get_gaussian(uint gs_id) const
496 {
497 const uint4 data = texelFetch(shape_data_tx, int(gs_id));
499 }
500
501 SplatShape get_splat_implementation(uint vert_id, ObjectMatrices object, ViewMatrices view) const
502 {
503 float2 shape_offset = detail::get_shape_offset(vert_id);
504 if (any(isnan(shape_offset))) {
505 return SplatShape::culled();
506 }
507
508 SplatShape shape = {.id = detail::get_shape_id(vert_id), .shape_offset = 2.0f * shape_offset};
509 AxisTuple axes;
510
511 /* TODO(not_mark): Load of precomputed data is disabled until we can address
512 * incompatibility of a compute prepass with instancing and other factors. For now,
513 * resolve splat billboard data on the fly. */
514 if constexpr (false) {
515 const uint2 prepass_data = texelFetch(ellipses_comp_tx, int(shape.id)).xy;
516 if (prepass_data.x == 0u) {
517 return SplatShape::culled();
518 }
519
520 /* Unpack ellipse axes, centroid, normal. */
521 axes = AxisTuple::unpack(prepass_data.x);
522 const uint4 shape_data = texelFetch(shape_data_tx, int(shape.id));
523 shape.mean = detail::unpack_gaussian_mean(shape_data, infos.splat_mean_range);
524 shape.wP = object.point_object_to_world(shape.mean);
525 shape.wN = detail::unpack_normal_octahedral(unpackSnorm2x16(prepass_data.y));
526 }
527 else {
528 const Gaussian gs = get_gaussian(shape.id);
529
530 /* Project Gaussian to screen-space, recovering 2D axes for a splatted ellipse. */
531 float3 covmat_2d_v = project_gaussian(object, view, gs);
532 axes = covmat_to_axes(covmat_2d_v);
533
534 /* Compute world normal. Normal is oriented towards view, never back-facing. */
535 float3 wP = object.point_object_to_world(gs.mean);
536 float3 lN = normalize(get_planar_normal(gs.rotation, gs.scale));
537 float3 wN = object.normal_object_to_world(lN);
538 if (dot(wN, view.world_incident_vector(wP)) < 0.0f) {
539 wN = -wN;
540 }
541
542 shape.mean = gs.mean;
543 shape.wP = wP;
544 shape.wN = wN;
545 }
546
547 /* Screen-space offset determined by ellipse axis tuple. */
548 float2 ss_delta = shape.shape_offset.x * axes.axis_0 + shape.shape_offset.y * axes.axis_1;
549
550 /* Add screen-space offset to homogeneous position. */
551 shape.hP = view.point_world_to_homogenous(shape.wP);
552 shape.hP.xy += ss_delta * shape.hP.w;
553 shape.wP = view.point_homogeneous_to_world(shape.hP);
554
555 return shape;
556 }
557
558 public:
564 float3 get_radiance(uint gs_id) const
565 {
566 return texelFetch(radiance_comp_tx, int(gs_id)).rgb;
567 }
568
575 float get_opacity(uint gs_id) const
576 {
577 const uint4 shape_data = texelFetch(shape_data_tx, int(gs_id));
578 return detail::unpack_gaussian_opacity(shape_data);
579 }
580
584 PointShape get_point(uint vert_id, ObjectMatrices object, ViewMatrices view) const
585 {
586 PointShape gs;
587 gs.id = vert_id;
588
589 const uint4 shape_data = texelFetch(shape_data_tx, int(vert_id));
591 gs.wP = object.point_object_to_world(gs.mean);
592 gs.hP = view.point_world_to_homogenous(gs.wP);
593 return gs;
594 }
595
599 SplatShape get_splat(uint vert_id, ObjectMatrices object, ViewMatrices view) const
600 {
601 return get_splat_implementation(vert_id, object, view);
602 }
603};
604
608float evaluate_gaussian(float2 x_min_mu, float opacity)
609{
610 return saturate(exp(-dot(x_min_mu, x_min_mu)) * opacity);
611}
612
613} // namespace draw::gsplat
#define NAN_FLT
#define M_PI_2
btScalar max
SIMD_FORCE_INLINE btScalar norm() const
Return the norm (length) of the vector.
Definition btVector3.h:263
#define DRW_GSPLAT_SHAPE_DATA_TEX_SLOT
#define DRW_GSPLAT_RADIANCE_COMP_TEX_SLOT
#define DRW_GSPLAT_STRIP_TILE_SIZE
#define DRW_GSPLAT_ELLIPSE_COMP_TEX_SLOT
#define DRW_OBJ_DATA_INFO_UBO_SLOT
#define uniform(slot)
#define sampler(slot)
#define isnan
VecBase< bool, D > greaterThanEqual(VecOp< T, D >, VecOp< T, D >) RET
#define sin
bool any(VecOp< bool, D >) RET
#define exp
#define cos
VecBase< float, D > normalize(VecOp< float, D >) RET
float dot(VecOp< float, D >, VecOp< float, D >) RET
constexpr T inversesqrt(T) RET
#define abs
float2 unpackSnorm2x16(uint) RET
bool all(VecOp< bool, D >) RET
#define sqrt
MatBase< R, C > transpose(MatBase< C, R >) RET
VecBase< bool, D > equal(VecOp< T, D >, VecOp< T, D >) RET
constexpr T clamp(T, U, U) RET
float length(VecOp< float, D >) RET
SamplerBase< uint, 1 > usamplerBuffer
TEX_TEMPLATE DataVec texelFetch(T, IntCoord, int) RET
SamplerBase< float, 1 > samplerBuffer
float cos_from_sin(float s)
float3x3 scale(float3x3 mat, float2 scale)
float2x2 from_scale(float2 scale)
float3 transform_point(float3x3 mat, float3 point)
float3x3 quaternion_to_float3x3(Quaternion q)
VecT normalize_and_get_length(VecT vector, float &out_length)
float reduce_add(float2 a)
#define M
#define N
#define T
#define R
VecBase< uint32_t, 4 > uint4
MatBase< float, 4, 4 > float4x4
VecBase< float, 2 > float2
VecBase< float, 3 > float3
uint3 slice_tuple_xynz(uint t1, uint t2)
float unpack_gaussian_opacity(uint4 pack)
float3 unpack_normal_octahedral(float2 p)
Quaternion unpack_gaussian_rotation(uint4 pack)
uint get_shape_id(uint vert_id)
bool get_shape_winding_ccw(uint vert_id)
uint3 slice_tuple_xnyz(uint t1, uint t2)
float3 unpack_gaussian_mean(uint4 pack, ScalingRange data_range)
float4 unpack_quaternion_3_to_4(float3 v)
float2 get_shape_offset(uint vert_id)
float3 unpack_gaussian_scale(uint4 pack, ScalingRange data_range)
float2 pack_normal_octahedral(float3 N)
float3x3 get_rot_scale_mat(Quaternion rotation, float3 scale)
float3 project_gaussian(ObjectMatrices object, ViewMatrices view, Gaussian gs)
float evaluate_gaussian(float2 x_min_mu, float opacity)
AxisTuple covmat_to_axes(float3 covmat_2d_v)
float3 get_planar_normal(Quaternion rotation, float3 scale)
float3x3 get_covmat(Quaternion rotation, float3 scale)
double Gaussian(double x, double sigma)
Definition convolve.h:32
#define mix
KERNEL_FEATURE_LIGHT_PASSES KERNEL_FEATURE_PATH_GUIDING float
#define saturate(a)
Definition smaa.cc:319
#define min(a, b)
Definition sort.cc:38
struct ScalingRange splat_mean_range
struct ScalingRange splat_scale_range
static Quaternion from_float4(float4 v)
float3 scale_from_unit(float3 value) const
bool is_perspective() const
float4 point_world_to_homogenous(float3 P) const
float3 point_homogeneous_to_world(float4 hP) const
float3 world_incident_vector(float3 P) const
static AxisTuple unpack(uint data)
static AxisTuple from(float2 axis_0, float2 axis_1)
static Gaussian unpack(uint gs_id, uint4 data, ScalingRange mean_range, ScalingRange scale_range)
const usamplerBuffer ellipses_comp_tx
float3 get_radiance(uint gs_id) const
float get_opacity(uint gs_id) const
PointShape get_point(uint vert_id, ObjectMatrices object, ViewMatrices view) const
SplatShape get_splat(uint vert_id, ObjectMatrices object, ViewMatrices view) const
float x
float y
float z
Definition sky_math.h:136
float y
Definition sky_math.h:136
float x
Definition sky_math.h:136
uint x
Definition types_uint2.h:13
uint y
Definition types_uint2.h:13
uint y
Definition types_uint3.h:13
uint z
Definition types_uint3.h:13
uint x
Definition types_uint3.h:13
CCL_NAMESPACE_BEGIN struct Window V