tiramisu/texture

Texture manipulation utilities for Three.js textures.

This module provides type-safe access to Three.js texture properties, particularly useful for spritesheet animation where you need to control UV offset and repeat to display different frames.

UV Coordinates

UV coordinates in Three.js range from 0.0 to 1.0:

(0, 0) is the bottom-left corner
(1, 1) is the top-right corner

Offset and Repeat

Offset: Shifts which portion of the texture is displayed
Repeat: Controls how much of the texture is shown (0.5 = show half)

Example: Spritesheet Animation

// For a 4-frame horizontal spritesheet:
// Frame 0: offset (0.0, 0.0), repeat (0.25, 1.0)
// Frame 1: offset (0.25, 0.0), repeat (0.25, 1.0)
// Frame 2: offset (0.5, 0.0), repeat (0.25, 1.0)
// Frame 3: offset (0.75, 0.0), repeat (0.25, 1.0)

let texture = asset.get_texture(cache, "spritesheet.png")

// Setup for animation
texture
|> texture.set_repeat(0.25, 1.0)  // Show 1/4 of texture width
|> texture.set_wrap_mode(texture.RepeatWrapping, texture.RepeatWrapping)

// Change to frame 2
texture.set_offset(texture, 0.5, 0.0)

Types

FilterMode

</>

Texture filtering mode

pub type FilterMode {
  NearestFilter
  LinearFilter
}

Constructors

```
NearestFilter
```
Nearest neighbor filtering (best for pixel art)
```
LinearFilter
```
Linear interpolation filtering (smooth, default)

WrapMode

</>

Texture wrapping mode

pub type WrapMode {
  RepeatWrapping
  ClampToEdgeWrapping
  MirroredRepeatWrapping
}

Constructors

```
RepeatWrapping
```
Repeat the texture (requires power-of-two dimensions)
```
ClampToEdgeWrapping
```
Clamp to edge (default, works with any dimensions)
```
MirroredRepeatWrapping
```
Mirror the texture when repeating

Values

clone

</>

pub fn clone(texture: asset.Texture) -> asset.Texture

Clone a texture for independent manipulation.

This is essential for spritesheet animation when you want multiple sprites to show different frames from the same source texture.

Example

let base_texture = asset.get_texture(cache, "spritesheet.png")
let player1_texture = texture.clone(base_texture)
let player2_texture = texture.clone(base_texture)

// Now player1 and player2 can show different frames
texture.set_offset(player1_texture, 0.0, 0.0)  // Frame 0
texture.set_offset(player2_texture, 0.25, 0.0) // Frame 1

set_filter_mode

</>

pub fn set_filter_mode(
  texture: asset.Texture,
  min_filter min_filter: FilterMode,
  mag_filter mag_filter: FilterMode,
) -> asset.Texture

Set the texture filtering mode.

Controls how the texture is sampled when scaled.

Parameters

min_filter: Minification filter (when texture appears smaller)
mag_filter: Magnification filter (when texture appears larger)

Example

// Use nearest filtering for crisp pixel art
texture.set_filter_mode(
  my_texture,
  texture.NearestFilter,
  texture.NearestFilter,
)

set_offset

</>

pub fn set_offset(
  texture: asset.Texture,
  x x: Float,
  y y: Float,
) -> asset.Texture

Set the texture UV offset.

Controls which portion of the texture starts being displayed. Values range from 0.0 to 1.0.

Parameters

x: Horizontal offset (0.0 = left edge, 1.0 = right edge)
y: Vertical offset (0.0 = bottom edge, 1.0 = top edge)

Example

// Show the right half of the texture
texture.set_offset(my_texture, 0.5, 0.0)

set_repeat

</>

pub fn set_repeat(
  texture: asset.Texture,
  x x: Float,
  y y: Float,
) -> asset.Texture

Set the texture UV repeat (scaling).

Controls how much of the texture is displayed. Values range from 0.0 to 1.0 (or higher for tiling).

Parameters

x: Horizontal repeat (0.5 = show half width, 2.0 = tile twice)
y: Vertical repeat (0.5 = show half height, 2.0 = tile twice)

Example

// Show only 1/4 of texture width (for 4-frame horizontal sprite)
texture.set_repeat(my_texture, 0.25, 1.0)

set_wrap_mode

</>

pub fn set_wrap_mode(
  texture: asset.Texture,
  wrap_s wrap_s: WrapMode,
  wrap_t wrap_t: WrapMode,
) -> asset.Texture

Set the texture wrapping mode.

Controls how the texture behaves at edges when UV coordinates exceed 0-1 range.

Important: RepeatWrapping only works with power-of-two texture dimensions (2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, etc.)

Parameters

wrap_s: Horizontal wrapping mode
wrap_t: Vertical wrapping mode

Example

// Required for spritesheet animation
texture.set_wrap_mode(
  my_texture,
  texture.RepeatWrapping,
  texture.RepeatWrapping,
)