GPUDevice: метод createTexture()

Метод createTexture() интерфейса GPUDevice создаёт GPUTexture для хранения одномерных, двумерных или трёхмерных массивов данных, таких как изображения, для использования в операциях рендеринга на GPU.

descriptor

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

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

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

• "1d": Текстура одномерная.
• "2d": Текстура двумерная или массив двумерных слоёв.
• "3d": Текстура трёхмерная.

dimension по умолчанию равно "2d", если значение не указано.

format

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

Примечание:

• Для создания текстур формата depth32float-stencil8 необходимо включить функцию depth32float-stencil8.
• Для создания двумерных сжатых BC текстур GPUTexture форматов: bc1-rgba-unorm, bc1-rgba-unorm-srgb, bc2-rgba-unorm, bc2-rgba-unorm-srgb, bc3-rgba-unorm, bc3-rgba-unorm-srgb, bc4-r-unorm, bc4-r-snorm, bc5-rg-unorm, bc5-rg-snorm, bc6h-rgb-ufloat, bc6h-rgb-float, bc7-rgba-unorm, и bc7-rgba-unorm-srgb необходимо включить функцию texture-compression-bc.
• Для создания двумерных сжатых ASTC текстур GPUTexture форматов: astc-4x4-unorm, astc-4x4-unorm-srgb, astc-5x4-unorm, astc-5x4-unorm-srgb, astc-5x5-unorm, astc-5x5-unorm-srgb, astc-6x5-unorm, astc-6x5-unorm-srgb, astc-6x6-unorm, astc-6x6-unorm-srgb, astc-8x5-unorm, astc-8x5-unorm-srgb, astc-8x6-unorm, astc-8x6-unorm-srgb, astc-8x8-unorm, astc-8x8-unorm-srgb, astc-10x5-unorm, astc-10x5-unorm-srgb, astc-10x6-unorm, astc-10x6-unorm-srgb, astc-10x8-unorm, astc-10x8-unorm-srgb, astc-10x10-unorm, astc-10x10-unorm-srgb, astc-12x10-unorm, astc-12x10-unorm-srgb, и astc-12x12-unorm``astc-12x12-unorm-srgb необходимо включить функцию texture-compression-astc.
• Для создания двумерных сжатых ETC2 текстур GPUTexture форматов: etc2-rgb8unorm, etc2-rgb8unorm-srgb, etc2-rgb8a1unorm, etc2-rgb8a1unorm-srgb, etc2-rgba8unorm, etc2-rgba8unorm-srgb, eac-r11unorm, eac-r11snorm, eac-rg11unorm, и eac-rg11snorm необходимо включить функцию texture-compression-etc2.

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

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

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

Число, указывающее количество уровней mipmap текстуры. Если не указано, по умолчанию равно 1.

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

Число, указывающее количество сэмплов текстуры. Для корректного значения должно быть 1 или 4. Если не указано, по умолчанию равно 1. Значение, большее 1, указывает на многообразную текстуру.

size

Объект или массив, определяющий ширину, высоту и количество слоёв глубины/массива текстуры. Ширина должна быть всегда указана, в то время как высота и глубина/количество слоёв массива являются необязательными и будут по умолчанию равны 1, если не указаны.

Пример массива size.

size: [16, 16, 2];

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

size: {
  width: 16,
  height: 16,
  depthOrArrayLayers: 2
}

usage

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

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

usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT;

Примечание:

• Для указания способа использования STORAGE_BINDING для bgra8unorm-format GPUTexture необходимо включить функцию bgra8unorm-storage.
• Для указания способа использования RENDER_ATTACHMENT для rg11b10ufloat-format GPUTexture, а также его смешивания и многообразной выборки, необходимо включить функцию rg11b10ufloat-renderable.

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

Массив перечисляемых значений, определяющих другие форматы текстур, разрешённые при вызове GPUTexture.createView() для этой текстуры, помимо формата текстуры, указанного в поле format.

Объект GPUTexture.

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

• Указан корректный usage.
• Значения, указанные в size (ширина, высота или глубина/количество слоёв массива), должны быть больше 0.
• mipLevelCount должно быть больше 0.
• sampleCount должно быть равно 1 или 4.
• Если dimension установлено в "1d":
  • Значение ширины size должно быть меньше или равно пределу maxTextureDimension1D устройства GPUDevice (предел).
  • Значения высоты и глубины/количества слоёв массива size должны быть равны 1.
  • Значение sampleCount должно быть равно 1.
  • Значение format не должно быть сжатым форматом формат сжатия или форматом глубины/стенок формат глубины/стенок.
• Если dimension установлено в "2d":
  • Значения ширины и высоты size должны быть меньше или равны пределу maxTextureDimension2D устройства GPUDevice (предел).
  • Значение глубины/количества слоёв массива size должно быть меньше или равно пределу maxTextureArrayLayers устройства GPUDevice (предел).
• Если dimension установлено в "3d":
  • Значения ширины, высоты и глубины/количества слоёв массива size должны быть меньше или равны пределу maxTextureDimension3D устройства GPUDevice (предел).
  • Значение sampleCount должно быть равно 1.
  • Значение format не должно быть сжатым форматом формат сжатия или форматом глубины/стенок формат глубины/стенок.
• Значение ширины size должно быть кратно ширине блока текстуры.
• Значение высоты size должно быть кратно высоте блока текстуры.
• Если sampleCount больше 1:
  • mipLevelCount должно быть равно 1.
  • Значение глубины/количества слоёв массива size должно быть равно 1.
  • usage включает флаг GPUTextureUsage.RENDER_ATTACHMENT.
  • usage не включает флаг GPUTextureUsage.STORAGE_BINDING.
  • Указанный формат поддерживает многократную выборку.
• Значение mipLevelCount должно быть меньше или равно максимальному количеству уровней mip.
• Форматы, указанные в format и viewFormats являются совместимыми друг с другом.
• Если usage включает флаг GPUTextureUsage.RENDER_ATTACHMENT:
  • format является рендерируемым форматом (то есть форматом цветного рендеринга или форматом глубины/стенок).
  • dimension установлено в "2d".
• Если usage включает флаг GPUTextureUsage.STORAGE_BINDING:
  • Указанный format включает возможность STORAGE_BINDING (см. таблицу простых цветовых форматов для справки).

В примере Textured Cube на WebGPU, текстура для использования на гранях куба создаётся:

• Загрузка изображения в HTMLImageElement и создание изображения из растрового изображения с помощью createImageBitmap().
• Создание новой текстуры с помощью createTexture().
• Копирование растрового изображения в текстуру с помощью GPUQueue.copyExternalImageToTexture().

//...

let cubeTexture;

{
  const img = document.createElement("img");
  img.src = new URL(
    "../../../assets/img/Di-3d.png",
    import.meta.url,
  ).toString();
  await img.decode();
  const imageBitmap = await createImageBitmap(img);

  cubeTexture = device.createTexture({
    size: [imageBitmap.width, imageBitmap.height, 1],
    format: "rgba8unorm",
    usage:
      GPUTextureUsage.TEXTURE_BINDING |
      GPUTextureUsage.COPY_DST |
      GPUTextureUsage.RENDER_ATTACHMENT,
  });
  device.queue.copyExternalImageToTexture(
    { source: imageBitmap },
    { texture: cubeTexture },
    [imageBitmap.width, imageBitmap.height],
  );
}

//...

• The WebGPU API