alice-sdf 5.1.0

//! OpCode definitions for compiled SDF
//!
//! Author: Moroya Sakamoto

/// Operation codes for the SDF virtual machine
///
/// Each opcode represents either a primitive (pushes to stack),
/// an operation (pops operands, pushes result), or a transform
/// (modifies the evaluation point).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u8)]
// 4.0.0: `SdfNode` と同じ理由で宣言する (opcode の追加を minor で出せるように)。
#[non_exhaustive]
pub enum OpCode {
    // === Primitives (push distance to stack) ===
    /// Sphere: `params[0]` = radius
    Sphere = 0,
    /// Box3d: `params[0..3]` = half_extents (x, y, z)
    Box3d = 1,
    /// Cylinder: `params[0]` = radius, `params[1]` = half_height
    Cylinder = 2,
    /// Torus: `params[0]` = major_radius, `params[1]` = minor_radius
    Torus = 3,
    /// Plane: `params[0..3]` = normal (x, y, z), `params[3]` = distance
    Plane = 4,
    /// Capsule: `params[0..3]` = point_a, `params[3..6]` = point_b (radius in params via separate field)
    Capsule = 5,
    /// Cone: `params[0]` = radius, `params[1]` = half_height
    Cone = 6,
    /// Ellipsoid: `params[0..3]` = radii (x, y, z)
    Ellipsoid = 7,
    /// RoundedCone: `params[0]` = r1, `params[1]` = r2, `params[2]` = half_height
    RoundedCone = 8,
    /// Pyramid: `params[0]` = half_height
    Pyramid = 9,
    /// Octahedron: `params[0]` = size
    Octahedron = 10,
    /// HexPrism: `params[0]` = hex_radius, `params[1]` = half_height
    HexPrism = 11,
    /// Link: `params[0]` = half_length, `params[1]` = r1, `params[2]` = r2
    Link = 12,

    // === Extended Primitives (64-101) ===
    /// RoundedBox: `params[0..3]` = half_extents, `params[3]` = round_radius
    RoundedBox = 64,
    /// CappedCone: `params[0]` = half_height, `params[1]` = r1, `params[2]` = r2
    CappedCone = 65,
    /// CappedTorus: `params[0]` = major_radius, `params[1]` = minor_radius, `params[2]` = cap_angle
    CappedTorus = 66,
    /// RoundedCylinder: `params[0]` = radius, `params[1]` = round_radius, `params[2]` = half_height
    RoundedCylinder = 67,
    /// TriangularPrism: `params[0]` = width, `params[1]` = half_depth
    TriangularPrism = 68,
    /// CutSphere: `params[0]` = radius, `params[1]` = cut_height
    CutSphere = 69,
    /// CutHollowSphere: `params[0]` = radius, `params[1]` = cut_height, `params[2]` = thickness
    CutHollowSphere = 70,
    /// DeathStar: `params[0]` = ra, `params[1]` = rb, `params[2]` = d
    DeathStar = 71,
    /// SolidAngle: `params[0]` = angle, `params[1]` = radius
    SolidAngle = 72,
    /// Rhombus: `params[0]` = la, `params[1]` = lb, `params[2]` = half_height, `params[3]` = round_radius
    Rhombus = 73,
    /// Horseshoe: `params[0]` = angle, `params[1]` = radius, `params[2]` = half_length, `params[3]` = width, `params[4]` = thickness
    Horseshoe = 74,
    /// Vesica: `params[0]` = radius, `params[1]` = half_dist
    Vesica = 75,
    /// InfiniteCylinder: `params[0]` = radius
    InfiniteCylinder = 76,
    /// InfiniteCone: `params[0]` = angle
    InfiniteCone = 77,
    /// Gyroid: `params[0]` = scale, `params[1]` = thickness
    Gyroid = 78,
    /// Heart: `params[0]` = size
    Heart = 79,
    /// Tube: `params[0]` = outer_radius, `params[1]` = thickness, `params[2]` = half_height
    Tube = 80,
    /// Barrel: `params[0]` = radius, `params[1]` = half_height, `params[2]` = bulge
    Barrel = 81,
    /// Diamond: `params[0]` = radius, `params[1]` = half_height
    Diamond = 82,
    /// ChamferedCube: `params[0..3]` = half_extents, `params[3]` = chamfer
    ChamferedCube = 83,
    /// SchwarzP: `params[0]` = scale, `params[1]` = thickness
    SchwarzP = 84,
    /// Superellipsoid: `params[0..3]` = half_extents, `params[3]` = e1, `params[4]` = e2
    Superellipsoid = 85,
    /// RoundedX: `params[0]` = width, `params[1]` = round_radius, `params[2]` = half_height
    RoundedX = 86,
    /// Pie: `params[0]` = angle, `params[1]` = radius, `params[2]` = half_height
    Pie = 87,
    /// Trapezoid: `params[0]` = r1, `params[1]` = r2, `params[2]` = trap_height, `params[3]` = half_depth
    Trapezoid = 88,
    /// Parallelogram: `params[0]` = width, `params[1]` = para_height, `params[2]` = skew, `params[3]` = half_depth
    Parallelogram = 89,
    /// Tunnel: `params[0]` = width, `params[1]` = height_2d, `params[2]` = half_depth
    Tunnel = 90,
    /// UnevenCapsule: `params[0]` = r1, `params[1]` = r2, `params[2]` = cap_height, `params[3]` = half_depth
    UnevenCapsule = 91,
    /// Egg: `params[0]` = ra, `params[1]` = rb
    Egg = 92,
    /// ArcShape: `params[0]` = aperture, `params[1]` = radius, `params[2]` = thickness, `params[3]` = half_height
    ArcShape = 93,
    /// Moon: `params[0]` = d, `params[1]` = ra, `params[2]` = rb, `params[3]` = half_height
    Moon = 94,
    /// CrossShape: `params[0]` = length, `params[1]` = thickness, `params[2]` = round_radius, `params[3]` = half_height
    CrossShape = 95,
    /// BlobbyCross: `params[0]` = size, `params[1]` = half_height
    BlobbyCross = 96,
    /// ParabolaSegment: `params[0]` = width, `params[1]` = para_height, `params[2]` = half_depth
    ParabolaSegment = 97,
    /// RegularPolygon: `params[0]` = radius, `params[1]` = n_sides, `params[2]` = half_height
    RegularPolygon = 98,
    /// StarPolygon: `params[0]` = radius, `params[1]` = n_points, `params[2]` = m, `params[3]` = half_height
    StarPolygon = 99,
    /// Stairs: `params[0]` = step_width, `params[1]` = step_height, `params[2]` = n_steps, `params[3]` = half_depth
    Stairs = 100,
    /// Helix: `params[0]` = major_r, `params[1]` = minor_r, `params[2]` = pitch, `params[3]` = half_height
    Helix = 101,
    /// Tetrahedron: `params[0]` = size
    Tetrahedron = 102,
    /// Dodecahedron: `params[0]` = radius
    Dodecahedron = 103,
    /// Icosahedron: `params[0]` = radius
    Icosahedron = 104,
    /// TruncatedOctahedron: `params[0]` = radius
    TruncatedOctahedron = 105,
    /// TruncatedIcosahedron: `params[0]` = radius
    TruncatedIcosahedron = 106,
    /// BoxFrame: `params[0..3]` = half_extents, `params[3]` = edge
    BoxFrame = 107,
    /// DiamondSurface: `params[0]` = scale, `params[1]` = thickness
    DiamondSurface = 108,
    /// Neovius: `params[0]` = scale, `params[1]` = thickness
    Neovius = 109,
    /// Lidinoid: `params[0]` = scale, `params[1]` = thickness
    Lidinoid = 110,
    /// IWP: `params[0]` = scale, `params[1]` = thickness
    IWP = 111,
    /// FRD: `params[0]` = scale, `params[1]` = thickness
    FRD = 112,
    /// FischerKochS: `params[0]` = scale, `params[1]` = thickness
    FischerKochS = 113,
    /// PMY: `params[0]` = scale, `params[1]` = thickness
    PMY = 114,
    /// Circle2D: `params[0]` = radius, `params[1]` = half_height
    Circle2D = 115,
    /// Rect2D: `params[0..2]` = half_extents, `params[2]` = half_height
    Rect2D = 116,
    /// Segment2D: `params[0..4]` = a,b, `params[4]` = thickness, `params[5]` = half_height
    Segment2D = 117,
    /// Polygon2D: special handling
    Polygon2D = 118,
    /// RoundedRect2D: `params[0..2]` = half_extents, `params[2]` = round_radius, `params[3]` = half_height
    RoundedRect2D = 119,
    /// Annular2D: `params[0]` = outer_radius, `params[1]` = thickness, `params[2]` = half_height
    Annular2D = 120,
    /// MetricBall: `params[0]` = radius, `params[1..4]` = weights (l1, l2, linf)
    MetricBall = 121,

    // === Binary Operations (pop 2, push 1) ===
    /// Union: min(a, b)
    Union = 16,
    /// Intersection: max(a, b)
    Intersection = 17,
    /// Subtraction: max(a, -b)
    Subtraction = 18,
    /// SmoothUnion: `params[0]` = k
    SmoothUnion = 19,
    /// SmoothIntersection: `params[0]` = k
    SmoothIntersection = 20,
    /// SmoothSubtraction: `params[0]` = k
    SmoothSubtraction = 21,
    /// ChamferUnion: `params[0]` = r (chamfer radius)
    ChamferUnion = 22,
    /// ChamferIntersection: `params[0]` = r
    ChamferIntersection = 23,
    /// ChamferSubtraction: `params[0]` = r
    ChamferSubtraction = 24,
    /// StairsUnion: `params[0]` = r, `params[1]` = n
    StairsUnion = 25,
    /// StairsIntersection: `params[0]` = r, `params[1]` = n
    StairsIntersection = 26,
    /// StairsSubtraction: `params[0]` = r, `params[1]` = n
    StairsSubtraction = 27,

    // === Extended Binary Operations (128-136) ===
    /// XOR: symmetric difference
    XOR = 128,
    /// Morph: `params[0]` = t (blend factor)
    Morph = 129,
    /// ColumnsUnion: `params[0]` = r, `params[1]` = n
    ColumnsUnion = 130,
    /// ColumnsIntersection: `params[0]` = r, `params[1]` = n
    ColumnsIntersection = 131,
    /// ColumnsSubtraction: `params[0]` = r, `params[1]` = n
    ColumnsSubtraction = 132,
    /// Pipe: `params[0]` = r
    Pipe = 133,
    /// Engrave: `params[0]` = r
    Engrave = 134,
    /// Groove: `params[0]` = ra, `params[1]` = rb
    Groove = 135,
    /// Tongue: `params[0]` = ra, `params[1]` = rb
    Tongue = 136,
    /// ExpSmoothUnion: `params[0]` = k
    ExpSmoothUnion = 137,
    /// ExpSmoothIntersection: `params[0]` = k
    ExpSmoothIntersection = 138,
    /// ExpSmoothSubtraction: `params[0]` = k
    ExpSmoothSubtraction = 139,

    // === Transforms (modify point, then evaluate child) ===
    /// Translate: `params[0..3]` = offset (x, y, z)
    Translate = 32,
    /// Rotate: `params[0..4]` = quaternion (x, y, z, w)
    Rotate = 33,
    /// Scale: `params[0]` = uniform scale factor
    Scale = 34,
    /// ScaleNonUniform: `params[0..3]` = scale factors (x, y, z)
    ScaleNonUniform = 35,

    // === Extended Transforms (200-202) ===
    /// ProjectiveTransform: requires auxiliary data (inv_matrix, lipschitz_bound)
    ProjectiveTransform = 200,
    /// LatticeDeform: requires auxiliary data (control_points, lattice params)
    LatticeDeform = 201,
    /// SdfSkinning: requires auxiliary data (bones)
    SdfSkinning = 202,

    // === Modifiers ===
    /// Twist: `params[0]` = strength
    Twist = 48,
    /// Bend: `params[0]` = curvature
    Bend = 49,
    /// RepeatInfinite: `params[0..3]` = spacing (x, y, z)
    RepeatInfinite = 50,
    /// RepeatFinite: `params[0..3]` = count, `params[3..6]` = spacing
    RepeatFinite = 51,
    /// Round: `params[0]` = radius (post-process: d - radius)
    Round = 52,
    /// Onion: `params[0]` = thickness (post-process: |d| - thickness)
    Onion = 53,
    /// Elongate: `params[0..3]` = amount (x, y, z)
    Elongate = 54,
    /// Noise: `params[0]` = amplitude, `params[1]` = frequency, `params[2]` = seed
    /// Post-processes distance: d += noise(p * frequency) * amplitude
    Noise = 55,
    /// Mirror: `params[0..3]` = axes (non-zero = mirror that axis)
    Mirror = 56,
    /// Revolution: `params[0]` = offset from Y-axis
    Revolution = 57,
    /// Extrude: `params[0]` = half_height
    Extrude = 58,
    /// Taper: `params[0]` = factor
    Taper = 59,
    /// Displacement: `params[0]` = strength (post-process)
    Displacement = 60,
    /// PolarRepeat: `params[0]` = count (as f32)
    PolarRepeat = 61,
    /// SweepBezier: `params[0..6]` = p0.x, p0.z, p1.x, p1.z, p2.x, p2.z
    SweepBezier = 62,
    /// OctantMirror: abs + sort (x >= y >= z)
    OctantMirror = 63,
    /// MetricBlend: `params[0..3]` = centre, `params[3]` = radius, `params[4]` = skin
    MetricBlend = 140,
    /// Shear: `params[0..3]` = shear factors (xy, xz, yz)
    Shear = 144,
    /// Animated: `params[0]` = speed, `params[1]` = amplitude
    Animated = 145,

    // === Extended Modifiers (160-163) ===
    /// IcosahedralSymmetry: no params (maps to fundamental domain)
    IcosahedralSymmetry = 160,
    /// IFS: requires auxiliary data (transforms, iterations)
    IFS = 161,
    /// HeightmapDisplacement: requires auxiliary data (heightmap, dimensions)
    HeightmapDisplacement = 162,
    /// SurfaceRoughness: `params[0]` = frequency, `params[1]` = amplitude, `params[2]` = octaves
    SurfaceRoughness = 163,

    // === Control ===
    /// Pop transform from coordinate stack
    PopTransform = 240,
    /// End of program
    End = 255,
}

impl OpCode {
    /// Returns true if this opcode is a primitive (pushes to value stack)
    #[inline]
    pub const fn is_primitive(self) -> bool {
        matches!(self.kind(), OpKind::Primitive)
    }

    /// Returns true if this opcode is a binary operation
    #[inline]
    pub const fn is_binary_op(self) -> bool {
        matches!(self.kind(), OpKind::Binary)
    }

    /// Returns true if this opcode is a transform
    #[inline]
    pub const fn is_transform(self) -> bool {
        matches!(self.kind(), OpKind::Transform)
    }

    /// Returns true if this opcode is a modifier
    #[inline]
    pub const fn is_modifier(self) -> bool {
        matches!(self.kind(), OpKind::Modifier)
    }

    /// Returns true if this opcode modifies the evaluation point
    ///
    /// Exactly the frame-pushing opcodes for which the bytecode VM
    /// (`eval_core`) rewrites the point before the child runs: every
    /// transform, and the point-warping modifiers. `Animated` pushes a frame
    /// but leaves the point unchanged; the distance-only modifiers (`Round`,
    /// `Onion`, `Noise`, `Displacement`, `HeightmapDisplacement`,
    /// `SurfaceRoughness`) evaluate the child at the same point.
    #[inline]
    pub const fn modifies_point(self) -> bool {
        self.is_transform()
            || matches!(
                self,
                Self::Twist
                    | Self::Bend
                    | Self::RepeatInfinite
                    | Self::RepeatFinite
                    | Self::Elongate
                    | Self::Mirror
                    | Self::Revolution
                    | Self::Extrude
                    | Self::SweepBezier
                    | Self::Taper
                    | Self::PolarRepeat
                    | Self::OctantMirror
                    | Self::Shear
                    | Self::IcosahedralSymmetry
                    | Self::IFS
            )
    }

    /// Returns true if this opcode post-processes the distance value
    ///
    /// Exactly the opcodes whose frame the bytecode VM (`eval_core`) rewrites
    /// the child distance for when the matching `PopTransform` runs (scale
    /// and Lipschitz corrections, offsets, displacement terms).
    #[inline]
    pub const fn is_post_process(self) -> bool {
        matches!(
            self,
            Self::Scale
                | Self::ScaleNonUniform
                | Self::ProjectiveTransform
                | Self::LatticeDeform
                | Self::Round
                | Self::Onion
                | Self::Noise
                | Self::Extrude
                | Self::Taper
                | Self::Displacement
                | Self::IFS
                | Self::HeightmapDisplacement
                | Self::SurfaceRoughness
        )
    }
}

/// Stack-machine role of an opcode.
///
/// Exhaustive over every `OpCode` variant: adding a variant without
/// classifying it here is a compile error, so every evaluator / AABB walker
/// that dispatches on [`OpCode::kind`] stays in lockstep with the enum.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OpKind {
    /// Leaf: pushes one distance onto the value stack
    Primitive,
    /// Pops two distances, pushes one
    Binary,
    /// Prefix transform: pushes a coordinate frame, paired with `PopTransform`
    Transform,
    /// Prefix modifier: pushes a coordinate frame, paired with `PopTransform`
    Modifier,
    /// Pops a coordinate frame (and applies any post-processing)
    PopTransform,
    /// Terminates evaluation
    End,
}

impl OpCode {
    /// Classify this opcode (see [`OpKind`]). Exhaustive by construction.
    #[inline]
    pub const fn kind(self) -> OpKind {
        match self {
            Self::Sphere
            | Self::Box3d
            | Self::Cylinder
            | Self::Torus
            | Self::Plane
            | Self::Capsule
            | Self::Cone
            | Self::Ellipsoid
            | Self::RoundedCone
            | Self::Pyramid
            | Self::Octahedron
            | Self::HexPrism
            | Self::Link
            | Self::RoundedBox
            | Self::CappedCone
            | Self::CappedTorus
            | Self::RoundedCylinder
            | Self::TriangularPrism
            | Self::CutSphere
            | Self::CutHollowSphere
            | Self::DeathStar
            | Self::SolidAngle
            | Self::Rhombus
            | Self::Horseshoe
            | Self::Vesica
            | Self::InfiniteCylinder
            | Self::InfiniteCone
            | Self::Gyroid
            | Self::Heart
            | Self::Tube
            | Self::Barrel
            | Self::Diamond
            | Self::ChamferedCube
            | Self::SchwarzP
            | Self::Superellipsoid
            | Self::RoundedX
            | Self::Pie
            | Self::Trapezoid
            | Self::Parallelogram
            | Self::Tunnel
            | Self::UnevenCapsule
            | Self::Egg
            | Self::ArcShape
            | Self::Moon
            | Self::CrossShape
            | Self::BlobbyCross
            | Self::ParabolaSegment
            | Self::RegularPolygon
            | Self::StarPolygon
            | Self::Stairs
            | Self::Helix
            | Self::Tetrahedron
            | Self::Dodecahedron
            | Self::Icosahedron
            | Self::TruncatedOctahedron
            | Self::TruncatedIcosahedron
            | Self::BoxFrame
            | Self::DiamondSurface
            | Self::Neovius
            | Self::Lidinoid
            | Self::IWP
            | Self::FRD
            | Self::FischerKochS
            | Self::PMY
            | Self::Circle2D
            | Self::Rect2D
            | Self::Segment2D
            | Self::Polygon2D
            | Self::RoundedRect2D
            | Self::MetricBall
            | Self::Annular2D => OpKind::Primitive,
            Self::Union
            | Self::MetricBlend
            | Self::Intersection
            | Self::Subtraction
            | Self::SmoothUnion
            | Self::SmoothIntersection
            | Self::SmoothSubtraction
            | Self::ChamferUnion
            | Self::ChamferIntersection
            | Self::ChamferSubtraction
            | Self::StairsUnion
            | Self::StairsIntersection
            | Self::StairsSubtraction
            | Self::XOR
            | Self::Morph
            | Self::ColumnsUnion
            | Self::ColumnsIntersection
            | Self::ColumnsSubtraction
            | Self::Pipe
            | Self::Engrave
            | Self::Groove
            | Self::Tongue
            | Self::ExpSmoothUnion
            | Self::ExpSmoothIntersection
            | Self::ExpSmoothSubtraction => OpKind::Binary,
            Self::Translate
            | Self::Rotate
            | Self::Scale
            | Self::ScaleNonUniform
            | Self::ProjectiveTransform
            | Self::LatticeDeform
            | Self::SdfSkinning => OpKind::Transform,
            Self::Twist
            | Self::Bend
            | Self::RepeatInfinite
            | Self::RepeatFinite
            | Self::Round
            | Self::Onion
            | Self::Elongate
            | Self::Noise
            | Self::Mirror
            | Self::Revolution
            | Self::Extrude
            | Self::Taper
            | Self::Displacement
            | Self::PolarRepeat
            | Self::SweepBezier
            | Self::OctantMirror
            | Self::Shear
            | Self::Animated
            | Self::IcosahedralSymmetry
            | Self::IFS
            | Self::HeightmapDisplacement
            | Self::SurfaceRoughness => OpKind::Modifier,
            Self::PopTransform => OpKind::PopTransform,
            Self::End => OpKind::End,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_opcode_categories() {
        assert!(OpCode::Sphere.is_primitive());
        assert!(OpCode::Box3d.is_primitive());
        assert!(!OpCode::Union.is_primitive());

        assert!(OpCode::Union.is_binary_op());
        assert!(OpCode::SmoothUnion.is_binary_op());
        assert!(!OpCode::Sphere.is_binary_op());

        assert!(OpCode::Translate.is_transform());
        assert!(OpCode::Rotate.is_transform());
        assert!(!OpCode::Sphere.is_transform());

        assert!(OpCode::Twist.is_modifier());
        assert!(OpCode::Round.is_modifier());
        assert!(!OpCode::Union.is_modifier());
    }

    #[test]
    fn test_opcode_values() {
        // Ensure opcodes have expected values for serialization
        assert_eq!(OpCode::Sphere as u8, 0);
        assert_eq!(OpCode::Union as u8, 16);
        assert_eq!(OpCode::Translate as u8, 32);
        assert_eq!(OpCode::Twist as u8, 48);
        assert_eq!(OpCode::RoundedBox as u8, 64);
        assert_eq!(OpCode::Helix as u8, 101);
        assert_eq!(OpCode::End as u8, 255);
    }

    #[test]
    fn test_extended_primitives_are_primitives() {
        assert!(OpCode::RoundedBox.is_primitive());
        assert!(OpCode::Stairs.is_primitive());
        assert!(OpCode::Helix.is_primitive());
        assert!(OpCode::Heart.is_primitive());
        assert!(OpCode::Gyroid.is_primitive());
        assert!(!OpCode::RoundedBox.is_binary_op());
        assert!(!OpCode::RoundedBox.is_transform());
        assert!(!OpCode::RoundedBox.is_modifier());
    }

    #[test]
    fn test_new_transforms() {
        // Test the 3 new transform opcodes
        assert!(OpCode::ProjectiveTransform.is_transform());
        assert!(OpCode::LatticeDeform.is_transform());
        assert!(OpCode::SdfSkinning.is_transform());

        assert!(!OpCode::ProjectiveTransform.is_primitive());
        assert!(!OpCode::ProjectiveTransform.is_binary_op());
        assert!(!OpCode::ProjectiveTransform.is_modifier());

        assert_eq!(OpCode::ProjectiveTransform as u8, 200);
        assert_eq!(OpCode::LatticeDeform as u8, 201);
        assert_eq!(OpCode::SdfSkinning as u8, 202);
    }

    #[test]
    fn test_new_modifiers() {
        // Test the 4 new modifier opcodes
        assert!(OpCode::IcosahedralSymmetry.is_modifier());
        assert!(OpCode::IFS.is_modifier());
        assert!(OpCode::HeightmapDisplacement.is_modifier());
        assert!(OpCode::SurfaceRoughness.is_modifier());

        assert!(!OpCode::IcosahedralSymmetry.is_primitive());
        assert!(!OpCode::IcosahedralSymmetry.is_binary_op());
        assert!(!OpCode::IcosahedralSymmetry.is_transform());

        assert_eq!(OpCode::IcosahedralSymmetry as u8, 160);
        assert_eq!(OpCode::IFS as u8, 161);
        assert_eq!(OpCode::HeightmapDisplacement as u8, 162);
        assert_eq!(OpCode::SurfaceRoughness as u8, 163);
    }
}