Skip to main content

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}