docs
Loading...
Searching...
No Matches
GPUDriverabstract

#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

App::Create() installs a platform-specific GPUDriver for you.

The SDK includes reference drivers for Direct3D 11, Direct3D 12, Metal, and OpenGL. Their Zlib-licensed source code is in the platform folder.

Use these reference drivers as a starting point for your own driver.

Setting the GPU Driver

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

Threading and Lifetime

The library calls every method of this interface on the Renderer's thread– including NextTextureId(), NextRenderBufferId(), and NextGeometryId(). If your code also calls the ID methods (eg, to reserve an ImageSource texture ID) from another thread, your implementation must make them safe to call from that thread. The driver App::Create() installs and the SDK's reference drivers already make them safe to call from any thread.

Your driver must outlive the Renderer (destroy it only after the Renderer is destroyed).

The library doesn't call DestroyTexture(), DestroyRenderBuffer(), or DestroyGeometry() for resources that are still alive when the Renderer is destroyed, so you should free any remaining resources yourself when you destroy your driver.

Reporting Device Capabilities

Override GetDeviceCaps() to report optional features and device limits.

Most drivers need GPUDeviceCaps::supports_partial_redraw. Set this capability when the View's render target keeps its contents between frames– every reference driver sets it.

When this capability is left at zero, every composite clears and redraws the whole View, even for a small change.

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.

Each call to Renderer::Render() makes exactly one BeginSynchronize() / EndSynchronize() pair, even when nothing changed. UpdateCommandList() is called at most once per pair, after every Create / Update / Destroy call in that pair.

Drawing

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

The library dispatches a list of commands to the GPU driver during state synchronization. Your driver may execute a list later than that call (eg, on your own render thread), as long as it keeps the order UpdateCommandList() describes.

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_idThe geometry ID to use for the new geometry.
verticesThe vertex buffer data.
indicesThe 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_idThe render buffer ID to use for the new render buffer.
bufferThe 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_idThe texture ID to use for the new texture.
bitmapThe 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.
flagsA 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. This doesn't apply to an immutable bitmap (see Bitmap::is_immutable()), which you can keep a reference to instead.

◆ DestroyGeometry()

virtual void DestroyGeometry ( uint32_t geometry_id)
pure virtual

Destroy geometry.

Parameters
geometry_idThe geometry to destroy.

◆ DestroyRenderBuffer()

virtual void DestroyRenderBuffer ( uint32_t render_buffer_id)
pure virtual

Destroy a render buffer.

Parameters
render_buffer_idThe render buffer to destroy.

◆ DestroyTexture()

virtual void DestroyTexture ( uint32_t texture_id)
pure virtual

Destroy a texture.

Parameters
texture_idThe 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 library calls this method to query optional features and device limits (eg, partial redraws of the View and native sampling of block-compressed formats).

The library reads this once and caches the result, so the capabilities you report must not change afterward.

Parameters
capsA zero-initialized struct to fill in. Set only what this driver supports– leave the rest zero.
Note
The default implementation is empty and reports no capabilities.
Note
Rendering remains correct if you do not implement this method, but performance is reduced. When supports_partial_redraw is unset, the library clears and redraws the entire View on every composite. The library also decompresses block-compressed textures before upload.
See also
GPUDeviceCaps::supports_partial_redraw

◆ 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.

You must execute every command in every list, in the order the lists and their commands were given. You may execute a list later than this call (eg, on your own render thread). If you do, add each new list after any you haven't executed yet (never replace one), and apply the create, update, and destroy calls the library makes after this call only after that list has executed.

Parameters
listThe 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_idThe geometry to update.
verticesThe new vertex buffer data.
indicesThe 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_idThe texture to update.
bitmapThe new bitmap data. Always the complete texture surface, valid inside and outside dirty_rect.
dirty_rectThe 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. This doesn't apply to an immutable bitmap (see Bitmap::is_immutable()), which you can keep a reference to instead.

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