Class MaterialBuilder

Defined in File materialBuilder.h

Nested Relationships

Nested Types

Struct MaterialBuilder::MaterialData

Class Documentation

class MaterialBuilder

Конструктор материалов с поддержкой цепочечных вызовов (Builder Pattern).

Позволяет гибко настраивать PBR-материалы:

Текстуры: Albedo, Normal, Metallic, Roughness, AO, Emission, Height
Скалярные множители для каждого канала
Поддержку нескольких субматериалов (для много-подмешевых объектов)
Глобальные модификаторы, применяемые ко всем субматериалам
Загрузку сплошных цветов через std::array<unsigned char, 4>

См. также

MaterialComponent, TextureStorage, Renderer::materialBuilder()

Поддерживаемые форматы:

Обычные пути: "textures/brick_albedo.png"
Прямая передача цвета: albedo(0, {95, 23, 243, 255})

Пример использования:

auto material = renderer.materialBuilder()
    .forMesh(meshComponent)
    .albedo(0, "textures/brick_albedo.png")
    .normal(0, "textures/brick_normal.png")
    .metallic(0, 0.8f)
    .roughness(0, 0.4f)
    .emission(1, {255, 112, 52})       // Оранжевое свечение без файла
    .height(0, 0.5f)                   // Параллакс-смещение
    .complete();

Примечание

Все скалярные значения автоматически ограничиваются диапазоном [0.0; 1.0]

Примечание

Глобальные скаляры умножаются на локальные при финализации через complete()

Внутреннее состояние

std::vector<MaterialData> materialsData: Массив данных по субматериалам (индексируется по ID)

Глобальные модификаторы (применяются ко всем субматериалам)

float globalMetallicScalar = 1.0f: Глобальный множитель металличности [0.0–1.0].

float globalRoughnessScalar = 1.0f: Глобальный множитель шероховатости [0.0–1.0].

float globalEmissionScalar = 1.0f: Глобальный множитель эмиссии [0.0–1.0].

float globalAmbientScalar = 1.0f: Глобальный множитель Ambient Occlusion [0.0–1.0].

float globalHeightScalar = 1.0f: Глобальный множитель высоты [0.0–1.0].

Зависимости

prism::scene::Scene &scene: Ссылка на сцену для управления пулом компонентов

prism::PGC::L1::TextureStorage &storage: Ссылка на хранилище текстур для загрузки/кэширования

Настройка структуры материала

MaterialBuilder &size(uint16_t size)

Устанавливает количество субматериалов.

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

Предупреждение

Перезаписывает существующие данные при уменьшении размера.

Параметры:: size – Количество субматериалов (должно быть > 0).
Результат:: Ссылка на текущий объект для цепочечных вызовов.

MaterialBuilder &forMesh(prism::scene::MeshComponent &mesh)

Автоматически определяет количество субматериалов по данным меша.

Извлекает количество материалов из MeshComponent через Scene::getDataFromPool() и вызывает size() для подготовки билдера к настройке соответствующего числа субматериалов.

См. также

MeshComponent, Scene::getDataFromPool()

Примечание

Принимает ссылку для избежания копирования компонента.

Параметры:: mesh – Ссылка на компонент меша, к которому применяется материал.
Результат:: Ссылка на текущий объект для цепочечных вызовов.

MaterialBuilder &forMesh(prism::scene::Entity entity)

Автоматически определяет количество субматериалов по сущности (Entity).

Удобная перегрузка для работы с системой сущностей: автоматически извлекает MeshComponent из указанной сущности и делегирует вызов forMesh(MeshComponent&).

См. также

Scene::getComponent(), forMesh(prism::scene::MeshComponent&)

Предупреждение

Убедитесь, что сущность действительно имеет компонент MeshComponent, иначе поведение неопределено.

Параметры:: entity – Сущность, содержащая компонент MeshComponent.
Результат:: Ссылка на текущий объект для цепочечных вызовов.

Копирование данных из существующих материалов

MaterialBuilder &copyAll(prism::scene::MaterialComponent material)

Полностью копирует параметры всех субматериалов из другого материала.

Копирует пути к текстурам и значения скаляров для каждого субматериала. Глобальные модификаторы текущего билдера не изменяются.

Предупреждение

Требуется, чтобы размеры материалов совпадали (или был вызван size()/forMesh() заранее).

Параметры:: material – Исходный MaterialComponent для копирования.
Результат:: Ссылка на текущий объект для цепочечных вызовов.

MaterialBuilder &copy(prism::scene::MaterialComponent material, uint16_t subMaterialId)

Копирует параметры одного конкретного субматериала.

Предупреждение

Убедитесь, что текущий билдер имеет достаточный размер (size() >= subMaterialId + 1).

Параметры:

material – Исходный MaterialComponent.
subMaterialId – Индекс субматериала в исходном материале.

Результат:

Ссылка на текущий объект для цепочечных вызовов.

Настройка текстур

MaterialBuilder &albedo(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру альбедо для субматериала.

См. также

albedo(uint16_t, std::array<unsigned char, 4>)

Примечание

Текстура будет загружена в хранилище при вызове complete().

Параметры:

subMaterialId – Индекс субматериала (0-based).
filename – Путь к файлу текстуры.

Результат:

Ссылка на текущий объект для цепочечных вызовов.

MaterialBuilder &albedo(uint16_t subMaterialId, std::array<unsigned char, 4> rgba)

Устанавливает сплошной цвет альбедо через RGBA-массив.

Параметры:

subMaterialId – Индекс субматериала.
rgba – Массив из 4 байт {R, G, B, A} в диапазоне [0–255].

Результат:

Ссылка на текущий объект.

MaterialBuilder &normal(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает карту нормалей для субматериала.

Примечание

Ожидается текстура в формате нормалей (tangent space, DirectX-конвенция).

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к файлу текстуры.

Результат:

Ссылка на текущий объект.

MaterialBuilder &normal(uint16_t subMaterialId, std::array<unsigned char, 4> rgba)

Устанавливает сплошной цвет для карты нормалей (редко используется).

Параметры:

subMaterialId – Индекс субматериала.
rgba – Массив {R, G, B, A}, обычно {128, 128, 255, 255} для «нейтральной» нормали.

Результат:

Ссылка на текущий объект.

MaterialBuilder &mrao(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает комбинированную MRAO-текстуру для субматериала.

MRAO = Metallic (R), Roughness (G), Ambient Occlusion (B). Один вызов устанавливает пути для трёх каналов одновременно.

См. также

metallic(), roughness(), ambientOcclusion()

Примечание

Если нужны отдельные текстуры — используйте metallic()/roughness()/ambientOcclusion() раздельно.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к MRAO-текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &mrao(uint16_t subMaterialId, std::array<unsigned char, 4> rgba)

Устанавливает сплошной цвет для MRAO-текстуры.

Параметры:

subMaterialId – Индекс субматериала.
rgba – Массив {Metallic, Roughness, AO, unused}.

Результат:

Ссылка на текущий объект.

MaterialBuilder &mraoh(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает комбинированную MRAOH-текстуру (Metallic, Roughness, AO, Height).

MRAOH = Metallic (R), Roughness (G), Ambient Occlusion (B), Height (A). Один вызов устанавливает пути для четырёх каналов одновременно.

Примечание

Эквивалентно последовательному вызову mrao() + height() с одним файлом.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к MRAOH-текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &mraoh(uint16_t subMaterialId, std::array<unsigned char, 4> rgba)

Устанавливает сплошной цвет для MRAOH-текстуры.

Параметры:

subMaterialId – Индекс субматериала.
rgba – Массив {Metallic, Roughness, AO, Height}.

Результат:

Ссылка на текущий объект.

Настройка металличности (Metallic)

MaterialBuilder &metallic(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру металличности для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к одноканальной текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &metallic(uint16_t subMaterialId, float metallic)

Устанавливает скалярное значение металличности для субматериала.

Примечание

Значение будет ограничено std::clamp(0.0, 1.0) при финализации.

Параметры:

subMaterialId – Индекс субматериала.
metallic – Значение в диапазоне [0.0–1.0] (0 = диэлектрик, 1 = металл).

Результат:

Ссылка на текущий объект.

MaterialBuilder &metallic(float metallic)

Устанавливает глобальное значение металличности для всех субматериалов.

Примечание

Умножается на локальные значения при вызове complete().

Параметры:: metallic – Глобальный множитель [0.0–1.0].
Результат:: Ссылка на текущий объект.

Настройка шероховатости (Roughness)

MaterialBuilder &roughness(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру шероховатости для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к одноканальной текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &roughness(uint16_t subMaterialId, float roughness)

Устанавливает скалярное значение шероховатости для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
roughness – Значение в диапазоне [0.0–1.0] (0 = зеркальная, 1 = матовая).

Результат:

Ссылка на текущий объект.

MaterialBuilder &roughness(float roughness)

Устанавливает глобальное значение шероховатости для всех субматериалов.

Примечание

Умножается на локальные значения при вызове complete().

Параметры:: roughness – Глобальный множитель [0.0–1.0].
Результат:: Ссылка на текущий объект.

Настройка Ambient Occlusion (AO)

MaterialBuilder &ambientOcclusion(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру Ambient Occlusion для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к одноканальной AO-текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &ambientOcclusion(uint16_t subMaterialId, float ambient)

Устанавливает скалярное значение АО для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
ambient – Множитель интенсивности затенения [0.0–1.0].

Результат:

Ссылка на текущий объект.

MaterialBuilder &ambientOcclusion(float ambient)

Устанавливает глобальное значение АО для всех субматериалов.

Параметры:: ambient – Глобальный множитель [0.0–1.0].
Результат:: Ссылка на текущий объект.

Настройка эмиссии (Emission)

MaterialBuilder &emission(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру эмиссии для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к текстуре свечения.

Результат:

Ссылка на текущий объект.

MaterialBuilder &emission(uint16_t subMaterialId, std::array<unsigned char, 4> rgba)

Устанавливает сплошной цвет эмиссии через RGBA-массив.

Параметры:

subMaterialId – Индекс субматериала.
rgba – Массив {R, G, B, A}, где RGB задаёт цвет свечения.

Результат:

Ссылка на текущий объект.

MaterialBuilder &emission(uint16_t subMaterialId, float emission)

Устанавливает скалярную интенсивность эмиссии для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
emission – Множитель яркости [0.0–1.0].

Результат:

Ссылка на текущий объект.

MaterialBuilder &emission(float emission)

Устанавливает глобальную интенсивность эмиссии для всех субматериалов.

Параметры:: emission – Глобальный множитель [0.0–1.0].
Результат:: Ссылка на текущий объект.

Настройка высоты (Height/Displacement)

MaterialBuilder &height(uint16_t subMaterialId, std::filesystem::path filename)

Устанавливает текстуру высоты для субматериала.

Используется для паралакс-маппинга, тесселяции или дисплейсмент-маппинга.

Примечание

Значения высоты обычно интерпретируются как: 0 = минимум, 255 = максимум смещения.

Параметры:

subMaterialId – Индекс субматериала.
filename – Путь к одноканальной высоте-текстуре.

Результат:

Ссылка на текущий объект.

MaterialBuilder &height(uint16_t subMaterialId, float height)

Устанавливает скалярное значение высоты для субматериала.

Параметры:

subMaterialId – Индекс субматериала.
height – Множитель высоты [0.0–1.0] (0 = нет смещения, 1 = полное смещение).

Результат:

Ссылка на текущий объект.

MaterialBuilder &height(float height)

Устанавливает глобальное значение высоты для всех субматериалов.

Примечание

Умножается на локальные значения при вызове complete().

Параметры:: height – Глобальный множитель [0.0–1.0].
Результат:: Ссылка на текущий объект.

Public Functions

MaterialBuilder(prism::scene::Scene &scene, prism::PGC::L1::TextureStorage &storage)

Конструктор MaterialBuilder.

Предупреждение

Не создавайте экземпляр напрямую — используйте Renderer::materialBuilder()

Параметры:

scene – Ссылка на активную сцену.
storage – Ссылка на менеджер текстур.

prism::scene::MaterialComponent complete()

Финализирует настройку и создаёт MaterialComponent.

Выполняет:

Загрузку всех указанных текстур/цветов через TextureStorage
Применение глобальных и локальных скаляров (с std::clamp[0.0; 1.0])
Обновление кэша хранилища текстур (storage.update())
Добавление готового материала в пул компонентов сцены

См. также

MaterialComponent, TextureStorage::update(), PGC::colorToPath()

Предупреждение

После вызова complete() билдер можно повторно использовать, но предыдущие настройки будут сброшены при новых вызовах сеттеров.

Результат:: Созданный MaterialComponent, готовый к назначению на рендер-объекты.

struct MaterialData

Внутреннее описание параметров одного субматериала.

Хранит пути к текстурам и скалярные множители для PBR-каналов. Используется только внутри MaterialBuilder.

Public Members

std::optional<assets::AssetSpec> albedo: Спецификация текстуры альбедо (базовый цвет, sRGB)

std::optional<assets::AssetSpec> normal: Спецификация к карте нормалей (линейное пространство)

std::optional<assets::AssetSpec> metallic: Спецификация к карте металличности (одноканальная, линейная)

std::optional<assets::AssetSpec> roughness: Спецификация к карте шероховатости (одноканальная, линейная)

std::optional<assets::AssetSpec> ambient: Спецификация к карте Ambient Occlusion (одноканальная)

std::optional<assets::AssetSpec> emission: Спецификация к карте эмиссии (sRGB, HDR-значения возможны)

std::optional<assets::AssetSpec> height: Спецификация к карте высоты (для паралакс-маппинга/тесселяции)

float metallicScalar = 1.0f: Множитель металличности [0.0–1.0] для данного субматериала

float roughnessScalar = 1.0f: Множитель шероховатости [0.0–1.0] для данного субматериала

float ambientScalar = 1.0f: Множитель AO [0.0–1.0] для данного субматериала

float emissionScalar = 1.0f: Множитель интенсивности эмиссии [0.0–1.0] для данного субматериала

float heightScalar = 1.0f: Множитель высоты [0.0–1.0] для данного субматериала