docs

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:

C++
#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 GPUDeviceCaps before calling GetDeviceCaps(). 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.