viewport-lib-types 0.2.0

Pure-data types for viewport-lib: submission payloads, handles, and frame config, free of any GPU dependency.
Documentation
//! Texture-sampling parameters and ids for textured overlay items.

/// Handle to an overlay shape texture.
///
/// Pass this to `OverlayShapeItem::texture` (or `OverlayPolylineItem::texture`)
/// to use the image as fill. Obtain one from `DeviceResources::upload_overlay_texture`
/// (a one-shot upload) or `create_streaming_overlay_texture` (a reusable texture
/// you feed with `update_overlay_texture` each frame). Release it with
/// `free_overlay_texture`.
///
/// Wraps a packed slot index (low 32 bits) and generation (high 32 bits). A
/// handle whose texture was freed (its slot reused by a later upload) carries a
/// stale generation and resolves to `None` on lookup, so it cannot alias
/// whatever now occupies the slot. For a texture that is never freed the
/// generation is 0, so the handle's raw value equals its dense slot index.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct OverlayTextureId(pub(crate) u64);

impl OverlayTextureId {
    /// A handle that refers to no texture. Store lookups always return `None`
    /// for it. Use it as the default / placeholder value.
    pub const INVALID: OverlayTextureId = OverlayTextureId(u64::MAX);

    /// The raw slot index this handle points at.
    pub fn index(&self) -> usize {
        (self.0 as u32) as usize
    }
}

impl crate::ids::ContentHandle for OverlayTextureId {
    const INVALID: Self = OverlayTextureId(u64::MAX);

    fn index(&self) -> usize {
        (self.0 as u32) as usize
    }

    fn generation(&self) -> u32 {
        (self.0 >> 32) as u32
    }

    fn from_parts(index: u32, generation: u32) -> Self {
        OverlayTextureId(((generation as u64) << 32) | index as u64)
    }
}

/// Nine-patch / 9-slice texture sampling parameters.
///
/// Treats the bound texture as a panel with four corner regions that stay at
/// their authored pixel size, four edge regions that tile or stretch along one
/// axis, and a centre region that follows both axes. The standard way to ship
/// resizable button, dialog, and scrollbar art without the corners stretching.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct NineSlice {
    /// Inset in *texture pixels* from each edge to the centre region:
    /// `[top, right, bottom, left]`. Defines where the four corner regions end.
    pub insets_px: [f32; 4],
    /// Sampling for the centre region (between all four insets).
    pub centre_mode: TileMode,
    /// Sampling for the four edge regions (between two opposing insets).
    pub edge_mode: TileMode,
}

impl Default for NineSlice {
    fn default() -> Self {
        Self {
            insets_px: [0.0; 4],
            centre_mode: TileMode::Stretch,
            edge_mode: TileMode::Stretch,
        }
    }
}

/// How a texture region remaps its UV coordinate before sampling.
///
/// Shared by [`NineSlice`] and [`TextureTransform`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum TileMode {
    /// Linear stretch across the region. Default; matches non-9-slice
    /// behaviour for backwards compatibility.
    #[default]
    Stretch,
    /// Repeat the source region at its native pixel size.
    Tile,
    /// Repeat the source region with every other tile flipped along the
    /// matching axis, so the seam between tiles is mirrored. Smoothes the
    /// repeat for symmetric textures.
    Mirror,
}

/// Affine transform applied to the texture sample before lookup.
///
/// Lets a single texture pan, scale, rotate, tile, and flip independently
/// of the shape it fills. Use for scrolling marquees inside a shape, zooming
/// detail, rotating an icon without rotating the shape, repeating tile art,
/// and mirroring asymmetric assets.
///
/// The transform applies to the bounding-box UV in [0, 1] coordinates,
/// centred at (0.5, 0.5) for scale and rotation. When [`NineSlice`] is also
/// set on the same shape, the 9-slice remap wins and the texture transform
/// is ignored.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TextureTransform {
    /// UV offset added after scale and rotation. `[0.0, 0.0]` keeps the
    /// sample centred. Drives panning / scrolling.
    pub offset: [f32; 2],
    /// UV scale multiplier applied around the centre. `[1.0, 1.0]` is
    /// 1:1. Larger values widen the sampled UV range (more tiles with
    /// [`TileMode::Tile`], or a wider view of the source with `Stretch`
    /// or `Mirror`). Smaller values zoom in.
    pub scale: [f32; 2],
    /// Rotation around the UV centre `(0.5, 0.5)` in radians, CCW in math
    /// coordinates.
    pub rotation: f32,
    /// Sampling mode for UV values outside `[0, 1]`. `Stretch` clamps to
    /// the edge (default), `Tile` wraps, `Mirror` ping-pongs.
    pub tile_mode: TileMode,
    /// Flip the sample horizontally before lookup.
    pub flip_x: bool,
    /// Flip the sample vertically before lookup.
    pub flip_y: bool,
}

impl Default for TextureTransform {
    fn default() -> Self {
        Self {
            offset: [0.0, 0.0],
            scale: [1.0, 1.0],
            rotation: 0.0,
            tile_mode: TileMode::Stretch,
            flip_x: false,
            flip_y: false,
        }
    }
}

impl TextureTransform {
    /// Returns `true` when the transform is the identity (no offset, unit
    /// scale, no rotation, no flips, `Stretch` mode).
    pub fn is_identity(&self) -> bool {
        self.offset == [0.0, 0.0]
            && self.scale == [1.0, 1.0]
            && self.rotation == 0.0
            && matches!(self.tile_mode, TileMode::Stretch)
            && !self.flip_x
            && !self.flip_y
    }
}