raylib 6.0.0-rc.2

//! Image and texture related functions

use crate::core::databuf::DataBuf;
use crate::core::ffi::{Color, Rectangle};
use crate::core::math::Vector2;
use crate::core::{RaylibHandle, RaylibThread};
use crate::ffi;
use std::convert::TryInto;
use std::ffi::CString;
use std::mem::{ManuallyDrop, MaybeUninit};

use super::error::{InvalidImageError, LoadTextureError, UpdateTextureError};

make_rslice!(ImagePalette, Color, ffi::UnloadImagePalette);
make_rslice!(ImageColors, Color, ffi::UnloadImageColors);

/// NPatchInfo, n-patch layout info
#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct NPatchInfo {
    /// Texture source rectangle
    pub source: Rectangle,
    /// Left border offset
    pub left: i32,
    /// Top border offset
    pub top: i32,
    /// Right border offset
    pub right: i32,
    /// Bottom border offset
    pub bottom: i32,
    /// Layout of the n-patch: 3x3, 1x3 or 3x1
    pub layout: crate::consts::NPatchLayout,
}

impl From<ffi::NPatchInfo> for NPatchInfo {
    fn from(v: ffi::NPatchInfo) -> NPatchInfo {
        unsafe { std::mem::transmute(v) }
    }
}

impl From<NPatchInfo> for ffi::NPatchInfo {
    fn from(v: NPatchInfo) -> Self {
        unsafe { std::mem::transmute(v) }
    }
}

impl From<&NPatchInfo> for ffi::NPatchInfo {
    fn from(v: &NPatchInfo) -> Self {
        ffi::NPatchInfo {
            source: v.source,
            left: v.left,
            top: v.top,
            right: v.right,
            bottom: v.bottom,
            layout: (v.layout as u32) as i32,
        }
    }
}

fn no_drop<T>(_thing: T) {}
make_thin_wrapper!(
    /// CPU-side pixel buffer.
    ///
    /// An `Image` holds raw pixel data in system RAM. It is the starting point for most
    /// texture-loading workflows: generate or load pixels on the CPU, manipulate them
    /// (crop, resize, draw into, colour-fill, etc.), then upload to the GPU as a
    /// [`Texture2D`] via [`RaylibHandle::load_texture_from_image`].
    ///
    /// `Image` is automatically freed via `UnloadImage` when it goes out of scope.
    ///
    /// # Examples
    ///
    /// Generate a solid-colour image and read a pixel back (no window required):
    ///
    /// ```rust
    /// # #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    /// # {
    /// use raylib::prelude::*;
    /// let img = Image::gen_image_color(64, 64, Color::RED);
    /// assert_eq!(img.width(), 64);
    /// assert_eq!(img.height(), 64);
    /// let pixel = img.get_color(0, 0);
    /// assert_eq!(pixel.r, 255);
    /// assert_eq!(pixel.g, 0);
    /// assert_eq!(pixel.b, 0);
    /// # }
    /// ```
    Image,
    ffi::Image,
    ffi::UnloadImage
);
make_thin_wrapper!(
    /// GPU-side texture stored in VRAM.
    ///
    /// A `Texture2D` is uploaded from an [`Image`] (or loaded directly from a file) and
    /// lives on the graphics card. Draw it inside a drawing handle using the
    /// `draw_texture*` family of methods.
    ///
    /// `Texture2D` is automatically freed via `UnloadTexture` when it goes out of scope.
    ///
    /// # Examples
    ///
    /// Load a texture from file and draw it each frame:
    ///
    /// ```rust,no_run
    /// use raylib::prelude::*;
    /// let (mut rl, thread) = raylib::init().size(640, 480).title("texture demo").build();
    /// let tex = rl.load_texture(&thread, "assets/sprite.png").unwrap();
    /// while !rl.window_should_close() {
    ///     let mut d = rl.begin_drawing(&thread);
    ///     d.clear_background(Color::RAYWHITE);
    ///     d.draw_texture(&tex, 0, 0, Color::WHITE);
    /// }
    /// ```
    Texture2D,
    ffi::Texture2D,
    ffi::UnloadTexture
);
make_thin_wrapper!(WeakTexture2D, ffi::Texture2D, no_drop);
#[allow(clippy::derivable_impls)] // Cannot use #[derive(Default)] on a macro-generated struct
impl Default for WeakTexture2D {
    fn default() -> Self {
        Self(ffi::Texture::default())
    }
}
make_thin_wrapper!(
    /// Off-screen GPU framebuffer for render-to-texture.
    ///
    /// A `RenderTexture2D` wraps an OpenGL FBO. Use `begin_texture_mode`
    /// (or `draw_texture_mode`) on a `RaylibHandle` or `RaylibDrawHandle` to redirect
    /// drawing into the framebuffer, then access the result via
    /// [`RaylibRenderTexture2D::texture`] which returns a reference to the
    /// colour-attachment [`Texture2D`].
    ///
    /// Freed via `UnloadRenderTexture` on drop.
    ///
    /// # Examples
    ///
    /// Render a scene off-screen then display the result on the main framebuffer:
    ///
    /// ```rust,no_run
    /// use raylib::prelude::*;
    /// let (mut rl, thread) = raylib::init().size(640, 480).title("render-texture demo").build();
    /// let mut rt = rl.load_render_texture(&thread, 320, 240).unwrap();
    /// while !rl.window_should_close() {
    ///     // Draw into the off-screen buffer.
    ///     {
    ///         let mut tm = rl.begin_texture_mode(&thread, &mut rt);
    ///         tm.clear_background(Color::RED);
    ///     }
    ///     // Blit the render texture to the screen.
    ///     let mut d = rl.begin_drawing(&thread);
    ///     d.clear_background(Color::RAYWHITE);
    ///     d.draw_texture(rt.texture(), 0, 0, Color::WHITE);
    /// }
    /// ```
    RenderTexture2D,
    ffi::RenderTexture2D,
    ffi::UnloadRenderTexture
);
make_thin_wrapper!(WeakRenderTexture2D, ffi::RenderTexture2D, no_drop);

// Weak things can be clone
impl Clone for WeakTexture2D {
    fn clone(&self) -> WeakTexture2D {
        WeakTexture2D(self.0)
    }
}

// Weak things can be clone
impl Clone for WeakRenderTexture2D {
    fn clone(&self) -> WeakRenderTexture2D {
        WeakRenderTexture2D(self.0)
    }
}

impl RaylibRenderTexture2D for WeakRenderTexture2D {}
impl RaylibRenderTexture2D for RenderTexture2D {}

impl AsRef<ffi::Texture2D> for RenderTexture2D {
    #[inline]
    fn as_ref(&self) -> &ffi::Texture2D {
        self.texture()
    }
}

impl AsMut<ffi::Texture2D> for RenderTexture2D {
    #[inline]
    fn as_mut(&mut self) -> &mut ffi::Texture2D {
        self.texture_mut()
    }
}

impl AsRef<ffi::Texture2D> for WeakRenderTexture2D {
    #[inline]
    fn as_ref(&self) -> &ffi::Texture2D {
        self.texture()
    }
}

impl AsMut<ffi::Texture2D> for WeakRenderTexture2D {
    #[inline]
    fn as_mut(&mut self) -> &mut ffi::Texture2D {
        self.texture_mut()
    }
}

impl RenderTexture2D {
    /// # Safety
    ///
    /// The caller becomes responsible for ensuring the underlying `ffi::RenderTexture2D` is
    /// eventually unloaded. The returned `WeakRenderTexture2D` does not call `UnloadRenderTexture` on drop.
    #[inline]
    #[must_use]
    pub unsafe fn make_weak(self) -> WeakRenderTexture2D {
        let m = WeakRenderTexture2D(self.0);
        std::mem::forget(self);
        m
    }

    /// Check if a render texture is valid (loaded in GPU)
    #[inline]
    #[must_use]
    pub fn is_render_texture_valid(&self) -> bool {
        unsafe { ffi::IsRenderTextureValid(self.0) }
    }
}

/// Extension methods for types that wrap a raylib `RenderTexture2D` (both owned and weak variants).
///
/// Implemented for [`RenderTexture2D`] (RAII-owned) and `WeakRenderTexture2D` (no-drop
/// alias). Exposes the OpenGL FBO id ([`id`](Self::id)) plus the colour-attachment
/// texture as a borrowed [`WeakTexture2D`] ([`texture`](Self::texture),
/// [`texture_mut`](Self::texture_mut)) so callers can sample the offscreen result with
/// `draw_texture`, regenerate mipmaps, etc.
///
/// # Examples
///
/// ```no_run
/// use raylib::prelude::*;
/// use raylib::core::texture::RaylibRenderTexture2D;
///
/// let (mut rl, thread) = raylib::init().size(640, 480).title("rt").build();
/// let mut rt = rl
///     .load_render_texture(&thread, 320, 240)
///     .expect("render texture");
/// {
///     let mut tm = rl.begin_texture_mode(&thread, &mut rt);
///     tm.clear_background(Color::RED);
/// }
/// // Sample the offscreen colour attachment as a regular texture.
/// let mut d = rl.begin_drawing(&thread);
/// d.clear_background(Color::RAYWHITE);
/// d.draw_texture(rt.texture(), 0, 0, Color::WHITE);
/// ```
///
/// # See also
///
/// - [`RenderTexture2D`] — owning render-texture handle.
/// - [`RaylibTexture2D`] — companion trait for the colour-attachment texture.
pub trait RaylibRenderTexture2D: AsRef<ffi::RenderTexture2D> + AsMut<ffi::RenderTexture2D> {
    /// OpenGL framebuffer object id
    #[inline]
    #[must_use]
    fn id(&self) -> u32 {
        self.as_ref().id
    }

    /// Color buffer attachment texture
    #[inline]
    #[must_use]
    fn texture(&self) -> &WeakTexture2D {
        unsafe { std::mem::transmute(&self.as_ref().texture) }
    }

    /// Color buffer attachment texture
    #[inline]
    #[must_use]
    fn texture_mut(&mut self) -> &mut WeakTexture2D {
        unsafe { std::mem::transmute(&mut self.as_mut().texture) }
    }
}

impl Clone for Image {
    /// Create an image duplicate (useful for transformations)
    fn clone(&self) -> Image {
        unsafe { Image(ffi::ImageCopy(self.0)) }
    }
}

impl Image {
    /// Image base width
    #[inline]
    #[must_use]
    pub fn width(&self) -> i32 {
        self.0.width
    }
    /// Image base height
    #[inline]
    #[must_use]
    pub fn height(&self) -> i32 {
        self.0.height
    }
    /// Mipmap levels, 1 by default
    #[inline]
    #[must_use]
    pub fn mipmaps(&self) -> i32 {
        self.0.mipmaps
    }
    /// Image raw data
    ///
    /// # Safety
    ///
    /// The returned pointer is only valid for the lifetime of `self` and the image's backing
    /// buffer. The caller must not use the pointer after the image is dropped or reallocated.
    #[inline]
    #[must_use]
    pub unsafe fn data(&self) -> *mut ::std::os::raw::c_void {
        self.0.data
    }

    /// Apply Gaussian blur using a box blur approximation
    #[inline]
    pub fn blur_gaussian(&mut self, blur_size: i32) {
        unsafe { ffi::ImageBlurGaussian(&mut self.0, blur_size) }
    }
    /// Rotate image by input angle in degrees (-359 to 359)
    #[inline]
    pub fn rotate(&mut self, degrees: i32) {
        unsafe { ffi::ImageRotate(&mut self.0, degrees) }
    }
    /// Get image pixel color at (x, y) position
    #[inline]
    #[must_use]
    pub fn get_color(&self, x: i32, y: i32) -> Color {
        unsafe { ffi::GetImageColor(self.0, x, y) }
    }
    /// Draw circle outline within an image
    #[inline]
    pub fn draw_circle_lines(&mut self, center_x: i32, center_y: i32, radius: i32, color: Color) {
        unsafe { ffi::ImageDrawCircleLines(&mut self.0, center_x, center_y, radius, color) }
    }
    /// Draw circle outline within an image (Vector version)
    #[inline]
    pub fn draw_circle_lines_v(&mut self, center: impl Into<Vector2>, center_y: i32, color: Color) {
        unsafe { ffi::ImageDrawCircleLinesV(&mut self.0, center.into(), center_y, color) }
    }

    /// Data format (PixelFormat type)
    #[inline]
    #[must_use]
    pub fn format(&self) -> crate::consts::PixelFormat {
        let i: u32 = self.format as u32;
        unsafe { std::mem::transmute(i) }
    }

    /// Create an image from another image piece
    #[must_use]
    #[inline]
    pub fn from_image(&self, rec: impl Into<ffi::Rectangle>) -> Image {
        unsafe { Image(ffi::ImageFromImage(self.0, rec.into())) }
    }

    /// Create an image from a selected channel of another image (GRAYSCALE)
    #[inline]
    #[must_use]
    pub fn from_channel(&self, selected_channel: i32) -> Image {
        unsafe { Image(ffi::ImageFromChannel(self.0, selected_channel)) }
    }
    /// Exports image as a PNG file.
    #[inline]
    pub fn export_image(&self, filename: &str) {
        let c_filename = CString::new(filename).unwrap();
        unsafe {
            ffi::ExportImage(self.0, c_filename.as_ptr());
        }
    }

    /// Exports image as a PNG file.
    #[inline]
    pub fn export_image_as_code(&self, filename: &str) {
        let c_filename = CString::new(filename).unwrap();
        unsafe {
            ffi::ExportImageAsCode(self.0, c_filename.as_ptr());
        }
    }

    /// Get pixel data size in bytes (image or texture)
    #[inline]
    #[must_use]
    pub fn get_pixel_data_size(&self) -> usize {
        unsafe { ffi::GetPixelDataSize(self.width(), self.height(), self.format() as i32) as usize }
    }

    /// Gets pixel data from `image` as a Vec of Color structs.
    #[must_use]
    pub fn get_image_data(&self) -> ImageColors {
        unsafe {
            let image_data = ffi::LoadImageColors(self.0);
            let image_data_len = (self.width * self.height) as usize;
            ImageColors(ManuallyDrop::new(Box::from_raw(
                std::slice::from_raw_parts_mut(image_data as *mut _, image_data_len),
            )))
        }
    }

    /// Gets pixel data from `image` as a Vec of Color structs.
    #[must_use]
    pub fn get_image_data_u8(&self, flip: bool) -> Vec<u8> {
        let image_data_len = (self.width * self.height * 4) as usize;
        let mut res = Vec::with_capacity(image_data_len);
        if flip {
            for y in (0..self.height).rev() {
                for x in 0..self.width {
                    let color = self.get_color(x, y);
                    res.push(color.r);
                    res.push(color.g);
                    res.push(color.b);
                    res.push(color.a);
                }
            }
        } else {
            for y in 0..self.height {
                for x in 0..self.width {
                    let color = self.get_color(x, y);
                    res.push(color.r);
                    res.push(color.g);
                    res.push(color.b);
                    res.push(color.a);
                }
            }
        }
        res
    }
    /// Extract color palette from image to maximum size
    #[inline]
    #[must_use]
    pub fn extract_palette(&self, max_palette_size: u32) -> ImagePalette {
        unsafe {
            let mut palette_len = 0;
            let image_data =
                ffi::LoadImagePalette(self.0, max_palette_size as i32, &mut palette_len);
            ImagePalette(ManuallyDrop::new(Box::from_raw(
                std::slice::from_raw_parts_mut(image_data as *mut _, palette_len as usize),
            )))
        }
    }

    /// Converts `image` to POT (power-of-two).
    #[inline]
    pub fn to_pot(&mut self, fill_color: impl Into<ffi::Color>) {
        unsafe {
            ffi::ImageToPOT(&mut self.0, fill_color.into());
        }
    }

    /// Converts `image` data to desired pixel format.
    #[inline]
    pub fn set_format(&mut self, new_format: crate::consts::PixelFormat) {
        unsafe {
            ffi::ImageFormat(&mut self.0, (new_format as u32) as i32);
        }
    }

    /// Applies alpha mask to `image`.
    /// Alpha mask must be same size as the image. If alpha mask is not greyscale
    /// Ensure the colors are white (255, 255, 255, 255) or black (0, 0, 0, 0)
    #[inline]
    pub fn alpha_mask(&mut self, alpha_mask: &Image) {
        unsafe {
            ffi::ImageAlphaMask(&mut self.0, alpha_mask.0);
        }
    }

    /// Clears alpha channel on `image` to desired color.
    #[inline]
    pub fn alpha_clear(&mut self, color: impl Into<ffi::Color>, threshold: f32) {
        unsafe {
            ffi::ImageAlphaClear(&mut self.0, color.into(), threshold);
        }
    }

    /// Crops `image` depending on alpha value.
    #[inline]
    pub fn alpha_crop(&mut self, threshold: f32) {
        unsafe {
            ffi::ImageAlphaCrop(&mut self.0, threshold);
        }
    }

    /// Premultiplies alpha channel on `image`.
    #[inline]
    pub fn alpha_premultiply(&mut self) {
        unsafe {
            ffi::ImageAlphaPremultiply(&mut self.0);
        }
    }

    /// Crops `image` to a defined rectangle.
    #[inline]
    pub fn crop(&mut self, crop: impl Into<ffi::Rectangle>) {
        unsafe {
            ffi::ImageCrop(&mut self.0, crop.into());
        }
    }

    /// Resizes `image` (bilinear filtering).
    #[inline]
    pub fn resize(&mut self, new_width: i32, new_height: i32) {
        unsafe {
            ffi::ImageResize(&mut self.0, new_width, new_height);
        }
    }

    /// Resizes `image` (nearest-neighbor scaling).
    #[inline]
    pub fn resize_nn(&mut self, new_width: i32, new_height: i32) {
        unsafe {
            ffi::ImageResizeNN(&mut self.0, new_width, new_height);
        }
    }

    /// Resizes `image` canvas and fills with `color`.
    #[inline]
    pub fn resize_canvas(
        &mut self,
        new_width: i32,
        new_height: i32,
        offset_x: i32,
        offset_y: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageResizeCanvas(
                &mut self.0,
                new_width,
                new_height,
                offset_x,
                offset_y,
                color.into(),
            );
        }
    }

    /// Generates all mipmap levels for a provided `image`.
    #[inline]
    pub fn gen_mipmaps(&mut self) {
        unsafe {
            ffi::ImageMipmaps(&mut self.0);
        }
    }

    /// Dithers `image` data to 16bpp or lower (Floyd-Steinberg dithering).
    #[inline]
    pub fn dither(&mut self, r_bpp: i32, g_bpp: i32, b_bpp: i32, a_bpp: i32) {
        unsafe {
            ffi::ImageDither(&mut self.0, r_bpp, g_bpp, b_bpp, a_bpp);
        }
    }

    /// Get image alpha border rectangle
    #[inline]
    pub fn get_image_alpha_border(&self, threshold: f32) -> Rectangle {
        unsafe { ffi::GetImageAlphaBorder(self.0, threshold) }
    }

    /// Clear image background with given color
    #[inline]
    pub fn clear_background(&mut self, color: impl Into<ffi::Color>) {
        unsafe { ffi::ImageClearBackground(&mut self.0, color.into()) }
    }

    /// Draws a source image within a destination image.
    #[inline]
    pub fn draw(
        &mut self,
        src: &Image,
        src_rec: Rectangle,
        dst_rec: Rectangle,
        tint: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDraw(&mut self.0, src.0, src_rec, dst_rec, tint.into());
        }
    }

    /// Draw pixel within an image
    #[inline]
    pub fn draw_pixel(&mut self, pos_x: i32, pos_y: i32, color: impl Into<ffi::Color>) {
        unsafe { ffi::ImageDrawPixel(&mut self.0, pos_x, pos_y, color.into()) }
    }

    /// Draw pixel within an image (Vector version)
    #[inline]
    pub fn draw_pixel_v(&mut self, position: impl Into<Vector2>, color: impl Into<ffi::Color>) {
        unsafe { ffi::ImageDrawPixelV(&mut self.0, position.into(), color.into()) }
    }

    /// Draw line within an image
    #[inline]
    pub fn draw_line(
        &mut self,
        start_pos_x: i32,
        start_pos_y: i32,
        end_pos_x: i32,
        end_pos_y: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawLine(
                &mut self.0,
                start_pos_x,
                start_pos_y,
                end_pos_x,
                end_pos_y,
                color.into(),
            )
        }
    }

    /// Draw a line (using triangles/quads)
    #[inline]
    pub fn draw_line_ex(
        &mut self,
        start_pos: impl Into<Vector2>,
        end_pos: impl Into<Vector2>,
        thick: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawLineEx(
                &mut self.0,
                start_pos.into(),
                end_pos.into(),
                thick,
                color.into(),
            )
        }
    }

    /// Draw line within an image (Vector version)
    #[inline]
    pub fn draw_line_v(
        &mut self,
        start: impl Into<Vector2>,
        end: impl Into<Vector2>,
        color: impl Into<ffi::Color>,
    ) {
        unsafe { ffi::ImageDrawLineV(&mut self.0, start.into(), end.into(), color.into()) }
    }

    /// Draw triangle within an image
    #[inline]
    pub fn draw_triangle(
        &mut self,
        v1: impl Into<Vector2>,
        v2: impl Into<Vector2>,
        v3: impl Into<Vector2>,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawTriangle(&mut self.0, v1.into(), v2.into(), v3.into(), color.into())
        }
    }

    /// Draw triangle with interpolated colors within an image
    #[inline]
    pub fn draw_triangle_ex(
        &mut self,
        v1: impl Into<Vector2>,
        v2: impl Into<Vector2>,
        v3: impl Into<Vector2>,
        c1: impl Into<ffi::Color>,
        c2: impl Into<ffi::Color>,
        c3: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawTriangleEx(
                &mut self.0,
                v1.into(),
                v2.into(),
                v3.into(),
                c1.into(),
                c2.into(),
                c3.into(),
            )
        }
    }

    /// Draw triangle outline within an image
    #[inline]
    pub fn draw_triangle_lines(
        &mut self,
        v1: impl Into<Vector2>,
        v2: impl Into<Vector2>,
        v3: impl Into<Vector2>,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawTriangleLines(&mut self.0, v1.into(), v2.into(), v3.into(), color.into())
        }
    }

    /// Draw a triangle fan defined by points within an image (first vertex is the center)
    pub fn draw_triangle_fan(
        &mut self,
        points: &mut [crate::math::Vector2],
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawTriangleFan(
                &mut self.0,
                points.as_ptr() as *mut Vector2,
                points.len() as i32,
                color.into(),
            )
        }
    }

    /// Draw a triangle strip defined by points within an image
    pub fn draw_triangle_strip(
        &mut self,
        points: &mut [crate::math::Vector2],
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawTriangleStrip(
                &mut self.0,
                points.as_ptr() as *mut Vector2,
                points.len() as i32,
                color.into(),
            )
        }
    }

    /// Draw circle within an image
    #[inline]
    pub fn draw_circle(
        &mut self,
        center_x: i32,
        center_y: i32,
        radius: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe { ffi::ImageDrawCircle(&mut self.0, center_x, center_y, radius, color.into()) }
    }

    /// Draw circle within an image (Vector version)
    #[inline]
    pub fn draw_circle_v(
        &mut self,
        center: impl Into<Vector2>,
        radius: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe { ffi::ImageDrawCircleV(&mut self.0, center.into(), radius, color.into()) }
    }

    /// Draws a rectangle within an image.
    #[inline]
    pub fn draw_rectangle(
        &mut self,
        pos_x: i32,
        pos_y: i32,
        width: i32,
        height: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawRectangle(&mut self.0, pos_x, pos_y, width, height, color.into());
        }
    }

    /// Draw rectangle within an image (Vector version)
    #[inline]
    pub fn draw_rectangle_v(
        &mut self,
        position: impl Into<Vector2>,
        size: impl Into<Vector2>,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawRectangleV(&mut self.0, position.into(), size.into(), color.into());
        }
    }

    /// Draw rectangle within an image (Rectangle version)
    #[inline]
    pub fn draw_rectangle_rec(
        &mut self,
        rectangle: impl Into<ffi::Rectangle>,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawRectangleRec(&mut self.0, rectangle.into(), color.into());
        }
    }

    /// Draws a rectangle within an image.
    #[inline]
    pub fn draw_rectangle_lines(
        &mut self,
        rec: Rectangle,
        thickness: i32,
        color: impl Into<ffi::Color>,
    ) {
        unsafe {
            ffi::ImageDrawRectangleLines(&mut self.0, rec, thickness, color.into());
        }
    }

    /// Draws text (default font) within an image (destination).
    #[inline]
    pub fn draw_text(
        &mut self,
        text: &str,
        pos_x: i32,
        pos_y: i32,
        font_size: i32,
        color: impl Into<ffi::Color>,
    ) {
        let c_text = CString::new(text).unwrap();
        unsafe {
            ffi::ImageDrawText(
                &mut self.0,
                c_text.as_ptr(),
                pos_x,
                pos_y,
                font_size,
                color.into(),
            );
        }
    }

    /// Draws text (default font) within an image (destination).
    #[inline]
    pub fn draw_text_ex(
        &mut self,
        font: impl AsRef<ffi::Font>,
        text: &str,
        position: impl Into<Vector2>,
        font_size: f32,
        spacing: f32,
        color: impl Into<ffi::Color>,
    ) {
        let c_text = CString::new(text).unwrap();
        unsafe {
            ffi::ImageDrawTextEx(
                &mut self.0,
                *font.as_ref(),
                c_text.as_ptr(),
                position.into(),
                font_size,
                spacing,
                color.into(),
            );
        }
    }

    /// Flips `image` vertically.
    #[inline]
    pub fn flip_vertical(&mut self) {
        unsafe {
            ffi::ImageFlipVertical(&mut self.0);
        }
    }

    /// Flips `image` horizontally.
    #[inline]
    pub fn flip_horizontal(&mut self) {
        unsafe {
            ffi::ImageFlipHorizontal(&mut self.0);
        }
    }

    /// Rotates `image` clockwise by 90 degrees (PI/2 radians).
    #[inline]
    pub fn rotate_cw(&mut self) {
        unsafe {
            ffi::ImageRotateCW(&mut self.0);
        }
    }

    /// Rotates `image` counterclockwise by 90 degrees (PI/2 radians).
    #[inline]
    pub fn rotate_ccw(&mut self) {
        unsafe {
            ffi::ImageRotateCCW(&mut self.0);
        }
    }

    /// Tints colors in `image` using specified `color`.
    #[inline]
    pub fn color_tint(&mut self, color: impl Into<ffi::Color>) {
        unsafe {
            ffi::ImageColorTint(&mut self.0, color.into());
        }
    }

    /// Inverts the colors in `image`.
    #[inline]
    pub fn color_invert(&mut self) {
        unsafe {
            ffi::ImageColorInvert(&mut self.0);
        }
    }

    /// Converts `image color to grayscale.
    #[inline]
    pub fn color_grayscale(&mut self) {
        unsafe {
            ffi::ImageColorGrayscale(&mut self.0);
        }
    }

    /// Adjusts the contrast of `image`.
    #[inline]
    pub fn color_contrast(&mut self, contrast: f32) {
        unsafe {
            ffi::ImageColorContrast(&mut self.0, contrast);
        }
    }

    /// Adjusts the brightness of `image`.
    #[inline]
    pub fn color_brightness(&mut self, brightness: i32) {
        unsafe {
            ffi::ImageColorBrightness(&mut self.0, brightness);
        }
    }

    /// Searches `image` for all occurrences of `color` and replaces them with `replace` color.
    #[inline]
    pub fn color_replace(&mut self, color: impl Into<ffi::Color>, replace: impl Into<ffi::Color>) {
        unsafe {
            ffi::ImageColorReplace(&mut self.0, color.into(), replace.into());
        }
    }

    /// Export image to memory buffer.
    pub fn export_image_to_memory(
        &self,
        file_type: &str,
    ) -> Result<DataBuf<[u8]>, InvalidImageError> {
        if self.width == 0 {
            return Err(InvalidImageError::ZeroWidth);
        }
        if self.height == 0 {
            return Err(InvalidImageError::ZeroHeight);
        }
        if self.data.is_null() {
            return Err(InvalidImageError::NullData);
        }

        let c_filetype = CString::new(file_type).unwrap();
        let mut data_size = MaybeUninit::uninit();
        let data = unsafe {
            // ExportImageToMemory returns null if the code for converting to a file type never goes off.
            ffi::ExportImageToMemory(self.0, c_filetype.as_ptr(), data_size.as_mut_ptr())
        };

        // SAFETY: DataBuf::slice_from_raw returns None if the data ptr is null.
        let buf = unsafe { DataBuf::slice_from_raw(data, data_size) };
        buf.ok_or(InvalidImageError::UnsupportedFormat)
    }

    /// Apply custom square convolution kernel to image
    /// NOTE: The convolution kernel matrix is expected to be square
    pub fn kernel_convolution(&mut self, kernel: &[f32]) -> Result<(), InvalidImageError> {
        if self.width == 0 {
            return Err(InvalidImageError::ZeroWidth);
        }
        if self.height == 0 {
            return Err(InvalidImageError::ZeroHeight);
        }
        if self.data.is_null() {
            return Err(InvalidImageError::NullData);
        }

        let kernel_width = (kernel.len() as f32).sqrt() as i32;

        if (kernel_width * kernel_width) as usize != kernel.len() {
            return Err(InvalidImageError::NonSquareKernel);
        }

        unsafe { ffi::ImageKernelConvolution(&mut self.0, kernel.as_ptr(), kernel.len() as i32) }

        Ok(())
    }

    /// Generates a plain solid-colour image in CPU memory.
    ///
    /// Use this to create blank canvases for further pixel manipulation or as placeholder
    /// textures before real assets are available. Requires the `SUPPORT_IMAGE_GENERATION`
    /// feature (included in `full`).
    #[inline]
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_color(width: i32, height: i32, color: impl Into<ffi::Color>) -> Image {
        unsafe { Image(ffi::GenImageColor(width, height, color.into())) }
    }
    /// Generates an image containing Perlin noise in CPU memory.
    ///
    /// Useful for procedural terrain heightmaps, cloud textures, or any effect that
    /// benefits from smooth stochastic variation. Requires `SUPPORT_IMAGE_GENERATION`.
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_perlin_noise(
        &self,
        width: i32,
        height: i32,
        offset_x: i32,
        offset_y: i32,
        scale: f32,
    ) -> Image {
        Image(unsafe { ffi::GenImagePerlinNoise(width, height, offset_x, offset_y, scale) })
    }

    /// Generates an Image containing a radial gradient.
    #[inline]
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_gradient_radial(
        width: i32,
        height: i32,
        density: f32,
        inner: impl Into<ffi::Color>,
        outer: impl Into<ffi::Color>,
    ) -> Image {
        unsafe {
            Image(ffi::GenImageGradientRadial(
                width,
                height,
                density,
                inner.into(),
                outer.into(),
            ))
        }
    }

    /// Generates an Image containing a checkerboard pattern.
    #[inline]
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_checked(
        width: i32,
        height: i32,
        checks_x: i32,
        checks_y: i32,
        col1: impl Into<ffi::Color>,
        col2: impl Into<ffi::Color>,
    ) -> Image {
        unsafe {
            Image(ffi::GenImageChecked(
                width,
                height,
                checks_x,
                checks_y,
                col1.into(),
                col2.into(),
            ))
        }
    }

    /// Generate images an image linear gradient.
    /// `direction` in expected to be degrees [0..360]. 0 results in a vertical gradient
    #[must_use]
    #[inline]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_gradient_linear(
        width: i32,
        height: i32,
        direction: i32,
        start: Color,
        end: Color,
    ) -> Image {
        unsafe {
            Image(ffi::GenImageGradientLinear(
                width, height, direction, start, end,
            ))
        }
    }
    #[must_use]
    #[inline]
    /// Generate images an image with a square gradient
    /// For best results, `density` should be `0.0..1.0``
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_gradient_square(
        width: i32,
        height: i32,
        density: f32,
        start: Color,
        end: Color,
    ) -> Image {
        unsafe {
            Image(ffi::GenImageGradientSquare(
                width, height, density, start, end,
            ))
        }
    }

    /// Generates a grayscale image whose pixel data is initialised with the raw bytes of `text`.
    ///
    /// Wraps raylib's `GenImageText`. The returned image is `width × height` pixels in
    /// `PixelFormat::PIXELFORMAT_UNCOMPRESSED_GRAYSCALE` (one byte per pixel); the first
    /// `min(text.len(), width * height)` bytes are copied from `text` and the rest are
    /// zero. This is a low-level data-packing helper — it does **not** rasterize glyphs.
    /// For rasterized text use [`Image::image_text`] (or the `RaylibDraw::draw_text`
    /// family on a draw handle).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "software_renderer")] {
    /// use raylib::prelude::*;
    /// use raylib::test_harness::*;
    ///
    /// with_headless(64, 32, |rl, thread| {
    ///     // Bytes of "HELLO" land at offsets 0..5 of the grayscale buffer.
    ///     let img = Image::gen_image_text(64, 32, "HELLO");
    ///     assert_eq!(img.width(), 64);
    ///     assert_eq!(img.height(), 32);
    ///     // First pixel is 'H' = 0x48 = 72 on every channel (grayscale → RGB).
    ///     let p0 = img.get_color(0, 0);
    ///     assert_eq!(p0.r, b'H');
    ///     // Upload + draw to verify the texture round-trips through the GPU path.
    ///     let tex = rl
    ///         .load_texture_from_image(thread, &img)
    ///         .expect("texture upload");
    ///     let frame = render_frame(rl, thread, |d| {
    ///         d.clear_background(Color::BLACK);
    ///         d.draw_texture(&tex, 0, 0, Color::WHITE);
    ///     });
    ///     // Pixel (0, 0) corresponds to 'H' → grayscale 0x48 ≈ (72, 72, 72).
    ///     assert_pixel(&frame, 0, 0, Color::new(0x48, 0x48, 0x48, 255), 4);
    /// });
    /// # }
    /// ```
    ///
    /// # See also
    ///
    /// - [`Image::image_text`] — rasterized text into an image.
    /// - [`Image::gen_image_color`] — solid-fill counterpart.
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_text(width: i32, height: i32, text: &str) -> Image {
        let c_str = CString::new(text).unwrap();
        unsafe { Image(ffi::GenImageText(width, height, c_str.as_ptr())) }
    }

    /// Generates an Image containing white noise.
    #[inline]
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_white_noise(width: i32, height: i32, factor: f32) -> Image {
        unsafe { Image(ffi::GenImageWhiteNoise(width, height, factor)) }
    }

    /// Generates an Image using a cellular algorithm. Bigger `tile_size` means bigger cells.
    #[inline]
    #[must_use]
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    pub fn gen_image_cellular(width: i32, height: i32, tile_size: i32) -> Image {
        unsafe { Image(ffi::GenImageCellular(width, height, tile_size)) }
    }

    /// Get clipboard image.
    ///
    /// NOTE: Only available on Windows. Do not use if you plan to compile to other platforms.
    #[cfg(target_os = "windows")]
    pub fn get_clipboard_image(&mut self) -> Result<Image, InvalidImageError> {
        let i = unsafe { ffi::GetClipboardImage() };
        if i.data.is_null() {
            return Err(InvalidImageError::NullData);
        }
        Ok(Image(i))
    }

    /// Loads an image from a file path into CPU memory.
    ///
    /// Supported formats depend on which `SUPPORT_FILEFORMAT_*` features were compiled in.
    /// With the `full` feature, PNG, BMP, TGA, JPG, GIF, QOI, PSD, DDS, HDR, PIC, PNM,
    /// KTX, ASTC, PKM, and PVR are all available.
    ///
    /// To display the image, upload it to the GPU with [`RaylibHandle::load_texture_from_image`].
    pub fn load_image(filename: &str) -> Result<Image, InvalidImageError> {
        let c_filename = CString::new(filename).unwrap();
        let i = unsafe { ffi::LoadImage(c_filename.as_ptr()) };
        if i.data.is_null() {
            return Err(InvalidImageError::NullDataFromFile);
        }
        Ok(Image(i))
    }

    /// Loads image from a given memory buffer
    /// The input data is expected to be in a supported file format such as png. Which formats are
    /// supported depend on the build flags used for the raylib (C) library.
    pub fn load_image_from_mem(filetype: &str, bytes: &[u8]) -> Result<Image, InvalidImageError> {
        let c_filetype = CString::new(filetype).unwrap();
        let data_size = bytes.len().try_into().unwrap();
        if data_size == 0 {
            return Err(InvalidImageError::InvalidFile);
        }
        let i = unsafe { ffi::LoadImageFromMemory(c_filetype.as_ptr(), bytes.as_ptr(), data_size) };
        if i.data.is_null() {
            return Err(InvalidImageError::NullDataFromMemory);
        };
        Ok(Image(i))
    }

    /// Load image sequence from file, with the number of frames loaded saved to frame_num.
    /// Image.data buffer includes all frames.
    /// All frames returned are in RGBA format.
    /// Frames delay data is discarded
    #[must_use]
    pub fn load_image_anim(filename: &str, frame_num: &mut i32) -> Self {
        let c_filename = CString::new(filename).unwrap();

        unsafe { Image(ffi::LoadImageAnim(c_filename.as_ptr(), frame_num)) }
    }

    /// Load image from memory buffer, with the number of frames loaded saved to frame_num.
    /// fileType refers to extension: i.e. ".png". File extension must be provided in lower-case
    #[must_use]
    pub fn load_image_anim_from_memory(filetype: &str, data: &[u8], frame_num: &mut i32) -> Self {
        let c_filetype = CString::new(filetype).unwrap();

        unsafe {
            Image(ffi::LoadImageAnimFromMemory(
                c_filetype.as_ptr(),
                data.as_ptr(),
                data.len() as i32,
                frame_num,
            ))
        }
    }

    /// Loads image from RAW file data.
    pub fn load_image_raw(
        filename: &str,
        width: i32,
        height: i32,
        format: i32,
        header_size: i32,
    ) -> Result<Image, InvalidImageError> {
        let c_filename = CString::new(filename).unwrap();
        let i =
            unsafe { ffi::LoadImageRaw(c_filename.as_ptr(), width, height, format, header_size) };
        if i.data.is_null() {
            return Err(InvalidImageError::NullDataFromFile);
        }
        Ok(Image(i))
    }

    /// Creates an image from `text` (custom font).
    #[inline]
    #[must_use]
    pub fn image_text(text: &str, font_size: i32, color: impl Into<ffi::Color>) -> Image {
        let c_text = CString::new(text).unwrap();
        unsafe { Image(ffi::ImageText(c_text.as_ptr(), font_size, color.into())) }
    }

    /// Creates an image from `text` (custom font).
    #[inline]
    #[must_use]
    pub fn image_text_ex(
        font: impl std::convert::AsRef<ffi::Font>,
        text: &str,
        font_size: f32,
        spacing: f32,
        tint: impl Into<ffi::Color>,
    ) -> Image {
        let c_text = CString::new(text).unwrap();
        unsafe {
            Image(ffi::ImageTextEx(
                *font.as_ref(),
                c_text.as_ptr(),
                font_size,
                spacing,
                tint.into(),
            ))
        }
    }

    /// Check if an image is valid (data and parameters)
    #[inline]
    #[must_use]
    pub fn is_image_valid(&self) -> bool {
        unsafe { ffi::IsImageValid(self.0) }
    }
}

impl RaylibTexture2D for WeakTexture2D {}
impl RaylibTexture2D for Texture2D {}
impl RaylibTexture2D for WeakRenderTexture2D {}
impl RaylibTexture2D for RenderTexture2D {}

impl Texture2D {
    /// # Safety
    ///
    /// The caller becomes responsible for ensuring the underlying `ffi::Texture2D` is eventually
    /// unloaded. The returned `WeakTexture2D` does not call `UnloadTexture` on drop.
    pub unsafe fn make_weak(self) -> WeakTexture2D {
        let m = WeakTexture2D(self.0);
        std::mem::forget(self);
        m
    }
}

/// Extension methods for types that wrap a raylib `Texture2D` (both owned [`Texture2D`] and [`WeakTexture2D`]).
///
/// Implemented for [`Texture2D`] (RAII-owned, freed on drop) and [`WeakTexture2D`] (no-drop
/// alias from [`Texture2D::make_weak`]). Provides the field accessors
/// ([`width`](Self::width), [`height`](Self::height), [`mipmaps`](Self::mipmaps),
/// [`format`](Self::format)), GPU upload helpers ([`update_texture`](Self::update_texture),
/// [`update_texture_rec`](Self::update_texture_rec)), readback to a CPU
/// [`Image`] ([`load_image`](Self::load_image)), mipmap generation
/// ([`gen_texture_mipmaps`](Self::gen_texture_mipmaps)), and the sampler-state setters
/// ([`set_texture_filter`](Self::set_texture_filter),
/// [`set_texture_wrap`](Self::set_texture_wrap)).
///
/// # Examples
///
/// ```no_run
/// use raylib::prelude::*;
/// use raylib::core::texture::RaylibTexture2D;
///
/// let (mut rl, thread) = raylib::init().size(640, 480).title("tex").build();
/// let tex = rl
///     .load_texture(&thread, "assets/sprite.png")
///     .expect("texture load");
/// println!("{}x{}, mipmaps {}", tex.width(), tex.height(), tex.mipmaps());
/// while !rl.window_should_close() {
///     let mut d = rl.begin_drawing(&thread);
///     d.clear_background(Color::RAYWHITE);
///     d.draw_texture(&tex, 0, 0, Color::WHITE);
/// }
/// ```
///
/// # See also
///
/// - [`Texture2D`] — owning texture handle.
/// - [`Image`] — CPU-side counterpart; upload with
///   [`RaylibHandle::load_texture_from_image`].
/// - [`RaylibRenderTexture2D`] — companion trait for offscreen render targets.
pub trait RaylibTexture2D: AsRef<ffi::Texture2D> + AsMut<ffi::Texture2D> {
    /// Texture base width
    #[inline]
    #[must_use]
    fn width(&self) -> i32 {
        self.as_ref().width
    }

    /// Texture base height
    #[inline]
    #[must_use]
    fn height(&self) -> i32 {
        self.as_ref().height
    }

    /// Mipmap levels, 1 by default
    #[inline]
    #[must_use]
    fn mipmaps(&self) -> i32 {
        self.as_ref().mipmaps
    }

    /// Data format (PixelFormat type)
    #[inline]
    #[must_use]
    fn format(&self) -> i32 {
        self.as_ref().format
    }

    /// Updates GPU texture with new data.
    #[inline]
    fn update_texture(&mut self, pixels: &[u8]) -> Result<(), UpdateTextureError> {
        let expected_len = unsafe {
            get_pixel_data_size(
                self.as_ref().width,
                self.as_ref().height,
                std::mem::transmute::<i32, ffi::PixelFormat>(self.as_ref().format),
            ) as usize
        };
        if pixels.len() != expected_len {
            return Err(UpdateTextureError::WrongDataSize {
                expect: expected_len,
                actual: pixels.len(),
            });
        }
        unsafe {
            ffi::UpdateTexture(
                *self.as_mut(),
                pixels.as_ptr() as *const std::os::raw::c_void,
            );
        }

        Ok(())
    }

    /// Update GPU texture rectangle with new data
    fn update_texture_rec(
        &mut self,
        rec: impl Into<ffi::Rectangle>,
        pixels: &[u8],
    ) -> Result<(), UpdateTextureError> {
        let rec = rec.into();

        if (rec.x < 0.0)
            || (rec.y < 0.0)
            || ((rec.x as i32 + rec.width as i32) > (self.as_ref().width))
            || ((rec.y as i32 + rec.height as i32) > (self.as_ref().height))
        {
            return Err(UpdateTextureError::OutOfBounds);
        }
        if (rec.width < 0.0) || (rec.height < 0.0) {
            return Err(UpdateTextureError::NegativeSize);
        }

        let expected_len = unsafe {
            get_pixel_data_size(
                rec.width as i32,
                rec.height as i32,
                std::mem::transmute::<i32, ffi::PixelFormat>(self.as_ref().format),
            ) as usize
        };
        if pixels.len() != expected_len {
            return Err(UpdateTextureError::WrongDataSize {
                expect: expected_len,
                actual: pixels.len(),
            });
        }
        unsafe {
            ffi::UpdateTextureRec(
                *self.as_ref(),
                rec,
                pixels.as_ptr() as *const std::os::raw::c_void,
            )
        }

        Ok(())
    }

    /// Gets pixel data from GPU texture and returns an `Image`.
    /// Fairly sure this would never fail. If it does wrap in result.
    #[inline]
    fn load_image(&self) -> Result<Image, InvalidImageError> {
        let i = unsafe { ffi::LoadImageFromTexture(*self.as_ref()) };
        if i.data.is_null() {
            return Err(InvalidImageError::NullDataFromTexture);
        }
        Ok(Image(i))
    }

    /// Generates GPU mipmaps for a `texture`.
    #[inline]
    fn gen_texture_mipmaps(&mut self) {
        unsafe {
            ffi::GenTextureMipmaps(self.as_mut());
        }
    }

    /// Sets global `texture` scaling filter mode.
    #[inline]
    fn set_texture_filter(&self, _: &RaylibThread, filter_mode: crate::consts::TextureFilter) {
        unsafe {
            ffi::SetTextureFilter(*self.as_ref(), filter_mode as i32);
        }
    }

    /// Sets global texture wrapping mode.
    #[inline]
    fn set_texture_wrap(&self, _: &RaylibThread, wrap_mode: crate::consts::TextureWrap) {
        unsafe {
            ffi::SetTextureWrap(*self.as_ref(), wrap_mode as i32);
        }
    }

    /// Check if a texture is valid (loaded in GPU)
    #[inline]
    fn is_texture_valid(&self) -> bool {
        unsafe { ffi::IsTextureValid(*self.as_ref()) }
    }
}

/// Gets pixel data size in bytes (image or texture).
#[inline]
pub fn get_pixel_data_size(width: i32, height: i32, format: ffi::PixelFormat) -> i32 {
    unsafe { ffi::GetPixelDataSize(width, height, format as i32) }
}

impl RaylibHandle {
    /// Loads texture from file into GPU memory (VRAM).
    pub fn load_texture(
        &mut self,
        _: &RaylibThread,
        filename: &str,
    ) -> Result<Texture2D, LoadTextureError> {
        let c_filename = CString::new(filename).unwrap();
        let t = unsafe { ffi::LoadTexture(c_filename.as_ptr()) };
        if t.id == 0 {
            return Err(LoadTextureError::TextureFromFileFailed {
                path: filename.into(),
            });
        }
        Ok(Texture2D(t))
    }

    /// Load cubemap from image, multiple image cubemap layouts supported
    pub fn load_texture_cubemap(
        &mut self,
        _: &RaylibThread,
        image: &Image,
        layout: crate::consts::CubemapLayout,
    ) -> Result<Texture2D, LoadTextureError> {
        let t = unsafe { ffi::LoadTextureCubemap(image.0, layout as i32) };
        if t.id == 0 {
            return Err(LoadTextureError::CubemapFromImageFailed);
        }
        Ok(Texture2D(t))
    }

    /// Loads texture from image data.
    #[inline]
    pub fn load_texture_from_image(
        &mut self,
        _: &RaylibThread,
        image: &Image,
    ) -> Result<Texture2D, LoadTextureError> {
        if image.width == 0 || image.height == 0 {
            return Err(LoadTextureError::InvalidData);
        }
        let t = unsafe { ffi::LoadTextureFromImage(image.0) };
        if t.id == 0 {
            return Err(LoadTextureError::TextureFromImageFailed);
        }
        Ok(Texture2D(t))
    }

    /// Loads texture for rendering (framebuffer).
    pub fn load_render_texture(
        &mut self,
        _: &RaylibThread,
        width: u32,
        height: u32,
    ) -> Result<RenderTexture2D, LoadTextureError> {
        let t = unsafe { ffi::LoadRenderTexture(width as i32, height as i32) };
        if t.id == 0 {
            return Err(LoadTextureError::CreateRenderTextureFailed);
        }
        Ok(RenderTexture2D(t))
    }
}

impl RaylibHandle {
    /// Unload texture from GPU memory (VRAM).
    ///
    /// # Safety
    ///
    /// `texture` must not be used after this call. Weak textures will leak memory if not unloaded.
    #[inline]
    pub unsafe fn unload_texture(&mut self, _: &RaylibThread, texture: WeakTexture2D) {
        unsafe { ffi::UnloadTexture(*texture.as_ref()) }
    }
    /// Unload render texture from GPU memory (VRAM).
    ///
    /// # Safety
    ///
    /// `texture` must not be used after this call. Weak render textures will leak if not unloaded.
    #[inline]
    pub unsafe fn unload_render_texture(&mut self, _: &RaylibThread, texture: WeakRenderTexture2D) {
        unsafe { ffi::UnloadRenderTexture(*texture.as_ref()) }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    // Color is only used by the SUPPORT_IMAGE_GENERATION-gated test below.
    // Scoping the import to the same gate avoids an unused_imports warning
    // when the feature is off (clippy -Dwarnings would fail otherwise).
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    use crate::ffi::Color;

    /// Salvaged from raylib-test/src/texture.rs `test_image_loading`.
    /// Image is CPU-side; no window context needed. The happy-path
    /// load asserts only when the PNG decoder feature is enabled
    /// (raylib's image-format support is feature-gated).
    #[test]
    fn image_load_from_file_happy_and_error() {
        // Happy: load the bundled fixture. Gated on PNG support because
        // raylib's image-format decoders are feature-gated.
        #[cfg(feature = "SUPPORT_FILEFORMAT_PNG")]
        {
            let path = "tests/fixtures/billboard.png";
            if std::path::Path::new(path).exists() {
                let img = Image::load_image(path).expect("billboard.png loads");
                assert!(img.width() > 0, "loaded image has non-zero width");
                assert!(img.height() > 0, "loaded image has non-zero height");
            } else {
                eprintln!("SKIP: {path} not found (cargo invoked from a non-workspace-root cwd?)");
            }
        }

        // Error: nonexistent path returns Err.
        Image::load_image("tests/fixtures/does_not_exist.png")
            .expect_err("nonexistent file should error");
    }

    /// Salvaged from raylib-test/src/texture.rs `test_image_manipulations`.
    /// Exercises the Image CPU-side API without a window context.
    #[cfg(feature = "SUPPORT_IMAGE_GENERATION")]
    #[test]
    fn image_manipulations_no_segfault() {
        let mut i = Image::gen_image_color(32, 32, Color::new(230, 41, 55, 255));
        let mut canvas = Image::gen_image_color(32, 32, Color::new(0, 0, 0, 0));
        let mask = Image::gen_image_checked(
            32,
            32,
            8,
            8,
            Color::new(255, 255, 255, 255),
            Color::new(0, 0, 0, 0),
        );

        let mut c = i.clone();
        c.alpha_mask(&mask);
        c.alpha_clear(Color::new(0, 0, 255, 255), 0.5);
        c.alpha_crop(0.5);
        c.alpha_premultiply();

        let mut blurry = c.clone();
        blurry.resize(64, 64);
        c.resize_nn(64, 64);
        i.resize_canvas(64, 64, 10, 10, Color::new(0, 0, 255, 255));

        c.gen_mipmaps();
        blurry.dither(128, 128, 128, 128);

        let colors = c.extract_palette(100);
        assert_eq!(
            colors.len(),
            2,
            "checker-masked single-color image has 2-color palette"
        );

        canvas.draw(
            &i,
            Rectangle::new(0.0, 0.0, 20.0, 20.0),
            Rectangle::new(0.0, 0.0, 20.0, 20.0),
            Color::new(255, 255, 255, 255),
        );
        canvas.draw_rectangle_lines(
            Rectangle::new(20.0, 0.0, 20.0, 20.0),
            4,
            Color::new(0, 228, 48, 255),
        );
        canvas.draw_rectangle(40, 0, 20, 20, Color::new(255, 161, 0, 255));

        canvas.flip_vertical();
        canvas.flip_horizontal();
        canvas.rotate_cw();
        canvas.rotate_ccw();

        canvas.color_tint(Color::new(255, 109, 194, 255));
        canvas.color_invert();
        canvas.color_contrast(0.5);
        canvas.color_brightness(128);
        canvas.color_replace(Color::new(0, 228, 48, 255), Color::new(230, 41, 55, 255));

        // Test reaches here = no segfault during the manipulation pipeline.
    }
}