0
# @webgpu/types
1

2
TypeScript type definitions for the WebGPU standard, providing complete type safety for GPU programming in web browsers. This package defines interfaces, types, and constants that enable developers to use WebGPU APIs with full IntelliSense support and compile-time error checking.
3

4
## Package Information
5

6
- **Package Name**: @webgpu/types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @webgpu/types`
10

11
## Core Imports
12

13
Since this is a type definitions package, it provides ambient types that augment the global DOM environment:
14

15
```typescript
16
/// <reference types="@webgpu/types" />
17
```
18

19
Or via tsconfig.json:
20

21
```json
22
{
23
  "compilerOptions": {
24
    "types": ["@webgpu/types"]
25
  }
26
}
27
```
28

29
Alternative configuration using typeRoots:
30

31
```json
32
{
33
  "compilerOptions": {
34
    "typeRoots": ["./node_modules/@webgpu/types", "./node_modules/@types"]
35
  }
36
}
37
```
38

39
## Basic Usage
40

41
After configuring the types, WebGPU APIs become available with full type safety:
42

43
```typescript
44
// Access the GPU API through navigator
45
const gpu: GPU = navigator.gpu;
46

47
// Request an adapter with type safety
48
const adapter: GPUAdapter | null = await gpu.requestAdapter({
49
  powerPreference: "high-performance"
50
});
51

52
if (!adapter) {
53
  throw new Error("WebGPU not supported");
54
}
55

56
// Request a device with features and limits
57
const device: GPUDevice = await adapter.requestDevice({
58
  requiredFeatures: ["depth-clip-control"],
59
  requiredLimits: {
60
    maxBufferSize: 512 * 1024 * 1024
61
  }
62
});
63

64
// Configure canvas context
65
const canvas = document.querySelector('canvas') as HTMLCanvasElement;
66
const context: GPUCanvasContext = canvas.getContext('webgpu')!;
67

68
context.configure({
69
  device,
70
  format: gpu.getPreferredCanvasFormat(),
71
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
72
});
73
```
74

75
## Architecture
76

77
@webgpu/types provides comprehensive type coverage for the WebGPU ecosystem:
78

79
- **Ambient DOM Extensions**: Enhances existing interfaces like `Navigator`, `HTMLCanvasElement`
80
- **Complete Type Hierarchy**: 200+ interfaces covering the entire WebGPU specification
81
- **Strict Type Variants**: Additional safety types like `GPUExtent3DStrict` to prevent common errors
82
- **Usage Flag Constants**: Strongly-typed constants for buffer usage, texture usage, etc.
83
- **Error Type Hierarchy**: Complete error handling with `GPUError` subtypes
84
- **Event System**: Type-safe event handling for GPU device events
85

86
## Capabilities
87

88
### Core Types and Enums
89

90
Basic types, primitive aliases, and string literal enums that form the foundation of the WebGPU type system.
91

92
```typescript { .api }
93
type GPUSize32 = number;
94
type GPUIntegerCoordinate = number;
95
type GPUExtent3D = Iterable<GPUIntegerCoordinate> | GPUExtent3DDict;
96

97
type GPUTextureFormat = 
98
  | "r8unorm" | "r8snorm" | "r8uint" | "r8sint"
99
  | "r16uint" | "r16sint" | "r16float"
100
  | "rg8unorm" | "rg8snorm" | "rg8uint" | "rg8sint"
101
  // ... 98 more texture formats
102

103
type GPUBufferUsageFlags = number;
104
```
105

106
[Core Types and Enums](./core-types.md)
107

108
### GPU Interfaces
109

110
Main WebGPU interfaces including the root GPU object, adapters, and devices that provide the foundation for GPU access.
111

112
```typescript { .api }
113
interface GPU {
114
  requestAdapter(options?: GPURequestAdapterOptions): Promise<GPUAdapter | null>;
115
  getPreferredCanvasFormat(): GPUTextureFormat;
116
}
117

118
interface GPUAdapter {
119
  readonly features: GPUSupportedFeatures;
120
  readonly limits: GPUSupportedLimits;
121
  readonly info: GPUAdapterInfo;
122
  requestDevice(descriptor?: GPUDeviceDescriptor): Promise<GPUDevice>;
123
}
124

125
interface GPUDevice extends EventTarget {
126
  readonly features: GPUSupportedFeatures;
127
  readonly limits: GPUSupportedLimits;
128
  readonly queue: GPUQueue;
129
  destroy(): void;
130
  createBuffer(descriptor: GPUBufferDescriptor): GPUBuffer;
131
  createTexture(descriptor: GPUTextureDescriptor): GPUTexture;
132
  // ... many more creation methods
133
}
134
```
135

136
[GPU Interfaces](./gpu-interfaces.md)
137

138
### Resources
139

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

142
```typescript { .api }
143
interface GPUBuffer {
144
  readonly size: GPUSize64Out;
145
  readonly usage: GPUBufferUsageFlags;
146
  readonly mapState: GPUBufferMapState;
147
  mapAsync(mode: GPUMapModeFlags, offset?: GPUSize64, size?: GPUSize64): Promise<void>;
148
  getMappedRange(offset?: GPUSize64, size?: GPUSize64): ArrayBuffer;
149
  unmap(): void;
150
  destroy(): void;
151
}
152

153
interface GPUTexture {
154
  readonly width: GPUIntegerCoordinateOut;
155
  readonly height: GPUIntegerCoordinateOut;
156
  readonly depthOrArrayLayers: GPUIntegerCoordinateOut;
157
  readonly format: GPUTextureFormat;
158
  readonly usage: GPUTextureUsageFlags;
159
  createView(descriptor?: GPUTextureViewDescriptor): GPUTextureView;
160
  destroy(): void;
161
}
162

163
interface GPUBindGroup {
164
  readonly label: string | undefined;
165
}
166
```
167

168
[Resources](./resources.md)
169

170
### Pipelines and Shaders
171

172
Render pipelines, compute pipelines, and shader modules for defining GPU programs and rendering state.
173

174
```typescript { .api }
175
interface GPURenderPipeline {
176
  readonly label: string | undefined;
177
  getBindGroupLayout(index: number): GPUBindGroupLayout;
178
}
179

180
interface GPUComputePipeline {
181
  readonly label: string | undefined;
182
  getBindGroupLayout(index: number): GPUBindGroupLayout;
183
}
184

185
interface GPUShaderModule {
186
  readonly label: string | undefined;
187
  getCompilationInfo(): Promise<GPUCompilationInfo>;
188
}
189
```
190

191
[Pipelines and Shaders](./pipelines.md)
192

193
### Commands and Passes
194

195
Command recording, encoding, and execution including render passes and compute passes.
196

197
```typescript { .api }
198
interface GPUCommandEncoder {
199
  beginRenderPass(descriptor: GPURenderPassDescriptor): GPURenderPassEncoder;
200
  beginComputePass(descriptor?: GPUComputePassDescriptor): GPUComputePassEncoder;
201
  copyBufferToBuffer(source: GPUBuffer, sourceOffset: GPUSize64, destination: GPUBuffer, destinationOffset: GPUSize64, size: GPUSize64): void;
202
  copyBufferToTexture(source: GPUTexelCopyBufferInfo, destination: GPUTexelCopyTextureInfo, copySize: GPUExtent3D): void;
203
  finish(descriptor?: GPUCommandBufferDescriptor): GPUCommandBuffer;
204
}
205

206
interface GPURenderPassEncoder extends GPURenderCommandsMixin {
207
  setViewport(x: number, y: number, width: number, height: number, minDepth: number, maxDepth: number): void;
208
  setScissorRect(x: GPUIntegerCoordinate, y: GPUIntegerCoordinate, width: GPUIntegerCoordinate, height: GPUIntegerCoordinate): void;
209
  end(): void;
210
}
211
```
212

213
[Commands and Passes](./commands.md)
214

215
### Render Bundles
216

217
Pre-recorded command bundles for efficient command resubmission and improved rendering performance.
218

219
```typescript { .api }
220
interface GPURenderBundle extends GPUObjectBase {
221
  readonly label: string | undefined;
222
}
223

224
interface GPURenderBundleEncoder extends 
225
  GPUObjectBase,
226
  GPUCommandsMixin,
227
  GPUDebugCommandsMixin,
228
  GPUBindingCommandsMixin,
229
  GPURenderCommandsMixin {
230
  readonly label: string | undefined;
231
  finish(descriptor?: GPURenderBundleDescriptor): GPURenderBundle;
232
}
233
```
234

235
[Render Bundles](./render-bundles.md)
236

237
### Configuration and Descriptors
238

239
Configuration interfaces and descriptor objects for creating and configuring GPU resources and state.
240

241
```typescript { .api }
242
interface GPUBufferDescriptor extends GPUObjectDescriptorBase {
243
  size: GPUSize64;
244
  usage: GPUBufferUsageFlags;
245
  mappedAtCreation?: boolean;
246
}
247

248
interface GPUTextureDescriptor extends GPUObjectDescriptorBase {
249
  size: GPUExtent3D;
250
  mipLevelCount?: GPUIntegerCoordinate;
251
  sampleCount?: GPUSize32;
252
  dimension?: GPUTextureDimension;
253
  format: GPUTextureFormat;
254
  usage: GPUTextureUsageFlags;
255
}
256

257
interface GPURenderPipelineDescriptor extends GPUPipelineDescriptorBase {
258
  vertex: GPUVertexState;
259
  primitive?: GPUPrimitiveState;
260
  depthStencil?: GPUDepthStencilState;
261
  multisample?: GPUMultisampleState;
262
  fragment?: GPUFragmentState;
263
}
264
```
265

266
[Configuration and Descriptors](./configuration.md)
267

268
## Usage Constants
269

270
The package provides strongly-typed constants for various usage flags:
271

272
```typescript { .api }
273
interface GPUBufferUsage {
274
  readonly MAP_READ: GPUFlagsConstant;
275
  readonly MAP_WRITE: GPUFlagsConstant;
276
  readonly COPY_SRC: GPUFlagsConstant;
277
  readonly COPY_DST: GPUFlagsConstant;
278
  readonly INDEX: GPUFlagsConstant;
279
  readonly VERTEX: GPUFlagsConstant;
280
  readonly UNIFORM: GPUFlagsConstant;
281
  readonly STORAGE: GPUFlagsConstant;
282
  readonly INDIRECT: GPUFlagsConstant;
283
  readonly QUERY_RESOLVE: GPUFlagsConstant;
284
}
285

286
declare var GPUBufferUsage: GPUBufferUsage;
287

288
interface GPUColorWrite {
289
  readonly RED: GPUFlagsConstant;
290
  readonly GREEN: GPUFlagsConstant;
291
  readonly BLUE: GPUFlagsConstant;
292
  readonly ALPHA: GPUFlagsConstant;
293
  readonly ALL: GPUFlagsConstant;
294
}
295

296
declare var GPUColorWrite: GPUColorWrite;
297

298
interface GPUMapMode {
299
  readonly READ: GPUFlagsConstant;
300
  readonly WRITE: GPUFlagsConstant;
301
}
302

303
declare var GPUMapMode: GPUMapMode;
304

305
interface GPUShaderStage {
306
  readonly VERTEX: GPUFlagsConstant;
307
  readonly FRAGMENT: GPUFlagsConstant;
308
  readonly COMPUTE: GPUFlagsConstant;
309
}
310

311
declare var GPUShaderStage: GPUShaderStage;
312

313
interface GPUTextureUsage {
314
  readonly COPY_SRC: GPUFlagsConstant;
315
  readonly COPY_DST: GPUFlagsConstant;
316
  readonly TEXTURE_BINDING: GPUFlagsConstant;
317
  readonly STORAGE_BINDING: GPUFlagsConstant;
318
  readonly RENDER_ATTACHMENT: GPUFlagsConstant;
319
}
320

321
declare var GPUTextureUsage: GPUTextureUsage;
322
```
323

324
## DOM Integration
325

326
The package extends existing DOM interfaces for seamless WebGPU integration:
327

328
```typescript { .api }
329
interface HTMLCanvasElement {
330
  getContext(contextId: "webgpu"): GPUCanvasContext | null;
331
}
332

333
interface OffscreenCanvas {
334
  getContext(contextId: "webgpu"): GPUCanvasContext | null;
335
}
336

337
interface Navigator extends NavigatorGPU {}
338
interface WorkerNavigator extends NavigatorGPU {}
339

340
interface NavigatorGPU {
341
  readonly gpu: GPU;
342
}
343
```