RDTextureFormat
Размеры, формат и назначения для создания GPU-текстуры.
RDTextureFormat описывает будущую текстуру RenderingDevice. Сам объект не содержит GPU-изображение. Значения по умолчанию: R8Unorm, Type2D, Width/Height/Depth/ArrayLayers/Mipmaps=1, Samples1, UsageBits=0, IsResolveBuffer=false, IsDiscardable=false. Нулевые UsageBits нужно заменить: с ними TextureCreate отклоняет создание. Setter сохраняет значение, но не подтверждает допустимость всей конфигурации.
Для обычной RGBA8-текстуры подготовьте ровно width × height × 4 байта в порядке RGBA, по одной записи массива данных на слой. Этот выполненный helper создаёт один 2D-слой и один базовый уровень; он не загружает файл изображения и не генерирует mip-цепочку:
using System;
using Reckfell;
public static class RgbaTexture
{
// Caller owns the returned RID. Run in the supplied device's valid thread context.
public static Rid Create(RenderingDevice device, uint width, uint height, byte[] pixels)
{
ArgumentNullException.ThrowIfNull(device);
ArgumentNullException.ThrowIfNull(pixels);
ulong count = (ulong)width * height;
if (width == 0 || height == 0 || count > int.MaxValue / 4
|| pixels.Length != (int)count * 4)
throw new ArgumentException("Expected width * height * 4 RGBA8 bytes and positive dimensions.");
var usage = RenderingDevice.TextureUsageBits.SamplingBit
| RenderingDevice.TextureUsageBits.CanUpdateBit
| RenderingDevice.TextureUsageBits.CanCopyFromBit;
var format = RenderingDevice.DataFormat.R8G8B8A8Unorm;
if (!device.TextureIsFormatSupportedForUsage(format, usage))
throw new NotSupportedException("RGBA8 is unavailable for the requested usage.");
using var description = new RDTextureFormat
{
Format = format, Width = width, Height = height, Depth = 1,
ArrayLayers = 1, Mipmaps = 1,
TextureType = RenderingDevice.TextureType.Type2D,
Samples = RenderingDevice.TextureSamples.Samples1, UsageBits = usage
};
using var view = new RDTextureView();
var layers = new Reckfell.Collections.Array<byte[]> { pixels };
Rid texture = device.TextureCreate(description, view, layers);
if (!texture.IsValid) throw new InvalidOperationException("GPU texture creation failed.");
return texture;
}
}Контекст вызова обязателен: для основного устройства из RenderingServer.GetRenderingDevice вызывайте helper через RenderingServer.CallOnRenderThread. Это заимствованное устройство — не вызывайте у него Dispose. Helper не выбирает поток и не создаёт локальное устройство. Возвращённый RID принадлежит вызывающему коду: после завершения использования вызовите FreeRid на том же устройстве в допустимом контексте. Описания можно Dispose после TextureCreate; это не освобождает созданную текстуру.
Размеры задаются в texel; ArrayLayers — слои, а не глубина 3D. Mipmaps включает базовый уровень: 1 означает отсутствие дополнительных уровней. Samples задаёт MSAA, не фильтрацию. CanUpdateBit нужен для TextureUpdate, CanCopyFromBit — для TextureGetData. Синхронное чтение данных может остановить CPU в ожидании GPU; не используйте его как обычный покадровый путь.
AddShareableFormat задаёт список до создания: при непустом списке включите базовый Format и нужные форматы представлений. Разрешение в списке не гарантирует поддержку драйвером. Формат представления задаётся через RDTextureView. Изменение исходного описания или результата TextureGetFormat не меняет размеры и формат уже созданной текстуры: для другой конфигурации создайте новый ресурс и освободите старый.
На установленном Windows/Vulkan Forward+ проверены создание RGBA8, обновление, точные байты чтения, независимость описаний и срок жизни shared-представлений. Предупреждение Vulkan сохранено в отчёте. Чтение байтов не проверяет результат shader sampling, цветопередачу sRGB или качество картинки. 3D/cube/mip/MSAA/resolve/discardable и другие устройства этим примером не проверены.
Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.
Конструкторы1
RDTextureFormatКонструктор
public RDTextureFormat();Создаёт описание с R8Unorm, Type2D, размерами/слоями/уровнями 1, Samples1, UsageBits=0 и обоими флагами false. GPU-текстуру не создаёт; перед TextureCreate обязательно задайте назначения. Созданный вами RefCounted-объект можно освободить через Dispose после вызова создания.
Свойства11
ArrayLayersСвойство
public uint ArrayLayers { get; set; }Число слоёв, изначально 1. Применяется к массивам и кубическим текстурам; для них требуется не меньше 1 и соблюдение лимита устройства. У кубических типов число кратно 6, каждая грань — слой. Обычные неслоистые типы нормализуют значение до 1.
DepthСвойство
public uint Depth { get; set; }Глубина объёмной 3D-текстуры в texel, изначально 1. Для Type3D должна быть не меньше 1. У остальных типов при создании нормализуется до 1; это не число слоёв массива.
FormatСвойство
public RenderingDevice.DataFormat Format { get; set; }Формат хранения texel, изначально DataFormat.R8Unorm: один нормализованный 8-битный канал. Для RGBA8 явно задайте R8G8B8A8Unorm. Формат определяет размер и интерпретацию данных; поддержка зависит также от UsageBits и устройства.
HeightСвойство
public uint Height { get; set; }Высота базового уровня в texel, изначально 1. Для 2D/3D при создании нужна величина не меньше 1; для 1D устройство нормализует высоту до 1 в своей копии описания.
IsDiscardableСвойство
public bool IsDiscardable { get; set; }Разрешение не сохранять содержимое между использованиями render target, изначально false. Имеет смысл для целей draw list, когда старые данные не нужны. Не используйте для изображения, которое обязано сохраняться; флаг не обещает прирост FPS на каждом GPU.
IsResolveBufferСвойство
public bool IsResolveBuffer { get; set; }Признак назначения текстуры как результата resolve, изначально false. Учитывается при организации framebuffer/resolve; не превращает исходную MSAA-текстуру в обычную и не запускает операцию копирования или resolve.
MipmapsСвойство
public uint Mipmaps { get; set; }Количество уровней вместе с базовым, изначально 1: дополнительных mip-уровней нет. При создании требуется минимум 1 и не больше полной цепочки для размеров текстуры. Увеличение числа не генерирует изображение уменьшенных уровней; начальные данные должны содержать требуемые байты цепочки.
SamplesСвойство
public RenderingDevice.TextureSamples Samples { get; set; }Число выборок MSAA на texel, изначально TextureSamples.Samples1. Это не фильтрация, не число mip-уровней и не размер текстуры. Совместимость MSAA зависит от формата, назначения и устройства; изменение поля само не выполняет resolve.
TextureTypeСвойство
public RenderingDevice.TextureType TextureType { get; set; }Размерность и организация текстуры, изначально TextureType.Type2D. Выбирает смысл Width/Height/Depth/ArrayLayers и проверки при создании. Type3D использует Depth; массивы используют ArrayLayers. Не меняет тип уже созданного ресурса.
UsageBitsСвойство
public RenderingDevice.TextureUsageBits UsageBits { get; set; }Назначения текстуры, изначально 0; с нулём TextureCreate отклоняет создание. Объединяйте только нужные флаги через |: SamplingBit для чтения шейдером, CanUpdateBit для TextureUpdate, CanCopyFromBit для TextureGetData. Проверяйте сочетание формата и флагов через TextureIsFormatSupportedForUsage.
WidthСвойство
public uint Width { get; set; }Ширина базового уровня в texel, изначально 1. При создании нужна величина не меньше 1 в пределах лимита устройства. Setter только сохраняет uint и не выделяет память.
Методы24
AddShareableFormatvoid
public void AddShareableFormat(RenderingDevice.DataFormat format);Добавляет допустимый формат представления в описание. Если список непустой, включите в него и базовый Format, и каждый нужный override до создания текстуры. Добавление не устраняет дубликаты и не гарантирует совместимость форматов на устройстве. Уже созданная текстура не изменяется.
| Имя | Тип | По умолчанию |
|---|---|---|
format | RenderingDevice.DataFormat | — |
formatФормат представления для добавления в список; при непустом списке базовый Format также должен присутствовать.
GetArrayLayersuint
public uint GetArrayLayers();Возвращает сохранённое значение ArrayLayers из описания. Число слоёв, изначально 1. Применяется к массивам и кубическим текстурам; для них требуется не меньше 1 и соблюдение лимита устройства. У кубических типов число кратно 6, каждая грань — слой. Обычные неслоистые типы нормализуют значение до 1.
uintСохранённое ArrayLayers этого описания; не запрос текущего GPU-ресурса.
GetDepthuint
public uint GetDepth();Возвращает сохранённое значение Depth из описания. Глубина объёмной 3D-текстуры в texel, изначально 1. Для Type3D должна быть не меньше 1. У остальных типов при создании нормализуется до 1; это не число слоёв массива.
uintСохранённое Depth этого описания; не запрос текущего GPU-ресурса.
GetFormatRenderingDevice.DataFormat
public RenderingDevice.DataFormat GetFormat();Возвращает сохранённое значение Format из описания. Формат хранения texel, изначально DataFormat.R8Unorm: один нормализованный 8-битный канал. Для RGBA8 явно задайте R8G8B8A8Unorm. Формат определяет размер и интерпретацию данных; поддержка зависит также от UsageBits и устройства.
RenderingDevice.DataFormatСохранённое Format этого описания; не запрос текущего GPU-ресурса.
GetHeightuint
public uint GetHeight();Возвращает сохранённое значение Height из описания. Высота базового уровня в texel, изначально 1. Для 2D/3D при создании нужна величина не меньше 1; для 1D устройство нормализует высоту до 1 в своей копии описания.
uintСохранённое Height этого описания; не запрос текущего GPU-ресурса.
GetIsDiscardablebool
public bool GetIsDiscardable();Возвращает сохранённое значение IsDiscardable из описания. Разрешение не сохранять содержимое между использованиями render target, изначально false. Имеет смысл для целей draw list, когда старые данные не нужны. Не используйте для изображения, которое обязано сохраняться; флаг не обещает прирост FPS на каждом GPU.
boolСохранённое IsDiscardable этого описания; не запрос текущего GPU-ресурса.
GetIsResolveBufferbool
public bool GetIsResolveBuffer();Возвращает сохранённое значение IsResolveBuffer из описания. Признак назначения текстуры как результата resolve, изначально false. Учитывается при организации framebuffer/resolve; не превращает исходную MSAA-текстуру в обычную и не запускает операцию копирования или resolve.
boolСохранённое IsResolveBuffer этого описания; не запрос текущего GPU-ресурса.
GetMipmapsuint
public uint GetMipmaps();Возвращает сохранённое значение Mipmaps из описания. Количество уровней вместе с базовым, изначально 1: дополнительных mip-уровней нет. При создании требуется минимум 1 и не больше полной цепочки для размеров текстуры. Увеличение числа не генерирует изображение уменьшенных уровней; начальные данные должны содержать требуемые байты цепочки.
uintСохранённое Mipmaps этого описания; не запрос текущего GPU-ресурса.
GetSamplesRenderingDevice.TextureSamples
public RenderingDevice.TextureSamples GetSamples();Возвращает сохранённое значение Samples из описания. Число выборок MSAA на texel, изначально TextureSamples.Samples1. Это не фильтрация, не число mip-уровней и не размер текстуры. Совместимость MSAA зависит от формата, назначения и устройства; изменение поля само не выполняет resolve.
RenderingDevice.TextureSamplesСохранённое Samples этого описания; не запрос текущего GPU-ресурса.
GetTextureTypeRenderingDevice.TextureType
public RenderingDevice.TextureType GetTextureType();Возвращает сохранённое значение TextureType из описания. Размерность и организация текстуры, изначально TextureType.Type2D. Выбирает смысл Width/Height/Depth/ArrayLayers и проверки при создании. Type3D использует Depth; массивы используют ArrayLayers. Не меняет тип уже созданного ресурса.
RenderingDevice.TextureTypeСохранённое TextureType этого описания; не запрос текущего GPU-ресурса.
GetUsageBitsRenderingDevice.TextureUsageBits
public RenderingDevice.TextureUsageBits GetUsageBits();Возвращает сохранённое значение UsageBits из описания. Назначения текстуры, изначально 0; с нулём TextureCreate отклоняет создание. Объединяйте только нужные флаги через |: SamplingBit для чтения шейдером, CanUpdateBit для TextureUpdate, CanCopyFromBit для TextureGetData. Проверяйте сочетание формата и флагов через TextureIsFormatSupportedForUsage.
RenderingDevice.TextureUsageBitsСохранённое UsageBits этого описания; не запрос текущего GPU-ресурса.
GetWidthuint
public uint GetWidth();Возвращает сохранённое значение Width из описания. Ширина базового уровня в texel, изначально 1. При создании нужна величина не меньше 1 в пределах лимита устройства. Setter только сохраняет uint и не выделяет память.
uintСохранённое Width этого описания; не запрос текущего GPU-ресурса.
RemoveShareableFormatvoid
public void RemoveShareableFormat(RenderingDevice.DataFormat format);Удаляет одно вхождение формата из списка описания. При дубликатах могут остаться другие вхождения: выполненная проверка добавила формат дважды и после одного удаления смогла создать его представление. Не отзывает доступ у уже созданных GPU-представлений.
| Имя | Тип | По умолчанию |
|---|---|---|
format | RenderingDevice.DataFormat | — |
formatФормат, одно вхождение которого удаляется из списка описания.
SetArrayLayersvoid
public void SetArrayLayers(uint pMember);Сохраняет ArrayLayers без выделения GPU-памяти и проверки готовности всей конфигурации. Число слоёв, изначально 1. Применяется к массивам и кубическим текстурам; для них требуется не меньше 1 и соблюдение лимита устройства. У кубических типов число кратно 6, каждая грань — слой. Обычные неслоистые типы нормализуют значение до 1.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | uint | — |
pMemberЧисло слоёв, изначально 1. Применяется к массивам и кубическим текстурам; для них требуется не меньше 1 и соблюдение лимита устройства. У кубических типов число кратно 6, каждая грань — слой. Обычные неслоистые типы нормализуют значение до 1.
SetDepthvoid
public void SetDepth(uint pMember);Сохраняет Depth без выделения GPU-памяти и проверки готовности всей конфигурации. Глубина объёмной 3D-текстуры в texel, изначально 1. Для Type3D должна быть не меньше 1. У остальных типов при создании нормализуется до 1; это не число слоёв массива.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | uint | — |
pMemberГлубина объёмной 3D-текстуры в texel, изначально 1. Для Type3D должна быть не меньше 1. У остальных типов при создании нормализуется до 1; это не число слоёв массива.
SetFormatvoid
public void SetFormat(RenderingDevice.DataFormat pMember);Сохраняет Format без выделения GPU-памяти и проверки готовности всей конфигурации. Формат хранения texel, изначально DataFormat.R8Unorm: один нормализованный 8-битный канал. Для RGBA8 явно задайте R8G8B8A8Unorm. Формат определяет размер и интерпретацию данных; поддержка зависит также от UsageBits и устройства.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | RenderingDevice.DataFormat | — |
pMemberФормат хранения texel, изначально DataFormat.R8Unorm: один нормализованный 8-битный канал. Для RGBA8 явно задайте R8G8B8A8Unorm. Формат определяет размер и интерпретацию данных; поддержка зависит также от UsageBits и устройства.
SetHeightvoid
public void SetHeight(uint pMember);Сохраняет Height без выделения GPU-памяти и проверки готовности всей конфигурации. Высота базового уровня в texel, изначально 1. Для 2D/3D при создании нужна величина не меньше 1; для 1D устройство нормализует высоту до 1 в своей копии описания.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | uint | — |
pMemberВысота базового уровня в texel, изначально 1. Для 2D/3D при создании нужна величина не меньше 1; для 1D устройство нормализует высоту до 1 в своей копии описания.
SetIsDiscardablevoid
public void SetIsDiscardable(bool pMember);Сохраняет IsDiscardable без выделения GPU-памяти и проверки готовности всей конфигурации. Разрешение не сохранять содержимое между использованиями render target, изначально false. Имеет смысл для целей draw list, когда старые данные не нужны. Не используйте для изображения, которое обязано сохраняться; флаг не обещает прирост FPS на каждом GPU.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | bool | — |
pMemberРазрешение не сохранять содержимое между использованиями render target, изначально false. Имеет смысл для целей draw list, когда старые данные не нужны. Не используйте для изображения, которое обязано сохраняться; флаг не обещает прирост FPS на каждом GPU.
SetIsResolveBuffervoid
public void SetIsResolveBuffer(bool pMember);Сохраняет IsResolveBuffer без выделения GPU-памяти и проверки готовности всей конфигурации. Признак назначения текстуры как результата resolve, изначально false. Учитывается при организации framebuffer/resolve; не превращает исходную MSAA-текстуру в обычную и не запускает операцию копирования или resolve.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | bool | — |
pMemberПризнак назначения текстуры как результата resolve, изначально false. Учитывается при организации framebuffer/resolve; не превращает исходную MSAA-текстуру в обычную и не запускает операцию копирования или resolve.
SetMipmapsvoid
public void SetMipmaps(uint pMember);Сохраняет Mipmaps без выделения GPU-памяти и проверки готовности всей конфигурации. Количество уровней вместе с базовым, изначально 1: дополнительных mip-уровней нет. При создании требуется минимум 1 и не больше полной цепочки для размеров текстуры. Увеличение числа не генерирует изображение уменьшенных уровней; начальные данные должны содержать требуемые байты цепочки.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | uint | — |
pMemberКоличество уровней вместе с базовым, изначально 1: дополнительных mip-уровней нет. При создании требуется минимум 1 и не больше полной цепочки для размеров текстуры. Увеличение числа не генерирует изображение уменьшенных уровней; начальные данные должны содержать требуемые байты цепочки.
SetSamplesvoid
public void SetSamples(RenderingDevice.TextureSamples pMember);Сохраняет Samples без выделения GPU-памяти и проверки готовности всей конфигурации. Число выборок MSAA на texel, изначально TextureSamples.Samples1. Это не фильтрация, не число mip-уровней и не размер текстуры. Совместимость MSAA зависит от формата, назначения и устройства; изменение поля само не выполняет resolve.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | RenderingDevice.TextureSamples | — |
pMemberЧисло выборок MSAA на texel, изначально TextureSamples.Samples1. Это не фильтрация, не число mip-уровней и не размер текстуры. Совместимость MSAA зависит от формата, назначения и устройства; изменение поля само не выполняет resolve.
SetTextureTypevoid
public void SetTextureType(RenderingDevice.TextureType pMember);Сохраняет TextureType без выделения GPU-памяти и проверки готовности всей конфигурации. Размерность и организация текстуры, изначально TextureType.Type2D. Выбирает смысл Width/Height/Depth/ArrayLayers и проверки при создании. Type3D использует Depth; массивы используют ArrayLayers. Не меняет тип уже созданного ресурса.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | RenderingDevice.TextureType | — |
pMemberРазмерность и организация текстуры, изначально TextureType.Type2D. Выбирает смысл Width/Height/Depth/ArrayLayers и проверки при создании. Type3D использует Depth; массивы используют ArrayLayers. Не меняет тип уже созданного ресурса.
SetUsageBitsvoid
public void SetUsageBits(RenderingDevice.TextureUsageBits pMember);Сохраняет UsageBits без выделения GPU-памяти и проверки готовности всей конфигурации. Назначения текстуры, изначально 0; с нулём TextureCreate отклоняет создание. Объединяйте только нужные флаги через |: SamplingBit для чтения шейдером, CanUpdateBit для TextureUpdate, CanCopyFromBit для TextureGetData. Проверяйте сочетание формата и флагов через TextureIsFormatSupportedForUsage.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | RenderingDevice.TextureUsageBits | — |
pMemberНазначения текстуры, изначально 0; с нулём TextureCreate отклоняет создание. Объединяйте только нужные флаги через |: SamplingBit для чтения шейдером, CanUpdateBit для TextureUpdate, CanCopyFromBit для TextureGetData. Проверяйте сочетание формата и флагов через TextureIsFormatSupportedForUsage.
SetWidthvoid
public void SetWidth(uint pMember);Сохраняет Width без выделения GPU-памяти и проверки готовности всей конфигурации. Ширина базового уровня в texel, изначально 1. При создании нужна величина не меньше 1 в пределах лимита устройства. Setter только сохраняет uint и не выделяет память.
| Имя | Тип | По умолчанию |
|---|---|---|
pMember | uint | — |
pMemberШирина базового уровня в texel, изначально 1. При создании нужна величина не меньше 1 в пределах лимита устройства. Setter только сохраняет uint и не выделяет память.