Diligent::DynamicTextureArray Class Reference

#include <DynamicTextureArray.hpp>

Public Member Functions
	DynamicTextureArray (IRenderDevice *pDevice, const DynamicTextureArrayCreateInfo &CreateInfo)
	Initializes the dynamic texture array.
ITexture *	Resize (IRenderDevice *pDevice, IDeviceContext *pContext, Uint32 NewArraySize, bool DiscardContent=false)
	Resizes the texture array to the specified number of slices.
ITexture *	Update (IRenderDevice *pDevice, IDeviceContext *pContext)
	Updates the internal texture object.
ITexture *	GetTexture () const
	Returns a pointer to the texture object.
ITextureView *	GetTextureSRV (TEXTURE_FORMAT ViewFormat) const
	Returns a shader resource view of the internal texture in the specified format.
bool	PendingUpdate () const
TextureDesc	GetDesc () const
Uint32	GetArraySize () const noexcept
Uint32	GetVersion () const
	Returns dynamic texture version.
Uint64	GetMemoryUsage () const

Detailed Description

Dynamically resizable texture 2D array

Remarks

GetDesc(), GetArraySize(), GetVersion(), and GetMemoryUsage() are thread-safe and may be called from worker threads. If these methods race with Update() or Resize(), the returned value is a snapshot and may become stale immediately.

All other methods are not thread-safe and must be externally synchronized: they must not race with each other or with Update() or Resize().

Sparse arrays require exactly one immediate context in TextureDesc::ImmediateContextMask. The context used by Resize() or Update() must be that context and support sparse binding.

Constructor & Destructor Documentation

DynamicTextureArray()

Diligent::DynamicTextureArray::DynamicTextureArray	(	IRenderDevice *	pDevice,
		const DynamicTextureArrayCreateInfo &	CreateInfo )

Initializes the dynamic texture array.

Parameters

[in]	pDevice	- Render device that will be used to create the texture array. This parameter may be null (see remarks).
[in]	CreateInfo	- Texture array create information, see Diligent::DynamicTextureArrayCreateInfo.

If pDevice is null, internal texture creation will be postponed until Update() or Resize() is called.

Member Function Documentation

GetArraySize()

Uint32 Diligent::DynamicTextureArray::GetArraySize ( ) const

inlinenoexcept

Returns the current number of slices in the texture array.

For a sparse texture, this is the committed page-aligned resident capacity and may be greater than the size passed to Resize().

Remarks

The method is thread-safe and may be called from worker threads. If it races with Update() or Resize(), the returned value may become stale immediately.

GetDesc()

TextureDesc Diligent::DynamicTextureArray::GetDesc ( ) const

inline

Returns a snapshot of the texture description.

Remarks

The method is thread-safe and may be called from worker threads. If it races with Update() or Resize(), the returned value may become stale immediately.

GetMemoryUsage()

Uint64 Diligent::DynamicTextureArray::GetMemoryUsage

(

)

const

Returns the amount of memory currently used by the dynamic array, in bytes.

Remarks

The method is thread-safe and may be called from worker threads. If it races with Update() or Resize(), the returned value may become stale immediately.

GetTexture()

ITexture * Diligent::DynamicTextureArray::GetTexture ( ) const

inline

Returns a pointer to the texture object.

If the texture has not be initialized, the method returns null.

If the texture may need to be updated (initialized or resized), use the Update() method.

Remarks

The method is not thread-safe and must not race with other methods that may update the texture array.

GetTextureSRV()

ITextureView * Diligent::DynamicTextureArray::GetTextureSRV

(

TEXTURE_FORMAT

ViewFormat

)

const

Returns a shader resource view of the internal texture in the specified format.

The array returns the default SRV and, when typed texture views are supported, an additional sRGB SRV for compatible typeless formats. If the requested view is not available, the method returns null.

The method does not create a view and must not race with Update() or Resize().

GetVersion()

Uint32 Diligent::DynamicTextureArray::GetVersion ( ) const

inline

Returns dynamic texture version.

The version is incremented every time a new internal texture is created.

Remarks

The method is thread-safe and may be called from worker threads. If it races with Update() or Resize(), the returned value may become stale immediately.

PendingUpdate()

bool Diligent::DynamicTextureArray::PendingUpdate ( ) const

inline

Returns true if the texture must be updated before use (e.g. it has been resized, but internal texture has not been initialized or updated). When update is not pending, Update() may be called with null device and context.

Remarks

The method is not thread-safe and must not race with other methods that may update the texture array.

Resize()

ITexture * Diligent::DynamicTextureArray::Resize	(	IRenderDevice *	pDevice,
		IDeviceContext *	pContext,
		Uint32	NewArraySize,
		bool	DiscardContent = false )

Resizes the texture array to the specified number of slices.

Parameters

[in]	pDevice	- Render device that will be used create new internal texture. This parameter may be null (see remarks).
[in]	pContext	- Device context that will be used to copy existing contents to the new texture (when using non-sparse texture), or commit new memory tiles (when using sparse texture). This parameter may be null (see remarks).
[in]	NewArraySize	- The new number of slices in the texture array.
[in]	DiscardContent	- Whether to discard previous texture content (for non-sparse textures).

Returns

Pointer to the current usable texture object. If replacement creation is deferred or fails, this is the committed texture.

The method operation depends on which of pDevice and pContext parameters are not null:

• Both pDevice and pContext are not null: internal texture is created (if necessary) and existing contents is copied (for non-sparse textures). Update() may be called with both pDevice and pContext being null.
• pDevice is not null, pContext is null: internal texture or additional memory pages are created, but existing contents is not copied and memory tiles are not bound. An application must provide non-null device context when calling Update().
• Both pDevice and pContext are null: internal texture or memory pages are not created. An application must provide non-null device and device context when calling Update().

Typically pContext is null when the method is called from a worker thread.

For a sparse texture, NewArraySize is rounded up to a multiple of DynamicTextureArrayCreateInfo::NumSlicesInMemoryPage. GetArraySize() reports this committed page-aligned resident capacity.

A content-preserving default resize keeps the committed texture and its views usable until replacement texture creation succeeds.

After a replacement default texture has been created and its content copy is pending, the method may only be called with the same NewArraySize, for example to provide a context that was previously unavailable. Before the replacement is created, the pending request may be retargeted or cancelled.

If NewArraySize is zero, internal buffer will be released.

Update()

ITexture * Diligent::DynamicTextureArray::Update	(	IRenderDevice *	pDevice,
		IDeviceContext *	pContext )

Updates the internal texture object.

Parameters

[in]	pDevice	- Render device that will be used to create a new texture, if necessary (see remarks).
[in]	pContext	- Device context that will be used to copy existing texture contents (when using non-sparse texture), or bind memory tiles (when using sparse textures), if necessary (see remarks).

Returns

A pointer to the texture object.

If the texture has been resized, but internal texture object has not been initialized, pDevice and pContext must not be null.

If the texture does not need to be updated (PendingUpdate() returns false), both pDevice and pContext may be null.