Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.0

0.45.0 / src / canvas / opening.lucb

#==============================================================================================
#
#   canvas/opening - A picture opened as a document, loading while frames go on
#
#   DESCRIPTION:
#       A 216-megapixel PNG takes seconds to decode. Rather than a blank window until it
#       is done, the document binds at once with its layer empty, and a worker thread
#       decodes the picture a band of 256 rows at a time (luce_image/streaming), packing
#       each band into half-float tiles' bytes: a PNG's or JPEG's encoded samples through
#       tables of their half floats, any other picture from linear floats. Frames upload the bands packed so far
#       (`collect_opening`) through the layer's ordinary tiles, and the layer's pyramid is
#       brought up to date after each, so the view fills in from the top, zoomed in or
#       out, while the decode goes on. A few bands are packed ahead at most: the worker
#       waits for a free slot, so memory stays a few rows of tiles whatever the picture.
#
#       A picture placed as a new layer (File › Import, a drop on the Layers panel) loads
#       the same way. Off the canvas's grid, its bands go into a grid of its own first,
#       and each row of the layer's cells lands (`land_rows`) once the picture rows under
#       it are in; the picture's cells no row needs any more are let go as it goes.
#
#       A progressive JPEG or interlaced PNG shows itself before any row: its first scans or
#       pass give the picture at 1/8 size, which stands in for the layer's cells not yet in
#       (canvas/opening_coarse).
#
#       Edits and saves are refused until it is done (`require_loaded`); `opening_percent`
#       is the progress for the window to show.
#
#==============================================================================================

extend Canvas:
    ## Whether the picture the document was opened from is still loading
    ## (canvas/opening): it draws as far as it has come; edits and saves wait.
    pub func is_opening() -> bool:
        return self.opening != none

    ## How much of the picture has loaded, 0..100 (100 once it has).
    pub func opening_percent() -> i64:
        let opening = self.opening else return 100
        let rows = (u64)opening.rows.load(.acquire)
        return (i64)(rows * 100 // (u64)opening.extent_y)

    ## Take in the bands decoded since the last call, as a draw does: for a
    ## document not on screen, whose picture would otherwise wait for its next
    ## frame. A failed load is reported here, once.
    pub func continue_opening() -> !:
        let opening = self.opening else return
        let document = self.document else return
        let composer = self.composer else return
        let layer = document.find(opening.layer) else trap("the opening layer is gone")
        let tiles = layer.tiles() else trap("the opening layer has no tiles")
        let started = time.now()
        try show_coarse(opening, composer)
        let before = opening.uploaded
        while opening.uploaded < opening.packed.load(.acquire):
            let slot = &opening.slots[opening.uploaded % opening_slots]
            if opening.placed:
                try opening.source.write_packed(slot.row, slot.band, slot.painted)
                try land_opening(&self, composer, document, tiles, opening, slot.row)
            else:
                # What was made from this row so far is stale once it is in.
                composer.forget_band(document, tiles, slot.row)
                try tiles.write_packed(slot.row, slot.band, slot.painted)
                try build_band_levels(&self, composer, tiles, slot.row)
            opening.uploaded += 1
            opening.free_slots.release()
            try settle_job(&self)
            if time.now() - started > opening_upload_budget_ns:
                # The rest go in the next frame, which nothing else may ask for.
                wake_frames()
                break
        if opening.uploaded != before:
            try refresh_coarse(opening, composer)
        if opening.finished.load(.acquire) == 0 or opening.uploaded < opening.packed.load(.acquire):
            return
        self.opening = none
        hide_coarse(opening, composer)
        let failed = opening.failed
        let code = opening.failure_code
        # The message outlives the opening: the canvas keeps it.
        let length = opening.failure_length
        memory.copy(self.open_failure, opening.failure_text, length)
        free_opening(opening)
        if failed:
            error(code, (str)self.open_failure[..<length])

    ## Wait for the picture opening, if any, to be in: before another is
    ## placed, for one loads at a time.
    pub func finish_opening() -> !:
        while self.opening != none:
            try self.continue_opening()
            if self.opening != none:
                thread.sleep(1)

## Bands the worker may pack ahead of the uploads.
let opening_slots: usize = 3

## A frame uploads bands for at most this long, so it stays a frame.
let opening_upload_budget_ns: u64 = 12000000

## One packed band: its row of cells, and the bytes `pack_band` made.
struct OpeningSlot:
    var row: u32
    var band: u8[]
    var painted: bool[]

## A picture loading into layer `layer` of the document.
struct Opening:
    ## The picture, released on the main thread once the worker has stopped.
    var picture: interop.Reference[Image]
    var image: Image*
    var canvas: Canvas*
    var layer: u64
    ## The picture's size, which its bands are packed for.
    var extent_x: u32
    var extent_y: u32
    ## A placed picture off the canvas's grid: its own grid, where its top-left
    ## lands, the next row of the layer's cells to land and the row after the
    ## last, and the picture's cell rows let go so far.
    var placed: bool
    var source: Tiles
    var offset_x: i64
    var offset_y: i64
    var landed: i64
    var land_end: i64
    var source_freed: u32
    var slots: OpeningSlot[3]
    ## Each code's half float, made at the first band of encoded samples.
    var color: u16[]
    var alpha: u16[]
    ## Slots the worker may fill; the uploads give them back.
    var free_slots: sync.Semaphore
    ## Bands packed (by the worker) and uploaded (by frames).
    var packed: @usize
    var uploaded: usize
    ## Picture rows decoded, for the progress.
    var rows: @usize
    var finished: @u32
    var cancelled: @u32
    ## The worker's failure, if any, kept until the frame that reports it.
    var failed: bool
    var failure_code: ErrorCode
    var failure_text: u8[256]
    var failure_length: usize
    var handle: thread.Handle
    var started: bool
    ## A first sight of the picture while its rows come (canvas/opening_coarse).
    var coarse: CoarseSight

## Whether `picture`, the document's own picture, loads in the background:
## frames draw progressively (the window's setting) and it decodes on the CPU
## alone (a camera raw develops on the GPU; an SVG draws with the fonts).
func opens_in_background(canvas: const Canvas*, picture: interop.Reference[Image]) -> bool:
    return canvas.open_in_background and progressive_loading and not picture.value().is_camera_raw()

## Whether `picture`, placed as a layer, loads in the background: as the
## document's own picture does.
func places_in_background(picture: interop.Reference[Image]) -> bool:
    return progressive_loading and not picture.value().is_camera_raw()

## Start loading `picture`, which this takes, into layer `layer` with its
## top-left at document pixel (`x`, `y`): the layer gets empty tiles now, and
## a worker begins decoding.
func begin_opening(canvas: Canvas*, layer: u64, picture: interop.Reference[Image], x: i64 = 0, y: i64 = 0) -> !:
    let device = canvas.device else trap("bound")
    let document = canvas.document else trap("bound")
    let opening = new Opening(picture = picture, image = picture.value(), canvas = canvas, layer = layer, offset_x = x, offset_y = y,
                              uploaded = 0, failed = false, failure_code = invalid, failure_length = 0, started = false) in memory.heap catch failure:
        picture.release()
        error(failure.code, failure.message)
    errdefer free_opening(opening)
    let width = (u32)(try picture.value().width())
    let height = (u32)(try picture.value().height())
    opening.extent_x = width
    opening.extent_y = height
    var tiles = try Tiles.create(device, canvas.extent_x, canvas.extent_y)
    opening.placed = x != 0 or y != 0 or width != canvas.extent_x or height != canvas.extent_y
    if opening.placed:
        # What lies past the canvas is kept past it, as a moved layer keeps it.
        let range = landing_cells((f64)x, (f64)y, (f64)(x + (i64)width), (f64)(y + (i64)height))
        if x < 0 or y < 0 or x + (i64)width > (i64)canvas.extent_x or y + (i64)height > (i64)canvas.extent_y:
            tiles.cover(range) catch failure:
                tiles.destroy()
                error(failure.code, failure.message)
        opening.landed = range.top
        opening.land_end = range.bottom
        opening.source = Tiles.create(device, width, height) catch failure:
            opening.placed = false
            tiles.destroy()
            error(failure.code, failure.message)
    try document.set_tiles(layer, tiles)
    for slot in 0..<opening_slots:
        opening.slots[slot].band = try new u8[packed_band_bytes(width)] --- in memory.heap
        opening.slots[slot].painted = try new bool[(usize)tile_columns(width)] --- in memory.heap
    for unused in 0..<opening_slots:
        opening.free_slots.release()
    opening.handle = try thread.spawn(opening_worker, (void*)opening, name = "picture open")
    opening.started = true
    canvas.opening = opening

## The worker: the picture a band at a time into the slots.
func opening_worker(context: void*?):
    let opening = (Opening*)(context else return)
    opening_decode(opening) catch failure:
        if opening.cancelled.load(.acquire) == 0:
            let length = failure.message.length if failure.message.length < opening.failure_text.length else opening.failure_text.length
            memory.copy(opening.failure_text, failure.message.bytes, length)
            opening.failure_length = length
            opening.failure_code = failure.code
            opening.failed = true
        recover ()
    opening.finished.store(1, .release)
    wake_frames()

## Encoded samples where the format gives them, else linear floats.
func opening_decode(opening: Opening*) -> !:
    if not (try opening.image.encoded_rgba_bands((usize)tile_size, opening_coded_band, (void*)opening, opening_coarse)):
        try opening.image.linear_rgba_bands((usize)tile_size, opening_band, (void*)opening)

## `linear_rgba_bands`' sink on the worker: pack the band into a free slot.
func opening_band(context: void*?, first: usize, count: usize, pixels: f32[]) -> !:
    let opening = (Opening*)(context else return)
    let slot = try free_slot(opening, first)
    try pack_band(opening.extent_x, opening.extent_y, slot.row, pixels, slot.band, slot.painted)
    band_packed(opening, first + count)

## `encoded_rgba_bands`' sink on the worker: the samples through the tables into a free slot.
func opening_coded_band(context: void*?, first: usize, count: usize, samples: const u8[], deep: bool) -> !:
    let opening = (Opening*)(context else return)
    let slot = try free_slot(opening, first)
    if opening.color.length == 0:
        let codes: usize = 65536 if deep else 256
        opening.color = try new u16[codes] --- in memory.heap
        opening.alpha = try new u16[codes] --- in memory.heap
        try encoded_tables(deep, opening.color, opening.alpha)
    try pack_band_coded(opening.extent_x, opening.extent_y, slot.row, samples, deep, opening.color, opening.alpha, slot.band, slot.painted)
    band_packed(opening, first + count)

## The slot for the band starting at picture row `first`, once the uploads
## have left one free.
func free_slot(opening: Opening*, first: usize) -> OpeningSlot*!:
    opening.free_slots.acquire()
    if opening.cancelled.load(.acquire) != 0:
        error(invalid, "the document closed while its picture opened")
    let slot = &opening.slots[opening.packed.load(.acquire) % opening_slots]
    slot.row = (u32)(first // (usize)tile_size)
    return slot

## A slot is packed, the picture's rows through `rows` with it.
func band_packed(opening: Opening*, rows: usize):
    opening.rows.store(rows, .release)
    _ = opening.packed.add(1)
    # Frames upload it; the window's loop may be asleep waiting for input.
    wake_frames()

## A placed picture's cell row `row` is in: the rows of the layer's cells
## whose picture rows are all in now land, their levels made as a band's are,
## and the picture's cells no later row needs are let go.
func land_opening(canvas: Canvas*, composer: Composer*, document: const Document*, tiles: Tiles*, opening: Opening*, row: u32) -> !:
    let size = (i64)tile_size
    let loaded = min_i64((i64)(row + 1) * size, (i64)opening.extent_y)
    # The last band lands everything left; before it, only whole cell rows.
    var through = opening.land_end
    if loaded < (i64)opening.extent_y:
        let bottom = opening.offset_y + loaded
        through = min_i64(opening.land_end, bottom // size if bottom >= 0 else -((-bottom + size - 1) // size))
    if through <= opening.landed:
        return
    try land_rows(&opening.source, tiles, opening.offset_x, opening.offset_y, opening.landed, through)
    for landed in opening.landed..<through:
        if landed >= 0 and landed < (i64)tile_columns(canvas.extent_y):
            composer.forget_band(document, tiles, (u32)landed)
            try build_band_levels(canvas, composer, tiles, (u32)landed)
    opening.landed = through
    if through == opening.land_end:
        try tiles.settle()
    # Picture cell rows wholly above the next row to land are done with.
    let needed = through * size - opening.offset_y
    while opening.source_freed < opening.source.rows() and ((i64)opening.source_freed + 1) * size <= needed:
        for column in 0..<opening.source.columns():
            try opening.source.clear(column, opening.source_freed)
        opening.source_freed += 1

## The level tiles row `row` of cells completes, each level's row made once
## every row of cells under it is in: a zoomed-out view has the rows loaded so
## far ready, and no level tile is made twice.
func build_band_levels(canvas: Canvas*, composer: Composer*, tiles: const Tiles*, row: u32) -> !:
    let pyramid = composer.levels()
    let last = row + 1 == tile_columns(canvas.extent_y)
    let mark = transient_mark()
    defer release_transients(mark)
    var level: u32 = 1
    while level <= 16 and (last or (row + 1) % (1u32 << level) == 0):
        for column in 0..<level_cells(canvas.extent_x, level):
            pyramid.hold()
            _ = try pyramid.texture(tiles, column, row >> level, level)
        if level_cells(canvas.extent_x, level) == 1 and level_cells(canvas.extent_y, level) == 1:
            return
        level += 1

## Stop a load under way (the document is closing): the worker ends at its
## next band and the picture goes.
func cancel_opening(canvas: Canvas*):
    let opening = canvas.opening else return
    canvas.opening = none
    opening.cancelled.store(1, .release)
    for unused in 0..<opening_slots:
        opening.free_slots.release()
    free_opening(opening)

## Join the worker (it has stopped or is stopping) and free everything.
func free_opening(opening: Opening*):
    if opening.started:
        opening.handle.join() catch _:
            recover ()
    opening.picture.release()
    release_coarse(opening)
    if opening.placed:
        opening.source.destroy()
    if opening.color.length > 0:
        free(opening.color) in memory.heap
        free(opening.alpha) in memory.heap
    for slot in 0..<opening_slots:
        if opening.slots[slot].band.length > 0:
            free(opening.slots[slot].band) in memory.heap
        if opening.slots[slot].painted.length > 0:
            free(opening.slots[slot].painted) in memory.heap
    free(opening) in memory.heap

## Refuse what changes or saves the document while its picture is still
## opening, or while Select and Mask's OK refines the selection.
func require_loaded(canvas: const Canvas*) -> !:
    if canvas.opening != none:
        error(invalid, "the picture is still opening")
    if canvas.refine_keeping():
        error(invalid, "the selection is still being refined")