dymokomi/luce-image
Source of release 0.45.0
0.45.0 / src / canvas / package_open.lucb
#==============================================================================================
#
# canvas/package_open - Reading an .l2d document (package_format.lucb)
#
# DESCRIPTION:
# Opening reads the trailer, the manifest and the index, and builds the layers from the
# manifest; no pixels yet, since a document gets its GPU only when it is bound. At the
# bind each layer's tiles come back a batch at a time: read in order from the file,
# inflated and unfiltered across the processors, uploaded in one submission, and the
# memory tiers settle between batches, so a document larger than the GPU (or RAM)
# opens within its budget and nothing the size of the document is ever made. A tile
# stored once for several cells of a layer is uploaded once and shared. Every tile
# loaded stays backed by the file (luce-canvas tiles/backing): past the budgets the
# governor drops it rather than writing it to the scratch file, and reads it back from
# the document when it is wanted again.
#
#==============================================================================================
## An opened file's tables, kept from the open until the document is bound.
struct PackageSource:
var path: str
var blobs: PackageBlob[]
var cells: PackageCell[]
func destroy():
strings.release(self.path)
if self.blobs.length > 0:
free(self.blobs) in memory.heap
if self.cells.length > 0:
free(self.cells) in memory.heap
## Tiles read, inflated and uploaded together.
let load_batch: usize = 32
## Read the trailer and index of the document at `path`; the manifest's bytes
## go to `manifest` (heap, the caller frees).
func read_package(path: str, manifest: u8[]*) -> PackageSource!:
# A Luce string need not end in NUL; the file call gets a copy that does.
let native = try strings.copy(path)
defer strings.release(native)
var file = try files.File.open((c_api.str)native)
defer file.destroy()
let size = (u64)(try file.seek(0, files.SeekOrigin.end))
if size < (u64)(package_header_bytes + package_trailer_bytes):
error(invalid, "not an .l2d document: the file is too short")
var head: u8[16]
try read_at(&file, 0, u8[](&head[0], 16))
if (str)u8[](&head[0], 8) != package_magic:
error(invalid, "not an .l2d document")
if get_u32(u8[](&head[0], 16), 8) != package_version:
error(invalid, "an .l2d document of a version this build does not read")
var tail: u8[64]
let end = u8[](&tail[0], 64)
try read_at(&file, size - (u64)package_trailer_bytes, end)
if (str)end[..<8] != package_trailer_magic:
error(invalid, "the .l2d document is cut short or damaged")
let trailer = PackageTrailer(manifest_offset = get_u64(end, 8), manifest_length = get_u64(end, 16), preview_offset = get_u64(end, 24),
preview_length = get_u64(end, 32), index_offset = get_u64(end, 40), index_length = get_u64(end, 48))
let body = size - (u64)package_trailer_bytes
for (offset, length) in [(trailer.manifest_offset, trailer.manifest_length), (trailer.index_offset, trailer.index_length)]:
if offset > body or length > body - offset or length > ((u64)1 << 31):
error(invalid, "the .l2d document's tables are damaged")
let text = try new u8[(usize)trailer.manifest_length] --- in memory.heap
errdefer free(text) in memory.heap
try read_at(&file, trailer.manifest_offset, text)
let index = try new u8[(usize)trailer.index_length] --- in memory.heap
defer free(index) in memory.heap
try read_at(&file, trailer.index_offset, index)
var source = try parse_index(index, body)
errdefer source.destroy()
source.path = try strings.copy(path)
*manifest = text
return source
## The blob and cell tables from the index's bytes, every offset checked
## against `body` (where the tiles may be) and every cell against the blobs.
func parse_index(index: const u8[], body: u64) -> PackageSource!:
if index.length < 8:
error(invalid, "the .l2d document's index is damaged")
let blob_count = (usize)get_u32(index, 0)
if blob_count > (index.length - 8) // package_blob_bytes:
error(invalid, "the .l2d document's index is damaged")
let at_cells = 4 + blob_count * package_blob_bytes
let cell_count = (usize)get_u32(index, at_cells)
if at_cells + 4 + cell_count * package_cell_bytes > index.length:
error(invalid, "the .l2d document's index is damaged")
var source = PackageSource(path = "")
source.blobs = try new PackageBlob[blob_count if blob_count > 0 else 1] --- in memory.heap
source.cells = try new PackageCell[cell_count if cell_count > 0 else 1] --- in memory.heap
let most = (u64)flate.deflate_bound((usize)tile_size * tile_row_bytes)
for blob in 0..<blob_count:
let at = 4 + blob * package_blob_bytes
let found = PackageBlob(offset = get_u64(index, at), length = get_u32(index, at + 8), rows = get_u16(index, at + 12), filter = index[at + 14])
if found.rows == 0 or (u32)found.rows > tile_size or (found.filter != tile_filter_sub and found.filter != coverage_filter) or (u64)found.length > most or found.offset > body or (u64)found.length > body - found.offset:
source.destroy()
error(invalid, "the .l2d document's tile table is damaged")
source.blobs[blob] = found
for cell in 0..<cell_count:
let at = at_cells + 4 + cell * package_cell_bytes
let found = PackageCell(layer = get_u32(index, at), plane = get_u32(index, at + 4), column = (i32)get_u32(index, at + 8),
row = (i32)get_u32(index, at + 12), blob = get_u32(index, at + 16))
# A channel's cell selected throughout has no record.
if found.plane > plane_channel_full or (found.plane != plane_channel_full and (usize)found.blob >= blob_count):
source.destroy()
error(invalid, "the .l2d document's cell table is damaged")
source.cells[cell] = found
source.blobs = source.blobs[..<blob_count]
source.cells = source.cells[..<cell_count]
return source
## `Canvas.open` of an `.l2d`: the manifest's layers, their tiles waiting in
## the file until the document is bound.
func open_package(path: str) -> interop.Reference[Canvas]!:
var text: u8[]
var source = try read_package(path, &text)
errdefer source.destroy()
defer free(text) in memory.heap
let manifest = try prism.Document.decode(text)
defer manifest.release()
let doc = manifest.value()
let width = try get_integer(doc, "/document", "width")
let height = try get_integer(doc, "/document", "height")
var reservation = try interop.Reservation[Canvas](canvas_type)
errdefer reservation.cancel()
let native = try new Canvas(width, height) in memory.heap
errdefer native.close()
try native.set_resolution(try get_number(doc, "/document", "resolution"))
# The layer the application had selected; a file without it selects none.
native.selected_layer_index = get_integer(doc, "/document", "selected") catch failure:
_ = failure
recover -1
let profile_value = try doc.get("/document", "profile")
defer profile_value.release()
native.set_profile(try profile_value.value().text_at())
try native.set_linear_blend(try get_integer(doc, "/document", "linear_blend") != 0)
let total = doc.child_count("/layers")
# The ids the file's layers get, for groups named by their place in it.
let ids = try new i64[total if total > 0 else 1] --- in memory.heap
defer free(ids) in memory.heap
for index in 0..<total:
let element = doc.child_at("/layers", index) else error(invalid, "a layer element is missing")
let name_value = try doc.get(element, "name")
defer name_value.release()
let group = (try get_integer(doc, element, "group")) != 0
let adjustment = try get_integer(doc, element, "adjustment")
var id: i64 = 0
if adjustment >= 0:
for parameter in 0..<parameter_count:
var key_buffer: u8[32]
try native.set_adjustment((i64)parameter, try get_number(doc, element, try format_file(key_buffer, "a", parameter, "")))
if adjustment == (i64)curves:
try read_curves(doc, element, native)
id = try native.add_adjustment_layer(try name_value.value().text_at(), adjustment)
native.clear_adjustments()
elif group:
id = try native.add_group(try name_value.value().text_at())
else:
id = try native.add_layer(try name_value.value().text_at())
ids[index] = id
try native.set_layer(id, (try get_integer(doc, element, "visible")) != 0, try get_number(doc, element, "opacity"), try get_integer(doc, element, "blend"))
try native.set_clipped(id, (try get_integer(doc, element, "clipped")) != 0)
# A layer without styles has no style fields.
let styled = get_number(doc, element, "shadow") catch failure:
_ = failure
recover -1.0
if styled >= 0.0:
let names = style_field_names()
for field in 0..<style_field_count:
try native.set_style_value(id, field, try get_number(doc, element, names[(usize)field]))
let slot = try native.index((u64)id)
# Its tiles come from the file when the document is bound.
native.records[slot].stored = (i64)index
if not group and adjustment < 0:
try read_type(doc, element, native, id)
try load_elements(doc, element, native, id)
try load_graph(doc, element, native, id)
if (try get_integer(doc, element, "mask")) != 0:
try native.set_mask(id, true)
native.records[slot].mask_linked = (try get_integer(doc, element, "mask_linked")) != 0
native.records[slot].mask_enabled = (try get_integer(doc, element, "mask_enabled")) != 0
# The guides.
for index in 0..<doc.child_count("/guides"):
let element = doc.child_at("/guides", index) else break
_ = try native.add_guide((try get_integer(doc, element, "vertical")) != 0, try get_number(doc, element, "position"))
try read_channels(native, &source, doc)
# Groups come after their layers in the file, so layers go into them once all are read.
for index in 0..<total:
let element = doc.child_at("/layers", index) else error(invalid, "a layer element is missing")
let parent = try get_integer(doc, element, "parent")
if parent > 0 and parent <= (i64)total:
try native.move_into(ids[index], ids[(usize)parent - 1], -1)
let kept = try new PackageSource in memory.heap
*kept = source
native.package = kept
return reservation.publish(native, memory.heap)
## At the bind: every stored layer's tiles from the file, then the file's
## tables go.
func load_package(canvas: Canvas*) -> !:
let source = canvas.package else return
canvas.package = none
defer:
source.destroy()
free(source) in memory.heap
let document = canvas.document else trap("loading an unbound document")
var file = try files.File.open((c_api.str)source.path)
defer file.destroy()
# The file backs the tiles loaded from it; the canvas keeps a hold on it.
let backing = try open_tile_source(source.path, none, decode_record)
if let previous = canvas.backing:
release_tile_source(previous)
canvas.backing = backing
for index in 0..<canvas.count:
let stored = canvas.records[index].stored
if stored < 0:
continue
canvas.records[index].stored = -1
let id = canvas.records[index].id
if not canvas.records[index].group and canvas.records[index].adjustment < 0:
if let tiles = try load_tiles(canvas, source, &file, backing, (u32)stored, plane_pixels):
try document.set_tiles(id, tiles)
let layer = document.find(id) else trap("a loaded layer is gone")
try build_levels(canvas, layer.tiles() else trap("a loaded layer has no pixels"), false)
if canvas.records[index].masked:
if let mask = try load_tiles(canvas, source, &file, backing, (u32)stored, plane_mask):
var old = try document.take_mask(id, mask)
old.destroy()
let layer = document.find(id) else trap("a loaded layer is gone")
try build_levels(canvas, layer.mask_tiles() else trap("a loaded mask is gone"), true)
## The staged records of one load batch and what they become.
struct LoadBatch:
var packed: u8[]
var filtered: u8[]
var texels: u8[]
var lengths: usize[]
var rows: usize[]
var failed: @bool
## On a worker: inflate and unfilter slot `slot` of a load batch.
func inflate_slot(context: void*?, slot: usize):
let batch = (LoadBatch*)(context else return)
let size = (usize)tile_size * tile_row_bytes
let bound = flate.deflate_bound(size)
let bytes = batch.rows[slot] * tile_row_bytes
let filtered = batch.filtered[slot * size..<slot * size + bytes]
# It fills `filtered` exactly and answers how much of the record it read.
let used = flate.inflate_raw(batch.packed[slot * bound..<slot * bound + batch.lengths[slot]], filtered) catch failure:
_ = failure
batch.failed.store(true, .release)
return
if used != batch.lengths[slot]:
batch.failed.store(true, .release)
return
unfilter_tile(filtered, batch.rows[slot], batch.texels[slot * size..<slot * size + bytes])
## Layer `layer`'s tiles of `base` (pixels or mask, with the plane past the
## canvas after it) as a new store; none when the file holds no cell of them.
func load_tiles(canvas: Canvas*, source: PackageSource*, file: files.File*, backing: TileSource*, layer: u32, base: u32) -> Tiles?!:
var any = false
var outside = CellRange(left = 0, top = 0, right = 0, bottom = 0)
var beyond = false
for cell in source.cells:
if cell.layer != layer or (cell.plane != base and cell.plane != base + 1):
continue
any = true
if cell.plane == base + 1:
let column = (i64)cell.column
let row = (i64)cell.row
if not beyond:
outside = CellRange(left = column, top = row, right = column + 1, bottom = row + 1)
beyond = true
outside.left = math.imin(outside.left, column)
outside.top = math.imin(outside.top, row)
outside.right = math.imax(outside.right, column + 1)
outside.bottom = math.imax(outside.bottom, row + 1)
if not any:
return none
let device = canvas.device else trap("loading without a device")
var tiles = try Tiles.create(device, canvas.extent_x, canvas.extent_y)
errdefer tiles.destroy()
if beyond:
try tiles.cover(outside)
# Where each blob went first on the canvas grid, for cells that share it.
let first = try new i64[source.blobs.length if source.blobs.length > 0 else 1] --- in memory.heap
defer free(first) in memory.heap
for at in 0..<first.length:
first[at] = -1
let size = (usize)tile_size * tile_row_bytes
let bound = flate.deflate_bound(size)
var batch = LoadBatch()
batch.failed.store(false, .release)
batch.packed = try new u8[load_batch * bound] --- in memory.heap
defer free(batch.packed) in memory.heap
batch.filtered = try new u8[load_batch * size] --- in memory.heap
defer free(batch.filtered) in memory.heap
batch.texels = try new u8[load_batch * size] --- in memory.heap
defer free(batch.texels) in memory.heap
batch.lengths = try new usize[load_batch] --- in memory.heap
defer free(batch.lengths) in memory.heap
batch.rows = try new usize[load_batch] --- in memory.heap
defer free(batch.rows) in memory.heap
let places = try new PackageCell[load_batch] --- in memory.heap
defer free(places) in memory.heap
# Cells showing a tile loaded for an earlier cell; shared once it is placed.
let shares = try new PackageCell[source.cells.length if source.cells.length > 0 else 1] --- in memory.heap
defer free(shares) in memory.heap
var share_count: usize = 0
var staged: usize = 0
# Loading goes a row of cells at a time (the file holds a layer's cells in rows): once
# a row is in, the cells sharing its tiles are placed and the levels above the rows
# finished so far are made, while those rows' tiles are still on the GPU. Past the
# budgets they may then leave (the file backs them) without ever being read again.
var building = LevelBuild(canvas = canvas, tiles = &tiles, mask = base == plane_mask, top = top_level(canvas), done = 0)
var current: i64 = -1
for cell in source.cells:
if cell.layer != layer or (cell.plane != base and cell.plane != base + 1):
continue
let blob = source.blobs[(usize)cell.blob]
if cell.plane == base:
if (u32)cell.column >= tiles.columns() or (u32)cell.row >= tiles.rows() or cell.column < 0 or cell.row < 0:
error(invalid, "a stored cell lies off the canvas grid")
if (i64)cell.row != current:
try place_batch(canvas, &tiles, &batch, places, staged, base, source, backing)
staged = 0
try place_shares(&tiles, first, shares[..<share_count])
share_count = 0
if current >= 0:
try building.rows_through((u32)current)
current = (i64)cell.row
# A tile this layer already has: shared, not read again.
if first[(usize)cell.blob] >= 0:
shares[share_count] = cell
share_count += 1
continue
if (u32)blob.rows < tiles.region((u32)cell.column, (u32)cell.row).height:
error(invalid, "a stored tile is shorter than its cell")
first[(usize)cell.blob] = (i64)cell.row * 65536 + (i64)cell.column
try read_at(file, blob.offset, batch.packed[staged * bound..<staged * bound + (usize)blob.length])
batch.lengths[staged] = (usize)blob.length
batch.rows[staged] = (usize)blob.rows
places[staged] = cell
staged += 1
if staged == load_batch:
try place_batch(canvas, &tiles, &batch, places, staged, base, source, backing)
staged = 0
try place_batch(canvas, &tiles, &batch, places, staged, base, source, backing)
try place_shares(&tiles, first, shares[..<share_count])
if current >= 0:
try building.rows_through(tiles.rows() - 1)
return tiles
## Place the cells of `shares` sharing a tile already loaded (`first` says
## where it went on the canvas grid).
func place_shares(tiles: Tiles*, first: const i64[], shares: const PackageCell[]) -> !:
for cell in shares:
let seen = first[(usize)cell.blob]
try tiles.share((u32)cell.column, (u32)cell.row, (u32)(seen % 65536), (u32)(seen // 65536))
## The level at which the document fits one cell: the view at fit reads it.
func top_level(canvas: const Canvas*) -> u32:
var level: u32 = 0
while level_size(canvas.extent_x, level) > tile_size or level_size(canvas.extent_y, level) > tile_size:
level += 1
return level
## A layer's pyramid made as its rows of cells load: the levels above every
## row finished so far, each level from the one below it while that is fresh.
struct LevelBuild:
var canvas: Canvas*
var tiles: const Tiles*
var mask: bool
var top: u32
## Rows of cells finished at level 0.
var done: u32
## Rows 0..`row` of level 0 are in: make every level's rows they complete.
func rows_through(row: u32) -> !:
if self.top == 0 or row + 1 <= self.done:
return
let composer = self.canvas.composer else return
# A request of its own: what earlier rows made may leave the cache now, as
# the load is not inside one frame's request (which would keep all of it).
composer.levels().hold()
let finished = row + 1
let rows = self.tiles.rows()
let mark = transient_mark()
defer release_transients(mark)
for level in 1..<self.top + 1:
# The rows of this level whose children, rows at level 0, are all in now.
let span = 1u32 << level
let before = self.done // span if self.done < rows else (rows + span - 1) // span
let after = finished // span if finished < rows else (rows + span - 1) // span
let columns = (self.tiles.columns() + span - 1) // span
for level_row in before..<after:
for column in 0..<columns:
_ = try composer.levels().texture(self.tiles, column, level_row, level, self.mask)
self.done = finished
## Inflate the batch's `count` records across the processors, upload them in
## one submission into their cells, and let the tiers settle.
func place_batch(canvas: Canvas*, tiles: Tiles*, batch: LoadBatch*, places: const PackageCell[], count: usize, base: u32, source: const PackageSource*, backing: TileSource*) -> !:
if count == 0:
return
# A batch of its own each time: its staging goes once the copies are done.
var upload = try gpu.UploadBatch.begin(canvas.device else trap("loading without a device"))
defer upload.finish()
try spread(count, (void*)batch, inflate_slot)
if batch.failed.load(.acquire):
error(invalid, "a stored tile of the .l2d document is damaged")
let device = canvas.device else trap("loading without a device")
let size = (usize)tile_size * tile_row_bytes
for slot in 0..<count:
let cell = places[slot]
var texture = try tile_texture(device)
errdefer texture.destroy()
try upload.add(texture, batch.texels[slot * size..<slot * size + batch.rows[slot] * tile_row_bytes], gpu.Region(0, 0, tile_size, (u32)batch.rows[slot]))
if cell.plane == base:
try tiles.set((u32)cell.column, (u32)cell.row, texture)
else:
try tiles.place((i64)cell.column, (i64)cell.row, texture, false, true)
try upload.submit()
# Each tile keeps its record in the file, so leaving the GPU or RAM costs nothing.
for slot in 0..<count:
let cell = places[slot]
if cell.plane != base:
continue
let blob = source.blobs[(usize)cell.blob]
try back_cell(tiles, (u32)cell.column, (u32)cell.row, backing, blob.offset, blob.length, (u32)blob.rows)
# What came in may push older tiles down a tier before the next batch; the layer
# loading counts as shown, not as history's.
try settle_loading(canvas, tiles)
## Build `tiles`' pyramid up to the level where the document fits one cell,
## while the layer's newest tiles are still on the GPU: the first view of the
## document then reads levels already made, rather than bringing every tile
## that moved to RAM or disk back for one frame.
func build_levels(canvas: Canvas*, tiles: const Tiles*, mask: bool) -> !:
let composer = canvas.composer else return
var level: u32 = 0
while level_size(canvas.extent_x, level) > tile_size or level_size(canvas.extent_y, level) > tile_size:
level += 1
if level == 0:
return
let mark = transient_mark()
defer release_transients(mark)
_ = try composer.levels().texture(tiles, 0, 0, level, mask)
try settle_job(canvas)
## luce-canvas's decode of this format's records (tiles/backing): inflate the
## record, then undo its filter into `into`'s first `rows` texel rows. Runs on
## worker threads too.
func decode_record(context: void*?, packed: const u8[], rows: u32, into: u8[]) -> !:
_ = context
let bytes = (usize)rows * tile_row_bytes
if bytes > into.length:
error(invalid, "a stored tile of the .l2d document is damaged")
let filtered = try new u8[bytes] --- in memory.heap
defer free(filtered) in memory.heap
let used = try flate.inflate_raw(packed, filtered)
if used != packed.length:
error(invalid, "a stored tile of the .l2d document is damaged")
unfilter_tile(filtered, (usize)rows, into[..<bytes])
## The elements `element` holds, if any: the layer with id `id` is a vector layer again.
func load_elements(doc: prism.Document*, element: str, canvas: Canvas*, id: i64) -> !:
let list = (try read_elements(doc, element)) else return
let index = canvas.index((u64)id) catch failure:
free_list(list)
error(failure.code, failure.message)
release_elements(&canvas.records[index])
canvas.records[index].elements = list
canvas.records[index].shaped = true
## The graph `element` holds, if any, as the graph of layer `id`.
func load_graph(doc: prism.Document*, element: str, canvas: Canvas*, id: i64) -> !:
var graph = (try read_graph(doc, element)) else return
let index = canvas.index((u64)id) catch failure:
free_graph(&graph)
error(failure.code, failure.message)
free_graph(&canvas.records[index].graph)
canvas.records[index].graph = graph
canvas.records[index].generated_fresh = false