tiramisu/texture

Texture loading and manipulation.

Textures are images applied to materials or used as sprites. This module provides loading, cloning, and UV manipulation for texture coordinates.

Loading Textures

fn init(ctx: Context) {
  #(
    Model(texture: option.None),
    texture.load(
      from_url: "/textures/player.png",
      on_success: TextureLoaded,
      on_error: TextureFailed,
    ),
    None,
  )
}

Spritesheet UV Manipulation

For animated sprites, use offset and repeat to show specific frames:

// 4x4 spritesheet: show frame at row 1, column 2
texture.set_repeat(tex, vec2.Vec2(0.25, 0.25))  // Each frame is 1/4 of texture
texture.set_offset(tex, vec2.Vec2(0.5, 0.25))   // Column 2, row 1

Texture Filtering

// Pixel art: use nearest neighbor for crisp pixels
texture.set_filter_mode(tex, texture.NearestFilter, texture.NearestFilter)

// Smooth textures: use linear (default)
texture.set_filter_mode(tex, texture.LinearFilter, texture.LinearFilter)

Types

FilterMode

</>

Texture filtering mode.

Controls how textures are sampled when scaled.

Variants

NearestFilter - No interpolation, uses nearest pixel (best for pixel art)
LinearFilter - Bilinear interpolation for smooth texture sampling (default)

pub type FilterMode {
  NearestFilter
  LinearFilter
}

Constructors

```
NearestFilter
```
```
LinearFilter
```

Texture

</>

pub type Texture =
  savoiardi.Texture

WrapMode

</>

Texture wrapping mode.

Controls how textures behave when UV coordinates exceed the 0-1 range.

Variants

RepeatWrapping - Texture repeats infinitely (requires power-of-two dimensions)
ClampToEdgeWrapping - Edge pixels stretch infinitely (works with any dimensions)
MirroredRepeatWrapping - Texture repeats with alternating mirrored copies

pub type WrapMode {
  RepeatWrapping
  ClampToEdgeWrapping
  MirroredRepeatWrapping
}

Constructors

```
RepeatWrapping
```
```
ClampToEdgeWrapping
```
```
MirroredRepeatWrapping
```

Values

clone

</>

pub fn clone(texture: savoiardi.Texture) -> savoiardi.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

load

</>

pub fn load(
  from_url url: String,
  on_success on_success: fn(savoiardi.Texture) -> msg,
  on_error on_error: msg,
) -> effect.Effect(msg)

Load a texture from URL

set_filter_mode

</>

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

Sets the texture filtering mode.

Controls how the texture is sampled when scaled. Use NearestFilter for crisp pixel art, LinearFilter for smooth textures.

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: savoiardi.Texture,
  offset offset: vec2.Vec2(Float),
) -> savoiardi.Texture

Sets the texture UV offset.

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

Example

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

set_repeat

</>

pub fn set_repeat(
  texture: savoiardi.Texture,
  repeat repeat: vec2.Vec2(Float),
) -> savoiardi.Texture

Sets 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).

Example

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

set_wrap_mode

</>

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

Sets 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.

Example

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