|
Ultralight C++ API 2.0.0
|
#include <Ultralight/platform/GPUDriver.h>
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().
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.
When using Renderer::Create(), you can provide your own implementation of this class via Platform::set_gpu_driver().
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.
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.
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.
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.
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.
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. | |
|
virtual |
|
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.
|
pure virtual |
Create geometry with certain ID and vertex/index data.
| geometry_id | The geometry ID to use for the new geometry. |
| vertices | The vertex buffer data. |
| indices | The index buffer data. |
|
pure virtual |
Create a render buffer with certain ID and buffer description.
| render_buffer_id | The render buffer ID to use for the new render buffer. |
| buffer | The render buffer description. |
|
pure virtual |
Create a texture with a certain ID and bitmap.
| 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). |
|
pure virtual |
Destroy geometry.
| geometry_id | The geometry to destroy. |
|
pure virtual |
Destroy a render buffer.
| render_buffer_id | The render buffer to destroy. |
|
pure virtual |
Destroy a texture.
| texture_id | The texture to destroy. |
|
pure virtual |
Called after all state has been updated during a call to Renderer::Render().
|
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.
| caps | A zero-initialized struct to fill in. Set only what this driver supports– leave the rest zero. |
|
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.
|
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.
|
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.
|
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.
| list | The list of commands to execute. |
|
pure virtual |
Update existing geometry with new vertex/index data.
| geometry_id | The geometry to update. |
| vertices | The new vertex buffer data. |
| indices | The new index buffer data. |
|
pure virtual |
Update an existing non-RTT texture with new bitmap data.
| 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. |