Textures

Recommended reading

We assume that you are familiar with the following concepts:

• WebGPU Fundamentals
• Textures
• Storage Textures

In a similar fashion to buffers, textures provide a way to store and manage data on the GPU. They allow for both read and write access from WGSL shaders, and can also be sampled in the case of sampled textures. The main advantage of using textures over buffers is their optimized memory layout for spatial data, which can lead to better performance in certain scenarios as well as additional functionality such as filtering and mipmapping.

TypeGPU textures serve as a wrapper that provides type safety and higher level utilities (such as automatic mipmap generation). They also allow - in a similar way to buffers - for fixed resource creation that can be used directly in shaders without the need for manual bind group management.

Let’s look at an example of creating and using a typed texture.

import { tgpu } from 'typegpu';

const root = await tgpu.init();

const response = await fetch('path/to/image.png');
const blob = await response.blob();
const imageBitmap = await createImageBitmap(blob);

const texture = root.createTexture({
  size: [imageBitmap.width, imageBitmap.height],
  format: 'rgba8unorm' as const,
}).$usage('sampled', 'render');

// Uploading image data to the texture
texture.write(imageBitmap);

// Creating a view to use in shader
const sampledView = texture.createView();
const sampledView: TgpuTextureView<WgslTexture2d<F32>>

Creating a texture

Textures can be created using the root.createTexture method. It accepts a descriptor similar to vanilla GPUTextureDescriptor. If specified, the properties will be reflected in the created texture type - this will later help with static checks when creating views or binding the texture in a layout.

type TextureProps = {
  size: readonly number[];
  format: GPUTextureFormat;
  viewFormats?: GPUTextureFormat[] | undefined;
  dimension?: GPUTextureDimension | undefined;
  mipLevelCount?: number | undefined;
  sampleCount?: number | undefined;
};

const texture = root.createTexture({
const texture: TgpuTexture<{
    size: [512, 512, 128];
    format: "rgba8unorm";
    dimension: "3d";
    mipLevelCount: 4;
}>
  size: [512, 512, 128],
  format: 'rgba8unorm',
  mipLevelCount: 4,
  dimension: '3d',
})

Usage flags

Similar to buffers, textures need usage flags to specify how they will be used. You can add usage flags using the .$usage(...) method.

const texture = root.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
})
  .$usage('sampled') // Can be sampled in shaders
  .$usage('storage') // Can be written or read to as storage texture
  .$usage('render'); // Can be used as a render target or image upload target

You can also add multiple flags at once:

const texture = root.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
}).$usage('sampled', 'storage', 'render');

For raw WebGPU usage flags, use .$overrideFlags(...):

const texture = root
  .createTexture({
    size: [256, 256],
    format: 'rgba8unorm',
  })
  .$overrideFlags(GPUTextureUsage.RENDER_ATTACHMENT);

Caution

This is an escape hatch. It replaces the flags TypeGPU would normally infer and marks the texture as usable through sampled, storage, and render APIs. Use it responsibly, do not call .$usage(...) after it, and make sure the resulting GPUTextureDescriptor is valid.

Writing to a texture

The .write() method accepts a variety of data sources. Here’s a quick overview of the available options:

Source	Use when
texture.write(imageBitmap)	You already have a decoded image that matches the texture size.
texture.write(imageBitmap, { fit: 'stretch' })	You want the image resampled to fit the texture.
texture.write(imageBitmap, { fit: 'clip' })	You want a 1:1 copy of the overlapping region.
texture.writeAsync(blob, { ... })	You have a fetched Blob and don’t need to keep the decoded bitmap around.
texture.write([layer0, layer1])	You want to fill a texture array or 3D texture one layer at a time.
texture.write(bytes)	You already have raw texel bytes.
texture.write(imageBitmap, { origin, size, ... })	You need a crop or a destination region.
common.writeChannels(texture, { ... })	You want to pack image sources into individual channels.

Writing image sources requires the 'render' usage flag (raw binary writes do not), and the source and destination sizes have to match unless you pick a mismatch behavior with the fit option.

Writing image data

You can write various image sources to textures. If the image dimensions match the texture size, all it takes is a single .write() call:

const texture = root.createTexture({
  size: [imageBitmap.width, imageBitmap.height],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

texture.write(imageBitmap);

Browser support

Besides ImageBitmap, GPUCopyExternalImageSource also includes canvas, video, ImageData, HTMLImageElement, and VideoFrame - but browser support for these varies. For portable code, decode fetched images to ImageBitmap first.

Handling size mismatches

If the image dimensions don’t match the texture size, a plain .write() call throws. The fit option picks what happens instead: 'stretch' resamples the source to fill the target region, while 'clip' copies texels 1:1 and cuts off whatever doesn’t overlap.

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

texture.write(imageBitmap, { fit: 'stretch' });

texture.write(imageBitmap, {
  sourceOrigin: [16, 16],
  sourceSize: [128, 128],
  size: [256, 256],
  fit: 'stretch',
});

texture.write(tileBitmap, { origin: [128, 64], fit: 'clip' });

Note

Under the hood, fit: 'stretch' runs a render-pass blit, while fit: 'clip' is a plain texel copy.

Writing blobs

If you fetched an image and don’t need to keep the decoded ImageBitmap around, you can hand the Blob directly to writeAsync and let TypeGPU handle the decoding. With fit: 'stretch', the resize options are passed along to createImageBitmap before uploading.

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

const blob = await (await fetch('path/to/image.png')).blob();

await texture.writeAsync(blob, { fit: 'stretch' });

If you don’t specify a size, it defaults to the size of the written region - the target mip level minus the origin offset. Keep in mind that the decoded bitmap is still written as an image source, so the texture needs the 'render' usage flag.

Writing arrays of images

For texture arrays, you can write multiple images at once - one per layer:

const texture = root.createTexture({
  size: [256, 256, 3],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

texture.write([layer0, layer1, layer2]);

Each image has to match the layer size, unless you pass a fit mode.

The same form works for 3D textures (created with dimension: '3d') - each image in the array fills one depth slice:

const texture3d = root.createTexture({
  size: [256, 256, 3],
  format: 'rgba8unorm',
  dimension: '3d',
}).$usage('sampled', 'render');

texture3d.write([slice0, slice1, slice2]);

Writing raw binary data

You can write raw binary data directly to textures using ArrayBuffer, typed arrays, or DataView:

const texture = root.createTexture({
  size: [2, 2],
  format: 'rgba8unorm',
  mipLevelCount: 2,
}).$usage('sampled');

// Using Uint8Array for RGBA data (4 pixels, 4 bytes each)
const data = new Uint8Array([
  255, 0, 0, 255,    // Red pixel
  0, 255, 0, 255,    // Green pixel
  0, 0, 255, 255,    // Blue pixel
  255, 255, 0, 255,  // Yellow pixel
]);
texture.write(data);

// Write to a specific mip level
const mipData = new Uint8Array(4); // Data for 1 pixel
texture.write(mipData, 1); // Write to mip level 1

// Update just a region
const regionData = new Uint8Array(4); // Data for 1 pixel
texture.write(regionData, { origin: [1, 1], size: [1, 1] });

Writing raw data doesn’t require the 'render' usage flag, but the byte length has to exactly match the written region for the given texture format.

Regions and channel writes

If you only want to update a part of the texture, or copy just a fragment of the source image, you can pass options with source and destination regions. The options also let you flip the source vertically (flipY), premultiply alpha (premultipliedAlpha), or convert to a specific color space (colorSpace).

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

texture.write(imageBitmap, {
  sourceOrigin: [16, 16],
  sourceSize: [128, 128],
  origin: [128, 64],
  size: [128, 128],
});

Sometimes you’ll want to pack multiple grayscale maps into a single texture - for example combining separate roughness, metalness, and mask maps into one material texture. The common.writeChannels utility does exactly that. Each entry writes a single channel of the texture, with from selecting which channel of the source to read. Entries set to undefined are skipped.

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}).$usage('sampled', 'render');

common.writeChannels(texture, {
  r: { source: roughnessMap, from: 'r' },
  g: { source: metalnessMap, from: 'r' },
  a: { source: maskMap, from: 'r' },
});

Region and channel writes follow the same rules as other image writes - they require the 'render' usage flag, and sizes have to match unless you pass a fit mode.

Mipmaps

TypeGPU provides automatic mipmap generation for textures:

const texture = root.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
  mipLevelCount: 9, // log2(256) + 1
}).$usage('sampled', 'render');

texture.write(imageBitmap, { fit: 'stretch' });
texture.generateMipmaps(); // Generate all mip levels automatically

Note

The generateMipmaps() method requires both 'sampled' and 'render' usage flags, as TypeGPU runs a downsampling pipeline behind the scenes to generate the mip levels.

Copying and clearing

You can also copy data from another texture. If both textures have the same size and format, a plain targetTexture.copyFrom(sourceTexture) is all you need. To copy a region, target a specific mip level, or copy between differently sized textures, pass copy options:

targetTexture.copyFrom(sourceTexture, {
  sourceOrigin: [16, 16],
  origin: [128, 64],
  size: [32, 32],
});

To wipe a texture clean, use texture.clear(), which fills every mip level with zeros, or pass a mip level to clear only that level. You can also pass an rgba color to fill the texture with instead (this requires the 'render' usage flag):

texture.clear([0, 0.5, 0, 1]);

Call .destroy() when the texture is no longer needed. This releases the underlying GPUTexture; subsequent operations on the TypeGPU texture are invalid.

Texture views

To create a view - which will also serve as fixed texture usage - you can use one of the available texture schemas. You can pass it to the .createView method of the texture.

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}).$usage('sampled');

const sampledView = texture.createView(d.texture2d(d.f32));
// in this case the same as:
// - texture.createView(d.texture2d()); (defaults to f32)
// - texture.createView();              (defaults to texture2d<f32>)

Tip

If type information is available the view schema will be statically checked against the texture properties.

const texture = root.createTexture({
  size: [512, 512],
  format: 'rgba8unorm',
}); // <-- missing .$usage('sampled')

const sampledView = texture.createView(d.texture2d(d.f32));
Error ts(2769)  ― No overload matches this call.
  The last overload gave the following error.
    Argument of type 'WgslTexture2d<F32>' is not assignable to parameter of type '"(Error) Texture not usable as storage, call $usage('storage') first" | "(Error) Storage texture format 'rgba8unorm' incompatible with texture format 'rgba8unorm'" | ... 38 more ... | "(Error) Storage texture format 'rgba8uint' incompatible with texture format 'rgba8unorm'"'.

const texture = root.createTexture({
  size: [512, 512],
  format: 'r32float',
}).$usage('storage');

const sampledView = texture.createView(d.textureStorage2d('rgba8unorm')); // <-- wrong format
Error ts(2769)  ― No overload matches this call.
  The last overload gave the following error.
    Argument of type 'WgslStorageTexture2d<"rgba8unorm", "write-only">' is not assignable to parameter of type '"(Error) Storage texture format 'rgba8unorm' incompatible with texture format 'r32float'"'.

Samplers

To sample textures in shaders, you’ll often need a sampler that defines how the texture should be filtered and addressed. The createSampler method accepts the same descriptor as the vanilla WebGPU GPUSamplerDescriptor:

const sampler = root.createSampler({
  magFilter: 'linear',
  minFilter: 'linear',
  mipmapFilter: 'linear',
  addressModeU: 'repeat',
  addressModeV: 'repeat',
});

The returned sampler object can be used like a fixed resource directly in shaders, or bound in a bind group for manual binding.

Comparison samplers

Depth comparisons use a distinct sampler type. Create one with root.createComparisonSampler, then pass it to std.textureSampleCompare with a depth texture:

const shadowMap = root.createTexture({
  size: [1024, 1024],
  format: 'depth24plus',
}).$usage('sampled');

const shadowView = shadowMap.createView(d.textureDepth2d());
const shadowSampler = root.createComparisonSampler({
  compare: 'less-equal',
  magFilter: 'linear',
  minFilter: 'linear',
});

const sampleShadow = tgpu.fn([d.vec2f, d.f32], d.f32)((uv, depth) => {
  'use gpu';
  return std.textureSampleCompare(shadowView.$, shadowSampler.$, uv, depth);
});

For manual binding, pair d.comparisonSampler() with a comparison layout entry:

const layout = tgpu.bindGroupLayout({
  shadowMap: { texture: d.textureDepth2d() },
  shadowSampler: { sampler: 'comparison' },
});

Regular samplers created with createSampler use d.sampler() and a 'filtering' or 'non-filtering' layout entry instead.

Binding textures

Textures can be used in shaders through bind groups or as fixed resources, similar to buffers.

Manual binding

const texture = root.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
}).$usage('sampled');

const sampler = root.createSampler({
  magFilter: 'linear',
  minFilter: 'linear',
});

const bindGroupLayout = tgpu.bindGroupLayout({
  myTexture: { texture: d.texture2d() },
  mySampler: { sampler: 'filtering' },
});

const bindGroup = root.createBindGroup(bindGroupLayout, {
  myTexture: texture,
  // views can also be used - as long as the schema matches
  // myTexture: texture.createView(),
  mySampler: sampler,
});

Using fixed resources

For textures that remain consistent across operations, you can create fixed texture views:

const texture = root.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
}).$usage('sampled');

// Create a fixed sampled view
const sampledView = texture.createView();

const sampler = root.createSampler({
  magFilter: 'linear',
  minFilter: 'linear',
});

const myShader = tgpu.fn([d.vec2f], d.vec4f)((uv) => {
  'use gpu';
  // Use the fixed texture view directly
  return std.textureSample(sampledView.$, sampler.$, uv);
});