threers 0.1.0

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
Documentation
//! Metal enumerants and by-value structs.
//!
//! Metal's headers are C enums and small structs; without a binding generator
//! they have to be restated. The values are ABI — they are what the framework
//! reads — so they are transcribed from `<Metal/Metal.h>` and must not be
//! renumbered for convenience.
//!
//! Every struct here is `#[repr(C)]` and is passed to `objc_msgSend` by value,
//! which is correct on both arm64 and x86_64 because rustc lays `repr(C)` out
//! with the platform C ABI.

#![allow(dead_code)]

/// `NSUInteger` — the width of a pointer on every platform Metal runs on.
pub type NSUInteger = usize;

/// `MTLPixelFormat`.
pub mod pixel_format {
    use super::NSUInteger;
    pub const R8_UNORM: NSUInteger = 10;
    /// One 8-bit unsigned integer channel: an 8-bit video plane's samples.
    pub const R8_UINT: NSUInteger = 13;
    /// One 16-bit unsigned integer channel: a deeper video plane's samples.
    pub const R16_UINT: NSUInteger = 23;
    pub const RG8_UNORM: NSUInteger = 30;
    /// Two 8-bit unsigned integer channels: an NV12 Cb/Cr plane.
    pub const RG8_UINT: NSUInteger = 33;
    /// Two 16-bit unsigned integer channels: a P010 Cb/Cr plane.
    pub const RG16_UINT: NSUInteger = 63;
    pub const R16_FLOAT: NSUInteger = 25;
    pub const R32_FLOAT: NSUInteger = 55;
    pub const RGBA8_UNORM: NSUInteger = 70;
    pub const RGBA8_UNORM_SRGB: NSUInteger = 71;
    pub const BGRA8_UNORM: NSUInteger = 80;
    pub const BGRA8_UNORM_SRGB: NSUInteger = 81;
    pub const RGBA16_FLOAT: NSUInteger = 115;
    pub const RGBA32_FLOAT: NSUInteger = 125;
    // Values from the SDK's MTLPixelFormat.h, not from memory: BC7 sRGB was
    // once written here as 145, which is no pixel format at all, and every
    // BC7 texture failed to create.
    pub const R16_UNORM: NSUInteger = 20;
    pub const RG16_FLOAT: NSUInteger = 65;
    pub const RGB10A2_UNORM: NSUInteger = 90;
    pub const RG11B10_FLOAT: NSUInteger = 92;
    pub const RGB9E5_FLOAT: NSUInteger = 93;
    pub const RG32_FLOAT: NSUInteger = 105;
    pub const RGBA16_UNORM: NSUInteger = 110;
    /// The BC formats. Desktop-class GPUs only — see
    /// `MTLDevice.supportsBCTextureCompression`.
    pub const BC1_RGBA: NSUInteger = 130;
    pub const BC1_RGBA_SRGB: NSUInteger = 131;
    pub const BC3_RGBA: NSUInteger = 134;
    pub const BC3_RGBA_SRGB: NSUInteger = 135;
    pub const BC4_R_UNORM: NSUInteger = 140;
    pub const BC5_RG_UNORM: NSUInteger = 142;
    pub const BC6H_RGB_FLOAT: NSUInteger = 150;
    pub const BC6H_RGB_UFLOAT: NSUInteger = 151;
    pub const BC7_RGBA: NSUInteger = 152;
    pub const BC7_RGBA_SRGB: NSUInteger = 153;
    /// ETC2 and EAC: Apple-family GPUs (Apple silicon, iOS, tvOS, visionOS).
    pub const EAC_RGBA8: NSUInteger = 178;
    pub const EAC_RGBA8_SRGB: NSUInteger = 179;
    pub const ETC2_RGB8: NSUInteger = 180;
    pub const ETC2_RGB8_SRGB: NSUInteger = 181;
    /// ASTC LDR, by footprint in `AstcBlock::ALL` order: sRGB from 186, linear
    /// from 204, each with a gap after 6x6 (191 and 209 are not formats).
    pub fn astc(index: usize, srgb: bool) -> NSUInteger {
        let base = if srgb { 186 } else { 204 };
        base + index + (index >= 5) as usize
    }
    pub const DEPTH32_FLOAT: NSUInteger = 252;
    pub const DEPTH32_FLOAT_STENCIL8: NSUInteger = 260;

    /// Bytes per pixel for the formats this backend uploads or reads back.
    pub fn bytes_per_pixel(format: NSUInteger) -> Option<usize> {
        Some(match format {
            R8_UNORM => 1,
            RG8_UNORM | R16_FLOAT => 2,
            R32_FLOAT => 4,
            RGBA8_UNORM | RGBA8_UNORM_SRGB | BGRA8_UNORM | BGRA8_UNORM_SRGB => 4,
            RGBA16_FLOAT => 8,
            RGBA32_FLOAT => 16,
            _ => return None,
        })
    }

    /// Whether the GPU applies the sRGB transfer function on write/read.
    pub fn is_srgb(format: NSUInteger) -> bool {
        matches!(format, RGBA8_UNORM_SRGB | BGRA8_UNORM_SRGB)
    }

    /// Whether channel order is BGRA rather than RGBA (the `CAMetalLayer` default).
    pub fn is_bgra(format: NSUInteger) -> bool {
        matches!(format, BGRA8_UNORM | BGRA8_UNORM_SRGB)
    }
}

/// `MTLTextureType`.
pub mod texture_type {
    use super::NSUInteger;
    pub const TYPE_2D: NSUInteger = 2;
    pub const TYPE_2D_ARRAY: NSUInteger = 3;
    pub const TYPE_2D_MULTISAMPLE: NSUInteger = 4;
    pub const TYPE_CUBE: NSUInteger = 5;
    pub const TYPE_3D: NSUInteger = 7;
}

/// `MTLTextureUsage` — a bit mask.
pub mod texture_usage {
    use super::NSUInteger;
    pub const UNKNOWN: NSUInteger = 0;
    pub const SHADER_READ: NSUInteger = 1;
    pub const SHADER_WRITE: NSUInteger = 2;
    pub const RENDER_TARGET: NSUInteger = 4;
}

/// `MTLStorageMode`, as it appears on a texture descriptor.
pub mod storage_mode {
    use super::NSUInteger;
    pub const SHARED: NSUInteger = 0;
    pub const MANAGED: NSUInteger = 1;
    pub const PRIVATE: NSUInteger = 2;
    pub const MEMORYLESS: NSUInteger = 3;
}

/// `MTLResourceOptions` — storage mode shifted into the resource-option bits.
pub mod resource_options {
    use super::NSUInteger;
    pub const STORAGE_MODE_SHARED: NSUInteger = 0 << 4;
    pub const STORAGE_MODE_MANAGED: NSUInteger = 1 << 4;
    pub const STORAGE_MODE_PRIVATE: NSUInteger = 2 << 4;
}

/// `MTLLoadAction`.
pub mod load_action {
    use super::NSUInteger;
    pub const DONT_CARE: NSUInteger = 0;
    pub const LOAD: NSUInteger = 1;
    pub const CLEAR: NSUInteger = 2;
}

/// `MTLStoreAction`.
pub mod store_action {
    use super::NSUInteger;
    pub const DONT_CARE: NSUInteger = 0;
    pub const STORE: NSUInteger = 1;
    pub const MULTISAMPLE_RESOLVE: NSUInteger = 2;
    pub const STORE_AND_MULTISAMPLE_RESOLVE: NSUInteger = 3;
}

/// `MTLPrimitiveType`.
pub mod primitive {
    use super::NSUInteger;
    pub const POINT: NSUInteger = 0;
    pub const LINE: NSUInteger = 1;
    pub const LINE_STRIP: NSUInteger = 2;
    pub const TRIANGLE: NSUInteger = 3;
    pub const TRIANGLE_STRIP: NSUInteger = 4;
}

/// `MTLPrimitiveTopologyClass`.
///
/// A pipeline whose vertex function writes `render_target_array_index` must
/// declare which of these it rasterises — Metal rejects it otherwise.
pub mod topology_class {
    use super::NSUInteger;
    pub const UNSPECIFIED: NSUInteger = 0;
    pub const POINT: NSUInteger = 1;
    pub const LINE: NSUInteger = 2;
    pub const TRIANGLE: NSUInteger = 3;

    /// The class a `MTLPrimitiveType` belongs to.
    pub fn of(primitive: NSUInteger) -> NSUInteger {
        match primitive {
            super::primitive::POINT => POINT,
            super::primitive::LINE | super::primitive::LINE_STRIP => LINE,
            _ => TRIANGLE,
        }
    }
}

/// `MTLIndexType`.
pub mod index_type {
    use super::NSUInteger;
    pub const UINT16: NSUInteger = 0;
    pub const UINT32: NSUInteger = 1;
}

/// `MTLCompareFunction`.
pub mod compare {
    use super::NSUInteger;
    pub const NEVER: NSUInteger = 0;
    pub const LESS: NSUInteger = 1;
    pub const EQUAL: NSUInteger = 2;
    pub const LESS_EQUAL: NSUInteger = 3;
    pub const GREATER: NSUInteger = 4;
    pub const NOT_EQUAL: NSUInteger = 5;
    pub const GREATER_EQUAL: NSUInteger = 6;
    pub const ALWAYS: NSUInteger = 7;
}

/// `MTLCullMode`.
pub mod cull {
    use super::NSUInteger;
    pub const NONE: NSUInteger = 0;
    pub const FRONT: NSUInteger = 1;
    pub const BACK: NSUInteger = 2;
}

/// `MTLWinding`.
pub mod winding {
    use super::NSUInteger;
    pub const CLOCKWISE: NSUInteger = 0;
    pub const COUNTER_CLOCKWISE: NSUInteger = 1;
}

/// `MTLTriangleFillMode`.
pub mod fill_mode {
    use super::NSUInteger;
    pub const FILL: NSUInteger = 0;
    pub const LINES: NSUInteger = 1;
}

/// `MTLBlendFactor`.
pub mod blend_factor {
    use super::NSUInteger;
    pub const ZERO: NSUInteger = 0;
    pub const ONE: NSUInteger = 1;
    pub const SOURCE_COLOR: NSUInteger = 2;
    pub const ONE_MINUS_SOURCE_COLOR: NSUInteger = 3;
    pub const SOURCE_ALPHA: NSUInteger = 4;
    pub const ONE_MINUS_SOURCE_ALPHA: NSUInteger = 5;
    pub const DESTINATION_COLOR: NSUInteger = 6;
    pub const DESTINATION_ALPHA: NSUInteger = 8;
}

/// `MTLBlendOperation`.
pub mod blend_op {
    use super::NSUInteger;
    pub const ADD: NSUInteger = 0;
}

/// `MTLSamplerMinMagFilter` / `MTLSamplerMipFilter`.
pub mod filter {
    use super::NSUInteger;
    pub const NEAREST: NSUInteger = 0;
    pub const LINEAR: NSUInteger = 1;
    pub const MIP_NOT_MIPMAPPED: NSUInteger = 0;
    pub const MIP_NEAREST: NSUInteger = 1;
    pub const MIP_LINEAR: NSUInteger = 2;
}

/// `MTLSamplerAddressMode`.
pub mod address_mode {
    use super::NSUInteger;
    pub const CLAMP_TO_EDGE: NSUInteger = 0;
    pub const MIRROR_CLAMP_TO_EDGE: NSUInteger = 1;
    pub const REPEAT: NSUInteger = 2;
    pub const MIRROR_REPEAT: NSUInteger = 3;
}

/// `MTLOrigin`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct MTLOrigin {
    pub x: NSUInteger,
    pub y: NSUInteger,
    pub z: NSUInteger,
}

/// `MTLSize`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct MTLSize {
    pub width: NSUInteger,
    pub height: NSUInteger,
    pub depth: NSUInteger,
}

/// `MTLRegion`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct MTLRegion {
    pub origin: MTLOrigin,
    pub size: MTLSize,
}

impl MTLRegion {
    /// The whole of a 2D image.
    pub fn image_2d(width: u32, height: u32) -> Self {
        Self {
            origin: MTLOrigin::default(),
            size: MTLSize {
                width: width as NSUInteger,
                height: height as NSUInteger,
                depth: 1,
            },
        }
    }
}

/// `MTLClearColor` — four `double`s, always linear (never sRGB-encoded, even
/// for an sRGB attachment: the GPU applies the transfer function on write).
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct MTLClearColor {
    pub red: f64,
    pub green: f64,
    pub blue: f64,
    pub alpha: f64,
}

/// `MTLViewport`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct MTLViewport {
    pub origin_x: f64,
    pub origin_y: f64,
    pub width: f64,
    pub height: f64,
    pub znear: f64,
    pub zfar: f64,
}

/// `MTLScissorRect` — top-left origin, in attachment pixels, and it must lie
/// inside the attachment.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[repr(C)]
pub struct MTLScissorRect {
    pub x: NSUInteger,
    pub y: NSUInteger,
    pub width: NSUInteger,
    pub height: NSUInteger,
}

/// `NSRange`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct NSRange {
    pub location: NSUInteger,
    pub length: NSUInteger,
}

/// `CGSize`.
#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
pub struct CGSize {
    pub width: f64,
    pub height: f64,
}

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

    #[test]
    fn struct_layouts_match_metal() {
        // These sizes are the ABI contract with the framework; a mismatch is a
        // silently corrupt argument list, not a compile error.
        let word = std::mem::size_of::<usize>();
        assert_eq!(std::mem::size_of::<MTLOrigin>(), 3 * word);
        assert_eq!(std::mem::size_of::<MTLSize>(), 3 * word);
        assert_eq!(std::mem::size_of::<MTLRegion>(), 6 * word);
        assert_eq!(std::mem::size_of::<MTLClearColor>(), 32);
        assert_eq!(std::mem::size_of::<MTLViewport>(), 48);
        assert_eq!(std::mem::size_of::<NSRange>(), 2 * word);
        assert_eq!(std::mem::size_of::<CGSize>(), 16);
    }

    #[test]
    fn pixel_format_metadata() {
        assert_eq!(
            pixel_format::bytes_per_pixel(pixel_format::RGBA8_UNORM_SRGB),
            Some(4)
        );
        assert_eq!(
            pixel_format::bytes_per_pixel(pixel_format::RGBA16_FLOAT),
            Some(8)
        );
        assert_eq!(
            pixel_format::bytes_per_pixel(pixel_format::DEPTH32_FLOAT),
            None
        );
        assert!(pixel_format::is_srgb(pixel_format::BGRA8_UNORM_SRGB));
        assert!(!pixel_format::is_srgb(pixel_format::RGBA8_UNORM));
        assert!(pixel_format::is_bgra(pixel_format::BGRA8_UNORM));
        assert!(!pixel_format::is_bgra(pixel_format::RGBA8_UNORM_SRGB));
    }
}