WebGPU Correspondence Reference

Living Document,

This version:
https://gpuweb.github.io/gpuweb/correspondence/
Issue Tracking:
Inline In Spec
Editors:
(Google)
(Google)
Participate:
File an issue (open issues)

Copyright © 2023 the Contributors to the WebGPU Correspondence Reference Specification, published by the GPU for the Web Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

This non-normative document provides an unofficial reference for how WebGPU names correspond to names in other APIs. It also provides references for how to implement some parts of WebGPU on various backend APIs. It is not guaranteed to be correct or up-to-date.

Correspondence or implementation strategy information not covered by this document can generally be found in GitHub issue discussions.

1. Terminology

1.1. Resources

WebGPU OpenGL/Vulkan Metal D3D12
uniform buffer uniform buffer constant memory buffer CBV (constant buffer view)
storage buffer storage buffer device memory buffer UAV (unordered access view) of a buffer
sampled texture sampled texture/image texture binding (texture views are also represented as textures) SRV (shader resource view)
storage texture storage texture/storage image, or storage texel buffer device texture with read/write access UAV (unordered access view) of a texture
(array or cube) layer index cube-face and layer index cube-face and array element sub-resource index

2. Limits

This section provides references for computing WebGPU’s limit values in each of the three backend APIs. These references inform the base values of these limits, as well as how implementations compute adapter limits. User agents are not required to use these formulas and may expose whatever they want (e.g. always choosing the base value of a limit, or bucketing devices as a fingerprinting protection).

Limit Issue Vulkan Metal D3D12
Required Limits Feature Set Tables Constants, Hardware Tiers, Root Signature Limits

need a max buffer size limit

#1371 maxMemoryAllocationSize MTLDevice.maxBufferLength

No documented limit?

maxTextureDimension1D #1327 maxImageDimension1D Maximum 1D texture width 16384 = D3D12_REQ_TEXTURE1D_U_DIMENSION
maxTextureDimension2D #1327 min(maxImageDimension2D, maxImageDimensionCube) min(Maximum 2D texture width and height, Maximum cube map texture width and height) 16384 = min(D3D12_REQ_TEXTURE2D_U_OR_V_DIMENSION, D3D12_REQ_TEXTURECUBE_DIMENSION)
maxTextureDimension3D #1327 maxImageDimension3D Maximum 3D texture width, height, and depth 2048 = D3D12_REQ_TEXTURE3D_U_V_OR_W_DIMENSION
maxTextureArrayLayers #1327 maxImageArrayLayers Maximum number of layers per 1D texture array, 2D texture array, or 3D texture 2048 = D3D12_REQ_TEXTURE2D_ARRAY_AXIS_DIMENSION
maxBindGroups #47 maxBoundDescriptorSets

It’s complicated.

Strategy-dependent. Allocate the D3D12_MAX_ROOT_COST, minus reserved slots, across these three limits.
maxDynamicUniformBuffersPerPipelineLayout #406 maxDescriptorSetUniformBuffersDynamic When not using argument buffers: maxUniformBuffersPerShaderStage

When using argument buffers: ?

maxDynamicStorageBuffersPerPipelineLayout #406 maxDescriptorSetStorageBuffersDynamic When not using argument buffers, maxStorageBuffersPerShaderStage

When using argument buffers: ?

maxSamplersPerShaderStage #409 maxPerStageDescriptorSamplers Maximum number of entries in the sampler state argument table, per graphics or kernel function Maximum number of Samplers in all descriptor tables per shader stage
maxSampledTexturesPerShaderStage #409 maxPerStageDescriptorSampledImages Strategy-dependent. Allocate Maximum number of entries in the texture argument table, per graphics or kernel function across these two limits. Maximum number of Shader Resource Views in all descriptor tables per shader stage
maxStorageTexturesPerShaderStage #409 maxPerStageDescriptorStorageImages Strategy-dependent. Allocate Maximum number of Unordered Access Views in all descriptor tables across all stages across these two limits.
maxStorageBuffersPerShaderStage #409 maxPerStageDescriptorStorageBuffers Strategy-dependent. Allocate Maximum number of entries in the buffer argument table, per graphics or kernel function across these three limits.
maxUniformBuffersPerShaderStage #409 maxPerStageDescriptorUniformBuffers Maximum number of Constant Buffer Views in all descriptor tables per shader stage
maxVertexBuffers #693 maxVertexInputBindings 16
maxUniformBufferBindingSize #803 maxUniformBufferRange No documented limit. Use maxBufferSize. 65536 = D3D12_REQ_CONSTANT_BUFFER_ELEMENT_COUNT * sizeof(float4)
maxStorageBufferBindingSize #1163 maxStorageBufferRange No documented limit. Use maxBufferSize.

No documented limit. Use 4 GiB, or 2 GiB if that’s problematic?

minUniformBufferOffsetAlignment #1863 minUniformBufferOffsetAlignment Minimum constant buffer offset alignment 256 = D3D12_CONSTANT_BUFFER_DATA_PLACEMENT_ALIGNMENT
minStorageBufferOffsetAlignment #1863 minStorageBufferOffsetAlignment No documented limit. Use 32, which is the lowest allowed value. 32 = max(32, D3D12_RAW_UAV_SRV_BYTE_ALIGNMENT (16))
maxVertexAttributes #693 maxVertexInputAttributes No limit. Use maxVertexBuffers * Maximum number of vertex attributes, per vertex descriptor 32 = D3D12_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT
maxVertexBufferArrayStride #693 maxVertexInputBindingStride No documented limit? 2048 B = D3D12_SO_BUFFER_MAX_STRIDE_IN_BYTES
maxInterStageShaderComponents #1962 min(maxVertexOutputComponents, maxFragmentInputComponents) Maximum number of input components to a fragment function, declared with the stage_in qualifier, subtract 4 for non-Apple GPUs 120 = maxInterStageShaderVariables * 4
maxInterStageShaderVariables #1962 min(maxVertexOutputComponents // 4, maxFragmentInputComponents // 4) Maximum number of inputs (scalars or vectors) to a fragment function, declared with the stage_in qualifier, subtract 2 for non-Apple GPUs 30 = min(D3D12_VS_OUTPUT_REGISTER_COUNT - 1, D3D12_PS_INPUT_REGISTER_COUNT - 2)
maxColorAttachments #2820 min(maxColorAttachments, maxFragmentOutputAttachments) Maximum number of color render targets per render pass descriptor 8 = D3D12_SIMULTANEOUS_RENDER_TARGET_COUNT
maxComputeWorkgroupStorageSize #1863 maxComputeSharedMemorySize Maximum total threadgroup memory allocation 32 KiB
maxComputeInvocationsPerWorkgroup #1863 min(maxComputeWorkGroupInvocations, product(maxComputeWorkGroupSize[0..2])) Maximum threads per threadgroup (but actually maxTotalThreadsPerThreadgroup for a given pipeline) 1024 = D3D12_CS_THREAD_GROUP_MAX_THREADS_PER_GROUP
maxComputeWorkgroupSizeX #1898 min(maxComputeWorkGroupSize[0], maxComputeWorkGroupInvocations) 1024 = D3D12_CS_THREAD_GROUP_MAX_X
maxComputeWorkgroupSizeY #1898 min(maxComputeWorkGroupSize[1], maxComputeWorkGroupInvocations) 1024 = D3D12_CS_THREAD_GROUP_MAX_Y
maxComputeWorkgroupSizeZ #1898 min(maxComputeWorkGroupSize[2], maxComputeWorkGroupInvocations) 64 = D3D12_CS_THREAD_GROUP_MAX_Z
maxComputeWorkgroupsPerDimension #1863 min(maxComputeWorkGroupCount[0..2])

No documented limit?

65535 = D3D12_CS_DISPATCH_MAX_THREAD_GROUPS_PER_DIMENSION

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119

Issues Index

need a max buffer size limit ↵
No documented limit? ↵
It’s complicated. ↵
When using argument buffers: ? ↵
When using argument buffers: ? ↵
No documented limit. Use 4 GiB, or 2 GiB if that’s problematic? ↵
No documented limit? ↵