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

#include <GraphicsContextMTL.h>

Public Member Functions
Constructor, Destructor and Initializers
	GraphicsContextImpl (GraphicsDeviceImpl *driver, SurfaceHandle surface)
RenderTarget *	getScreenRenderTarget () const override
	Set the Screen Render Target object.
bool	updateSurface (SurfaceHandle surface, uint32_t width, uint32_t height) override
	Updates surface when the window resized or surface recretad.
void	setDepthStencilState (DepthStencilState *depthStencilState) override
	Set depthStencil status.
void	setGraphicsPipeline (GraphicsPipeline *graphicsPipeline) override
	Sets the current render pipeline state object once.
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.
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
bool	beginFrame () override
	Indicate the begining of a frame Wait until the inflight command buffer has completed its work.
void	beginRenderPass (RenderTarget *renderTarget, const RenderPassDesc &descriptor) override
	Create a MTLRenderCommandEncoder object for graphics rendering to an attachment in a RenderPassDesc.
void	updateDepthStencilState (const DepthStencilDesc &descriptor) override
	Update depthStencil status, improvment: for metal backend cache it.
void	updatePipelineState (const RenderTarget *rt, const PipelineDesc &desc, PrimitiveType primitiveType) override
	Update render pipeline status Building a programmable pipeline involves an expensive evaluation of GPU state.
void	setViewport (int x, int y, unsigned int w, unsigned int h) override
	Fixed-function state.
void	setCullMode (CullMode mode) override
	Fixed-function state.
void	setWinding (Winding winding) override
	Fixed-function state.
void	setVertexBuffer (Buffer *buffer) override
	Set a global buffer for all vertex shaders at the given bind point index 0.
void	setIndexBuffer (Buffer *buffer) override
	Set indexes when drawing primitives with index list @ buffer A buffer object that the device will read indexes from.
void	setInstanceBuffer (Buffer *buffer) override
	Set matrix tranform when drawing instances of the same model @ buffer A buffer object that the device will read matrices from.
void	drawArrays (size_t start, size_t count, bool wireframe) override
	Draw primitives without an index list.
void	drawElements (IndexFormat indexType, size_t count, size_t offset, bool wireframe) override
	Draw primitives with an index list.
void	drawElementsInstanced (IndexFormat indexType, size_t count, size_t offset, int instanceCount, bool wireframe=false) override
	Draw primitives with an index list instanced.
void	endRenderPass () override
	Do some resources release.
void	endFrame () override
	Present a drawable and commit a command buffer so it can be executed as soon as possible.
void	submitCurrentFrameCommands (bool waitForCompletion) override
	Submit currently encoded frame commands without presenting the default surface.
void	setScissorRect (bool enabled, float x, float y, float width, float height) override
	Fixed-function state.
void	readPixels (RenderTarget *rt, std::function< void(const PixelBufferDesc &)> callback) override
	Read pixels from the specified render target.
bool	copyTexture (RenderTarget src, Texture dst) override
	Copies the rendered contents of a render target into a texture resource.
bool	copyTexture (Texture src, Texture dst) override
	Copies the contents of one texture resource into another texture resource.
bool	dispatch (const ComputeDispatchDesc &desc) override
	Dispatches a compute pipeline on the graphics queue.
bool	copyTexture (id< MTLTexture > src, Texture *dst)
	Copies the contents of one MTLTexture into another via a synchronous blit command.

Additional Inherited Members

Detailed Description

Store encoded commands for the GPU to execute.

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

Constructor & Destructor Documentation

◆ GraphicsContextImpl()

GraphicsContextImpl	(	GraphicsDeviceImpl *	driver,
		SurfaceHandle	surface )

Parameters

driver The device for which MTLCommandQueue object was created.

Member Function Documentation

◆ getScreenRenderTarget()

RenderTarget * getScreenRenderTarget ( ) const

inlineoverridevirtual

Set the Screen Render Target object.

Parameters

rt

Implements GraphicsContext.

◆ updateSurface()

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

overridevirtual

Updates surface when the window resized or surface recretad.

Parameters

surface
width
height

Returns: true; false

Reimplemented from GraphicsContext.

◆ setDepthStencilState()

void setDepthStencilState ( DepthStencilState * depthStencilState )

overridevirtual

Set depthStencil status.

Parameters

depthStencilState Specifies the depth and stencil status

Implements GraphicsContext.

◆ setGraphicsPipeline()

void setGraphicsPipeline ( GraphicsPipeline * graphicsPipeline )

overridevirtual

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.

Implements GraphicsContext.

◆ beginFrame()

bool beginFrame ( )

overridevirtual

Indicate the begining of a frame Wait until the inflight command buffer has completed its work.

Then create MTLCommandBuffer and enqueue it to MTLCommandQueue. Then start schedule available MTLBuffer

Implements GraphicsContext.

◆ beginRenderPass()

void beginRenderPass	(	RenderTarget *	renderTarget,
		const RenderPassDesc &	descriptor )

overridevirtual

Create a MTLRenderCommandEncoder object for graphics rendering to an attachment in a RenderPassDesc.

MTLRenderCommandEncoder is cached if current RenderPassDesc is identical to previous one.

Parameters

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

Implements GraphicsContext.

◆ updateDepthStencilState()

void updateDepthStencilState ( const DepthStencilDesc & descriptor )

overridevirtual

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

Parameters

depthStencilState Specifies the depth and stencil status

Implements GraphicsContext.

◆ updatePipelineState()

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

overridevirtual

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.
desc	Specifies the pipeline descriptor.

Implements GraphicsContext.

◆ setViewport()

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

overridevirtual

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.

Implements GraphicsContext.

◆ setCullMode()

void setCullMode ( CullMode mode )

overridevirtual

Fixed-function state.

Parameters

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

Implements GraphicsContext.

◆ setWinding()

void setWinding ( Winding winding )

overridevirtual

Fixed-function state.

Parameters

winding The winding order of front-facing primitives.

Implements GraphicsContext.

◆ setVertexBuffer()

void setVertexBuffer ( Buffer * buffer )

overridevirtual

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

Parameters

buffer The buffer to set in the buffer argument table.

Implements GraphicsContext.

◆ setIndexBuffer()

void setIndexBuffer ( Buffer * buffer )

overridevirtual

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

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

Implements GraphicsContext.

◆ setInstanceBuffer()

void setInstanceBuffer ( Buffer * buffer )

overridevirtual

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.

Implements GraphicsContext.

◆ drawArrays()

void drawArrays	(	size_t	start,
		size_t	count,
		bool	wireframe )

overridevirtual

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(IndexFormat indexType, unsigned int count, unsigned int offset)

Implements GraphicsContext.

◆ drawElements()

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

overridevirtual

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)

Implements GraphicsContext.

◆ drawElementsInstanced()

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

overridevirtual

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)

Implements GraphicsContext.

◆ submitCurrentFrameCommands()

void submitCurrentFrameCommands ( bool waitForCompletion )

overridevirtual

Submit currently encoded frame commands without presenting the default surface.

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

Reimplemented from GraphicsContext.

◆ setScissorRect()

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

overridevirtual

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

Implements GraphicsContext.

◆ readPixels()

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

overridevirtual

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.

Implements GraphicsContext.

◆ copyTexture() [1/3]

bool copyTexture	(	RenderTarget *	src,
		Texture *	dst )

overridevirtual

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.

Implements GraphicsContext.

◆ copyTexture() [2/3]

bool copyTexture	(	Texture *	src,
		Texture *	dst )

overridevirtual

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.

Implements GraphicsContext.

◆ dispatch()

bool dispatch ( const ComputeDispatchDesc & desc )

overridevirtual

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 from GraphicsContext.

◆ copyTexture() [3/3]

bool copyTexture	(	id< MTLTexture >	src,
		Texture *	dst )

Copies the contents of one MTLTexture into another via a synchronous blit command.

Parameters

src	Source texture.
dst	Destination texture.

Returns: true if the copy was issued, otherwise false.

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

GraphicsContextMTL.h

Public Member Functions

Setters & Getters

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ GraphicsContextImpl()

Member Function Documentation

◆ getScreenRenderTarget()

◆ updateSurface()

◆ setDepthStencilState()

◆ setGraphicsPipeline()

◆ beginFrame()

◆ beginRenderPass()

◆ updateDepthStencilState()

◆ updatePipelineState()

◆ setViewport()

◆ setCullMode()

◆ setWinding()

◆ setVertexBuffer()

◆ setIndexBuffer()

◆ setInstanceBuffer()

◆ drawArrays()

◆ drawElements()

◆ drawElementsInstanced()

◆ submitCurrentFrameCommands()

◆ setScissorRect()

◆ readPixels()

◆ copyTexture() [1/3]

◆ copyTexture() [2/3]

◆ dispatch()

◆ copyTexture() [3/3]