WebGPU Textures & Samplers

A texture is an image on the GPU. A sampler decides how the shader reads it.

Textures put pictures, patterns and text on your shapes. In this lesson you will make a texture from raw pixels, copy a canvas drawing into one, and draw both on a square.

Textures vs Buffers

You already know buffers. A buffer is a plain list of bytes. A texture is different:

A pixel in a texture is often called a texel.

Create a Texture

Use device.createTexture(). Give it a size, a format and a usage:

const texture = device.createTexture({
  size: [TEXTURE_SIZE, TEXTURE_SIZE],
  format: "rgba8unorm",
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
});

• "rgba8unorm" means 4 bytes per texel: red, green, blue and alpha. Each byte goes from 0 to 255, and the shader sees it as 0.0 to 1.0.
• TEXTURE_BINDING lets a shader read the texture.
• COPY_DST lets you copy data into it.

Upload Raw Pixels

device.queue.writeTexture() copies bytes from JavaScript into a texture. You tell it how many bytes are in each row with bytesPerRow:

device.queue.writeTexture(
  { texture },
  createCheckerboardPixels(),
  { bytesPerRow: TEXTURE_SIZE * BYTES_PER_PIXEL },
  [TEXTURE_SIZE, TEXTURE_SIZE]
);

The pixels are a Uint8Array, filled row by row from the top:

function createCheckerboardPixels() {
  const pixels = new Uint8Array(TEXTURE_SIZE * TEXTURE_SIZE * BYTES_PER_PIXEL);
  for (let y = 0; y < TEXTURE_SIZE; y++) {
    for (let x = 0; x < TEXTURE_SIZE; x++) {
      const isTopLeft = x === 0 && y === 0;
      const isLight = (x + y) % 2 === 0;
      const color = isTopLeft ? topLeftMarker : isLight ? lightSquare : darkSquare;
      pixels.set(color, (y * TEXTURE_SIZE + x) * BYTES_PER_PIXEL);
    }
  }
  return pixels;
}

Texture Coordinates (UV)

Shaders do not read textures by pixel number. They use UV coordinates from 0 to 1, so the same code works for any texture size:

• (0, 0) is the top-left corner of the texture.
• (1, 1) is the bottom-right corner.
• u goes left to right, v goes top to bottom.

Each corner of the square gets a UV, next to its position. The GPU blends the UVs across the square, so every pixel knows where to read:

return new Float32Array([
  left, top, 0, 0,
  left, bottom, 0, 1,
  right, bottom, 1, 1,
  left, top, 0, 0,
  right, bottom, 1, 1,
  right, top, 1, 0
]);

Samplers

A sampler tells the GPU how to read a texture: how to blend texels, and what to do outside the 0-to-1 range.

const sampler = device.createSampler({
  magFilter: "nearest",
  minFilter: "nearest"
});

The two most important filter values are:

• "nearest": use the single closest texel. Sharp, blocky pixels. Good for pixel art.
• "linear": blend the four closest texels. Smooth. Good for photos.

const nearestSampler = device.createSampler({
  magFilter: "nearest",
  minFilter: "nearest"
});
const linearSampler = device.createSampler({
  magFilter: "linear",
  minFilter: "linear"
});

The example makes one bind group per sampler. It draws the left square with one and the right square with the other. The texture is the same.

Reading a Texture in WGSL

In WGSL, a texture has the type texture_2d<f32>, and a sampler has the type sampler. Read a colour with textureSample(texture, sampler, uv):

struct VertexOutput {
  @builtin(position) position: vec4f,
  @location(0) uv: vec2f,
}

@group(0) @binding(0) var checkerTexture: texture_2d<f32>;
@group(0) @binding(1) var checkerSampler: sampler;

@vertex
fn vertexMain(@location(0) position: vec2f, @location(1) uv: vec2f) -> VertexOutput {
  var output: VertexOutput;
  output.position = vec4f(position, 0.0, 1.0);
  output.uv = uv;
  return output;
}

@fragment
fn fragmentMain(input: VertexOutput) -> @location(0) vec4f {
  return textureSample(checkerTexture, checkerSampler, input.uv);
}

Bind the Texture and Sampler

Textures and samplers reach the shader through a bind group, just like uniform buffers. Pass a texture view for the texture, and the sampler itself:

const bindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [
    { binding: 0, resource: texture.createView() },
    { binding: 1, resource: sampler }
  ]
});

Then call pass.setBindGroup(0, bindGroup) before drawing.

Upload an Image

To put a picture in a texture, use device.queue.copyExternalImageToTexture(). The source can be an ImageBitmap, an HTMLCanvasElement, an OffscreenCanvas, a video frame and more.

The example draws its own picture with the 2D canvas API, so it needs no image file:

function drawPicture() {
  const pictureCanvas = new OffscreenCanvas(IMAGE_WIDTH, IMAGE_HEIGHT);
  const drawing = pictureCanvas.getContext("2d");
  const gradient = drawing.createLinearGradient(0, 0, IMAGE_WIDTH, IMAGE_HEIGHT);
  gradient.addColorStop(0, "#1e3a8a");
  gradient.addColorStop(1, "#9d174d");
  drawing.fillStyle = gradient;
  drawing.fillRect(0, 0, IMAGE_WIDTH, IMAGE_HEIGHT);
  drawing.fillStyle = "#ffffff";
  drawing.font = "bold 52px system-ui, sans-serif";
  drawing.fillText("Hello, WebGPU!", 40, 140);
  return pictureCanvas;
}

const texture = device.createTexture({
  size: [IMAGE_WIDTH, IMAGE_HEIGHT],
  format: "rgba8unorm",
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT
});
device.queue.copyExternalImageToTexture(
  { source: drawPicture() },
  { texture },
  [IMAGE_WIDTH, IMAGE_HEIGHT]
);

To load a real image file, fetch it, turn it into an ImageBitmap, and copy that in the same way:

const response = await fetch("photo.png");
const bitmap = await createImageBitmap(await response.blob());
const photoTexture = device.createTexture({
  size: [bitmap.width, bitmap.height],
  format: "rgba8unorm",
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT
});
device.queue.copyExternalImageToTexture({ source: bitmap }, { texture: photoTexture }, [bitmap.width, bitmap.height]);

Sampler Options

Filters decide how texels are blended:

Address modes decide what happens when a UV is below 0 or above 1:

Exercises

const sampler = device.createSampler({
  magFilter: "nearest",
  minFilter: "nearest",
  addressModeU: "repeat",
  addressModeV: "repeat"
});

return textureSample(checkerTexture, checkerSampler, input.uv * 3.0);

Summary

• A texture is a grid of texels with a fixed format, such as rgba8unorm.
• Upload raw bytes with writeTexture, and images or canvases with copyExternalImageToTexture.
• UV coordinates go from (0, 0) at the top-left to (1, 1) at the bottom-right.
• A sampler sets filtering ("nearest" or "linear") and address modes ("clamp-to-edge" or "repeat").
• In WGSL, read a texture_2d<f32> with textureSample(texture, sampler, uv).

Official documentation

Go deeper with the specifications and reference documentation:

• developer.mozilla.org

  MDN: GPUDevice.createTexture()

  Texture sizes, formats, mip levels and usage flags.

• developer.mozilla.org

  MDN: GPUDevice.createSampler()

  Filtering, address modes and anisotropy.

• developer.mozilla.org

  MDN: GPUQueue.copyExternalImageToTexture()

  Uploading images, canvases and video frames to the GPU.

• w3.org

  WGSL specification: textureSample

  The built-in that reads a filtered texel in a fragment shader.