dear_imgui_rs/

texture.rs

//! Texture management for Dear ImGui
//!
//! This module provides access to Dear ImGui's modern texture management system
//! introduced in version 1.92+. It includes support for ImTextureData, texture
//! status management, and automatic texture updates.

use crate::sys;
use std::ffi::c_void;

/// Simple texture ID for backward compatibility
///
/// This is a simple wrapper around u64 that can be used to identify textures.
/// For modern texture management, use TextureData instead.
///
/// Note: Changed from usize to u64 in Dear ImGui 1.91.4+ to support 64-bit handles
/// like Vulkan and DX12 on 32-bit targets.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
#[repr(transparent)]
pub struct TextureId(u64);

impl TextureId {
    /// Creates a new texture id with the given identifier
    #[inline]
    pub const fn new(id: u64) -> Self {
        Self(id)
    }

    /// Returns the id of the TextureId
    #[inline]
    pub const fn id(self) -> u64 {
        self.0
    }

    /// Creates a null texture ID
    #[inline]
    pub const fn null() -> Self {
        Self(0)
    }

    /// Checks if this texture ID is null
    #[inline]
    pub const fn is_null(self) -> bool {
        self.0 == 0
    }
}

impl From<u64> for TextureId {
    #[inline]
    fn from(id: u64) -> Self {
        TextureId(id)
    }
}

impl<T> From<*const T> for TextureId {
    #[inline]
    fn from(ptr: *const T) -> Self {
        TextureId(ptr as usize as u64)
    }
}

impl<T> From<*mut T> for TextureId {
    #[inline]
    fn from(ptr: *mut T) -> Self {
        TextureId(ptr as usize as u64)
    }
}

impl From<TextureId> for *const c_void {
    #[inline]
    fn from(id: TextureId) -> Self {
        id.0 as usize as *const c_void
    }
}

impl From<TextureId> for *mut c_void {
    #[inline]
    fn from(id: TextureId) -> Self {
        id.0 as usize as *mut c_void
    }
}

// Backward compatibility: allow conversion from usize for legacy code
impl From<usize> for TextureId {
    #[inline]
    fn from(id: usize) -> Self {
        TextureId(id as u64)
    }
}

// Allow conversion to usize for legacy code
impl From<TextureId> for usize {
    #[inline]
    fn from(id: TextureId) -> Self {
        id.0 as usize
    }
}

impl Default for TextureId {
    #[inline]
    fn default() -> Self {
        Self::null()
    }
}

/// Raw texture ID type for compatibility with Dear ImGui
pub type RawTextureId = *const c_void;

/// A convenient, typed wrapper around ImGui's ImTextureRef (v1.92+)
///
/// Can reference either a plain `TextureId` (legacy path) or a managed `TextureData`.
///
/// Examples
/// - With a plain GPU handle (legacy path):
/// ```no_run
/// # use dear_imgui_rs::{Ui, TextureId};
/// # fn demo(ui: &Ui) {
/// let tex_id = TextureId::new(12345);
/// ui.image(tex_id, [64.0, 64.0]);
/// # }
/// ```
/// - With a managed texture (ImGui 1.92 texture system):
/// ```no_run
/// # use dear_imgui_rs::{Ui, texture::{TextureData, TextureFormat}};
/// # fn demo(ui: &Ui) {
/// let mut tex = TextureData::new();
/// tex.create(TextureFormat::RGBA32, 256, 256);
/// // Fill pixels or schedule updates...
/// ui.image(&mut *tex, [256.0, 256.0]);
/// // The renderer backend will honor WantCreate/WantUpdates/WantDestroy
/// // via DrawData::textures() when rendering this frame.
/// # }
/// ```
#[derive(Copy, Clone, Debug)]
#[repr(transparent)]
pub struct TextureRef(sys::ImTextureRef);

impl TextureRef {
    /// Create a texture reference from a raw ImGui texture ref
    #[inline]
    pub fn from_raw(raw: sys::ImTextureRef) -> Self {
        Self(raw)
    }

    /// Get the underlying ImGui texture ref (by value)
    #[inline]
    pub fn raw(self) -> sys::ImTextureRef {
        self.0
    }
}

impl From<TextureId> for TextureRef {
    #[inline]
    fn from(id: TextureId) -> Self {
        TextureRef(sys::ImTextureRef {
            _TexData: std::ptr::null_mut(),
            _TexID: id.id() as sys::ImTextureID,
        })
    }
}

impl From<u64> for TextureRef {
    #[inline]
    fn from(id: u64) -> Self {
        TextureRef::from(TextureId::from(id))
    }
}

impl From<&TextureData> for TextureRef {
    #[inline]
    fn from(td: &TextureData) -> Self {
        // Safe for immediate use during the frame; the caller must uphold lifetime.
        TextureRef(sys::ImTextureRef {
            _TexData: td.as_raw() as *mut sys::ImTextureData,
            _TexID: 0,
        })
    }
}

impl From<&mut TextureData> for TextureRef {
    #[inline]
    fn from(td: &mut TextureData) -> Self {
        TextureRef(sys::ImTextureRef {
            _TexData: td.as_raw_mut(),
            _TexID: 0,
        })
    }
}

/// Texture format supported by Dear ImGui
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[repr(i32)]
pub enum TextureFormat {
    /// 4 components per pixel, each is unsigned 8-bit. Total size = TexWidth * TexHeight * 4
    RGBA32 = sys::ImTextureFormat_RGBA32 as i32,
    /// 1 component per pixel, each is unsigned 8-bit. Total size = TexWidth * TexHeight
    Alpha8 = sys::ImTextureFormat_Alpha8 as i32,
}

impl From<sys::ImTextureFormat> for TextureFormat {
    fn from(format: sys::ImTextureFormat) -> Self {
        match format {
            sys::ImTextureFormat_RGBA32 => TextureFormat::RGBA32,
            sys::ImTextureFormat_Alpha8 => TextureFormat::Alpha8,
            _ => TextureFormat::RGBA32, // Default fallback
        }
    }
}

impl From<TextureFormat> for sys::ImTextureFormat {
    fn from(format: TextureFormat) -> Self {
        format as sys::ImTextureFormat
    }
}

/// Status of a texture to communicate with Renderer Backend
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[repr(i32)]
pub enum TextureStatus {
    /// Texture is ready and can be used
    OK = sys::ImTextureStatus_OK as i32,
    /// Backend destroyed the texture
    Destroyed = sys::ImTextureStatus_Destroyed as i32,
    /// Requesting backend to create the texture. Set status OK when done.
    WantCreate = sys::ImTextureStatus_WantCreate as i32,
    /// Requesting backend to update specific blocks of pixels. Set status OK when done.
    WantUpdates = sys::ImTextureStatus_WantUpdates as i32,
    /// Requesting backend to destroy the texture. Set status to Destroyed when done.
    WantDestroy = sys::ImTextureStatus_WantDestroy as i32,
}

impl From<sys::ImTextureStatus> for TextureStatus {
    fn from(status: sys::ImTextureStatus) -> Self {
        match status {
            sys::ImTextureStatus_OK => TextureStatus::OK,
            sys::ImTextureStatus_Destroyed => TextureStatus::Destroyed,
            sys::ImTextureStatus_WantCreate => TextureStatus::WantCreate,
            sys::ImTextureStatus_WantUpdates => TextureStatus::WantUpdates,
            sys::ImTextureStatus_WantDestroy => TextureStatus::WantDestroy,
            _ => TextureStatus::Destroyed, // Default fallback
        }
    }
}

impl From<TextureStatus> for sys::ImTextureStatus {
    fn from(status: TextureStatus) -> Self {
        status as sys::ImTextureStatus
    }
}

/// Coordinates of a rectangle within a texture
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub struct TextureRect {
    /// Upper-left X coordinate of rectangle to update
    pub x: u16,
    /// Upper-left Y coordinate of rectangle to update
    pub y: u16,
    /// Width of rectangle to update
    pub w: u16,
    /// Height of rectangle to update
    pub h: u16,
}

impl From<sys::ImTextureRect> for TextureRect {
    fn from(rect: sys::ImTextureRect) -> Self {
        Self {
            x: rect.x,
            y: rect.y,
            w: rect.w,
            h: rect.h,
        }
    }
}

impl From<TextureRect> for sys::ImTextureRect {
    fn from(rect: TextureRect) -> Self {
        Self {
            x: rect.x,
            y: rect.y,
            w: rect.w,
            h: rect.h,
        }
    }
}

/// Texture data managed by Dear ImGui
///
/// This is a wrapper around ImTextureData that provides safe access to
/// texture information and pixel data. It's used by renderer backends
/// to create, update, and destroy textures.
///
/// Lifecycle & Backend Flow (ImGui 1.92+)
/// - Create an instance (e.g. via `TextureData::new()` + `create()`)
/// - Mutate pixels, set flags/rects (e.g. call `set_data()` or directly write `Pixels` then
///   set `UpdateRect`), and set status to `WantCreate`/`WantUpdates`.
/// - When you pass `&mut TextureData` to any widget/draw call, Dear ImGui will place this
///   texture into `DrawData::textures()` for the current frame.
/// - Your renderer backend iterates `DrawData::textures()` and performs the requested
///   create/update/destroy operations, then updates status to `OK`/`Destroyed`.
/// - You can also set/get a `TexID` (e.g., GPU handle) via `set_tex_id()/tex_id()` after creation.
///
/// Lifetime Note: If using the managed path, you must keep `TextureData` alive at least until the
/// end of the frame where it is referenced by UI calls. Prefer owning containers like `Box`/`Arc`.
#[repr(transparent)]
pub struct TextureData {
    raw: sys::ImTextureData,
}

impl TextureData {
    /// Create a new empty texture data
    ///
    /// This creates a new TextureData instance with default values.
    /// The texture will be in Destroyed status and needs to be created with `create()`.
    pub fn new() -> Box<Self> {
        // Initialize via ImGui constructor to inherit default changes safely
        let raw = unsafe {
            let p = sys::ImTextureData_ImTextureData();
            let v = *p;
            sys::ImTextureData_destroy(p);
            v
        };
        let raw_data = Box::new(raw);
        unsafe { Box::from_raw(Box::into_raw(raw_data) as *mut Self) }
    }

    /// Create a new texture data from raw pointer (crate-internal)
    ///
    /// Safety: caller must ensure the pointer is valid for the returned lifetime.
    pub(crate) unsafe fn from_raw<'a>(raw: *mut sys::ImTextureData) -> &'a mut Self {
        unsafe { &mut *(raw as *mut Self) }
    }

    /// Get the raw pointer to the underlying ImTextureData
    pub fn as_raw(&self) -> *const sys::ImTextureData {
        &self.raw as *const _
    }

    /// Get the raw mutable pointer to the underlying ImTextureData
    pub fn as_raw_mut(&mut self) -> *mut sys::ImTextureData {
        &mut self.raw as *mut _
    }

    /// Get the unique ID of this texture (for debugging)
    pub fn unique_id(&self) -> i32 {
        self.raw.UniqueID
    }

    /// Get the current status of this texture
    pub fn status(&self) -> TextureStatus {
        TextureStatus::from(self.raw.Status)
    }

    /// Set the status of this texture
    ///
    /// This should only be called by renderer backends after handling a request.
    pub fn set_status(&mut self, status: TextureStatus) {
        self.raw.Status = status.into();
    }

    /// Get the backend user data
    pub fn backend_user_data(&self) -> *mut c_void {
        self.raw.BackendUserData
    }

    /// Set the backend user data
    pub fn set_backend_user_data(&mut self, data: *mut c_void) {
        self.raw.BackendUserData = data;
    }

    /// Get the texture ID
    pub fn tex_id(&self) -> TextureId {
        TextureId::from(self.raw.TexID)
    }

    /// Set the texture ID
    ///
    /// This should only be called by renderer backends after creating or destroying the texture.
    pub fn set_tex_id(&mut self, tex_id: TextureId) {
        self.raw.TexID = tex_id.id() as sys::ImTextureID;
    }

    /// Get the texture format
    pub fn format(&self) -> TextureFormat {
        TextureFormat::from(self.raw.Format)
    }

    /// Get the texture width
    pub fn width(&self) -> i32 {
        self.raw.Width
    }

    /// Get the texture height
    pub fn height(&self) -> i32 {
        self.raw.Height
    }

    /// Get the bytes per pixel
    pub fn bytes_per_pixel(&self) -> i32 {
        self.raw.BytesPerPixel
    }

    /// Get the number of unused frames
    pub fn unused_frames(&self) -> i32 {
        self.raw.UnusedFrames
    }

    /// Get the reference count
    pub fn ref_count(&self) -> u16 {
        self.raw.RefCount
    }

    /// Check if the texture uses colors (rather than just white + alpha)
    pub fn use_colors(&self) -> bool {
        self.raw.UseColors
    }

    /// Check if the texture is queued for destruction next frame
    pub fn want_destroy_next_frame(&self) -> bool {
        self.raw.WantDestroyNextFrame
    }

    /// Get the pixel data
    ///
    /// Returns None if no pixel data is available.
    pub fn pixels(&self) -> Option<&[u8]> {
        if self.raw.Pixels.is_null() {
            None
        } else {
            let size = (self.width() * self.height() * self.bytes_per_pixel()) as usize;
            unsafe {
                Some(std::slice::from_raw_parts(
                    self.raw.Pixels as *const u8,
                    size,
                ))
            }
        }
    }

    /// Get the bounding box of all used pixels in the texture
    pub fn used_rect(&self) -> TextureRect {
        unsafe { TextureRect::from((*self.as_raw()).UsedRect) }
    }

    /// Get the bounding box of all queued updates
    pub fn update_rect(&self) -> TextureRect {
        unsafe { TextureRect::from((*self.as_raw()).UpdateRect) }
    }

    /// Iterate over queued update rectangles (copying to safe TextureRect)
    pub fn updates(&self) -> impl Iterator<Item = TextureRect> + '_ {
        unsafe {
            let vec = &(*self.as_raw()).Updates;
            let count = vec.Size as usize;
            let data = vec.Data as *const sys::ImTextureRect;
            (0..count).map(move |i| TextureRect::from(*data.add(i)))
        }
    }

    /// Get the pixel data at a specific position
    ///
    /// Returns None if no pixel data is available or coordinates are out of bounds.
    pub fn pixels_at(&self, x: i32, y: i32) -> Option<&[u8]> {
        if self.raw.Pixels.is_null() || x < 0 || y < 0 || x >= self.width() || y >= self.height() {
            None
        } else {
            let offset = (x + y * self.width()) * self.bytes_per_pixel();
            let remaining_size = ((self.width() - x) + (self.height() - y - 1) * self.width())
                * self.bytes_per_pixel();
            unsafe {
                let ptr = (self.raw.Pixels as *const u8).add(offset as usize);
                Some(std::slice::from_raw_parts(ptr, remaining_size as usize))
            }
        }
    }

    /// Get the pitch (bytes per row)
    pub fn pitch(&self) -> i32 {
        self.width() * self.bytes_per_pixel()
    }

    /// Create a new texture with the specified format and dimensions
    ///
    /// This allocates pixel data and sets the status to WantCreate.
    pub fn create(&mut self, format: TextureFormat, width: i32, height: i32) {
        unsafe {
            sys::ImTextureData_Create(self.as_raw_mut(), format.into(), width, height);
        }
    }

    /// Destroy the pixel data
    ///
    /// This frees the CPU-side pixel data but doesn't affect the GPU texture.
    pub fn destroy_pixels(&mut self) {
        unsafe {
            sys::ImTextureData_DestroyPixels(self.as_raw_mut());
        }
    }

    /// Set the pixel data for the texture
    ///
    /// This copies the provided data into the texture's pixel buffer.
    pub fn set_data(&mut self, data: &[u8]) {
        unsafe {
            let raw = self.as_raw_mut();
            let needed = (*raw)
                .Width
                .saturating_mul((*raw).Height)
                .saturating_mul((*raw).BytesPerPixel);
            if needed <= 0 {
                // Nothing to do without valid dimensions/format.
                return;
            }

            // Ensure pixel buffer exists and has correct size
            if (*raw).Pixels.is_null() {
                sys::ImTextureData_Create(
                    self.as_raw_mut(),
                    (*raw).Format,
                    (*raw).Width,
                    (*raw).Height,
                );
            }

            let copy_bytes = std::cmp::min(needed as usize, data.len());
            if copy_bytes == 0 {
                return;
            }

            std::ptr::copy_nonoverlapping(data.as_ptr(), (*raw).Pixels as *mut u8, copy_bytes);

            // Mark entire texture as updated
            (*raw).UpdateRect = sys::ImTextureRect {
                x: 0u16,
                y: 0u16,
                w: (*raw).Width.clamp(0, u16::MAX as i32) as u16,
                h: (*raw).Height.clamp(0, u16::MAX as i32) as u16,
            };
            (*raw).Status = sys::ImTextureStatus_WantUpdates;
        }
    }

    /// Set the width of the texture
    pub fn set_width(&mut self, width: u32) {
        unsafe {
            (*self.as_raw_mut()).Width = width as i32;
        }
    }

    /// Set the height of the texture
    pub fn set_height(&mut self, height: u32) {
        unsafe {
            (*self.as_raw_mut()).Height = height as i32;
        }
    }

    /// Set the format of the texture
    pub fn set_format(&mut self, format: TextureFormat) {
        unsafe {
            (*self.as_raw_mut()).Format = format.into();
        }
    }
}

/// Get the number of bytes per pixel for a texture format
pub fn get_format_bytes_per_pixel(format: TextureFormat) -> i32 {
    unsafe { sys::igImTextureDataGetFormatBytesPerPixel(format.into()) }
}

/// Create an ImTextureRef from a texture ID
///
/// This is the safe way to create an ImTextureRef for use with Dear ImGui.
/// Use this instead of directly constructing the sys::ImTextureRef structure.
pub fn create_texture_ref(texture_id: u64) -> sys::ImTextureRef {
    sys::ImTextureRef {
        _TexData: std::ptr::null_mut(),
        _TexID: texture_id,
    }
}

/// Get the name of a texture status (for debugging)
pub fn get_status_name(status: TextureStatus) -> &'static str {
    unsafe {
        let ptr = sys::igImTextureDataGetStatusName(status.into());
        if ptr.is_null() {
            "Unknown"
        } else {
            std::ffi::CStr::from_ptr(ptr).to_str().unwrap_or("Invalid")
        }
    }
}

/// Get the name of a texture format (for debugging)
pub fn get_format_name(format: TextureFormat) -> &'static str {
    unsafe {
        let ptr = sys::igImTextureDataGetFormatName(format.into());
        if ptr.is_null() {
            "Unknown"
        } else {
            std::ffi::CStr::from_ptr(ptr).to_str().unwrap_or("Invalid")
        }
    }
}