Implementing a GPUDriver
Implement the GPUDriver interface to render views with a native graphics API.
On this page
You can render web content through your graphics pipeline by implementing the GPUDriver interface. This lets you receive texture updates, geometry buffers, and draw calls directly from the renderer.
To register a driver and display a view, see GPU Renderer Overview. Reference implementations for major graphics APIs are available in the SDK platform folder.
Implementing the Interface
To create a custom driver, inherit from GPUDriver and implement its pure virtual methods:
#include <Ultralight/Ultralight.h>
#include <vector>
using namespace ultralight;
class MyGPUDriver : public GPUDriver {
public:
void BeginSynchronize() override {}
void EndSynchronize() override {}
uint32_t NextTextureId() override { return next_texture_id_++; }
uint32_t NextRenderBufferId() override { return next_render_buffer_id_++; }
uint32_t NextGeometryId() override { return next_geometry_id_++; }
void CreateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap,
uint32_t flags) override;
void UpdateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap,
const IntRect& dirty_rect) override;
void DestroyTexture(uint32_t texture_id) override;
void CreateRenderBuffer(uint32_t render_buffer_id,
const RenderBuffer& buffer) override;
void DestroyRenderBuffer(uint32_t render_buffer_id) override;
void CreateGeometry(uint32_t geometry_id, const VertexBuffer& vertices,
const IndexBuffer& indices) override;
void UpdateGeometry(uint32_t geometry_id, const VertexBuffer& vertices,
const IndexBuffer& indices) override;
void DestroyGeometry(uint32_t geometry_id) override;
void UpdateCommandList(const CommandList& list) override;
///
/// Optional. Our render targets keep their pixels between frames.
///
void GetDeviceCaps(GPUDeviceCaps& caps) override {
caps.supports_partial_redraw = 1;
}
// Not part of the interface. Call this after Renderer::Render().
void DrawCommandList();
private:
void ApplyState(const GPUState& state);
uint32_t next_texture_id_ = 1;
uint32_t next_render_buffer_id_ = 1;
uint32_t next_geometry_id_ = 1;
std::vector<Command> pending_;
};
You must implement all 14 pure virtual methods.
📘 Porting from Ultralight 1.4
If you're updating a driver written for Ultralight 1.4, see Porting from 1.4 to 2.0.
Reporting Device Capabilities
GetDeviceCaps() is the only optional override in GPUDriver. Use it to report supported features and limits to the renderer— see GPU Device Capabilities.
The library calls this method once and caches the result— the values you report must never change afterward.
Setting supports_partial_redraw to 1 tells the renderer to redraw only the modified areas of a View. When left at 0, the library clears and repaints the entire View on every composite.
🚧 Preserve Render Target Pixels
Set
supports_partial_redrawto 1 only when your render targets keep their pixels between frames— see Enabling Partial Redraws.
Managing IDs and Synchronization
NextTextureId(), NextRenderBufferId(), and NextGeometryId() must each return a unique non-zero ID for each resource. The value 0 represents no resource. Your driver maps each ID to its own native graphics handle.
You can also reserve a texture ID yourself by calling NextTextureId() directly (see Displaying Custom Textures). That ID may appear in a draw command's texture slot without a CreateTexture() call— your driver binds your own texture for it.
The library calls every driver method on the Renderer thread, including the three ID methods.
🚧 Thread-Safe Resource IDs
If you call
NextTextureId()from another thread (eg, to reserve a texture ID off theRendererthread), your ID methods must be safe to call from that thread. Atomic counters work well for this.
The library creates, updates, and destroys resources inside Renderer::Render(). All of these calls happen between BeginSynchronize() and EndSynchronize()— use them to open and close a GPU upload batch.
Your driver must outlive the Renderer. Destroy the driver only after destroying the Renderer.
Managing Textures
Creating Textures
When the library allocates a texture, it calls CreateTexture() with a unique ID, a Bitmap object, and a bitmask of GPUTextureFlags.
| Flag | Meaning |
|---|---|
kGPUTextureFlag_RenderTarget |
Backs a render buffer. The bitmap contains dimensions and a format but no pixel rows— create a texture that can be rendered into and sampled from. |
kGPUTextureFlag_Antialiased |
Requires a multisampled render target that resolves to a single-sample texture when sampled. The library passes this flag only when your driver reports MSAA support and analytic rendering is off (never under the default Config::enable_photon = true— see GPU Device Capabilities). |
kGPUTextureFlag_Immutable |
The texture is uploaded once and never modified— the library never calls UpdateTexture() on it. You can use immutable GPU storage and don't need to keep it CPU-writable. The bitmap is immutable (Bitmap::is_immutable()), so you can keep a reference to it rather than copying its pixels. |
Texture Formats
The BitmapFormat enum specifies the pixel layout for each allocated texture.
| Format | Native Texture |
|---|---|
BitmapFormat::BGRA8_UNORM_SRGB |
Standard 8-bit BGRA UNORM (eg, DXGI_FORMAT_B8G8R8A8_UNORM), never a hardware sRGB format. The library blends stored sRGB values directly— a hardware sRGB format causes the GPU to decode values on sampling, which alters colors. |
BitmapFormat::A8_UNORM |
Single-channel 8-bit format. Read this as alpha when sampled. When created as a render target, back it with a renderable single-channel format (R8) with no alpha swizzle. |
BitmapFormat::RG8_UNORM |
Two 8-bit unsigned normalized channels. |
BitmapFormat::RGBA16F, BitmapFormat::RGBA16UI, BitmapFormat::RGBA32F |
Data pages for analytic shader programs. Create these textures without filtering or mipmaps— see GPU Shader Programs. |
BitmapFormat::BC1_UNORM, BC2_UNORM, BC3_UNORM, BC7_UNORM |
Block-compressed color formats. The library passes these only when your driver reports that family in GetDeviceCaps()— see Compressed Textures. |
Updating Textures
When pixel content changes, the library calls UpdateTexture() with the full bitmap surface and a dirty_rect bounding the modified pixels. This rectangle is never empty and serves as a hint— your driver may upload only the dirty sub-region or re-upload the entire bitmap. The library never calls UpdateTexture() on render targets.
🚧 Copy Data for Asynchronous Uploads
The data passed to
CreateTexture(),UpdateTexture(),CreateGeometry(),UpdateGeometry(), andUpdateCommandList()is valid only until the call returns. If you stage or upload data asynchronously on another thread, make a deep copy before returning. You don't need to copy immutable bitmaps (Bitmap::is_immutable(), including everykGPUTextureFlag_Immutabletexture)— keep theRefPtr<Bitmap>instead, since its pixels never change and live as long as theBitmap.
Implement CreateTexture() and UpdateTexture() to allocate native textures and upload pixel data:
void MyGPUDriver::CreateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap,
uint32_t flags) {
if (flags & kGPUTextureFlag_RenderTarget) {
///
/// The bitmap holds dimensions and format only. Create a texture we can
/// both render into and sample from (multisampled if
/// kGPUTextureFlag_Antialiased is set).
///
// Pseudo-code, create a bitmap->width() x bitmap->height() render target
// here.
return;
}
///
/// Upload the pixels (copy them first if the upload is asynchronous).
///
auto pixels = bitmap->LockPixelsSafe();
// Pseudo-code, upload pixels.data() (pixels.size() bytes,
// bitmap->row_bytes() per row) here.
}
void MyGPUDriver::UpdateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap,
const IntRect& dirty_rect) {
///
/// The bitmap is always the whole surface. Upload just dirty_rect, or all
/// of it.
///
auto pixels = bitmap->LockPixelsSafe();
// Pseudo-code, upload the changed rows here.
}
Creating Render Buffers and Geometry
To configure render targets and vertex geometry, implement CreateRenderBuffer() and CreateGeometry():
void MyGPUDriver::CreateRenderBuffer(uint32_t render_buffer_id,
const RenderBuffer& buffer) {
///
/// buffer.texture_id is a texture created with kGPUTextureFlag_RenderTarget.
///
// Pseudo-code, create a framebuffer / render-target view over that
// texture here.
}
void MyGPUDriver::CreateGeometry(uint32_t geometry_id,
const VertexBuffer& vertices,
const IndexBuffer& indices) {
///
/// vertices.format picks the vertex struct; indices.data is an array of
/// IndexType.
///
// Pseudo-code, create a vertex buffer of vertices.size bytes and an index
// buffer of indices.size bytes here (copy both if the upload is
// asynchronous).
}
CreateRenderBuffer() wraps an existing texture created with kGPUTextureFlag_RenderTarget. Use RenderBuffer::texture_id to locate the backing texture, then wrap it in a native framebuffer or render-target view.
CreateGeometry() and UpdateGeometry() manage vertex and index data for drawing operations. VertexBuffer::format selects one of three vertex layouts— see GPU Shader Programs for the layout structures. The index buffer contains an array of 32-bit IndexType values, and both buffers provide their data size in bytes.
Executing the Command List
Store incoming commands during UpdateCommandList() and replay them after Renderer::Render() returns:
void MyGPUDriver::UpdateCommandList(const CommandList& list) {
///
/// The list does not outlive this call, so keep our own copy. Append it:
/// a list we have not drawn yet must still run.
///
pending_.insert(pending_.end(), list.commands, list.commands + list.size);
}
void MyGPUDriver::DrawCommandList() {
for (const Command& cmd : pending_) {
switch (cmd.command_type) {
case CommandType::ClearRenderBuffer:
// Pseudo-code, clear cmd.gpu_state.render_buffer_id to transparent
// black here.
break;
case CommandType::DrawGeometry:
ApplyState(cmd.gpu_state);
// Pseudo-code, draw cmd.indices_count indices of cmd.geometry_id,
// starting at cmd.indices_offset, here.
break;
case CommandType::Flush:
// Rare, but never skip one. Pseudo-code, submit pending GPU work
// here (Direct3D 11 / OpenGL only).
break;
}
}
pending_.clear();
}
The library issues one CommandList for each frame that paints, and sends nothing on idle frames. The command array is valid only for the duration of the call— copy the commands into your own storage before UpdateCommandList() returns.
More than one command list can arrive before you draw (eg, when you call Renderer::Render() twice before a draw). Append incoming lists to your pending commands rather than replacing earlier ones. You must execute every command across all lists, in the exact order they arrived.
The example above executes commands right after Renderer::Render() returns, but you can also run them later on your own render thread. If you defer execution, you must apply any create, update, and destroy calls that follow a command list only after your driver finishes executing that list.
📘 Asynchronous GPU Driver
If you render on a separate thread, consider using
GPUDriverAsync. It records driver calls and copies their data into frame packages for your render thread— see Asynchronous GPU Driver.
| Command | What to Do |
|---|---|
CommandType::ClearRenderBuffer |
Clear the buffer identified by gpu_state.render_buffer_id to transparent black (#00000000). Ignore all other fields in gpu_state. |
CommandType::DrawGeometry |
Apply gpu_state to the pipeline, then draw indices_count indices from geometry_id starting at indices_offset. |
CommandType::Flush |
Submit pending GPU work before the next command. You receive this before the library draws into a render buffer whose texture earlier draws in the same command list sampled. The command is rare and many command lists hold none— still handle every one. Call Flush() on Direct3D 11 or glFlush() on OpenGL. Skipping it causes intermittent dropouts in sampled content on some drivers. On Direct3D 12, Metal, or Vulkan, this is usually a no-op when resource barriers already order access (barriers must cover clears as well as draws). |
Applying GPU State
GPUState holds the complete pipeline configuration for a CommandType::DrawGeometry command. In the example above, ApplyState() sets up the GPU in the stages described below.
Setting the Render Target, Viewport, and Scissor
Bind the native framebuffer for render_buffer_id, and set the viewport to viewport_width by viewport_height pixels.
🚧 Preserve Render Buffer Contents
Never clear or discard a render buffer when binding it, and avoid "don't care" load actions. The library redraws parts of its tile render buffers on every driver— with partial redraws enabled in GPU Device Capabilities, it redraws parts of the View's render target as well. A render buffer must keep its pixels until a draw updates them or
CommandType::ClearRenderBufferclears them.
When enable_scissor is true, enable the scissor test and clip drawing to scissor_rect (in pixels). When enable_scissor is false, disable the scissor test.
Projecting the Transform
Multiply transform by an orthographic projection using Matrix::SetOrthographicProjection() before passing the matrix to the vertex shader:
///
/// Combine the draw's transform with a screen-space orthographic projection
/// (pass flip_y = true on OpenGL).
///
Matrix4x4 ProjectedTransform(const GPUState& state, bool flip_y) {
Matrix projection;
projection.SetOrthographicProjection(state.viewport_width,
state.viewport_height, flip_y);
Matrix transform;
transform.Set(state.transform);
projection.Transform(transform);
return projection.GetMatrix4x4();
}
Pass flip_y = true on OpenGL drivers, since the library draws into offscreen render targets.
Binding Shaders, Textures, and Constants
shader_type identifies the vertex and pixel shader pair to bind for the draw call.
Bind texture_1_id through texture_4_id to texture slots 1 through 4 (leave a slot unbound if its ID is 0). Slot 4 appears only during analytic shader draws and requires an integer texture view.
Combine the uniform arrays, the clip stack, and the projected transform into a single constant buffer. For buffer layouts and register assignments, see GPU Shader Programs.
Configuring Blending
When enable_blend is false, disable blending so incoming pixels overwrite the target.
When enable_blend is true, configure the blend state using blend_src_factor, blend_dst_factor, and blend_equation. Apply those same factors to the alpha channel— since Direct3D rejects color factors on alpha channels, pass the alpha equivalent instead (eg, InvDestAlpha for InvDestColor).