Complete TypeScript type definitions for the WebGPU standard enabling type-safe GPU programming.
—
Configuration interfaces and descriptor objects for creating and configuring GPU resources, pipelines, and state.
Common base interface for all GPU object descriptors.
interface GPUObjectDescriptorBase {
/** Optional debug label for the object */
label?: string;
}Descriptors for buffer creation and binding.
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 from offset) */
size?: GPUSize64;
}Descriptors for texture and texture view creation.
interface GPUTextureDescriptor extends GPUObjectDescriptorBase {
/** Texture dimensions */
size: GPUExtent3D;
/** Number of mip levels (default: 1) */
mipLevelCount?: GPUIntegerCoordinate;
/** Samples per texel for multisampling (default: 1) */
sampleCount?: GPUSize32;
/** Texture dimension (default: "2d") */
dimension?: GPUTextureDimension;
/** Pixel format */
format: GPUTextureFormat;
/** Usage flags */
usage: GPUTextureUsageFlags;
/** View formats that can be used with this texture */
viewFormats?: Iterable<GPUTextureFormat>;
}
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 (defaults to all remaining) */
mipLevelCount?: GPUIntegerCoordinate;
/** Base array layer */
baseArrayLayer?: GPUIntegerCoordinate;
/** Number of array layers (defaults to all remaining) */
arrayLayerCount?: GPUIntegerCoordinate;
}Descriptor for sampler state configuration.
interface GPUSamplerDescriptor extends GPUObjectDescriptorBase {
/** Address mode for U coordinate (default: "clamp-to-edge") */
addressModeU?: GPUAddressMode;
/** Address mode for V coordinate (default: "clamp-to-edge") */
addressModeV?: GPUAddressMode;
/** Address mode for W coordinate (default: "clamp-to-edge") */
addressModeW?: GPUAddressMode;
/** Magnification filter (default: "nearest") */
magFilter?: GPUFilterMode;
/** Minification filter (default: "nearest") */
minFilter?: GPUFilterMode;
/** Mipmap filter (default: "nearest") */
mipmapFilter?: GPUMipmapFilterMode;
/** Minimum LOD clamp (default: 0) */
lodMinClamp?: number;
/** Maximum LOD clamp (default: 32) */
lodMaxClamp?: number;
/** Comparison function for depth textures */
compare?: GPUCompareFunction;
/** Maximum anisotropy (default: 1) */
maxAnisotropy?: number;
}Descriptors for bind groups and their layouts.
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;
}
interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase {
/** Array of binding layout 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 (default: "uniform") */
type?: GPUBufferBindingType;
/** Whether binding has dynamic offset */
hasDynamicOffset?: boolean;
/** Minimum binding size in bytes */
minBindingSize?: GPUSize64;
}
interface GPUSamplerBindingLayout {
/** Sampler binding type (default: "filtering") */
type?: GPUSamplerBindingType;
}
interface GPUTextureBindingLayout {
/** Sample type (default: "float") */
sampleType?: GPUTextureSampleType;
/** View dimension (default: "2d") */
viewDimension?: GPUTextureViewDimension;
/** Whether texture is multisampled */
multisampled?: boolean;
}
interface GPUStorageTextureBindingLayout {
/** Storage access mode (default: "write-only") */
access?: GPUStorageTextureAccess;
/** Texture format */
format: GPUTextureFormat;
/** View dimension (default: "2d") */
viewDimension?: GPUTextureViewDimension;
}
interface GPUExternalTextureBindingLayout {}Base configuration for pipelines and their layouts.
interface GPUPipelineLayoutDescriptor extends GPUObjectDescriptorBase {
/** Array of bind group layouts */
bindGroupLayouts: Iterable<GPUBindGroupLayout>;
}
interface GPUPipelineDescriptorBase extends GPUObjectDescriptorBase {
/** Pipeline layout or "auto" for automatic layout generation */
layout: GPUPipelineLayout | "auto";
}
interface GPUProgrammableStage {
/** Shader module containing the stage code */
module: GPUShaderModule;
/** Entry point function name (default: "main") */
entryPoint?: string;
/** Pipeline constants to specialize the shader */
constants?: Record<string, GPUPipelineConstantValue>;
}Complete render pipeline state configuration.
interface GPURenderPipelineDescriptor extends GPUPipelineDescriptorBase {
/** Vertex stage configuration */
vertex: GPUVertexState;
/** Primitive assembly configuration */
primitive?: GPUPrimitiveState;
/** Depth/stencil state */
depthStencil?: GPUDepthStencilState;
/** Multisample state */
multisample?: GPUMultisampleState;
/** Fragment stage configuration */
fragment?: GPUFragmentState;
}
interface GPUVertexState extends GPUProgrammableStage {
/** Vertex buffer layout descriptions */
buffers?: Iterable<GPUVertexBufferLayout | null>;
}
interface GPUVertexBufferLayout {
/** Stride between vertices in bytes */
arrayStride: GPUSize64;
/** Step mode for vertex fetching (default: "vertex") */
stepMode?: GPUVertexStepMode;
/** Vertex attribute descriptions */
attributes: Iterable<GPUVertexAttribute>;
}
interface GPUVertexAttribute {
/** Vertex format */
format: GPUVertexFormat;
/** Byte offset within vertex */
offset: GPUSize64;
/** Shader location binding */
shaderLocation: GPUIndex32;
}
interface GPUPrimitiveState {
/** Primitive topology (default: "triangle-list") */
topology?: GPUPrimitiveTopology;
/** Strip index format for strip topologies */
stripIndexFormat?: GPUIndexFormat;
/** Front face winding (default: "ccw") */
frontFace?: GPUFrontFace;
/** Face culling mode (default: "none") */
cullMode?: GPUCullMode;
/** Whether to enable conservative rasterization */
unclippedDepth?: boolean;
}
interface GPUFragmentState extends GPUProgrammableStage {
/** Color target states */
targets: Iterable<GPUColorTargetState | null>;
}
interface GPUColorTargetState {
/** Color format */
format: GPUTextureFormat;
/** Blend state */
blend?: GPUBlendState;
/** Write mask (default: all channels) */
writeMask?: GPUColorWriteFlags;
}
interface GPUBlendState {
/** Color blend configuration */
color: GPUBlendComponent;
/** Alpha blend configuration */
alpha: GPUBlendComponent;
}
interface GPUBlendComponent {
/** Blend operation (default: "add") */
operation?: GPUBlendOperation;
/** Source factor (default: "one") */
srcFactor?: GPUBlendFactor;
/** Destination factor (default: "zero") */
dstFactor?: GPUBlendFactor;
}
interface GPUDepthStencilState {
/** Depth/stencil format */
format: GPUTextureFormat;
/** Whether depth writes are enabled (default: false) */
depthWriteEnabled?: boolean;
/** Depth comparison function (default: "always") */
depthCompare?: GPUCompareFunction;
/** Stencil front face state */
stencilFront?: GPUStencilFaceState;
/** Stencil back face state */
stencilBack?: GPUStencilFaceState;
/** Stencil read mask (default: 0xFFFFFFFF) */
stencilReadMask?: GPUStencilValue;
/** Stencil write mask (default: 0xFFFFFFFF) */
stencilWriteMask?: GPUStencilValue;
/** Depth bias constant (default: 0) */
depthBias?: GPUDepthBias;
/** Depth bias slope scale (default: 0) */
depthBiasSlopeScale?: number;
/** Depth bias clamp (default: 0) */
depthBiasClamp?: number;
}
interface GPUStencilFaceState {
/** Comparison function (default: "always") */
compare?: GPUCompareFunction;
/** Fail operation (default: "keep") */
failOp?: GPUStencilOperation;
/** Depth fail operation (default: "keep") */
depthFailOp?: GPUStencilOperation;
/** Pass operation (default: "keep") */
passOp?: GPUStencilOperation;
}
interface GPUMultisampleState {
/** Number of samples (default: 1) */
count?: GPUSize32;
/** Sample mask (default: 0xFFFFFFFF) */
mask?: GPUSampleMask;
/** Alpha to coverage enabled (default: false) */
alphaToCoverageEnabled?: boolean;
}Configuration for compute pipelines.
interface GPUComputePipelineDescriptor extends GPUPipelineDescriptorBase {
/** Compute stage configuration */
compute: GPUProgrammableStage;
}Configuration for shader compilation and hints.
interface GPUShaderModuleDescriptor extends GPUObjectDescriptorBase {
/** WGSL shader source code */
code: string;
/** Optional compilation hints for optimization */
hints?: Record<string, GPUShaderModuleCompilationHint>;
}
interface GPUShaderModuleCompilationHint {
/** Entry point name */
entryPoint?: string;
/** Pipeline layout for optimization */
layout?: GPUPipelineLayout | "auto";
}Configuration for device creation and queues.
interface GPUDeviceDescriptor extends GPUObjectDescriptorBase {
/** Required features */
requiredFeatures?: Iterable<GPUFeatureName>;
/** Required limits */
requiredLimits?: Record<string, GPUSize64>;
/** Default queue configuration */
defaultQueue?: GPUQueueDescriptor;
}
interface GPUQueueDescriptor extends GPUObjectDescriptorBase {}
interface GPURequestAdapterOptions {
/** Power preference for adapter selection */
powerPreference?: GPUPowerPreference;
/** Force fallback adapter */
forceFallbackAdapter?: boolean;
}Configuration for canvas contexts and rendering.
interface GPUCanvasConfiguration {
/** Device to use for rendering */
device: GPUDevice;
/** Surface format */
format: GPUTextureFormat;
/** Surface usage flags (default: RENDER_ATTACHMENT) */
usage?: GPUTextureUsageFlags;
/** Color space (default: "srgb") */
colorSpace?: GPUCanvasColorSpace;
/** Tone mapping configuration */
toneMapping?: GPUCanvasToneMapping;
/** Alpha mode (default: "opaque") */
alphaMode?: GPUCanvasAlphaMode;
/** View formats that can be used */
viewFormats?: Iterable<GPUTextureFormat>;
}
interface GPUCanvasToneMapping {
/** Tone mapping mode (default: "standard") */
mode?: GPUCanvasToneMappingMode;
}
interface GPUCanvasConfigurationOut {
readonly device: GPUDevice;
readonly format: GPUTextureFormat;
readonly usage: GPUTextureUsageFlags;
readonly colorSpace: GPUCanvasColorSpace;
readonly toneMapping: GPUCanvasToneMapping;
readonly alphaMode: GPUCanvasAlphaMode;
readonly viewFormats: ReadonlyArray<GPUTextureFormat>;
}Configuration for query sets.
interface GPUQuerySetDescriptor extends GPUObjectDescriptorBase {
/** Type of queries in the set */
type: GPUQueryType;
/** Number of queries in the set */
count: GPUSize32;
}Configuration for external textures from image sources.
interface GPUExternalTextureDescriptor extends GPUObjectDescriptorBase {
/** External image source */
source: GPUCopyExternalImageSource;
/** Color space (default: "srgb") */
colorSpace?: GPUExternalTextureColorSpace;
}Configuration for command recording.
interface GPUCommandEncoderDescriptor extends GPUObjectDescriptorBase {}
interface GPUCommandBufferDescriptor extends GPUObjectDescriptorBase {}
interface GPURenderPassDescriptor extends GPUObjectDescriptorBase {
/** Color attachments */
colorAttachments: Iterable<GPURenderPassColorAttachment | null>;
/** Depth/stencil attachment */
depthStencilAttachment?: GPURenderPassDepthStencilAttachment;
/** Occlusion query set */
occlusionQuerySet?: GPUQuerySet;
/** Timestamp query writes */
timestampWrites?: GPURenderPassTimestampWrites;
/** Maximum number of draw commands */
maxDrawCount?: GPUSize64;
}
interface GPUComputePassDescriptor extends GPUObjectDescriptorBase {
/** Timestamp query writes */
timestampWrites?: GPUComputePassTimestampWrites;
}// Vertex buffer configuration
const vertexBufferDesc: GPUBufferDescriptor = {
size: vertexData.byteLength,
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
label: "Mesh Vertices"
};
const vertexBuffer = device.createBuffer(vertexBufferDesc);
// Uniform buffer with mapping
const uniformBufferDesc: GPUBufferDescriptor = {
size: 256, // 4x4 matrix + padding
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
mappedAtCreation: true,
label: "View-Projection Matrix"
};
const uniformBuffer = device.createBuffer(uniformBufferDesc);
// Storage buffer for compute
const storageBufferDesc: GPUBufferDescriptor = {
size: 1024 * 1024, // 1MB
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
label: "Particle Data"
};
const storageBuffer = device.createBuffer(storageBufferDesc);// Color texture with mipmaps
const colorTextureDesc: GPUTextureDescriptor = {
size: { width: 1024, height: 1024 },
mipLevelCount: Math.floor(Math.log2(1024)) + 1, // Full mip chain
format: "rgba8unorm",
usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
label: "Albedo Texture"
};
const colorTexture = device.createTexture(colorTextureDesc);
// Depth buffer
const depthTextureDesc: GPUTextureDescriptor = {
size: { width: 1920, height: 1080 },
format: "depth24plus-stencil8",
usage: GPUTextureUsage.RENDER_ATTACHMENT,
label: "Scene Depth Buffer"
};
const depthTexture = device.createTexture(depthTextureDesc);
// Multisampled render target
const msaaTextureDesc: GPUTextureDescriptor = {
size: { width: 1920, height: 1080 },
sampleCount: 4,
format: "bgra8unorm",
usage: GPUTextureUsage.RENDER_ATTACHMENT,
label: "MSAA Color Target"
};
const msaaTexture = device.createTexture(msaaTextureDesc);
// Cube map texture
const cubeTextureDesc: GPUTextureDescriptor = {
size: { width: 512, height: 512, depthOrArrayLayers: 6 },
format: "rgba16float",
usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
label: "Environment Cube Map"
};
const cubeTexture = device.createTexture(cubeTextureDesc);// Linear filtering sampler
const linearSamplerDesc: GPUSamplerDescriptor = {
addressModeU: "repeat",
addressModeV: "repeat",
magFilter: "linear",
minFilter: "linear",
mipmapFilter: "linear",
label: "Linear Repeat Sampler"
};
const linearSampler = device.createSampler(linearSamplerDesc);
// Shadow comparison sampler
const shadowSamplerDesc: GPUSamplerDescriptor = {
addressModeU: "clamp-to-edge",
addressModeV: "clamp-to-edge",
magFilter: "linear",
minFilter: "linear",
compare: "less-equal",
label: "Shadow Sampler"
};
const shadowSampler = device.createSampler(shadowSamplerDesc);
// Anisotropic filtering sampler
const anisotropicSamplerDesc: GPUSamplerDescriptor = {
addressModeU: "repeat",
addressModeV: "repeat",
magFilter: "linear",
minFilter: "linear",
mipmapFilter: "linear",
maxAnisotropy: 16,
label: "Anisotropic Sampler"
};
const anisotropicSampler = device.createSampler(anisotropicSamplerDesc);// Material bind group layout
const materialLayoutDesc: GPUBindGroupLayoutDescriptor = {
entries: [
{
binding: 0,
visibility: GPUShaderStage.FRAGMENT,
buffer: { type: "uniform" }
},
{
binding: 1,
visibility: GPUShaderStage.FRAGMENT,
sampler: { type: "filtering" }
},
{
binding: 2,
visibility: GPUShaderStage.FRAGMENT,
texture: { sampleType: "float", viewDimension: "2d" }
},
{
binding: 3,
visibility: GPUShaderStage.FRAGMENT,
texture: { sampleType: "float", viewDimension: "2d" }
}
],
label: "Material Layout"
};
const materialLayout = device.createBindGroupLayout(materialLayoutDesc);
// Compute bind group layout
const computeLayoutDesc: GPUBindGroupLayoutDescriptor = {
entries: [
{
binding: 0,
visibility: GPUShaderStage.COMPUTE,
buffer: { type: "read-only-storage" }
},
{
binding: 1,
visibility: GPUShaderStage.COMPUTE,
buffer: { type: "storage" }
},
{
binding: 2,
visibility: GPUShaderStage.COMPUTE,
storageTexture: {
access: "write-only",
format: "rgba8unorm",
viewDimension: "2d"
}
}
],
label: "Compute Layout"
};
const computeLayout = device.createBindGroupLayout(computeLayoutDesc);// Complete render pipeline configuration
const renderPipelineDesc: GPURenderPipelineDescriptor = {
layout: device.createPipelineLayout({
bindGroupLayouts: [sceneLayout, materialLayout]
}),
vertex: {
module: vertexShader,
entryPoint: "vs_main",
buffers: [
{
arrayStride: 44, // Position(12) + Normal(12) + Tangent(16) + UV(8)
attributes: [
{ format: "float32x3", offset: 0, shaderLocation: 0 }, // position
{ format: "float32x3", offset: 12, shaderLocation: 1 }, // normal
{ format: "float32x4", offset: 24, shaderLocation: 2 }, // tangent
{ format: "float32x2", offset: 40, shaderLocation: 3 } // uv
]
}
]
},
primitive: {
topology: "triangle-list",
cullMode: "back",
frontFace: "ccw"
},
depthStencil: {
format: "depth24plus-stencil8",
depthWriteEnabled: true,
depthCompare: "less",
stencilFront: {
compare: "always",
failOp: "keep",
depthFailOp: "keep",
passOp: "replace"
},
stencilBack: {
compare: "always",
failOp: "keep",
depthFailOp: "keep",
passOp: "replace"
}
},
multisample: {
count: 4,
alphaToCoverageEnabled: false
},
fragment: {
module: fragmentShader,
entryPoint: "fs_main",
targets: [
{
format: "bgra8unorm",
blend: {
color: {
srcFactor: "src-alpha",
dstFactor: "one-minus-src-alpha",
operation: "add"
},
alpha: {
srcFactor: "one",
dstFactor: "one-minus-src-alpha",
operation: "add"
}
},
writeMask: GPUColorWrite.ALL
}
]
},
label: "PBR Render Pipeline"
};
const renderPipeline = device.createRenderPipeline(renderPipelineDesc);// Configure canvas for high-quality rendering
const canvasConfig: GPUCanvasConfiguration = {
device,
format: navigator.gpu.getPreferredCanvasFormat(),
usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
colorSpace: "display-p3", // Wide color gamut
alphaMode: "premultiplied",
toneMapping: { mode: "extended" }
};
context.configure(canvasConfig);
// Alternative configuration for maximum compatibility
const compatConfig: GPUCanvasConfiguration = {
device,
format: "bgra8unorm",
usage: GPUTextureUsage.RENDER_ATTACHMENT,
colorSpace: "srgb",
alphaMode: "opaque"
};// Request device with specific features and limits
const deviceDesc: GPUDeviceDescriptor = {
requiredFeatures: [
"depth-clip-control",
"timestamp-query",
"texture-compression-bc",
"indirect-first-instance"
],
requiredLimits: {
maxTextureDimension2D: 8192,
maxBufferSize: 1024 * 1024 * 1024, // 1GB
maxStorageBufferBindingSize: 128 * 1024 * 1024, // 128MB
maxUniformBufferBindingSize: 64 * 1024, // 64KB
maxBindGroups: 8,
maxDynamicUniformBuffersPerPipelineLayout: 8,
maxComputeWorkgroupSizeX: 1024,
maxComputeWorkgroupSizeY: 1024,
maxComputeWorkgroupSizeZ: 64
},
defaultQueue: {
label: "Main Queue"
},
label: "High Performance Device"
};
const device = await adapter.requestDevice(deviceDesc);// Timestamp query set for performance measurement
const timestampQueryDesc: GPUQuerySetDescriptor = {
type: "timestamp",
count: 16, // Enough for multiple passes
label: "Frame Timing Queries"
};
const timestampQueries = device.createQuerySet(timestampQueryDesc);
// Occlusion query set for visibility testing
const occlusionQueryDesc: GPUQuerySetDescriptor = {
type: "occlusion",
count: 100, // For many objects
label: "Occlusion Queries"
};
const occlusionQueries = device.createQuerySet(occlusionQueryDesc);Install with Tessl CLI
npx tessl i tessl/npm-webgpu--types