#include <Ultralight/platform/GPUDriver.h>

Overview

User-defined GPU driver interface.

The library uses this to optionally render Views on the GPU (see ViewConfig::is_accelerated).

You can provide the library with your own GPU driver implementation so that all rendering is performed using an existing GPU context (useful for game engines).

When a View is rendered on the GPU, you can retrieve the backing texture ID via View::render_target().

Default Implementation

A platform-specific implementation of GPUDriver is provided for you when you call App::Create(), (currently D3D11, Metal, and OpenGL). We recommend using these classes as a starting point for your own implementation (they ship as Zlib-licensed source in the SDK's platform folder).

Setting the GPU Driver

When using Renderer::Create(), you can provide your own implementation of this class via Platform::set_gpu_driver().

State Synchronization

During each call to Renderer::Render(), the library will update the state of the GPU driver (textures, render buffers, geometry, command lists, etc.) to match the current state of the library.

Detecting State Changes

The library will call BeginSynchronize() before any state is updated and EndSynchronize() after all state is updated. All Create / Update / Destroy calls will be made between these two calls.

This allows the GPU driver implementation to prepare the GPU for any state changes.

Drawing

All drawing is done via command lists (UpdateCommandList()) to allow asynchronous execution of commands on the GPU.

The library will dispatch a list of commands to the GPU driver during state synchronization. The GPU driver implementation should periodically consume the command list and execute the commands at an appropriate time.

See also: Platform::set_gpu_driver()

Public Member Functions
virtual	~GPUDriver ()
virtual void	BeginSynchronize ()=0
	Called before any state (eg, CreateTexture(), UpdateTexture(), DestroyTexture(), etc.) is updated during a call to Renderer::Render().
virtual void	EndSynchronize ()=0
	Called after all state has been updated during a call to Renderer::Render().
virtual uint32_t	NextTextureId ()=0
	Get the next available texture ID.
virtual void	CreateTexture (uint32_t texture_id, RefPtr< Bitmap > bitmap, uint32_t flags)=0
	Create a texture with a certain ID and bitmap.
virtual void	UpdateTexture (uint32_t texture_id, RefPtr< Bitmap > bitmap, const IntRect &dirty_rect)=0
	Update an existing non-RTT texture with new bitmap data.
virtual void	DestroyTexture (uint32_t texture_id)=0
	Destroy a texture.
virtual uint32_t	NextRenderBufferId ()=0
	Get the next available render buffer ID.
virtual void	CreateRenderBuffer (uint32_t render_buffer_id, const RenderBuffer &buffer)=0
	Create a render buffer with certain ID and buffer description.
virtual void	DestroyRenderBuffer (uint32_t render_buffer_id)=0
	Destroy a render buffer.
virtual uint32_t	NextGeometryId ()=0
	Get the next available geometry ID.
virtual void	CreateGeometry (uint32_t geometry_id, const VertexBuffer &vertices, const IndexBuffer &indices)=0
	Create geometry with certain ID and vertex/index data.
virtual void	UpdateGeometry (uint32_t geometry_id, const VertexBuffer &vertices, const IndexBuffer &indices)=0
	Update existing geometry with new vertex/index data.
virtual void	DestroyGeometry (uint32_t geometry_id)=0
	Destroy geometry.
virtual void	UpdateCommandList (const CommandList &list)=0
	Update the pending command list with commands to execute on the GPU.
virtual void	GetDeviceCaps (GPUDeviceCaps &caps)
	Report this driver's optional capabilities.

Constructor & Destructor Documentation

◆ ~GPUDriver()

virtual ~GPUDriver ( )

virtual

Member Function Documentation

◆ BeginSynchronize()

virtual void BeginSynchronize ( )

pure virtual

Called before any state (eg, CreateTexture(), UpdateTexture(), DestroyTexture(), etc.) is updated during a call to Renderer::Render().

This is a good time to prepare the GPU for any state updates.

◆ CreateGeometry()

virtual void CreateGeometry	(	uint32_t	geometry_id,
		const VertexBuffer &	vertices,
		const IndexBuffer &	indices )

pure virtual

Create geometry with certain ID and vertex/index data.

Parameters

geometry_id	The geometry ID to use for the new geometry.
vertices	The vertex buffer data.
indices	The index buffer data.

Warning: A deep copy of the vertex/index data should be made if you are uploading it to the GPU asynchronously, it will not persist beyond this call.

◆ CreateRenderBuffer()

virtual void CreateRenderBuffer	(	uint32_t	render_buffer_id,
		const RenderBuffer &	buffer )

pure virtual

Create a render buffer with certain ID and buffer description.

Parameters

render_buffer_id	The render buffer ID to use for the new render buffer.
buffer	The render buffer description.

◆ CreateTexture()

virtual void CreateTexture	(	uint32_t	texture_id,
		RefPtr< Bitmap >	bitmap,
		uint32_t	flags )

pure virtual

Create a texture with a certain ID and bitmap.

Parameters

texture_id	The texture ID to use for the new texture.
bitmap	The bitmap to initialize the texture with. For a render target (flags includes kGPUTextureFlag_RenderTarget) this holds the dimensions and format but no pixel rows; otherwise it holds the pixel data to upload.
flags	A bitwise-OR of GPUTextureFlags describing how the texture will be used (render target, antialiased, immutable).

Warning: A deep copy of the bitmap data should be made if you are uploading it to the GPU asynchronously, it will not persist beyond this call.

◆ DestroyGeometry()

virtual void DestroyGeometry ( uint32_t geometry_id )

pure virtual

Destroy geometry.

Parameters

geometry_id The geometry to destroy.

◆ DestroyRenderBuffer()

virtual void DestroyRenderBuffer ( uint32_t render_buffer_id )

pure virtual

Destroy a render buffer.

Parameters

render_buffer_id The render buffer to destroy.

◆ DestroyTexture()

virtual void DestroyTexture ( uint32_t texture_id )

pure virtual

Destroy a texture.

Parameters

texture_id The texture to destroy.

◆ EndSynchronize()

virtual void EndSynchronize ( )

pure virtual

Called after all state has been updated during a call to Renderer::Render().

◆ GetDeviceCaps()

virtual void GetDeviceCaps ( GPUDeviceCaps & caps )

inlinevirtual

Report this driver's optional capabilities.

The engine calls this to discover optional features (for example, which block-compressed texture formats can be uploaded and sampled natively). The result may be cached.

Parameters

caps	A zero-initialized structure to fill in. Set only the capabilities this driver supports and leave the rest at zero.

Note: The default implementation reports no optional capabilities, so a driver that does not override this method keeps working unchanged (the engine falls back to software where a capability is required).

◆ NextGeometryId()

virtual uint32_t NextGeometryId ( )

pure virtual

Get the next available geometry ID.

This is used to generate a unique geometry ID for each geometry created by the library. The GPU driver implementation is responsible for mapping these IDs to a native ID.

Note: Numbering should start at 1, 0 is reserved for "no geometry".

Returns: Returns the next available geometry ID.

◆ NextRenderBufferId()

virtual uint32_t NextRenderBufferId ( )

pure virtual

Get the next available render buffer ID.

This is used to generate a unique render buffer ID for each render buffer created by the library. The GPU driver implementation is responsible for mapping these IDs to a native ID.

Note: Numbering should start at 1, 0 is reserved for "no render buffer".

Returns: Returns the next available render buffer ID.

◆ NextTextureId()

virtual uint32_t NextTextureId ( )

pure virtual

Get the next available texture ID.

This is used to generate a unique texture ID for each texture created by the library. The GPU driver implementation is responsible for mapping these IDs to a native ID.

Note: Numbering should start at 1, 0 is reserved for "no texture".

Returns: Returns the next available texture ID.

◆ UpdateCommandList()

virtual void UpdateCommandList ( const CommandList & list )

pure virtual

Update the pending command list with commands to execute on the GPU.

Commands are dispatched to the GPU driver asynchronously via this method. The GPU driver implementation should consume these commands and execute them at an appropriate time.

Parameters

list	The list of commands to execute.

Warning: Implementations should make a deep copy of the command list, it will not persist beyond this call.

◆ UpdateGeometry()

virtual void UpdateGeometry	(	uint32_t	geometry_id,
		const VertexBuffer &	vertices,
		const IndexBuffer &	indices )

pure virtual

Update existing geometry with new vertex/index data.

Parameters

geometry_id	The geometry to update.
vertices	The new vertex buffer data.
indices	The new index buffer data.

Warning: A deep copy of the vertex/index data should be made if you are uploading it to the GPU asynchronously, it will not persist beyond this call.

◆ UpdateTexture()

virtual void UpdateTexture	(	uint32_t	texture_id,
		RefPtr< Bitmap >	bitmap,
		const IntRect &	dirty_rect )

pure virtual

Update an existing non-RTT texture with new bitmap data.

Parameters

texture_id	The texture to update.
bitmap	The new bitmap data. Always the complete texture surface, valid inside and outside dirty_rect.
dirty_rect	The region of the bitmap, in pixels, that changed since the last upload. This is an optimization hint: a driver may upload only this region, or ignore it and upload the whole bitmap. Never larger than the bitmap bounds and never empty.

Warning: A deep copy of the bitmap data should be made if you are uploading it to the GPU asynchronously, it will not persist beyond this call.

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

Ultralight/platform/GPUDriver.h

Overview

Default Implementation

Setting the GPU Driver

State Synchronization

Detecting State Changes

Drawing

Public Member Functions

Constructor & Destructor Documentation

◆ ~GPUDriver()

Member Function Documentation

◆ BeginSynchronize()

◆ CreateGeometry()

◆ CreateRenderBuffer()

◆ CreateTexture()

◆ DestroyGeometry()

◆ DestroyRenderBuffer()

◆ DestroyTexture()

◆ EndSynchronize()

◆ GetDeviceCaps()

◆ NextGeometryId()

◆ NextRenderBufferId()

◆ NextTextureId()

◆ UpdateCommandList()

◆ UpdateGeometry()

◆ UpdateTexture()