1. Introduction
This specification rocks.
2. Type Definitions
typedef long ;i32 typedef unsigned long ;u32 typedef unsigned long long ;u64 dictionary {GPUColorDict required float ;r required float ;g required float ;b required float ; };a typedef (sequence <float >or GPUColorDict );GPUColor dictionary {GPUOrigin2DDict u32 = 0;x u32 = 0; };y typedef (sequence <u32 >or GPUOrigin2DDict );GPUOrigin2D dictionary {GPUOrigin3DDict u32 = 0;x u32 = 0;y u32 = 0; };z typedef (sequence <u32 >or GPUOrigin3DDict );GPUOrigin3D dictionary {GPUExtent3DDict required u32 ;width required u32 ;height required u32 ; };depth typedef (sequence <u32 >or GPUExtent3DDict );GPUExtent3D typedef sequence <any >; // [GPUBuffer, ArrayBuffer]GPUMappedBuffer interface mixin {GPUObjectBase attribute DOMString ?; };label dictionary {GPUObjectDescriptorBase DOMString ?; };label
3. Buffers
typedef u32 ;GPUBufferUsageFlags interface {GPUBufferUsage const u32 = 0x0000;NONE const u32 = 0x0001;MAP_READ const u32 = 0x0002;MAP_WRITE const u32 = 0x0004;TRANSFER_SRC const u32 = 0x0008;TRANSFER_DST const u32 = 0x0010;INDEX const u32 = 0x0020;VERTEX const u32 = 0x0040;UNIFORM const u32 = 0x0080; };STORAGE dictionary :GPUBufferDescriptor GPUObjectDescriptorBase {required u64 ;size required GPUBufferUsageFlags ; };usage interface :GPUBuffer GPUObjectBase {Promise <ArrayBuffer >();mapReadAsync Promise <ArrayBuffer >();mapWriteAsync void ();unmap void (); };destroy
4. Textures
enum {GPUTextureDimension ,"1d" ,"2d" }; // Texture formats // The name of the format specifies the order of components, bits per component, and data type for // the component. // r, g, b, a = red, green, blue, alpha // unorm = unsigned normalized // snorm = signed normalized // uint = unsigned int // sint = signed int // float = floating point // If the format has the "-srgb" suffix, then sRGB gamma compression and decompression are // applied during the reading and writing of color values in the pixel. // Compressed texture formats are provided by extensions. Their naming should follow the // convention here, with the texture name as a prefix. e.g. "etc2-rgba8unorm"."3d" enum { /* Normal 8 bit formats */GPUTextureFormat ,"r8unorm" ,"r8unorm-srgb" ,"r8snorm" ,"r8uint" , /* Normal 16 bit formats */"r8sint" ,"r16unorm" ,"r16snorm" ,"r16uint" ,"r16sint" ,"r16float" ,"rg8unorm" ,"rg8unorm-srgb" ,"rg8snorm" ,"rg8uint" , /* Packed 16 bit formats */"rg8sint" , /* Normal 32 bit formats */"b5g6r5unorm" ,"r32uint" ,"r32sint" ,"r32float" ,"rg16unorm" ,"rg16snorm" ,"rg16uint" ,"rg16sint" ,"rg16float" ,"rgba8unorm" ,"rgba8unorm-srgb" ,"rgba8snorm" ,"rgba8uint" ,"rgba8sint" ,"bgra8unorm" , /* Packed 32 bit formats */"bgra8unorm-srgb" ,"rgb10a2unorm" , /* Normal 64 bit formats */"rg11b10float" ,"rg32uint" ,"rg32sint" ,"rg32float" ,"rgba16unorm" ,"rgba16snorm" ,"rgba16uint" ,"rgba16sint" , /* Normal 128 bit formats */"rgba16float" ,"rgba32uint" ,"rgba32sint" , /* Depth and Stencil formats */"rgba32float" , // depth24plus has a precision of 1 ULP <= 1/(2**24). // (This is unlike the 24-bit unsigned normalized format family typically // found in native APIs, which has a precision of 1 ULP = 1/(2**24-1).)"depth32float" ,"depth24plus" };"depth24plus-stencil8" typedef u32 ;GPUTextureUsageFlags interface {GPUTextureUsage const u32 = 0x00;NONE const u32 = 0x01;TRANSFER_SRC const u32 = 0x02;TRANSFER_DST const u32 = 0x04;SAMPLED const u32 = 0x08;STORAGE const u32 = 0x10; };OUTPUT_ATTACHMENT dictionary :GPUTextureDescriptor GPUObjectDescriptorBase {required GPUExtent3D ;size u32 = 1;arrayLayerCount u32 = 1;mipLevelCount u32 = 1;sampleCount GPUTextureDimension = "2d";dimension required GPUTextureFormat ;format required GPUTextureUsageFlags ; }; // Texture viewusage enum {GPUTextureViewDimension ,"1d" ,"2d" ,"2d-array" ,"cube" ,"cube-array" };"3d" enum {GPUTextureAspect ,"all" ,"stencil-only" };"depth-only" dictionary :GPUTextureViewDescriptor GPUObjectDescriptorBase {required GPUTextureFormat ;format required GPUTextureViewDimension ;dimension required GPUTextureAspect ;aspect u32 = 0;baseMipLevel u32 = 1;mipLevelCount u32 = 0;baseArrayLayer u32 = 1; };arrayLayerCount interface :GPUTextureView GPUObjectBase { };interface :GPUTexture GPUObjectBase {GPUTextureView (createView GPUTextureViewDescriptor );desc GPUTextureView ();createDefaultView void (); };destroy
5. Samplers
enum {GPUAddressMode ,"clamp-to-edge" ,"repeat" };"mirror-repeat" enum {GPUFilterMode ,"nearest" };"linear" enum {GPUCompareFunction ,"never" ,"less" ,"equal" ,"less-equal" ,"greater" ,"not-equal" ,"greater-equal" };"always" dictionary :GPUSamplerDescriptor GPUObjectDescriptorBase {GPUAddressMode = "clamp-to-edge";addressModeU GPUAddressMode = "clamp-to-edge";addressModeV GPUAddressMode = "clamp-to-edge";addressModeW GPUFilterMode = "nearest";magFilter GPUFilterMode = "nearest";minFilter GPUFilterMode = "nearest";mipmapFilter float = 0;lodMinClamp float = 0xffffffff; // TODO: What should this be? Was Number.MAX_VALUE.lodMaxClamp GPUCompareFunction = "never"; };compare interface :GPUSampler GPUObjectBase { };
6. Binding and Layout
typedef u32 ;GPUShaderStageFlags interface {GPUShaderStageBit const u32 = 0x0;NONE const u32 = 0x1;VERTEX const u32 = 0x2;FRAGMENT const u32 = 0x4; };COMPUTE enum {GPUBindingType ,"uniform-buffer" ,"storage-buffer" ,"readonly-storage-buffer" ,"sampler" ,"sampled-texture" // TODO other binding types };"storage-texture" dictionary {GPUBindGroupLayoutBinding required u32 ;binding required GPUShaderStageFlags ;visibility required GPUBindingType ; // For uniform, storage and readonly storage buffer, means that the binding // has a dynamic offset. One offset must be passed to setBindGroup for each // dynamic binding in increasing order of `binding` number.type boolean =dynamic false ; };dictionary :GPUBindGroupLayoutDescriptor GPUObjectDescriptorBase {required sequence <GPUBindGroupLayoutBinding >; };bindings interface :GPUBindGroupLayout GPUObjectBase { };dictionary :GPUPipelineLayoutDescriptor GPUObjectDescriptorBase {required sequence <GPUBindGroupLayout >; };bindGroupLayouts interface :GPUPipelineLayout GPUObjectBase { };dictionary {GPUBufferBinding required GPUBuffer ;buffer u64 = 0; // If size is undefined, use the whole size of the buffer.offset u64 ; };size typedef (GPUSampler or GPUTextureView or GPUBufferBinding );GPUBindingResource dictionary {GPUBindGroupBinding required u32 ;binding required GPUBindingResource ; };resource dictionary :GPUBindGroupDescriptor GPUObjectDescriptorBase {required GPUBindGroupLayout ;layout required sequence <GPUBindGroupBinding >; };bindings interface :GPUBindGroup GPUObjectBase { };
7. Shader Module
// Note: While the choice of shader language is undecided, // GPUShaderModuleDescriptor will temporarily accept both // text and binary input.typedef (Uint32Array or DOMString );GPUShaderCode dictionary :GPUShaderModuleDescriptor GPUObjectDescriptorBase {required GPUShaderCode ; };code interface :GPUShaderModule GPUObjectBase { };
8. Pipeline Creation
// RasterizationStateenum {GPUFrontFace ,"ccw" };"cw" enum {GPUCullMode ,"none" ,"front" };"back" dictionary {GPURasterizationStateDescriptor GPUFrontFace = "ccw";frontFace GPUCullMode = "none";cullMode i32 = 0;depthBias float = 0;depthBiasSlopeScale float = 0; }; // BlendStatedepthBiasClamp enum {GPUBlendFactor ,"zero" ,"one" ,"src-color" ,"one-minus-src-color" ,"src-alpha" ,"one-minus-src-alpha" ,"dst-color" ,"one-minus-dst-color" ,"dst-alpha" ,"one-minus-dst-alpha" ,"src-alpha-saturated" ,"blend-color" };"one-minus-blend-color" enum {GPUBlendOperation ,"add" ,"subtract" ,"reverse-subtract" ,"min" };"max" typedef u32 ;GPUColorWriteFlags interface {GPUColorWriteBits const u32 = 0x0;NONE const u32 = 0x1;RED const u32 = 0x2;GREEN const u32 = 0x4;BLUE const u32 = 0x8;ALPHA const u32 = 0xF; };ALL dictionary {GPUBlendDescriptor GPUBlendFactor = "one";srcFactor GPUBlendFactor = "zero";dstFactor GPUBlendOperation = "add"; };operation dictionary {GPUColorStateDescriptor required GPUTextureFormat ;format required GPUBlendDescriptor ;alphaBlend required GPUBlendDescriptor ;colorBlend GPUColorWriteFlags = 0xF; // GPUColorWriteBits.ALL };writeMask enum {GPUStencilOperation ,"keep" ,"zero" ,"replace" ,"invert" ,"increment-clamp" ,"decrement-clamp" ,"increment-wrap" };"decrement-wrap" dictionary {GPUStencilStateFaceDescriptor GPUCompareFunction = "always";compare GPUStencilOperation = "keep";failOp GPUStencilOperation = "keep";depthFailOp GPUStencilOperation = "keep"; };passOp dictionary {GPUDepthStencilStateDescriptor required GPUTextureFormat ;format boolean =depthWriteEnabled false ;GPUCompareFunction = "always";depthCompare required GPUStencilStateFaceDescriptor ;stencilFront required GPUStencilStateFaceDescriptor ;stencilBack u32 = 0xFFFFFFFF;stencilReadMask u32 = 0xFFFFFFFF; }; // Vertex InputstencilWriteMask enum {GPUIndexFormat ,"uint16" }; // Vertex formats // The name of the format specifies the data type of the component, the number of // values, and whether the data is normalized. // uchar = unsigned 8-bit value // char = signed 8-bit value // ushort = unsigned 16-bit value // short = signed 16-bit value // half = half-precision 16-bit floating point value // float = 32-bit floating point value // uint = unsigned 32-bit integer value // int = signed 32-bit integer value // If no number of values is given in the name, a single value is provided. // If the format has the "-bgra" suffix, it means the values are arranged as // blue, green, red and alpha values."uint32" enum {GPUVertexFormat ,"uchar2" ,"uchar4" ,"char2" ,"char4" ,"uchar2norm" ,"uchar4norm" ,"char2norm" ,"char4norm" ,"ushort2" ,"ushort4" ,"short2" ,"short4" ,"ushort2norm" ,"ushort4norm" ,"short2norm" ,"short4norm" ,"half2" ,"half4" ,"float" ,"float2" ,"float3" ,"float4" ,"uint" ,"uint2" ,"uint3" ,"uint4" ,"int" ,"int2" ,"int3" };"int4" enum {GPUInputStepMode ,"vertex" };"instance" dictionary {GPUVertexAttributeDescriptor u64 = 0;offset required GPUVertexFormat ;format required u32 ; };shaderLocation dictionary {GPUVertexBufferDescriptor required u64 ;stride GPUInputStepMode = "vertex";stepMode required sequence <GPUVertexAttributeDescriptor >; };attributeSet dictionary {GPUVertexInputDescriptor GPUIndexFormat = "uint32";indexFormat required sequence <GPUVertexBufferDescriptor ?>; };vertexBuffers
9. Pipeline Descriptors
dictionary {GPUPipelineStageDescriptor required GPUShaderModule ;module required DOMString ; // TODO other stuff like specialization constants? };entryPoint dictionary :GPUPipelineDescriptorBase GPUObjectDescriptorBase {required GPUPipelineLayout ; };layout
10. Compute Pipeline
dictionary :GPUComputePipelineDescriptor GPUPipelineDescriptorBase {required GPUPipelineStageDescriptor ; };computeStage interface :GPUComputePipeline GPUObjectBase { };
11. Render Pipeline
enum {GPUPrimitiveTopology ,"point-list" ,"line-list" ,"line-strip" ,"triangle-list" };"triangle-strip" dictionary :GPURenderPipelineDescriptor GPUPipelineDescriptorBase {required GPUPipelineStageDescriptor ;vertexStage GPUPipelineStageDescriptor ?=fragmentStage null ;required GPUPrimitiveTopology ;primitiveTopology required GPURasterizationStateDescriptor ;rasterizationState required sequence <GPUColorStateDescriptor >;colorStates GPUDepthStencilStateDescriptor ?=depthStencilState null ;required GPUVertexInputDescriptor ; // Number of MSAA samplesvertexInput u32 = 1;sampleCount u32 = 0xFFFFFFFF;sampleMask boolean =alphaToCoverageEnabled false ; // TODO other properties };interface :GPURenderPipeline GPUObjectBase { };
12. Command Recording
interface :GPUProgrammablePassEncoder GPUObjectBase {void (); // Allowed in both compute and render passesendPass void (setBindGroup u32 ,index GPUBindGroup ,bindGroup optional sequence <u64 >); // Debugging assistancedynamicOffsets void (pushDebugGroup DOMString );groupLabel void ();popDebugGroup void (insertDebugMarker DOMString ); };markerLabel interface :GPURenderPassEncoder GPUProgrammablePassEncoder {void (setPipeline GPURenderPipeline );pipeline void (setBlendColor GPUColor );color void (setStencilReference u32 ); // The default viewport is (0.0, 0.0, w, h, 0.0, 1.0), where w and h are the dimensions of back bufferreference void (setViewport float ,x float ,y float ,width float ,height float ,minDepth float ); // The default scissor rectangle is (0, 0, w, h), where w and h are the dimensions of back buffer. // Width and height must be greater than 0. Otherwise, an error will be generated.maxDepth void (setScissorRect u32 ,x u32 ,y u32 ,width u32 );height void (setIndexBuffer GPUBuffer ,buffer u64 );offset void (setVertexBuffers u32 ,startSlot sequence <GPUBuffer >,buffers sequence <u64 >);offsets void (draw u32 ,vertexCount u32 ,instanceCount u32 ,firstVertex u32 );firstInstance void (drawIndexed u32 ,indexCount u32 ,instanceCount u32 ,firstIndex i32 ,baseVertex u32 ); // TODO add missing commands };firstInstance interface :GPUComputePassEncoder GPUProgrammablePassEncoder {void (setPipeline GPUComputePipeline );pipeline void (dispatch u32 ,x optional u32 = 1,y optional u32 = 1); // TODO add missing commands };z enum {GPULoadOp ,"clear" };"load" enum {GPUStoreOp };"store" dictionary {GPURenderPassColorAttachmentDescriptor required GPUTextureView ;attachment GPUTextureView ?=resolveTarget null ;required GPULoadOp ;loadOp required GPUStoreOp ;storeOp GPUColor ; // defaults to {r: 0.0, g: 0.0, b: 0.0, a: 1.0} };clearColor dictionary {GPURenderPassDepthStencilAttachmentDescriptor required GPUTextureView ;attachment required GPULoadOp ;depthLoadOp required GPUStoreOp ;depthStoreOp required float ;clearDepth required GPULoadOp ;stencilLoadOp required GPUStoreOp ;stencilStoreOp u32 = 0; };clearStencil dictionary :GPURenderPassDescriptor GPUObjectDescriptorBase {required sequence <GPURenderPassColorAttachmentDescriptor >;colorAttachments GPURenderPassDepthStencilAttachmentDescriptor ?=depthStencilAttachment null ; };dictionary :GPUComputePassDescriptor GPUObjectDescriptorBase { };dictionary :GPUCommandBufferDescriptor GPUObjectDescriptorBase { };dictionary {GPUBufferCopyView required GPUBuffer ;buffer u64 = 0;offset required u32 ;rowPitch required u32 ; };imageHeight dictionary {GPUTextureCopyView required GPUTexture ;texture u32 = 0;mipLevel u32 = 0;arrayLayer GPUOrigin3D ; // defaults to {x: 0, y: 0, z: 0} };origin dictionary {ImageBitmapCopyView ImageBitmap ;imageBitmap GPUOrigin2D ; };origin interface :GPUCommandBuffer GPUObjectBase { };interface :GPUCommandEncoder GPUObjectBase {GPURenderPassEncoder (beginRenderPass GPURenderPassDescriptor );descriptor GPUComputePassEncoder (beginComputePass GPUComputePassEncoder ?); // Commands allowed outside of "passes"descriptor void (copyBufferToBuffer GPUBuffer ,src u64 ,srcOffset GPUBuffer ,dst u64 ,dstOffset u64 );size void (copyBufferToTexture GPUBufferCopyView ,source GPUTextureCopyView ,destination GPUExtent3D );copySize void (copyTextureToBuffer GPUTextureCopyView ,source GPUBufferCopyView ,destination GPUExtent3D );copySize void (copyTextureToTexture GPUTextureCopyView ,source GPUTextureCopyView ,destination GPUExtent3D );copySize void (copyImageBitmapToTexture ImageBitmapCopyView ,source GPUTextureCopyView , // For now, copySize.z must be 1.destination GPUExtent3D ); // Debugging assistancecopySize void (pushDebugGroup DOMString );groupLabel void ();popDebugGroup void (insertDebugMarker DOMString );markerLabel GPUCommandBuffer (finish optional GPUCommandBufferDescriptor ); };descriptor dictionary :GPUCommandEncoderDescriptor GPUObjectDescriptorBase { //TODO: reusability flag? };
13. Fences
dictionary :GPUFenceDescriptor GPUObjectDescriptorBase {u64 = 0; };initialValue interface :GPUFence GPUObjectBase {u64 ();getCompletedValue Promise <void >(onCompletion u64 ); };completionValue
14. Queues
interface :GPUQueue GPUObjectBase {void (submit sequence <GPUCommandBuffer >);buffers GPUFence (createFence optional GPUFenceDescriptor );descriptor void (signal GPUFence ,fence u64 ); };signalValue
15. Canvas Rendering and Swap Chain
interface { // Calling configureSwapChain a second time invalidates the previous one, // and all of the textures it’s produced.GPUCanvasContext GPUSwapChain (configureSwapChain GPUSwapChainDescriptor );descriptor Promise <GPUTextureFormat >(getSwapChainPreferredFormat GPUDevice ); };device dictionary :GPUSwapChainDescriptor GPUObjectDescriptorBase {required GPUDevice ;device required GPUTextureFormat ;format GPUTextureUsageFlags = 0x10; // GPUTextureUsage.OUTPUT_ATTACHMENT };usage interface :GPUSwapChain GPUObjectBase {GPUTexture (); };getCurrentTexture
16. Device
dictionary {GPUExtensions boolean =anisotropicFiltering false ; };dictionary {GPULimits u32 = 4; }; // Device [maxBindGroups Exposed =(Window ,Worker )]interface :GPUDevice EventTarget {readonly attribute GPUExtensions ;extensions readonly attribute GPULimits ;limits readonly attribute GPUAdapter ;adapter GPUBuffer (createBuffer GPUBufferDescriptor );descriptor GPUMappedBuffer (createBufferMapped GPUBufferDescriptor );descriptor Promise <GPUMappedBuffer >(createBufferMappedAsync GPUBufferDescriptor );descriptor GPUTexture (createTexture GPUTextureDescriptor );descriptor GPUSampler (createSampler optional GPUSamplerDescriptor );descriptor GPUBindGroupLayout (createBindGroupLayout GPUBindGroupLayoutDescriptor );descriptor GPUPipelineLayout (createPipelineLayout GPUPipelineLayoutDescriptor );descriptor GPUBindGroup (createBindGroup GPUBindGroupDescriptor );descriptor GPUShaderModule (createShaderModule GPUShaderModuleDescriptor );descriptor GPUComputePipeline (createComputePipeline GPUComputePipelineDescriptor );descriptor GPURenderPipeline (createRenderPipeline GPURenderPipelineDescriptor );descriptor GPUCommandEncoder (createCommandEncoder optional GPUCommandEncoderDescriptor );descriptor GPUQueue (); };getQueue GPUDevice includes GPUObjectBase ;dictionary :GPUDeviceDescriptor GPUObjectDescriptorBase {GPUExtensions ;extensions GPULimits ; // TODO are other things configurable like queues? };limits interface :GPUAdapter GPUObjectBase {readonly attribute DOMString ;name readonly attribute GPUExtensions ; //readonly attribute GPULimits limits; Don’t expose higher limits for now. // May reject with DOMException // TODO: DOMException("OperationError")?extensions Promise <GPUDevice >(requestDevice optional GPUDeviceDescriptor ); };descriptor enum {GPUPowerPreference ,"low-power" };"high-performance" dictionary {GPURequestAdapterOptions GPUPowerPreference ?; }; [powerPreference Exposed =Window ]interface { // May reject with DOMException // TODO: DOMException("OperationError")?GPU Promise <GPUAdapter >(requestAdapter optional GPURequestAdapterOptions ); }; [options Exposed =Window ]partial interface Navigator { [SameObject ]readonly attribute GPU ; }; [gpu Exposed =DedicatedWorker ]partial interface WorkerNavigator { [SameObject ]readonly attribute GPU ; };gpu
17. Fatal Errors
interface {GPUDeviceLostInfo readonly attribute DOMString ; };message partial interface GPUDevice {readonly attribute Promise <GPUDeviceLostInfo >; };lost
18. Error Scopes
enum {GPUErrorFilter ,"none" ,"out-of-memory" }; ["validation" () ]Constructor interface {}; [GPUOutOfMemoryError (Constructor DOMString ) ]message interface {GPUValidationError readonly attribute DOMString ; };message typedef (GPUOutOfMemoryError or GPUValidationError );GPUError partial interface GPUDevice {void (pushErrorScope GPUErrorFilter );filter Promise <GPUError ?>(); };popErrorScope
19. Telemetry
[
Constructor (DOMString type , GPUUncapturedErrorEventInit gpuUncapturedErrorEventInitDict ),
Exposed =Window
]
interface GPUUncapturedErrorEvent : Event {
readonly attribute GPUError error ;
};
dictionary GPUUncapturedErrorEventInit : EventInit {
required GPUError error ;
};
partial interface GPUDevice {
[Exposed =Window ]
attribute EventHandler onuncapturederror ;
};