GPU Device Capabilities
Report optional GPU features and device limits to the renderer.
On this page
You can report optional hardware features and device limits to the renderer when implementing a custom GPU driver. This lets the renderer use capabilities like multisampling and compressed textures while staying within hardware boundaries.
Drivers included with AppCore already report their capabilities— you only need to set them when providing a custom driver.
Reporting Capabilities
To report device capabilities and limits, override GPUDriver::GetDeviceCaps() and populate the fields your hardware supports:
#include <Ultralight/Ultralight.h>
using namespace ultralight;
class MyGPUDriver : public GPUDriver {
public:
void GetDeviceCaps(GPUDeviceCaps& caps) override {
///
/// Our render targets keep their pixels between frames, so the library
/// can redraw just the part of a View that changed.
///
caps.supports_partial_redraw = 1;
///
/// Our device samples both block-compressed families in hardware.
///
caps.compressed_formats =
kGPUCompressedFormat_BC1_BC3 | kGPUCompressedFormat_BC7;
///
/// We can allocate multisampled render targets, four samples each.
///
caps.supports_msaa = 1;
caps.max_msaa_samples = 4;
///
/// The largest width or height our device can create (ask your
/// graphics API).
///
caps.max_texture_dimension = 16384;
}
// The remaining overrides are covered in Implementing a GPUDriver.
};
đźš§ Capabilities Are Cached
The library zero-initializes
GPUDeviceCapsbefore callingGetDeviceCaps(). It reads your capabilities once and caches the result— the values you report must never change afterward.
If you use GPUDriverAsync, set GPUDriverAsync::Options::caps instead of overriding GetDeviceCaps()— these capabilities stay fixed for the driver's lifetime. For details, see Asynchronous GPU Driver.
Overriding GetDeviceCaps() is optional. When you omit the override, every field stays zero— the renderer still draws correctly, but leaves optional hardware features disabled and applies the default behavior shown below:
| Field | Kind | When Zero |
|---|---|---|
compressed_formats |
Capability | No compressed formats. Textures decompress to BGRA before upload. |
supports_msaa |
Capability | Single-sample render targets only. |
supports_partial_redraw |
Capability | Whole View target cleared and redrawn on every composite. |
max_texture_dimension |
Limit | Not reported (uses built-in default). |
max_msaa_samples |
Limit | Not reported (uses built-in default). |
max_geometry_size |
Limit | Not reported (uses built-in default). |
Setting a limit to zero never restricts that resource to zero— the renderer uses its built-in default instead.
Configuring Multisampling
Set supports_msaa to 1 when the driver can allocate multisampled render targets, and set max_msaa_samples to the sample count so the renderer can account for texture memory.
The driver receives the kGPUTextureFlag_Antialiased flag in GPUDriver::CreateTexture() only when supports_msaa is set and analytic rendering is turned off. Analytic rendering (Config::enable_photon) defaults to true and performs antialiasing directly in shaders without allocating multisampled targets.
Report multisampling support whenever the hardware supports it, even when analytic rendering remains active.
Enabling Partial Redraws
Set supports_partial_redraw to 1 so the renderer redraws only the changed region of a View's render target during each composite.
When left at 0, the renderer clears and redraws the entire View render target on every composite— GPU time follows the size of the View rather than the size of the change.
You should enable this capability whenever your render targets keep their contents between frames. All four reference drivers (Direct3D 11, Direct3D 12, Metal, and OpenGL) set this flag.
đźš§ Preserve Render Target Contents
When enabling partial redraws, your driver must keep the View's render target contents between frames. Bind the target without clearing or discarding contents (avoid "don't care" load actions), and clear only for
CommandType::ClearRenderBuffer. You must also keep the same native texture behind each texture ID across frames, or pixels outside the redrawn region will be stale or missing.
Supporting Compressed Formats
Set compressed_formats using a bitmask of GPUCompressedFormat flags to advertise the block-compressed formats the device supports.
When a flag is set, GPUDriver::CreateTexture() receives textures in that family for direct hardware sampling— unset formats are decompressed to BGRA before upload.
| Flag | Formats |
|---|---|
kGPUCompressedFormat_BC1_BC3 |
BC1, BC2, and BC3 (DXT1, DXT3, DXT5) |
kGPUCompressedFormat_BC7 |
BC7 |
Compressed textures require a Pro edition or higher. For instructions on loading and uploading compressed assets, see Compressed Textures.
Setting Hardware Limits
Set max_texture_dimension to the maximum width or height of any texture or render target the device can create. The renderer guarantees that no requested texture will exceed this dimension.
Set max_geometry_size to the largest buffer size, in bytes, for a single vertex or index buffer. If tessellating a vector path produces geometry that exceeds this limit, the renderer drops the path instead of attempting to upload it.