Skip to content
Fragment Color v0.10.11
Blog

Texture

Description

Section titled “Description”

A GPU texture resource. Public API wrapper that holds a shareable reference to the internal TextureObject and a numeric handle used by uniforms.

  • Construct via Renderer::create_texture_* helpers (no direct constructors)
  • Set on shaders with shader.set(“key”, &Texture)
  • Texture owns its sampler; you can tweak filtering and wrapping via set_sampler_options.

How to use

Section titled “How to use”

Create a Texture and set it on a Shader

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {


use fragmentcolor::{Renderer, Shader, Size};
let renderer = Renderer::new();
let shader = Shader::new(r#"
@group(0) @binding(0) var my_texture: texture_2d<f32>;
@group(0) @binding(1) var my_sampler: sampler;
@vertex fn vs_main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
let p = array<vec2<f32>,3>(vec2f(-1.,-1.), vec2f(3.,-1.), vec2f(-1.,3.));
return vec4f(p[i], 0., 1.);
}
@fragment fn main() -> @location(0) vec4<f32> { return vec4f(1.,1.,1.,1.); }
"#)?;


// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];
let texture = renderer.create_texture_with_size(pixels, [1,1]).await?;


// insert  the texture in the shader matching the name in the shader
shader.set("my_texture", &texture)?;


4 collapsed lines
_ = shader;
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Methods

Section titled “Methods”

Texture::id()

Section titled “Texture::id()”

Return the stable TextureId for this texture instance. The id is valid within the Renderer that created it.

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, TextureFormat};
let renderer = Renderer::new();
let texture = renderer.create_storage_texture([64, 64], TextureFormat::Rgba, None).await?;
let id = *texture.id();
3 collapsed lines
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Texture::size

Section titled “Texture::size”

Returns the texture size (w, h[, d]).

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, Size};
let renderer = Renderer::new();
let pixels: &[u8] = &[255,255,255,255];
let tex = renderer.create_texture_with_size(pixels, [1,1]).await?;
let sz = tex.size();
4 collapsed lines
assert_eq!([sz.width, sz.height], [1, 1]);
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Texture::aspect

Section titled “Texture::aspect”

Returns width/height as f32.

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {


use fragmentcolor::{Renderer, Size};


let renderer = Renderer::new();
// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];
let tex = renderer.create_texture_with_size(pixels, [1, 1]).await?;
let a = tex.aspect();


4 collapsed lines
assert!(a > 0.0);
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Texture::set_sampler_options

Section titled “Texture::set_sampler_options”

Update the texture sampler options (filtering, wrapping, etc.).

Note: changes take effect on next bind; the renderer recreates the sampler as needed.

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, Size, SamplerOptions};
let renderer = Renderer::new();
// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];


let texture = renderer.create_texture_with_size(pixels, [1,1]).await?;
let opts = SamplerOptions { repeat_x: true, repeat_y: true, smooth: true, compare: None };
texture.set_sampler_options(opts);




3 collapsed lines
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Texture::write(bytes)

Section titled “Texture::write(bytes)”

Efficiently upload raw pixel data into an existing texture. Ideal for video playback or any per-frame dynamic image updates.

  • Whole texture updates: use Texture.write(&bytes) or Texture.write_with(&bytes, TextureWriteOptions::whole()).
  • Sub-rectangle updates: pass origin and size via TextureWriteOptions.
  • Bytes per row must be a multiple of 256. When unspecified, compute it from the pixel stride and align up.

Notes

Section titled “Notes”
  • Supported formats initially: Rgba8Unorm, Rgba8UnormSrgb, Bgra8Unorm, Bgra8UnormSrgb, and other 4-bytes-per-pixel formats. Unsupported formats return an error.
  • The texture must have COPY_DST usage.

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, TextureFormat};
let renderer = Renderer::new();
let texture = renderer.create_storage_texture([64, 64], TextureFormat::Rgba, None).await?;
let frame_bytes = vec![0u8; 64 * 64 * 4];


texture.write(&frame_bytes)?;
3 collapsed lines
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }

Texture::write_with(bytes, options)

Section titled “Texture::write_with(bytes, options)”

Same as Texture::write, but allows specifying origin, size, bytes_per_row and rows_per_image.

Notes

Section titled “Notes”
  • See Texture::write for format and alignment details.

Example

Section titled “Example”
1 collapsed line
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, TextureFormat, TextureWriteOptions};
let renderer = Renderer::new();
let texture = renderer.create_storage_texture([64, 32], TextureFormat::Rgba, None).await?;
let region_bytes = vec![0u8; 64 * 32 * 4];
let opt = TextureWriteOptions::whole().with_bytes_per_row(256).with_rows_per_image(32);
texture.write_with(&region_bytes, opt)?;
3 collapsed lines
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }