dymokomi/luce-browser-render
Source of release 0.6.2
0.6.2 / src / gpu_player / compositor.lucb
#==============================================================================================
#
# compositor - tiles kept across frames, drawn when missing, composited every frame
#
# DESCRIPTION:
# A GpuCompositor belongs to one view. Each frame it takes the display list and scroll
# state the page presented and draws them onto a luce-gpu target:
#
# 1. a new display list is cut into layers (layers.lucb) and every tile is dropped
# (their textures go back to a pool);
# 2. for each layer, the tiles of its plane that the viewport shows are found by key:
# the layer's number, what its pixels depend on (gpu_layer_key) and the tile's place.
# A tile not kept yet is drawn: recorded by the GPU player and replayed, or, when
# the recording gives up, drawn by the CPU player and uploaded. A tile on which
# nothing draws keeps no texture;
# 3. every visible tile is composited, layer by layer in paint order, moved by its
# layer's scroll offset. Layers blend in the encoded space, as the CPU player
# blends them into one surface: on a target that blends on encoded values (an
# encoded surface, or an rgba8_linear texture) tiles go straight onto it; on
# any other they go into a frame texture of the viewport's size, which is then
# drawn onto the target decoded for its linear-light pixels
# (shaders/composite.frag).
#
# A scroll therefore moves tiles and draws only those it uncovers. Tiles not used for a
# while are released past a budget; textures are reused through a small pool.
#
# Copyright (c) 2026 the luce-browser authors.
# SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================
## Tiles kept (with textures) before the least recently used are released: 96 tiles of 1 MiB.
pub let gpu_tile_budget: usize = 96
## Textures kept for reuse when tiles are dropped.
let gpu_pool_limit: usize = 16
## One kept tile: its key, its place in its layer's plane, its texture (none when empty), and
## the frame it was last used in.
struct GpuTile:
var key: u64
var x: i32
var y: i32
var texture: gpu.Texture?
var used: u64
## The GPU compositor of one view (see the header).
pub struct GpuCompositor:
var device: gpu.Device?
## The pipelines (in memory.heap), which the player draws with too.
var pipelines: GpuPipelines*?
var atlas: GpuAtlas
var images: GpuImageCache
var player: DisplayListPlayerGpu*?
## The allocator the CPU player draws with (the caller's; see gpu_cpu_tile).
var cpu_allocator: memory.Allocator?
var pixels: u8[]
var list: const display_list.DisplayList*?
var layers: ak.Vector[GpuLayer]
var tiles: ak.Vector[GpuTile]
var keys: GpuIndexMap
var pool: ak.Vector[gpu.Texture]
var frame: u64
## The viewport's frame texture (see step 3), and its size.
var frame_texture: gpu.Texture?
var frame_width: i32
var frame_height: i32
## A compositor with nothing drawn yet.
pub func gpu_compositor_create() -> GpuCompositor*:
return (new GpuCompositor() in memory.heap) else trap("gpu_player: out of memory")
## Releases everything the compositor holds (main thread, as every GPU call).
pub func gpu_compositor_destroy(this: GpuCompositor*):
with memory.heap:
gpu_compositor_drop_device(this)
if this.pixels.length > 0:
free(this.pixels) in memory.heap
free(this) in memory.heap
## Releases the tiles, caches and pipelines (and the device they were on).
func gpu_compositor_drop_device(this: GpuCompositor*):
gpu_compositor_drop_tiles(this)
if let texture = this.frame_texture:
var handle = texture
handle.destroy()
this.frame_texture = none
for texture in ak.vector_span(&this.pool):
var handle = texture
handle.destroy()
ak.vector_clear(&this.pool)
this.atlas.release()
this.images.release()
if let pipelines = this.pipelines:
pipelines.release()
free(pipelines) in memory.heap
this.pipelines = none
if let player = this.player:
display_list_player_gpu_destroy(player)
this.player = none
if let device = this.device:
var handle = device
handle.destroy()
this.device = none
gpu_player_stats_the.resident_tiles = 0
gpu_player_stats_the.resident_bytes = 0
## Drops every tile, keeping up to the pool's limit of their textures.
func gpu_compositor_drop_tiles(this: GpuCompositor*):
for tile in ak.vector_span(&this.tiles):
if let texture = tile.texture:
gpu_compositor_recycle(this, texture)
ak.vector_clear(&this.tiles)
this.keys.clear()
gpu_player_stats_the.resident_tiles = 0
## Gives a tile's texture back: to the pool, or released when the pool is full.
func gpu_compositor_recycle(this: GpuCompositor*, texture: gpu.Texture):
if ak.vector_size(&this.pool) < gpu_pool_limit:
ak.vector_append_t(&this.pool, texture)
return
var handle = texture
handle.destroy()
## A tile texture: from the pool, or new.
func gpu_compositor_texture(this: GpuCompositor*, device: gpu.Device) -> gpu.Texture!:
if not ak.vector_is_empty(&this.pool):
return ak.vector_take_last(&this.pool)
return try gpu.Texture.create(device, (u32)gpu_tile_size, (u32)gpu_tile_size, gpu.Format.rgba8_linear)
## Opens what drawing needs on `target`'s device the first time (or after a device change).
func gpu_compositor_open(this: GpuCompositor*, target: const gpu.RenderTarget*) -> gpu.Device!:
var device = try gpu.device_of(target)
if let current = this.device:
if current.same(&device):
device.destroy()
return current
gpu_compositor_drop_device(this)
this.list = none
this.device = device
let made = try gpu_pipelines_create(device)
let stored = try new GpuPipelines() in memory.heap
*stored = made
this.pipelines = stored
this.player = display_list_player_gpu_create(&this.atlas, &this.images)
if this.pixels.length == 0:
this.pixels = try new u8[(usize)(gpu_tile_size * gpu_tile_size * 4)] --- in memory.heap
return device
# mark: Drawing a frame ==========================================================================
## Draws `list` at `snapshot`'s scroll offsets onto `target`, the page's device pixel (0, 0) at
## the target's top left, one device pixel a backing pixel of the target, covering `width` by
## `height` device pixels.
## Everything the compositor keeps is in the process heap (an engine's collected heap would not
## see the compositor's pointers into it); tiles the CPU player draws are drawn with
## `cpu_allocator`, the heap the engine's painting uses (the process heap when none).
pub func gpu_compositor_draw(this: GpuCompositor*, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, target: const gpu.RenderTarget*,
width: i32, height: i32, cpu_allocator: memory.Allocator? = none) -> !:
if width <= 0 or height <= 0:
return
this.cpu_allocator = cpu_allocator
# The frame's CPU player and tile surface, here where the engine's collector sees them.
var scratch = GpuCpuScratch()
with memory.heap:
try gpu_compositor_draw_frame(this, &scratch, list, snapshot, target, width, height)
## gpu_compositor_draw's work, in the process heap.
func gpu_compositor_draw_frame(this: GpuCompositor*, scratch: GpuCpuScratch*, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, target: const gpu.RenderTarget*,
width: i32, height: i32) -> !:
let extent = try target.size()
let scale = extent.pixel_width / extent.width if extent.width > 0.0 else 1.0
let device = try gpu_compositor_open(this, target)
let target_format = try target.pixel_format()
let direct = target_format == gpu.Format.rgba8_linear or (try target.blending()) == gpu.Blending.encoded
let pipelines = this.pipelines else trap("gpu_player: no pipelines")
let copy = try pipelines.composite_for(device, gpu.Format.rgba8_linear)
let present = try pipelines.composite_for(device, target_format)
if this.list != list:
gpu_compositor_drop_tiles(this)
ak.vector_clear(&this.layers)
this.layers = gpu_layers_of(list)
this.list = list
this.frame += 1
this.images.frame = this.frame
let viewport = GpuRect(width = width, height = height)
if direct:
# Tiles straight onto the target, kept to the viewport, at the target's pixels.
if let texture = this.frame_texture:
var handle = texture
handle.destroy()
this.frame_texture = none
this.frame_width = 0
this.frame_height = 0
let placement = try target.placement()
let page = try target.clipped(gpu.Rect(0.0, 0.0, (f64)width / scale, (f64)height / scale))
defer page.release()
let origin = gfx.IntPoint(m_x = (i32)(placement.x * scale), m_y = (i32)(placement.y * scale))
for layer_index in 0..<ak.vector_size(&this.layers):
let layer = *ak.vector_at(&this.layers, layer_index)
try gpu_compositor_layer(this, scratch, device, list, snapshot, &layer, layer_index, viewport, page.value(), present, origin, scale)
gpu_compositor_evict(this)
return
let frame_texture = try gpu_compositor_frame_texture(this, device, width, height)
let frame = try frame_texture.frame()
defer frame.release()
let canvas = try frame.value().target()
defer canvas.release()
for layer_index in 0..<ak.vector_size(&this.layers):
let layer = *ak.vector_at(&this.layers, layer_index)
try gpu_compositor_layer(this, scratch, device, list, snapshot, &layer, layer_index, viewport, canvas.value(), copy, gfx.IntPoint(), 1.0)
_ = try frame.value().present(gpu.Color(0.0, 0.0, 0.0, 0.0))
# The frame onto the target, decoded.
let placement = try target.placement()
var params = gpu_composite_uniforms((f32)(placement.x * scale), (f32)(placement.y * scale), true)
try gpu.shade(target, present, gpu.Rect(0.0, 0.0, (f64)width / scale, (f64)height / scale), u8[]((u8*)¶ms[0], 12), [frame_texture], gpu.Filter.nearest)
gpu_compositor_evict(this)
## The frame texture for a viewport of `width` by `height` pixels, made again when it changes.
func gpu_compositor_frame_texture(this: GpuCompositor*, device: gpu.Device, width: i32, height: i32) -> gpu.Texture!:
if let texture = this.frame_texture:
if this.frame_width == width and this.frame_height == height:
return texture
var handle = texture
handle.destroy()
this.frame_texture = none
let texture = try gpu.Texture.create(device, (u32)width, (u32)height, gpu.Format.rgba8_linear)
this.frame_texture = texture
this.frame_width = width
this.frame_height = height
return texture
## Draws the tiles `layer` shows in `viewport` (drawing those not kept) into `canvas` with the
## `copy` pipeline: the frame texture's target, or the target itself, whose backing pixels
## start at `origin` and are `scale` to a point.
func gpu_compositor_layer(this: GpuCompositor*, scratch: GpuCpuScratch*, device: gpu.Device, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, layer: const GpuLayer*,
layer_index: usize, viewport: GpuRect, canvas: const gpu.RenderTarget*, copy: gpu.Pipeline, origin: gfx.IntPoint, scale: f64) -> !:
let offset = gpu_layer_offset(layer, snapshot)
let key = gpu_hash(gpu_layer_key(layer, snapshot), (u64)layer_index)
var plane = gpu_layer_snapshot(layer, snapshot)
defer ak.vector_clear(&plane.m_device_offsets)
# The part of the layer's plane the viewport shows.
let visible = viewport.translated(-offset.m_x, -offset.m_y)
let first_column = gpu_floor_div(visible.x, gpu_tile_size)
let first_row = gpu_floor_div(visible.y, gpu_tile_size)
let last_column = gpu_floor_div(visible.x + visible.width - 1, gpu_tile_size)
let last_row = gpu_floor_div(visible.y + visible.height - 1, gpu_tile_size)
let side = (f64)gpu_tile_size / scale
for row in first_row..<last_row + 1:
for column in first_column..<last_column + 1:
let tile = try gpu_compositor_tile(this, scratch, device, list, &plane, layer, key, column * gpu_tile_size, row * gpu_tile_size)
let texture = tile.texture else continue
let x = tile.x + offset.m_x
let y = tile.y + offset.m_y
var params = gpu_composite_uniforms((f32)(x + origin.m_x), (f32)(y + origin.m_y), false)
try gpu.shade(canvas, copy, gpu.Rect((f64)x / scale, (f64)y / scale, side, side), u8[]((u8*)¶ms[0], 12), [texture], gpu.Filter.nearest)
gpu_player_stats_the.composited_tiles += 1
## The tile of `layer` at (`x`, `y`) in its plane for `key`: kept, or drawn now.
func gpu_compositor_tile(this: GpuCompositor*, scratch: GpuCpuScratch*, device: gpu.Device, list: display_list.DisplayList*, plane: const display_list.ScrollStateSnapshot*, layer: const GpuLayer*,
key: u64, x: i32, y: i32) -> GpuTile!:
let tile_key = gpu_hash(gpu_hash(key, (u64)(u32)x), (u64)(u32)y)
if let index = this.keys.get(tile_key):
let kept = ak.vector_at(&this.tiles, (usize)index)
kept.used = this.frame
return *kept
var tile = GpuTile(key = tile_key, x = x, y = y, used = this.frame)
let player = this.player else trap("gpu_player: no player")
# The recording may draw into the tile before it ends (when the atlas makes room).
let texture = try gpu_compositor_texture(this, device)
display_list_player_gpu_begin(player, device, this.pipelines else trap("gpu_player: no pipelines"), texture, gpu_tile_size)
display_list.display_list_player_execute_tile((display_list.DisplayListPlayer*)player, list, plane, none, layer.first, layer.end, gfx.IntPoint(m_x = x, m_y = y))
if let reason = player.fallback():
gpu_player_stats_the.fallbacks[(usize)reason] += 1
let met = player.fallback_reasons()
for kind in 0..<gpu_fallback_count:
if (met >> (u32)kind) & 1 != 0:
gpu_player_stats_the.reasons[kind] += 1
gpu_player_stats_the.cpu_tiles += 1
tile.texture = texture
let origin = gfx.IntPoint(m_x = x, m_y = y)
if let allocator = this.cpu_allocator:
with allocator:
try gpu_cpu_tile(scratch, list, plane, layer, origin, texture, this.pixels)
else:
try gpu_cpu_tile(scratch, list, plane, layer, origin, texture, this.pixels)
elif player.is_empty() and not display_list_player_gpu_flushed(player):
gpu_player_stats_the.empty_tiles += 1
gpu_compositor_recycle(this, texture)
else:
gpu_player_stats_the.gpu_tiles += 1
tile.texture = texture
if not player.is_empty():
let pipelines = this.pipelines else trap("gpu_player: no pipelines")
try gpu_replay_tile(player, pipelines, texture, gpu_tile_size, display_list_player_gpu_flushed(player))
this.keys.put(tile_key, (u32)ak.vector_size(&this.tiles))
ak.vector_append_t(&this.tiles, tile)
return tile
## Releases the least recently used tiles past the budget (never this frame's: a page whose
## frame needs more keeps them), and forgets empty tiles not used for a while.
func gpu_compositor_evict(this: GpuCompositor*):
# When the older tiles were last used, newest first.
var stamps: ak.Vector[u64]
defer ak.vector_clear(&stamps)
var resident: usize = 0
var stale = false
for tile in ak.vector_span_const(&this.tiles):
if tile.texture != none:
resident += 1
if tile.used < this.frame:
ak.vector_append_t(&stamps, tile.used)
elif this.frame - tile.used > 64:
stale = true
let older = ak.vector_span(&stamps)
let current = resident - older.length
let allowed = gpu_tile_budget - current if gpu_tile_budget > current else 0
if older.length <= allowed and not stale:
gpu_compositor_note_memory(this, resident)
return
for i in 1..<older.length:
let value = older[i]
var j = i
while j > 0 and older[j - 1] < value:
older[j] = older[j - 1]
j -= 1
older[j] = value
# Tiles last used at or before `cutoff` go (none when the budget holds them all).
let cutoff: u64 = older[allowed] if allowed < older.length else 0
let dropping = allowed < older.length
var kept: ak.Vector[GpuTile]
resident = 0
for tile in ak.vector_span_const(&this.tiles):
if let texture = tile.texture:
if dropping and tile.used <= cutoff:
gpu_compositor_recycle(this, texture)
continue
resident += 1
elif this.frame - tile.used > 64:
continue
ak.vector_append_t(&kept, tile)
ak.vector_clear(&this.tiles)
this.tiles = kept
this.keys.clear()
for index in 0..<ak.vector_size(&this.tiles):
this.keys.put(ak.vector_at(&this.tiles, index).key, (u32)index)
gpu_compositor_note_memory(this, resident)
## Counts the GPU memory held: resident tiles, pooled textures, images, the atlas and the frame.
func gpu_compositor_note_memory(this: const GpuCompositor*, resident: usize):
let tile_bytes = (u64)(gpu_tile_size * gpu_tile_size * 4)
gpu_player_stats_the.resident_tiles = (u64)resident
let tiles = (u64)(resident + ak.vector_size(&this.pool)) * tile_bytes
let frame = (u64)this.frame_width * (u64)this.frame_height * 4
gpu_player_stats_the.resident_bytes = tiles + this.images.resident_bytes() + (u64)(this.atlas.size * this.atlas.size) + frame
## `a` divided by `b` (positive), rounded down.
func gpu_floor_div(a: i32, b: i32) -> i32:
return a // b if a >= 0 else -((-a + b - 1) // b)