ImageTexture3D — C# API

Объёмная GPU-текстура из отдельных изображений-срезов.

class ImageTexture3DReckfellSharpНаследует Texture3D

ImageTexture3D создаёт объём из Image-срезов. Это не Texture2DArray: глубина является третьей координатой объёма. Create задаёт формат и размеры, Update загружает полный совместимый набор, GetData читает отдельные изображения. Редактирование прочитанных Image само по себе не обновляет GPU.

Без mipmaps нужны depth изображений width×height. С mipmaps порядок идёт по уровням; на каждом следующем уровне ширина, высота и глубина делятся на 2 с округлением вниз, минимум 1. Для 4×4×4 это 4 + 2 + 1 изображение. Не вызывайте GenerateMipmaps на отдельных срезах вместо подготовки объёмной цепочки.

Ниже проверенный помощник для простого RGBA8-объёма без mipmaps: каждый Color заполняет один Z-срез. Вызывающий код владеет возвращённым ресурсом. Это пример структуры данных, а не демонстрация графики.

C#
using System;
using Reckfell;

public static class VolumeSlices
{
    // Each color fills one Z slice. This creates a volume without mipmaps.
    public static ImageTexture3D CreateSolid(int width, int height, params Color[] colors)
    {
        if (width <= 0 || height <= 0)
            throw new ArgumentOutOfRangeException(nameof(width), "Positive dimensions required.");
        ArgumentNullException.ThrowIfNull(colors);
        if (colors.Length == 0)
            throw new ArgumentException("At least one Z slice required.", nameof(colors));
        var slices = new Reckfell.Collections.Array<Image>();
        try
        {
            foreach (var color in colors)
            {
                var image = Image.CreateEmpty(width, height, false, Image.Format.Rgba8);
                image.Fill(color);
                slices.Add(image);
            }
            var texture = new ImageTexture3D();
            var result = texture.Create(Image.Format.Rgba8, width, height, colors.Length, false, slices);
            if (result == Error.Ok) return texture;
            texture.Dispose();
            throw new InvalidOperationException($"Texture creation failed: {result}");
        }
        finally
        {
            foreach (var image in slices) image.Dispose();
            slices.Clear();
        }
    }
}

Обычный объём и кубическая mip-цепочка проверены при независимой загрузке бинарного ресурса. Но 1×1×4 с mipmaps после сохранения загружается как 1×1×7 без mipmaps: внутренний _Images выводит уровни только по изменению ширины/высоты. Дефект воспроизведён и не исправлялся в движке; проверяйте размер и HasMipmaps после загрузки.

Проверены ресурсные операции в Windows Forward+/Vulkan. Использование в тумане, частицах и шейдерах, все форматы, объёмы и пределы памяти этим прогоном не подтверждены.

Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.

Конструкторы1

ImageTexture3DКонструктор

# ImageTexture3D

C#
public ImageTexture3D();

Создаёт ещё не инициализированный объёмный ресурс. Метаданные по умолчанию: 1×1×1, формат L8, без mipmaps; это не доказательство загруженных пикселей. Сначала вызовите Create. Получение RID может создать заглушку и не заменяет инициализацию.

Свойства1

_ImagesСвойство

# _Images

C#
public Reckfell.Collections.Array<Image> _Images { get; set; }

Внутреннее сохраняемое свойство для сериализации. Getter читает срезы; setter выводит размер и наличие mipmaps из списка изображений. Для обычного кода используйте Create/GetData/Update. Подтверждено ограничение: сохранённый объём 1×1×4 с mipmaps загружается как 1×1×7 без mipmaps, поскольку ширина/высота всех срезов одинаковы и setter не распознаёт уменьшение только глубины. Для такой формы не полагайтесь на автоматическое сохранение ресурса: храните явные размеры/флаг и восстанавливайте Create из корректных данных, проверяя результат.

Методы2

CreateError

# Create

C#
public Error Create(Image.Format format, int width, int height, int depth, bool useMipmaps, Reckfell.Collections.Array<Image> data);

Создаёт или заменяет объёмную текстуру. Без mipmaps передайте ровно depth непустых Image одинакового формата и размера width×height. С mipmaps передайте все уровни отдельными срезами: например, 4×4×4 — четыре 4×4, два 2×2 и один 1×1. Каждый Image должен быть без собственной mipmap-цепочки. Проверяйте Error и журнал; не используйте метод как универсальный валидатор произвольных массивов. При замене корректного ресурса RID сохраняется; атомарность ошибочного запроса не гарантируется.

Параметры
Имя	Тип	По умолчанию
`format`	`Image.Format`	—
`width`	`int`	—
`height`	`int`	—
`depth`	`int`	—
`useMipmaps`	`bool`	—
`data`	`Reckfell.Collections.Array<Image>`	—

format

Единый Image.Format всех срезов; пример проверен с Rgba8.

width

Положительная ширина основного уровня в текселях.

height

Положительная высота основного уровня в текселях.

depth

Положительное число Z-срезов основного уровня, не число всех mip-изображений.

useMipmaps

Есть ли полная объёмная mip-цепочка в data; уровни не генерируются автоматически.

data

Упорядоченные непустые Image без собственных mipmaps: все Z-срезы уровня 0, затем уровня 1 и далее до 1×1×1 при включённых mipmaps.

Возвращает Error

Error результата Create; проверяйте также диагностику и свойства полученной текстуры.

Updatevoid

# Update

C#
public void Update(Reckfell.Collections.Array<Image> data);

Загружает полный новый набор срезов в уже созданный объём, сохраняя формат, размеры и конфигурацию mipmaps. Передайте тот же порядок и количество изображений, что требует Create для текущего объёма. Это не обновление одного произвольного Z-среза и не автоматический resize. Метод void; ошибки проверяются по журналу, Error не возвращается.

Параметры
Имя	Тип	По умолчанию
`data`	`Reckfell.Collections.Array<Image>`	—

data