docs
Loading...
Searching...
No Matches
GPUDriver.h
Go to the documentation of this file.
1///
2/// Copyright (C) 2026 Ultralight, Inc. All rights reserved.
3/// A license is required for commercial use. https://ultralig.ht
4///
5
6// clang-format off
7#pragma once
8#if defined(_MSC_VER)
9#pragma warning(disable : 4251)
10#endif
11#include <Ultralight/Defines.h>
12#include <Ultralight/Geometry.h>
13#include <Ultralight/Matrix.h>
14#include <Ultralight/Bitmap.h>
15
16namespace ultralight {
17
18/// \cond ignore
19/// This pragma pack(push, 1) command is important!
20/// GPU structs should not be padded with any bytes.
21/// \endcond
22#pragma pack(push, 1)
23
24///
25/// Render buffer description.
26///
27/// This structure describes a render buffer that can be used as a target for drawing commands.
28///
29/// @see GPUDriver::CreateRenderBuffer.
30///
32 uint32_t texture_id; ///< The backing texture for this RenderBuffer
33 uint32_t width; ///< The width of the RenderBuffer texture
34 uint32_t height; ///< The height of the RenderBuffer texture
35 bool has_stencil_buffer; ///< Currently unused, always false.
36 bool has_depth_buffer; ///< Currently unused, always false.
37};
38
39///
40/// Vertex layout for path vertices.
41///
42/// This struct is the in-memory layout for each path vertex (useful for synthesizing or modifying
43/// your own vertex data).
44///
46 float pos[2]; ///< Vertex position (x, y) in pixels.
47 unsigned char color[4]; ///< Vertex color (RGBA, 8 bits per channel).
48 float obj[2]; ///< Object-space coordinates (used for anti-aliasing).
49};
50
51///
52/// Vertex layout for quad vertices.
53///
54/// This struct is the in-memory layout for each quad vertex (useful for synthesizing or modifying
55/// your own vertex data).
56///
58 float pos[2]; ///< Vertex position (x, y) in pixels.
59 unsigned char color[4]; ///< Vertex color (RGBA, 8 bits per channel).
60 float tex[2]; ///< Texture coordinates (u, v).
61 float obj[2]; ///< Object-space coordinates (used for anti-aliasing).
62 float data0[4]; ///< Per-vertex shader data (shader-specific).
63 float data1[4]; ///< Per-vertex shader data (shader-specific).
64 float data2[4]; ///< Per-vertex shader data (shader-specific).
65 float data3[4]; ///< Per-vertex shader data (shader-specific).
66 float data4[4]; ///< Per-vertex shader data (shader-specific).
67 float data5[4]; ///< Per-vertex shader data (shader-specific).
68 float data6[4]; ///< Per-vertex shader data (shader-specific).
69};
70
71///
72/// Vertex layout for instance vertices.
73///
74/// This struct is the in-memory layout for each instance vertex (used for instanced cell
75/// rendering, see ShaderType::FillPhotonGrid).
76///
78 float pos[2]; ///< Vertex position (x, y) in pixels.
79 uint32_t header_addr; ///< Cell header texel address in the index data page.
80 uint32_t path_slot; ///< Per-path constant-table slot (low bits) plus flags.
81};
82
83///
84/// Vertex buffer formats.
85///
86/// This enumeration describes the format of a vertex buffer.
87///
88/// @note Identifiers start with an underscore due to C++ naming rules.
89///
90/// @see VertexBuffer
91///
92enum class VertexBufferFormat : uint8_t {
93 _2f_4ub_2f, ///< Vertex_2f_4ub_2f (used for path rendering)
94 _2f_4ub_2f_2f_28f, ///< Vertex_2f_4ub_2f_2f_28f (used for quad rendering)
95 _2f_2ui, ///< Vertex_2f_2ui (used for instanced cell rendering)
96};
97
98///
99/// Vertex buffer description.
100///
101/// @see GPUDriver::CreateGeometry
102///
104 VertexBufferFormat format; ///< The format of the vertex buffer.
105 uint32_t size; ///< The size of the vertex buffer in bytes.
106 uint8_t* data; ///< The raw vertex buffer data.
107};
108
109///
110/// Vertex index type.
111///
112typedef uint32_t IndexType;
113
114///
115/// Index buffer description.
116///
117/// This structure describes an index buffer that can be used to index into a vertex buffer.
118///
119/// @note The index buffer is a simple array of IndexType values.
120///
121/// @see GPUDriver::CreateGeometry
122///
124 uint32_t size; ///< The size of the index buffer in bytes.
125 uint8_t* data; ///< The raw index buffer data.
126};
127
128///
129/// Shader program types.
130///
131/// Each of these correspond to a vertex/pixel shader pair. Stock shaders for every program ship in
132/// the SDK's `platform/shaders` folder, in a compiled or generated form for each backend (DXBC,
133/// SPIR-V, MSL, and GLSL).
134///
135/// A conforming GPUDriver implements every program in this enumeration; the library does not
136/// query for per-program support.
137///
138/// @see GPUState::shader_type
139///
140enum class ShaderType : uint8_t {
141 Fill, ///< Shader program for filling quad geometry.
142 FillPath, ///< Shader program for filling tessellated path geometry.
143 FilterBasic, ///< Shader program for basic CSS/SVG filters.
144 FilterBlur, ///< Shader program for blur CSS/SVG filters.
145 FilterDropShadow, ///< Shader program for drop-shadow CSS/SVG filters.
146
147 ///
148 /// Shader program for analytic vector rendering (Photon). Uses the quad
149 /// vertex layout.
150 ///
151 /// Photon draws carry data pages in the GPUState texture slots and read
152 /// them with texel loads only. Bind each slot **unfiltered, no mipmaps**,
153 /// at the register the shipped shader source declares:
154 ///
155 /// | GPUState slot | Carries | Format | Shader binding |
156 /// |----------------|----------------------------------|----------|-----------------------|
157 /// | `texture_1_id` | Curve page | RGBA16F | `Texture0` (t0) |
158 /// | `texture_2_id` | (never set on Photon draws) | | |
159 /// | `texture_3_id` | Constants / glyph LUT / ramp | RGBA32F | `Texture2` (t2) |
160 /// | `texture_4_id` | Index/header page | RGBA16UI | `IndexTexture` (t3) |
161 ///
162 /// The index page has its own slot and register because it needs an
163 /// integer (`uint4`) texture view; it must never share a binding point
164 /// with the float views other programs use.
165 ///
166 /// Every driver must support this program alongside the others; there is
167 /// no capability query for it.
168 ///
170
171 ///
172 /// Shader program for grid-based analytic vector rendering (Photon). Uses
173 /// the Vertex_2f_2ui instance layout.
174 ///
175 /// Binds the same data pages, slots, and registers as FillPhoton, with one
176 /// addition: the **vertex** shader also reads the texture slots, so bind
177 /// them to both shader stages for this program.
178 ///
179 /// Every driver must support this program alongside the others.
180 ///
182};
183
184///
185/// Blend factors that define how source and destination colors are weighted during blending.
186///
187/// These factors control how much the source color (from the pixel shader) and destination color
188/// (from the render buffer) contribute to the final blended result.
189///
190/// For each color channel, the blend equation combines colors as:
191/// Result = (SourceColor * SourceFactor) [op] (DestColor * DestFactor)
192/// where [op] is defined by BlendEquation.
193///
194enum class BlendFactor : uint8_t {
195 Zero, ///< Factor of (0, 0, 0, 0) - completely removes this color's contribution
196 One, ///< Factor of (1, 1, 1, 1) - uses this color at full intensity
197
198 /// Source-based factors (use the incoming pixel shader output)
199 SrcColor, ///< Factor of (Rs, Gs, Bs, As) - multiply by source color components
200 InvSrcColor, ///< Factor of (1-Rs, 1-Gs, 1-Bs, 1-As) - multiply by inverse source color
201 SrcAlpha, ///< Factor of (As, As, As, As) - multiply all channels by source alpha
202 InvSrcAlpha, ///< Factor of (1-As, 1-As, 1-As, 1-As) - multiply by inverse source alpha
203
204 /// Destination-based factors (use the existing render buffer color)
205 DestColor, ///< Factor of (Rd, Gd, Bd, Ad) - multiply by destination color components
206 InvDestColor, ///< Factor of (1-Rd, 1-Gd, 1-Bd, 1-Ad) - multiply by inverse dest color
207 DestAlpha, ///< Factor of (Ad, Ad, Ad, Ad) - multiply all channels by destination alpha
208 InvDestAlpha, ///< Factor of (1-Ad, 1-Ad, 1-Ad, 1-Ad) - multiply by inverse dest alpha
209
210 /// Special factors
211 SrcAlphaSaturate ///< Factor of (f, f, f, 1) where f = min(As, 1-Ad). Useful for additive
212 ///< blending that doesn't oversaturate the destination alpha channel.
213};
214
215///
216/// Mathematical operations for combining source and destination colors during blending.
217///
218/// This defines how the GPU combines the weighted source and destination colors after they've
219/// been multiplied by their respective blend factors.
220///
221enum class BlendEquation : uint8_t {
222 Add, ///< Result = (Src * SrcFactor) + (Dest * DestFactor)
223 ///< Standard additive blending - most common operation
224
225 Subtract, ///< Result = (Src * SrcFactor) - (Dest * DestFactor)
226 ///< Subtractive blending - source reduces destination
227
228 RevSubtract, ///< Result = (Dest * DestFactor) - (Src * SrcFactor)
229 ///< Reverse subtractive blending - destination reduces source
230
231 Min, ///< Result = min(Src, Dest) - takes darker/smaller value
232 ///< Note: Ignores blend factors, compares colors directly
233
234 Max ///< Result = max(Src, Dest) - takes lighter/larger value
235 ///< Note: Ignores blend factors, compares colors directly
236};
237
238///
239/// The state of the GPU for a given draw command.
240///
241/// This structure describes the current state of the GPU for a given draw command.
242///
243/// @see Command::gpu_state
244///
246 /// Viewport width in pixels
248
249 /// Viewport height in pixels
251
252 /// Transform matrix-- you should multiply this with the screen-space orthographic projection
253 /// matrix then pass to the vertex shader.
255
256 /// Whether or not we should enable texturing for the current draw command.
258
259 /// Whether or not we should enable blending for the current draw command. If blending is
260 /// disabled, any drawn pixels should overwrite existing. This is mainly used so we can modify
261 /// alpha values of the RenderBuffer during scissored clears.
263
264 /// The blend factor for the source color (pixel shader output).
265 /// This factor is multiplied with the source color before the blend equation is applied.
266 /// The library sets it on every draw command (One for normal premultiplied-alpha drawing).
267 /// Ignore it when enable_blend is false.
269
270 /// The blend factor for the destination color (render buffer).
271 /// This factor is multiplied with the destination color before the blend equation is applied.
272 /// The library sets it on every draw command (InvSrcAlpha for normal premultiplied-alpha
273 /// drawing). Ignore it when enable_blend is false.
275
276 /// The mathematical equation used to combine the source and destination colors.
277 /// The library sets it on every draw command (Add for normal drawing). Ignore it when
278 /// enable_blend is false.
280
281 /// The vertex/pixel shader program pair to use for the current draw command.
283
284 /// The render buffer to use for the current draw command.
286
287 /// The texture id to bind to slot #1. (Will be 0 if none)
288 uint32_t texture_1_id;
289
290 /// The texture id to bind to slot #2. (Will be 0 if none)
291 uint32_t texture_2_id;
292
293 /// The texture id to bind to slot #3. (Will be 0 if none)
294 uint32_t texture_3_id;
295
296 /// The texture id to bind to slot #4. (Will be 0 if none)
297 ///
298 /// Set only on Photon draws: carries the RGBA16UI index/header page, which
299 /// needs an integer texture view. The slot table on ShaderType::FillPhoton
300 /// has the full binding contract.
301 uint32_t texture_4_id;
302
303 /// The uniform integers (passed to the pixel shader via uniforms).
304 int32_t uniform_integer[8];
305
306 /// The uniform scalars (passed to the pixel shader via uniforms).
308
309 /// The uniform vectors (passed to the pixel shader via uniforms).
311
312 /// The clip size (passed to the pixel shader via uniforms).
313 uint8_t clip_size;
314
315 /// The clip stack (passed to the pixel shader via uniforms).
317
318 /// Whether or not scissor testing should be used for the current draw command.
320
321 /// The scissor rect to use for scissor testing (units in pixels)
323};
324
325///
326/// The types of commands.
327///
328/// This enumeration describes the type of command to execute on the GPU.
329///
330/// @see Command
331///
332enum class CommandType : uint8_t {
333 ClearRenderBuffer, ///< Clear the specified render buffer.
334 DrawGeometry, ///< Draw the specified geometry to the specified render buffer.
335
336 ///
337 /// Submit pending GPU work before executing the next command.
338 ///
339 /// The library emits this command right before it draws into a render buffer whose texture was
340 /// sampled by earlier draws in the same command list (ie. the target is bound again after it
341 /// was read).
342 ///
343 /// The library avoids that pattern where it can, so this command is rare and many command lists
344 /// have none. Some content still needs it (eg, some CSS blend modes and blurred text shadows)--
345 /// your driver must handle every one.
346 ///
347 /// - **Direct3D 12 / Metal / Vulkan:** This is usually a no-op. Your per-resource barriers or
348 /// transitions already order these accesses. Verify that ordering covers clears as well as
349 /// draws.
350 /// - **Direct3D 11 / OpenGL:** Submit pending work (`Flush()` / `glFlush()`). Otherwise, some
351 /// drivers reorder the pending sampling draws against the upcoming clear and draws-- this
352 /// causes intermittent dropouts in the sampled output.
353 ///
354 /// @note No fields of GPUState are meaningful on a Flush command.
355 ///
357};
358
359///
360/// A command to execute on the GPU.
361///
362/// This structure describes a command to be executed on the GPU.
363///
364/// Commands are dispatched to the GPU driver asynchronously via GPUDriver::UpdateCommandList(),
365/// the GPU driver should consume these commands and execute them at an appropriate time.
366///
367/// @see CommandList
368///
370 CommandType command_type; ///< The type of command to dispatch.
371 GPUState gpu_state; ///< The current GPU state.
372 uint32_t geometry_id; ///< The geometry ID to bind. (used with CommandType::DrawGeometry)
373 uint32_t indices_count; ///< The number of indices. (used with CommandType::DrawGeometry)
374 uint32_t indices_offset; ///< The index to start from. (used with CommandType::DrawGeometry)
375};
376
377///
378/// List of commands to execute on the GPU.
379///
380/// @see GPUDriver::UpdateCommandList
381///
383 uint32_t size; ///< The number of commands in the list.
384 Command* commands; ///< The raw command list data.
385};
386
387#pragma pack(pop)
388
389///
390/// Optional GPU compressed-texture format families.
391///
392/// Each value is a single bit within GPUDeviceCaps::compressed_formats. A driver
393/// sets a bit to advertise that it can accept a Bitmap in any of that family's
394/// formats in CreateTexture() and sample it directly (the GPU decompresses the
395/// blocks in hardware on read).
396///
397/// @note These are bit flags and are append-only: never renumber or reuse an
398/// existing value. Treat any bit you do not recognize as unsupported.
399///
400enum GPUCompressedFormat : uint32_t {
401 /// BC1, BC2, and BC3 (also known as DXT1 / DXT3 / DXT5).
403
404 /// BC7.
406};
407
408///
409/// Optional capabilities reported by a GPUDriver.
410///
411/// The library zero-initializes this structure and passes it to GPUDriver::GetDeviceCaps(). Your
412/// driver fills in what it supports.
413///
414/// A capability field left at zero means the feature is not supported.
415///
416/// A limit field left at zero uses the library's built-in default.
417///
418/// Leaving a capability unset still produces correct output, but it can reduce performance--
419/// for example, leaving supports_partial_redraw unset forces the library to redraw the whole
420/// View on every composite.
421///
422/// @note This structure may grow over time as new fields are appended. Because the library owns
423/// and zero-initializes it, a driver compiled against an older definition leaves newer
424/// fields at their default values.
425///
427 ///
428 /// Bitmask of supported compressed-texture families (see GPUCompressedFormat).
429 /// Zero means no block-compressed formats are supported; such textures are
430 /// decompressed before upload.
431 ///
433
434 ///
435 /// Nonzero if this driver can allocate multisampled (antialiased) render
436 /// targets (see kGPUTextureFlag_Antialiased). Zero (the default) means it only
437 /// creates single-sample targets.
438 ///
440
441 ///
442 /// The largest width or height, in pixels, of a texture or render target this
443 /// driver can create. The engine will not ask you to create one whose width or
444 /// height exceeds this value.
445 ///
446 /// @note This is a limit, not a capability flag: zero (the default) means the
447 /// driver does not report a limit, and the engine substitutes a
448 /// conservative built-in default rather than treating it as "no
449 /// textures allowed".
450 ///
452
453 ///
454 /// The sample count this driver uses for multisampled render targets (see
455 /// supports_msaa), reported so the engine can account their memory.
456 ///
457 /// @note This is a limit, not a capability flag: zero (the default) means the
458 /// driver does not report a count, and the engine substitutes a
459 /// conservative built-in default when supports_msaa is set. Ignored
460 /// when supports_msaa is zero.
461 ///
463
464 ///
465 /// The largest size, in bytes, of a single vertex or index buffer the engine
466 /// will build for this driver. A path whose tessellated geometry would exceed
467 /// this is dropped rather than uploaded, so the driver never receives an
468 /// oversized CreateGeometry / UpdateGeometry.
469 ///
470 /// @note This is a limit, not a capability flag: zero (the default) means the
471 /// driver does not report a limit, and the engine substitutes a
472 /// conservative built-in default rather than treating it as "no
473 /// geometry allowed".
474 ///
476
477 ///
478 /// Whether or not the library may redraw only the changed region of a View's render target.
479 ///
480 /// When set to 1, each composite redraws only the region of the View that changed. GPU cost
481 /// follows the changed area.
482 ///
483 /// When set to 0 (the default), every composite with changes clears and redraws the entire
484 /// View target, even for a small change. Frames where nothing changed are still skipped.
485 /// GPU cost follows the size of the View.
486 ///
487 /// Set this to 1 when the View's render target keeps its contents between frames. All reference
488 /// drivers set this to 1.
489 ///
490 /// @warning When nonzero, the View's render target must keep its contents between frames. Bind
491 /// the target without clearing, discarding, or using a "don't care" load action.
492 /// Clear the target only when handling CommandType::ClearRenderBuffer. The same
493 /// native texture must also back each texture ID across frames. Failing to preserve
494 /// target contents causes stale or missing content outside the redrawn region.
495 ///
496 /// \parblock
497 /// @note This field is a capability flag (like `supports_msaa`), not a limit. Setting it to 0
498 /// is a safe default that disables partial redraws.
499 /// \endparblock
500 ///
501 /// \parblock
502 /// @note This setting governs only the View's render target. The library performs small
503 /// partial redraws on its tile render buffers on every driver regardless (load-and-store
504 /// operations are required there). Sampling an existing render texture is always
505 /// required.
506 /// \endparblock
507 ///
509};
510
511///
512/// Flags passed to GPUDriver::CreateTexture() that tell your driver how a texture will be used.
513/// They are combined with bitwise OR; test the bits your driver supports.
514///
515enum GPUTextureFlags : uint32_t {
516 ///
517 /// The texture is a render target (the backing texture for a RenderBuffer). Create it so you can
518 /// both render into and sample from it. The supplied bitmap is empty (dimensions and format
519 /// only), so there's nothing to upload at texture creation.
520 ///
521 /// Most render targets are BGRA (BitmapFormat::BGRA8_UNORM_SRGB). A render target may also be
522 /// single-channel (BitmapFormat::A8_UNORM): back it with a renderable one-channel format (R8 on
523 /// modern graphics APIs) so that sampling it returns the stored value in the RED channel. Do not
524 /// apply the alpha swizzle that sampled (non-render-target) A8 textures traditionally carry; the
525 /// library's shaders read a single-channel render target's red channel directly. Single-channel
526 /// render targets are only ever drawn with blending disabled and are never multisampled.
527 ///
529
530 ///
531 /// The render target should be multisampled (antialiased), resolved to a single-sample texture
532 /// when sampled. You will only receive this flag if your driver reports
533 /// GPUDeviceCaps::supports_msaa from GetDeviceCaps().
534 ///
536
537 ///
538 /// The texture is uploaded once and never changes. UpdateTexture() is never called on it, so
539 /// you may use immutable/static storage and need not keep it CPU-writable.
540 ///
541 /// The supplied bitmap is immutable (see Bitmap::is_immutable()), so you can keep a reference to
542 /// it instead of copying its pixels.
543 ///
545};
546
547///
548/// User-defined GPU driver interface.
549///
550/// The library uses this to optionally render Views on the GPU (see ViewConfig::is_accelerated).
551///
552/// You can provide the library with your own GPU driver implementation so that all rendering is
553/// performed using an existing GPU context (useful for game engines).
554///
555/// When a View is rendered on the GPU, you can retrieve the backing texture ID via
556/// View::render_target().
557///
558/// ## Default Implementation
559///
560/// App::Create() installs a platform-specific GPUDriver for you.
561///
562/// The SDK includes reference drivers for Direct3D 11, Direct3D 12, Metal, and OpenGL. Their
563/// Zlib-licensed source code is in the `platform` folder.
564///
565/// Use these reference drivers as a starting point for your own driver.
566///
567/// ## Setting the GPU Driver
568///
569/// When using Renderer::Create(), you can provide your own implementation of this
570/// class via Platform::set_gpu_driver().
571///
572/// ## Threading and Lifetime
573///
574/// The library calls every method of this interface on the Renderer's thread-- including
575/// NextTextureId(), NextRenderBufferId(), and NextGeometryId(). If your code also calls the ID
576/// methods (eg, to reserve an ImageSource texture ID) from another thread, your implementation must
577/// make them safe to call from that thread. The driver App::Create() installs and the SDK's
578/// reference drivers already make them safe to call from any thread.
579///
580/// Your driver must outlive the Renderer (destroy it only after the Renderer is destroyed).
581///
582/// The library doesn't call DestroyTexture(), DestroyRenderBuffer(), or DestroyGeometry() for
583/// resources that are still alive when the Renderer is destroyed, so you should free any remaining
584/// resources yourself when you destroy your driver.
585///
586/// ## Reporting Device Capabilities
587///
588/// Override GetDeviceCaps() to report optional features and device limits.
589///
590/// Most drivers need GPUDeviceCaps::supports_partial_redraw. Set this capability when the View's
591/// render target keeps its contents between frames-- every reference driver sets it.
592///
593/// When this capability is left at zero, every composite clears and redraws the whole View, even
594/// for a small change.
595///
596/// ## State Synchronization
597///
598/// During each call to Renderer::Render(), the library will update the state of the GPU driver
599/// (textures, render buffers, geometry, command lists, etc.) to match the current state of the
600/// library.
601///
602/// ### Detecting State Changes
603///
604/// The library will call BeginSynchronize() before any state is updated and EndSynchronize() after
605/// all state is updated. All `Create` / `Update` / `Destroy` calls will be made between these two
606/// calls.
607///
608/// This allows the GPU driver implementation to prepare the GPU for any state changes.
609///
610/// Each call to Renderer::Render() makes exactly one BeginSynchronize() / EndSynchronize() pair,
611/// even when nothing changed. UpdateCommandList() is called at most once per pair, after every
612/// `Create` / `Update` / `Destroy` call in that pair.
613///
614/// ## Drawing
615///
616/// All drawing is done via command lists (UpdateCommandList()) to allow asynchronous execution
617/// of commands on the GPU.
618///
619/// The library dispatches a list of commands to the GPU driver during state synchronization. Your
620/// driver may execute a list later than that call (eg, on your own render thread), as long as it
621/// keeps the order UpdateCommandList() describes.
622///
623/// @see Platform::set_gpu_driver()
624///
626 public:
627 virtual ~GPUDriver();
628
629 ///
630 /// Called before any state (eg, CreateTexture(), UpdateTexture(), DestroyTexture(), etc.) is
631 /// updated during a call to Renderer::Render().
632 ///
633 /// This is a good time to prepare the GPU for any state updates.
634 ///
635 virtual void BeginSynchronize() = 0;
636
637 ///
638 /// Called after all state has been updated during a call to Renderer::Render().
639 ///
640 virtual void EndSynchronize() = 0;
641
642 ///
643 /// Get the next available texture ID.
644 ///
645 /// This is used to generate a unique texture ID for each texture created by the library. The
646 /// GPU driver implementation is responsible for mapping these IDs to a native ID.
647 ///
648 /// @note Numbering should start at 1, 0 is reserved for "no texture".
649 ///
650 /// @return Returns the next available texture ID.
651 ///
652 virtual uint32_t NextTextureId() = 0;
653
654 ///
655 /// Create a texture with a certain ID and bitmap.
656 ///
657 /// @param texture_id The texture ID to use for the new texture.
658 ///
659 /// @param bitmap The bitmap to initialize the texture with. For a render
660 /// target (`flags` includes kGPUTextureFlag_RenderTarget) this
661 /// holds the dimensions and format but no pixel rows; otherwise
662 /// it holds the pixel data to upload.
663 ///
664 /// @param flags A bitwise-OR of GPUTextureFlags describing how the
665 /// texture will be used (render target, antialiased,
666 /// immutable).
667 ///
668 /// @warning A deep copy of the bitmap data should be made if you are uploading it to the GPU
669 /// asynchronously, it will not persist beyond this call. This doesn't apply to an
670 /// immutable bitmap (see Bitmap::is_immutable()), which you can keep a reference to
671 /// instead.
672 ///
673 virtual void CreateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap, uint32_t flags) = 0;
674
675 ///
676 /// Update an existing non-RTT texture with new bitmap data.
677 ///
678 /// @param texture_id The texture to update.
679 ///
680 /// @param bitmap The new bitmap data. Always the complete texture surface, valid inside
681 /// and outside `dirty_rect`.
682 ///
683 /// @param dirty_rect The region of the bitmap, in pixels, that changed since the last upload.
684 /// This is an optimization hint: a driver may upload only this region, or
685 /// ignore it and upload the whole bitmap. Never larger than the bitmap
686 /// bounds and never empty.
687 ///
688 /// @warning A deep copy of the bitmap data should be made if you are uploading it to the GPU
689 /// asynchronously, it will not persist beyond this call. This doesn't apply to an
690 /// immutable bitmap (see Bitmap::is_immutable()), which you can keep a reference to
691 /// instead.
692 ///
693 virtual void UpdateTexture(uint32_t texture_id, RefPtr<Bitmap> bitmap,
694 const IntRect& dirty_rect)
695 = 0;
696
697 ///
698 /// Destroy a texture.
699 ///
700 /// @param texture_id The texture to destroy.
701 ///
702 virtual void DestroyTexture(uint32_t texture_id) = 0;
703
704 ///
705 /// Get the next available render buffer ID.
706 ///
707 /// This is used to generate a unique render buffer ID for each render buffer created by the
708 /// library. The GPU driver implementation is responsible for mapping these IDs to a native ID.
709 ///
710 /// @note Numbering should start at 1, 0 is reserved for "no render buffer".
711 ///
712 /// @return Returns the next available render buffer ID.
713 ///
714 virtual uint32_t NextRenderBufferId() = 0;
715
716 ///
717 /// Create a render buffer with certain ID and buffer description.
718 ///
719 /// @param render_buffer_id The render buffer ID to use for the new render buffer.
720 ///
721 /// @param buffer The render buffer description.
722 ///
723 virtual void CreateRenderBuffer(uint32_t render_buffer_id, const RenderBuffer& buffer) = 0;
724
725 ///
726 /// Destroy a render buffer.
727 ///
728 /// @param render_buffer_id The render buffer to destroy.
729 ///
730 virtual void DestroyRenderBuffer(uint32_t render_buffer_id) = 0;
731
732 ///
733 /// Get the next available geometry ID.
734 ///
735 /// This is used to generate a unique geometry ID for each geometry created by the library. The
736 /// GPU driver implementation is responsible for mapping these IDs to a native ID.
737 ///
738 /// @note Numbering should start at 1, 0 is reserved for "no geometry".
739 ///
740 /// @return Returns the next available geometry ID.
741 ///
742 virtual uint32_t NextGeometryId() = 0;
743
744 ///
745 /// Create geometry with certain ID and vertex/index data.
746 ///
747 /// @param geometry_id The geometry ID to use for the new geometry.
748 ///
749 /// @param vertices The vertex buffer data.
750 ///
751 /// @param indices The index buffer data.
752 ///
753 /// @warning A deep copy of the vertex/index data should be made if you are uploading it to the
754 /// GPU asynchronously, it will not persist beyond this call.
755 ///
756 virtual void CreateGeometry(uint32_t geometry_id, const VertexBuffer& vertices,
757 const IndexBuffer& indices)
758 = 0;
759
760 ///
761 /// Update existing geometry with new vertex/index data.
762 ///
763 /// @param geometry_id The geometry to update.
764 ///
765 /// @param vertices The new vertex buffer data.
766 ///
767 /// @param indices The new index buffer data.
768 ///
769 /// @warning A deep copy of the vertex/index data should be made if you are uploading it to the
770 /// GPU asynchronously, it will not persist beyond this call.
771 ///
772 virtual void UpdateGeometry(uint32_t geometry_id, const VertexBuffer& vertices,
773 const IndexBuffer& indices)
774 = 0;
775
776 ///
777 /// Destroy geometry.
778 ///
779 /// @param geometry_id The geometry to destroy.
780 ///
781 virtual void DestroyGeometry(uint32_t geometry_id) = 0;
782
783 ///
784 /// Update the pending command list with commands to execute on the GPU.
785 ///
786 /// Commands are dispatched to the GPU driver asynchronously via this method. The GPU driver
787 /// implementation should consume these commands and execute them at an appropriate time.
788 ///
789 /// You must execute every command in every list, in the order the lists and their commands
790 /// were given. You may execute a list later than this call (eg, on your own render thread). If
791 /// you do, add each new list after any you haven't executed yet (never replace one), and apply
792 /// the create, update, and destroy calls the library makes after this call only after that list
793 /// has executed.
794 ///
795 /// @param list The list of commands to execute.
796 ///
797 /// @warning Implementations should make a deep copy of the command list, it will not persist
798 /// beyond this call.
799 ///
800 virtual void UpdateCommandList(const CommandList& list) = 0;
801
802 ///
803 /// Report this driver's optional capabilities.
804 ///
805 /// The library calls this method to query optional features and device limits (eg, partial
806 /// redraws of the View and native sampling of block-compressed formats).
807 ///
808 /// The library reads this once and caches the result, so the capabilities you report must not
809 /// change afterward.
810 ///
811 /// @param caps A zero-initialized struct to fill in. Set only what this driver supports--
812 /// leave the rest zero.
813 ///
814 /// \parblock
815 /// @note The default implementation is empty and reports no capabilities.
816 /// \endparblock
817 ///
818 /// \parblock
819 /// @note Rendering remains correct if you do not implement this method, but performance
820 /// is reduced. When `supports_partial_redraw` is unset, the library clears and
821 /// redraws the entire View on every composite. The library also decompresses
822 /// block-compressed textures before upload.
823 /// \endparblock
824 ///
825 /// @see GPUDeviceCaps::supports_partial_redraw
826 ///
827 virtual void GetDeviceCaps(GPUDeviceCaps& caps) { }
828};
829
830} // namespace ultralight
831
832// clang-format on
#define UExport
Definition Exports.h:22
User-defined GPU driver interface.
Definition GPUDriver.h:625
virtual void EndSynchronize()=0
Called after all state has been updated during a call to Renderer::Render().
virtual void BeginSynchronize()=0
Called before any state (eg, CreateTexture(), UpdateTexture(), DestroyTexture(), etc....
virtual void CreateRenderBuffer(uint32_t render_buffer_id, const RenderBuffer &buffer)=0
Create a render buffer with certain ID and buffer description.
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 uint32_t NextRenderBufferId()=0
Get the next available render buffer 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 uint32_t NextTextureId()=0
Get the next available texture 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 DestroyTexture(uint32_t texture_id)=0
Destroy a texture.
virtual void GetDeviceCaps(GPUDeviceCaps &caps)
Report this driver's optional capabilities.
Definition GPUDriver.h:827
virtual void UpdateCommandList(const CommandList &list)=0
Update the pending command list with commands to execute on the GPU.
virtual void DestroyRenderBuffer(uint32_t render_buffer_id)=0
Destroy a render buffer.
virtual void DestroyGeometry(uint32_t geometry_id)=0
Destroy geometry.
virtual uint32_t NextGeometryId()=0
Get the next available geometry ID.
virtual void UpdateGeometry(uint32_t geometry_id, const VertexBuffer &vertices, const IndexBuffer &indices)=0
Update existing geometry with new vertex/index data.
A nullable smart pointer.
Definition RefPtr.h:126
Root namespace for every public Ultralight type, function, and enumeration.
CommandType
The types of commands.
Definition GPUDriver.h:332
@ Flush
Submit pending GPU work before executing the next command.
Definition GPUDriver.h:356
@ ClearRenderBuffer
Clear the specified render buffer.
Definition GPUDriver.h:333
@ DrawGeometry
Draw the specified geometry to the specified render buffer.
Definition GPUDriver.h:334
GPUTextureFlags
Flags passed to GPUDriver::CreateTexture() that tell your driver how a texture will be used.
Definition GPUDriver.h:515
@ kGPUTextureFlag_Immutable
The texture is uploaded once and never changes.
Definition GPUDriver.h:544
@ kGPUTextureFlag_RenderTarget
The texture is a render target (the backing texture for a RenderBuffer).
Definition GPUDriver.h:528
@ kGPUTextureFlag_Antialiased
The render target should be multisampled (antialiased), resolved to a single-sample texture when samp...
Definition GPUDriver.h:535
BlendEquation
Mathematical operations for combining source and destination colors during blending.
Definition GPUDriver.h:221
@ Subtract
Result = (Src * SrcFactor) - (Dest * DestFactor) Subtractive blending - source reduces destination.
Definition GPUDriver.h:225
@ Max
Result = max(Src, Dest) - takes lighter/larger value Note: Ignores blend factors, compares colors dir...
Definition GPUDriver.h:234
@ Min
Result = min(Src, Dest) - takes darker/smaller value Note: Ignores blend factors, compares colors dir...
Definition GPUDriver.h:231
@ RevSubtract
Result = (Dest * DestFactor) - (Src * SrcFactor) Reverse subtractive blending - destination reduces s...
Definition GPUDriver.h:228
@ Add
Result = (Src * SrcFactor) + (Dest * DestFactor) Standard additive blending - most common operation.
Definition GPUDriver.h:222
BlendFactor
Blend factors that define how source and destination colors are weighted during blending.
Definition GPUDriver.h:194
@ One
Factor of (1, 1, 1, 1) - uses this color at full intensity.
Definition GPUDriver.h:196
@ SrcColor
Source-based factors (use the incoming pixel shader output).
Definition GPUDriver.h:199
@ DestAlpha
Factor of (Ad, Ad, Ad, Ad) - multiply all channels by destination alpha.
Definition GPUDriver.h:207
@ InvSrcAlpha
Factor of (1-As, 1-As, 1-As, 1-As) - multiply by inverse source alpha.
Definition GPUDriver.h:202
@ SrcAlphaSaturate
Special factors.
Definition GPUDriver.h:211
@ InvDestColor
Factor of (1-Rd, 1-Gd, 1-Bd, 1-Ad) - multiply by inverse dest color.
Definition GPUDriver.h:206
@ DestColor
Destination-based factors (use the existing render buffer color).
Definition GPUDriver.h:205
@ InvDestAlpha
Factor of (1-Ad, 1-Ad, 1-Ad, 1-Ad) - multiply by inverse dest alpha.
Definition GPUDriver.h:208
@ SrcAlpha
Factor of (As, As, As, As) - multiply all channels by source alpha.
Definition GPUDriver.h:201
@ Zero
Factor of (0, 0, 0, 0) - completely removes this color's contribution.
Definition GPUDriver.h:195
@ InvSrcColor
Factor of (1-Rs, 1-Gs, 1-Bs, 1-As) - multiply by inverse source color.
Definition GPUDriver.h:200
GPUCompressedFormat
Optional GPU compressed-texture format families.
Definition GPUDriver.h:400
@ kGPUCompressedFormat_BC1_BC3
BC1, BC2, and BC3 (also known as DXT1 / DXT3 / DXT5).
Definition GPUDriver.h:402
@ kGPUCompressedFormat_BC7
BC7.
Definition GPUDriver.h:405
ShaderType
Shader program types.
Definition GPUDriver.h:140
@ FillPhoton
Shader program for analytic vector rendering (Photon).
Definition GPUDriver.h:169
@ FillPhotonGrid
Shader program for grid-based analytic vector rendering (Photon).
Definition GPUDriver.h:181
@ FillPath
Shader program for filling tessellated path geometry.
Definition GPUDriver.h:142
@ FilterBlur
Shader program for blur CSS/SVG filters.
Definition GPUDriver.h:144
@ FilterDropShadow
Shader program for drop-shadow CSS/SVG filters.
Definition GPUDriver.h:145
@ Fill
Shader program for filling quad geometry.
Definition GPUDriver.h:141
@ FilterBasic
Shader program for basic CSS/SVG filters.
Definition GPUDriver.h:143
VertexBufferFormat
Vertex buffer formats.
Definition GPUDriver.h:92
@ _2f_4ub_2f
Vertex_2f_4ub_2f (used for path rendering).
Definition GPUDriver.h:93
@ _2f_2ui
Vertex_2f_2ui (used for instanced cell rendering).
Definition GPUDriver.h:95
@ _2f_4ub_2f_2f_28f
Vertex_2f_4ub_2f_2f_28f (used for quad rendering).
Definition GPUDriver.h:94
uint32_t IndexType
Vertex index type.
Definition GPUDriver.h:112
A command to execute on the GPU.
Definition GPUDriver.h:369
GPUState gpu_state
The current GPU state.
Definition GPUDriver.h:371
CommandType command_type
The type of command to dispatch.
Definition GPUDriver.h:370
uint32_t indices_count
The number of indices. (used with CommandType::DrawGeometry).
Definition GPUDriver.h:373
uint32_t geometry_id
The geometry ID to bind. (used with CommandType::DrawGeometry).
Definition GPUDriver.h:372
uint32_t indices_offset
The index to start from. (used with CommandType::DrawGeometry).
Definition GPUDriver.h:374
List of commands to execute on the GPU.
Definition GPUDriver.h:382
Command * commands
The raw command list data.
Definition GPUDriver.h:384
uint32_t size
The number of commands in the list.
Definition GPUDriver.h:383
Optional capabilities reported by a GPUDriver.
Definition GPUDriver.h:426
uint32_t max_texture_dimension
The largest width or height, in pixels, of a texture or render target this driver can create.
Definition GPUDriver.h:451
uint32_t supports_msaa
Nonzero if this driver can allocate multisampled (antialiased) render targets (see kGPUTextureFlag_An...
Definition GPUDriver.h:439
uint32_t compressed_formats
Bitmask of supported compressed-texture families (see GPUCompressedFormat).
Definition GPUDriver.h:432
uint32_t max_msaa_samples
The sample count this driver uses for multisampled render targets (see supports_msaa),...
Definition GPUDriver.h:462
uint32_t supports_partial_redraw
Whether or not the library may redraw only the changed region of a View's render target.
Definition GPUDriver.h:508
uint32_t max_geometry_size
The largest size, in bytes, of a single vertex or index buffer the engine will build for this driver.
Definition GPUDriver.h:475
The state of the GPU for a given draw command.
Definition GPUDriver.h:245
uint32_t viewport_height
Viewport height in pixels.
Definition GPUDriver.h:250
BlendFactor blend_dst_factor
The blend factor for the destination color (render buffer).
Definition GPUDriver.h:274
Matrix4x4 clip[8]
The clip stack (passed to the pixel shader via uniforms).
Definition GPUDriver.h:316
uint32_t texture_3_id
The texture id to bind to slot #3. (Will be 0 if none).
Definition GPUDriver.h:294
uint32_t texture_1_id
The texture id to bind to slot #1. (Will be 0 if none).
Definition GPUDriver.h:288
uint32_t texture_2_id
The texture id to bind to slot #2. (Will be 0 if none).
Definition GPUDriver.h:291
IntRect scissor_rect
The scissor rect to use for scissor testing (units in pixels).
Definition GPUDriver.h:322
bool enable_blend
Whether or not we should enable blending for the current draw command.
Definition GPUDriver.h:262
Matrix4x4 transform
Transform matrix– you should multiply this with the screen-space orthographic projection matrix then ...
Definition GPUDriver.h:254
uint32_t render_buffer_id
The render buffer to use for the current draw command.
Definition GPUDriver.h:285
bool enable_texturing
Whether or not we should enable texturing for the current draw command.
Definition GPUDriver.h:257
uint32_t texture_4_id
The texture id to bind to slot #4.
Definition GPUDriver.h:301
bool enable_scissor
Whether or not scissor testing should be used for the current draw command.
Definition GPUDriver.h:319
ShaderType shader_type
The vertex/pixel shader program pair to use for the current draw command.
Definition GPUDriver.h:282
BlendFactor blend_src_factor
The blend factor for the source color (pixel shader output).
Definition GPUDriver.h:268
BlendEquation blend_equation
The mathematical equation used to combine the source and destination colors.
Definition GPUDriver.h:279
uint8_t clip_size
The clip size (passed to the pixel shader via uniforms).
Definition GPUDriver.h:313
vec4 uniform_vector[8]
The uniform vectors (passed to the pixel shader via uniforms).
Definition GPUDriver.h:310
float uniform_scalar[8]
The uniform scalars (passed to the pixel shader via uniforms).
Definition GPUDriver.h:307
int32_t uniform_integer[8]
The uniform integers (passed to the pixel shader via uniforms).
Definition GPUDriver.h:304
uint32_t viewport_width
Viewport width in pixels.
Definition GPUDriver.h:247
Index buffer description.
Definition GPUDriver.h:123
uint32_t size
The size of the index buffer in bytes.
Definition GPUDriver.h:124
uint8_t * data
The raw index buffer data.
Definition GPUDriver.h:125
Integer Rectangle Helper.
Definition Geometry.h:533
4x4 Matrix Helper
Definition Matrix.h:15
Render buffer description.
Definition GPUDriver.h:31
bool has_depth_buffer
Currently unused, always false.
Definition GPUDriver.h:36
uint32_t texture_id
The backing texture for this RenderBuffer.
Definition GPUDriver.h:32
uint32_t width
The width of the RenderBuffer texture.
Definition GPUDriver.h:33
bool has_stencil_buffer
Currently unused, always false.
Definition GPUDriver.h:35
uint32_t height
The height of the RenderBuffer texture.
Definition GPUDriver.h:34
Vertex layout for instance vertices.
Definition GPUDriver.h:77
uint32_t header_addr
Cell header texel address in the index data page.
Definition GPUDriver.h:79
uint32_t path_slot
Per-path constant-table slot (low bits) plus flags.
Definition GPUDriver.h:80
float pos[2]
Vertex position (x, y) in pixels.
Definition GPUDriver.h:78
Vertex layout for quad vertices.
Definition GPUDriver.h:57
float obj[2]
Object-space coordinates (used for anti-aliasing).
Definition GPUDriver.h:61
float data2[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:64
float data3[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:65
float data1[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:63
float tex[2]
Texture coordinates (u, v).
Definition GPUDriver.h:60
float data4[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:66
unsigned char color[4]
Vertex color (RGBA, 8 bits per channel).
Definition GPUDriver.h:59
float data5[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:67
float data0[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:62
float pos[2]
Vertex position (x, y) in pixels.
Definition GPUDriver.h:58
float data6[4]
Per-vertex shader data (shader-specific).
Definition GPUDriver.h:68
Vertex layout for path vertices.
Definition GPUDriver.h:45
float obj[2]
Object-space coordinates (used for anti-aliasing).
Definition GPUDriver.h:48
unsigned char color[4]
Vertex color (RGBA, 8 bits per channel).
Definition GPUDriver.h:47
float pos[2]
Vertex position (x, y) in pixels.
Definition GPUDriver.h:46
Vertex buffer description.
Definition GPUDriver.h:103
VertexBufferFormat format
The format of the vertex buffer.
Definition GPUDriver.h:104
uint32_t size
The size of the vertex buffer in bytes.
Definition GPUDriver.h:105
uint8_t * data
The raw vertex buffer data.
Definition GPUDriver.h:106
4D Vector Helper
Definition Geometry.h:280