GPUDevice: метод createRenderPipeline()

Метод createRenderPipeline() интерфейса GPUDevice создаёт GPURenderPipeline, который может управлять этапами вершинного и фрагментного шейдеров и использоваться в GPURenderPassEncoder или GPURenderBundleEncoder.

descriptor

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

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

Объект (см. depthStencil структуру объекта) описывающий свойства глубины и трафарета, включая проверку, операции и смещение.

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

Объект (см. fragment структуру объекта) описывающий точку входа фрагментного шейдера в конвейер и его выходные цвета. Если точка входа фрагментного шейдера не определена, конвейер не будет генерировать выходные цвета для прикреплений, но всё равно будет выполнять растрирование и генерировать значения глубины, основанные на выходных вершинных координатах. Проверка глубины и операции с трафаретом по-прежнему могут быть использованы.

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

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

layout

Определяет макет (структура, назначение и тип) всех ресурсов GPU (буферы, текстуры и т. д.), используемых во время выполнения конвейера. Возможные значения:

• Объект GPUPipelineLayout, созданный с помощью GPUDevice.createPipelineLayout(), который позволяет GPU определить, как запустить конвейер наиболее эффективно заранее.
• Строка "auto", которая заставляет конвейер генерировать неявной макет группы привязок на основе любых привязок, определённых в коде шейдера. Если используется "auto", сгенерированные макеты групп привязок могут использоваться только с текущим конвейером.

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

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

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

Объект (см. primitive структуру объекта) описывающий, как конвейер строит и растрирует примитивы из его вершинных входов.

vertex

Объект (см. vertex структуру объекта) описывающий точку входа вершинного шейдера в конвейер и макеты входных буферов.

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

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

Число, представляющее постоянную смещение глубины, добавляемую к каждому фрагменту. Если опущено, depthBias по умолчанию равно 0.

Примечание: Свойства depthBias, depthBiasClamp, и depthBiasSlopeScale должны быть установлены в 0 для топологий линий и точек, т.е. если topology установлено в "line-list", "line-strip", или "point-list". В противном случае будет сгенерирована ошибка GPUValidationError, и возвращаемая GPURenderPipeline будет недействительной.

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

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

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

Число, представляющее смещение глубины, масштабируемое с наклоном фрагмента. Если опущено, depthBiasSlopeScale по умолчанию равно 0.

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

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

• "never": Тесты сравнения никогда не проходят.
• "less": Предоставленное значение проходит тест сравнения, если оно меньше значения выборки.
• "equal": Предоставленное значение проходит тест сравнения, если оно равно значению выборки.
• "less-equal": Предоставленное значение проходит тест сравнения, если оно меньше или равно значению выборки.
• "greater": Предоставленное значение проходит тест сравнения, если оно больше значения выборки.
• "not-equal": Предоставленное значение проходит тест сравнения, если оно не равно значению выборки.
• "greater-equal": Предоставленное значение проходит тест сравнения, если оно больше или равно значению выборки.
• "always": Тесты сравнения всегда проходят.

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

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

Булево значение. Значение true указывает, что GPURenderPipeline может изменять depthStencilAttachment значения глубины после создания. Установка в false означает, что это невозможно.

depthWriteEnabled не требуется, если указанный format не имеет компонента глубины.

format

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

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

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

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

Перечисление, определяющее операцию сравнения, используемую при проверке фрагментов относительно depthStencilAttachment значений маскировки глубины. Возможные значения такие же, как для свойства depthCompare; см. выше. Если опущено, compare по умолчанию равно "always".

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

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

• "decrement-clamp": Уменьшить текущее значение маскировки глубины, ограничив его 0.
• "decrement-wrap": Уменьшить текущее значение маскировки глубины, переходя к максимальному представимому значению аспекта маскировки глубины, если значение станет меньше 0.
• "invert": Побитовое отрицание текущего значения маскировки глубины.
• "increment-clamp": Увеличить текущее значение маскировки глубины, ограничив его максимальным представимым значением аспекта маскировки глубины.
• "increment-wrap": Увеличить текущее значение маскировки глубины, переходя к нулю, если значение превысит максимальное представимое значение аспекта маскировки глубины.
• "keep": Сохранить текущее значение.
• "replace": Установить значение маскировки глубины на текущее значение.
• "zero": Установить значение маскировки глубины в 0.

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

Примечание: Значение маскировки глубины в состоянии рендеринга инициализируется значением 0 в начале прохода рендеринга.

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

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

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

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

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

Объект, определяющий, как выполняются сравнения и операции с маскировкой глубины для направленных вперед примитивов. Его свойства такие же, как для stencilBack.

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

Маска битов, управляющая тем, какие биты depthStencilAttachment значения маскировки глубины считываются при выполнении тестов сравнения маскировки глубины. Если опущено, stencilReadMask по умолчанию равно 0xFFFFFFFF.

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

Маска битов, управляющая тем, какие биты depthStencilAttachment значения маскировки глубины записываются при выполнении операций с маскировкой глубины. Если опущено, stencilWriteMask по умолчанию равно 0xFFFFFFFF.

Объект fragment содержит массив объектов, каждый из которых может содержать следующие свойства:

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

Последовательность типов записей со структурой (id, value), представляющая значения переопределения для констант WGSL, которые могут быть переопределены в конвейере. Они ведут себя как упорядоченные карты. В каждом случае id является ключом для идентификации или выбора записи, а constant — перечисление, представляющее значение WGSL.

В зависимости от константы, которую вы хотите переопределить, id может принимать вид числового идентификатора константы, если он указан, или иначе — идентификатора имени константы.

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

{
  // ...
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  }
}

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

Имя функции в module, которую этот этап будет использовать для выполнения своей работы. Соответствующая функция шейдера должна иметь атрибут @fragment, чтобы быть идентифицированной как эта точка входа. Подробнее см. Описание точки входа.

Вы можете опустить свойство entryPoint, если ваш код шейдера содержит единственную функцию с заданным атрибутом @fragment — браузер будет использовать её в качестве точки входа по умолчанию. Если entryPoint опущено и браузер не может определить точку входа по умолчанию, генерируется GPUValidationError, и полученная GPURenderPipeline будет недействительной.

module

Объект GPUShaderModule, содержащий код WGSL, который будет выполняться этим программируемым этапом.

targets

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

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

Объект, описывающий режим смешивания, применяемый к выводимому цвету. blend имеет два свойства:

alpha

Описывает значение альфа-канала.

color

Описывает значение цвета.

alpha и color оба принимают объект в качестве значения, который может включать следующие свойства:

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

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

• "constant"
• "dst"
• "dst-alpha"
• "one"
• "one-minus-dst"
• "one-minus-src"
• "one-minus-src1"
• "one-minus-src-alpha"
• "one-minus-src1-alpha"
• "one-minus-dst-alpha"
• "one-minus-constant"
• "src"
• "src1"
• "src-alpha"
• "src1-alpha"
• "src-alpha-saturated"
• "zero"

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

Примечание: Для успешного использования операций смешивания dual-source-blending функция должна быть включена. В противном случае генерируется GPUValidationError.

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

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

• "add"
• "max"
• "min"
• "reverse-subtract"
• "subtract"

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

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

Перечисление, определяющее операцию смешивания, выполняемую над значениями из фрагментного шейдера. Возможные значения такие же, как и для dstFactor. Если опущено, srcFactor по умолчанию равно "one".

Примечание: Для подробного объяснения алгоритмов, определённых каждым перечислением dstFactor/srcFactor и operation, см. раздел Состояние смешивания спецификации.

format

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

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

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

• GPUColorWrite.RED
• GPUColorWrite.GREEN
• GPUColorWrite.BLUE
• GPUColorWrite.ALPHA
• GPUColorWrite.ALL

Если опущено, writeMask по умолчанию равно GPUColorWrite.ALL.

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

writeMask: GPUColorWrite.RED | GPUColorWrite.ALPHA;

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

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

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

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

Число, определяющее количество выборок на пиксель. Конвейер будет совместим только с текстурами прикрепления (colorAttachment и depthStencilAttachment), с соответствующим sampleCounts (см. GPUTexture).

Если опущено, count по умолчанию равно 1.

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

Битовая маска, определяющая, какие выборки записываются. Если опущено, mask по умолчанию равно 0xFFFFFFFF.

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

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

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

• "back": Отсекаются заднесторонние полигоны.
• "front": Отсекаются переднесторонние полигоны.
• "none": Никакие полигоны не отсекаются.

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

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

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

• "ccw": Полигоны с вершинами, координаты которых в буфере фреймов заданы в порядке против часовой стрелки.
• "cw": Полигоны с вершинами, координаты которых в буфере фреймов заданы в порядке по часовой стрелке.

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

Примечание:>frontFace и cullMode не оказывают влияния на топологии "point-list", "line-list" или "line-strip".

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

Перечисление, определяющее формат буфера индексов и значение для перезапуска примитивов в случае конвейеров с топологией полосок ("line-strip" или 0xFFFF). Значение перезапуска примитива указывает, какое значение индекса обозначает начало нового примитива, а не продолжение построения полоски с предыдущими индексированными вершинами. Возможные значения:

• "uint16": Указывает размер в байтах 2 и значение для перезапуска примитива 0xFFFF.
• "uint32": Указывает размер в байтах 4 и значение для перезапуска примитива 0xFFFFFFFF.

Состояния примитивов GPU, которые указывают топологию примитива полоски, должны указать формат индекса полоски, если они используются для индексированных отрисовок (например, с помощью GPURenderPassEncoder.drawIndexed()), чтобы значение для перезапуска примитива было известно во время создания конвейера. Конвейеры с топологиями примитивов списка ("line-list", "point-list", или "triangle-list" ) не должны указывать значение stripIndexFormat. Вместо этого они будут использовать формат индексов, переданный, например, GPURenderPassEncoder.setIndexBuffer(), при индексированном рендеринге.

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

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

• "line-list": Каждая последующая пара из двух вершин определяет примитив линии.
• "line-strip": Каждая вершина после первой определяет примитив линии между ней и предыдущей вершиной.
• "triangle-list": Каждая вершина определяет примитив точки.
• "triangle-strip": Каждая последующая тройка из трёх вершин определяет примитив треугольника.
• "triangle-strip": Каждая вершина после первых двух определяет примитив треугольника между ней и двумя предыдущими вершинами.

Если опущено, topology по умолчанию равно "triangle-list".

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

Булево значение. Значение true указывает, что отсечение по глубине отключено. Если опущено, unclippedDepth по умолчанию равно false. Обратите внимание, что для управления отсечением по глубине необходимо включить depth-clip-control функцию в GPUDevice.

Примечание: Для успешного использования свойства unclippedDepth необходимо включить depth-clip-control функцию. В противном случае генерируется GPUValidationError.

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

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

Последовательность типов записей со структурой (id, value), представляющих значения переопределения для констант WGSL, которые можно переопределить в конвейере. Они ведут себя как упорядоченные отображения. В каждом случае id — ключ, используемый для идентификации или выбора записи, а constant — перечисленное значение, представляющее WGSL.

В зависимости от константы, которую вы хотите переопределить, id может принимать форму числового идентификатора константы, если он указан, или иначе имя идентификатора константы.

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

{
  // ...
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  }
}

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

Имя функции в module, которую этот этап будет использовать для выполнения своей работы. Соответствующая функция шейдера должна иметь атрибут @vertex, чтобы быть идентифицированной как эта точка входа. См. Описание точки входа для получения дополнительной информации.

Вы можете опустить свойство entryPoint, если ваш код шейдера содержит единственную функцию с установленным атрибутом @vertex, — браузер будет использовать ее в качестве точки входа по умолчанию. Если entryPoint опущено, и браузер не может определить точку входа по умолчанию, генерируется GPUValidationError, и результирующий GPURenderPipeline будет недействительным.

module

Объект GPUShaderModule, содержащий код WGSL, который будет выполняться этим программируемым этапом.

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

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

arrayStride

Число, представляющее шаг (в байтах) между различными структурами (например, вершинами) внутри буфера.

attributes

Массив объектов, определяющих структуру атрибутов вершин в каждой структуре. Каждый объект имеет следующие свойства:

format

Перечисление, определяющее формат вершины. Все доступные значения см. в GPUVertexFormat определении в спецификации.

offset

Число, указывающее смещение (в байтах) от начала структуры до данных для атрибута.

shaderLocation

Числовой идентификатор, соответствующий этому атрибуту, который будет соответствовать атрибуту @location, объявленному в коде WGSL связанного GPUShaderModule, указанного в свойстве vertex объекта module.

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

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

• "instance": Каждая структура — экземпляр; адрес увеличивается на arrayStride для каждого экземпляра.
• "vertex": Каждая структура — вершина; адрес увеличивается на arrayStride для каждой вершины и сбрасывается между экземплярами.

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

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

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

• Для объектов depthStencil:
  • format должен быть форматом depth-or-stencil.
  • Свойства depthBias, depthBiasClamp и depthBiasSlopeScale должны быть установлены в 0 для топологий линий и точек, т.е. если topology установлено в "line-list", "line-strip" или "point-list".
  • Если depthWriteEnabled равно true или depthCompare не равно "always", format имеет компонент глубины.
  • Если свойства stencilFront или stencilBack не имеют значения по умолчанию, format имеет компонент трафарета.
• Для объектов fragment:
  • targets.length должно быть меньше или равно предельному значению maxColorAttachments GPUDevice (см. предел).
  • Для каждого target, численное значение writeMask должно быть меньше или равно 16.
  • Если какие-либо используемые операции смешивания используют альфа-канал источника (например, "src-alpha-saturated"), выходное изображение должно иметь альфа-канал (т.е. это должно быть vec4).
  • Если используются операции смешивания src1, one-minus-src1, src1-alpha или one-minus-src1-alpha, то функция dual-source-blending поддерживается.
  • Если свойство entryPoint опущено, код шейдера содержит единственную функцию входа фрагментного шейдера, которую браузер может использовать в качестве функции входа по умолчанию.
• Для объектов primitive:
  • Если используется свойство unclippedDepth, то функция depth-clip-control поддерживается.
• Для объектов vertex:
  • Если свойство entryPoint опущено, код шейдера содержит единственную функцию входа вершинного шейдера, которую браузер может использовать в качестве функции входа по умолчанию.

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

// ...

const vertexBuffers = [
  {
    attributes: [
      {
        shaderLocation: 0, // position
        offset: 0,
        format: "float32x4",
      },
      {
        shaderLocation: 1, // color
        offset: 16,
        format: "float32x4",
      },
    ],
    arrayStride: 32,
    stepMode: "vertex",
  },
];

const pipelineDescriptor = {
  vertex: {
    module: shaderModule,
    entryPoint: "vertex_main",
    buffers: vertexBuffers,
  },
  fragment: {
    module: shaderModule,
    entryPoint: "fragment_main",
    targets: [
      {
        format: navigator.gpu.getPreferredCanvasFormat(),
      },
    ],
  },
  primitive: {
    topology: "triangle-list",
  },
  layout: "auto",
};

const renderPipeline = device.createRenderPipeline(pipelineDescriptor);

// ...

• API WebGPU