Luce packages
LuceLuce BaseLuciaOS

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