dymokomi/luce-canvas
Source of release 0.5.1
0.5.1 / src / tiles / reading.lucb
#==============================================================================================
#
# tiles/reading - Many cells read back at once
#
# DESCRIPTION:
# `read_cells` reads a list of cells through two of the device's read batches: while the
# caller works through one batch's cells, the next batch is already on the GPU. Each batch
# takes as many tiles as a readback slot holds (64 at 256 pixels in rgba16f), so a whole
# 360-megapixel layer is about 90 submissions and waits rather than one per tile. Every
# reader of layer pixels (whole reads, single cells, bounds, the wand, heal) goes
# through here. A tile with a copy in RAM is read from there, with no GPU work at all;
# a whole tile read from the GPU leaves such a copy behind when the governor has room
# (tiles/residency), so the next reader, or evicting it, costs nothing.
#
#==============================================================================================
## A cell of the canvas grid.
pub struct Cell:
pub var column: u32
pub var row: u32
## One batch's share of the list: cells `first..<last`, and where each landed in
## the batch (`empty_cell` for a cell with no tile, `ram_cell` for one read
## from its RAM copy, `sources` holding the tile).
struct CellBatch:
var batch: gpu.ReadBatch
var first: usize
var last: usize
var offsets: usize[]
var sources: Tile*?[]
var submitted: bool
var pending: bool
let empty_cell: usize = 0xffffffffffffffff
let ram_cell: usize = 0xfffffffffffffffe
## Read `cells` of `tiles` back and call `visit(context, cell, bytes)` for each,
## in the list's order. `bytes` are the cell's rgba16f texels, rows 256 texels
## (2048 bytes) apart, as many rows as the cell has; empty for a cell with no
## tile (transparent). They are valid only during the call. Main thread only.
## With `warm`, whole tiles read back from the GPU are kept in RAM too while
## the governor has room (a later read is free); a one-pass reader (a save)
## passes false, so it leaves memory as it found it.
pub func read_cells(tiles: const Tiles*, cells: const Cell[], context: void*?, visit: func(void*?, Cell, const u8[]) -> unit!, warm: bool = true) -> !:
if cells.length == 0:
return
let device = tiles.device()
var batches: CellBatch[2] = [CellBatch(batch = try gpu.ReadBatch.begin(device)), CellBatch(batch = gpu.ReadBatch())]
defer release_cell_batch(&batches[0])
batches[1].batch = try gpu.ReadBatch.begin(device)
defer release_cell_batch(&batches[1])
let per_batch = batches[0].batch.capacity() // cell_bytes()
if per_batch == 0:
error(invalid, "a read batch cannot hold one tile")
for index in 0..<(usize)2:
batches[index].offsets = try new usize[per_batch] --- in memory.heap
batches[index].sources = try new Tile*?[per_batch] --- in memory.heap
var next: usize = 0
next = try fill_cell_batch(tiles, cells, &batches[0], next)
if next < cells.length:
next = try fill_cell_batch(tiles, cells, &batches[1], next)
var turn: usize = 0
while batches[turn].pending:
let current = &batches[turn]
if current.submitted:
try current.batch.wait()
for index in current.first..<current.last:
let offset = current.offsets[index - current.first]
let cell = cells[index]
if offset == empty_cell:
var nothing: u8[]
try visit(context, cell, nothing)
continue
let rows = (usize)tiles.region(cell.column, cell.row).height
let length = rows * (usize)tile_size * 8
if offset == ram_cell:
let source = current.sources[index - current.first] else trap("a RAM cell lost its tile")
try visit(context, cell, source.ram[..<length])
continue
let bytes = try current.batch.bytes(offset, length)
# A whole tile read anyway is kept in RAM too while there is room.
if let source = current.sources[index - current.first]:
if warm and rows == (usize)tile_size:
keep_warm(source, bytes)
try visit(context, cell, bytes)
current.pending = false
if next < cells.length:
next = try fill_cell_batch(tiles, cells, current, next)
turn = 1 - turn
## The bytes one cell takes in a batch.
func cell_bytes() -> usize:
return (usize)tile_size * (usize)tile_size * 8
## Record cells from `next` on into `target` until it is full, submit it, and
## return where the list continues.
func fill_cell_batch(tiles: const Tiles*, cells: const Cell[], target: CellBatch*, next: usize) -> usize!:
try target.batch.reset()
target.first = next
target.submitted = false
try fetch_batch(tiles, cells, next, target.offsets.length)
var at = next
while at < cells.length and at - next < target.offsets.length:
let cell = cells[at]
target.sources[at - next] = none
if let tile = tiles.tile(cell.column, cell.row):
target.sources[at - next] = tile
if not tile.on_gpu:
# Neither on the GPU nor in RAM: its slot in the scratch file.
try ensure_ram(tile)
if tile.ram.length > 0:
target.offsets[at - next] = ram_cell
else:
let rows = tiles.region(cell.column, cell.row).height
let offset = (try target.batch.reserve(cell_bytes())) else break
try target.batch.copy(tile.texture, gpu.Region(0, 0, tile_size, rows), offset)
target.offsets[at - next] = offset
else:
target.offsets[at - next] = empty_cell
at += 1
target.last = at
target.pending = true
if target.batch.copies() > 0:
try target.batch.submit()
target.submitted = true
return at
## The next `most` cells from `next` that are only somewhere slower, brought
## into RAM together (tiles/gathering) rather than one by one as the batch is filled.
func fetch_batch(tiles: const Tiles*, cells: const Cell[], next: usize, most: usize) -> !:
try gather_cells(tiles, cells[next..<min_usize(cells.length, next + most)])
func release_cell_batch(target: CellBatch*):
target.batch.finish()
if target.offsets.length > 0:
free(target.offsets) in memory.heap
var none_left: usize[]
target.offsets = none_left
if target.sources.length > 0:
free(target.sources) in memory.heap
var no_sources: Tile*?[]
target.sources = no_sources
# mark: The Tiles readers on it ===============================================================
## `read_cell`'s visitor: one cell into 256 by 256 straight RGBA f32 samples.
func cell_to_floats(context: void*?, cell: Cell, bytes: const u8[]) -> !:
_ = cell
let pixels = *(f32[]*)(context else trap("a cell read lost its buffer"))
halves_to_floats(bytes, pixels, (usize)tile_size, 0, 0, (usize)tile_size)
## Where a whole read lands: the document's samples and its width.
struct WholeRead:
var pixels: f32[]
var width: usize
var height: usize
## `read`'s visitor: a cell into its place among the document's samples.
func cell_into_whole(context: void*?, cell: Cell, bytes: const u8[]) -> !:
let whole = (WholeRead*)(context else trap("a layer read lost its buffer"))
let left = (usize)cell.column * (usize)tile_size
let top = (usize)cell.row * (usize)tile_size
let columns = min_usize((usize)tile_size, whole.width - left)
halves_to_floats(bytes, whole.pixels, columns, left, top, whole.width)
## Half-float texels (rows 256 texels apart) to f32 samples at (`left`, `top`)
## of `pixels`, `stride` samples of four wide, `columns` of each row. Empty
## `bytes` leave the zeros already there.
func halves_to_floats(bytes: const u8[], pixels: f32[], columns: usize, left: usize, top: usize, stride: usize):
let rows = bytes.length // ((usize)tile_size * 8)
for y in 0..<rows:
for x in 0..<columns:
let source = (y * (usize)tile_size + x) * 8
let destination = ((top + y) * stride + left + x) * 4
for channel in 0..<(usize)4:
pixels[destination + channel] = from_half((u16)bytes[source + channel * 2] | ((u16)bytes[source + channel * 2 + 1] << 8))
## What `content_bounds` has found so far.
struct BoundsRead:
var bounds: Bounds
var found: bool
var width: u32
var height: u32
## `content_bounds`' visitor: grow the box by every pixel of the cell with any alpha.
func cell_into_bounds(context: void*?, cell: Cell, bytes: const u8[]) -> !:
let read = (BoundsRead*)(context else trap("a bounds read lost its box"))
let left = (i64)(cell.column * tile_size)
let top = (i64)(cell.row * tile_size)
let columns = (usize)min_u32(tile_size, read.width - cell.column * tile_size)
let rows = bytes.length // ((usize)tile_size * 8)
for y in 0..<rows:
for x in 0..<columns:
let source = (y * (usize)tile_size + x) * 8
# Any alpha at all: the half's bits but the sign.
if ((u16)bytes[source + 6] | ((u16)bytes[source + 7] << 8)) & 0x7fff == 0:
continue
let px = left + (i64)x
let py = top + (i64)y
read.found = true
if px < read.bounds.left: read.bounds.left = px
if py < read.bounds.top: read.bounds.top = py
if px + 1 > read.bounds.right: read.bounds.right = px + 1
if py + 1 > read.bounds.bottom: read.bounds.bottom = py + 1
## Collect into `list` the painted cells of ring `ring` of `cells` (0 the
## outermost) that do not lie wholly inside `read`'s box so far: how many.
func ring_cells(tiles: const Tiles*, cells: CellRange, ring: i64, read: const BoundsRead*, list: CellList*) -> usize!:
var count: usize = 0
for row in cells.top + ring..<cells.bottom - ring:
# Inner rows of the ring hold only its two side cells.
let edge = row == cells.top + ring or row == cells.bottom - ring - 1
var column = cells.left + ring
while column < cells.right - ring:
if tiles.painted((u32)column, (u32)row) and not inside_bounds(tiles, read, (u32)column, (u32)row):
if count == list.cells.length:
let grown = try new Cell[list.cells.length * 2 + 64] --- in memory.heap
memory.copy(grown, list.cells, count)
list.release()
list.cells = grown
list.cells[count] = Cell(column = (u32)column, row = (u32)row)
count += 1
if edge or column == cells.right - ring - 1:
column += 1
else:
column = cells.right - ring - 1
return count
## A growable list of cells on the heap.
struct CellList:
var cells: Cell[]
func release():
if self.cells.length > 0:
free(self.cells) in memory.heap
var none_left: Cell[]
self.cells = none_left
## Whether cell (`column`, `row`) lies wholly inside the box found so far.
func inside_bounds(tiles: const Tiles*, read: const BoundsRead*, column: u32, row: u32) -> bool:
if not read.found:
return false
let area = tiles.region(column, row)
let left = (i64)(column * tile_size)
let top = (i64)(row * tile_size)
return left >= read.bounds.left and top >= read.bounds.top and left + (i64)area.width <= read.bounds.right and top + (i64)area.height <= read.bounds.bottom