From b46609d251ba2a174f1a386b95eb84ee49cbfcfa Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Fri, 6 Oct 2023 16:54:36 -0700 Subject: [PATCH] Add documentation of ClipBic Refer to Arxiv paper and mention bicyclic semigroups. --- crates/encoding/src/clip.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/crates/encoding/src/clip.rs b/crates/encoding/src/clip.rs index 025b86bc..1a68fbab 100644 --- a/crates/encoding/src/clip.rs +++ b/crates/encoding/src/clip.rs @@ -4,10 +4,18 @@ use bytemuck::{Pod, Zeroable}; /// Clip stack element. +/// +/// This is the bicyclic semigroup, a monoid useful for representing +/// stack depth. There is considerably more detail in the draft paper +/// [Fast GPU bounding boxes on tree-structured scenes]. +/// +/// [Fast GPU bounding boxes on tree-structured scenes]: https://arxiv.org/abs/2205.11659 #[derive(Copy, Clone, Pod, Zeroable, Debug, Default)] #[repr(C)] pub struct ClipBic { + /// When interpreted as a stack operation, the number of pop operations. pub a: u32, + /// When interpreted as a stack operation, the number of push operations. pub b: u32, } @@ -47,6 +55,12 @@ impl ClipBic { ClipBic { a, b } } + /// The bicyclic semigroup operation. + /// + /// This operation is associative. When interpreted as a stack + /// operation, it represents doing the pops of `self`, the pushes of + /// `self`, the pops of `other`, and the pushes of `other`. The middle + /// two can cancel each other out. pub fn combine(self, other: ClipBic) -> Self { let m = self.b.min(other.a); ClipBic::new(self.a + other.a - m, self.b + other.b - m)