Store encoded commands for the GPU to execute. More...

#include <GraphicsContext.h>

Inherits Object.

Inherited by GraphicsContextImpl, , and GraphicsContextImpl.

Public Member Functions
virtual RenderTarget *	getScreenRenderTarget () const =0
	Set the Screen Render Target object.
virtual bool	updateSurface (SurfaceHandle surface, uint32_t width, uint32_t height)
	Updates surface when the window resized or surface recretad.
virtual void	setDepthStencilState (DepthStencilState *depthStencilState)=0
	Set depthStencil status once.
virtual void	setGraphicsPipeline (GraphicsPipeline *graphicsPipeline)=0
	Sets the current render pipeline state object once.
Public Member Functions inherited from Object
void	retain ()
	Retains the ownership.
void	release ()
	Releases the ownership immediately.
Object *	autorelease ()
	Releases the ownership sometime soon automatically.
unsigned int	getReferenceCount () const
	Returns the Object's current reference count.
uint64_t	getObjectID () const noexcept
	Returns the process-local diagnostic identifier assigned at construction.
virtual	~Object ()
	Destructor.

Setters & Getters
virtual bool	beginFrame ()=0
	Indicate the begining of a frame.
virtual void	beginRenderPass (RenderTarget *renderTarget, const RenderPassDesc &desc)=0
	Begin a render pass, initial color, depth and stencil attachment.
virtual void	updateDepthStencilState (const DepthStencilDesc &desc)=0
	Update depthStencil status, improvment: for metal backend cache it.
virtual void	updatePipelineState (const RenderTarget *rt, const PipelineDesc &desc, PrimitiveType primitiveType)=0
	Update render pipeline status Building a programmable pipeline involves an expensive evaluation of GPU state.
virtual void	setViewport (int x, int y, unsigned int w, unsigned int h)=0
	Fixed-function state.
virtual void	setCullMode (CullMode mode)=0
	Fixed-function state.
virtual void	setWinding (Winding winding)=0
	Fixed-function state.
virtual void	setVertexBuffer (Buffer *buffer)=0
	Set a global buffer for all vertex shaders at the given bind point index 0.
virtual void	setIndexBuffer (Buffer *buffer)=0
	Set indexes when drawing primitives with index list @ buffer A buffer object that the device will read indexes from.
virtual void	setInstanceBuffer (Buffer *buffer)=0
	Set matrix tranform when drawing instances of the same model @ buffer A buffer object that the device will read matrices from.
virtual void	drawArrays (size_t start, size_t count, bool wireframe=false)=0
	Draw primitives without an index list.
virtual void	drawElements (IndexFormat indexType, size_t count, size_t offset, bool wireframe=false)=0
	Draw primitives with an index list.
virtual void	drawElementsInstanced (IndexFormat indexType, size_t count, size_t offset, int instanceCount, bool wireframe=false)=0
	Draw primitives with an index list instanced.
virtual void	endRenderPass ()=0
	Do some resources release.
virtual void	endFrame ()=0
	Present a drawable and commit a command buffer so it can be executed as soon as possible.
virtual void	submitCurrentFrameCommands (bool waitForCompletion)
	Submit currently encoded frame commands without presenting the default surface.
virtual void	setScissorRect (bool enabled, float x, float y, float width, float height)=0
	Fixed-function state.
virtual void	readPixels (RenderTarget *rt, std::function< void(const PixelBufferDesc &)> callback)=0
	Read pixels from the specified render target.
virtual bool	copyTexture (Texture src, Texture dst)=0
	Copies the contents of one texture resource into another texture resource.
virtual bool	copyTexture (RenderTarget src, Texture dst)=0
	Copies the rendered contents of a render target into a texture resource.
virtual bool	dispatch (const ComputeDispatchDesc &desc)
	Dispatches a compute pipeline on the graphics queue.
virtual void	setFrameBufferOnly (bool frameBufferOnly)
	This property controls whether or not the drawables' metal textures may only be used for framebuffer attachments (YES) or whether they may also be used for texture sampling and pixel read/write operations (NO).
virtual void	setStencilReferenceValue (uint32_t value)
	Update both front and back stencil reference value.
virtual uint64_t	getCompletedFenceValue () const
	Returns the last completed fence value for GPU synchronization.

Detailed Description

Store encoded commands for the GPU to execute.

A Render Context stores encoded commands until the buffer is committed for execution by the GPU

Member Function Documentation

◆ getScreenRenderTarget()

virtual RenderTarget * getScreenRenderTarget ( ) const

pure virtual

Set the Screen Render Target object.

Parameters

rt

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ updateSurface()

virtual bool updateSurface	(	SurfaceHandle	surface,
		uint32_t	width,
		uint32_t	height )

virtual

Updates surface when the window resized or surface recretad.

Parameters

surface
width
height

Returns: true; false

Reimplemented in GraphicsContextImpl, and GraphicsContextImpl.

◆ setDepthStencilState()

virtual void setDepthStencilState ( DepthStencilState * depthStencilState )

pure virtual

Set depthStencil status once.

Parameters

depthStencilState Specifies the depth and stencil status

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setGraphicsPipeline()

virtual void setGraphicsPipeline ( GraphicsPipeline * graphicsPipeline )

pure virtual

Sets the current render pipeline state object once.

Parameters

graphicsPipeline An object that contains the graphics functions and configuration state used in a render pass.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ beginRenderPass()

virtual void beginRenderPass	(	RenderTarget *	renderTarget,
		const RenderPassDesc &	desc )

pure virtual

Begin a render pass, initial color, depth and stencil attachment.

Parameters

desc	Specifies a group of render targets that hold the results of a render pass.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ updateDepthStencilState()

virtual void updateDepthStencilState ( const DepthStencilDesc & desc )

pure virtual

Update depthStencil status, improvment: for metal backend cache it.

Parameters

depthStencilState Specifies the depth and stencil status

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ updatePipelineState()

virtual void updatePipelineState	(	const RenderTarget *	rt,
		const PipelineDesc &	desc,
		PrimitiveType	primitiveType )

pure virtual

Update render pipeline status Building a programmable pipeline involves an expensive evaluation of GPU state.

So a new render pipeline object will be created only if it hasn't been created before.

Parameters

rt	Specifies the render target.
pipelineDesc	Specifies the pipeline desc.
primitiveType	The type of primitives that elements are assembled into.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setViewport()

virtual void setViewport	(	int	x,
		int	y,
		unsigned int	w,
		unsigned int	h )

pure virtual

Fixed-function state.

Parameters

x	The x coordinate of the upper-left corner of the viewport.
y	The y coordinate of the upper-left corner of the viewport.
w	The width of the viewport, in pixels.
h	The height of the viewport, in pixels.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setCullMode()

virtual void setCullMode ( CullMode mode )

pure virtual

Fixed-function state.

Parameters

mode	Controls if primitives are culled when front facing, back facing, or not culled at all.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setWinding()

virtual void setWinding ( Winding winding )

pure virtual

Fixed-function state.

Parameters

winding The winding order of front-facing primitives.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setVertexBuffer()

virtual void setVertexBuffer ( Buffer * buffer )

pure virtual

Set a global buffer for all vertex shaders at the given bind point index 0.

Parameters

buffer The vertex buffer to be setted in the buffer argument table.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setIndexBuffer()

virtual void setIndexBuffer ( Buffer * buffer )

pure virtual

Set indexes when drawing primitives with index list @ buffer A buffer object that the device will read indexes from.

@ see drawElements(PrimitiveType primitiveType, IndexFormat indexType, unsigned int count, unsigned int offset)

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setInstanceBuffer()

virtual void setInstanceBuffer ( Buffer * buffer )

pure virtual

Set matrix tranform when drawing instances of the same model @ buffer A buffer object that the device will read matrices from.

It may be null when the shader uses the instance ID and has no per-instance vertex attributes.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ drawArrays()

virtual void drawArrays	(	size_t	start,
		size_t	count,
		bool	wireframe = false )

pure virtual

Draw primitives without an index list.

Parameters

start	For each instance, the first index to draw
count	For each instance, the number of indexes to draw

See also: drawElements(PrimitiveType primitiveType, IndexFormat indexType, unsigned int count, unsigned int offset)

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ drawElements()

virtual void drawElements	(	IndexFormat	indexType,
		size_t	count,
		size_t	offset,
		bool	wireframe = false )

pure virtual

Draw primitives with an index list.

Parameters

indexType	The type if indexes, either 16 bit integer or 32 bit integer.
count	The number of indexes to read from the index buffer for each instance.
offset	Byte offset within indexBuffer to start reading indexes from.

See also: setIndexBuffer(Buffer* buffer); drawArrays(PrimitiveType primitiveType, unsigned int start, unsigned int count)

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ drawElementsInstanced()

virtual void drawElementsInstanced	(	IndexFormat	indexType,
		size_t	count,
		size_t	offset,
		int	instanceCount,
		bool	wireframe = false )

pure virtual

Draw primitives with an index list instanced.

Parameters

indexType	The type if indexes, either 16 bit integer or 32 bit integer.
count	The number of indexes to read from the index buffer for each instance.
offset	Byte offset within indexBuffer to start reading indexes from.
instance	Count of instances to draw at once.

See also: setIndexBuffer(Buffer* buffer); drawArrays(PrimitiveType primitiveType, unsigned int start, unsigned int count)

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ submitCurrentFrameCommands()

virtual void submitCurrentFrameCommands ( bool waitForCompletion )

virtual

Submit currently encoded frame commands without presenting the default surface.

External runtimes such as OpenXR call this before releasing acquired swapchain images.

Reimplemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setScissorRect()

virtual void setScissorRect	(	bool	enabled,
		float	x,
		float	y,
		float	width,
		float	height )

pure virtual

Fixed-function state.

Parameters

x,y	Specifies the lower left corner of the scissor box
wdith	Specifies the width of the scissor box
height	Specifies the height of the scissor box

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ readPixels()

virtual void readPixels	(	RenderTarget *	rt,
		std::function< void(const PixelBufferDesc &)>	callback )

pure virtual

Read pixels from the specified render target.

Parameters

rt	The render target to read pixels from.
callback	A callback invoked with the resulting pixel buffer description.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ copyTexture() [1/2]

virtual bool copyTexture	(	Texture *	src,
		Texture *	dst )

pure virtual

Copies the contents of one texture resource into another texture resource.

This operation performs a GPU-side texture copy without involving the CPU. The source and destination textures must be compatible for copying according to the underlying graphics backend requirements.

Parameters

src	Source texture to copy from.
dst	Destination texture to copy into.

Returns: true if the copy command was successfully issued; otherwise false.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ copyTexture() [2/2]

virtual bool copyTexture	(	RenderTarget *	src,
		Texture *	dst )

pure virtual

Copies the rendered contents of a render target into a texture resource.

Unlike texture-to-texture copies, this operation copies from the current render target output. The underlying implementation may use a framebuffer copy, resolve, or other backend-specific operation depending on the graphics API.

Parameters

src	Source render target.
dst	Destination texture to receive the rendered contents.

Returns: true if the copy command was successfully issued; otherwise false.

Implemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ dispatch()

virtual bool dispatch ( const ComputeDispatchDesc & desc )

virtual

Dispatches a compute pipeline on the graphics queue.

The pipeline and program state must reference the same compute program. All resources declared by that program must be bound through the program state before dispatch. The dispatch is submitted outside an active render pass; the RHI performs the required synchronization with subsequent compute and graphics accesses.

Parameters

desc	Compute pipeline, resource bindings, and workgroup counts.

Returns: true if the dispatch was accepted; otherwise false when compute is unsupported or the descriptor is invalid.

Reimplemented in GraphicsContextImpl, GraphicsContextImpl, and GraphicsContextImpl.

◆ setFrameBufferOnly()

virtual void setFrameBufferOnly ( bool frameBufferOnly )

virtual

This property controls whether or not the drawables' metal textures may only be used for framebuffer attachments (YES) or whether they may also be used for texture sampling and pixel read/write operations (NO).

Parameters

frameBufferOnly A value of YES allows CAMetalLayer to allocate the MTLTexture objects in ways that are optimized for display purposes that makes them unsuitable for sampling. The recommended value for most applications is YES.

Note: This interface is specificaly designed for metal.

◆ setStencilReferenceValue()

virtual void setStencilReferenceValue ( uint32_t value )

virtual

Update both front and back stencil reference value.

Parameters

value Specifies stencil reference value.

◆ getCompletedFenceValue()

virtual uint64_t getCompletedFenceValue ( ) const

virtual

Returns the last completed fence value for GPU synchronization.

Only modern graphics APIs such as D3D12 and Vulkan provide explicit fence value tracking. Legacy APIs (e.g., OpenGL, D3D11 without timeline semaphores) do not expose this, so the default implementation returns UINT64_MAX as a sentinel.

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

GraphicsContext.h

Public Member Functions

Setters & Getters

Detailed Description

Member Function Documentation

◆ getScreenRenderTarget()

◆ updateSurface()

◆ setDepthStencilState()

◆ setGraphicsPipeline()

◆ beginRenderPass()

◆ updateDepthStencilState()

◆ updatePipelineState()

◆ setViewport()

◆ setCullMode()

◆ setWinding()

◆ setVertexBuffer()

◆ setIndexBuffer()

◆ setInstanceBuffer()

◆ drawArrays()

◆ drawElements()

◆ drawElementsInstanced()

◆ submitCurrentFrameCommands()

◆ setScissorRect()

◆ readPixels()

◆ copyTexture() [1/2]

◆ copyTexture() [2/2]

◆ dispatch()

◆ setFrameBufferOnly()

◆ setStencilReferenceValue()

◆ getCompletedFenceValue()