Textures

This page covers texture declarations in defineMaterial, the runtime texture value forms, update modes, upload behavior, mipmap generation, and sampler configuration.

For loading textures from URLs, see Loading Textures.

Declaring textures

Textures are declared in the textures field of defineMaterial:

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  let color = textureSample(uAlbedo, uAlbedoSampler, uv);
  return color;
}
`,
  textures: {
    uAlbedo: {
      colorSpace: 'srgb',
      filter: 'linear',
      generateMipmaps: true
    }
  }
});

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  let color = textureSample(uAlbedo, uAlbedoSampler, uv);
  return color;
}
`,
  textures: {
    uAlbedo: {
      colorSpace: 'srgb',
      filter: 'linear',
      generateMipmaps: true
    }
  }
});

Each texture with fragmentVisible: true (default) creates two WGSL bindings:

• uFoo: texture_2d<f32> — the texture
• uFooSampler: sampler — the associated sampler

When fragmentVisible: false, the texture slot is excluded from fragment WGSL declarations and group(0) fragment bind-group bindings.

TextureDefinition fields

Runtime texture value forms

You can set texture sources at definition time or at runtime via state.setTexture():

Example: setting a texture from a video

Because the source is an HTMLVideoElement, the update mode is automatically set to perFrame.

Update modes

The update mode controls when the texture is re-uploaded to the GPU:

Resolution precedence

1. Runtime override — TextureData.update (from state.setTexture({ source, update: '...' }))
2. Definition default — TextureDefinition.update (from defineMaterial({ textures: { ... } }))
3. Automatic fallback — HTMLVideoElement → perFrame, everything else → once

Storage textures (compute)

When storage: true is enabled, the texture participates in compute bindings (group(2)):

• format must be a storage-compatible format.
• For PingPongComputePass, the target texture must have explicit width and height.
• Storage textures are compute-managed and are not source-uploaded through normal texture update flow.
• Use fragmentVisible: false for compute-only storage textures that should not consume fragment sampler/texture bindings.

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  return vec4f(uv, 0.0, 1.0);
}
`,
  textures: {
    simState: {
      storage: true,
      format: 'rgba16float',
      width: 256,
      height: 256,
      fragmentVisible: false // compute-only slot
    }
  }
});

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  return vec4f(uv, 0.0, 1.0);
}
`,
  textures: {
    simState: {
      storage: true,
      format: 'rgba16float',
      width: 256,
      height: 256,
      fragmentVisible: false // compute-only slot
    }
  }
});

Upload behavior

The renderer decides how to handle each texture per frame:

The renderer maintains a fallback 1×1 opaque white texture for each binding. If the user source is null, the fallback is used so the shader always has a valid binding.

Mipmap generation

When generateMipmaps: true is set:

1. The base level (mip 0) is uploaded normally with copyExternalImageToTexture.
2. Each subsequent mip level is generated by drawing into an offscreen canvas, halving dimensions each time.
3. Each downscaled level is uploaded individually.

The implementation uses OffscreenCanvas when available, falling back to a regular <canvas> element.

Mipmap generation adds upload cost proportional to ~33% of the base texture size. Use it when texture minification is visible (e.g., a texture displayed at varying scales).

Sampler configuration

The sampler created for each texture is configured from the TextureDefinition fields:

If generateMipmaps is enabled, mipmapFilter is also set to the same value as filter.

Naming rules

Texture identifiers follow the same rules as uniforms: [A-Za-z_][A-Za-z0-9_]*. Invalid names throw at material definition time.

Practical recommendations