LLGL::RenderSystem Class Reference

Render system interface. More...

#include <RenderSystem.h>

Inheritance diagram for LLGL::RenderSystem:

Public Member Functions
	~RenderSystem ()
	Releases the internal data.
int	GetRendererID () const
	Rendering API identification number.
const char *	GetName () const
	Returns the name of this render system, e.g. "Direct3D 12".
const RendererInfo &	GetRendererInfo ()
	Returns basic renderer information.
const RenderingCapabilities &	GetRenderingCaps ()
	Returns the rendering capabilities.
const Report *	GetReport () const
	Returns a pointer to the report or null if there is none.
virtual SwapChain *	CreateSwapChain (const SwapChainDescriptor &swapChainDesc, const std::shared_ptr< Surface > &surface={})=0
	Creates a new swap-chain. At least one swap-chain is required to render into an output surface.
virtual void	Release (SwapChain &swapChain)=0
	Releases the specified swap-chain. After this call, the specified object must no longer be used.
virtual CommandQueue *	GetCommandQueue ()=0
	Returns the single instance of the command queue.
virtual CommandBuffer *	CreateCommandBuffer (const CommandBufferDescriptor &commandBufferDesc={})=0
	Creates a new command buffer.
virtual void	Release (CommandBuffer &commandBuffer)=0
	Releases the specified command buffer. After this call, the specified object must no longer be used.
virtual Buffer *	CreateBuffer (const BufferDescriptor &bufferDesc, const void *initialData=nullptr)=0
	Creates a new generic hardware buffer.
virtual BufferArray *	CreateBufferArray (ArrayView< VertexBufferView > bufferViews)=0
	Creates a new buffer array.
virtual void	Release (Buffer &buffer)=0
	Releases the specified buffer object. After this call, the specified object must no longer be used.
virtual void	Release (BufferArray &bufferArray)=0
	Releases the specified buffer array object. After this call, the specified object must no longer be used.
virtual void	WriteBuffer (Buffer &buffer, std::uint64_t offset, const void *data, std::uint64_t dataSize)=0
	Updates the data of the specified buffer.
virtual void	ReadBuffer (Buffer &buffer, std::uint64_t offset, void *data, std::uint64_t dataSize)=0
	Reads the data from the specified buffer.
virtual void *	MapBuffer (Buffer &buffer, const CPUAccess access)=0
	Maps the specified buffer from GPU to CPU memory space.
virtual void *	MapBuffer (Buffer &buffer, const CPUAccess access, std::uint64_t offset, std::uint64_t length)=0
	Maps the specified buffer range from GPU to CPU memory space.
virtual void	UnmapBuffer (Buffer &buffer)=0
	Unmaps the specified buffer.
virtual Texture *	CreateTexture (const TextureDescriptor &textureDesc, const ImageView *initialImage=nullptr)=0
	Creates a new texture.
virtual void	Release (Texture &texture)=0
	Releases the specified texture object. After this call, the specified object must no longer be used.
virtual void	WriteTexture (Texture &texture, const TextureRegion &textureRegion, const ImageView &srcImageView)=0
	Updates the image data of the specified texture.
virtual void	ReadTexture (Texture &texture, const TextureRegion &textureRegion, const MutableImageView &dstImageView)=0
	Reads the image data from the specified texture.
virtual Sampler *	CreateSampler (const SamplerDescriptor &samplerDesc)=0
	Creates a new Sampler object.
virtual void	Release (Sampler &sampler)=0
	Releases the specified Sampler object. After this call, the specified object must no longer be used.
virtual ResourceHeap *	CreateResourceHeap (const ResourceHeapDescriptor &resourceHeapDesc, ArrayView< ResourceViewDescriptor > initialResourceViews={})=0
	Creates a new resource heap.
virtual void	Release (ResourceHeap &resourceHeap)=0
	Releases the specified ResourceHeap object. After this call, the specified object must no longer be used.
virtual std::uint32_t	WriteResourceHeap (ResourceHeap &resourceHeap, std::uint32_t firstDescriptor, ArrayView< ResourceViewDescriptor > resourceViews)=0
	Writes new resource view descriptors into the specified resource heap.
virtual RenderPass *	CreateRenderPass (const RenderPassDescriptor &renderPassDesc)=0
	Creates a new RenderPass object.
virtual void	Release (RenderPass &renderPass)=0
	Releases the specified RenderPass object. After this call, the specified object must no longer be used.
virtual RenderTarget *	CreateRenderTarget (const RenderTargetDescriptor &renderTargetDesc)=0
	Creates a new RenderTarget object.
virtual void	Release (RenderTarget &renderTarget)=0
	Releases the specified RenderTarget object. After this call, the specified object must no longer be used.
virtual Shader *	CreateShader (const ShaderDescriptor &shaderDesc)=0
	Creates a new and Shader object and compiles the specified source.
virtual void	Release (Shader &shader)=0
	Releases the specified Shader object. After this call, the specified object must no longer be used.
virtual PipelineLayout *	CreatePipelineLayout (const PipelineLayoutDescriptor &pipelineLayoutDesc)=0
	Creates a new and initialized pipeline layout object, if and only if the renderer supports pipeline layouts.
virtual void	Release (PipelineLayout &pipelineLayout)=0
	Releases the specified PipelineLayout object. After this call, the specified object must no longer be used.
virtual PipelineCache *	CreatePipelineCache (const Blob &initialBlob={})=0
	Creates a new pipeline cache with optional initial data.
virtual void	Release (PipelineCache &pipelineCache)=0
	Releases the specified PipelineCache object. After this call, the specified object must no longer be used.
virtual PipelineState *	CreatePipelineState (const GraphicsPipelineDescriptor &pipelineStateDesc, PipelineCache *pipelineCache=nullptr)=0
	Creates a new graphics pipeline state object (PSO).
virtual PipelineState *	CreatePipelineState (const ComputePipelineDescriptor &pipelineStateDesc, PipelineCache *pipelineCache=nullptr)=0
	Creates a new compute pipeline state object (PSO).
virtual PipelineState *	CreatePipelineState (const MeshPipelineDescriptor &pipelineStateDesc, PipelineCache *pipelineCache=nullptr)=0
	Creates a new mesh pipeline state object (PSO) if supported.
virtual void	Release (PipelineState &pipelineState)=0
	Releases the specified PipelineState object. After this call, the specified object must no longer be used.
virtual QueryHeap *	CreateQueryHeap (const QueryHeapDescriptor &queryHeapDesc)=0
	Creates a new query heap.
virtual void	Release (QueryHeap &queryHeap)=0
	Releases the specified QueryHeap object. After this call, the specified object must no longer be used.
virtual Fence *	CreateFence ()=0
	Creates a new fence (used for CPU/GPU synchronization).
virtual void	Release (Fence &fence)=0
	Releases the specified Fence object. After this call, the specified object must no longer be used.
virtual bool	GetNativeHandle (void *nativeHandle, std::size_t nativeHandleSize)=0
	Returns the native device handle.
Public Member Functions inherited from LLGL::Interface
virtual bool	IsInstanceOf (int id) const
	Returns true if this object is an instance of the specified interface.
Public Member Functions inherited from LLGL::NonCopyable
	NonCopyable (const NonCopyable &)=delete
NonCopyable &	operator= (const NonCopyable &)=delete
virtual	~NonCopyable ()=default

Static Public Member Functions
static std::vector< std::string >	FindModules ()
	Returns the list of all available render system modules for the current platform.
static RenderSystemPtr	Load (const RenderSystemDescriptor &renderSystemDesc, Report *report=nullptr)
	Loads a new render system from the specified module.
static void	Unload (RenderSystemPtr &&renderSystem)
	Unloads the specified render system and the internal module.

Protected Member Functions
	RenderSystem ()
	Allocates the internal data.
Report &	GetMutableReport ()
	Returns the internal report of this render system to be modified by the renderer implementation.
void	Errorf (const char *format,...)
	Prints a formatted string and replaces the current render system report with it as error.
virtual bool	QueryRendererDetails (RendererInfo *outInfo, RenderingCapabilities *outCaps)=0
	Queries the renderer information and capabilities.
Protected Member Functions inherited from LLGL::NonCopyable
	NonCopyable ()=default

Static Protected Member Functions
static void	AssertCreateBuffer (const BufferDescriptor &bufferDesc, std::uint64_t maxSize)
	Validates the specified buffer descriptor to be used for buffer creation.
static void	AssertCreateShader (const ShaderDescriptor &shaderDesc)
	Validates the specified shader descriptor.

Detailed Description

Render system interface.

Remarks

This is the main interface for the entire renderer. It manages the ownership of all graphics objects and is used to create, modify, and delete all those objects. The main functions for most graphics objects are Create*, Write*, Read*, Map*, Unmap*, and Release:

// Create and initialize vertex buffer
LLGL::BufferDescriptor bufferDesc;
//fill descriptor ...
auto vertexBuffer = renderSystem->CreateBuffer(*buffer, bufferDesc, initialData);
 
// Modify data
renderSystem->WriteBuffer(*buffer, modificationData, ...);
 
// Release object
renderSystem->Release(*buffer);

Constructor & Destructor Documentation

~RenderSystem()

LLGL::RenderSystem::~RenderSystem

(

)

Releases the internal data.

RenderSystem()

LLGL::RenderSystem::RenderSystem ( )

protected

Allocates the internal data.

Member Function Documentation

AssertCreateBuffer()

void LLGL::RenderSystem::AssertCreateBuffer ( const BufferDescriptor & bufferDesc, std::uint64_t maxSize )

staticprotected

Validates the specified buffer descriptor to be used for buffer creation.

AssertCreateShader()

void LLGL::RenderSystem::AssertCreateShader ( const ShaderDescriptor & shaderDesc )

staticprotected

Validates the specified shader descriptor.

CreateBuffer()

virtual Buffer * LLGL::RenderSystem::CreateBuffer ( const BufferDescriptor & bufferDesc, const void * initialData = nullptr )

pure virtual

Creates a new generic hardware buffer.

Parameters

[in]	bufferDesc	Specifies the buffer descriptor.
[in]	initialData	Optional raw pointer to the data with which the buffer is to be initialized. This may also be null, to only initialize the size of the buffer. In this case, the buffer must be initialized with the "WriteBuffer" function before it is used for drawing operations. By default null.

See also

WriteBuffer

CreateBufferArray()

virtual BufferArray * LLGL::RenderSystem::CreateBufferArray ( ArrayView< VertexBufferView > bufferViews )

pure virtual

Creates a new buffer array.

Parameters

[in]

bufferViews

Array of vertex buffer buffer views with optional strides and offsets.

Remarks

All buffers within this array must have the same binding flags. The buffers inside this array must persist as long as this buffer array is used, and the individual buffers are still required to read and write its data from and to the GPU.

See also

BufferDescriptor::bindFlags

RenderingLimits::maxVertexBufferInputs

CreateCommandBuffer()

virtual CommandBuffer * LLGL::RenderSystem::CreateCommandBuffer ( const CommandBufferDescriptor & commandBufferDesc = {} )

pure virtual

Creates a new command buffer.

Parameters

[in]

commandBufferDesc

Specifies an optional command buffer descriptor.

Remarks

Each render system can create multiple command buffers, but especially the legacy graphics APIs such as OpenGL and Direct3D 11 don't provide a performance benefit with that feature.

CreateFence()

virtual Fence * LLGL::RenderSystem::CreateFence ( )

pure virtual

Creates a new fence (used for CPU/GPU synchronization).

See also

CommandBuffer::SubmitFence

CommandBuffer::WaitFence

CreatePipelineCache()

virtual PipelineCache * LLGL::RenderSystem::CreatePipelineCache ( const Blob & initialBlob = {} )

pure virtual

Creates a new pipeline cache with optional initial data.

Parameters

[in]

initialBlob

Specifies an optional blob to initialize the pipeline cache. If no initial blob is provided, the pipeline cache will be initialized the first time it is used to create a PSO. If the backend does not support pipeline caching, the initial blob may be ignored and the pipeline cache cannot be used to store arbitrary blobs of data.

Remarks

Backends that do not support pipeline caching might be using only a single pipeline cache object with a reference counter, in which case the return value might always point to the same instance.

See also

CreatePipelineState

CreatePipelineLayout()

virtual PipelineLayout * LLGL::RenderSystem::CreatePipelineLayout ( const PipelineLayoutDescriptor & pipelineLayoutDesc )

pure virtual

Creates a new and initialized pipeline layout object, if and only if the renderer supports pipeline layouts.

Parameters

[in]

pipelineLayoutDesc

Specifies the pipeline layout descriptor with all layout bindings.

Remarks

A pipeline layout is required in combination with a ResourceHeap to bind multiple resources at once. For modern graphics APIs (i.e. Direct3D 12 and Vulkan), this is only way to bind shader resources. For legacy graphics APIs (i.e. Direct3D 11 and OpenGL), shader resources can also be bound individually with the extended command buffer.

Returns

Pointer to the new PipelineLayout object or null if the renderer does not support pipeline layouts.

See also

CreateResourceHeap

Parse

CreatePipelineState() [1/3]

virtual PipelineState * LLGL::RenderSystem::CreatePipelineState ( const ComputePipelineDescriptor & pipelineStateDesc, PipelineCache * pipelineCache = nullptr )

pure virtual

Creates a new compute pipeline state object (PSO).

Parameters

[in]	pipelineStateDesc	Specifies the compute PSO descriptor. This will describe the entire pipeline state. The computeShader member of the descriptor must never be null!
[out]	pipelineCache	Optional pointer to pipeline cache.

See also

ComputePipelineDescriptor

CreatePipelineCache

CreatePipelineState() [2/3]

virtual PipelineState * LLGL::RenderSystem::CreatePipelineState ( const GraphicsPipelineDescriptor & pipelineStateDesc, PipelineCache * pipelineCache = nullptr )

pure virtual

Creates a new graphics pipeline state object (PSO).

Parameters

[in]	pipelineStateDesc	Specifies the graphics PSO descriptor. This will describe the entire pipeline state, i.e. the blending-, rasterizer-, depth-, stencil- and shader states. The vertexShader member of the descriptor must never be null!
[out]	pipelineCache	Optional pointer to pipeline cache.

See also

GraphicsPipelineDescriptor

CreatePipelineCache

CreatePipelineState() [3/3]

virtual PipelineState * LLGL::RenderSystem::CreatePipelineState ( const MeshPipelineDescriptor & pipelineStateDesc, PipelineCache * pipelineCache = nullptr )

pure virtual

Creates a new mesh pipeline state object (PSO) if supported.

Returns

Pointer to the new mesh pipeline or null if mesh shaders are not supported.

Parameters

[in]	pipelineStateDesc	Specifies the mesh PSO descriptor. The meshShader member of the descriptor must never be null!
[out]	pipelineCache	Optional pointer to pipeline cache.

See also

MeshPipelineDescriptor

CreatePipelineCache

RenderingFeatures::hasMeshShaders

CreateQueryHeap()

virtual QueryHeap * LLGL::RenderSystem::CreateQueryHeap ( const QueryHeapDescriptor & queryHeapDesc )

pure virtual

Creates a new query heap.

CreateRenderPass()

virtual RenderPass * LLGL::RenderSystem::CreateRenderPass ( const RenderPassDescriptor & renderPassDesc )

pure virtual

Creates a new RenderPass object.

Returns

Pointer to the new RenderPass object or null if the render system does not use render passes. In the case of the latter, null pointers are allowed for render passes.

See also

RenderTargetDescriptor::renderPass

GraphicsPipelineDescriptor::renderPass

CommandBuffer::BeginRenderPass

CommandBuffer::EndRenderPass

CreateRenderTarget()

virtual RenderTarget * LLGL::RenderSystem::CreateRenderTarget ( const RenderTargetDescriptor & renderTargetDesc )

pure virtual

Creates a new RenderTarget object.

Remarks

Use render targets to render into a texture instead of a swap-chain (i.e. the screen).

CreateResourceHeap()

virtual ResourceHeap * LLGL::RenderSystem::CreateResourceHeap ( const ResourceHeapDescriptor & resourceHeapDesc, ArrayView< ResourceViewDescriptor > initialResourceViews = {} )

pure virtual

Creates a new resource heap.

Parameters

[in]	resourceHeapDesc	Specifies the descriptor for the resource heap. If the numResourceViews field is zero, the initialResourceViews parameter will determine the number of resources, it must not be empty and it must be a multiple of the number of bindings in the pipeline layout.
[in]	initialResourceViews	Specifies an optional array of initial resource views. If this is non-null, the array pointed to must have enough elements to initialize the entire resource heap. Uninitialized resource views must be written with a call to WriteResourceHeap before the resource heap can be used in a command buffer.

Remarks

Resource heaps are used in combination with a pipeline layout. The pipeline layout determines to which binding points the resources are bound.

See also

CreatePipelineLayout

CommandBuffer::SetResourceHeap

WriteResourceHeap

ResourceHeapDescriptor::numResourceViews

CreateSampler()

virtual Sampler * LLGL::RenderSystem::CreateSampler ( const SamplerDescriptor & samplerDesc )

pure virtual

Creates a new Sampler object.

Remarks

Samplers (aka. sampler states) define how to sample texture resources in shaders.

See also

GetRenderingCaps

CreateShader()

virtual Shader * LLGL::RenderSystem::CreateShader ( const ShaderDescriptor & shaderDesc )

pure virtual

Creates a new and Shader object and compiles the specified source.

Remarks

To check whether the compilation was successful or not, use the HasErrors and GetReport functions of the Shader interface.

See also

Shader::HasErrors

Shader::GetReport

ShaderDescriptor

ShaderDescFromFile

CreateSwapChain()

virtual SwapChain * LLGL::RenderSystem::CreateSwapChain ( const SwapChainDescriptor & swapChainDesc, const std::shared_ptr< Surface > & surface = {} )

pure virtual

Creates a new swap-chain. At least one swap-chain is required to render into an output surface.

Parameters

[in]	swapChainDesc	Specifies the swap-chain descriptor, which contains resolution, bit depth, multi-sampling settings etc.
[in]	surface	Optional shared pointer to a surface for the swap-chain. If this is null, the swap-chain will create its own platform specific surface, which can be accessed by SwapChain::GetSurface. The default surface on desktop platforms (i.e. Window interface) is not shown automatically, i.e. the Window::Show function has to be invoked to show the surface.

See also

SwapChain::GetSurface

Window::Show

CreateTexture()

virtual Texture * LLGL::RenderSystem::CreateTexture ( const TextureDescriptor & textureDesc, const ImageView * initialImage = nullptr )

pure virtual

Creates a new texture.

Parameters

[in]	textureDesc	Specifies the texture descriptor.
[in]	initialImage	Optional pointer to an image view that provides the initial image data. If this is null, the texture will be initialized with the currently configured default image color (if this feature is enabled). If this is non-null, it is used to initialize the texture data. This parameter will be ignored if the texture type is a multi-sampled texture (i.e. TextureType::Texture2DMS or TextureType::Texture2DMSArray).

See also

WriteTexture

Errorf()

void LLGL::RenderSystem::Errorf ( const char * format, ... )

protected

Prints a formatted string and replaces the current render system report with it as error.

Remarks

This can be used to log non-fatal errors so the client programmer can query the last error message.

See also

Report::Errorf

FindModules()

std::vector< std::string > LLGL::RenderSystem::FindModules ( )

static

Returns the list of all available render system modules for the current platform.

Remarks

For example, on Win32 this might be { "Direct3D12", "Direct3D11", "OpenGL" }, but on MacOS it might be { "Metal", "OpenGL" }.

GetCommandQueue()

virtual CommandQueue * LLGL::RenderSystem::GetCommandQueue ( )

pure virtual

Returns the single instance of the command queue.

GetMutableReport()

Report & LLGL::RenderSystem::GetMutableReport ( )

protected

Returns the internal report of this render system to be modified by the renderer implementation.

GetName()

const char * LLGL::RenderSystem::GetName

(

)

const

Returns the name of this render system, e.g. "Direct3D 12".

GetNativeHandle()

virtual bool LLGL::RenderSystem::GetNativeHandle ( void * nativeHandle, std::size_t nativeHandleSize )

pure virtual

Returns the native device handle.

Parameters

[out]	nativeHandle	Raw pointer to the backend specific structure to store the native handle. Obtain the respective structure from #include <LLGL/Backend/BACKEND/NativeHandle.h> where BACKEND must be either Direct3D12, Direct3D11, Vulkan, Metal, or OpenGL.
[in]	nativeHandleSize	Specifies the size (in bytes) of the native handle structure for robustness. This must be sizeof(STRUCT) where STRUCT is the respective backend specific structure such as LLGL::Direct3D12::RenderSystemNativeHandle.

Returns

True if the native handle was successfully retrieved. Otherwise, nativeHandleSize specifies an incompatible structure size.

Remarks

For the Direct3D backends, all retrieved COM pointers will be incremented and the user is responsible for releasing those pointers, i.e. a call to IUnknown::Release is required to each of the objects returned by this function.

For the Metal backend, all retrieved NSObject instances will have their retain counter incremented and the user is responsible for releasing those objects, i.e. a call to -(oneway void)release is required to each of the objects returned by this function.

For backends that do not support this function, the return value is false unless nativeHandle is null or nativeHandleSize is 0.

Example for obtaining the native handle of a Direct3D12 render system:

#include <LLGL/Backend/Direct3D12/NativeHandle.h>
//...
LLGL::Direct3D12::RenderSystemNativeHandle d3dNativeHandle;
myRenderer->GetNativeHandle(&d3dNativeHandle, sizeof(d3dNativeHandle));
ID3D12Device* d3dDevice = d3dNativeHandle.device;
...
d3dDevice->Release();

See also

Direct3D12::RenderSystemNativeHandle

Direct3D11::RenderSystemNativeHandle

Vulkan::RenderSystemNativeHandle

Metal::RenderSystemNativeHandle

OpenGL::RenderSystemNativeHandle

GetRendererID()

int LLGL::RenderSystem::GetRendererID

(

)

const

Rendering API identification number.

Remarks

This can be a value of the RendererID entries. Since the render system is modular, a new render system can have its own ID number.

See also

RendererID

GetRendererInfo()

const RendererInfo & LLGL::RenderSystem::GetRendererInfo

(

)

Returns basic renderer information.

Remarks

This is not a constant member function because the first call invokes the query, while subsequent calls return the cached information.

GetRenderingCaps()

const RenderingCapabilities & LLGL::RenderSystem::GetRenderingCaps

(

)

Returns the rendering capabilities.

Remarks

This is not a constant member function because the first call invokes the query, while subsequent calls return the cached information.

GetReport()

const Report * LLGL::RenderSystem::GetReport

(

)

const

Returns a pointer to the report or null if there is none.

Remarks

If there is a report, it indicates errors from a previous operation, similar to ::GetLastError() from the Windows API.

See also

Report

Load()

RenderSystemPtr LLGL::RenderSystem::Load ( const RenderSystemDescriptor & renderSystemDesc, Report * report = nullptr )

static

Loads a new render system from the specified module.

Parameters

[in]	renderSystemDesc	Specifies the render system descriptor structure. The 'moduleName' member of this structure must not be empty.
[out]	report	Optional pointer to a report on potential failure of loading the specified module.

Remarks

If loading the specified module failed, the return value is null and the reason for failure is reported in report if it's a valid pointer.

The descriptor structure can be initialized by only the module name like shown in the following example:

// Load the "OpenGL" render system module
LLGL::RenderSystemPtr myRenderSystem = LLGL::RenderSystem::Load("OpenGL");

The debugger and profiler can be used like this:

// Forward all log reports to the standard output stream for errors
LLGL::Log::RegisterCallbackStd();
 
// Declare profiler and debugger (these classes can also be extended)
LLGL::RenderingDebugger myDebugger;
 
// Load the "Direct3D11" render system module
LLGL::RenderSystemDescriptor myRendererDesc;
{
    myRendererDesc.moduleName   = "Direct3D11";
    myRendererDesc.debugger     = &myDebugger;
}
LLGL::RenderSystemPtr myRenderSystem = LLGL::RenderSystem::Load(myRendererDesc);

See also

RenderSystemDescriptor::moduleName

MapBuffer() [1/2]

virtual void * LLGL::RenderSystem::MapBuffer ( Buffer & buffer, const CPUAccess access )

pure virtual

Maps the specified buffer from GPU to CPU memory space.

Parameters

[in]	buffer	Specifies the buffer which is to be mapped. Depending on the CPU access type (see access parameter), this buffer must have been created with the corresponding CPU access flag, i.e. CPUAccessFlags::Read and/or CPUAccessFlags::Write.
[in]	access	Specifies the CPU buffer access requirement, i.e. if the CPU can read and/or write the mapped memory.

Returns

Raw pointer to the mapped memory block in CPU memory space or null if the operation failed.

Remarks

Memory that is written back from CPU to GPU becomes visible in the GPU after a corresponding UnmapBuffer operation.

See also

UnmapBuffer

MapBuffer() [2/2]

virtual void * LLGL::RenderSystem::MapBuffer ( Buffer & buffer, const CPUAccess access, std::uint64_t offset, std::uint64_t length )

pure virtual

Maps the specified buffer range from GPU to CPU memory space.

Parameters

[in]	buffer	Specifies the buffer which is to be mapped. Depending on the CPU access type (see access parameter), this buffer must have been created with the corresponding CPU access flag, i.e. CPUAccessFlags::Read and/or CPUAccessFlags::Write.
[in]	access	Specifies the CPU buffer access requirement, i.e. if the CPU can read and/or write the mapped memory.
[in]	offset	Specifies the memory offset (in bytes) from the GPU buffer.
[in]	length	Specifies the length of the memory block (in bytes) that is to be mapped.

Returns

Raw pointer to the mapped memory block in CPU memory space or null if the operation failed.

Remarks

Memory that is written back from CPU to GPU becomes visible in the GPU after a corresponding UnmapBuffer operation.

See also

UnmapBuffer

QueryRendererDetails()

virtual bool LLGL::RenderSystem::QueryRendererDetails ( RendererInfo * outInfo, RenderingCapabilities * outCaps )

protectedpure virtual

Queries the renderer information and capabilities.

Parameters

[out]	outInfo	Specifies the output parameter for the renderer info. This may be null.
[out]	outCaps	Specifies the output parameter for the renderer capabilities. This may be null.

Remarks

This function may be called separately for both the information and capabilities query.

Returns

True on success. Otherwise, the backend is not ready yet to provide the requested details.

ReadBuffer()

virtual void LLGL::RenderSystem::ReadBuffer ( Buffer & buffer, std::uint64_t offset, void * data, std::uint64_t dataSize )

pure virtual

Reads the data from the specified buffer.

Parameters

[in]	buffer	Specifies the buffer which is to be read.
[in]	offset	Specifies the offset (in bytes) at which the buffer is to be read.
[out]	data	Raw pointer to a memory block in CPU memory space where the data will be written to.
[in]	dataSize	Specifies the size (in bytes) of the data block given by the data parameter.

See also

WriteBuffer

ReadTexture()

virtual void LLGL::RenderSystem::ReadTexture ( Texture & texture, const TextureRegion & textureRegion, const MutableImageView & dstImageView )

pure virtual

Reads the image data from the specified texture.

Parameters

[in]	texture	Specifies the texture object to read from.
[in]	textureRegion	Specifies the region where the texture data is to be read.
[out]	dstImageView	Specifies the destination image view to write the texture data to.

Remarks

The required size for a successful texture read operation depends on the image format, data type, and texture size. The Texture::GetDesc or Texture::GetMipExtent functions can be used to determine the texture dimensions.

// Query texture size attribute
auto myTextureExtent = myTexture->GetMipExtent(0);
 
// Allocate image buffer with elements in all dimensions
std::vector<std::uint8_t> myImage(myTextureExtent.width * myTextureExtent.height * myTextureExtent.depth * 4);
 
// Initialize destination image descriptor
const MutableImageView myImageView {
    LLGL::ImageFormat::RGBA,                // RGBA image format, since the size of 'myImage' is a multiple of 4
    LLGL::DataType::UInt8,                  // 8-bit unsigned integral data type: <std::uint8_t> or <unsigned char>
    myImage.data(),                         // Output image buffer
    myImage.size() * sizeof(std::uint8_t)   // Image buffer size: number of color elements and size of each color element
};
 
// Read texture data from first MIP-map level (index 0)
myRenderSystem->ReadTexture(*myTexture, 0, myImageView);

Note

The behavior is undefined if dstImageView.data points to an invalid buffer, or dstImageView.data points to a buffer that is smaller than specified by dstImageView.dataSize, or dstImageView.dataSize is less than the required size.

Exceptions

std::invalid_argument

If dstImageView.data is null.

See also

Texture::GetDesc

Texture::GetMipExtent

Release() [1/15]

virtual void LLGL::RenderSystem::Release ( Buffer & buffer )

pure virtual

Releases the specified buffer object. After this call, the specified object must no longer be used.

Release() [2/15]

virtual void LLGL::RenderSystem::Release ( BufferArray & bufferArray )

pure virtual

Releases the specified buffer array object. After this call, the specified object must no longer be used.

Release() [3/15]

virtual void LLGL::RenderSystem::Release ( CommandBuffer & commandBuffer )

pure virtual

Releases the specified command buffer. After this call, the specified object must no longer be used.

See also

CreateCommandBuffer

Release() [4/15]

virtual void LLGL::RenderSystem::Release ( Fence & fence )

pure virtual

Releases the specified Fence object. After this call, the specified object must no longer be used.

Release() [5/15]

virtual void LLGL::RenderSystem::Release ( PipelineCache & pipelineCache )

pure virtual

Releases the specified PipelineCache object. After this call, the specified object must no longer be used.

Remarks

Backends that do not support pipeline caching might be using only a single pipeline cache object with a reference counter, in which case releasing such object will only decrement its internal counter and only delete the object until this counter reaches zero.

Release() [6/15]

virtual void LLGL::RenderSystem::Release ( PipelineLayout & pipelineLayout )

pure virtual

Releases the specified PipelineLayout object. After this call, the specified object must no longer be used.

Release() [7/15]

virtual void LLGL::RenderSystem::Release ( PipelineState & pipelineState )

pure virtual

Releases the specified PipelineState object. After this call, the specified object must no longer be used.

Release() [8/15]

virtual void LLGL::RenderSystem::Release ( QueryHeap & queryHeap )

pure virtual

Releases the specified QueryHeap object. After this call, the specified object must no longer be used.

Release() [9/15]

virtual void LLGL::RenderSystem::Release ( RenderPass & renderPass )

pure virtual

Releases the specified RenderPass object. After this call, the specified object must no longer be used.

Release() [10/15]

virtual void LLGL::RenderSystem::Release ( RenderTarget & renderTarget )

pure virtual

Releases the specified RenderTarget object. After this call, the specified object must no longer be used.

Release() [11/15]

virtual void LLGL::RenderSystem::Release ( ResourceHeap & resourceHeap )

pure virtual

Releases the specified ResourceHeap object. After this call, the specified object must no longer be used.

Release() [12/15]

virtual void LLGL::RenderSystem::Release ( Sampler & sampler )

pure virtual

Releases the specified Sampler object. After this call, the specified object must no longer be used.

Release() [13/15]

virtual void LLGL::RenderSystem::Release ( Shader & shader )

pure virtual

Releases the specified Shader object. After this call, the specified object must no longer be used.

Release() [14/15]

virtual void LLGL::RenderSystem::Release ( SwapChain & swapChain )

pure virtual

Releases the specified swap-chain. After this call, the specified object must no longer be used.

See also

CreateSwapChain

Release() [15/15]

virtual void LLGL::RenderSystem::Release ( Texture & texture )

pure virtual

Releases the specified texture object. After this call, the specified object must no longer be used.

Unload()

void LLGL::RenderSystem::Unload ( RenderSystemPtr && renderSystem )

static

Unloads the specified render system and the internal module.

Remarks

After this call, the specified render system and all the objects associated to it must no longer be used!

UnmapBuffer()

virtual void LLGL::RenderSystem::UnmapBuffer ( Buffer & buffer )

pure virtual

Unmaps the specified buffer.

Remarks

This must be called on a buffer that was previously mapped into CPU memory space. The following example illustrates how to map and unmap a buffer from GPU into CPU memory space:

if (void* data = myRenderer->MapBuffer(*myBuffer, LLGL::CPUAccess::Write))
{
    // Write to 'data' ...
    myRenderer->UnmapBuffer(*myBuffer);
}

See also

MapBuffer

WriteBuffer()

virtual void LLGL::RenderSystem::WriteBuffer ( Buffer & buffer, std::uint64_t offset, const void * data, std::uint64_t dataSize )

pure virtual

Updates the data of the specified buffer.

Parameters

[in]	buffer	Specifies the destination buffer whose data is to be updated.
[in]	offset	Specifies the offset (in bytes) at which the buffer is to be updated. This offset plus the data block size (i.e. offset + dataSize) must be less than or equal to the size of the buffer.
[in]	data	Raw pointer to the data with which the buffer is to be updated. This must not be null!
[in]	dataSize	Specifies the size (in bytes) of the data block which is to be updated. This must be less then or equal to the size of the buffer.

Remarks

This function, just like any other write operation from the RenderSystem, should not be interleaved with command buffer recording in which these resources are used, unless they are carefully organized to not override their content during such command recordings. This is because even an immediate context does not guarantee that any command is submitted to the GPU until the end of recording (i.e. CommandBuffer::End). To update buffers during command recording, use CommandBuffer::UpdateBuffer.

See also

ReadBuffer

WriteResourceHeap()

virtual std::uint32_t LLGL::RenderSystem::WriteResourceHeap ( ResourceHeap & resourceHeap, std::uint32_t firstDescriptor, ArrayView< ResourceViewDescriptor > resourceViews )

pure virtual

Writes new resource view descriptors into the specified resource heap.

Parameters

[in]	resourceHeap	Specifies the resource heap that is to be updated.
[in]	firstDescriptor	Zero-based index to the first descriptor that is to be updated. This must be less than the number of bindings in the resource heap's pipeline layout (PipelineLayout::GetNumHeapBindings) multiplied by the number of descriptor sets in the resource heap (ResourceHeap::GetNumDescriptorSets).
[in]	resourceViews	Array of resource view descriptors.

Remarks

The type of a resource view, i.e. whether it's a buffer, texture, or sampler, must not be changed with this function.

This function, just like any other write operation from the RenderSystem, should not be interleaved with command buffer recording in which these resources are used, unless they are carefully organized to not override their content during such command recordings. This is because even an immediate context does not guarantee that any command is submitted to the GPU until the end of recording (i.e. CommandBuffer::End). To swap out resources during command recording, use CommandBuffer::SetResource with individual bindings or write descriptors to unique sets within the heap.

Returns

Number of resource views that have been updated by this call. Any resource view descriptor with a resource field that is null will be ignored silently.

See also

ResourceHeap::GetNumDescriptorSets

PipelineLayout::GetNumHeapBindings

CommandBuffer::SetResourceHeap

WriteTexture()

virtual void LLGL::RenderSystem::WriteTexture ( Texture & texture, const TextureRegion & textureRegion, const ImageView & srcImageView )

pure virtual

Updates the image data of the specified texture.

Parameters

[in]	texture	Specifies the texture whose data is to be updated.
[in]	textureRegion	Specifies the region where the texture is to be updated. The field TextureRegion::numMipLevels must be 1.
[in]	srcImageView	Specifies the source image view. Its data member must not be null!

Remarks

This function cannot be used with multi-sample textures, i.e. textures of type TextureType::Texture2DMS or TextureType::Texture2DMSArray.

This function, just like any other write operation from the RenderSystem, should not be interleaved with command buffer recording in which these resources are used, unless they are carefully organized to not override their content during such command recordings. This is because even an immediate context does not guarantee that any command is submitted to the GPU until the end of recording (i.e. CommandBuffer::End). If texture data needs to be updated from the CPU during command recording, update a buffer via CommandBuffer::UpdateBuffer and then copy that buffer region into the texture via CommandBuffer::CopyTextureFromBuffer.

---

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

• RenderSystem.h