three_rs/objects/clipping_group.rs
1//! Port of `three.js/src/objects/ClippingGroup.js`.
2
3use crate::core::object_ref::ObjectRef;
4use crate::core::Object3D;
5use crate::math::Plane;
6use crate::objects::Payload;
7
8/// `ClippingGroup` — a `Group` whose clipping planes clip every descendant,
9/// which is how `WebGPURenderer` encodes clipping in the scene graph
10/// (`Material.clippingPlanes` and `renderer.clippingPlanes` are WebGL-only).
11///
12/// The renderer's walk keeps a clipping context per group it enters
13/// (`ClippingContext.getGroupContext()`): a nested group's planes are added to
14/// its parent's, as an intersection when `clip_intersection` is set and as a
15/// union otherwise. The planes are world-space and read every frame, so moving
16/// one needs nothing; changing how many there are rebuilds the programs below
17/// the group, as a new cache key does in three.js.
18///
19/// The node is an `Object3D` with `type = 'ClippingGroup'` and `isGroup =
20/// true`; this state is its [`Payload::ClippingGroup`].
21#[derive(Clone, Debug)]
22pub struct ClippingGroup {
23 /// `ClippingGroup.clippingPlanes`, world-space.
24 pub clipping_planes: Vec<Plane>,
25 /// `ClippingGroup.enabled` — with it off the group clips nothing and its
26 /// descendants keep the context they would have had without it.
27 pub enabled: bool,
28 /// `ClippingGroup.clipIntersection` — clip only what is behind *all* of
29 /// the planes, rather than what is behind any one of them.
30 pub clip_intersection: bool,
31 /// `ClippingGroup.clipShadows` — whether the planes also clip the
32 /// descendants' shadow-map draws.
33 pub clip_shadows: bool,
34}
35
36impl Default for ClippingGroup {
37 fn default() -> Self {
38 Self {
39 clipping_planes: Vec::new(),
40 enabled: true,
41 clip_intersection: false,
42 clip_shadows: false,
43 }
44 }
45}
46
47impl ClippingGroup {
48 /// `new ClippingGroup()`, as a scene-graph [`ObjectRef`], with no planes.
49 #[allow(clippy::new_ret_no_self)] // `new` mirrors three.js's constructor and returns a scene-graph `ObjectRef`, not `Self`; public API, not changing.
50 pub fn new() -> ObjectRef {
51 Self::of(Self::default())
52 }
53
54 /// A `ClippingGroup` node holding `group`.
55 pub fn of(group: Self) -> ObjectRef {
56 let mut object = Object3D {
57 object_type: "ClippingGroup",
58 is_group: true,
59 ..Default::default()
60 };
61 object.payload = Payload::ClippingGroup(group);
62 object.into_node()
63 }
64}