RDTextureFormat
Dimensions, format and usages for GPU texture creation.
RDTextureFormat describes a future RenderingDevice texture. The object itself holds no GPU image. Defaults are R8Unorm, Type2D, Width/Height/Depth/ArrayLayers/Mipmaps=1, Samples1, UsageBits=0, IsResolveBuffer=false and IsDiscardable=false. Replace the zero UsageBits: TextureCreate rejects them. A setter stores a value without establishing that the entire configuration is valid.
For a regular RGBA8 texture, supply exactly width × height × 4 bytes in RGBA order, with one data-array entry per layer. This executed helper creates one 2D layer and one base level; it neither loads an image file nor generates a mip chain:
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;
}
}Call context matters: for the main device from RenderingServer.GetRenderingDevice, invoke the helper through RenderingServer.CallOnRenderThread. That device is borrowed; do not Dispose it. The helper neither selects a thread nor creates a local device. The caller owns the returned RID: after use, call FreeRid on the same device in a valid context. Dispose your descriptors after TextureCreate; doing so does not free the created texture.
Dimensions are in texels; ArrayLayers counts layers, not 3D depth. Mipmaps includes the base level: 1 means no additional levels. Samples selects MSAA, not filtering. CanUpdateBit enables TextureUpdate; CanCopyFromBit enables TextureGetData. Synchronous readback can stall the CPU waiting for the GPU; do not use it as a routine per-frame path.
AddShareableFormat configures a list before creation: a nonempty list must include the base Format and required view formats. Being listed does not guarantee driver support. Set the view format through RDTextureView. Editing the original descriptor or the TextureGetFormat result changes neither the size nor format of an existing texture: create a new resource for another configuration and free the old one.
Creation, updates, exact raw-byte readback, descriptor independence and shared-view lifetime were checked on installed Windows/Vulkan Forward+. The Vulkan warning remains in the report. Byte readback establishes neither shader-sampling output, sRGB color conversion nor image quality. This example does not validate 3D/cube/mip/MSAA/resolve/discardable behavior or other devices.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
RDTextureFormatConstructor
public RDTextureFormat();Creates a descriptor with R8Unorm, Type2D, dimensions/layers/levels 1, Samples1, UsageBits=0 and both flags false. Allocates no GPU texture; set usages before TextureCreate. You can Dispose your own RefCounted descriptor after the creation call.
Properties11
ArrayLayersProperty
public uint ArrayLayers { get; set; }Layer count, initially 1. Applies to array and cube textures; these require at least 1 within the device limit. Cube types require a multiple of 6, with one layer per face. Ordinary nonarray types normalize it to 1.
DepthProperty
public uint Depth { get; set; }Volume-texture depth in texels, initially 1. Must be at least 1 for Type3D. Other types normalize it to 1 at creation; this is not an array-layer count.
FormatProperty
public RenderingDevice.DataFormat Format { get; set; }Texel storage format, initially DataFormat.R8Unorm: one normalized 8-bit channel. Select R8G8B8A8Unorm explicitly for RGBA8. Format determines data size and interpretation; support also depends on UsageBits and the device.
HeightProperty
public uint Height { get; set; }Base-level height in texels, initially 1. Creation requires at least 1 for 2D/3D; for 1D the device normalizes height to 1 in its descriptor copy.
IsDiscardableProperty
public bool IsDiscardable { get; set; }Permission to discard render-target contents between uses, initially false. Relevant to draw-list targets whose prior data is unnecessary. Do not use for an image that must persist; the flag promises no FPS gain on every GPU.
IsResolveBufferProperty
public bool IsResolveBuffer { get; set; }Marks a texture intended as a resolve destination, initially false. Used when arranging framebuffer/resolve operations; does not turn an MSAA source into a regular texture or execute a copy or resolve.
MipmapsProperty
public uint Mipmaps { get; set; }Level count including the base level, initially 1: no additional mip levels. Creation requires at least 1 and no more than the full chain for the dimensions. Raising the count does not generate downscaled images; initial data must contain the required chain bytes.
SamplesProperty
public RenderingDevice.TextureSamples Samples { get; set; }MSAA samples per texel, initially TextureSamples.Samples1. Not filtering, a mip-level count or texture dimensions. MSAA compatibility depends on format, usage and device; editing the field performs no resolve.
TextureTypeProperty
public RenderingDevice.TextureType TextureType { get; set; }Texture dimensionality and layout, initially TextureType.Type2D. Selects the meaning of Width/Height/Depth/ArrayLayers and creation checks. Type3D uses Depth; arrays use ArrayLayers. Changes no existing resource type.
UsageBitsProperty
public RenderingDevice.TextureUsageBits UsageBits { get; set; }Texture usages, initially 0; TextureCreate rejects zero usage. Combine required flags with |: SamplingBit for shader sampling, CanUpdateBit for TextureUpdate, CanCopyFromBit for TextureGetData. Check the format/usage combination with TextureIsFormatSupportedForUsage.
WidthProperty
public uint Width { get; set; }Base-level width in texels, initially 1. Creation requires at least 1 within the device limit. The setter only stores a uint and allocates no memory.
Methods24
AddShareableFormatvoid
public void AddShareableFormat(RenderingDevice.DataFormat format);Appends an allowed view format to the descriptor. If the list is nonempty, include the base Format and each required override before texture creation. Appending does not deduplicate entries or guarantee device format compatibility. An existing texture is unchanged.
| Name | Type | Default |
|---|---|---|
format | RenderingDevice.DataFormat | — |
formatView format to append; a nonempty list must also contain the base Format.
GetArrayLayersuint
public uint GetArrayLayers();Returns the stored descriptor value for ArrayLayers. Layer count, initially 1. Applies to array and cube textures; these require at least 1 within the device limit. Cube types require a multiple of 6, with one layer per face. Ordinary nonarray types normalize it to 1.
uintStored ArrayLayers of this descriptor, not a query of a current GPU resource.
GetDepthuint
public uint GetDepth();Returns the stored descriptor value for Depth. Volume-texture depth in texels, initially 1. Must be at least 1 for Type3D. Other types normalize it to 1 at creation; this is not an array-layer count.
uintStored Depth of this descriptor, not a query of a current GPU resource.
GetFormatRenderingDevice.DataFormat
public RenderingDevice.DataFormat GetFormat();Returns the stored descriptor value for Format. Texel storage format, initially DataFormat.R8Unorm: one normalized 8-bit channel. Select R8G8B8A8Unorm explicitly for RGBA8. Format determines data size and interpretation; support also depends on UsageBits and the device.
RenderingDevice.DataFormatStored Format of this descriptor, not a query of a current GPU resource.
GetHeightuint
public uint GetHeight();Returns the stored descriptor value for Height. Base-level height in texels, initially 1. Creation requires at least 1 for 2D/3D; for 1D the device normalizes height to 1 in its descriptor copy.
uintStored Height of this descriptor, not a query of a current GPU resource.
GetIsDiscardablebool
public bool GetIsDiscardable();Returns the stored descriptor value for IsDiscardable. Permission to discard render-target contents between uses, initially false. Relevant to draw-list targets whose prior data is unnecessary. Do not use for an image that must persist; the flag promises no FPS gain on every GPU.
boolStored IsDiscardable of this descriptor, not a query of a current GPU resource.
GetIsResolveBufferbool
public bool GetIsResolveBuffer();Returns the stored descriptor value for IsResolveBuffer. Marks a texture intended as a resolve destination, initially false. Used when arranging framebuffer/resolve operations; does not turn an MSAA source into a regular texture or execute a copy or resolve.
boolStored IsResolveBuffer of this descriptor, not a query of a current GPU resource.
GetMipmapsuint
public uint GetMipmaps();Returns the stored descriptor value for Mipmaps. Level count including the base level, initially 1: no additional mip levels. Creation requires at least 1 and no more than the full chain for the dimensions. Raising the count does not generate downscaled images; initial data must contain the required chain bytes.
uintStored Mipmaps of this descriptor, not a query of a current GPU resource.
GetSamplesRenderingDevice.TextureSamples
public RenderingDevice.TextureSamples GetSamples();Returns the stored descriptor value for Samples. MSAA samples per texel, initially TextureSamples.Samples1. Not filtering, a mip-level count or texture dimensions. MSAA compatibility depends on format, usage and device; editing the field performs no resolve.
RenderingDevice.TextureSamplesStored Samples of this descriptor, not a query of a current GPU resource.
GetTextureTypeRenderingDevice.TextureType
public RenderingDevice.TextureType GetTextureType();Returns the stored descriptor value for TextureType. Texture dimensionality and layout, initially TextureType.Type2D. Selects the meaning of Width/Height/Depth/ArrayLayers and creation checks. Type3D uses Depth; arrays use ArrayLayers. Changes no existing resource type.
RenderingDevice.TextureTypeStored TextureType of this descriptor, not a query of a current GPU resource.
GetUsageBitsRenderingDevice.TextureUsageBits
public RenderingDevice.TextureUsageBits GetUsageBits();Returns the stored descriptor value for UsageBits. Texture usages, initially 0; TextureCreate rejects zero usage. Combine required flags with |: SamplingBit for shader sampling, CanUpdateBit for TextureUpdate, CanCopyFromBit for TextureGetData. Check the format/usage combination with TextureIsFormatSupportedForUsage.
RenderingDevice.TextureUsageBitsStored UsageBits of this descriptor, not a query of a current GPU resource.
GetWidthuint
public uint GetWidth();Returns the stored descriptor value for Width. Base-level width in texels, initially 1. Creation requires at least 1 within the device limit. The setter only stores a uint and allocates no memory.
uintStored Width of this descriptor, not a query of a current GPU resource.
RemoveShareableFormatvoid
public void RemoveShareableFormat(RenderingDevice.DataFormat format);Removes one format occurrence from the descriptor list. Duplicates can leave other occurrences: the executed probe added a format twice and created its view after one removal. Does not revoke an existing GPU view.
| Name | Type | Default |
|---|---|---|
format | RenderingDevice.DataFormat | — |
formatFormat whose single occurrence is removed from the descriptor list.
SetArrayLayersvoid
public void SetArrayLayers(uint pMember);Stores ArrayLayers without GPU allocation or full-configuration validation. Layer count, initially 1. Applies to array and cube textures; these require at least 1 within the device limit. Cube types require a multiple of 6, with one layer per face. Ordinary nonarray types normalize it to 1.
| Name | Type | Default |
|---|---|---|
pMember | uint | — |
pMemberLayer count, initially 1. Applies to array and cube textures; these require at least 1 within the device limit. Cube types require a multiple of 6, with one layer per face. Ordinary nonarray types normalize it to 1.
SetDepthvoid
public void SetDepth(uint pMember);Stores Depth without GPU allocation or full-configuration validation. Volume-texture depth in texels, initially 1. Must be at least 1 for Type3D. Other types normalize it to 1 at creation; this is not an array-layer count.
| Name | Type | Default |
|---|---|---|
pMember | uint | — |
pMemberVolume-texture depth in texels, initially 1. Must be at least 1 for Type3D. Other types normalize it to 1 at creation; this is not an array-layer count.
SetFormatvoid
public void SetFormat(RenderingDevice.DataFormat pMember);Stores Format without GPU allocation or full-configuration validation. Texel storage format, initially DataFormat.R8Unorm: one normalized 8-bit channel. Select R8G8B8A8Unorm explicitly for RGBA8. Format determines data size and interpretation; support also depends on UsageBits and the device.
| Name | Type | Default |
|---|---|---|
pMember | RenderingDevice.DataFormat | — |
pMemberTexel storage format, initially DataFormat.R8Unorm: one normalized 8-bit channel. Select R8G8B8A8Unorm explicitly for RGBA8. Format determines data size and interpretation; support also depends on UsageBits and the device.
SetHeightvoid
public void SetHeight(uint pMember);Stores Height without GPU allocation or full-configuration validation. Base-level height in texels, initially 1. Creation requires at least 1 for 2D/3D; for 1D the device normalizes height to 1 in its descriptor copy.
| Name | Type | Default |
|---|---|---|
pMember | uint | — |
pMemberBase-level height in texels, initially 1. Creation requires at least 1 for 2D/3D; for 1D the device normalizes height to 1 in its descriptor copy.
SetIsDiscardablevoid
public void SetIsDiscardable(bool pMember);Stores IsDiscardable without GPU allocation or full-configuration validation. Permission to discard render-target contents between uses, initially false. Relevant to draw-list targets whose prior data is unnecessary. Do not use for an image that must persist; the flag promises no FPS gain on every GPU.
| Name | Type | Default |
|---|---|---|
pMember | bool | — |
pMemberPermission to discard render-target contents between uses, initially false. Relevant to draw-list targets whose prior data is unnecessary. Do not use for an image that must persist; the flag promises no FPS gain on every GPU.
SetIsResolveBuffervoid
public void SetIsResolveBuffer(bool pMember);Stores IsResolveBuffer without GPU allocation or full-configuration validation. Marks a texture intended as a resolve destination, initially false. Used when arranging framebuffer/resolve operations; does not turn an MSAA source into a regular texture or execute a copy or resolve.
| Name | Type | Default |
|---|---|---|
pMember | bool | — |
pMemberMarks a texture intended as a resolve destination, initially false. Used when arranging framebuffer/resolve operations; does not turn an MSAA source into a regular texture or execute a copy or resolve.
SetMipmapsvoid
public void SetMipmaps(uint pMember);Stores Mipmaps without GPU allocation or full-configuration validation. Level count including the base level, initially 1: no additional mip levels. Creation requires at least 1 and no more than the full chain for the dimensions. Raising the count does not generate downscaled images; initial data must contain the required chain bytes.
| Name | Type | Default |
|---|---|---|
pMember | uint | — |
pMemberLevel count including the base level, initially 1: no additional mip levels. Creation requires at least 1 and no more than the full chain for the dimensions. Raising the count does not generate downscaled images; initial data must contain the required chain bytes.
SetSamplesvoid
public void SetSamples(RenderingDevice.TextureSamples pMember);Stores Samples without GPU allocation or full-configuration validation. MSAA samples per texel, initially TextureSamples.Samples1. Not filtering, a mip-level count or texture dimensions. MSAA compatibility depends on format, usage and device; editing the field performs no resolve.
| Name | Type | Default |
|---|---|---|
pMember | RenderingDevice.TextureSamples | — |
pMemberMSAA samples per texel, initially TextureSamples.Samples1. Not filtering, a mip-level count or texture dimensions. MSAA compatibility depends on format, usage and device; editing the field performs no resolve.
SetTextureTypevoid
public void SetTextureType(RenderingDevice.TextureType pMember);Stores TextureType without GPU allocation or full-configuration validation. Texture dimensionality and layout, initially TextureType.Type2D. Selects the meaning of Width/Height/Depth/ArrayLayers and creation checks. Type3D uses Depth; arrays use ArrayLayers. Changes no existing resource type.
| Name | Type | Default |
|---|---|---|
pMember | RenderingDevice.TextureType | — |
pMemberTexture dimensionality and layout, initially TextureType.Type2D. Selects the meaning of Width/Height/Depth/ArrayLayers and creation checks. Type3D uses Depth; arrays use ArrayLayers. Changes no existing resource type.
SetUsageBitsvoid
public void SetUsageBits(RenderingDevice.TextureUsageBits pMember);Stores UsageBits without GPU allocation or full-configuration validation. Texture usages, initially 0; TextureCreate rejects zero usage. Combine required flags with |: SamplingBit for shader sampling, CanUpdateBit for TextureUpdate, CanCopyFromBit for TextureGetData. Check the format/usage combination with TextureIsFormatSupportedForUsage.
| Name | Type | Default |
|---|---|---|
pMember | RenderingDevice.TextureUsageBits | — |
pMemberTexture usages, initially 0; TextureCreate rejects zero usage. Combine required flags with |: SamplingBit for shader sampling, CanUpdateBit for TextureUpdate, CanCopyFromBit for TextureGetData. Check the format/usage combination with TextureIsFormatSupportedForUsage.
SetWidthvoid
public void SetWidth(uint pMember);Stores Width without GPU allocation or full-configuration validation. Base-level width in texels, initially 1. Creation requires at least 1 within the device limit. The setter only stores a uint and allocates no memory.
| Name | Type | Default |
|---|---|---|
pMember | uint | — |
pMemberBase-level width in texels, initially 1. Creation requires at least 1 within the device limit. The setter only stores a uint and allocates no memory.