0
# Resources
1
2
GPU resource objects including buffers, textures, samplers, and bind groups for managing GPU memory and data binding.
3
4
## Capabilities
5
6
### GPU Buffer
7
8
Memory buffer for vertex data, uniforms, storage, and other GPU data.
9
10
```typescript { .api }
11
interface GPUBuffer {
12
/** Size of the buffer in bytes */
13
readonly size: GPUSize64Out;
14
15
/** Usage flags indicating how the buffer can be used */
16
readonly usage: GPUBufferUsageFlags;
17
18
/** Current mapping state */
19
readonly mapState: GPUBufferMapState;
20
21
/** Optional debug label */
22
readonly label: string | undefined;
23
24
/**
25
* Maps buffer memory for CPU access
26
* @param mode - Mapping mode (READ or WRITE)
27
* @param offset - Byte offset into the buffer
28
* @param size - Number of bytes to map
29
* @returns Promise that resolves when mapping is complete
30
*/
31
mapAsync(
32
mode: GPUMapModeFlags,
33
offset?: GPUSize64,
34
size?: GPUSize64
35
): Promise<void>;
36
37
/**
38
* Gets a mapped range as an ArrayBuffer
39
* @param offset - Byte offset into the mapped region
40
* @param size - Number of bytes to access
41
* @returns ArrayBuffer for the mapped range
42
*/
43
getMappedRange(offset?: GPUSize64, size?: GPUSize64): ArrayBuffer;
44
45
/** Unmaps the buffer, making it available for GPU use */
46
unmap(): void;
47
48
/** Destroys the buffer and releases resources */
49
destroy(): void;
50
}
51
52
interface GPUBufferDescriptor extends GPUObjectDescriptorBase {
53
/** Size of the buffer in bytes */
54
size: GPUSize64;
55
56
/** Buffer usage flags */
57
usage: GPUBufferUsageFlags;
58
59
/** Whether buffer should be mapped at creation */
60
mappedAtCreation?: boolean;
61
}
62
63
interface GPUBufferBinding {
64
/** Buffer to bind */
65
buffer: GPUBuffer;
66
67
/** Byte offset into the buffer */
68
offset?: GPUSize64;
69
70
/** Number of bytes to bind (defaults to entire buffer) */
71
size?: GPUSize64;
72
}
73
```
74
75
### GPU Texture
76
77
2D/3D texture for rendering, sampling, and storage operations.
78
79
```typescript { .api }
80
interface GPUTexture {
81
/** Width in texels */
82
readonly width: GPUIntegerCoordinateOut;
83
84
/** Height in texels */
85
readonly height: GPUIntegerCoordinateOut;
86
87
/** Depth or array layers */
88
readonly depthOrArrayLayers: GPUIntegerCoordinateOut;
89
90
/** Number of mip levels */
91
readonly mipLevelCount: GPUIntegerCoordinateOut;
92
93
/** Number of samples per texel */
94
readonly sampleCount: GPUSize32Out;
95
96
/** Texture dimension */
97
readonly dimension: GPUTextureDimension;
98
99
/** Pixel format */
100
readonly format: GPUTextureFormat;
101
102
/** Usage flags */
103
readonly usage: GPUTextureUsageFlags;
104
105
/** Optional debug label */
106
readonly label: string | undefined;
107
108
/**
109
* Creates a texture view
110
* @param descriptor - Optional view configuration
111
* @returns New texture view
112
*/
113
createView(descriptor?: GPUTextureViewDescriptor): GPUTextureView;
114
115
/** Destroys the texture and releases resources */
116
destroy(): void;
117
}
118
119
interface GPUTextureDescriptor extends GPUObjectDescriptorBase {
120
/** Texture dimensions */
121
size: GPUExtent3D;
122
123
/** Number of mip levels (default: 1) */
124
mipLevelCount?: GPUIntegerCoordinate;
125
126
/** Samples per texel (default: 1) */
127
sampleCount?: GPUSize32;
128
129
/** Texture dimension (default: "2d") */
130
dimension?: GPUTextureDimension;
131
132
/** Pixel format */
133
format: GPUTextureFormat;
134
135
/** Usage flags */
136
usage: GPUTextureUsageFlags;
137
}
138
```
139
140
### GPU Texture View
141
142
View into a texture with specific format and subresource range.
143
144
```typescript { .api }
145
interface GPUTextureView {
146
/** Optional debug label */
147
readonly label: string | undefined;
148
}
149
150
interface GPUTextureViewDescriptor extends GPUObjectDescriptorBase {
151
/** View format (defaults to texture format) */
152
format?: GPUTextureFormat;
153
154
/** View dimension (defaults to texture dimension) */
155
dimension?: GPUTextureViewDimension;
156
157
/** Texture aspect to view */
158
aspect?: GPUTextureAspect;
159
160
/** Base mip level */
161
baseMipLevel?: GPUIntegerCoordinate;
162
163
/** Number of mip levels */
164
mipLevelCount?: GPUIntegerCoordinate;
165
166
/** Base array layer */
167
baseArrayLayer?: GPUIntegerCoordinate;
168
169
/** Number of array layers */
170
arrayLayerCount?: GPUIntegerCoordinate;
171
}
172
```
173
174
### GPU Sampler
175
176
Texture sampling configuration for filtering and addressing.
177
178
```typescript { .api }
179
interface GPUSampler {
180
/** Optional debug label */
181
readonly label: string | undefined;
182
}
183
184
interface GPUSamplerDescriptor extends GPUObjectDescriptorBase {
185
/** Address mode for U coordinate */
186
addressModeU?: GPUAddressMode;
187
188
/** Address mode for V coordinate */
189
addressModeV?: GPUAddressMode;
190
191
/** Address mode for W coordinate */
192
addressModeW?: GPUAddressMode;
193
194
/** Magnification filter */
195
magFilter?: GPUFilterMode;
196
197
/** Minification filter */
198
minFilter?: GPUFilterMode;
199
200
/** Mipmap filter */
201
mipmapFilter?: GPUMipmapFilterMode;
202
203
/** Minimum LOD clamp */
204
lodMinClamp?: number;
205
206
/** Maximum LOD clamp */
207
lodMaxClamp?: number;
208
209
/** Comparison function for depth textures */
210
compare?: GPUCompareFunction;
211
212
/** Maximum anisotropy */
213
maxAnisotropy?: number;
214
}
215
```
216
217
### GPU Bind Group
218
219
Collection of resources bound together for shader access.
220
221
```typescript { .api }
222
interface GPUBindGroup {
223
/** Optional debug label */
224
readonly label: string | undefined;
225
}
226
227
interface GPUBindGroupDescriptor extends GPUObjectDescriptorBase {
228
/** Layout defining the bind group structure */
229
layout: GPUBindGroupLayout;
230
231
/** Array of resource bindings */
232
entries: Iterable<GPUBindGroupEntry>;
233
}
234
235
interface GPUBindGroupEntry {
236
/** Binding index matching shader */
237
binding: GPUIndex32;
238
239
/** Resource to bind */
240
resource: GPUBindingResource;
241
}
242
243
type GPUBindingResource =
244
| GPUSampler
245
| GPUTextureView
246
| GPUBufferBinding
247
| GPUExternalTexture;
248
```
249
250
### GPU Bind Group Layout
251
252
Template defining the structure and types of resources in a bind group.
253
254
```typescript { .api }
255
interface GPUBindGroupLayout {
256
/** Optional debug label */
257
readonly label: string | undefined;
258
}
259
260
interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase {
261
/** Array of binding entries */
262
entries: Iterable<GPUBindGroupLayoutEntry>;
263
}
264
265
interface GPUBindGroupLayoutEntry {
266
/** Binding index */
267
binding: GPUIndex32;
268
269
/** Shader stages that can access this binding */
270
visibility: GPUShaderStageFlags;
271
272
/** Buffer binding layout */
273
buffer?: GPUBufferBindingLayout;
274
275
/** Sampler binding layout */
276
sampler?: GPUSamplerBindingLayout;
277
278
/** Texture binding layout */
279
texture?: GPUTextureBindingLayout;
280
281
/** Storage texture binding layout */
282
storageTexture?: GPUStorageTextureBindingLayout;
283
284
/** External texture binding layout */
285
externalTexture?: GPUExternalTextureBindingLayout;
286
}
287
288
interface GPUBufferBindingLayout {
289
/** Buffer binding type */
290
type?: GPUBufferBindingType;
291
292
/** Whether binding has dynamic offset */
293
hasDynamicOffset?: boolean;
294
295
/** Minimum binding size */
296
minBindingSize?: GPUSize64;
297
}
298
299
interface GPUSamplerBindingLayout {
300
/** Sampler binding type */
301
type?: GPUSamplerBindingType;
302
}
303
304
interface GPUTextureBindingLayout {
305
/** Sample type */
306
sampleType?: GPUTextureSampleType;
307
308
/** View dimension */
309
viewDimension?: GPUTextureViewDimension;
310
311
/** Whether texture is multisampled */
312
multisampled?: boolean;
313
}
314
315
interface GPUStorageTextureBindingLayout {
316
/** Storage access mode */
317
access?: GPUStorageTextureAccess;
318
319
/** Texture format */
320
format: GPUTextureFormat;
321
322
/** View dimension */
323
viewDimension?: GPUTextureViewDimension;
324
}
325
326
interface GPUExternalTextureBindingLayout {}
327
328
type GPUSamplerBindingType = "filtering" | "non-filtering" | "comparison";
329
type GPUStorageTextureAccess = "write-only" | "read-only" | "read-write";
330
```
331
332
### GPU External Texture
333
334
Texture created from external image sources.
335
336
```typescript { .api }
337
interface GPUExternalTexture {
338
/** Optional debug label */
339
readonly label: string | undefined;
340
}
341
342
interface GPUExternalTextureDescriptor extends GPUObjectDescriptorBase {
343
/** External image source */
344
source: GPUCopyExternalImageSource;
345
346
/** Color space for the texture */
347
colorSpace?: GPUExternalTextureColorSpace;
348
}
349
350
type GPUExternalTextureColorSpace = "srgb";
351
```
352
353
### GPU Query Set
354
355
Collection of query objects for performance measurement.
356
357
```typescript { .api }
358
interface GPUQuerySet {
359
/** Query type */
360
readonly type: GPUQueryType;
361
362
/** Number of queries in the set */
363
readonly count: GPUSize32Out;
364
365
/** Optional debug label */
366
readonly label: string | undefined;
367
368
/** Destroys the query set */
369
destroy(): void;
370
}
371
372
interface GPUQuerySetDescriptor extends GPUObjectDescriptorBase {
373
/** Type of queries */
374
type: GPUQueryType;
375
376
/** Number of queries in the set */
377
count: GPUSize32;
378
}
379
380
type GPUQueryType = "occlusion" | "timestamp";
381
```
382
383
## Usage Examples
384
385
### Buffer Creation and Usage
386
387
```typescript
388
// Create a vertex buffer
389
const vertexBuffer = device.createBuffer({
390
size: vertices.byteLength,
391
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
392
label: "Vertex Buffer"
393
});
394
395
// Write data to buffer
396
device.queue.writeBuffer(vertexBuffer, 0, vertices);
397
398
// Create a uniform buffer with mapped creation
399
const uniformBuffer = device.createBuffer({
400
size: 256,
401
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
402
mappedAtCreation: true,
403
label: "Uniform Buffer"
404
});
405
406
// Write to mapped buffer
407
const mappedRange = uniformBuffer.getMappedRange();
408
new Float32Array(mappedRange).set([1.0, 0.0, 0.0, 1.0]);
409
uniformBuffer.unmap();
410
411
// Map buffer for reading
412
await resultBuffer.mapAsync(GPUMapMode.READ);
413
const result = new Float32Array(resultBuffer.getMappedRange());
414
console.log("Compute result:", Array.from(result));
415
resultBuffer.unmap();
416
```
417
418
### Texture Creation and Views
419
420
```typescript
421
// Create a 2D color texture
422
const colorTexture = device.createTexture({
423
size: { width: 1024, height: 768 },
424
format: "rgba8unorm",
425
usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
426
label: "Color Texture"
427
});
428
429
// Create a depth texture
430
const depthTexture = device.createTexture({
431
size: { width: 1024, height: 768 },
432
format: "depth24plus-stencil8",
433
usage: GPUTextureUsage.RENDER_ATTACHMENT,
434
label: "Depth Texture"
435
});
436
437
// Create texture views
438
const colorView = colorTexture.createView();
439
const depthView = depthTexture.createView();
440
441
// Create a texture array
442
const textureArray = device.createTexture({
443
size: { width: 256, height: 256, depthOrArrayLayers: 6 },
444
format: "rgba8unorm",
445
usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
446
label: "Texture Array"
447
});
448
449
// Create a cube map view
450
const cubeView = textureArray.createView({
451
dimension: "cube"
452
});
453
```
454
455
### Sampler Configuration
456
457
```typescript
458
// Create a linear filtering sampler
459
const linearSampler = device.createSampler({
460
magFilter: "linear",
461
minFilter: "linear",
462
mipmapFilter: "linear",
463
addressModeU: "repeat",
464
addressModeV: "repeat",
465
label: "Linear Sampler"
466
});
467
468
// Create a comparison sampler for shadow mapping
469
const shadowSampler = device.createSampler({
470
magFilter: "linear",
471
minFilter: "linear",
472
compare: "less-equal",
473
addressModeU: "clamp-to-edge",
474
addressModeV: "clamp-to-edge",
475
label: "Shadow Sampler"
476
});
477
478
// Create a nearest neighbor sampler
479
const pixelSampler = device.createSampler({
480
magFilter: "nearest",
481
minFilter: "nearest",
482
addressModeU: "clamp-to-edge",
483
addressModeV: "clamp-to-edge",
484
label: "Pixel Art Sampler"
485
});
486
```
487
488
### Bind Group Creation
489
490
```typescript
491
// Create bind group layout
492
const bindGroupLayout = device.createBindGroupLayout({
493
entries: [
494
{
495
binding: 0,
496
visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
497
buffer: { type: "uniform" }
498
},
499
{
500
binding: 1,
501
visibility: GPUShaderStage.FRAGMENT,
502
sampler: {}
503
},
504
{
505
binding: 2,
506
visibility: GPUShaderStage.FRAGMENT,
507
texture: {}
508
}
509
],
510
label: "Material Bind Group Layout"
511
});
512
513
// Create bind group
514
const bindGroup = device.createBindGroup({
515
layout: bindGroupLayout,
516
entries: [
517
{
518
binding: 0,
519
resource: { buffer: uniformBuffer }
520
},
521
{
522
binding: 1,
523
resource: linearSampler
524
},
525
{
526
binding: 2,
527
resource: colorTexture.createView()
528
}
529
],
530
label: "Material Bind Group"
531
});
532
```
533
534
### Storage Buffer Example
535
536
```typescript
537
// Create storage buffer for compute
538
const storageBuffer = device.createBuffer({
539
size: 1024 * 1024, // 1MB
540
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
541
label: "Compute Storage Buffer"
542
});
543
544
// Create read-only storage buffer
545
const inputBuffer = device.createBuffer({
546
size: data.byteLength,
547
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
548
mappedAtCreation: true,
549
label: "Input Data"
550
});
551
552
new Float32Array(inputBuffer.getMappedRange()).set(data);
553
inputBuffer.unmap();
554
555
// Bind as storage in compute shader
556
const computeBindGroup = device.createBindGroup({
557
layout: computeBindGroupLayout,
558
entries: [
559
{
560
binding: 0,
561
resource: { buffer: inputBuffer }
562
},
563
{
564
binding: 1,
565
resource: { buffer: storageBuffer }
566
}
567
]
568
});
569
```
570
571
### Query Set Usage
572
573
```typescript
574
// Create timestamp query set
575
const timestampQuerySet = device.createQuerySet({
576
type: "timestamp",
577
count: 4,
578
label: "Frame Timing Queries"
579
});
580
581
// Create occlusion query set
582
const occlusionQuerySet = device.createQuerySet({
583
type: "occlusion",
584
count: 10,
585
label: "Occlusion Queries"
586
});
587
588
// Query buffer for results
589
const queryBuffer = device.createBuffer({
590
size: 8 * timestampQuerySet.count, // 8 bytes per timestamp
591
usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
592
label: "Query Results"
593
});
594
595
// Use in render pass (timestamps)
596
const encoder = device.createCommandEncoder();
597
encoder.writeTimestamp(timestampQuerySet, 0);
598
599
const passEncoder = encoder.beginRenderPass({
600
// ... render pass config
601
timestampWrites: {
602
querySet: timestampQuerySet,
603
beginningOfPassWriteIndex: 1,
604
endOfPassWriteIndex: 2
605
}
606
});
607
608
// ... rendering commands ...
609
610
passEncoder.end();
611
encoder.writeTimestamp(timestampQuerySet, 3);
612
613
// Resolve query results
614
encoder.resolveQuerySet(timestampQuerySet, 0, 4, queryBuffer, 0);
615
```