GPUCommandEncoder: метод beginRenderPass()

Метод beginRenderPass() интерфейса GPUCommandEncoder начинает кодирование прохода отрисовки, возвращая GPURenderPassEncoder, который можно использовать для управления отрисовкой.

descriptor

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

colorAttachments

Массив объектов (см. Структура объекта прикрепления цвета), определяющих цветовые прикрепления, которые будут выводиться при выполнении этого прохода отрисовки.

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

Объект (см. Структура объекта прикрепления глубины/маски), определяющий прикрепление глубины/маски, которое будет выводиться и проверяться при выполнении этого прохода отрисовки.

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

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

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

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

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

GPUQuerySet для хранения результатов запроса экранирования для этого прохода.

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

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

• location: Перечисление, указывающее, когда выполняется отметка времени. Доступные значения:
  • "beginning": Отметка времени выполняется вместе с другими закодированными командами в вычислительном проходе после отправки соответствующего GPUCommandBuffer.
  • "end": Отметка времени выполняется в рамках отдельного списка прикреплений отметки времени после завершения прохода.
• queryIndex: Число, указывающее позицию индекса в querySet, в которую будет записана отметка времени.
• querySet: GPUQuerySet для записи отметки времени.

Примечание: Для использования запросов отметки времени требуется включение timestamp-query функции.

Объекты прикрепления цвета могут иметь следующие свойства:

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

Значение цвета для очистки текстуры view перед выполнением прохода отрисовки. Это значение игнорируется, если loadOp не установлено в "clear". clearValue принимает массив или объект, представляющий четыре цветовых компонента r, g, b, и a в виде десятичных чисел.

Вот пример массива:

clearValue: [0.0, 0.5, 1.0, 1.0];

Эквивалентный объект будет выглядеть так:

clearValue: {
  r: 0.0,
  g: 0.5,
  b: 1.0,
  a: 1.0
}

Если clearValue опущено, оно по умолчанию равно {r: 0, g: 0, b: 0, a: 0}.

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

Число, представляющее индекс 3D-слоя глубины, который будет выводиться для этого прикрепления цвета в случае 3D-GPUTextureView view. При указании этого значения WebGPU может напрямую отрисовывать срезы 3D-текстур в рамках проходов отрисовки.

loadOp

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

• "clear": Загружает clearValue для этого прикрепления в проход отрисовки.
• "load": Загружает существующее значение для этого прикрепления в проход отрисовки.

Примечание: Рекомендуется всегда использовать "clear" в случаях, когда начальное значение не имеет значения, так как это обеспечит лучшую производительность на некоторых устройствах, таких как мобильные.

storeOp

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

• "discard": Отбрасывает результирующее значение прохода отрисовки для этого прикрепления.
• "store": Сохраняет результирующее значение прохода отрисовки для этого прикрепления.

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

Объект GPUTextureView, представляющий подресурс текстуры, который получит разрешенное выходное значение для этого цветового прикрепления, если view является многовыборочным.

view

Объект GPUTextureView, представляющий подресурс текстуры, который будет выводиться для этого цветового прикрепления.

Примечание: Каждое цветовое или глубинно-масковое прикрепление должно быть уникальным подресурсом текстуры, и подресурсы текстур, используемые как прикрепления, не могут использоваться внутри прохода отрисовки.

Объект depthStencilAttachment может иметь следующие свойства:

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

Число, указывающее значение для очистки компоненты глубины view перед выполнением прохода рендеринга. Это игнорируется, если depthLoadOp не установлено в "clear".

Значение должно быть между 0.0 и 1.0 включительно.

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

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

• "clear": Загружает значение clearValue для данного присоединения в проход рендеринга.
• "load": Загружает существующее значение для данного присоединения в проход рендеринга.

Примечание: Рекомендуется всегда использовать "clear" в случаях, когда начальное значение не имеет значения, так как это обеспечит лучшую производительность на некоторых устройствах, таких как мобильные.

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

Булево значение. Установка значения в true делает компонент глубины view только для чтения. Если depthReadOnly опущено, по умолчанию используется false.

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

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

• "discard": Отбрасывает результирующее значение прохода рендеринга для данного присоединения.
• "store": Сохраняет результирующее значение прохода рендеринга для данного присоединения.

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

Число, указывающее значение для очистки компоненты трафарета view перед выполнением прохода рендеринга. Это игнорируется, если stencilLoadOp не установлено в "clear".

Если stencilClearValue опущено, по умолчанию используется 0.

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

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

• "clear": Загружает значение clearValue для данного присоединения в проход рендеринга.
• "load": Загружает существующее значение для данного присоединения в проход рендеринга.

Примечание: Рекомендуется всегда использовать "clear" в случаях, когда начальное значение не имеет значения, так как это обеспечит лучшую производительность на некоторых устройствах, таких как мобильные.

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

Булево значение. Установка значения в true делает компонент трафарета view только для чтения. Если stencilReadOnly опущено, по умолчанию используется false.

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

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

• "discard": Отбрасывает результирующее значение прохода рендеринга для данного присоединения.
• "store": Сохраняет результирующее значение прохода рендеринга для данного присоединения.

view

Объект GPUTextureView, представляющий подресурс текстуры, который будет выводиться и читаться для данного присоединения глубины/трафарета.

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

При вызове beginRenderPass() должны быть соблюдены следующие критерии, иначе будет сгенерирована ошибка GPUValidationError, и будет возвращен недействительный объект GPURenderPassEncoder.

Общие:

• colorAttachments.length меньше или равно пределу maxColorAttachments устройства GPUDevice (limit).
• Если colorAttachments содержит только значения null, то предоставляется depthStencilAttachment.
• Все view в colorAttachments и depthStencilAttachment имеют одинаковые значения GPUTexture.sampleCount и размеры рендеринга (GPUTexture.height, GPUTexture.width и GPUTexture.depthOrArrayLayers).
• Если occlusionQuerySet установлено, связанный объект GPUQuerySet имеет значение "occlusion" для type.

Для объектов присоединения цвета

• Объект view отображается, и формат view (указанный в описателе исходного вызова GPUTexture.createView()) — формат, подходящий для рендеринга цвета.
• Если resolveTarget указано:
  • Значение sampleCount исходной текстуры GPUTexture объекта view больше 1.
  • Значение sampleCount исходной текстуры GPUTexture объекта resolveTarget равно 1.
  • resolveTarget отображается.
  • Размеры подресурсов, представленных объектами view и resolveTarget, совпадают.
  • Форматы view и resolveTarget совпадают.
• Количество байтов на пиксель для присоединений цвета меньше или равно пределу maxColorAttachmentBytesPerSample устройства GPUDevice (limit).

Для объектов присоединения глубины/трафарета:

• Объект view отображается, и его формат — формат глубины/трафарета.
• Если depthLoadOp установлено в "clear", предоставлен допустимый объект depthClearValue.
• Если формат view — комбинированный формат глубины/трафарета, то depthReadOnly соответствует stencilReadOnly.
• Если формат view содержит компонент глубины и depthReadOnly равно false, то предоставлены depthLoadOp и depthStoreOp.
• Если формат view содержит компонент глубины и depthReadOnly равно true, то depthLoadOp и depthStoreOp не предоставлены.
• Если формат view содержит компонент трафарета и stencilReadOnly равно false, то предоставлены stencilLoadOp и stencilStoreOp.
• Если формат view содержит компонент трафарета и stencilReadOnly равно true, то stencilLoadOp и stencilStoreOp не предоставлены.

Для запросов отметки времени:

• Функция timestamp-query (feature) включена в устройстве GPUDevice.
• Ни у двух объектов timestampWrites нет одинаковых значений location.
• Для каждого запроса отметки времени тип querySet GPUQuerySet.type равен "timestamp", и значение queryIndex меньше, чем GPUQuerySet.count.
• Ни у двух объектов timestampWrites нет одинаковой пары значений queryIndex и querySet.

В нашей демо-версии простейшего рендеринга ряд команд записывается через объект GPUCommandEncoder. Эти команды происходят от объекта GPURenderPassEncoder, созданного с помощью beginRenderPass():

// ...

// Create GPUCommandEncoder
const commandEncoder = device.createCommandEncoder();

// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render pass

const renderPassDescriptor = {
  colorAttachments: [
    {
      clearValue: clearColor,
      loadOp: "clear",
      storeOp: "store",
      view: context.getCurrentTexture().createView(),
    },
  ],
};

const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// Draw a triangle

passEncoder.setPipeline(renderPipeline);
passEncoder.setVertexBuffer(0, vertexBuffer);
passEncoder.draw(3);

// End the render pass

passEncoder.end();

device.queue.submit([commandEncoder.finish()]);

// ...

• API WebGPU