graphics.rs

use crate::color::{ColorMode, extract_color_with_mode};
use crate::glfw::GlfwContext;
use crate::input;
use crate::math::{extract_vec2, extract_vec3, extract_vec4};
use bevy::{
    color::{ColorToPacked, LinearRgba, Srgba},
    math::{Affine3A, Mat4, Vec3, Vec4},
    prelude::Entity,
    render::render_resource::{Extent3d, TextureFormat},
};
use processing::prelude::*;
use pyo3::{
    exceptions::{PyRuntimeError, PyValueError},
    prelude::*,
    types::{PyDict, PyList, PyTuple},
};
use std::sync::Mutex;

#[cfg(feature = "cuda")]
use crate::cuda::CudaImage;

/// Flatten `*args` of numbers (or a single list/tuple of numbers) into a `Vec<f32>`.
fn flatten_floats(args: &Bound<'_, PyTuple>) -> PyResult<Vec<f32>> {
    if args.len() == 1
        && let Ok(seq) = args.get_item(0)?.extract::<Vec<f32>>()
    {
        return Ok(seq);
    }
    let mut out = Vec::with_capacity(args.len());
    for item in args.iter() {
        out.push(item.extract::<f32>()?);
    }
    Ok(out)
}

/// Build a Python list of `Color` objects from linear-RGBA pixels.
fn pixels_to_pylist(py: Python<'_>, pixels: &[LinearRgba]) -> PyResult<Py<PyList>> {
    let colors = pixels
        .iter()
        .map(|p| crate::color::PyColor(bevy::prelude::Color::LinearRgba(*p)));
    Ok(PyList::new(py, colors)?.unbind())
}

/// Convert a Python sequence of colors (as returned by `load_pixels()`, or
/// individual `Color`/`[r,g,b,a]` values) into linear-RGBA pixels.
fn pyseq_to_pixels(seq: &Bound<'_, PyAny>) -> PyResult<Vec<LinearRgba>> {
    let mut out = Vec::with_capacity(seq.len().unwrap_or(0));
    for item in seq.try_iter()? {
        let item = item?;
        let color = if let Ok(c) = item.extract::<crate::color::PyColor>() {
            c.0
        } else if let Ok(rgba) = item.extract::<[f32; 4]>() {
            bevy::prelude::Color::LinearRgba(LinearRgba::new(rgba[0], rgba[1], rgba[2], rgba[3]))
        } else if let Ok(rgb) = item.extract::<[f32; 3]>() {
            bevy::prelude::Color::LinearRgba(LinearRgba::new(rgb[0], rgb[1], rgb[2], 1.0))
        } else {
            return Err(PyValueError::new_err(
                "pixels must contain Color values or [r, g, b, (a)] sequences",
            ));
        };
        out.push(LinearRgba::from(color));
    }
    Ok(out)
}

/// Resolve the sequence `update_pixels()` should write: an explicit argument if
/// given, otherwise the buffer cached by `load_pixels()`.
fn resolve_pixels_arg<'py>(
    py: Python<'py>,
    pixels: Option<&Bound<'py, PyAny>>,
    cache: &Mutex<Option<Py<PyList>>>,
) -> PyResult<Bound<'py, PyAny>> {
    match pixels {
        Some(p) => Ok(p.clone()),
        None => {
            let cached = cache.lock().unwrap().as_ref().map(|l| l.clone_ref(py));
            match cached {
                Some(list) => Ok(list.into_bound(py).into_any()),
                None => Err(PyRuntimeError::new_err(
                    "update_pixels() called before load_pixels()",
                )),
            }
        }
    }
}

fn rt_err(e: impl std::fmt::Display) -> PyErr {
    PyRuntimeError::new_err(format!("{e}"))
}

/// Composite mode code for `mask()` (see `filters/composite.wgsl`).
const COMPOSITE_MODE_MASK: u32 = 10;
/// Composite mode code for `copy()` — REPLACE (matches `BlendMode::Replace`).
const COMPOSITE_MODE_REPLACE: u32 = 9;

/// Normalize a pixel rect `(x, y, w, h)` to uv-space `(x0, y0, x1, y1)`; `None`
/// means the full `(0, 0, 1, 1)` extent.
fn normalize_rect(rect: Option<[f32; 4]>, w: f32, h: f32) -> [f32; 4] {
    match rect {
        None => [0.0, 0.0, 1.0, 1.0],
        Some([x, y, rw, rh]) => [x / w, y / h, (x + rw) / w, (y + rh) / h],
    }
}

/// Normalize a source pixel rect against the source image's own dimensions.
fn normalize_src_rect(entity: Entity, rect: Option<[f32; 4]>) -> PyResult<[f32; 4]> {
    match rect {
        None => Ok([0.0, 0.0, 1.0, 1.0]),
        Some(r) => {
            let (w, h) = image_size(entity).map_err(rt_err)?;
            Ok(normalize_rect(Some(r), w as f32, h as f32))
        }
    }
}

/// Run the built-in composite filter: blend the `src` texture into the `dst`
/// graphics target using `mode`, with normalized src/dst rects. This is the
/// shader-based composite pass shared by `copy`/`blend`/`mask`.
fn composite_apply(
    dst: Entity,
    src: Entity,
    mode: u32,
    src_rect: [f32; 4],
    dst_rect: [f32; 4],
    opacity: f32,
) -> PyResult<()> {
    use shader_value::ShaderValue;
    let filter = filter_composite().map_err(rt_err)?;
    filter_set(filter, "src", ShaderValue::Texture(src)).map_err(rt_err)?;
    filter_set(filter, "mode", ShaderValue::UInt(mode)).map_err(rt_err)?;
    filter_set(filter, "opacity", ShaderValue::Float(opacity)).map_err(rt_err)?;
    filter_set(filter, "src_rect", ShaderValue::Float4(src_rect)).map_err(rt_err)?;
    filter_set(filter, "dst_rect", ShaderValue::Float4(dst_rect)).map_err(rt_err)?;
    graphics_apply_filter(dst, filter).map_err(rt_err)
}

/// Write raw sRGB RGBA bytes to a PNG file on disk.
fn write_png_file(path: &str, width: u32, height: u32, rgba: &[u8]) -> PyResult<()> {
    let lower = path.to_lowercase();
    if !lower.ends_with(".png") {
        return Err(PyValueError::new_err(format!(
            "save() currently supports only .png files, got {path:?}"
        )));
    }
    let file = std::fs::File::create(path)
        .map_err(|e| PyRuntimeError::new_err(format!("create {path}: {e}")))?;
    let writer = std::io::BufWriter::new(file);
    let mut encoder = png::Encoder::new(writer, width, height);
    encoder.set_color(png::ColorType::Rgba);
    encoder.set_depth(png::BitDepth::Eight);
    encoder.set_source_srgb(png::SrgbRenderingIntent::Perceptual);
    let mut writer = encoder
        .write_header()
        .map_err(|e| PyRuntimeError::new_err(format!("PNG header: {e}")))?;
    writer
        .write_image_data(rgba)
        .map_err(|e| PyRuntimeError::new_err(format!("PNG write: {e}")))
}

/// Parse Processing-style `applyMatrix`/`setMatrix` arguments into an `Affine3A`:
/// 6 values for a 2D affine (`n00 n01 n02 n10 n11 n12`) or 16 values for a full
/// 3D matrix in row-major order (matching Processing; glam is column-major).
fn affine_from_matrix_args(args: &Bound<'_, PyTuple>) -> PyResult<Affine3A> {
    let v = flatten_floats(args)?;
    let mat = match v.len() {
        6 => Mat4::from_cols_array(&[
            v[0], v[3], 0.0, 0.0, //
            v[1], v[4], 0.0, 0.0, //
            0.0, 0.0, 1.0, 0.0, //
            v[2], v[5], 0.0, 1.0,
        ]),
        16 => {
            let mut arr = [0.0f32; 16];
            arr.copy_from_slice(&v);
            Mat4::from_cols_array(&arr).transpose()
        }
        n => {
            return Err(PyValueError::new_err(format!(
                "matrix expects 6 (2D) or 16 (3D) values, got {n}"
            )));
        }
    };
    Ok(Affine3A::from_mat4(mat))
}

#[cfg(feature = "cuda")]
fn cuda_import_from_interface(
    entity: bevy::prelude::Entity,
    obj: &pyo3::Bound<'_, pyo3::PyAny>,
) -> PyResult<()> {
    let interface = obj
        .getattr("__cuda_array_interface__")?
        .cast_into::<PyDict>()?;

    let data_tuple: (u64, bool) = interface
        .get_item("data")?
        .ok_or_else(|| PyRuntimeError::new_err("missing 'data' in __cuda_array_interface__"))?
        .extract()?;
    let src_ptr = data_tuple.0;

    let shape: Vec<usize> = interface
        .get_item("shape")?
        .ok_or_else(|| PyRuntimeError::new_err("missing 'shape' in __cuda_array_interface__"))?
        .extract()?;

    let typestr: String = interface
        .get_item("typestr")?
        .ok_or_else(|| PyRuntimeError::new_err("missing 'typestr' in __cuda_array_interface__"))?
        .extract()?;

    let elem_size = processing_cuda::elem_size_for_typestr(&typestr)
        .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
    let total_elements: usize = shape.iter().product();
    let byte_size = (total_elements * elem_size) as u64;

    processing_cuda::cuda_import(entity, src_ptr, byte_size)
        .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
}

#[pyclass(name = "BlendMode", from_py_object)]
#[derive(Clone)]
pub struct PyBlendMode {
    pub(crate) blend_state: Option<bevy::render::render_resource::BlendState>,
    name: Option<&'static str>,
}

impl PyBlendMode {
    pub(crate) fn from_preset(mode: BlendMode) -> Self {
        Self {
            blend_state: mode.to_blend_state(),
            name: Some(mode.name()),
        }
    }

    /// The composite-shader mode code (the `BlendMode` discriminant) for this
    /// blend mode, or `None` for custom modes with no named preset.
    pub(crate) fn composite_mode(&self) -> Option<u32> {
        self.name.and_then(BlendMode::from_name).map(|m| m as u32)
    }
}

#[pymethods]
impl PyBlendMode {
    #[new]
    #[pyo3(signature = (*, color_src, color_dst, color_op, alpha_src, alpha_dst, alpha_op))]
    fn new(
        color_src: u8,
        color_dst: u8,
        color_op: u8,
        alpha_src: u8,
        alpha_dst: u8,
        alpha_op: u8,
    ) -> PyResult<Self> {
        let blend_state = custom_blend_state(
            color_src, color_dst, color_op, alpha_src, alpha_dst, alpha_op,
        )
        .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self {
            blend_state: Some(blend_state),
            name: None,
        })
    }

    fn __repr__(&self) -> String {
        match self.name {
            Some(name) => format!("BlendMode.{name}"),
            None => "BlendMode(custom)".to_string(),
        }
    }

    #[classattr]
    const ZERO: u8 = 0;
    #[classattr]
    const ONE: u8 = 1;
    #[classattr]
    const SRC_COLOR: u8 = 2;
    #[classattr]
    const ONE_MINUS_SRC_COLOR: u8 = 3;
    #[classattr]
    const SRC_ALPHA: u8 = 4;
    #[classattr]
    const ONE_MINUS_SRC_ALPHA: u8 = 5;
    #[classattr]
    const DST_COLOR: u8 = 6;
    #[classattr]
    const ONE_MINUS_DST_COLOR: u8 = 7;
    #[classattr]
    const DST_ALPHA: u8 = 8;
    #[classattr]
    const ONE_MINUS_DST_ALPHA: u8 = 9;
    #[classattr]
    const SRC_ALPHA_SATURATED: u8 = 10;

    #[classattr]
    const OP_ADD: u8 = 0;
    #[classattr]
    const OP_SUBTRACT: u8 = 1;
    #[classattr]
    const OP_REVERSE_SUBTRACT: u8 = 2;
    #[classattr]
    const OP_MIN: u8 = 3;
    #[classattr]
    const OP_MAX: u8 = 4;
}

/// Configures how an image is sampled when drawn.
///
/// Controls texture filtering and edge wrapping behavior.
///
/// - `filter` — `LINEAR` (smooth, default) or `NEAREST` (pixelated).
/// - `wrap` — `CLAMP` (default), `REPEAT`, or `MIRROR`.
///   Use `wrap_x`/`wrap_y` to set each axis independently.
#[pyclass(from_py_object)]
#[derive(Clone)]
pub struct Sampler {
    pub(crate) filter: u8,
    pub(crate) wrap_x: u8,
    pub(crate) wrap_y: u8,
}

impl Sampler {
    fn parse_filter(s: &str) -> PyResult<u8> {
        match () {
            _ if s.eq_ignore_ascii_case(constants::LINEAR) => Ok(0),
            _ if s.eq_ignore_ascii_case(constants::NEAREST) => Ok(1),
            _ => Err(PyValueError::new_err(format!(
                "unknown filter: {s:?} (expected {:?} or {:?})",
                constants::LINEAR,
                constants::NEAREST
            ))),
        }
    }

    fn parse_wrap(s: &str) -> PyResult<u8> {
        match () {
            _ if s.eq_ignore_ascii_case(constants::CLAMP) => Ok(0),
            _ if s.eq_ignore_ascii_case(constants::REPEAT) => Ok(1),
            _ if s.eq_ignore_ascii_case(constants::MIRROR) => Ok(2),
            _ => Err(PyValueError::new_err(format!(
                "unknown wrap: {s:?} (expected {:?}, {:?}, or {:?})",
                constants::CLAMP,
                constants::REPEAT,
                constants::MIRROR
            ))),
        }
    }

    fn filter_name(filter: u8) -> &'static str {
        match filter {
            0 => constants::LINEAR,
            1 => constants::NEAREST,
            _ => "?",
        }
    }

    fn wrap_name(wrap: u8) -> &'static str {
        match wrap {
            0 => constants::CLAMP,
            1 => constants::REPEAT,
            2 => constants::MIRROR,
            _ => "?",
        }
    }
}

#[pymethods]
impl Sampler {
    #[new]
    #[pyo3(signature = (*, filter=constants::LINEAR, wrap=constants::CLAMP, wrap_x=None, wrap_y=None))]
    fn new(filter: &str, wrap: &str, wrap_x: Option<&str>, wrap_y: Option<&str>) -> PyResult<Self> {
        let wrap_default = Self::parse_wrap(wrap)?;
        Ok(Self {
            filter: Self::parse_filter(filter)?,
            wrap_x: wrap_x
                .map(Self::parse_wrap)
                .transpose()?
                .unwrap_or(wrap_default),
            wrap_y: wrap_y
                .map(Self::parse_wrap)
                .transpose()?
                .unwrap_or(wrap_default),
        })
    }

    fn __repr__(&self) -> String {
        format!(
            "Sampler(filter={:?}, wrap_x={:?}, wrap_y={:?})",
            Self::filter_name(self.filter),
            Self::wrap_name(self.wrap_x),
            Self::wrap_name(self.wrap_y)
        )
    }
}

pub use crate::surface::Surface;

#[pyclass]
#[derive(Debug)]
pub struct Light {
    pub(crate) entity: Entity,
}

#[pymethods]
impl Light {
    /// Opaque id for this object.
    pub fn id(&self) -> u64 {
        self.entity.to_bits()
    }

    #[pyo3(signature = (*args))]
    pub fn position(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        transform_set_position(self.entity, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (*args))]
    pub fn look_at(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        transform_look_at(self.entity, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (*args))]
    pub fn translate(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        transform_translate(self.entity, v).map_err(rt_err)
    }

    pub fn rotate_x(&self, angle: f32) -> PyResult<()> {
        transform_rotate_x(self.entity, angle).map_err(rt_err)
    }

    pub fn rotate_y(&self, angle: f32) -> PyResult<()> {
        transform_rotate_y(self.entity, angle).map_err(rt_err)
    }

    pub fn rotate_z(&self, angle: f32) -> PyResult<()> {
        transform_rotate_z(self.entity, angle).map_err(rt_err)
    }

    /// Rotate by `angle` radians around `axis`.
    #[pyo3(signature = (angle, *axis))]
    pub fn rotate_axis(&self, angle: f32, axis: &Bound<'_, PyTuple>) -> PyResult<()> {
        let axis = extract_vec3(axis)?;
        transform_rotate_axis(self.entity, angle, axis).map_err(rt_err)
    }

    /// Back to the origin with no rotation.
    pub fn reset(&self) -> PyResult<()> {
        transform_reset(self.entity).map_err(rt_err)
    }
}

// TODO: implement `light_destroy`
// impl Drop for Light {
//     fn drop(&mut self) {
//         let _ = light_destroy(self.entity);
//     }
// }

#[pyclass]
#[derive(Debug)]
pub struct Font {
    pub(crate) entity: Entity,
}

#[pymethods]
impl Font {
    /// Opaque id for this object.
    pub fn id(&self) -> u64 {
        self.entity.to_bits()
    }

    /// Query variable font axes.
    ///
    /// Returns a list of `(tag, min, max, default)` tuples.
    pub fn variations(&self) -> PyResult<Vec<(String, f32, f32, f32)>> {
        font_variations(self.entity)
            .map(|axes| {
                axes.into_iter()
                    .map(|a| (a.tag, a.min, a.max, a.default))
                    .collect()
            })
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Query font metadata.
    ///
    /// Returns a `(family, style, weight, width, is_variable)` tuple.
    pub fn metadata(&self) -> PyResult<(String, String, f32, f32, bool)> {
        font_metadata(self.entity)
            .map(|m| (m.family, m.style, m.weight, m.width, m.is_variable))
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }
}

/// Convert glyph outline groups into per-group lists of Python command tuples.
fn path_commands_to_py(
    py: Python<'_>,
    groups: Vec<Vec<processing_render::render::primitive::text::PathCommand>>,
) -> Vec<Vec<Py<PyAny>>> {
    use processing_render::render::primitive::text::PathCommand;

    let to_py = |cmd: PathCommand| -> Py<PyAny> {
        match cmd {
            PathCommand::MoveTo(x, y) => ("M", x, y).into_pyobject(py).unwrap().into_any().unbind(),
            PathCommand::LineTo(x, y) => ("L", x, y).into_pyobject(py).unwrap().into_any().unbind(),
            PathCommand::QuadTo { cx, cy, x, y } => ("Q", cx, cy, x, y)
                .into_pyobject(py)
                .unwrap()
                .into_any()
                .unbind(),
            PathCommand::CubicTo {
                cx1,
                cy1,
                cx2,
                cy2,
                x,
                y,
            } => ("C", cx1, cy1, cx2, cy2, x, y)
                .into_pyobject(py)
                .unwrap()
                .into_any()
                .unbind(),
            PathCommand::Close => ("Z",).into_pyobject(py).unwrap().into_any().unbind(),
        }
    };

    groups
        .into_iter()
        .map(|group| group.into_iter().map(to_py).collect())
        .collect()
}

#[pyclass]
#[derive(Debug)]
pub struct Image {
    pub(crate) entity: Entity,
    /// Cached `pixels` list populated by `load_pixels()` and written back by
    /// `update_pixels()`, mirroring Processing's `PImage.pixels[]`.
    pixel_cache: Mutex<Option<Py<PyList>>>,
}

impl Image {
    pub(crate) fn wrap(entity: Entity) -> Self {
        Self {
            entity,
            pixel_cache: Mutex::new(None),
        }
    }
}

/// Anything that can be sampled as an image: an `Image`, a `Webcam`, or an
/// offscreen `Graphics`.
pub(crate) struct ImageRef {
    entity: Entity,
    graphics: Option<Entity>,
}

impl ImageRef {
    /// The entity carrying the image. A `Graphics` source is flushed first, so
    /// what it has drawn so far is what gets sampled.
    pub(crate) fn texture(&self) -> PyResult<Entity> {
        if let Some(graphics) = self.graphics {
            graphics_flush(graphics).map_err(rt_err)?;
        }
        Ok(self.entity)
    }
}

impl<'a, 'py> FromPyObject<'a, 'py> for ImageRef {
    type Error = PyErr;

    fn extract(ob: pyo3::Borrowed<'a, 'py, PyAny>) -> PyResult<Self> {
        if let Ok(img) = ob.extract::<PyRef<Image>>() {
            return Ok(ImageRef {
                entity: img.entity,
                graphics: None,
            });
        }
        // an offscreen canvas's render target is an image on its surface entity
        if let Ok(g) = ob.extract::<PyRef<Graphics>>() {
            return Ok(ImageRef {
                entity: g.surface.entity,
                graphics: Some(g.entity),
            });
        }
        #[cfg(feature = "webcam")]
        if let Ok(cam) = ob.extract::<PyRef<crate::webcam::Webcam>>() {
            return Ok(ImageRef {
                entity: cam.image_entity()?,
                graphics: None,
            });
        }
        Err(pyo3::exceptions::PyTypeError::new_err(
            "expected an Image, Graphics, or Webcam",
        ))
    }
}

#[pymethods]
impl Image {
    /// Opaque id for this object.
    pub fn id(&self) -> u64 {
        self.entity.to_bits()
    }

    /// Replace the whole image from raw pixel bytes in the image's format
    /// (RGBA, 8 bits per channel for images from `create_image`), tightly
    /// packed, top row first. Accepts anything with the buffer protocol:
    /// `bytes`, `bytearray`, a C-contiguous `uint8` numpy array, ... This is
    /// the fast path for streaming frames in; `pixels`/`update_pixels` go
    /// through Python objects per pixel.
    pub fn update_raw(&self, data: &Bound<'_, PyAny>) -> PyResult<()> {
        let buffer = pyo3::buffer::PyBuffer::<u8>::get(data)?;
        let bytes = buffer.to_vec(data.py())?;
        image_update_raw(self.entity, &bytes).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Applies a `Sampler` to this image, controlling filtering and wrapping.
    ///
    /// ```python
    /// s = Sampler(filter=NEAREST, wrap=REPEAT)
    /// img.sampler(s)
    /// ```
    fn sampler(&self, sampler: &Sampler) -> PyResult<()> {
        image_set_sampler(self.entity, sampler.filter, sampler.wrap_x, sampler.wrap_y)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Resize to `width` x `height` pixels. A 0 for either keeps the aspect ratio.
    pub fn resize(&self, width: u32, height: u32) -> PyResult<()> {
        let (w, h) = image_size(self.entity).map_err(rt_err)?;
        let (width, height) = match (width, height) {
            (0, 0) => return Err(PyValueError::new_err("resize() needs a non-zero size")),
            (0, height) => ((w as f32 * height as f32 / h as f32).round() as u32, height),
            (width, 0) => (width, (h as f32 * width as f32 / w as f32).round() as u32),
            size => size,
        };
        image_resize(
            self.entity,
            Extent3d {
                width: width.max(1),
                height: height.max(1),
                depth_or_array_layers: 1,
            },
        )
        .map_err(rt_err)
    }

    /// Image width in pixels.
    #[getter]
    fn width(&self) -> PyResult<u32> {
        image_size(self.entity)
            .map(|(w, _)| w)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Image height in pixels.
    #[getter]
    fn height(&self) -> PyResult<u32> {
        image_size(self.entity)
            .map(|(_, h)| h)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Read a single pixel as a `Color` (Processing `get`).
    fn get(&self, x: u32, y: u32) -> PyResult<crate::color::PyColor> {
        let (w, h) =
            image_size(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        if x >= w || y >= h {
            return Err(PyValueError::new_err(format!(
                "pixel ({x}, {y}) out of bounds for {w}x{h} image"
            )));
        }
        let pixels =
            image_readback(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        let p = pixels[(y * w + x) as usize];
        Ok(crate::color::PyColor(bevy::prelude::Color::LinearRgba(p)))
    }

    /// Write a single pixel (Processing `set`). Accepts a `Color`, hex string,
    /// or color components in the default (sRGB) color mode.
    #[pyo3(signature = (x, y, *args))]
    fn set(&self, x: u32, y: u32, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let color = extract_color_with_mode(args, &ColorMode::default())?;
        image_update_region(self.entity, x, y, 1, 1, &[LinearRgba::from(color)])
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Read all pixels into the `pixels` list (Processing `loadPixels`).
    fn load_pixels(&self, py: Python<'_>) -> PyResult<Py<PyList>> {
        let pixels =
            image_readback(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        let list = pixels_to_pylist(py, &pixels)?;
        *self.pixel_cache.lock().unwrap() = Some(list.clone_ref(py));
        Ok(list)
    }

    /// The pixel buffer as a list of `Color` (Processing `pixels[]`). Auto-loads
    /// on first access if `load_pixels()` has not been called.
    #[getter]
    fn pixels(&self, py: Python<'_>) -> PyResult<Py<PyList>> {
        let cached = self
            .pixel_cache
            .lock()
            .unwrap()
            .as_ref()
            .map(|list| list.clone_ref(py));
        match cached {
            Some(list) => Ok(list),
            None => self.load_pixels(py),
        }
    }

    /// Write the `pixels` list back to the image (Processing `updatePixels`). If
    /// `pixels` is omitted, the cached buffer from `load_pixels()` is used.
    #[pyo3(signature = (pixels=None))]
    fn update_pixels(&self, py: Python<'_>, pixels: Option<&Bound<'_, PyAny>>) -> PyResult<()> {
        let seq = resolve_pixels_arg(py, pixels, &self.pixel_cache)?;
        let data = pyseq_to_pixels(&seq)?;
        image_update(self.entity, &data).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Copies a source into this image via a GPU blit (a sampling copy that
    /// handles differing size and format). `src` may be another `Image` or a
    /// `Graphics` render target — e.g. render into an offscreen graphics, then
    /// `img.copy_from(g)` to pull the result into a plain, sampleable image.
    fn copy_from(&self, src: &Bound<'_, PyAny>) -> PyResult<()> {
        if let Ok(img) = src.extract::<PyRef<Image>>() {
            image_copy_from(self.entity, img.entity, false).map_err(rt_err)
        } else if let Ok(g) = src.extract::<PyRef<Graphics>>() {
            image_copy_from(self.entity, g.entity, true).map_err(rt_err)
        } else {
            Err(PyValueError::new_err(
                "copy_from() expects an Image or Graphics source",
            ))
        }
    }

    /// Save the image to a PNG file (Processing `save`).
    fn save(&self, filename: &str) -> PyResult<()> {
        let (w, h) =
            image_size(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        let pixels =
            image_readback(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        let rgba: Vec<u8> = pixels
            .iter()
            .flat_map(|p| Srgba::from(*p).to_u8_array())
            .collect();
        write_png_file(filename, w, h, &rgba)
    }
}

impl Drop for Image {
    fn drop(&mut self) {
        let _ = image_destroy(self.entity);
    }
}

#[cfg(feature = "cuda")]
#[pymethods]
impl Image {
    pub fn cuda(&self) -> PyResult<CudaImage> {
        processing_cuda::cuda_export(self.entity)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(CudaImage::new(self.entity))
    }

    pub fn update_from(&self, obj: &Bound<'_, pyo3::PyAny>) -> PyResult<()> {
        cuda_import_from_interface(self.entity, obj)
    }
}

#[pyclass(unsendable)]
pub struct Geometry {
    pub(crate) entity: Entity,
}

#[pyclass]
pub struct Sketch {
    pub source: String,
}

impl Geometry {
    pub(crate) fn create(kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
        let topology = match kwargs.and_then(|k| k.get_item("topology").ok().flatten()) {
            Some(t) => {
                let s = t.extract::<String>()?;
                geometry::Topology::parse(&s)
                    .ok_or_else(|| PyValueError::new_err(format!("unknown topology: {s:?}")))?
            }
            None => geometry::Topology::TriangleList,
        };

        let geometry =
            geometry_create(topology).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self { entity: geometry })
    }
}

#[pymethods]
impl Geometry {
    /// Opaque id for this object.
    pub fn id(&self) -> u64 {
        self.entity.to_bits()
    }

    #[pyo3(signature = (*args))]
    pub fn color(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec4(args)?;
        geometry_color(self.entity, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (*args))]
    pub fn normal(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        geometry_normal(self.entity, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (*args))]
    pub fn vertex(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        geometry_vertex(self.entity, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (*args))]
    pub fn uv(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec2(args)?;
        geometry_uv(self.entity, v.x, v.y).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    pub fn index(&self, i: u32) -> PyResult<()> {
        geometry_index(self.entity, i).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[pyo3(signature = (i, *args))]
    pub fn set_vertex(&self, i: u32, args: &Bound<'_, PyTuple>) -> PyResult<()> {
        let v = extract_vec3(args)?;
        geometry_set_vertex(self.entity, i, v).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    pub fn vertex_count(&self) -> PyResult<u32> {
        geometry_vertex_count(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    #[staticmethod]
    #[pyo3(signature = (radius, sectors=32, stacks=18))]
    pub fn sphere(radius: f32, sectors: u32, stacks: u32) -> PyResult<Self> {
        let entity = geometry_sphere(radius, sectors, stacks)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self { entity })
    }

    #[staticmethod]
    pub fn r#box(width: f32, height: f32, depth: f32) -> PyResult<Self> {
        let entity = geometry_box(width, height, depth)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self { entity })
    }

    /// A point lattice centered at the origin, to seed `create_particles(geometry)`.
    #[staticmethod]
    #[pyo3(signature = (nx, ny, nz, spacing=1.0))]
    pub fn grid(nx: u32, ny: u32, nz: u32, spacing: f32) -> PyResult<Self> {
        let entity = geometry_grid(nx, ny, nz, spacing)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self { entity })
    }
}

#[pyclass(unsendable)]
pub struct Graphics {
    pub(crate) entity: Entity,
    pub surface: Surface,
    #[pyo3(get)]
    pub width: u32,
    #[pyo3(get)]
    pub height: u32,
    /// Cached `pixels` list populated by `load_pixels()` and written back by
    /// `update_pixels()`, mirroring Processing's `pixels[]`.
    pixel_cache: Mutex<Option<Py<PyList>>>,
}

impl Drop for Graphics {
    fn drop(&mut self) {
        let _ = graphics_destroy(self.entity);
    }
}

/// `mode_3d()`'s field of view.
const DEFAULT_FOV: f32 = std::f32::consts::FRAC_PI_3;

impl Graphics {
    /// How far `mode_3d()` puts the camera: where the canvas fills the view.
    fn default_camera_z(&self) -> f32 {
        (self.height as f32 / 2.0) / (DEFAULT_FOV / 2.0).tan()
    }

    pub(crate) fn current_color_mode(&self) -> PyResult<ColorMode> {
        graphics_get_color_mode(self.entity).map_err(|e| PyRuntimeError::new_err(format!("{e}")))
    }

    /// Create an offscreen graphics buffer in the already-running app (no window,
    /// no `init`). Backs `create_graphics()` / `new_offscreen()`. The caller must
    /// ensure the app exists (i.e. `size()` was called first).
    pub(crate) fn wrap_offscreen(width: u32, height: u32, hdr: bool) -> PyResult<Self> {
        let texture_format = if hdr {
            TextureFormat::Rgba16Float
        } else {
            TextureFormat::Rgba8UnormSrgb
        };
        let surface_entity = surface_create_offscreen(width, height, 1.0, texture_format)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Self::from_surface(surface_entity, width, height, texture_format, None)
    }

    /// Wrap an existing surface entity in a `Graphics` (camera + draw state). The
    /// `glfw_ctx` is `None` for offscreen and secondary windows — the main
    /// surface owns the shared `GlfwContext` that drives every window.
    pub(crate) fn from_surface(
        surface_entity: Entity,
        width: u32,
        height: u32,
        texture_format: TextureFormat,
        glfw_ctx: Option<GlfwContext>,
    ) -> PyResult<Self> {
        let graphics = graphics_create(surface_entity, width, height, texture_format)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
        Ok(Self {
            entity: graphics,
            surface: Surface {
                entity: surface_entity,
                glfw_ctx,
            },
            width,
            height,
            pixel_cache: Mutex::new(None),
        })
    }

    /// Wrap a secondary window's surface in a `Graphics` (HDR window target). The
    /// window lives on the main surface's shared `GlfwContext`, so this holds no
    /// `glfw_ctx` of its own.
    pub(crate) fn wrap_window(surface_entity: Entity, width: u32, height: u32) -> PyResult<Self> {
        Self::from_surface(
            surface_entity,
            width,
            height,
            TextureFormat::Rgba16Float,
            None,
        )
    }
}

#[pymethods]
impl Graphics {
    /// Opaque id for this object.
    pub fn id(&self) -> u64 {
        self.entity.to_bits()
    }

    #[new]
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        width: u32,
        height: u32,
        asset_path: &str,
        sketch_root_path: &str,
        sketch_file_name: &str,
        log_level: Option<&str>,
        transparent: bool,
    ) -> PyResult<Self> {
        let mut glfw_ctx = GlfwContext::new(width, height, transparent)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;

        let mut config = Config::new();
        config.set(ConfigKey::AssetRootPath, asset_path.to_string());
        config.set(ConfigKey::SketchRootPath, sketch_root_path.to_string());
        config.set(ConfigKey::SketchFileName, sketch_file_name.to_string());
        if let Some(level) = log_level {
            config.set(ConfigKey::LogLevel, level.to_string());
        }
        init(config).map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;

        let surface = glfw_ctx
            .create_surface(width, height, transparent)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;

        let surface = Surface {
            entity: surface,
            glfw_ctx: Some(glfw_ctx),
        };

        let graphics = graphics_create(surface.entity, width, height, TextureFormat::Rgba16Float)
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;

        // The Window component (applied each frame by the sync loop) otherwise
        // defaults its title; match the GLFW create-time title.
        surface_set_title(surface.entity, "Processing".to_string())
            .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;