tessl/npm-webgpu--types

Complete TypeScript type definitions for the WebGPU standard enabling type-safe GPU programming.

—

Pending

Overview

Eval results

Files

Resources

Name: tessl/npm-webgpu--types
Author: tessl

GPU resource objects including buffers, textures, samplers, and bind groups for managing GPU memory and data binding.

Capabilities

GPU Buffer

Memory buffer for vertex data, uniforms, storage, and other GPU data.

interface GPUBuffer {
  /** Size of the buffer in bytes */
  readonly size: GPUSize64Out;
  
  /** Usage flags indicating how the buffer can be used */
  readonly usage: GPUBufferUsageFlags;
  
  /** Current mapping state */
  readonly mapState: GPUBufferMapState;
  
  /** Optional debug label */
  readonly label: string | undefined;
  
  /**
   * Maps buffer memory for CPU access
   * @param mode - Mapping mode (READ or WRITE)
   * @param offset - Byte offset into the buffer
   * @param size - Number of bytes to map
   * @returns Promise that resolves when mapping is complete
   */
  mapAsync(
    mode: GPUMapModeFlags,
    offset?: GPUSize64,
    size?: GPUSize64
  ): Promise<void>;
  
  /**
   * Gets a mapped range as an ArrayBuffer
   * @param offset - Byte offset into the mapped region
   * @param size - Number of bytes to access
   * @returns ArrayBuffer for the mapped range
   */
  getMappedRange(offset?: GPUSize64, size?: GPUSize64): ArrayBuffer;
  
  /** Unmaps the buffer, making it available for GPU use */
  unmap(): void;
  
  /** Destroys the buffer and releases resources */
  destroy(): void;
}

interface GPUBufferDescriptor extends GPUObjectDescriptorBase {
  /** Size of the buffer in bytes */
  size: GPUSize64;
  
  /** Buffer usage flags */
  usage: GPUBufferUsageFlags;
  
  /** Whether buffer should be mapped at creation */
  mappedAtCreation?: boolean;
}

interface GPUBufferBinding {
  /** Buffer to bind */
  buffer: GPUBuffer;
  
  /** Byte offset into the buffer */
  offset?: GPUSize64;
  
  /** Number of bytes to bind (defaults to entire buffer) */
  size?: GPUSize64;
}

GPU Texture

2D/3D texture for rendering, sampling, and storage operations.

interface GPUTexture {
  /** Width in texels */
  readonly width: GPUIntegerCoordinateOut;
  
  /** Height in texels */
  readonly height: GPUIntegerCoordinateOut;
  
  /** Depth or array layers */
  readonly depthOrArrayLayers: GPUIntegerCoordinateOut;
  
  /** Number of mip levels */
  readonly mipLevelCount: GPUIntegerCoordinateOut;
  
  /** Number of samples per texel */
  readonly sampleCount: GPUSize32Out;
  
  /** Texture dimension */
  readonly dimension: GPUTextureDimension;
  
  /** Pixel format */
  readonly format: GPUTextureFormat;
  
  /** Usage flags */
  readonly usage: GPUTextureUsageFlags;
  
  /** Optional debug label */
  readonly label: string | undefined;
  
  /**
   * Creates a texture view
   * @param descriptor - Optional view configuration
   * @returns New texture view
   */
  createView(descriptor?: GPUTextureViewDescriptor): GPUTextureView;
  
  /** Destroys the texture and releases resources */
  destroy(): void;
}

interface GPUTextureDescriptor extends GPUObjectDescriptorBase {
  /** Texture dimensions */
  size: GPUExtent3D;
  
  /** Number of mip levels (default: 1) */
  mipLevelCount?: GPUIntegerCoordinate;
  
  /** Samples per texel (default: 1) */
  sampleCount?: GPUSize32;
  
  /** Texture dimension (default: "2d") */
  dimension?: GPUTextureDimension;
  
  /** Pixel format */
  format: GPUTextureFormat;
  
  /** Usage flags */
  usage: GPUTextureUsageFlags;
}

GPU Texture View

View into a texture with specific format and subresource range.

interface GPUTextureView {
  /** Optional debug label */
  readonly label: string | undefined;
}

interface GPUTextureViewDescriptor extends GPUObjectDescriptorBase {
  /** View format (defaults to texture format) */
  format?: GPUTextureFormat;
  
  /** View dimension (defaults to texture dimension) */
  dimension?: GPUTextureViewDimension;
  
  /** Texture aspect to view */
  aspect?: GPUTextureAspect;
  
  /** Base mip level */
  baseMipLevel?: GPUIntegerCoordinate;
  
  /** Number of mip levels */
  mipLevelCount?: GPUIntegerCoordinate;
  
  /** Base array layer */
  baseArrayLayer?: GPUIntegerCoordinate;
  
  /** Number of array layers */
  arrayLayerCount?: GPUIntegerCoordinate;
}

GPU Sampler

Texture sampling configuration for filtering and addressing.

interface GPUSampler {
  /** Optional debug label */
  readonly label: string | undefined;
}

interface GPUSamplerDescriptor extends GPUObjectDescriptorBase {
  /** Address mode for U coordinate */
  addressModeU?: GPUAddressMode;
  
  /** Address mode for V coordinate */
  addressModeV?: GPUAddressMode;
  
  /** Address mode for W coordinate */
  addressModeW?: GPUAddressMode;
  
  /** Magnification filter */
  magFilter?: GPUFilterMode;
  
  /** Minification filter */
  minFilter?: GPUFilterMode;
  
  /** Mipmap filter */
  mipmapFilter?: GPUMipmapFilterMode;
  
  /** Minimum LOD clamp */
  lodMinClamp?: number;
  
  /** Maximum LOD clamp */
  lodMaxClamp?: number;
  
  /** Comparison function for depth textures */
  compare?: GPUCompareFunction;
  
  /** Maximum anisotropy */
  maxAnisotropy?: number;
}

GPU Bind Group

Collection of resources bound together for shader access.

interface GPUBindGroup {
  /** Optional debug label */
  readonly label: string | undefined;
}

interface GPUBindGroupDescriptor extends GPUObjectDescriptorBase {
  /** Layout defining the bind group structure */
  layout: GPUBindGroupLayout;
  
  /** Array of resource bindings */
  entries: Iterable<GPUBindGroupEntry>;
}

interface GPUBindGroupEntry {
  /** Binding index matching shader */
  binding: GPUIndex32;
  
  /** Resource to bind */
  resource: GPUBindingResource;
}

type GPUBindingResource =
  | GPUSampler
  | GPUTextureView
  | GPUBufferBinding
  | GPUExternalTexture;

GPU Bind Group Layout

Template defining the structure and types of resources in a bind group.

interface GPUBindGroupLayout {
  /** Optional debug label */
  readonly label: string | undefined;
}

interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase {
  /** Array of binding entries */
  entries: Iterable<GPUBindGroupLayoutEntry>;
}

interface GPUBindGroupLayoutEntry {
  /** Binding index */
  binding: GPUIndex32;
  
  /** Shader stages that can access this binding */
  visibility: GPUShaderStageFlags;
  
  /** Buffer binding layout */
  buffer?: GPUBufferBindingLayout;
  
  /** Sampler binding layout */
  sampler?: GPUSamplerBindingLayout;
  
  /** Texture binding layout */
  texture?: GPUTextureBindingLayout;
  
  /** Storage texture binding layout */
  storageTexture?: GPUStorageTextureBindingLayout;
  
  /** External texture binding layout */
  externalTexture?: GPUExternalTextureBindingLayout;
}

interface GPUBufferBindingLayout {
  /** Buffer binding type */
  type?: GPUBufferBindingType;
  
  /** Whether binding has dynamic offset */
  hasDynamicOffset?: boolean;
  
  /** Minimum binding size */
  minBindingSize?: GPUSize64;
}

interface GPUSamplerBindingLayout {
  /** Sampler binding type */
  type?: GPUSamplerBindingType;
}

interface GPUTextureBindingLayout {
  /** Sample type */
  sampleType?: GPUTextureSampleType;
  
  /** View dimension */
  viewDimension?: GPUTextureViewDimension;
  
  /** Whether texture is multisampled */
  multisampled?: boolean;
}

interface GPUStorageTextureBindingLayout {
  /** Storage access mode */
  access?: GPUStorageTextureAccess;
  
  /** Texture format */
  format: GPUTextureFormat;
  
  /** View dimension */
  viewDimension?: GPUTextureViewDimension;
}

interface GPUExternalTextureBindingLayout {}

type GPUSamplerBindingType = "filtering" | "non-filtering" | "comparison";
type GPUStorageTextureAccess = "write-only" | "read-only" | "read-write";

GPU External Texture

Texture created from external image sources.

interface GPUExternalTexture {
  /** Optional debug label */
  readonly label: string | undefined;
}

interface GPUExternalTextureDescriptor extends GPUObjectDescriptorBase {
  /** External image source */
  source: GPUCopyExternalImageSource;
  
  /** Color space for the texture */
  colorSpace?: GPUExternalTextureColorSpace;
}

type GPUExternalTextureColorSpace = "srgb";

GPU Query Set

Collection of query objects for performance measurement.

interface GPUQuerySet {
  /** Query type */
  readonly type: GPUQueryType;
  
  /** Number of queries in the set */
  readonly count: GPUSize32Out;
  
  /** Optional debug label */
  readonly label: string | undefined;
  
  /** Destroys the query set */
  destroy(): void;
}

interface GPUQuerySetDescriptor extends GPUObjectDescriptorBase {
  /** Type of queries */
  type: GPUQueryType;
  
  /** Number of queries in the set */
  count: GPUSize32;
}

type GPUQueryType = "occlusion" | "timestamp";

Usage Examples

Buffer Creation and Usage

// Create a vertex buffer
const vertexBuffer = device.createBuffer({
  size: vertices.byteLength,
  usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
  label: "Vertex Buffer"
});

// Write data to buffer
device.queue.writeBuffer(vertexBuffer, 0, vertices);

// Create a uniform buffer with mapped creation
const uniformBuffer = device.createBuffer({
  size: 256,
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
  mappedAtCreation: true,
  label: "Uniform Buffer"
});

// Write to mapped buffer
const mappedRange = uniformBuffer.getMappedRange();
new Float32Array(mappedRange).set([1.0, 0.0, 0.0, 1.0]);
uniformBuffer.unmap();

// Map buffer for reading
await resultBuffer.mapAsync(GPUMapMode.READ);
const result = new Float32Array(resultBuffer.getMappedRange());
console.log("Compute result:", Array.from(result));
resultBuffer.unmap();

Texture Creation and Views

// Create a 2D color texture
const colorTexture = device.createTexture({
  size: { width: 1024, height: 768 },
  format: "rgba8unorm",
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
  label: "Color Texture"
});

// Create a depth texture
const depthTexture = device.createTexture({
  size: { width: 1024, height: 768 },
  format: "depth24plus-stencil8",
  usage: GPUTextureUsage.RENDER_ATTACHMENT,
  label: "Depth Texture"
});

// Create texture views
const colorView = colorTexture.createView();
const depthView = depthTexture.createView();

// Create a texture array
const textureArray = device.createTexture({
  size: { width: 256, height: 256, depthOrArrayLayers: 6 },
  format: "rgba8unorm",
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
  label: "Texture Array"
});

// Create a cube map view
const cubeView = textureArray.createView({
  dimension: "cube"
});

Sampler Configuration

// Create a linear filtering sampler
const linearSampler = device.createSampler({
  magFilter: "linear",
  minFilter: "linear",
  mipmapFilter: "linear",
  addressModeU: "repeat",
  addressModeV: "repeat",
  label: "Linear Sampler"
});

// Create a comparison sampler for shadow mapping
const shadowSampler = device.createSampler({
  magFilter: "linear",
  minFilter: "linear",
  compare: "less-equal",
  addressModeU: "clamp-to-edge",
  addressModeV: "clamp-to-edge",
  label: "Shadow Sampler"
});

// Create a nearest neighbor sampler
const pixelSampler = device.createSampler({
  magFilter: "nearest",
  minFilter: "nearest",
  addressModeU: "clamp-to-edge",
  addressModeV: "clamp-to-edge",
  label: "Pixel Art Sampler"
});

Bind Group Creation

// Create bind group layout
const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
      buffer: { type: "uniform" }
    },
    {
      binding: 1,
      visibility: GPUShaderStage.FRAGMENT,
      sampler: {}
    },
    {
      binding: 2,
      visibility: GPUShaderStage.FRAGMENT,
      texture: {}
    }
  ],
  label: "Material Bind Group Layout"
});

// Create bind group
const bindGroup = device.createBindGroup({
  layout: bindGroupLayout,
  entries: [
    {
      binding: 0,
      resource: { buffer: uniformBuffer }
    },
    {
      binding: 1,
      resource: linearSampler
    },
    {
      binding: 2,
      resource: colorTexture.createView()
    }
  ],
  label: "Material Bind Group"
});

Storage Buffer Example

// Create storage buffer for compute
const storageBuffer = device.createBuffer({
  size: 1024 * 1024, // 1MB
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
  label: "Compute Storage Buffer"
});

// Create read-only storage buffer
const inputBuffer = device.createBuffer({
  size: data.byteLength,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
  mappedAtCreation: true,
  label: "Input Data"
});

new Float32Array(inputBuffer.getMappedRange()).set(data);
inputBuffer.unmap();

// Bind as storage in compute shader
const computeBindGroup = device.createBindGroup({
  layout: computeBindGroupLayout,
  entries: [
    {
      binding: 0,
      resource: { buffer: inputBuffer }
    },
    {
      binding: 1,
      resource: { buffer: storageBuffer }
    }
  ]
});

Query Set Usage

// Create timestamp query set
const timestampQuerySet = device.createQuerySet({
  type: "timestamp",
  count: 4,
  label: "Frame Timing Queries"
});

// Create occlusion query set
const occlusionQuerySet = device.createQuerySet({
  type: "occlusion",
  count: 10,
  label: "Occlusion Queries"
});

// Query buffer for results
const queryBuffer = device.createBuffer({
  size: 8 * timestampQuerySet.count, // 8 bytes per timestamp
  usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
  label: "Query Results"
});

// Use in render pass (timestamps)
const encoder = device.createCommandEncoder();
encoder.writeTimestamp(timestampQuerySet, 0);

const passEncoder = encoder.beginRenderPass({
  // ... render pass config
  timestampWrites: {
    querySet: timestampQuerySet,
    beginningOfPassWriteIndex: 1,
    endOfPassWriteIndex: 2
  }
});

// ... rendering commands ...

passEncoder.end();
encoder.writeTimestamp(timestampQuerySet, 3);

// Resolve query results
encoder.resolveQuerySet(timestampQuerySet, 0, 4, queryBuffer, 0);

Install with Tessl CLI