Textures

This page covers texture declarations in

For loading textures from URLs, see Loading Textures.

Declaring textures

Textures are declared in the

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 named

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

TextureDefinition fields

Runtime texture value forms

You can set texture sources at definition time or at runtime via

Example: setting a texture from a video

<script lang="ts">
  import { useFrame } from '@motion-core/motion-gpu';

  let video: HTMLVideoElement;

  useFrame((state) => {
    if (video && video.readyState >= 2) {
      state.setTexture('uVideo', video);
    }
  });
</script>

<video bind:this={video} src="/assets/loop.mp4" autoplay loop muted playsinline />

<script lang="ts">
  import { useFrame } from '@motion-core/motion-gpu';

  let video: HTMLVideoElement;

  useFrame((state) => {
    if (video && video.readyState >= 2) {
      state.setTexture('uVideo', video);
    }
  });
</script>

<video bind:this={video} src="/assets/loop.mp4" autoplay loop muted playsinline />

Because the source is an

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

Upload behaviour

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

Mipmap generation

When

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

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

If

Naming rules

Texture identifiers follow the same rules as uniforms:

Practical recommendations