screencapturekit/

metal.rs

//! Metal texture helpers for `IOSurface`
//!
//! This module provides utilities for creating Metal textures from `IOSurface`
//! with zero-copy GPU access. This is the most efficient way to use captured
//! frames with Metal rendering.
//!
//! ## Features
//!
//! - Zero-copy texture creation from `IOSurface`
//! - Automatic pixel format detection and Metal format mapping
//! - Multi-plane support for YCbCr formats (420v, 420f)
//! - Native Metal device and texture types (no external crate needed)
//! - Embedded Metal shaders for common rendering scenarios
//!
//! ## When to Use
//!
//! Use this module when you need:
//! - **Real-time rendering** - Display captured frames in a Metal view
//! - **GPU processing** - Apply compute shaders to captured content
//! - **Zero-copy performance** - Avoid CPU-GPU memory transfers
//!
//! For CPU-based processing, use [`CVPixelBuffer`](crate::cv::CVPixelBuffer) with lock guards instead.
//!
//! ## Workflow
//!
//! 1. Get `IOSurface` from captured frame via [`CMSampleBufferExt::pixel_buffer()`](crate::cm::CMSampleBufferExt::pixel_buffer)
//! 2. Create Metal textures with [`IOSurface::create_metal_textures()`](crate::cm::IOSurface::create_metal_textures)
//! 3. Render using the built-in shaders or your own
//!
//! ## Example
//!
//! ```no_run
//! use screencapturekit::cm::{CMSampleBuffer, CMSampleBufferExt, IOSurface};
//! use screencapturekit::metal::{IOSurfaceMetalExt, MetalDevice};
//!
//! // Get the system default Metal device
//! let device = MetalDevice::system_default().expect("No Metal device");
//!
//! // In your frame handler
//! fn handle_frame(sample: &CMSampleBuffer, device: &MetalDevice) {
//!     if let Some(pixel_buffer) = sample.pixel_buffer() {
//!         if let Some(surface) = pixel_buffer.io_surface() {
//!             // Create textures directly - no closures or factories needed
//!             if let Some(textures) = surface.create_metal_textures(device) {
//!                 if textures.is_ycbcr() {
//!                     // Use YCbCr shader with plane0 (Y) and plane1 (CbCr)
//!                     println!("YCbCr texture: {}x{}",
//!                         textures.plane0.width(), textures.plane0.height());
//!                 } else {
//!                     // Use single-plane shader (BGRA, l10r)
//!                     println!("Single-plane texture: {}x{}",
//!                         textures.plane0.width(), textures.plane0.height());
//!                 }
//!             }
//!         }
//!     }
//! }
//! ```
//!
//! ## Built-in Shaders
//!
//! The [`SHADER_SOURCE`] constant contains Metal shaders for common rendering scenarios:
//!
//! | Function | Description |
//! |----------|-------------|
//! | `vertex_fullscreen` | Aspect-ratio-preserving fullscreen quad |
//! | `fragment_textured` | BGRA/L10R single-texture rendering |
//! | `fragment_ycbcr` | YCbCr biplanar (420v/420f) to RGB conversion |
//! | `vertex_colored` / `fragment_colored` | UI overlay rendering |

use std::ffi::{c_void, CStr};
use std::marker::PhantomData;
use std::ptr::NonNull;
use std::sync::{Arc, Mutex, PoisonError};

use crate::cm::IOSurface;
use crate::FourCharCode;

/// Pixel format constants using [`FourCharCode`]
///
/// These match the values returned by `IOSurface::pixel_format()`.
pub mod pixel_format {
    use crate::FourCharCode;

    /// BGRA 8-bit per channel (32-bit total)
    pub const BGRA: FourCharCode = FourCharCode::from_bytes(*b"BGRA");

    /// 10-bit RGB (ARGB2101010, also known as l10r)
    pub const L10R: FourCharCode = FourCharCode::from_bytes(*b"l10r");

    /// YCbCr 4:2:0 biplanar, video range
    pub const YCBCR_420V: FourCharCode = FourCharCode::from_bytes(*b"420v");

    /// YCbCr 4:2:0 biplanar, full range
    pub const YCBCR_420F: FourCharCode = FourCharCode::from_bytes(*b"420f");

    /// Check if a pixel format is a YCbCr biplanar format
    ///
    /// Accepts either a `FourCharCode` or a raw `u32`.
    #[must_use]
    pub fn is_ycbcr_biplanar(format: impl Into<FourCharCode>) -> bool {
        let f = format.into();
        f.equals(YCBCR_420V) || f.equals(YCBCR_420F)
    }

    /// Check if a pixel format uses full range (vs video range)
    ///
    /// Accepts either a `FourCharCode` or a raw `u32`.
    #[must_use]
    pub fn is_full_range(format: impl Into<FourCharCode>) -> bool {
        format.into().equals(YCBCR_420F)
    }
}

/// Metal pixel format enum matching `MTLPixelFormat` values
///
/// This provides a Rust-native enum for common Metal pixel formats used in screen capture.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u64)]
pub enum MetalPixelFormat {
    /// 8-bit normalized unsigned integer per channel (BGRA order)
    BGRA8Unorm = 80,
    /// 10-bit RGB with 2-bit alpha (BGR order)
    BGR10A2Unorm = 94,
    /// 8-bit normalized unsigned integer (single channel, for Y plane)
    R8Unorm = 10,
    /// 8-bit normalized unsigned integer per channel (two channels, for `CbCr` plane)
    RG8Unorm = 30,
}

impl MetalPixelFormat {
    /// Get the raw `MTLPixelFormat` value
    #[must_use]
    pub const fn raw(self) -> u64 {
        self as u64
    }

    /// Create from a raw `MTLPixelFormat` value
    #[must_use]
    pub const fn from_raw(value: u64) -> Option<Self> {
        match value {
            80 => Some(Self::BGRA8Unorm),
            94 => Some(Self::BGR10A2Unorm),
            10 => Some(Self::R8Unorm),
            30 => Some(Self::RG8Unorm),
            _ => None,
        }
    }
}

/// Information about an `IOSurface` for Metal texture creation
#[derive(Debug, Clone)]
pub struct IOSurfaceInfo {
    /// Width in pixels
    pub width: usize,
    /// Height in pixels
    pub height: usize,
    /// Bytes per row
    pub bytes_per_row: usize,
    /// Pixel format
    pub pixel_format: FourCharCode,
    /// Number of planes (0 for single-plane formats, 2 for YCbCr biplanar)
    pub plane_count: usize,
    /// Per-plane information
    pub planes: Vec<PlaneInfo>,
}

/// Information about a single plane within an `IOSurface`
#[derive(Debug, Clone)]
pub struct PlaneInfo {
    /// Plane index
    pub index: usize,
    /// Width in pixels
    pub width: usize,
    /// Height in pixels
    pub height: usize,
    /// Bytes per row
    pub bytes_per_row: usize,
}

/// Metal texture descriptor parameters for creating textures from `IOSurface`
///
/// This provides the information needed to configure a Metal `MTLTextureDescriptor`.
#[derive(Debug, Clone, Copy)]
pub struct TextureParams {
    /// Width in pixels
    pub width: usize,
    /// Height in pixels
    pub height: usize,
    /// Recommended Metal pixel format
    pub format: MetalPixelFormat,
    /// Plane index for multi-planar surfaces
    pub plane: usize,
}

impl TextureParams {
    /// Get the raw `MTLPixelFormat` value for use with Metal APIs
    #[must_use]
    pub const fn metal_pixel_format(&self) -> u64 {
        self.format.raw()
    }
}

/// Result of creating Metal textures from an `IOSurface`
#[derive(Debug)]
pub struct CapturedTextures<T> {
    /// Primary texture (BGRA/L10R for single-plane, Y plane for YCbCr)
    pub plane0: T,
    /// Secondary texture (`CbCr` plane for YCbCr formats)
    pub plane1: Option<T>,
    /// The pixel format of the source surface
    pub pixel_format: FourCharCode,
    /// Width in pixels
    pub width: usize,
    /// Height in pixels
    pub height: usize,
}

impl<T> CapturedTextures<T> {
    /// Check if this capture uses a YCbCr biplanar format
    #[must_use]
    pub fn is_ycbcr(&self) -> bool {
        pixel_format::is_ycbcr_biplanar(self.pixel_format)
    }
}

/// Metal shader source for rendering captured frames
///
/// This shader supports:
/// - BGRA and BGR10A2 single-plane formats
/// - YCbCr 4:2:0 biplanar formats (420v and 420f)
/// - Aspect-ratio-preserving fullscreen quad
///
/// ## Uniforms
///
/// The shader expects a `Uniforms` buffer:
/// - `viewport_size: float2` - Current viewport dimensions
/// - `texture_size: float2` - Source texture dimensions
/// - `time: float` - Animation time (optional)
/// - `pixel_format: uint` - `FourCC` pixel format code
///
/// ## Usage
///
/// 1. Compile shader with `device.new_library_with_source(SHADER_SOURCE, ...)`
/// 2. Create pipeline with `vertex_fullscreen` + `fragment_textured` (for BGRA/L10R)
/// 3. Or use `vertex_fullscreen` + `fragment_ycbcr` (for 420v/420f)
/// 4. Bind plane0 to texture slot 0, plane1 to texture slot 1 (for YCbCr)
pub const SHADER_SOURCE: &str = r"
#include <metal_stdlib>
using namespace metal;

struct Uniforms {
    float2 viewport_size;
    float2 texture_size;
    float time;
    uint pixel_format;
    float padding[2];
};

struct TexturedVertexOut {
    float4 position [[position]];
    float2 texcoord;
};

// Fullscreen quad vertex shader with aspect ratio correction
vertex TexturedVertexOut vertex_fullscreen(uint vid [[vertex_id]], constant Uniforms& uniforms [[buffer(0)]]) {
    TexturedVertexOut out;
    float va = uniforms.viewport_size.x / uniforms.viewport_size.y;
    float ta = uniforms.texture_size.x / uniforms.texture_size.y;
    float sx = ta > va ? 1.0 : ta / va;
    float sy = ta > va ? va / ta : 1.0;
    float2 positions[4] = { float2(-sx, -sy), float2(sx, -sy), float2(-sx, sy), float2(sx, sy) };
    float2 texcoords[4] = { float2(0.0, 1.0), float2(1.0, 1.0), float2(0.0, 0.0), float2(1.0, 0.0) };
    out.position = float4(positions[vid], 0.0, 1.0);
    out.texcoord = texcoords[vid];
    return out;
}

// BGRA/RGB texture fragment shader
fragment float4 fragment_textured(TexturedVertexOut in [[stage_in]], texture2d<float> tex [[texture(0)]]) {
    constexpr sampler s(mag_filter::linear, min_filter::linear);
    return tex.sample(s, in.texcoord);
}

// YCbCr to RGB conversion (BT.709 matrix for HD video)
float4 ycbcr_to_rgb(float y, float2 cbcr, bool full_range) {
    float y_adj = full_range ? y : (y - 16.0/255.0) * (255.0/219.0);
    float2 cbcr_adj = full_range
        ? cbcr - 0.5
        : (cbcr - 16.0/255.0) * (255.0/224.0) - 0.5;
    float cb = cbcr_adj.x;
    float cr = cbcr_adj.y;
    // BT.709 conversion matrix
    float r = y_adj + 1.5748 * cr;
    float g = y_adj - 0.1873 * cb - 0.4681 * cr;
    float b = y_adj + 1.8556 * cb;
    return float4(saturate(float3(r, g, b)), 1.0);
}

// YCbCr biplanar (420v/420f) fragment shader
fragment float4 fragment_ycbcr(TexturedVertexOut in [[stage_in]], 
    texture2d<float> y_tex [[texture(0)]], 
    texture2d<float> cbcr_tex [[texture(1)]],
    constant Uniforms& uniforms [[buffer(0)]]) {
    constexpr sampler s(mag_filter::linear, min_filter::linear);
    float y = y_tex.sample(s, in.texcoord).r;
    float2 cbcr = cbcr_tex.sample(s, in.texcoord).rg;
    bool full_range = (uniforms.pixel_format == 0x34323066); // '420f'
    return ycbcr_to_rgb(y, cbcr, full_range);
}

// Colored vertex input/output for UI overlays
struct ColoredVertex {
    float2 position [[attribute(0)]];
    float4 color [[attribute(1)]];
};

struct ColoredVertexOut {
    float4 position [[position]];
    float4 color;
};

// Colored vertex shader for UI elements (position in pixels, converted to NDC)
vertex ColoredVertexOut vertex_colored(ColoredVertex in [[stage_in]], constant Uniforms& uniforms [[buffer(1)]]) {
    ColoredVertexOut out;
    float2 ndc = (in.position / uniforms.viewport_size) * 2.0 - 1.0;
    ndc.y = -ndc.y;
    out.position = float4(ndc, 0.0, 1.0);
    out.color = in.color;
    return out;
}

// Colored fragment shader for UI elements
fragment float4 fragment_colored(ColoredVertexOut in [[stage_in]]) {
    return in.color;
}
";

/// Uniforms structure for Metal shaders
///
/// This matches the layout expected by `SHADER_SOURCE`.
#[repr(C)]
#[derive(Debug, Clone, Copy, Default)]
pub struct Uniforms {
    /// Viewport width and height
    pub viewport_size: [f32; 2],
    /// Texture width and height
    pub texture_size: [f32; 2],
    /// Animation time (optional)
    pub time: f32,
    /// Pixel format (raw u32 for GPU compatibility)
    pub pixel_format: u32,
    /// Padding for alignment
    #[doc(hidden)]
    pub _padding: [f32; 2],
}

impl Uniforms {
    /// Encoded size of one uniforms value.
    pub const BYTE_LEN: usize = 32;

    /// Create uniforms for a given viewport and texture size
    #[must_use]
    pub fn new(
        viewport_width: f32,
        viewport_height: f32,
        texture_width: f32,
        texture_height: f32,
    ) -> Self {
        Self {
            viewport_size: [viewport_width, viewport_height],
            texture_size: [texture_width, texture_height],
            time: 0.0,
            pixel_format: 0,
            _padding: [0.0; 2],
        }
    }

    /// Create uniforms from viewport size and captured textures
    ///
    /// Automatically extracts texture dimensions and pixel format.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use screencapturekit::metal::{IOSurfaceMetalExt, MetalDevice, Uniforms};
    /// use screencapturekit::cm::IOSurface;
    ///
    /// fn example(surface: &IOSurface, device: &MetalDevice) {
    ///     if let Some(textures) = surface.create_metal_textures(device) {
    ///         let uniforms = Uniforms::from_captured_textures(1920.0, 1080.0, &textures);
    ///     }
    /// }
    /// ```
    #[must_use]
    #[allow(clippy::cast_precision_loss)] // Screen dimensions will fit in f32
    pub fn from_captured_textures<T>(
        viewport_width: f32,
        viewport_height: f32,
        textures: &CapturedTextures<T>,
    ) -> Self {
        Self {
            viewport_size: [viewport_width, viewport_height],
            texture_size: [textures.width as f32, textures.height as f32],
            time: 0.0,
            pixel_format: textures.pixel_format.as_u32(),
            _padding: [0.0; 2],
        }
    }

    /// Set the pixel format
    ///
    /// Accepts either a `FourCharCode` or a raw `u32`:
    /// ```no_run
    /// use screencapturekit::metal::{Uniforms, pixel_format};
    ///
    /// let uniforms = Uniforms::new(1920.0, 1080.0, 1920.0, 1080.0)
    ///     .with_pixel_format(pixel_format::BGRA);
    /// ```
    #[must_use]
    pub fn with_pixel_format(mut self, format: impl Into<FourCharCode>) -> Self {
        self.pixel_format = format.into().as_u32();
        self
    }

    /// Set the animation time
    #[must_use]
    pub fn with_time(mut self, time: f32) -> Self {
        self.time = time;
        self
    }

    /// Encode this value as initialized native-endian GPU bytes.
    #[must_use]
    #[allow(clippy::used_underscore_binding)]
    pub fn to_bytes(self) -> [u8; Self::BYTE_LEN] {
        let words = [
            self.viewport_size[0].to_bits(),
            self.viewport_size[1].to_bits(),
            self.texture_size[0].to_bits(),
            self.texture_size[1].to_bits(),
            self.time.to_bits(),
            self.pixel_format,
            self._padding[0].to_bits(),
            self._padding[1].to_bits(),
        ];
        let mut bytes = [0_u8; Self::BYTE_LEN];
        for (chunk, word) in bytes.chunks_exact_mut(4).zip(words) {
            chunk.copy_from_slice(&word.to_ne_bytes());
        }
        bytes
    }
}

/// Errors raised before an invalid Metal operation reaches the native API.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MetalError {
    /// A Rust `usize` cannot be represented by Swift's signed `Int`.
    SwiftIntOverflow {
        /// Argument name.
        argument: &'static str,
        /// Rejected value.
        value: usize,
    },
    /// A binding index exceeds the native slot count.
    IndexOutOfRange {
        /// Argument name.
        argument: &'static str,
        /// Rejected index.
        index: usize,
        /// Exclusive upper bound.
        max_exclusive: usize,
    },
    /// The Swift bridge rejected an operation after defensive validation.
    NativeCallRejected {
        /// Operation name.
        operation: &'static str,
    },
    /// The command buffer was already committed.
    CommandBufferAlreadyCommitted,
    /// A command encoder is still active on the command buffer.
    CommandBufferHasActiveEncoder,
    /// The command buffer already has an active render encoder.
    RenderEncoderAlreadyActive,
    /// Native render-encoder creation failed.
    RenderEncoderCreationFailed,
    /// The render encoder has already ended.
    RenderEncoderEnded,
    UnknownPixelFormat {
        raw: u64,
    },
}

impl std::fmt::Display for MetalError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::SwiftIntOverflow { argument, value } => {
                write!(f, "{argument} value {value} exceeds Swift Int")
            }
            Self::IndexOutOfRange {
                argument,
                index,
                max_exclusive,
            } => write!(f, "{argument} index {index} is outside 0..{max_exclusive}"),
            Self::NativeCallRejected { operation } => {
                write!(f, "native Metal rejected {operation}")
            }
            Self::CommandBufferAlreadyCommitted => f.write_str("command buffer already committed"),
            Self::CommandBufferHasActiveEncoder => {
                f.write_str("command buffer has an active encoder")
            }
            Self::RenderEncoderAlreadyActive => {
                f.write_str("command buffer already has an active render encoder")
            }
            Self::RenderEncoderCreationFailed => {
                f.write_str("native render command encoder creation failed")
            }
            Self::RenderEncoderEnded => f.write_str("render command encoder already ended"),
            Self::UnknownPixelFormat { raw } => {
                write!(
                    f,
                    "texture pixel format {raw} is not a known MetalPixelFormat"
                )
            }
        }
    }
}

impl std::error::Error for MetalError {}

// MARK: - FFI Declarations

#[link(name = "Metal", kind = "framework")]
extern "C" {}

#[link(name = "QuartzCore", kind = "framework")]
extern "C" {}

extern "C" {
    // Device
    fn metal_create_system_default_device() -> *mut c_void;
    fn metal_device_release(device: *mut c_void);
    fn metal_device_get_name(device: *mut c_void) -> *const std::ffi::c_char;
    fn metal_device_retain(device: *mut c_void) -> *mut c_void;
    fn metal_string_free(ptr: *mut std::ffi::c_char);
    fn metal_device_create_command_queue(device: *mut c_void) -> *mut c_void;
    fn metal_device_create_render_pipeline_state(
        device: *mut c_void,
        desc: *mut c_void,
    ) -> *mut c_void;

    // Texture
    fn metal_create_texture_from_iosurface(
        device: *mut c_void,
        iosurface: *mut c_void,
        plane: usize,
        width: usize,
        height: usize,
        pixel_format: u64,
    ) -> *mut c_void;
    fn metal_texture_release(texture: *mut c_void);
    fn metal_texture_retain(texture: *mut c_void) -> *mut c_void;
    fn metal_texture_get_width(texture: *mut c_void) -> usize;
    fn metal_texture_get_height(texture: *mut c_void) -> usize;
    fn metal_texture_get_pixel_format(texture: *mut c_void) -> u64;

    // Command Queue
    fn metal_command_queue_release(queue: *mut c_void);
    fn metal_command_queue_command_buffer(queue: *mut c_void) -> *mut c_void;

    // Library/Function
    fn metal_device_create_library_with_source(
        device: *mut c_void,
        source: *const std::ffi::c_char,
        error_out: *mut *const std::ffi::c_char,
    ) -> *mut c_void;
    fn metal_library_release(library: *mut c_void);
    fn metal_library_get_function(
        library: *mut c_void,
        name: *const std::ffi::c_char,
    ) -> *mut c_void;
    fn metal_function_release(function: *mut c_void);

    // Buffer
    fn metal_device_create_buffer(device: *mut c_void, length: usize, options: u64) -> *mut c_void;
    fn metal_buffer_contents(buffer: *mut c_void) -> *mut c_void;
    fn metal_buffer_length(buffer: *mut c_void) -> usize;
    fn metal_buffer_did_modify_range(buffer: *mut c_void, location: usize, length: usize);
    fn metal_buffer_release(buffer: *mut c_void);

    // Layer
    fn metal_layer_create() -> *mut c_void;
    fn metal_layer_set_device(layer: *mut c_void, device: *mut c_void);
    fn metal_layer_set_pixel_format(layer: *mut c_void, format: u64);
    fn metal_layer_set_drawable_size(layer: *mut c_void, width: f64, height: f64);
    fn metal_layer_set_presents_with_transaction(layer: *mut c_void, value: bool);
    fn metal_layer_next_drawable(layer: *mut c_void) -> *mut c_void;
    fn metal_layer_release(layer: *mut c_void);

    // Drawable
    fn metal_drawable_texture(drawable: *mut c_void) -> *mut c_void;
    fn metal_drawable_release(drawable: *mut c_void);

    // Command Buffer
    fn metal_command_buffer_present_drawable(cmd_buffer: *mut c_void, drawable: *mut c_void);
    fn metal_command_buffer_commit(cmd_buffer: *mut c_void);
    fn metal_command_buffer_retain(cmd_buffer: *mut c_void) -> *mut c_void;
    fn metal_command_buffer_release(cmd_buffer: *mut c_void);

    // Render Pass
    fn metal_render_pass_descriptor_create() -> *mut c_void;
    fn metal_render_pass_set_color_attachment_texture(
        desc: *mut c_void,
        index: usize,
        texture: *mut c_void,
    ) -> bool;
    fn metal_render_pass_set_color_attachment_load_action(
        desc: *mut c_void,
        index: usize,
        action: u64,
    ) -> bool;
    fn metal_render_pass_set_color_attachment_store_action(
        desc: *mut c_void,
        index: usize,
        action: u64,
    ) -> bool;
    fn metal_render_pass_set_color_attachment_clear_color(
        desc: *mut c_void,
        index: usize,
        r: f64,
        g: f64,
        b: f64,
        a: f64,
    ) -> bool;
    fn metal_render_pass_descriptor_release(desc: *mut c_void);

    // Vertex Descriptor
    fn metal_vertex_descriptor_create() -> *mut c_void;
    fn metal_vertex_descriptor_set_attribute(
        desc: *mut c_void,
        index: usize,
        format: u64,
        offset: usize,
        buffer_index: usize,
    ) -> bool;
    fn metal_vertex_descriptor_set_layout(
        desc: *mut c_void,
        buffer_index: usize,
        stride: usize,
        step_function: u64,
    ) -> bool;
    fn metal_vertex_descriptor_release(desc: *mut c_void);

    // Render Pipeline Descriptor
    fn metal_render_pipeline_descriptor_create() -> *mut c_void;
    fn metal_render_pipeline_descriptor_set_vertex_function(
        desc: *mut c_void,
        function: *mut c_void,
    );
    fn metal_render_pipeline_descriptor_set_fragment_function(
        desc: *mut c_void,
        function: *mut c_void,
    );
    fn metal_render_pipeline_descriptor_set_vertex_descriptor(
        desc: *mut c_void,
        vertex_descriptor: *mut c_void,
    );
    fn metal_render_pipeline_descriptor_set_color_attachment_pixel_format(
        desc: *mut c_void,
        index: usize,
        format: u64,
    ) -> bool;
    fn metal_render_pipeline_descriptor_set_blending_enabled(
        desc: *mut c_void,
        index: usize,
        enabled: bool,
    ) -> bool;
    fn metal_render_pipeline_descriptor_set_blend_operations(
        desc: *mut c_void,
        index: usize,
        rgb_op: u64,
        alpha_op: u64,
    ) -> bool;
    fn metal_render_pipeline_descriptor_set_blend_factors(
        desc: *mut c_void,
        index: usize,
        src_rgb: u64,
        dst_rgb: u64,
        src_alpha: u64,
        dst_alpha: u64,
    ) -> bool;
    fn metal_render_pipeline_descriptor_release(desc: *mut c_void);
    fn metal_render_pipeline_state_release(state: *mut c_void);

    // Render Command Encoder
    fn metal_command_buffer_render_command_encoder(
        cmd_buffer: *mut c_void,
        render_pass: *mut c_void,
    ) -> *mut c_void;
    fn metal_render_encoder_set_pipeline_state(encoder: *mut c_void, state: *mut c_void);
    fn metal_render_encoder_set_vertex_buffer(
        encoder: *mut c_void,
        buffer: *mut c_void,
        offset: usize,
        index: usize,
    ) -> bool;
    fn metal_render_encoder_set_fragment_buffer(
        encoder: *mut c_void,
        buffer: *mut c_void,
        offset: usize,
        index: usize,
    ) -> bool;
    fn metal_render_encoder_set_fragment_texture(
        encoder: *mut c_void,
        texture: *mut c_void,
        index: usize,
    ) -> bool;
    fn metal_render_encoder_draw_primitives(
        encoder: *mut c_void,
        primitive_type: u64,
        vertex_start: usize,
        vertex_count: usize,
    ) -> bool;
    fn metal_render_encoder_end_encoding(encoder: *mut c_void);
    fn metal_render_encoder_retain(encoder: *mut c_void) -> *mut c_void;
    fn metal_render_encoder_release(encoder: *mut c_void);

    // NSView helpers
    fn nsview_set_wants_layer(view: *mut c_void);
    fn nsview_set_layer(view: *mut c_void, layer: *mut c_void);
}

// MARK: - Metal Device

/// A Metal device (GPU)
///
/// This is a wrapper around `MTLDevice` that provides safe access to Metal functionality.
#[derive(Debug)]
pub struct MetalDevice {
    ptr: NonNull<c_void>,
    /// Whether this wrapper owns a `+1` reference that must be released on drop.
    /// `false` for borrowed devices created via [`Self::from_ptr`].
    owned: bool,
}

impl MetalDevice {
    /// Get the system default Metal device
    ///
    /// Returns `None` if no Metal device is available.
    #[must_use]
    pub fn system_default() -> Option<Self> {
        let ptr = unsafe { metal_create_system_default_device() };
        NonNull::new(ptr).map(|ptr| Self { ptr, owned: true })
    }

    /// Create a `MetalDevice` from a raw `MTLDevice` pointer
    ///
    /// This is useful when you already have a device from another source
    /// (e.g., the `metal` crate) and want to use it for texture creation.
    ///
    /// # Safety
    ///
    /// The pointer must be a valid `MTLDevice` pointer. The wrapper *borrows*
    /// the device: it will NOT be released when this wrapper is dropped. Use
    /// [`Self::from_ptr_retained`] if you want the wrapper to hold its own
    /// reference.
    #[must_use]
    pub unsafe fn from_ptr(ptr: *mut c_void) -> Option<Self> {
        NonNull::new(ptr).map(|ptr| Self { ptr, owned: false })
    }

    /// Create a `MetalDevice` from a raw `MTLDevice` pointer, retaining it
    ///
    /// The wrapper takes its own `+1` reference (via an Objective-C `retain`)
    /// and releases it on drop, so the caller keeps ownership of their
    /// reference.
    ///
    /// # Safety
    ///
    /// The pointer must be a valid `MTLDevice` pointer.
    #[must_use]
    pub unsafe fn from_ptr_retained(ptr: *mut c_void) -> Option<Self> {
        if ptr.is_null() {
            return None;
        }
        let retained = unsafe { metal_device_retain(ptr) };
        NonNull::new(retained).map(|ptr| Self { ptr, owned: true })
    }

    /// Get the name of this device
    #[must_use]
    pub fn name(&self) -> String {
        unsafe {
            let name_ptr = metal_device_get_name(self.ptr.as_ptr());
            if name_ptr.is_null() {
                return String::new();
            }
            let name = CStr::from_ptr(name_ptr).to_string_lossy().into_owned();
            // `metal_device_get_name` returns a malloc'd copy we own.
            metal_string_free(name_ptr.cast_mut());
            name
        }
    }

    /// Create a command queue for this device
    #[must_use]
    pub fn create_command_queue(&self) -> Option<MetalCommandQueue> {
        let ptr = unsafe { metal_device_create_command_queue(self.ptr.as_ptr()) };
        NonNull::new(ptr).map(|ptr| MetalCommandQueue { ptr })
    }

    /// Create a shader library from source code
    ///
    /// # Errors
    /// Returns an error message if shader compilation fails.
    pub fn create_library_with_source(&self, source: &str) -> Result<MetalLibrary, String> {
        use std::ffi::CString;
        let source_c = CString::new(source).map_err(|e| e.to_string())?;
        let mut error_ptr: *const std::ffi::c_char = std::ptr::null();

        let ptr = unsafe {
            metal_device_create_library_with_source(
                self.ptr.as_ptr(),
                source_c.as_ptr(),
                &raw mut error_ptr,
            )
        };

        NonNull::new(ptr).map_or_else(
            || {
                let error = if error_ptr.is_null() {
                    "Unknown shader compilation error".to_string()
                } else {
                    let msg = unsafe { CStr::from_ptr(error_ptr).to_string_lossy().into_owned() };
                    // `errorOut` is a malloc'd copy we own.
                    unsafe { metal_string_free(error_ptr.cast_mut()) };
                    msg
                };
                Err(error)
            },
            |ptr| Ok(MetalLibrary { ptr }),
        )
    }

    /// Create a buffer
    ///
    /// Returns `None` if `length` exceeds `isize::MAX`: the Swift bridge takes
    /// a signed `Int`, so such a length would arrive as a negative size.
    #[must_use]
    pub fn create_buffer(&self, length: usize, options: ResourceOptions) -> Option<MetalBuffer> {
        let length = checked_swift_int(length)?;
        let ptr = unsafe { metal_device_create_buffer(self.ptr.as_ptr(), length, options.0) };
        NonNull::new(ptr).map(|ptr| MetalBuffer { ptr })
    }

    /// Create a buffer and populate it with initialized bytes.
    ///
    /// ```
    /// use screencapturekit::metal::{MetalDevice, Uniforms};
    ///
    /// let device = MetalDevice::system_default().expect("Metal device");
    /// let bytes = Uniforms::new(1920.0, 1080.0, 1280.0, 720.0).to_bytes();
    /// let buffer = device.create_buffer_with_bytes(&bytes).expect("buffer");
    /// assert_eq!(buffer.length(), Uniforms::BYTE_LEN);
    /// ```
    ///
    #[must_use]
    pub fn create_buffer_with_bytes(&self, data: &[u8]) -> Option<MetalBuffer> {
        let buffer =
            self.create_buffer(data.len(), ResourceOptions::CPU_CACHE_MODE_DEFAULT_CACHE)?;
        if data.is_empty() {
            return Some(buffer);
        }
        let destination = NonNull::new(buffer.contents().cast::<u8>())?;
        unsafe {
            std::ptr::copy_nonoverlapping(data.as_ptr(), destination.as_ptr(), data.len());
        }
        Some(buffer)
    }

    /// Create a buffer by copying the object representation of `data`.
    ///
    /// Prefer [`Self::create_buffer_with_bytes`] and an explicit encoder such
    /// as [`Uniforms::to_bytes`].
    ///
    /// # Safety
    ///
    /// Every byte in `T`, including padding, must be initialized. Its layout
    /// and native-endian representation must match the GPU consumer, and it
    /// must not contain references, pointers, or ownership-bearing handles
    /// that the GPU could interpret or outlive.
    #[must_use]
    pub unsafe fn create_buffer_with_data<T: Copy>(&self, data: &T) -> Option<MetalBuffer> {
        let size = std::mem::size_of::<T>();
        let bytes =
            unsafe { std::slice::from_raw_parts(std::ptr::from_ref(data).cast::<u8>(), size) };
        self.create_buffer_with_bytes(bytes)
    }

    /// Create a render pipeline state from a descriptor
    #[must_use]
    pub fn create_render_pipeline_state(
        &self,
        descriptor: &MetalRenderPipelineDescriptor,
    ) -> Option<MetalRenderPipelineState> {
        let ptr = unsafe {
            metal_device_create_render_pipeline_state(self.ptr.as_ptr(), descriptor.as_ptr())
        };
        NonNull::new(ptr).map(|ptr| MetalRenderPipelineState { ptr })
    }

    /// Get the raw pointer to the underlying `MTLDevice`
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }

    /// Borrow this device as an `apple_metal::MetalDevice` for interop with the
    /// lightweight `apple-metal` crate.
    ///
    /// The returned guard references the same `MTLDevice` instance and does
    /// not release it on drop, so it must not outlive this [`MetalDevice`].
    /// That is enforced by the borrow: `apple_metal::ManuallyDropDevice` has no
    /// lifetime of its own, so returning it directly let callers keep a
    /// dangling `MTLDevice` handle after the owner was dropped.
    ///
    /// Deref to reach the `apple_metal::MetalDevice` API.
    #[must_use]
    pub fn as_apple_metal(&self) -> BorrowedAppleMetalDevice<'_> {
        BorrowedAppleMetalDevice {
            inner: unsafe { apple_metal::MetalDevice::from_raw_borrowed(self.ptr.as_ptr()) },
            _owner: PhantomData,
        }
    }
}

/// An `apple_metal::MetalDevice` borrowed from an SCK [`MetalDevice`].
///
/// Returned by [`MetalDevice::as_apple_metal`]. Dereferences to
/// [`apple_metal::MetalDevice`] and does not release the underlying
/// `MTLDevice`; the borrow keeps the owning [`MetalDevice`] alive.
pub struct BorrowedAppleMetalDevice<'a> {
    inner: apple_metal::ManuallyDropDevice,
    _owner: PhantomData<&'a MetalDevice>,
}

impl std::ops::Deref for BorrowedAppleMetalDevice<'_> {
    type Target = apple_metal::MetalDevice;

    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl std::fmt::Debug for BorrowedAppleMetalDevice<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("BorrowedAppleMetalDevice").finish()
    }
}

impl Drop for MetalDevice {
    fn drop(&mut self) {
        if self.owned {
            unsafe { metal_device_release(self.ptr.as_ptr()) }
        }
    }
}

// SAFETY: `MTLDevice` is documented by Apple as thread-safe; the wrapper holds
// only a retained pointer with atomic ObjC reference counting.
unsafe impl Send for MetalDevice {}
unsafe impl Sync for MetalDevice {}

// MARK: - Metal Texture

/// A Metal texture
///
/// This is a wrapper around `MTLTexture` that provides safe access.
#[derive(Debug)]
pub struct MetalTexture {
    ptr: NonNull<c_void>,
}

impl MetalTexture {
    /// Get the width of this texture
    #[must_use]
    pub fn width(&self) -> usize {
        unsafe { metal_texture_get_width(self.ptr.as_ptr()) }
    }

    /// Get the height of this texture
    #[must_use]
    pub fn height(&self) -> usize {
        unsafe { metal_texture_get_height(self.ptr.as_ptr()) }
    }

    /// Get the pixel format of this texture
    #[allow(clippy::missing_errors_doc)]
    pub fn pixel_format(&self) -> Result<MetalPixelFormat, MetalError> {
        let raw = unsafe { metal_texture_get_pixel_format(self.ptr.as_ptr()) };
        MetalPixelFormat::from_raw(raw).ok_or(MetalError::UnknownPixelFormat { raw })
    }

    /// Get the raw pointer to the underlying `MTLTexture`
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Clone for MetalTexture {
    fn clone(&self) -> Self {
        let ptr = unsafe { metal_texture_retain(self.ptr.as_ptr()) };
        // `metal_texture_retain` is an Objective-C `retain`, which returns the
        // same (non-null) pointer for a live object. Fall back to `self.ptr`
        // rather than panicking on the unreachable null case (Clone must be
        // infallible).
        Self {
            ptr: NonNull::new(ptr).unwrap_or(self.ptr),
        }
    }
}

impl Drop for MetalTexture {
    fn drop(&mut self) {
        unsafe { metal_texture_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLTexture` is documented by Apple as thread-safe for the read-only
// access exposed here; the wrapper holds only a retained pointer with atomic
// ObjC reference counting.
unsafe impl Send for MetalTexture {}
unsafe impl Sync for MetalTexture {}

// MARK: - Metal Command Queue

/// A Metal command queue
#[derive(Debug)]
pub struct MetalCommandQueue {
    ptr: NonNull<c_void>,
}

impl MetalCommandQueue {
    /// Create a command buffer
    #[must_use]
    pub fn command_buffer(&self) -> Option<MetalCommandBuffer> {
        let ptr = unsafe { metal_command_queue_command_buffer(self.ptr.as_ptr()) };
        NonNull::new(ptr).map(|ptr| MetalCommandBuffer {
            ptr,
            state: Arc::new(Mutex::new(CommandBufferState::default())),
        })
    }

    /// Get the raw pointer to the underlying `MTLCommandQueue`
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalCommandQueue {
    fn drop(&mut self) {
        unsafe { metal_command_queue_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLCommandQueue` is documented by Apple as thread-safe; the wrapper
// holds only a retained pointer with atomic ObjC reference counting.
unsafe impl Send for MetalCommandQueue {}
unsafe impl Sync for MetalCommandQueue {}

// MARK: - Metal Library

/// A Metal shader library
#[derive(Debug)]
pub struct MetalLibrary {
    ptr: NonNull<c_void>,
}

impl MetalLibrary {
    /// Get a function from this library by name
    #[must_use]
    pub fn get_function(&self, name: &str) -> Option<MetalFunction> {
        use std::ffi::CString;
        let name_c = CString::new(name).ok()?;
        let ptr = unsafe { metal_library_get_function(self.ptr.as_ptr(), name_c.as_ptr()) };
        NonNull::new(ptr).map(|ptr| MetalFunction { ptr })
    }

    /// Get the raw pointer to the underlying `MTLLibrary`
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalLibrary {
    fn drop(&mut self) {
        unsafe { metal_library_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLLibrary` is documented by Apple as thread-safe; the wrapper holds
// only a retained pointer with atomic ObjC reference counting.
unsafe impl Send for MetalLibrary {}
unsafe impl Sync for MetalLibrary {}

// MARK: - Metal Function

/// A Metal shader function
#[derive(Debug)]
pub struct MetalFunction {
    ptr: NonNull<c_void>,
}

impl MetalFunction {
    /// Get the raw pointer to the underlying `MTLFunction`
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalFunction {
    fn drop(&mut self) {
        unsafe { metal_function_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLFunction` is documented by Apple as thread-safe; the wrapper holds
// only a retained pointer with atomic ObjC reference counting.
unsafe impl Send for MetalFunction {}
unsafe impl Sync for MetalFunction {}

// MARK: - Metal Buffer

/// A Metal buffer for vertex/uniform data
#[derive(Debug)]
pub struct MetalBuffer {
    ptr: NonNull<c_void>,
}

/// Resource options for buffer creation
#[derive(Debug, Clone, Copy, Default)]
pub struct ResourceOptions(u64);

impl ResourceOptions {
    /// CPU cache mode default, storage mode shared
    pub const CPU_CACHE_MODE_DEFAULT_CACHE: Self = Self(0);
    /// Storage mode shared (CPU and GPU can access)
    pub const STORAGE_MODE_SHARED: Self = Self(0);
    /// Storage mode managed (CPU writes, GPU reads)
    pub const STORAGE_MODE_MANAGED: Self = Self(1 << 4);
}

impl MetalBuffer {
    /// Get a pointer to the buffer contents
    #[must_use]
    pub fn contents(&self) -> *mut c_void {
        unsafe { metal_buffer_contents(self.ptr.as_ptr()) }
    }

    /// Get the length of the buffer in bytes
    #[must_use]
    pub fn length(&self) -> usize {
        unsafe { metal_buffer_length(self.ptr.as_ptr()) }
    }

    /// Notify that a range of the buffer was modified (for managed storage mode)
    ///
    /// The call is skipped when the range cannot be expressed as the Swift
    /// bridge's signed `Int` pair — Swift reconstructs `start ..< end` and
    /// traps on an overflowing or reversed range.
    pub fn did_modify_range(&self, range: std::ops::Range<usize>) {
        if range.end < range.start
            || checked_swift_int(range.start).is_none()
            || checked_swift_int(range.end).is_none()
        {
            return;
        }
        unsafe { metal_buffer_did_modify_range(self.ptr.as_ptr(), range.start, range.len()) }
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalBuffer {
    fn drop(&mut self) {
        unsafe { metal_buffer_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLBuffer` is documented by Apple as thread-safe. Note that `Sync`
// exposes `contents()` as a raw `*mut c_void`, not a Rust `&mut`; callers that
// write to the GPU buffer from multiple threads are responsible for their own
// synchronization (the standard GPU-programming contract).
unsafe impl Send for MetalBuffer {}
unsafe impl Sync for MetalBuffer {}

// MARK: - Metal Layer

/// A `CAMetalLayer` for rendering to a window
#[derive(Debug)]
pub struct MetalLayer {
    ptr: NonNull<c_void>,
}

impl MetalLayer {
    /// Create a new Metal layer
    ///
    /// # Panics
    /// Panics if layer creation fails (should not happen on macOS with Metal support).
    #[must_use]
    pub fn new() -> Self {
        let ptr = unsafe { metal_layer_create() };
        Self {
            ptr: NonNull::new(ptr).expect("metal_layer_create returned null"),
        }
    }

    /// Set the device for this layer
    pub fn set_device(&self, device: &MetalDevice) {
        unsafe { metal_layer_set_device(self.ptr.as_ptr(), device.as_ptr()) }
    }

    /// Set the pixel format
    pub fn set_pixel_format(&self, format: MTLPixelFormat) {
        unsafe { metal_layer_set_pixel_format(self.ptr.as_ptr(), format.raw()) }
    }

    /// Set the drawable size
    pub fn set_drawable_size(&self, width: f64, height: f64) {
        unsafe { metal_layer_set_drawable_size(self.ptr.as_ptr(), width, height) }
    }

    /// Set whether to present with transaction
    pub fn set_presents_with_transaction(&self, value: bool) {
        unsafe { metal_layer_set_presents_with_transaction(self.ptr.as_ptr(), value) }
    }

    /// Get the next drawable
    #[must_use]
    pub fn next_drawable(&self) -> Option<MetalDrawable> {
        let ptr = unsafe { metal_layer_next_drawable(self.ptr.as_ptr()) };
        NonNull::new(ptr).map(|ptr| MetalDrawable { ptr })
    }

    /// Get the raw pointer (for attaching to a view)
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Default for MetalLayer {
    fn default() -> Self {
        Self::new()
    }
}

impl Drop for MetalLayer {
    fn drop(&mut self) {
        unsafe { metal_layer_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Metal Drawable

/// A drawable from a Metal layer
#[derive(Debug)]
pub struct MetalDrawable {
    ptr: NonNull<c_void>,
}

impl MetalDrawable {
    /// Get the texture for this drawable
    ///
    /// # Panics
    /// Panics if the drawable has no texture (should not happen for valid drawables).
    #[must_use]
    pub fn texture(&self) -> MetalTexture {
        let ptr = unsafe { metal_drawable_texture(self.ptr.as_ptr()) };
        // Null-check the borrowed pointer BEFORE retaining it.
        let ptr = NonNull::new(ptr).expect("drawable texture is null");
        // Texture is borrowed from the drawable; retain so MetalTexture owns it.
        let retained = unsafe { metal_texture_retain(ptr.as_ptr()) };
        MetalTexture {
            ptr: NonNull::new(retained).unwrap_or(ptr),
        }
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalDrawable {
    fn drop(&mut self) {
        unsafe { metal_drawable_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Command Buffer

#[derive(Debug, Default)]
struct CommandBufferState {
    committed: bool,
    encoder_active: bool,
}

/// A Metal command buffer
#[derive(Debug)]
pub struct MetalCommandBuffer {
    ptr: NonNull<c_void>,
    state: Arc<Mutex<CommandBufferState>>,
}

impl MetalCommandBuffer {
    /// Create a render command encoder
    ///
    /// # Errors
    ///
    /// Returns an error after commit, while another encoder is active, or
    /// when native encoder creation fails.
    pub fn render_command_encoder(
        &self,
        render_pass: &MetalRenderPassDescriptor,
    ) -> Result<MetalRenderCommandEncoder, MetalError> {
        let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner);
        if state.committed {
            return Err(MetalError::CommandBufferAlreadyCommitted);
        }
        if state.encoder_active {
            return Err(MetalError::RenderEncoderAlreadyActive);
        }
        let ptr = unsafe {
            metal_command_buffer_render_command_encoder(self.ptr.as_ptr(), render_pass.as_ptr())
        };
        let ptr = NonNull::new(ptr).ok_or(MetalError::RenderEncoderCreationFailed)?;
        state.encoder_active = true;
        drop(state);
        Ok(MetalRenderCommandEncoder {
            ptr,
            state: Arc::new(RenderEncoderState {
                ended: Mutex::new(false),
                command: Arc::clone(&self.state),
            }),
        })
    }

    /// Present a drawable
    ///
    /// # Errors
    ///
    /// Returns an error if the command buffer was already committed.
    pub fn present_drawable(&self, drawable: &MetalDrawable) -> Result<(), MetalError> {
        let state = self.state.lock().unwrap_or_else(PoisonError::into_inner);
        if state.committed {
            return Err(MetalError::CommandBufferAlreadyCommitted);
        }
        unsafe { metal_command_buffer_present_drawable(self.ptr.as_ptr(), drawable.as_ptr()) }
        drop(state);
        Ok(())
    }

    /// Commit the command buffer
    ///
    /// # Errors
    ///
    /// Returns an error if it was already committed or an encoder is active.
    pub fn commit(&self) -> Result<(), MetalError> {
        let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner);
        if state.committed {
            return Err(MetalError::CommandBufferAlreadyCommitted);
        }
        if state.encoder_active {
            return Err(MetalError::CommandBufferHasActiveEncoder);
        }
        unsafe { metal_command_buffer_commit(self.ptr.as_ptr()) }
        state.committed = true;
        drop(state);
        Ok(())
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Clone for MetalCommandBuffer {
    fn clone(&self) -> Self {
        let ptr = unsafe { metal_command_buffer_retain(self.ptr.as_ptr()) };
        Self {
            ptr: NonNull::new(ptr).unwrap_or(self.ptr),
            state: Arc::clone(&self.state),
        }
    }
}

impl Drop for MetalCommandBuffer {
    fn drop(&mut self) {
        unsafe { metal_command_buffer_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Render Pass Descriptor

/// A render pass descriptor
#[derive(Debug)]
pub struct MetalRenderPassDescriptor {
    ptr: NonNull<c_void>,
}

/// Load action for render pass attachments
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLLoadAction {
    /// Don't care about existing contents
    DontCare = 0,
    /// Load existing contents
    Load = 1,
    /// Clear to a value
    #[default]
    Clear = 2,
}

/// Store action for render pass attachments
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLStoreAction {
    /// Don't care about storing
    DontCare = 0,
    /// Store the results
    #[default]
    Store = 1,
}

/// Pixel format
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLPixelFormat {
    /// Invalid format
    Invalid = 0,
    /// BGRA 8-bit unsigned normalized
    #[default]
    BGRA8Unorm = 80,
    /// BGR 10-bit, A 2-bit unsigned normalized
    BGR10A2Unorm = 94,
    /// R 8-bit unsigned normalized
    R8Unorm = 10,
    /// RG 8-bit unsigned normalized
    RG8Unorm = 30,
}

impl MTLPixelFormat {
    /// Get the raw value
    #[must_use]
    pub const fn raw(self) -> u64 {
        self as u64
    }
}

/// Vertex format for vertex attributes
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLVertexFormat {
    /// Invalid format
    Invalid = 0,
    /// Two 32-bit floats
    #[default]
    Float2 = 29,
    /// Three 32-bit floats
    Float3 = 30,
    /// Four 32-bit floats
    Float4 = 31,
}

impl MTLVertexFormat {
    /// Get the raw value
    #[must_use]
    pub const fn raw(self) -> u64 {
        self as u64
    }
}

/// Vertex step function
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLVertexStepFunction {
    /// Constant value (same for all vertices)
    Constant = 0,
    /// Step once per vertex (default)
    #[default]
    PerVertex = 1,
    /// Step once per instance
    PerInstance = 2,
}

impl MTLVertexStepFunction {
    /// Get the raw value
    #[must_use]
    pub const fn raw(self) -> u64 {
        self as u64
    }
}

/// Primitive type for drawing
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLPrimitiveType {
    /// Points
    Point = 0,
    /// Lines
    Line = 1,
    /// Line strip
    LineStrip = 2,
    /// Triangles
    #[default]
    Triangle = 3,
    /// Triangle strip
    TriangleStrip = 4,
}

impl MTLPrimitiveType {
    /// Get the raw value
    #[must_use]
    pub const fn raw(self) -> u64 {
        self as u64
    }
}

/// Blend operation
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLBlendOperation {
    /// Add source and destination
    #[default]
    Add = 0,
    /// Subtract destination from source
    Subtract = 1,
    /// Subtract source from destination
    ReverseSubtract = 2,
    /// Minimum of source and destination
    Min = 3,
    /// Maximum of source and destination
    Max = 4,
}

/// Blend factor
#[derive(Debug, Clone, Copy, Default)]
#[repr(u64)]
pub enum MTLBlendFactor {
    /// 0
    Zero = 0,
    /// 1
    #[default]
    One = 1,
    /// Source color
    SourceColor = 2,
    /// 1 - source color
    OneMinusSourceColor = 3,
    /// Source alpha
    SourceAlpha = 4,
    /// 1 - source alpha
    OneMinusSourceAlpha = 5,
    /// Destination color
    DestinationColor = 6,
    /// 1 - destination color
    OneMinusDestinationColor = 7,
    /// Destination alpha
    DestinationAlpha = 8,
    /// 1 - destination alpha
    OneMinusDestinationAlpha = 9,
}

impl MetalRenderPassDescriptor {
    /// Create a new render pass descriptor
    ///
    /// # Panics
    /// Panics if descriptor creation fails (should not happen).
    #[must_use]
    pub fn new() -> Self {
        let ptr = unsafe { metal_render_pass_descriptor_create() };
        Self {
            ptr: NonNull::new(ptr).expect("render pass descriptor create failed"),
        }
    }

    /// Set the texture for a color attachment
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_color_attachment_texture(
        &self,
        index: usize,
        texture: &MetalTexture,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pass_set_color_attachment_texture(
                self.ptr.as_ptr(),
                index,
                texture.as_ptr(),
            )
        };
        bridge_result(accepted, "set render-pass color texture")
    }

    /// Set the load action for a color attachment
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_color_attachment_load_action(
        &self,
        index: usize,
        action: MTLLoadAction,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pass_set_color_attachment_load_action(
                self.ptr.as_ptr(),
                index,
                action as u64,
            )
        };
        bridge_result(accepted, "set render-pass load action")
    }

    /// Set the store action for a color attachment
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_color_attachment_store_action(
        &self,
        index: usize,
        action: MTLStoreAction,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pass_set_color_attachment_store_action(
                self.ptr.as_ptr(),
                index,
                action as u64,
            )
        };
        bridge_result(accepted, "set render-pass store action")
    }

    /// Set the clear color for a color attachment
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_color_attachment_clear_color(
        &self,
        index: usize,
        r: f64,
        g: f64,
        b: f64,
        a: f64,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pass_set_color_attachment_clear_color(self.ptr.as_ptr(), index, r, g, b, a)
        };
        bridge_result(accepted, "set render-pass clear color")
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Default for MetalRenderPassDescriptor {
    fn default() -> Self {
        Self::new()
    }
}

impl Drop for MetalRenderPassDescriptor {
    fn drop(&mut self) {
        unsafe { metal_render_pass_descriptor_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Vertex Descriptor

/// A vertex descriptor for specifying vertex buffer layout
#[derive(Debug)]
pub struct MetalVertexDescriptor {
    ptr: NonNull<c_void>,
}

impl MetalVertexDescriptor {
    /// Create a new vertex descriptor
    ///
    /// # Panics
    /// Panics if descriptor creation fails (should not happen).
    #[must_use]
    pub fn new() -> Self {
        let ptr = unsafe { metal_vertex_descriptor_create() };
        Self {
            ptr: NonNull::new(ptr).expect("vertex descriptor create failed"),
        }
    }

    /// Set an attribute's format, offset, and buffer index
    ///
    /// # Errors
    ///
    /// Returns an error for an invalid attribute/buffer slot or an offset that
    /// cannot be represented by Swift's `Int`.
    pub fn set_attribute(
        &self,
        index: usize,
        format: MTLVertexFormat,
        offset: usize,
        buffer_index: usize,
    ) -> Result<(), MetalError> {
        let index = checked_slot("vertex attribute", index, MAX_VERTEX_ATTRIBUTES)?;
        let offset = checked_swift_value("vertex attribute offset", offset)?;
        let buffer_index = checked_slot("vertex buffer", buffer_index, MAX_BUFFER_BINDINGS)?;
        let accepted = unsafe {
            metal_vertex_descriptor_set_attribute(
                self.ptr.as_ptr(),
                index,
                format.raw(),
                offset,
                buffer_index,
            )
        };
        bridge_result(accepted, "set vertex attribute")
    }

    /// Set a buffer layout's stride and step function
    ///
    /// # Errors
    ///
    /// Returns an error for an invalid buffer slot or a stride that cannot be
    /// represented by Swift's `Int`.
    pub fn set_layout(
        &self,
        buffer_index: usize,
        stride: usize,
        step_function: MTLVertexStepFunction,
    ) -> Result<(), MetalError> {
        let buffer_index = checked_slot("vertex buffer", buffer_index, MAX_BUFFER_BINDINGS)?;
        let stride = checked_swift_value("vertex stride", stride)?;
        let accepted = unsafe {
            metal_vertex_descriptor_set_layout(
                self.ptr.as_ptr(),
                buffer_index,
                stride,
                step_function.raw(),
            )
        };
        bridge_result(accepted, "set vertex layout")
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Default for MetalVertexDescriptor {
    fn default() -> Self {
        Self::new()
    }
}

impl Drop for MetalVertexDescriptor {
    fn drop(&mut self) {
        unsafe { metal_vertex_descriptor_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Render Pipeline Descriptor

/// A render pipeline descriptor
#[derive(Debug)]
pub struct MetalRenderPipelineDescriptor {
    ptr: NonNull<c_void>,
}

impl MetalRenderPipelineDescriptor {
    /// Create a new render pipeline descriptor
    ///
    /// # Panics
    /// Panics if descriptor creation fails (should not happen).
    #[must_use]
    pub fn new() -> Self {
        let ptr = unsafe { metal_render_pipeline_descriptor_create() };
        Self {
            ptr: NonNull::new(ptr).expect("render pipeline descriptor create failed"),
        }
    }

    /// Set the vertex function
    pub fn set_vertex_function(&self, function: &MetalFunction) {
        unsafe {
            metal_render_pipeline_descriptor_set_vertex_function(
                self.ptr.as_ptr(),
                function.as_ptr(),
            );
        }
    }

    /// Set the fragment function
    pub fn set_fragment_function(&self, function: &MetalFunction) {
        unsafe {
            metal_render_pipeline_descriptor_set_fragment_function(
                self.ptr.as_ptr(),
                function.as_ptr(),
            );
        }
    }

    /// Set the vertex descriptor for vertex buffer layout
    pub fn set_vertex_descriptor(&self, descriptor: &MetalVertexDescriptor) {
        unsafe {
            metal_render_pipeline_descriptor_set_vertex_descriptor(
                self.ptr.as_ptr(),
                descriptor.as_ptr(),
            );
        }
    }

    /// Set color attachment pixel format
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_color_attachment_pixel_format(
        &self,
        index: usize,
        format: MTLPixelFormat,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pipeline_descriptor_set_color_attachment_pixel_format(
                self.ptr.as_ptr(),
                index,
                format.raw(),
            )
        };
        bridge_result(accepted, "set pipeline color format")
    }

    /// Set blending enabled for a color attachment
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_blending_enabled(&self, index: usize, enabled: bool) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pipeline_descriptor_set_blending_enabled(self.ptr.as_ptr(), index, enabled)
        };
        bridge_result(accepted, "set pipeline blending")
    }

    /// Set blend operations
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_blend_operations(
        &self,
        index: usize,
        rgb_op: MTLBlendOperation,
        alpha_op: MTLBlendOperation,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pipeline_descriptor_set_blend_operations(
                self.ptr.as_ptr(),
                index,
                rgb_op as u64,
                alpha_op as u64,
            )
        };
        bridge_result(accepted, "set pipeline blend operations")
    }

    /// Set blend factors
    ///
    /// # Errors
    ///
    /// Returns an error when `index` is not a native color-attachment slot.
    pub fn set_blend_factors(
        &self,
        index: usize,
        src_rgb: MTLBlendFactor,
        dst_rgb: MTLBlendFactor,
        src_alpha: MTLBlendFactor,
        dst_alpha: MTLBlendFactor,
    ) -> Result<(), MetalError> {
        let index = checked_slot("color attachment", index, MAX_COLOR_ATTACHMENTS)?;
        let accepted = unsafe {
            metal_render_pipeline_descriptor_set_blend_factors(
                self.ptr.as_ptr(),
                index,
                src_rgb as u64,
                dst_rgb as u64,
                src_alpha as u64,
                dst_alpha as u64,
            )
        };
        bridge_result(accepted, "set pipeline blend factors")
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Default for MetalRenderPipelineDescriptor {
    fn default() -> Self {
        Self::new()
    }
}

impl Drop for MetalRenderPipelineDescriptor {
    fn drop(&mut self) {
        unsafe { metal_render_pipeline_descriptor_release(self.ptr.as_ptr()) }
    }
}

// MARK: - Render Pipeline State

/// A compiled render pipeline state
#[derive(Debug)]
pub struct MetalRenderPipelineState {
    ptr: NonNull<c_void>,
}

impl MetalRenderPipelineState {
    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Drop for MetalRenderPipelineState {
    fn drop(&mut self) {
        unsafe { metal_render_pipeline_state_release(self.ptr.as_ptr()) }
    }
}

// SAFETY: `MTLRenderPipelineState` is documented by Apple as thread-safe; the
// wrapper holds only a retained pointer with atomic ObjC reference counting.
unsafe impl Send for MetalRenderPipelineState {}
unsafe impl Sync for MetalRenderPipelineState {}

// MARK: - Render Command Encoder

#[derive(Debug)]
struct RenderEncoderState {
    ended: Mutex<bool>,
    command: Arc<Mutex<CommandBufferState>>,
}

impl RenderEncoderState {
    fn with_active(
        &self,
        operation: impl FnOnce() -> Result<(), MetalError>,
    ) -> Result<(), MetalError> {
        let ended = self.ended.lock().unwrap_or_else(PoisonError::into_inner);
        if *ended {
            return Err(MetalError::RenderEncoderEnded);
        }
        let result = operation();
        drop(ended);
        result
    }

    fn end(&self, encoder: NonNull<c_void>) -> Result<(), MetalError> {
        let mut ended = self.ended.lock().unwrap_or_else(PoisonError::into_inner);
        if *ended {
            return Err(MetalError::RenderEncoderEnded);
        }
        unsafe { metal_render_encoder_end_encoding(encoder.as_ptr()) }
        *ended = true;
        drop(ended);
        let mut command = self.command.lock().unwrap_or_else(PoisonError::into_inner);
        command.encoder_active = false;
        drop(command);
        Ok(())
    }

    fn end_on_drop(&self, encoder: NonNull<c_void>) {
        let mut ended = self.ended.lock().unwrap_or_else(PoisonError::into_inner);
        if *ended {
            return;
        }
        unsafe { metal_render_encoder_end_encoding(encoder.as_ptr()) }
        *ended = true;
        drop(ended);
        let mut command = self.command.lock().unwrap_or_else(PoisonError::into_inner);
        command.encoder_active = false;
        drop(command);
    }
}

/// A render command encoder
///
/// Dropping the final retained handle ends encoding automatically so the
/// parent command buffer cannot be left permanently uncommittable.
#[derive(Debug)]
pub struct MetalRenderCommandEncoder {
    ptr: NonNull<c_void>,
    state: Arc<RenderEncoderState>,
}

impl MetalRenderCommandEncoder {
    /// Set the render pipeline state
    ///
    /// # Errors
    ///
    /// Returns an error after encoding has ended.
    pub fn set_render_pipeline_state(
        &self,
        pipeline: &MetalRenderPipelineState,
    ) -> Result<(), MetalError> {
        self.state.with_active(|| {
            unsafe {
                metal_render_encoder_set_pipeline_state(self.ptr.as_ptr(), pipeline.as_ptr());
            }
            Ok(())
        })
    }

    /// Set a vertex buffer
    ///
    /// # Errors
    ///
    /// Returns an error after encoding has ended or for an invalid offset or
    /// buffer binding index.
    pub fn set_vertex_buffer(
        &self,
        buffer: &MetalBuffer,
        offset: usize,
        index: usize,
    ) -> Result<(), MetalError> {
        self.state.with_active(|| {
            let offset = checked_swift_value("vertex buffer offset", offset)?;
            let index = checked_slot("vertex buffer", index, MAX_BUFFER_BINDINGS)?;
            let accepted = unsafe {
                metal_render_encoder_set_vertex_buffer(
                    self.ptr.as_ptr(),
                    buffer.as_ptr(),
                    offset,
                    index,
                )
            };
            bridge_result(accepted, "set vertex buffer")
        })
    }

    /// Set a fragment buffer
    ///
    /// # Errors
    ///
    /// Returns an error after encoding has ended or for an invalid offset or
    /// buffer binding index.
    pub fn set_fragment_buffer(
        &self,
        buffer: &MetalBuffer,
        offset: usize,
        index: usize,
    ) -> Result<(), MetalError> {
        self.state.with_active(|| {
            let offset = checked_swift_value("fragment buffer offset", offset)?;
            let index = checked_slot("fragment buffer", index, MAX_BUFFER_BINDINGS)?;
            let accepted = unsafe {
                metal_render_encoder_set_fragment_buffer(
                    self.ptr.as_ptr(),
                    buffer.as_ptr(),
                    offset,
                    index,
                )
            };
            bridge_result(accepted, "set fragment buffer")
        })
    }

    /// Set a fragment texture
    ///
    /// # Errors
    ///
    /// Returns an error after encoding has ended or for an invalid texture
    /// binding index.
    pub fn set_fragment_texture(
        &self,
        texture: &MetalTexture,
        index: usize,
    ) -> Result<(), MetalError> {
        self.state.with_active(|| {
            let index = checked_slot("fragment texture", index, MAX_TEXTURE_BINDINGS)?;
            let accepted = unsafe {
                metal_render_encoder_set_fragment_texture(
                    self.ptr.as_ptr(),
                    texture.as_ptr(),
                    index,
                )
            };
            bridge_result(accepted, "set fragment texture")
        })
    }

    /// Draw primitives
    ///
    /// # Errors
    ///
    /// Returns an error after encoding has ended or when the vertex range
    /// cannot be represented by Swift's `Int`.
    pub fn draw_primitives(
        &self,
        primitive_type: MTLPrimitiveType,
        vertex_start: usize,
        vertex_count: usize,
    ) -> Result<(), MetalError> {
        self.state.with_active(|| {
            let vertex_start = checked_swift_value("vertex start", vertex_start)?;
            let vertex_count = checked_swift_value("vertex count", vertex_count)?;
            let accepted = unsafe {
                metal_render_encoder_draw_primitives(
                    self.ptr.as_ptr(),
                    primitive_type.raw(),
                    vertex_start,
                    vertex_count,
                )
            };
            bridge_result(accepted, "draw primitives")
        })
    }

    /// End encoding
    ///
    /// # Errors
    ///
    /// Returns an error if encoding already ended through this handle or one
    /// of its retained clones.
    pub fn end_encoding(&self) -> Result<(), MetalError> {
        self.state.end(self.ptr)
    }

    /// Get the raw pointer
    #[must_use]
    pub fn as_ptr(&self) -> *mut c_void {
        self.ptr.as_ptr()
    }
}

impl Clone for MetalRenderCommandEncoder {
    fn clone(&self) -> Self {
        let ptr = unsafe { metal_render_encoder_retain(self.ptr.as_ptr()) };
        Self {
            ptr: NonNull::new(ptr).unwrap_or(self.ptr),
            state: Arc::clone(&self.state),
        }
    }
}

impl Drop for MetalRenderCommandEncoder {
    fn drop(&mut self) {
        if Arc::strong_count(&self.state) == 1 {
            self.state.end_on_drop(self.ptr);
        }
        unsafe { metal_render_encoder_release(self.ptr.as_ptr()) }
    }
}

// MARK: - IOSurface Metal Extension

/// Result of creating Metal textures from an `IOSurface`
pub type MetalCapturedTextures = CapturedTextures<MetalTexture>;

/// Extension trait that adds Metal-related convenience methods to
/// `apple_cf::iosurface::IOSurface`.
///
/// It's a trait (rather than inherent impls) because Rust's orphan rules
/// forbid inherent impls on out-of-crate types.
///
/// Bring this trait into scope to call `info()`, `texture_params()`,
/// `metal_textures(...)`, `create_metal_textures(...)`, etc. on any
/// `IOSurface`.
pub trait IOSurfaceMetalExt {
    /// Detailed information about this surface for Metal texture creation.
    fn info(&self) -> IOSurfaceInfo;
    /// Whether this surface uses a YCbCr biplanar format.
    fn is_ycbcr_biplanar(&self) -> bool;
    /// Texture params (one per plane) needed to create matching Metal textures.
    fn texture_params(&self) -> Vec<TextureParams>;
    /// Generic texture creation via user-supplied closure.
    fn metal_textures<T, F>(&self, create_texture: F) -> Option<CapturedTextures<T>>
    where
        F: Fn(&TextureParams, *const c_void) -> Option<T>;
    /// Convenience: create concrete `MetalTexture`s using a `MetalDevice`.
    fn create_metal_textures(&self, device: &MetalDevice) -> Option<MetalCapturedTextures>;
}

impl IOSurfaceMetalExt for IOSurface {
    /// Get detailed information about this `IOSurface` for Metal texture creation
    fn info(&self) -> IOSurfaceInfo {
        let width = self.width();
        let height = self.height();
        let bytes_per_row = self.bytes_per_row();
        let pix_format: FourCharCode = self.pixel_format().into();
        let plane_count = self.plane_count();

        let planes = if plane_count > 0 {
            (0..plane_count)
                .map(|i| PlaneInfo {
                    index: i,
                    width: self.width_of_plane(i),
                    height: self.height_of_plane(i),
                    bytes_per_row: self.bytes_per_row_of_plane(i),
                })
                .collect()
        } else {
            vec![]
        };

        IOSurfaceInfo {
            width,
            height,
            bytes_per_row,
            pixel_format: pix_format,
            plane_count,
            planes,
        }
    }

    /// Check if this `IOSurface` uses a YCbCr biplanar format
    fn is_ycbcr_biplanar(&self) -> bool {
        pixel_format::is_ycbcr_biplanar(self.pixel_format())
    }

    /// Get texture parameters for creating Metal textures from this `IOSurface`
    ///
    /// Returns texture parameters for each plane needed to render this surface.
    /// - Single-plane formats (BGRA, L10R): Returns 1 texture param
    /// - YCbCr biplanar formats: Returns 2 texture params (Y and `CbCr` planes)
    fn texture_params(&self) -> Vec<TextureParams> {
        let pix_format: FourCharCode = self.pixel_format().into();
        let plane_count = self.plane_count();

        if pix_format == pixel_format::BGRA {
            vec![TextureParams {
                width: self.width(),
                height: self.height(),
                format: MetalPixelFormat::BGRA8Unorm,
                plane: 0,
            }]
        } else if pix_format == pixel_format::L10R {
            vec![TextureParams {
                width: self.width(),
                height: self.height(),
                format: MetalPixelFormat::BGR10A2Unorm,
                plane: 0,
            }]
        } else if pixel_format::is_ycbcr_biplanar(pix_format) && plane_count >= 2 {
            vec![
                // Plane 0: Y (luminance) - R8Unorm
                TextureParams {
                    width: self.width_of_plane(0),
                    height: self.height_of_plane(0),
                    format: MetalPixelFormat::R8Unorm,
                    plane: 0,
                },
                // Plane 1: CbCr (chrominance) - RG8Unorm
                TextureParams {
                    width: self.width_of_plane(1),
                    height: self.height_of_plane(1),
                    format: MetalPixelFormat::RG8Unorm,
                    plane: 1,
                },
            ]
        } else {
            // Fallback to BGRA
            vec![TextureParams {
                width: self.width(),
                height: self.height(),
                format: MetalPixelFormat::BGRA8Unorm,
                plane: 0,
            }]
        }
    }

    /// Create Metal textures from this `IOSurface` using a closure
    ///
    /// This is a zero-copy operation - the textures share memory with the `IOSurface`.
    ///
    /// The closure receives `TextureParams` and the raw `IOSurfaceRef` pointer,
    /// and should return the created texture.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use screencapturekit::cm::IOSurface;
    /// use screencapturekit::metal::IOSurfaceMetalExt;
    /// use std::ffi::c_void;
    ///
    /// fn example(surface: &IOSurface) {
    ///     let textures = surface.metal_textures(|params, _iosurface_ptr| {
    ///         // Create Metal texture using params.width, params.height, params.format
    ///         // Return Some(texture) or None
    ///         Some(()) // placeholder
    ///     });
    ///
    ///     if let Some(textures) = textures {
    ///         if textures.is_ycbcr() {
    ///             // Use YCbCr shader with plane0 (Y) and plane1 (CbCr)
    ///         }
    ///     }
    /// }
    /// ```
    ///
    /// # Safety
    ///
    /// The closure receives a raw `IOSurfaceRef` pointer. The pointer is valid
    /// for the duration of the closure call.
    fn metal_textures<T, F>(&self, create_texture: F) -> Option<CapturedTextures<T>>
    where
        F: Fn(&TextureParams, *const c_void) -> Option<T>,
    {
        let width = self.width();
        let height = self.height();
        let pix_format: FourCharCode = self.pixel_format().into();

        if width == 0 || height == 0 {
            return None;
        }

        let iosurface_ptr = self.as_ptr();
        let params = self.texture_params();

        if params.len() == 1 {
            // Single-plane format
            let texture = create_texture(&params[0], iosurface_ptr)?;
            Some(CapturedTextures {
                plane0: texture,
                plane1: None,
                pixel_format: pix_format,
                width,
                height,
            })
        } else if params.len() >= 2 {
            // YCbCr biplanar format
            let y_texture = create_texture(&params[0], iosurface_ptr)?;
            let uv_texture = create_texture(&params[1], iosurface_ptr)?;
            Some(CapturedTextures {
                plane0: y_texture,
                plane1: Some(uv_texture),
                pixel_format: pix_format,
                width,
                height,
            })
        } else {
            None
        }
    }

    /// Create Metal textures from this `IOSurface` using the provided device
    ///
    /// This is a zero-copy operation - the textures share memory with the `IOSurface`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use screencapturekit::metal::{IOSurfaceMetalExt, MetalDevice};
    /// use screencapturekit::cm::IOSurface;
    ///
    /// fn example(surface: &IOSurface) {
    ///     let device = MetalDevice::system_default().expect("No Metal device");
    ///     if let Some(textures) = surface.create_metal_textures(&device) {
    ///         if textures.is_ycbcr() {
    ///             // Use YCbCr shader with plane0 (Y) and plane1 (CbCr)
    ///         }
    ///     }
    /// }
    /// ```
    fn create_metal_textures(&self, device: &MetalDevice) -> Option<MetalCapturedTextures> {
        let width = self.width();
        let height = self.height();
        let pix_format: FourCharCode = self.pixel_format().into();

        if width == 0 || height == 0 {
            return None;
        }

        let params = self.texture_params();

        if params.len() == 1 {
            // Single-plane format
            let texture = create_texture_for_plane(self, device, &params[0])?;
            Some(CapturedTextures {
                plane0: texture,
                plane1: None,
                pixel_format: pix_format,
                width,
                height,
            })
        } else if params.len() >= 2 {
            // YCbCr biplanar format
            let y_texture = create_texture_for_plane(self, device, &params[0])?;
            let uv_texture = create_texture_for_plane(self, device, &params[1])?;
            Some(CapturedTextures {
                plane0: y_texture,
                plane1: Some(uv_texture),
                pixel_format: pix_format,
                width,
                height,
            })
        } else {
            None
        }
    }
}

/// Private helper used by `create_metal_textures` to build a `MetalTexture`
/// for one plane of the surface. Was previously an inherent method on
/// `IOSurface`; lives here as a free function now that `IOSurface` is
/// defined in `apple-cf`.
fn create_texture_for_plane(
    surface: &IOSurface,
    device: &MetalDevice,
    params: &TextureParams,
) -> Option<MetalTexture> {
    // The Swift bridge takes `Int`; a plane/extent above `isize::MAX` would
    // arrive negative and index out of bounds inside Metal.
    checked_swift_int(params.plane)?;
    checked_swift_int(params.width)?;
    checked_swift_int(params.height)?;
    let ptr = unsafe {
        metal_create_texture_from_iosurface(
            device.as_ptr(),
            surface.as_ptr(),
            params.plane,
            params.width,
            params.height,
            params.format.raw(),
        )
    };
    NonNull::new(ptr).map(|ptr| MetalTexture { ptr })
}

/// Reject `usize` values the Swift bridge cannot represent.
///
/// Every size/index parameter crosses the boundary as Swift's signed `Int`.
/// The two types are the same width, so anything above `isize::MAX` silently
/// becomes a negative length or index on the Swift side.
const fn checked_swift_int(value: usize) -> Option<usize> {
    if value > isize::MAX as usize {
        None
    } else {
        Some(value)
    }
}

const MAX_COLOR_ATTACHMENTS: usize = 8;
const MAX_VERTEX_ATTRIBUTES: usize = 31;
const MAX_BUFFER_BINDINGS: usize = 31;
const MAX_TEXTURE_BINDINGS: usize = 128;

fn checked_swift_value(argument: &'static str, value: usize) -> Result<usize, MetalError> {
    checked_swift_int(value).ok_or(MetalError::SwiftIntOverflow { argument, value })
}

fn checked_slot(
    argument: &'static str,
    index: usize,
    max_exclusive: usize,
) -> Result<usize, MetalError> {
    let index = checked_swift_value(argument, index)?;
    if index >= max_exclusive {
        Err(MetalError::IndexOutOfRange {
            argument,
            index,
            max_exclusive,
        })
    } else {
        Ok(index)
    }
}

fn bridge_result(accepted: bool, operation: &'static str) -> Result<(), MetalError> {
    if accepted {
        Ok(())
    } else {
        Err(MetalError::NativeCallRejected { operation })
    }
}

// MARK: - Autorelease Pool

#[link(name = "Foundation", kind = "framework")]
extern "C" {
    fn objc_autoreleasePoolPush() -> *mut c_void;
    fn objc_autoreleasePoolPop(pool: *mut c_void);
}

/// RAII guard that pops the pushed autorelease pool on drop, including while
/// unwinding.
struct AutoreleasePoolGuard {
    pool: *mut c_void,
}

impl Drop for AutoreleasePoolGuard {
    fn drop(&mut self) {
        unsafe { objc_autoreleasePoolPop(self.pool) }
    }
}

/// Execute a closure within an autorelease pool
///
/// This is equivalent to `@autoreleasepool { ... }` in Objective-C/Swift.
/// Use this when running code that creates temporary Objective-C objects
/// that need to be released promptly.
///
/// The pool is popped by an RAII guard, so it is balanced even if `f` panics.
/// Leaking the push would corrupt the thread's pool stack for every later
/// pool on that thread, not just this one.
///
/// # Example
///
/// ```no_run
/// use screencapturekit::metal::autoreleasepool;
///
/// autoreleasepool(|| {
///     // Code that creates temporary Objective-C objects
///     println!("Inside autorelease pool");
/// });
/// ```
pub fn autoreleasepool<F, R>(f: F) -> R
where
    F: FnOnce() -> R,
{
    let _guard = AutoreleasePoolGuard {
        pool: unsafe { objc_autoreleasePoolPush() },
    };
    f()
}

// MARK: - NSView Helpers

/// Set up an `NSView` for Metal rendering
///
/// This sets `wantsLayer = YES` and assigns the Metal layer to the view.
///
/// # Safety
///
/// The `view` pointer must be a valid `NSView` pointer.
///
/// # Example
///
/// ```no_run
/// use screencapturekit::metal::{setup_metal_view, MetalLayer};
/// use std::ffi::c_void;
///
/// fn example(ns_view: *mut c_void) {
///     let layer = MetalLayer::new();
///     unsafe { setup_metal_view(ns_view, &layer); }
/// }
/// ```
pub unsafe fn setup_metal_view(view: *mut c_void, layer: &MetalLayer) {
    unsafe {
        nsview_set_wants_layer(view);
        nsview_set_layer(view, layer.as_ptr());
    }
}