dymokomi/luce-image
Source of release 0.45.1
0.45.1 / src / canvas / package_format.lucb
#==============================================================================================
#
# canvas/package_format - The .l2d file: its layout and its tile codec
#
# DESCRIPTION:
# An .l2d document is one file, written front to back in a single pass:
#
# header 16 bytes: "LUCED2D1", format version (u32), reserved (u32)
# tiles one record per stored tile, back to back (see below)
# preview a small flattened PNG of the document, for quick looks
# manifest the document as Prism text: size, resolution, profile, blending, every
# layer's settings, text, vector elements and node graphs, styles, guides, and the
# alpha channels' names
# index where every tile is and which cells use it
# trailer 64 bytes: "L2DINDEX", then the offset and length (u64 each) of
# the manifest, the preview and the index, then 8 reserved bytes
#
# All numbers are little-endian. The index is a blob table, then a cell table:
#
# u32 blob count, then per blob: u64 offset, u32 length, u16 rows, u8 filter, u8 0
# u32 cell count, then per cell: u32 layer, u32 plane, i32 column, i32 row, u32 blob
#
# `layer` is the layer's place in the manifest; `plane` is 0 for its pixels on the
# canvas grid, 1 for its pixels past the canvas, 2 and 3 likewise for its mask. A cell
# with nothing painted has no entry (a mask's unpainted cells are white), and one
# tile shared by several cells is stored once. Planes 4 and 5 are an alpha channel's
# cells, `layer` its place among the channels (package_channels.lucb). A tile record is the cell's rgba16f
# texels, 256 to a row and `rows` rows, each 16-bit sample replaced by its difference
# from the same channel of the texel to its left, split into a plane of low bytes then
# one of high bytes, and deflated (raw DEFLATE). Nothing is ever the size of the
# document: tiles go out and come back one batch at a time.
#
#==============================================================================================
## Where a document's parts sit in its file, from the trailer.
struct PackageTrailer:
var manifest_offset: u64
var manifest_length: u64
var preview_offset: u64
var preview_length: u64
var index_offset: u64
var index_length: u64
## One stored tile: where its record is and how to read it back.
struct PackageBlob:
var offset: u64
var length: u32
var rows: u16
var filter: u8
## One cell that shows a stored tile.
struct PackageCell:
var layer: u32
var plane: u32
var column: i32
var row: i32
var blob: u32
let package_magic: str = "LUCED2D1"
let package_trailer_magic: str = "L2DINDEX"
let package_version: u32 = 5
let package_header_bytes: usize = 16
let package_trailer_bytes: usize = 64
let package_blob_bytes: usize = 16
let package_cell_bytes: usize = 20
## The planes of a layer: pixels on the canvas and past it, then its mask's.
let plane_pixels: u32 = 0
let plane_pixels_beyond: u32 = 1
let plane_mask: u32 = 2
let plane_mask_beyond: u32 = 3
## Tile records: the sub filter with byte planes, deflated at this level.
let tile_filter_sub: u8 = 1
let tile_deflate_level: i32 = 1
## Bytes one texel row of a tile takes (256 texels of four half floats).
let tile_row_bytes: usize = 2048
# -- Little-endian numbers into and out of byte arrays.
func put_u16(bytes: u8[], at: usize, value: u16):
bytes[at] = (u8)(value & 0xff)
bytes[at + 1] = (u8)(value >> 8)
func put_u32(bytes: u8[], at: usize, value: u32):
for index in 0..<(usize)4:
bytes[at + index] = (u8)((value >> (u32)(index * 8)) & 0xff)
func put_u64(bytes: u8[], at: usize, value: u64):
for index in 0..<(usize)8:
bytes[at + index] = (u8)((value >> (u64)(index * 8)) & 0xff)
func get_u16(bytes: const u8[], at: usize) -> u16:
return (u16)bytes[at] | ((u16)bytes[at + 1] << 8)
func get_u32(bytes: const u8[], at: usize) -> u32:
var value: u32 = 0
for index in 0..<(usize)4:
value |= (u32)bytes[at + index] << (u32)(index * 8)
return value
func get_u64(bytes: const u8[], at: usize) -> u64:
var value: u64 = 0
for index in 0..<(usize)8:
value |= (u64)bytes[at + index] << (u64)(index * 8)
return value
# -- The tile codec.
## Filter a tile's `rows` texel rows from `texels` into `filtered` (as many
## bytes): each sample's difference from the one to its left, low bytes first.
## The lengths are checked once; the loops then run on pointers with wrapping
## arithmetic (checked indexing per byte made this the save's hottest loop).
func filter_tile(texels: const u8[], rows: usize, filtered: u8[]):
let per_row = tile_row_bytes // 2
let count = rows * per_row
if texels.length < count * 2 or filtered.length < count * 2:
trap("a tile filter was given too few bytes")
let source = (const u16*)texels.data
let low = filtered.data
let high = filtered.data + count
var row: usize = 0
while row < rows:
let base = row *% per_row
var sample: usize = 0
while sample < 4:
let value = source[base +% sample]
low[base +% sample] = (u8)(value & 0xff)
high[base +% sample] = (u8)(value >> 8)
sample = sample +% 1
while sample < per_row:
let at = base +% sample
let delta = source[at] -% source[at -% 4]
low[at] = (u8)(delta & 0xff)
high[at] = (u8)(delta >> 8)
sample = sample +% 1
row = row +% 1
## Undo `filter_tile`: `filtered` back into `texels`, `rows` rows of them.
func unfilter_tile(filtered: const u8[], rows: usize, texels: u8[]):
let per_row = tile_row_bytes // 2
let count = rows * per_row
if texels.length < count * 2 or filtered.length < count * 2:
trap("a tile unfilter was given too few bytes")
let target = (u16*)texels.data
let low = filtered.data
let high = filtered.data + count
var row: usize = 0
while row < rows:
let base = row *% per_row
var sample: usize = 0
while sample < 4:
let at = base +% sample
target[at] = (u16)low[at] | ((u16)high[at] << 8)
sample = sample +% 1
while sample < per_row:
let at = base +% sample
let delta = (u16)low[at] | ((u16)high[at] << 8)
target[at] = delta +% target[at -% 4]
sample = sample +% 1
row = row +% 1
## A whole tile's rgba16f `texels` as a stored record in `into` (the tile
## codec's bound): filtered, then deflated at the document's level; its
## length. What the memory governor's compressed tier packs with, on workers.
func encode_tile_record(context: void*?, texels: const u8[], into: u8[]) -> usize!:
_ = context
let filtered = try new u8[texels.length] --- in memory.heap
defer free(filtered) in memory.heap
filter_tile(texels, (usize)tile_size, filtered)
return try flate.deflate_raw(filtered, tile_deflate_level, into, true)
# -- Work spread over the processors.
## `task(context, index)` for every index in 0..<`count` on the worker pool, at
## most 16 threads.
func spread(count: usize, context: void*?, task: func(void*?, usize) -> unit) -> !:
pool.run(count, task, context, limit = 16)
# -- A file written and read in whole pieces.
## Write all of `bytes` to `file`.
func write_all(file: files.File*, bytes: const u8[]) -> !:
var done: usize = 0
while done < bytes.length:
let wrote = try file.write(bytes[done..])
if wrote == 0:
error(invalid, "the document file stopped taking bytes")
done += wrote
## Fill all of `buffer` from `file` at `offset`.
func read_at(file: files.File*, offset: u64, buffer: u8[]) -> !:
_ = try file.seek((i64)offset)
var done: usize = 0
while done < buffer.length:
let got = try file.read(buffer[done..])
if got == 0:
error(invalid, "the document file ends too soon")
done += got