GPUDevice: метод createBindGroupLayout()

Метод createBindGroupLayout() интерфейса GPUDevice создаёт GPUBindGroupLayout, определяющий структуру и назначение связанных ресурсов графического процессора, таких как буферы, которые будут использоваться в конвейере. Он используется в качестве шаблона при создании GPUBindGroup.

descriptor

Объект, содержащий следующие свойства:

entries

Массив объектов входов, каждый из которых описывает одно связывание ресурса шейдера, подлежащее включению в GPUBindGroupLayout. Каждый вход будет соответствовать входу, определённому в GPUBindGroup (созданном с помощью вызова GPUDevice.createBindGroup()), который использует этот объект GPUBindGroupLayout в качестве шаблона.

label Необязательно

Строка, предоставляющая метку, которую можно использовать для идентификации объекта, например, в сообщениях об GPUError или предупреждениях консоли.

Объект входа включает следующие свойства:

binding

Число, представляющее уникальный идентификатор этого входа, который соответствует значению binding соответствующего входа GPUBindGroup. Кроме того, он соответствует значению индекса n соответствующего атрибута @binding(n) в шейдере (GPUShaderModule), используемом в связанном конвейере.

visibility

Один или несколько битовых флагов, определяющих стадии шейдеров, для которых вход GPUBindGroup, соответствующий этому входу, будет видимым. Возможные значения:

• GPUShaderStage.COMPUTE: Вход группы связывания будет доступен для шейдеров вычислений.
• GPUShaderStage.FRAGMENT: Вход группы связывания будет доступен для фрагментных шейдеров.
• GPUShaderStage.VERTEX: Вход группы связывания будет доступен для вершинных шейдеров.

Обратите внимание, что можно указать несколько стадий, разделив значения символом "|" (например):

visibility: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX;

"Объект макета ресурсов"

Объект, определяющий требуемый тип и структуру ресурса для связывания входа GPUBindGroup, соответствующего этому входу. Это свойство может быть одним из buffer, externalTexture, sampler, storageTexture, или texture, структуры которых описаны в следующей секции.

Объект макета ресурса может быть одним из следующих (см. также GPUDevice.createBindGroup() для подробностей о структуре необходимых ресурсов для каждой записи):

• buffer: Указывает, что соответствующая запись GPUBindGroup будет объектом GPUBufferBinding, который содержит GPUBuffer плюс значения offset и size. Объект макета ресурса buffer может содержать следующие свойства:

  hasDynamicOffset Необязательно

  Булево значение. Если установлено в true, это указывает, что данному связыванию требуется динамический смещение, например, установленное во время вызова GPURenderPassEncoder.setBindGroup(). Если опущено, hasDynamicOffset по умолчанию равно false.

  minBindingSize Необязательно

  Число, указывающее минимально допустимый размер, в байтах, связанных буферов. Если опущено, minBindingSize по умолчанию равно 0. Если значение равно 0, минимальный размер буфера игнорируется при создании конвейера и вместо этого проверяется выпущенными командами отрисовки/диспатча.

  type Необязательно

  Перечисление, определяющее требуемый тип GPUBuffer связываний с этим связыванием (см. GPUDevice.createBuffer() для получения дополнительной информации о типах буферов). Возможные значения:

  • "read-only-storage": Читать-только буфер, созданный с usage GPUBufferUsage.STORAGE.
  • "storage": Записываемый буфер, созданный с usage GPUBufferUsage.STORAGE.
  • "uniform": Буфер, созданный с usage GPUBufferUsage.UNIFORM.

  Если опущено, type по умолчанию равно "uniform".

• externalTexture: Указывает, что соответствующая запись GPUBindGroup будет объектом GPUExternalTexture. Объект макета ресурса externalTexture пуст — {}.

• sampler: Указывает, что соответствующая запись GPUBindGroup будет объектом GPUSampler. Объект макета ресурса sampler может содержать следующие свойства:

  type Необязательно

  Перечисление, определяющее требуемый тип для GPUSampler связываний с этим связыванием (см. GPUDevice.createSampler() для получения дополнительной информации о типах сэмплеров). Возможные значения:

  • "comparison": Сэмплер сравнения.
  • "filtering": Сэмплер фильтрации.
  • "non-filtering": Сэмплер без фильтрации.

  Если опущено, type по умолчанию равно "filtering".

• storageTexture: Указывает, что соответствующая запись GPUBindGroup будет объектом GPUTextureView. Объект макета ресурса storageTexture может содержать следующие свойства:

  access Необязательно

  Перечисление, определяющее, будут ли текстурные представления, связанные с этим связыванием, связаны для чтения и/или записи. Возможные значения:

  • "read-only": Разрешает коду WGSL читать хранилищные текстуры.
  • "read-write": Разрешает коду WGSL читать и писать в хранилищные текстуры.
  • "write-only": Значение по умолчанию; Разрешает коду WGSL писать в хранилищные текстуры.

  Значения "read-only" и "read-write" могут быть использованы только в том случае, если расширение языка WGSL "readonly_and_readwrite_storage_textures" присутствует в WGSLLanguageFeatures. В противном случае генерируется GPUValidationError.

  format

  Перечисление, определяющее требуемый формат текстурных представлений, связанных с этим связыванием. См. раздел «Форматы текстур» спецификации по всем доступным значениям format.

  viewDimension Необязательно

  Перечисление, определяющее требуемую размерность для текстурных представлений, связанных с этим связыванием. Возможные значения:

  • "1d": Текстура рассматривается как одномерное изображение.
  • "2d": Текстура рассматривается как одно двумерное изображение.
  • "2d-array": Текстура рассматривается как массив двумерных изображений.
  • "cube": Текстура рассматривается как кубмап. Представление имеет 6 слоёв массива, соответствующих [+X, -X, +Y, -Y, +Z, -Z] граням куба. Выборка выполняется плавно по граням кубмапа.
  • "cube-array": Текстура рассматривается как упакованный массив n кубмапов, каждый из которых имеет 6 слоёв массива, соответствующих [+X, -X, +Y, -Y, +Z, -Z] граням куба. Выборка выполняется плавно по граням кубмапов.
  • "3d": Текстура рассматривается как трехмерное изображение.

  Если опущено, viewDimension по умолчанию равно "2d".

• texture: Указывает, что соответствующая запись GPUBindGroup будет объектом GPUTextureView. Объект макета ресурса texture может содержать следующие свойства:

  multisampled Необязательно

  Булево значение. Значение true указывает, что текстурные представления, связанные с этим связыванием, должны быть многообразными. Если опущено, multisampled по умолчанию равно false.

  sampleType Необязательно

  Перечисление, определяющее требуемый тип выборки для текстурных представлений, связанных с этим связыванием (см. GPUDevice.createTexture() для получения дополнительной информации о типах текстурных представлений). Возможные значения:

  • "depth"
  • "float"
  • "sint"
  • "uint"
  • "unfilterable-float"

  Если опущено, sampleType по умолчанию равно "float".

  viewDimension Необязательно

  Перечисление, определяющее требуемую размерность для текстурных представлений, связанных с этим связыванием. Возможные и значения по умолчанию такие же, как у объектов макета ресурсов storageTexture — см. выше.

Экземпляр объекта GPUBindGroupLayout.

При вызове createBindGroupLayout() должны быть выполнены следующие критерии, иначе генерируется GPUValidationError, и возвращается недопустимый объект GPUBindGroupLayout:

• Значение каждой записи binding является уникальным.
• Значение каждой записи binding меньше, чем maxBindingsPerBindGroup предел устройства GPUDevice.
• Количество записей не превышает пределов слотов связывания.
• Только 1 объект макета ресурса определен на запись.
• Если запись visibility включает GPUShaderStage.VERTEX:
  • Если её объект макета ресурса является buffer, её type не равно "storage".
  • Её объект макета ресурса не является storageTexture.
• Если объект макета ресурса записи является texture, и её значение multisampled равно true:
  • Её viewDimension равно "2d".
  • Её sampleType не равно "float".
• Если объект макета ресурса записи является storageTexture:
  • Её viewDimension не равно "cube" или "cube-array".
  • Её format — это формат, поддерживающий хранилищное использование.

Наш базовый демонстрационный пример вычислений демонстрирует пример создания макета группы связей, а затем использования его в качестве шаблона при создании группы связей.

// ...

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,
      },
    },
  ],
});

// ...

• API WebGPU