Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.0

0.45.0 / src / canvas / masking.lucb

#==============================================================================================
#
#   canvas/masking - Select and Mask: the selection's edge refined, previewed live
#
#   DESCRIPTION:
#       The selection stays as it began while the dialog is up. A slider only records the
#       setting (`preview_refine`); each frame (`draw_selection`) asks for the refinement at
#       the level the view draws, over the cells it shows (selection_preview.lucb): the
#       selection taken down to that level, the picture's lightness read at it, the
#       distances scaled to it. That work runs on a thread of its own (RefineWork,
#       selection_refine.lucb) while frames go on showing the last result; a setting that
#       changes meanwhile cancels it, and once it has stopped the latest is started, so a
#       drag's changes come down to one recompute at a time and the newest wins.
#       Keeping it refines the whole selection at full size once, as one undo step, taking
#       the cells a preview at full size already worked out for the same setting. From the
#       editor that runs on the same thread as the previews (a worst-case selection takes
#       seconds): edits are refused meanwhile, as while a picture opens, and the step is
#       recorded when a later frame finds the work done (`continue_refine`).
#
#==============================================================================================

extend Canvas:
    ## Select › Select and Mask: begin refining the selection's edge;
    ## `preview_refine` shows it, `end_refine` keeps it as one step or puts
    ## the selection back.
    pub func begin_refine() -> !:
        try self.require_open()
        try self.require_idle()
        if self.select_mask != none:
            error(invalid, "Select and Mask is already open")
        if not self.has_selection():
            error(invalid, "nothing is selected to refine")
        let origin = try self.live().copy()
        self.select_mask = try new SelectMask(origin = origin, view = refine_ants, setting = Refinement(), asked = false, levels = LevelOrigin(selection = none, level = 0),
                                              luma = none, lit = none, luma_level = 0, task = none, shown = Shown(selection = none, level = 0),
                                              shown_setting = Refinement(), shown_box = CellBox(), keeping = false, keep_read = 0) in memory.heap

    pub func refining() -> bool:
        return self.select_mask != none

    ## Show the selection as it began refined: edge detection `radius`
    ## (0..250), `smooth` (0..100), `feather` (0..250), `contrast` (0..100%)
    ## and `shift` edge (-100..100%). Only recorded here: the frames that
    ## follow work it out at the view's level, over what it shows, on a
    ## thread of their own (masking.lucb), the latest setting winning.
    pub func preview_refine(radius: i64, smooth: i64, feather: i64, contrast: f64, shift: f64) -> !:
        try ask_refine(&self, Refinement(radius = radius, smooth = smooth, feather = feather, contrast = contrast, shift = shift))

    ## OK (`keep`): the whole selection refined so at full size, one step;
    ## Cancel: as it was. With `background` OK returns at once: the work runs
    ## on the previews' thread, edits are refused (`refine_keeping`) until
    ## a frame or `continue_refine` finds it done and records the step.
    pub func end_refine(keep: bool, radius: i64 = 0, smooth: i64 = 0, feather: i64 = 0, contrast: f64 = 0.0, shift: f64 = 0.0,
                        background: bool = false) -> !:
        if keep and self.select_mask != none and not self.refine_keeping():
            try ask_refine(&self, Refinement(radius = radius, smooth = smooth, feather = feather, contrast = contrast, shift = shift))
        try end_refine(&self, keep, background)

    ## Keep OK's refinement once it is done (at once with `wait`): the
    ## editor calls it each frame; drawing the selection does too.
    pub func continue_refine(wait: bool = false) -> !:
        let session = self.select_mask else return
        if not session.keeping:
            return
        if session.task == none:
            if not (try read_keep_lightness(&self, session, wait)):
                return
            let work = refine_whole(&self, session) catch failure:
                drop_refine(&self)
                error(failure.code, failure.message)
            let started = start_background(run_refine_task, (void*)work, "select-and-mask") catch failure:
                RefineWork.destroy(work)
                drop_refine(&self)
                error(failure.code, failure.message)
            session.task = new RefineTask(work = work, setting = session.setting, level = 0, box = CellBox(), background = started) in memory.heap catch failure:
                work.cancel()
                join_background(started)
                RefineWork.destroy(work)
                drop_refine(&self)
                error(failure.code, failure.message)
        let task = session.task else trap("started above")
        if not wait and not background_done(task.background):
            return
        join_background(task.background)
        session.task = none
        session.keeping = false
        defer:
            RefineWork.destroy(task.work)
            free(task) in memory.heap
        if task.work.out_of_memory():
            drop_refine(&self)
            error(memory.exhausted, "out of memory refining the selection")
        try keep_refined(&self, Selection.adopt(try task.work.take()))

    ## Whether OK's refinement is still working: edits are refused meanwhile.
    pub func refine_keeping() -> bool:
        let session = self.select_mask else return false
        return session.keeping

    ## How far OK's refinement has come, 0..100.
    pub func refine_percent() -> i64:
        let session = self.select_mask else return 100
        if not session.keeping:
            return 100
        let task = session.task else return (i64)(session.keep_read * 10 // session.origin.coverage().count())
        return 10 + task.work.percent() * 90 // 100

    ## How the view shows the selection while refining: 0 marching ants,
    ## 1 a red overlay, 2 on black, 3 on white.
    pub func set_refine_view(mode: i64) -> !:
        if mode < 0 or mode > 3:
            error(invalid, "the view is 0 ants, 1 overlay, 2 on black or 3 on white")
        let session = self.select_mask else error(invalid, "Select and Mask is not open")
        session.view = mode

    pub func refine_view_mode() -> i64:
        let session = self.select_mask else return refine_ants
        return session.view

    ## The pyramid level the last finished preview shows, -1 when none does
    ## (none asked for yet, or no frame drawn since).
    pub func refine_preview_level() -> i64:
        let session = self.select_mask else return -1
        if session.shown.selection == none:
            return -1
        return (i64)session.shown.level

    ## Wait for a preview working on its own thread and take it in: for
    ## tests and scripts that look at it before the next frame.
    pub func wait_previews() -> !:
        let session = self.select_mask else return
        try collect_refine(session, true)

## How Select and Mask shows the selection.
let refine_ants: i64 = 0
let refine_overlay: i64 = 1
let refine_on_black: i64 = 2
let refine_on_white: i64 = 3

## Select and Mask while the dialog is up.
struct SelectMask:
    ## The selection it began from, as the live one stays meanwhile.
    var origin: Selection
    var view: i64
    ## The setting last asked for, in document pixels, and whether one was.
    var setting: Refinement
    var asked: bool
    ## The origin at the preview's level, and the picture's lightness there
    ## over the cells `lit` marks read.
    var levels: LevelOrigin
    var luma: Cells*?
    var lit: Cells*?
    var luma_level: u32
    ## The refinement working on its thread, if any.
    var task: RefineTask*?
    ## The last preview finished, and what it holds: the setting at its
    ## level and the box it worked out.
    var shown: Shown
    var shown_setting: Refinement
    var shown_box: CellBox
    ## OK was pressed: the lightness it needs is read a frame at a time
    ## (`keep_read` cells so far), then `task` refines the whole selection.
    var keeping: bool
    var keep_read: usize

## A preview's refinement on its own thread: the setting at `level` over `box`.
struct RefineTask:
    var work: RefineWork*
    var setting: Refinement
    var level: u32
    var box: CellBox
    var background: Background*

## `Canvas.preview_refine`: the setting the next frames show.
func ask_refine(canvas: Canvas*, refinement: Refinement) -> !:
    let session = canvas.select_mask else error(invalid, "Select and Mask is not open")
    try refinement.check()
    session.setting = refinement
    session.asked = true

## Bring the preview toward the setting asked for, as a view of `scope`
## would show it: take in a refinement that finished, cancel one gone stale,
## start the next. Never waits.
func prepare_refine_preview(canvas: Canvas*, scope: Scope) -> !:
    let session = canvas.select_mask else return
    if session.keeping:
        return
    try collect_refine(session)
    let changes = session.asked and session.setting.changes()
    let wanted = session.setting.at_level(scope.level)
    if let task = session.task:
        if not changes or task.level != scope.level or not task.setting.equals(wanted) or not task.box.covers(scope.box):
            # Stale: it stops at its next cell, and a later frame starts the latest.
            task.work.cancel()
        return
    if not changes:
        # Nothing to refine: the selection as it began shows.
        session.shown.destroy()
        return
    if session.shown.selection != none and session.shown.level == scope.level and session.shown_setting.equals(wanted) and session.shown_box.covers(scope.box):
        return
    let origin = try session.levels.at(&session.origin, scope.level)
    var luma: Cells*? = none
    if wanted.radius > 0:
        luma = try lightness_at(canvas, session, origin.coverage(), wanted, scope.box, scope.level)
    let work = try RefineWork.prepare(origin.coverage(), luma, wanted, scope.box, none, CellBox(), clear_outside = true)
    let started = start_background(run_refine_task, (void*)work, "select-and-mask") catch failure:
        RefineWork.destroy(work)
        error(failure.code, failure.message)
    session.task = new RefineTask(work = work, setting = wanted, level = scope.level, box = scope.box, background = started) in memory.heap catch failure:
        work.cancel()
        join_background(started)
        RefineWork.destroy(work)
        error(failure.code, failure.message)

## The thread's work: the refinement, cut short by a cancel.
func run_refine_task(context: void*?):
    let work = (RefineWork*)(context else return)
    _ = work.run()

## Take in the refinement under way if it has finished: shown when it ran to
## the end, let go when it was cancelled. With `wait`, wait for it.
func collect_refine(session: SelectMask*, wait: bool = false) -> !:
    if session.keeping:
        return
    let task = session.task else return
    if not wait and not background_done(task.background):
        return
    join_background(task.background)
    session.task = none
    defer:
        RefineWork.destroy(task.work)
        free(task) in memory.heap
    if task.work.out_of_memory():
        error(memory.exhausted, "out of memory refining the selection")
    if task.work.was_cancelled():
        return
    try session.shown.show(Selection.adopt(try task.work.take()), task.level)
    session.shown_setting = task.setting
    session.shown_box = task.box

## The picture's lightness at `level`, read (on this thread: the GPU's) for
## every cell refining `source` over `box` needs that has not been read yet;
## with `most`, for at most that many of them, `unread` set when some wait.
func lightness_at(canvas: Canvas*, session: SelectMask*, source: const Cells*, refinement: Refinement, box: CellBox, level: u32,
                  most: usize = 0, unread: bool*? = none) -> Cells*!:
    let document = canvas.document else error(invalid, "draw the document once before refining the selection")
    let composer = canvas.composer else error(invalid, "draw the document once before refining the selection")
    let device = canvas.device else error(invalid, "draw the document once before refining the selection")
    if session.luma != none and session.luma_level != level:
        drop_lightness(session)
    if session.luma == none:
        let luma = try new Cells in memory.heap
        *luma = try Cells.create(source.extent_x, source.extent_y)
        let lit = try new Cells in memory.heap
        *lit = try Cells.create(source.extent_x, source.extent_y)
        session.luma = luma
        session.lit = lit
        session.luma_level = level
    let luma = session.luma else trap("made above")
    let lit = session.lit else trap("made above")
    let values = try new i64[source.count()] --- in memory.heap
    defer free(values) in memory.heap
    _ = pending_cells(source, refinement, box, values)
    var needed = try Cells.create(source.extent_x, source.extent_y)
    defer needed.destroy()
    needed_cells(source, values, refinement.apron(), &needed)
    var wanted: usize = 0
    var waiting = false
    for index in 0..<needed.count():
        if needed.uniform(index) == 0:
            continue
        if lit.uniform(index) != 0:
            needed.fill(index, 0)
        elif most > 0 and wanted == most:
            needed.fill(index, 0)
            waiting = true
        else:
            wanted += 1
            lit.fill(index, 255)
    if let flag = unread:
        *flag = waiting
    if wanted > 0:
        var picture = PictureSource(composer = composer, document = document, extent_y = canvas.extent_y, level = level)
        try selection_sources.luma(luma, selection_sources.gpu_reader((void*)&picture, device, picture_cell_texture), &needed)
    return luma

func drop_lightness(session: SelectMask*):
    if let luma = session.luma:
        luma.destroy()
        free(luma) in memory.heap
    if let lit = session.lit:
        lit.destroy()
        free(lit) in memory.heap
    session.luma = none
    session.lit = none

## `Canvas.end_refine`: refine all of it at full size and keep that as one
## step, recorded against the selection it began from, or leave that one.
## With `background` OK returns at once: the frames that follow read the
## picture's lightness a slice at a time, then the refinement runs on the
## previews' thread, and it is kept when `continue_refine` finds it done.
## Edits wait meanwhile.
func end_refine(canvas: Canvas*, keep: bool, background: bool) -> !:
    let session = canvas.select_mask else return
    if session.keeping:
        error(invalid, "the selection is still being refined")
    if let task = session.task:
        task.work.cancel()
        collect_refine(session, true) catch failure:
            _ = failure
    if not keep or not session.asked or not session.setting.changes():
        drop_refine(canvas)
        return
    if background:
        session.keeping = true
        return
    let work = try refine_whole(canvas, session)
    defer RefineWork.destroy(work)
    if not work.run():
        error(memory.exhausted, "out of memory refining the selection")
    try keep_refined(canvas, Selection.adopt(try work.take()))

## How long a frame spends reading lightness for OK, and how many cells a read takes.
let keep_read_ns: u64 = 12000000
let keep_read_cells: usize = 48

## Read the full-size lightness OK's refinement needs, for about a frame's
## share of time (all of it with `wait`): true once all is in.
func read_keep_lightness(canvas: Canvas*, session: SelectMask*, wait: bool) -> bool!:
    if session.setting.radius <= 0:
        return true
    let started = time.now()
    var unread = true
    while unread:
        let luma = lightness_at(canvas, session, session.origin.coverage(), session.setting, CellBox(), 0, keep_read_cells, &unread) catch failure:
            drop_refine(canvas)
            error(failure.code, failure.message)
        _ = luma
        if not wait and time.now() - started > keep_read_ns:
            break
    session.keep_read = lit_count(session)
    return not unread

## Cells whose lightness has been read.
func lit_count(session: const SelectMask*) -> usize:
    let lit = session.lit else return 0
    var count: usize = 0
    for index in 0..<lit.count():
        if lit.uniform(index) != 0:
            count += 1
    return count

## Keep `refined` (handed over) as the selection, one step, and close.
func keep_refined(canvas: Canvas*, refined: Selection) -> !:
    var kept = refined
    canvas.remember_state("Select and Mask") catch failure:
        kept.destroy()
        error(failure.code, failure.message)
    var live = canvas.live()
    live.destroy()
    *live = kept
    drop_refine(canvas)

## The work that refines the selection it began from at full size, sharing
## the cells a full-size preview of the same setting already worked out.
## The picture's lightness is read here, on the GPU's thread, where not yet.
func refine_whole(canvas: Canvas*, session: SelectMask*) -> RefineWork*!:
    let source = session.origin.coverage()
    let setting = session.setting
    var reuse: const Cells*? = none
    var reused = CellBox()
    if let shown = session.shown.selection:
        if session.shown.level == 0 and session.shown_setting.equals(setting):
            reuse = shown.coverage()
            reused = session.shown_box
    var luma: Cells*? = none
    if setting.radius > 0:
        luma = try lightness_at(canvas, session, source, setting, CellBox(), 0)
    return try RefineWork.prepare(source, luma, setting, CellBox(), reuse, reused)

## Close Select and Mask, letting everything it holds go (the dialog closed,
## or the canvas).
func drop_refine(canvas: Canvas*):
    let session = canvas.select_mask else return
    canvas.select_mask = none
    if let task = session.task:
        task.work.cancel()
        join_background(task.background)
        RefineWork.destroy(task.work)
        free(task) in memory.heap
    session.shown.destroy()
    session.levels.destroy()
    drop_lightness(session)
    session.origin.destroy()
    free(session) in memory.heap

## Whether a preview is working on its thread: frames go on to show it.
func refine_busy(canvas: const Canvas*) -> bool:
    let session = canvas.select_mask else return false
    return session.task != none

## Select and Mask's view of the selection over the document as `draw` drew
## it: the preview (or, until there is one, the selection as it began) as
## marching ants, a red overlay, or the picture on black or white. False
## when Select and Mask is not open.
func draw_refine_view(canvas: Canvas*, target: interop.View[gpu.RenderTarget], rectangle: gpu.Rect, zoom: f64, offset_x: f64, offset_y: f64, phase: f64) -> bool!:
    try canvas.continue_refine(false)
    let session = canvas.select_mask else return false
    try prepare_refine_preview(canvas, view_scope(canvas, rectangle, zoom, offset_x, offset_y))
    if let shown = session.shown.selection:
        try draw_shown(canvas, shown, session.shown.level, session.view, target, rectangle, zoom, offset_x, offset_y, phase)
        return true
    if session.view == refine_ants:
        try draw_canvas_selection(canvas, target, rectangle, zoom, offset_x, offset_y, phase)
        return true
    let document = canvas.document else return true
    let tiles = (try document.selection_tiles()) else return true
    if session.view == refine_overlay:
        try draw_matte(canvas, target, rectangle, zoom, offset_x, offset_y, tiles, 0, false, [quick_red, 0.0, 0.0], quick_opacity)
    else:
        let shade: f32 = 0.0 if session.view == refine_on_black else 1.0
        try draw_matte(canvas, target, rectangle, zoom, offset_x, offset_y, tiles, 0, false, [shade, shade, shade], 1.0)
    return true