The plRenderDevice class is the primary interface for interactions with rendering APIs It contains a set of (non-virtual) functions to set state, create resources etc. which rely on API specific implementations provided by protected virtual functions. Redundant state changes are prevented at the platform independent level in the non-virtual functions. More...

#include <Device.h>

Inheritance diagram for plGALDevice:

[legend]

Classes
struct	DeadObject

Public Types
using	SwapChainFactoryFunction = plDelegate<plGALSwapChain(plAllocator)>

Public Member Functions
plResult	Init ()

plResult	Shutdown ()

plStringView	GetRenderer ()

plGALCommandEncoder *	BeginCommands (const char *szName)
	Begin recording GPU commands on the returned command encoder.

void	EndCommands (plGALCommandEncoder *pCommandEncoder)
	Stop recording commands on the command encoder.

plGALBlendStateHandle	CreateBlendState (const plGALBlendStateCreationDescription &description)

void	DestroyBlendState (plGALBlendStateHandle hBlendState)

plGALDepthStencilStateHandle	CreateDepthStencilState (const plGALDepthStencilStateCreationDescription &description)

void	DestroyDepthStencilState (plGALDepthStencilStateHandle hDepthStencilState)

plGALRasterizerStateHandle	CreateRasterizerState (const plGALRasterizerStateCreationDescription &description)

void	DestroyRasterizerState (plGALRasterizerStateHandle hRasterizerState)

plGALSamplerStateHandle	CreateSamplerState (const plGALSamplerStateCreationDescription &description)

void	DestroySamplerState (plGALSamplerStateHandle hSamplerState)

plGALShaderHandle	CreateShader (const plGALShaderCreationDescription &description)

void	DestroyShader (plGALShaderHandle hShader)

plGALBufferHandle	CreateBuffer (const plGALBufferCreationDescription &description, plArrayPtr< const plUInt8 > initialData=plArrayPtr< const plUInt8 >())

void	DestroyBuffer (plGALBufferHandle hBuffer)

plGALBufferHandle	CreateVertexBuffer (plUInt32 uiVertexSize, plUInt32 uiVertexCount, plArrayPtr< const plUInt8 > initialData=plArrayPtr< const plUInt8 >(), bool bDataIsMutable=false)

plGALBufferHandle	CreateIndexBuffer (plGALIndexType::Enum indexType, plUInt32 uiIndexCount, plArrayPtr< const plUInt8 > initialData=plArrayPtr< const plUInt8 >(), bool bDataIsMutable=false)

plGALBufferHandle	CreateConstantBuffer (plUInt32 uiBufferSize)

plGALTextureHandle	CreateTexture (const plGALTextureCreationDescription &description, plArrayPtr< plGALSystemMemoryDescription > initialData=plArrayPtr< plGALSystemMemoryDescription >())

void	DestroyTexture (plGALTextureHandle hTexture)

plGALTextureHandle	CreateProxyTexture (plGALTextureHandle hParentTexture, plUInt32 uiSlice)

void	DestroyProxyTexture (plGALTextureHandle hProxyTexture)

plGALTextureHandle	CreateSharedTexture (const plGALTextureCreationDescription &description, plArrayPtr< plGALSystemMemoryDescription > initialData={})

plGALTextureHandle	OpenSharedTexture (const plGALTextureCreationDescription &description, plGALPlatformSharedHandle hSharedHandle)

void	DestroySharedTexture (plGALTextureHandle hTexture)

plGALTextureResourceViewHandle	GetDefaultResourceView (plGALTextureHandle hTexture)

plGALBufferResourceViewHandle	GetDefaultResourceView (plGALBufferHandle hBuffer)

plGALTextureResourceViewHandle	CreateResourceView (const plGALTextureResourceViewCreationDescription &description)

void	DestroyResourceView (plGALTextureResourceViewHandle hResourceView)

plGALBufferResourceViewHandle	CreateResourceView (const plGALBufferResourceViewCreationDescription &description)

void	DestroyResourceView (plGALBufferResourceViewHandle hResourceView)

plGALRenderTargetViewHandle	GetDefaultRenderTargetView (plGALTextureHandle hTexture)

plGALRenderTargetViewHandle	CreateRenderTargetView (const plGALRenderTargetViewCreationDescription &description)

void	DestroyRenderTargetView (plGALRenderTargetViewHandle hRenderTargetView)

plGALTextureUnorderedAccessViewHandle	CreateUnorderedAccessView (const plGALTextureUnorderedAccessViewCreationDescription &description)

void	DestroyUnorderedAccessView (plGALTextureUnorderedAccessViewHandle hUnorderedAccessView)

plGALBufferUnorderedAccessViewHandle	CreateUnorderedAccessView (const plGALBufferUnorderedAccessViewCreationDescription &description)

void	DestroyUnorderedAccessView (plGALBufferUnorderedAccessViewHandle hUnorderedAccessView)

plGALSwapChainHandle	CreateSwapChain (const SwapChainFactoryFunction &func)

plResult	UpdateSwapChain (plGALSwapChainHandle hSwapChain, plEnum< plGALPresentMode > newPresentMode)

void	DestroySwapChain (plGALSwapChainHandle hSwapChain)

plGALVertexDeclarationHandle	CreateVertexDeclaration (const plGALVertexDeclarationCreationDescription &description)

void	DestroyVertexDeclaration (plGALVertexDeclarationHandle hVertexDeclaration)

plEnum< plGALAsyncResult >	GetTimestampResult (plGALTimestampHandle hTimestamp, plTime &out_result)
	Queries the result of a timestamp. Should be called every frame until plGALAsyncResult::Ready is returned.

plEnum< plGALAsyncResult >	GetOcclusionQueryResult (plGALOcclusionHandle hOcclusion, plUInt64 &out_uiResult)

plEnum< plGALAsyncResult >	GetFenceResult (plGALFenceHandle hFence, plTime timeout=plTime::MakeZero())

plGALTextureHandle	GetBackBufferTextureFromSwapChain (plGALSwapChainHandle hSwapChain)

void	EnqueueFrameSwapChain (plGALSwapChainHandle hSwapChain)
	Adds a swap-chain to be used for the next frame. Must be called before or during the plGALDeviceEvent::BeforeBeginFrame event (BeginFrame function) and repeated for every frame the swap-chain is to be used. This approach guarantees that all swap-chains of a frame acquire and present at the same time, which improves frame pacing.

void	BeginFrame (const plUInt64 uiAppFrame=0)
	Begins rendering of a frame. This needs to be called first before any rendering function can be called.

void	EndFrame ()
	Ends rendering of a frame and submits all data to the GPU. No further rendering calls are allowed until BeginFrame is called again.

plUInt64	GetCurrentFrame () const
	The current rendering frame. This is a monotonically increasing number which changes +1 every time EndFrame is called. You can use this to synchronize read/writes between CPU and GPU, see GetSafeFrame.

plUInt64	GetSafeFrame () const
	The latest frame that has been fully executed on the GPU. Whenever you execute any work that requires synchronization between CPU and GPU, remember the GetCurrentFrame result in which the operation was done. When GetSafeFrame reaches this number, you know for sure that the GPU has completed all operations of that frame.

const plGALDeviceCreationDescription *	GetDescription () const

const plGALSwapChain *	GetSwapChain (plGALSwapChainHandle hSwapChain) const

template<typename T >
const T *	GetSwapChain (plGALSwapChainHandle hSwapChain) const

const plGALShader *	GetShader (plGALShaderHandle hShader) const

const plGALTexture *	GetTexture (plGALTextureHandle hTexture) const

virtual const plGALSharedTexture *	GetSharedTexture (plGALTextureHandle hTexture) const =0

const plGALBuffer *	GetBuffer (plGALBufferHandle hBuffer) const

const plGALDepthStencilState *	GetDepthStencilState (plGALDepthStencilStateHandle hDepthStencilState) const

const plGALBlendState *	GetBlendState (plGALBlendStateHandle hBlendState) const

const plGALRasterizerState *	GetRasterizerState (plGALRasterizerStateHandle hRasterizerState) const

const plGALVertexDeclaration *	GetVertexDeclaration (plGALVertexDeclarationHandle hVertexDeclaration) const

const plGALSamplerState *	GetSamplerState (plGALSamplerStateHandle hSamplerState) const

const plGALTextureResourceView *	GetResourceView (plGALTextureResourceViewHandle hResourceView) const

const plGALBufferResourceView *	GetResourceView (plGALBufferResourceViewHandle hResourceView) const

const plGALRenderTargetView *	GetRenderTargetView (plGALRenderTargetViewHandle hRenderTargetView) const

const plGALTextureUnorderedAccessView *	GetUnorderedAccessView (plGALTextureUnorderedAccessViewHandle hUnorderedAccessView) const

const plGALBufferUnorderedAccessView *	GetUnorderedAccessView (plGALBufferUnorderedAccessViewHandle hUnorderedAccessView) const

const plGALDeviceCapabilities &	GetCapabilities () const

virtual plUInt64	GetMemoryConsumptionForTexture (const plGALTextureCreationDescription &description) const

virtual plUInt64	GetMemoryConsumptionForBuffer (const plGALBufferCreationDescription &description) const

void	Flush ()

void	WaitIdle ()
	Waits for the GPU to be idle and destroys any pending resources and GPU objects.

plAllocator *	GetAllocator ()
	Internal: Returns the allocator used by the device.

template<typename IdTableType , typename ReturnType >
PL_ALWAYS_INLINE ReturnType *	Get (typename IdTableType::TypeOfId hHandle, const IdTableType &IdTable) const

template<typename HandleType >
PL_FORCE_INLINE void	AddDeadObject (plUInt32 uiType, HandleType handle)

Static Public Member Functions
static void	SetDefaultDevice (plGALDevice *pDefaultDevice)

static plGALDevice *	GetDefaultDevice ()

static bool	HasDefaultDevice ()

Public Attributes
plMutex	m_Mutex

Static Public Attributes
static plEvent< const plGALDeviceEvent & >	s_Events

Protected Types
using	ShaderTable = plIdTable<plGALShaderHandle::IdType, plGALShader*, plLocalAllocatorWrapper>

using	BlendStateTable = plIdTable<plGALBlendStateHandle::IdType, plGALBlendState*, plLocalAllocatorWrapper>

using	DepthStencilStateTable = plIdTable<plGALDepthStencilStateHandle::IdType, plGALDepthStencilState*, plLocalAllocatorWrapper>

using	RasterizerStateTable = plIdTable<plGALRasterizerStateHandle::IdType, plGALRasterizerState*, plLocalAllocatorWrapper>

using	BufferTable = plIdTable<plGALBufferHandle::IdType, plGALBuffer*, plLocalAllocatorWrapper>

using	TextureTable = plIdTable<plGALTextureHandle::IdType, plGALTexture*, plLocalAllocatorWrapper>

using	TextureResourceViewTable = plIdTable<plGALTextureResourceViewHandle::IdType, plGALTextureResourceView*, plLocalAllocatorWrapper>

using	BufferResourceViewTable = plIdTable<plGALBufferResourceViewHandle::IdType, plGALBufferResourceView*, plLocalAllocatorWrapper>

using	SamplerStateTable = plIdTable<plGALSamplerStateHandle::IdType, plGALSamplerState*, plLocalAllocatorWrapper>

using	RenderTargetViewTable = plIdTable<plGALRenderTargetViewHandle::IdType, plGALRenderTargetView*, plLocalAllocatorWrapper>

using	TextureUnorderedAccessViewTable = plIdTable<plGALTextureUnorderedAccessViewHandle::IdType, plGALTextureUnorderedAccessView*, plLocalAllocatorWrapper>

using	BufferUnorderedAccessViewTable = plIdTable<plGALBufferUnorderedAccessViewHandle::IdType, plGALBufferUnorderedAccessView*, plLocalAllocatorWrapper>

using	SwapChainTable = plIdTable<plGALSwapChainHandle::IdType, plGALSwapChain*, plLocalAllocatorWrapper>

using	VertexDeclarationTable = plIdTable<plGALVertexDeclarationHandle::IdType, plGALVertexDeclaration*, plLocalAllocatorWrapper>

Protected Member Functions
	plGALDevice (const plGALDeviceCreationDescription &Description)

template<typename IdTableType , typename ReturnType >
ReturnType *	Get (typename IdTableType::TypeOfId hHandle, const IdTableType &IdTable) const

void	DestroyViews (plGALTexture *pResource)

void	DestroyViews (plGALBuffer *pResource)

template<typename HandleType >
void	AddDeadObject (plUInt32 uiType, HandleType handle)

template<typename HandleType >
void	ReviveDeadObject (plUInt32 uiType, HandleType handle)

void	DestroyDeadObjects ()

void	VerifyMultithreadedAccess () const
	Asserts that either this device supports multi-threaded resource creation, or that this function is executed on the main thread.

const plGALSwapChain *	GetSwapChainInternal (plGALSwapChainHandle hSwapChain, const plRTTI *pRequestedType) const

plGALTextureHandle	FinalizeTextureInternal (const plGALTextureCreationDescription &desc, plGALTexture *pTexture)

plGALBufferHandle	FinalizeBufferInternal (const plGALBufferCreationDescription &desc, plGALBuffer *pBuffer)

Protected Attributes
plProxyAllocator	m_Allocator

plLocalAllocatorWrapper	m_AllocatorWrapper

ShaderTable	m_Shaders

BlendStateTable	m_BlendStates

DepthStencilStateTable	m_DepthStencilStates

RasterizerStateTable	m_RasterizerStates

BufferTable	m_Buffers

TextureTable	m_Textures

TextureResourceViewTable	m_TextureResourceViews

BufferResourceViewTable	m_BufferResourceViews

SamplerStateTable	m_SamplerStates

RenderTargetViewTable	m_RenderTargetViews

TextureUnorderedAccessViewTable	m_TextureUnorderedAccessViews

BufferUnorderedAccessViewTable	m_BufferUnorderedAccessViews

SwapChainTable	m_SwapChains

VertexDeclarationTable	m_VertexDeclarations

plHashTable< plUInt32, plGALBlendStateHandle, plHashHelper< plUInt32 >, plLocalAllocatorWrapper >	m_BlendStateTable

plHashTable< plUInt32, plGALDepthStencilStateHandle, plHashHelper< plUInt32 >, plLocalAllocatorWrapper >	m_DepthStencilStateTable

plHashTable< plUInt32, plGALRasterizerStateHandle, plHashHelper< plUInt32 >, plLocalAllocatorWrapper >	m_RasterizerStateTable

plHashTable< plUInt32, plGALSamplerStateHandle, plHashHelper< plUInt32 >, plLocalAllocatorWrapper >	m_SamplerStateTable

plHashTable< plUInt32, plGALVertexDeclarationHandle, plHashHelper< plUInt32 >, plLocalAllocatorWrapper >	m_VertexDeclarationTable

plDynamicArray< DeadObject, plLocalAllocatorWrapper >	m_DeadObjects

plGALDeviceCreationDescription	m_Description

plGALDeviceCapabilities	m_Capabilities

Detailed Description

The plRenderDevice class is the primary interface for interactions with rendering APIs It contains a set of (non-virtual) functions to set state, create resources etc. which rely on API specific implementations provided by protected virtual functions. Redundant state changes are prevented at the platform independent level in the non-virtual functions.

Member Function Documentation

◆ BeginFrame()

void plGALDevice::BeginFrame ( const plUInt64 uiAppFrame = 0 )

Begins rendering of a frame. This needs to be called first before any rendering function can be called.

Parameters

uiAppFrame Frame index for debugging purposes, has no effect on GetCurrentFrame.

◆ CreateBuffer()

plGALBufferHandle plGALDevice::CreateBuffer	(	const plGALBufferCreationDescription &	description,
		plArrayPtr< const plUInt8 >	initialData = plArrayPtr<const plUInt8>() )

Todo: Platform independent validation (buffer type supported)

◆ CreateRenderTargetView()

plGALRenderTargetViewHandle plGALDevice::CreateRenderTargetView ( const plGALRenderTargetViewCreationDescription & description )

Todo: Platform independent validation

◆ CreateSamplerState()

plGALSamplerStateHandle plGALDevice::CreateSamplerState ( const plGALSamplerStateCreationDescription & description )

Todo: Platform independent validation

◆ CreateSharedTexture()

plGALTextureHandle plGALDevice::CreateSharedTexture	(	const plGALTextureCreationDescription &	description,
		plArrayPtr< plGALSystemMemoryDescription >	initialData = {} )

Todo: Platform independent validation (desc width & height < platform maximum, format, etc.)

◆ CreateTexture()

plGALTextureHandle plGALDevice::CreateTexture	(	const plGALTextureCreationDescription &	description,
		plArrayPtr< plGALSystemMemoryDescription >	initialData = plArrayPtr<plGALSystemMemoryDescription>() )

Todo: Platform independent validation (desc width & height < platform maximum, format, etc.)

◆ CreateVertexDeclaration()

plGALVertexDeclarationHandle plGALDevice::CreateVertexDeclaration ( const plGALVertexDeclarationCreationDescription & description )

Todo: Platform independent validation

◆ EndCommands()

void plGALDevice::EndCommands ( plGALCommandEncoder * pCommandEncoder )

Stop recording commands on the command encoder.

Parameters

pCommandEncoder Must match the command encoder returned by BeginCommands.

◆ EnqueueFrameSwapChain()

void plGALDevice::EnqueueFrameSwapChain ( plGALSwapChainHandle hSwapChain )

Adds a swap-chain to be used for the next frame. Must be called before or during the plGALDeviceEvent::BeforeBeginFrame event (BeginFrame function) and repeated for every frame the swap-chain is to be used. This approach guarantees that all swap-chains of a frame acquire and present at the same time, which improves frame pacing.

Parameters

hSwapChain Swap-chain used in this frame. The device will ensure to acquire an image from the swap-chain during BeginFrame and present it when calling EndFrame.

◆ GetBackBufferTextureFromSwapChain()

plGALTextureHandle plGALDevice::GetBackBufferTextureFromSwapChain ( plGALSwapChainHandle hSwapChain )

Todo: Map functions to save on memcpys

◆ GetCurrentFrame()

PL_ALWAYS_INLINE plUInt64 plGALDevice::GetCurrentFrame ( ) const

The current rendering frame. This is a monotonically increasing number which changes +1 every time EndFrame is called. You can use this to synchronize read/writes between CPU and GPU, see GetSafeFrame.

See also: GetSafeFrame

◆ GetFenceResult()

PL_ALWAYS_INLINE plEnum< plGALAsyncResult > plGALDevice::GetFenceResult	(	plGALFenceHandle	hFence,
		plTime	timeout = plTime::MakeZero() )

\briefQueries the result of a fence. Fences can never expire as they are just monotonically increasing numbers over time.

Parameters

hFence	The fence handle to query.
timeout	If set to > 0, the function will block until the fence is ready or the timeout is reached.

Returns: Returns either Ready or Pending.

See also: plCommandEncoder::InsertFence

◆ GetOcclusionQueryResult()

PL_ALWAYS_INLINE plEnum< plGALAsyncResult > plGALDevice::GetOcclusionQueryResult	(	plGALOcclusionHandle	hOcclusion,
		plUInt64 &	out_uiResult )

\briefQueries the result of an occlusion query. Should be called every frame until plGALAsyncResult::Ready is returned.

Parameters

hOcclusion	The occlusion query handle to query.
out_uiResult	If plGALAsyncResult::Ready is returned, this will be the number of pixels of the occlusion query.

Returns: If plGALAsyncResult::Expired is returned, the result was in a ready state for more than 4 frames and was thus deleted.

See also: plCommandEncoder::BeginOcclusionQuery, plCommandEncoder::EndOcclusionQuery

◆ GetSafeFrame()

PL_ALWAYS_INLINE plUInt64 plGALDevice::GetSafeFrame ( ) const

The latest frame that has been fully executed on the GPU. Whenever you execute any work that requires synchronization between CPU and GPU, remember the GetCurrentFrame result in which the operation was done. When GetSafeFrame reaches this number, you know for sure that the GPU has completed all operations of that frame.

See also: GetCurrentFrame

◆ GetTimestampResult()

PL_ALWAYS_INLINE plEnum< plGALAsyncResult > plGALDevice::GetTimestampResult	(	plGALTimestampHandle	hTimestamp,
		plTime &	out_result )

Queries the result of a timestamp. Should be called every frame until plGALAsyncResult::Ready is returned.

Parameters

hTimestamp	The timestamp handle to query.
out_result	If plGALAsyncResult::Ready is returned, this will be the timestamp at which this handle was inserted into the command encoder.

Returns: If plGALAsyncResult::Expired is returned, the result was in a ready state for more than 4 frames and was thus deleted.

See also: plCommandEncoder::InsertTimestamp

The documentation for this class was generated from the following files:

Code/Engine/RendererFoundation/Device/Device.h
Code/Engine/RendererFoundation/Device/Implementation/Device.cpp
Code/Engine/RendererFoundation/Device/Implementation/Device_inl.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ BeginFrame()

◆ CreateBuffer()

◆ CreateRenderTargetView()

◆ CreateSamplerState()

◆ CreateSharedTexture()

◆ CreateTexture()

◆ CreateVertexDeclaration()

◆ EndCommands()

◆ EnqueueFrameSwapChain()

◆ GetBackBufferTextureFromSwapChain()

◆ GetCurrentFrame()

◆ GetFenceResult()

◆ GetOcclusionQueryResult()

◆ GetSafeFrame()

◆ GetTimestampResult()