GPUDevice: createBindGroupLayout() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("WebGPU API")}}{{SecureContext_Header}}{{AvailableInWorkers}}
The **createBindGroupLayout()** method of the {{domxref("GPUDevice")}} interface creates a {{domxref("GPUBindGroupLayout")}} that defines the structure and purpose of related GPU resources such as buffers that will be used in a pipeline, and is used as a template when creating {{domxref("GPUBindGroup")}}s.
Syntax
createBindGroupLayout(descriptor)Parameters
descriptor- : An object containing the following properties:
entries- : An array of entry objects, each one of which describes a single shader resource binding to be included in the {{domxref("GPUBindGroupLayout")}}. Each entry will correspond to an entry defined in a {{domxref("GPUBindGroup")}} (created via a {{domxref("GPUDevice.createBindGroup()")}} call) that uses this {{domxref("GPUBindGroupLayout")}} object as a template.
label{{optional_inline}}- : A string providing a label that can be used to identify the object, for example in {{domxref("GPUError")}} messages or console warnings.
Entry objects
An entry object includes the following properties:
binding- : A number representing a unique identifier for this particular entry, which matches the
bindingvalue of a corresponding {{domxref("GPUBindGroup")}} entry. In addition, it matches thenindex value of the corresponding [@binding(n)](https://gpuweb.github.io/gpuweb/wgsl/#attribute-binding) attribute in the shader ({{domxref("GPUShaderModule")}}) used in the related pipeline. visibility- : One or more {{glossary("Bitwise_flags", "bitwise flags")}} defining the shader stages that a {{domxref("GPUBindGroup")}} entry corresponding to this entry will be visible to. Possible values are:
GPUShaderStage.COMPUTE: The bind group entry will be accessible to compute shaders.GPUShaderStage.FRAGMENT: The bind group entry will be accessible to fragment shaders.GPUShaderStage.VERTEX: The bind group entry will be accessible to vertex shaders.
Note that multiple stages can be specified by separating values with bitwise OR, for example: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX.
- "Resource layout object"
- : An object that defines the required binding resource type and structure of the {{domxref("GPUBindGroup")}} entry corresponding to this entry. This property can be one of
buffer,externalTexture,sampler,storageTexture, ortexture, the object structures of which are described in the next section.
Resource layout objects
The resource layout object can be one of the following (see also {{domxref("GPUDevice.createBindGroup()")}} for details of how the required resources for each entry are structured):
buffer: Indicates that the corresponding {{domxref("GPUBindGroup")}} entry will be aGPUBufferBindingobject, which contains a {{domxref("GPUBuffer")}} plusoffsetandsizevalues. Abufferresource layout object can contain the following properties:hasDynamicOffset{{optional_inline}}- : A boolean. If set to
true, it indicates that this binding requires a dynamic offset, for example as set during a {{domxref("GPURenderPassEncoder.setBindGroup()")}} call. If omitted,hasDynamicOffsetdefaults tofalse.
minBindingSize{{optional_inline}}- : A number indicating the minimum allowed size, in bytes, of bound buffers. If omitted,
minBindingSizedefaults to 0. If the value is 0, minimum buffer size is ignored during pipeline creation and is instead validated by issued draw/dispatch commands.
type{{optional_inline}}- : An enumerated value specifying the required type for {{domxref("GPUBuffer")}}s bound to this binding (see {{domxref("GPUDevice.createBuffer()")}} for more information on buffer types). Possible values are:
"read-only-storage": A read-only buffer created with ausageofGPUBufferUsage.STORAGE."storage": A writable buffer created with ausageofGPUBufferUsage.STORAGE."uniform": A buffer created with ausageofGPUBufferUsage.UNIFORM.
If omitted, type defaults to "uniform".
externalTexture: Indicates that the corresponding {{domxref("GPUBindGroup")}} entry will be a {{domxref("GPUExternalTexture")}} object. AnexternalTextureresource layout object is empty —{}.
sampler: Indicates that the corresponding {{domxref("GPUBindGroup")}} entry will be a {{domxref("GPUSampler")}} object. Asamplerresource layout object can contain the following properties:type{{optional_inline}}- : An enumerated value specifying the required type for {{domxref("GPUSampler")}}s bound to this binding (see {{domxref("GPUDevice.createSampler()")}} for more information on sampler types). Possible values are:
"comparison": A comparison sampler."filtering": A filtering sampler."non-filtering": A non-filtering sampler.
If omitted, type defaults to "filtering".
storageTexture: Indicates that the corresponding {{domxref("GPUBindGroup")}} entry will be a {{domxref("GPUTextureView")}} object. AstorageTextureresource layout object can contain the following properties:access{{optional_inline}}- : An enumerated value specifying whether texture views bound to this binding will be bound for read and/or write access. Possible values are:
"read-only": Enables WGSL code to read storage textures."read-write": Enables WGSL code to read and write to storage textures."write-only": The default value; enables WGSL code to write to storage textures.
The "read-only" and "read-write" values can only be used if the ["readonly_and_readwrite_storage_textures"](/en-US/docs/Web/API/WGSLLanguageFeatures#readonly_and_readwrite_storage_textures) WGSL language extension is present in {{domxref("WGSLLanguageFeatures")}}. If this is not the case, a {{domxref("GPUValidationError")}} is generated.
format- : An enumerated value specifying the required format of texture views bound to this binding. See the specification's Texture Formats section for all the available
formatvalues. Also see Tier 1 and Tier 2 texture formats.
توجه: Use of the bgra8unorm format for read-only storage textures is deprecated. The specification explicitly disallows this, as this format is intended for write-only access and is not portable. Any browser support for this combination is considered a bug.
viewDimension{{optional_inline}}- : An enumerated value specifying the required dimension for texture views bound to this binding. Possible values are:
"1d": The texture is viewed as a one-dimensional image."2d": The texture is viewed as a single two-dimensional image."2d-array": The texture is viewed as an array of two-dimensional images."cube": The texture is viewed as a cubemap. The view has 6 array layers, corresponding to the[+X, -X, +Y, -Y, +Z, -Z]faces of the cube. Sampling is done seamlessly across the faces of the cubemap."cube-array": The texture is viewed as a packed array ofncubemaps, each with 6 array layers corresponding to the[+X, -X, +Y, -Y, +Z, -Z]faces of the cube. Sampling is done seamlessly across the faces of the cubemaps."3d": The texture is viewed as a three-dimensional image.
If omitted, viewDimension defaults to "2d".
texture: Indicates that the corresponding {{domxref("GPUBindGroup")}} entry will be a {{domxref("GPUTextureView")}} object. Atextureresource layout object can contain the following properties:multisampled{{optional_inline}}- : A boolean. A value of
trueindicates that texture views bound to this binding must be multi-sampled. If omitted,multisampleddefaults tofalse.
sampleType{{optional_inline}}- : An enumerated value specifying the sample type required for texture views bound to this binding (see {{domxref("GPUDevice.createTexture()")}} for more information on texture view types). Possible values are:
"depth""float""sint""uint""unfilterable-float"
If omitted, sampleType defaults to "float".
viewDimension{{optional_inline}}- : An enumerated value specifying the required dimension for texture views bound to this binding. Possible and default values are the same as for
storageTextureresource layout objects — see above.
Return value
A {{domxref("GPUBindGroupLayout")}} object instance.
Validation
The following criteria must be met when calling **createBindGroupLayout()**, otherwise a {{domxref("GPUValidationError")}} is generated and an invalid {{domxref("GPUBindGroupLayout")}} object is returned:
- Each entry's
bindingvalue is unique. - Each entry's
bindingvalue is less than the {{domxref("GPUDevice")}}'smaxBindingsPerBindGroup{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - The number of entries does not exceed the binding slot limits.
- Only 1 resource layout object is defined per entry.
- If an entry's
visibilityincludesGPUShaderStage.VERTEX: - If its resource layout object is a
buffer, itstypeis not"storage". - Its resource layout object is not a
storageTexture. - If an entry's resource layout object is a
texture, and itsmultisampledvalue istrue: - Its
viewDimensionis"2d". - Its
sampleTypeis not"float". - If an entry's resource layout object is a
storageTexture: - Its
viewDimensionis not"cube"or"cube-array". - Its
formatis a format that supports storage usage.
Examples
توجه: The WebGPU samples feature many more examples.
Basic example
Our basic compute demo shows an example of creating a bind group layout and then using that as a template when creating a bind group.
// …
const bindGroupLayout = device.createBindGroupLayout({
entries: [
{
binding: 0,
visibility: GPUShaderStage.COMPUTE,
buffer: {
type: "storage",
},
},
],
});
const bindGroup = device.createBindGroup({
layout: bindGroupLayout,
entries: [
{
binding: 0,
resource: {
buffer: output,
},
},
],
});
// …Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- The WebGPU API