Class GPUTexture

The GPU texture resource object. This class is able to create 2D/3D textures, volume textures and render targets.

GPUTexture
Assembly: FlaxEngine.dll
File: Engine/Graphics/Textures/GPUTexture.h
Syntax
public class GPUTexture : public GPUResource

Constructors

GPUTexture()

Declaration
protected GPUTexture()

Fields

_desc

Declaration
protected GPUTextureDescription _desc
Field Value
GPUTextureDescription

_isBlockCompressed

Declaration
protected bool _isBlockCompressed
Field Value
bool

_residentMipLevels

Declaration
protected int32 _residentMipLevels
Field Value
int32

_sRGB

Declaration
protected bool _sRGB
Field Value
bool

ResidentMipsChanged

Event called when texture residency gets changed. Texture Mip gets loaded into GPU memory and is ready to use.

Declaration
public Delegate<GPUTexture* > ResidentMipsChanged
Field Value
Delegate<GPUTexture >

Methods

ArraySize()

Gets number of textures in the array.

Declaration
public int32 ArraySize() const
Returns
int32

calculateMemoryUsage()

Declaration
protected uint64 calculateMemoryUsage() const
Returns
uint64

CalculateMipSize(int32 size, int32 mipLevel)

Calculates the size of a particular mip.

Declaration
public int32 CalculateMipSize(int32 size, int32 mipLevel) const
Parameters
int32 size

The size.
int32 mipLevel

The mip level.
Returns
int32

Mip size.

ComputeBufferOffset(int32 subresource, int32 rowAlign, int32 sliceAlign)

Declaration
public int32 ComputeBufferOffset(int32 subresource, int32 rowAlign, int32 sliceAlign) const
Parameters
int32 subresource

int32 rowAlign

int32 sliceAlign

Returns
int32

ComputeBufferTotalSize(int32 rowAlign, int32 sliceAlign)

Declaration
public int32 ComputeBufferTotalSize(int32 rowAlign, int32 sliceAlign) const
Parameters
int32 rowAlign

int32 sliceAlign

Returns
int32

ComputePitch(int32 mipIndex, uint32& rowPitch, uint32& slicePitch)

Computes row and slice pitch of the mip map.

Declaration
public void ComputePitch(int32 mipIndex, uint32& rowPitch, uint32& slicePitch) const
Parameters
int32 mipIndex

Index of the mip.
uint32 rowPitch

The row pitch.
uint32 slicePitch

The slice pitch.

ComputeRowPitch(int32 mipLevel, int32 rowAlign)

Declaration
public int32 ComputeRowPitch(int32 mipLevel, int32 rowAlign) const
Parameters
int32 mipLevel

int32 rowAlign

Returns
int32

ComputeSlicePitch(int32 mipLevel, int32 rowAlign)

Declaration
public int32 ComputeSlicePitch(int32 mipLevel, int32 rowAlign) const
Parameters
int32 mipLevel

int32 rowAlign

Returns
int32

ComputeSubresourceSize(int32 subresource, int32 rowAlign, int32 sliceAlign)

Declaration
public int32 ComputeSubresourceSize(int32 subresource, int32 rowAlign, int32 sliceAlign) const
Parameters
int32 subresource

int32 rowAlign

int32 sliceAlign

Returns
int32

Depth()

Gets texture depth (in texels).

Declaration
public int32 Depth() const
Returns
int32

Dimensions()

Gets texture dimensions.

Declaration
public TextureDimensions Dimensions() const
Returns
TextureDimensions

DownloadData(TextureData& result)

Downloads the texture data to be accessible from CPU. For frequent access, use staging textures, otherwise current thread will be stalled to wait for the GPU frame to copy data into staging buffer.

Declaration
public bool DownloadData(TextureData& result)
Parameters
TextureData result

The destination texture data container.
Returns
bool

True if cannot download data, otherwise false.

DownloadDataAsync(TextureData& result)

Creates GPU async task that will gather texture data from the GPU.

Declaration
public Task* DownloadDataAsync(TextureData& result)
Parameters
TextureData result

The result data.
Returns
Task

Download data task (not started yet).

Flags()

Gets flags of the texture.

Declaration
public GPUTextureFlags Flags() const
Returns
GPUTextureFlags

Format()

Gets texture data format.

Declaration
public PixelFormat Format() const
Returns
PixelFormat

GetData(int32 arrayIndex, int32 mipMapIndex, TextureMipData& data, uint32 mipRowPitch = 0)

Gets texture mipmap data (raw bytes). Can be used only with textures created with Staging flag.

Declaration
public virtual bool GetData(int32 arrayIndex, int32 mipMapIndex, TextureMipData& data, uint32 mipRowPitch = 0) = 0
Parameters
int32 arrayIndex

Array slice index.
int32 mipMapIndex

Mip map index.
TextureMipData data

Output mip data.
uint32 mipRowPitch

Output mip data row pitch to use. Use 0 to use the pitch from the internal GPU storage.
Returns
bool

True if failed, otherwise false.

GetDescription()

Gets texture description structure.

Declaration
public GPUTextureDescription GetDescription() const
Returns
GPUTextureDescription

GetMipSize(int32 mipLevelIndex, int32& mipWidth, int32& mipHeight)

Gets the texture mip map dimensions.

Declaration
public void GetMipSize(int32 mipLevelIndex, int32& mipWidth, int32& mipHeight) const
Parameters
int32 mipLevelIndex

Mip level index (zero-based where 0 is top texture surface).
int32 mipWidth

The calculated mip level width (in pixels).
int32 mipHeight

The calculated mip level height (in pixels).

GetMipSize(int32 mipLevelIndex, int32& mipWidth, int32& mipHeight, int32& mipDepth)

Gets the texture mip map dimensions.

Declaration
public void GetMipSize(int32 mipLevelIndex, int32& mipWidth, int32& mipHeight, int32& mipDepth) const
Parameters
int32 mipLevelIndex

Mip level index (zero-based where 0 is top texture surface).
int32 mipWidth

The calculated mip level width (in pixels).
int32 mipHeight

The calculated mip level height (in pixels).
int32 mipDepth

The calculated mip level depth (in pixels).

GetNativePtr()

Gets the native pointer to the underlying resource. It's a low-level platform-specific handle.

Declaration
public virtual void* GetNativePtr() const = 0
Returns
void

The pointer.

GetResidentSize(int32& width, int32& height)

Gets current texture size (uploaded to the GPU and in use).

Declaration
public void GetResidentSize(int32& width, int32& height) const
Parameters
int32 width

The current width (in pixels).
int32 height

The current height (in pixels).

GetResidentSize(int32& width, int32& height, int32& depth)

Gets current texture size (uploaded to the GPU and in use).

Declaration
public void GetResidentSize(int32& width, int32& height, int32& depth) const
Parameters
int32 width

The current width (in pixels).
int32 height

The current height (in pixels).
int32 depth

The current depth (in pixels).

GetResourceType()

Gets the GPU resource type.

Declaration
public virtual GPUResourceType GetResourceType() const final override
Returns
GPUResourceType

Overrides

HasPerMipViews()

Gets a value indicating whether this instance has per mip level views.

Declaration
public bool HasPerMipViews() const
Returns
bool

HasPerSliceViews()

Gets a value indicating whether this instance has per slice views.

Declaration
public bool HasPerSliceViews() const
Returns
bool

HasResidentMip()

Gets a value indicating whether this texture has any resided mip (data already uploaded to the GPU).

Declaration
public bool HasResidentMip() const
Returns
bool

Height()

Gets texture height (in texels).

Declaration
public int32 Height() const
Returns
int32

HighestResidentMipIndex()

Gets the index of the highest resident mip map (may be equal to MipLevels if no mip has been uploaded). Note: mip=0 is the highest (top quality).

Declaration
public int32 HighestResidentMipIndex() const
Returns
int32

Init(const GPUTextureDescription& desc)

Initializes a texture resource (allocates the GPU memory and performs the resource setup).

Declaration
public bool Init(const GPUTextureDescription& desc)
Parameters
GPUTextureDescription desc

The texture description.
Returns
bool

True if cannot create texture, otherwise false.

IsAllocated()

Gets a value indicating whether this texture has been allocated.

Declaration
public bool IsAllocated() const
Returns
bool

IsArray()

Gets a value indicating whether this instance is an array texture.

Declaration
public bool IsArray() const
Returns
bool

IsBlockCompressed()

Gets a boolean indicating whether this GPUTexture is a using a block compress format (BC1, BC2, BC3, BC4, BC5, BC6H, BC7, etc.).

Declaration
public bool IsBlockCompressed() const
Returns
bool

IsCubeMap()

Gets a value indicating whether this instance is a cubemap texture.

Declaration
public bool IsCubeMap() const
Returns
bool

IsDepthStencil()

Gets a value indicating whether this texture is a depth stencil.

Declaration
public bool IsDepthStencil() const
Returns
bool

IsMultiSample()

Gets a value indicating whether this instance is a multi sample texture.

Declaration
public bool IsMultiSample() const
Returns
bool

IsPowerOfTwo()

Returns true if texture has size that is power of two.

Declaration
public bool IsPowerOfTwo() const
Returns
bool

True if texture has size that is power of two.

IsRegularTexture()

Checks if texture is normal texture asset (not render target or unordered access or depth buffer or sth else).

Declaration
public bool IsRegularTexture() const
Returns
bool

IsRenderTarget()

Gets a value indicating whether this texture is a render target.

Declaration
public bool IsRenderTarget() const
Returns
bool

IsShaderResource()

Gets a value indicating whether this texture is a shader resource.

Declaration
public bool IsShaderResource() const
Returns
bool

IsSRGB()

Checks if texture contains sRGB colors data.

Declaration
public bool IsSRGB() const
Returns
bool

IsStaging()

Checks if texture is a staging buffer (supports direct CPU access).

Declaration
public bool IsStaging() const
Returns
bool

IsUnorderedAccess()

Gets a value indicating whether this texture is a unordered access.

Declaration
public bool IsUnorderedAccess() const
Returns
bool

IsVolume()

Gets a value indicating whether this instance is a volume texture.

Declaration
public bool IsVolume() const
Returns
bool

MipLevels()

Gets number of mipmap levels in the texture.

Declaration
public int32 MipLevels() const
Returns
int32

MultiSampleLevel()

Gets multi-sampling parameters for the texture.

Declaration
public MSAALevel MultiSampleLevel() const
Returns
MSAALevel

OnInit()

Declaration
protected virtual bool OnInit() = 0
Returns
bool

OnReleaseGPU()

Releases GPU resource data (implementation).

Declaration
protected virtual void OnReleaseGPU() override
Overrides

OnResidentMipsChanged()

Declaration
protected virtual void OnResidentMipsChanged() = 0

operator GPUTextureView* ()

Implicit conversion to the first surface (only for 2D textures).

Declaration
public operator GPUTextureView* () const
Returns
FORCE_INLINE

The view to the main texture surface.

ResidentMipLevels()

Gets the number of resident mipmap levels in the texture (already uploaded to the GPU).

Declaration
public int32 ResidentMipLevels() const
Returns
int32

Resize(int32 width, int32 height, int32 depth, PixelFormat format=PixelFormat::Unknown)

Resizes the texture. It must be created first.

Declaration
public bool Resize(int32 width, int32 height, int32 depth, PixelFormat format=PixelFormat::Unknown)
Parameters
int32 width

The width.
int32 height

The height.
int32 depth

The depth.
PixelFormat format

The new texture format. Use Unknown to remain texture format unchanged.
Returns
bool

True if fails, otherwise false.

Resize(int32 width, int32 height, PixelFormat format=PixelFormat::Unknown)

Resizes the texture. It must be created first.

Declaration
public bool Resize(int32 width, int32 height, PixelFormat format=PixelFormat::Unknown)
Parameters
int32 width

The width.
int32 height

The height.
PixelFormat format

The new texture format. Use Unknown to remain texture format unchanged.
Returns
bool

True if fails, otherwise false.

RowPitch(int32 mipIndex = 0)

Calculates mip map row pitch (in bytes).

Declaration
public uint32 RowPitch(int32 mipIndex = 0) const
Parameters
int32 mipIndex

Index of the mip.
Returns
uint32

Row pitch.

SetResidentMipLevels(int32 count)

Sets the number of resident mipmap levels in the texture (already uploaded to the GPU).

Declaration
public void SetResidentMipLevels(int32 count)
Parameters
int32 count

Size()

Gets the texture total size in pixels.

Declaration
public Float2 Size() const
Returns
Float2

Size3()

Gets the texture total size in pixels (with depth).

Declaration
public Float3 Size3() const
Returns
Float3

SlicePitch(int32 mipIndex = 0)

Calculates mip map slice pitch (in bytes).

Declaration
public uint32 SlicePitch(int32 mipIndex = 0) const
Parameters
int32 mipIndex

Index of the mip.
Returns
uint32

Slice pitch.

ToStagingReadback()

Creates new staging readback texture with the same dimensions and properties as a source texture (but without a data transferred; warning: caller must delete object).

Declaration
public GPUTexture* ToStagingReadback() const
Returns
GPUTexture

The staging readback texture.

ToStagingUpload()

Creates new staging upload texture with the same dimensions and properties as a source texture (but without a data transferred; warning: caller must delete object).

Declaration
public GPUTexture* ToStagingUpload() const
Returns
GPUTexture

The staging upload texture.

ToString()

Gets the string representation of this object.

Declaration
public virtual String ToString() const override
Returns
String

Overrides

UploadMipMapAsync(const BytesContainer& data, int32 mipIndex, bool copyData=false)

Uploads mip map data to the GPU. Creates async GPU task.

Declaration
public GPUTask* UploadMipMapAsync(const BytesContainer& data, int32 mipIndex, bool copyData=false)
Parameters
BytesContainer data

Data to upload (it must be valid for the next a few frames due to GPU latency and async works executing)
int32 mipIndex

Mip level index.
bool copyData

If true, the data will be copied to the async execution task instead of using the input pointer provided.
Returns
GPUTask

Created async task or null if cannot.

UploadMipMapAsync(const BytesContainer& data, int32 mipIndex, int32 rowPitch, int32 slicePitch, bool copyData=false)

Uploads mip map data to the GPU. Creates async GPU task.

Declaration
public GPUTask* UploadMipMapAsync(const BytesContainer& data, int32 mipIndex, int32 rowPitch, int32 slicePitch, bool copyData=false)
Parameters
BytesContainer data

Data to upload (it must be valid for the next a few frames due to GPU latency and async works executing)
int32 mipIndex

Mip level index.
int32 rowPitch

The data row pitch.
int32 slicePitch

The data slice pitch.
bool copyData

If true, the data will be copied to the async execution task instead of using the input pointer provided.
Returns
GPUTask

Created async task or null if cannot.

View()

Gets the view to the first surface (only for 2D textures).

Declaration
public GPUTextureView* View() const
Returns
GPUTextureView

The view to the main texture surface.

View(int32 arrayOrDepthIndex)

Gets the view to the surface at index in an array.

To use per depth/array slice view you need to specify the GPUTextureFlags.PerSliceViews when creating the resource.

Declaration
public virtual GPUTextureView* View(int32 arrayOrDepthIndex) const = 0
Parameters
int32 arrayOrDepthIndex

The index of the surface in an array (or depth slice index).
Returns
GPUTextureView

The view to the surface at index in an array.

View(int32 arrayOrDepthIndex, int32 mipMapIndex)

Gets the view to the mip map surface at index in an array.

To use per mip map view you need to specify the GPUTextureFlags.PerMipViews when creating the resource.

Declaration
public virtual GPUTextureView* View(int32 arrayOrDepthIndex, int32 mipMapIndex) const = 0
Parameters
int32 arrayOrDepthIndex

The index of the surface in an array (or depth slice index).
int32 mipMapIndex

Index of the mip level.
Returns
GPUTextureView

The view to the surface at index in an array.

ViewArray()

Gets the view to the array of surfaces

To use array texture view you need to create render target as an array.

Declaration
public virtual GPUTextureView* ViewArray() const = 0
Returns
GPUTextureView

The view to the array of surfaces.

ViewReadOnlyDepth()

Gets the view to the texture as read-only depth/stencil buffer. Valid only if graphics device supports it and the texture uses depth/stencil.

Declaration
public virtual GPUTextureView* ViewReadOnlyDepth() const = 0
Returns
GPUTextureView

The view to the depth-stencil resource descriptor as read-only depth.

ViewVolume()

Gets the view to the volume texture (3D).

To use volume texture view you need to create render target as a volume resource (3D texture with Depth> 1).

Declaration
public virtual GPUTextureView* ViewVolume() const = 0
Returns
GPUTextureView

The view to the volume texture.

Width()

Gets texture width (in texels).

Declaration
public int32 Width() const
Returns
int32