Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.0

0.45.0 / src / canvas / retouch.lucb

#==============================================================================================
#
#   canvas/retouch - Clone stamp, spot healing, blur, dodge and burn, smudge and push
#
#   DESCRIPTION:
#       The retouching tools, as Compositor's. Clone stamp, the blur tool and spot healing
#       are brush strokes painting an effect image through their coverage instead of a
#       color: the picture shifted by the clone offset, a blurred copy, a lightened (dodge)
#       or darkened (burn) copy, the healed spot (worked out when the stroke ends; a dark
#       wash marks it meanwhile). retouch_effects.lucb makes those images, only where
#       the stroke reaches. Smudge works on the CPU dab by dab (luce-painting's smudge); Liquify's
#       push moves a displacement grid (canvas/liquifying.lucb). Each stroke is one undo step.
#
#==============================================================================================

extend Canvas:
    ## The tool strokes use: 0 paint (the brush), 1 clone stamp, 2 spot
    ## healing, 3 blur, 4 smudge, 5 push (Liquify's forward warp). Retouching
    ## takes the brush's diameter, hardness and opacity (strength).
    pub func set_retouch(kind: i64) -> !:
        if kind < retouch_paint or kind > retouch_burn:
            error(invalid, "retouching tools are 0 paint, 1 clone, 2 heal, 3 blur, 4 smudge, 5 push, 6 dodge, 7 burn")
        self.retouch = kind

    ## Dodge and Burn's range (0 shadows, 1 midtones, 2 highlights) and
    ## exposure (0..1), as their header's.
    pub func set_tone(range: i64, exposure: f64) -> !:
        if range < 0 or range > 2 or not math.is_finite(exposure):
            error(invalid, "a tone range is 0..2 and its exposure finite")
        self.tone_range = range
        self.tone_exposure = math.clamp(exposure, 0.0, 1.0)

    ## Where the clone stamp copies from (Alt-click): a new source starts a new alignment.
    pub func set_clone_source(x: f64, y: f64):
        self.clone_x = x
        self.clone_y = y
        self.clone_set = true
        self.clone_offset_set = false

    ## Aligned: every stroke keeps the first one's offset; otherwise each
    ## starts at the source again. `all_layers` samples everything shown.
    pub func set_clone_options(aligned: bool, all_layers: bool):
        self.clone_aligned = aligned
        self.clone_all = all_layers

    pub func has_clone_source() -> bool:
        return self.clone_set

    ## What a Clone Stamp stroke on layer `id` at (`x`, `y`) would lay down:
    ## the source under a brush `diameter` pixels wide, cut to its circle, as
    ## RGBA8 (sRGB, straight alpha, faded by `opacity`), a square the
    ## diameter rounded up — for the preview inside the brush. The source is the
    ## layer's own pixels, or with All Layers the picture; only the cells under
    ## the brush are read back.
    pub func clone_preview(id: i64, x: f64, y: f64, diameter: f64, opacity: f64 = 1.0) -> const u8[]!:
        let document = self.document else error(invalid, "draw the document once before previewing a clone")
        let side = (usize)math.max(1.0, math.min(1024.0, math.ceil(diameter)))
        if self.preview_bytes.length != side * side * 4:
            if self.preview_bytes.length > 0:
                free(self.preview_bytes) in memory.heap
            self.preview_bytes = try new u8[side * side * 4] --- in memory.heap
        let out = self.preview_bytes
        for index in 0..<out.length:
            out[index] = 0
        let left = (i64)math.floor(self.clone_sample_x(x) - (f64)side * 0.5)
        let top = (i64)math.floor(self.clone_sample_y(y) - (f64)side * 0.5)
        let layer = document.find((u64)id) else error(invalid, "no such layer")
        let first_column = (i64)math.max(0.0, math.floor((f64)left / (f64)tile_size))
        let first_row = (i64)math.max(0.0, math.floor((f64)top / (f64)tile_size))
        let last_column = math.imin((i64)tile_columns(self.extent_x), (left + (i64)side + (i64)tile_size - 1) // (i64)tile_size)
        let last_row = math.imin((i64)tile_columns(self.extent_y), (top + (i64)side + (i64)tile_size - 1) // (i64)tile_size)
        if last_column > first_column and last_row > first_row:
            let device = self.device else error(invalid, "draw the document once before previewing a clone")
            # The cells under the brush, read back together.
            var read = CloneRead(canvas = &self, layer = layer, out = out, side = side, left = left, top = top,
                                 first_column = first_column, first_row = first_row, columns = last_column - first_column)
            try read_pieces(device, (usize)((last_column - first_column) * (last_row - first_row)), (void*)&read, clone_piece, clone_visit)
        # The brush's circle: nothing past it; inside, faded by `opacity`.
        let radius = (f64)side * 0.5
        let fade = math.clamp(opacity, 0.0, 1.0)
        for py in 0..<side:
            for px in 0..<side:
                let dx = (f64)px + 0.5 - radius
                let dy = (f64)py + 0.5 - radius
                let at = (py * side + px) * 4 + 3
                if dx * dx + dy * dy > radius * radius:
                    out[at] = 0
                else:
                    out[at] = (u8)math.round((f64)out[at] * fade)
        return out

    ## Where a clone stroke through (`x`, `y`) takes its pixels from, for the source crosshair.
    pub func clone_sample_x(x: f64) -> f64:
        return x + (f64)self.clone_offset_x if self.clone_aligned and self.clone_offset_set else self.clone_x

    pub func clone_sample_y(y: f64) -> f64:
        return y + (f64)self.clone_offset_y if self.clone_aligned and self.clone_offset_set else self.clone_y

## The retouching tools `Canvas.set_retouch` picks for strokes: 0 is plain paint.
let retouch_paint: i64 = 0
let retouch_clone: i64 = 1
let retouch_heal: i64 = 2
let retouch_blur: i64 = 3
let retouch_smudge: i64 = 4
let retouch_push: i64 = 5
let retouch_dodge: i64 = 6
let retouch_burn: i64 = 7

## `Canvas.begin_stroke` with a retouching tool: the stroke for it, begun at
## (`x`, `y`) on layer `id`, with its original remembered for undo.
func begin_retouch(canvas: Canvas*, id: u64, x: f64, y: f64, pen: Pen) -> !:
    let document = canvas.document else error(invalid, "draw the document once before retouching")
    var painter = canvas.painter else error(invalid, "draw the document once before retouching")
    let index = try canvas.index(id)
    # Quick Mask is a mask too: a retouch there would reach the layer under it.
    if (canvas.mask_editing and canvas.records[index].masked) or canvas.quick_mask():
        error(invalid, "retouching works on a layer's pixels, not its mask")
    let layer = document.find(id) else error(invalid, "no such layer")
    let tiles = layer.tiles() else error(invalid, "this layer has no pixels to retouch")
    let kind = canvas.retouch
    if kind == retouch_push:
        try begin_liquify(canvas, id, tiles, x, y)
        return
    if kind == retouch_smudge:
        var warp = try WarpStroke.begin(tiles, x, y, canvas.brush.diameter, canvas.brush.hardness, canvas.brush.opacity, spacing = canvas.smudge_spacing,
                                        srgb = document.mixes_encoded())
        errdefer warp.destroy()
        let boxed = try new WarpStroke in memory.heap
        *boxed = warp
        try canvas.remember(id, try tiles.clone(), name = "Smudge")
        canvas.warp = boxed
        canvas.warped = id
        # The worker holds the boxed stroke's address, so it starts there; a
        # worker that cannot start leaves the stroke walking here.
        if canvas.warp_async:
            boxed.start_async() catch failure:
                _ = failure
        return
    var brush = canvas.brush
    brush.erase = false
    # The effect is made cell by cell as the stroke reaches them
    # (retouch_effects.lucb), from the picture as it is now.
    var source: EffectSource? = none
    if kind == retouch_clone:
        if not canvas.clone_set:
            error(invalid, "Alt-click where the Clone Stamp copies from first")
        if not canvas.clone_aligned or not canvas.clone_offset_set:
            canvas.clone_offset_x = (i64)math.round(canvas.clone_x - x)
            canvas.clone_offset_y = (i64)math.round(canvas.clone_y - y)
            canvas.clone_offset_set = true
        source = try clone_source(canvas, tiles, canvas.clone_offset_x, canvas.clone_offset_y)
    elif kind == retouch_blur:
        source = try blur_source(canvas, tiles, math.clamp(brush.diameter / 10.0, 1.5, 30.0))
    elif kind == retouch_dodge or kind == retouch_burn:
        source = try tone_source(canvas, tiles, kind == retouch_dodge)
    elif kind == retouch_heal:
        # While painting, a dark wash marks the spot; healing replaces it at the end.
        canvas.heal_opacity = brush.opacity
        brush.color = gpu.Color(0.12, 0.12, 0.12, 1.0)
        brush.opacity = 0.45
    let begun = stroke_target(document, id, false, false) catch failure:
        if let unused = source:
            unused.release(unused.context)
        error(failure.code, failure.message)
    let stroke = begin_boxed(&painter, begun, brush, x, y, false, pen, &canvas.brush_images) catch failure:
        if let unused = source:
            unused.release(unused.context)
        error(failure.code, failure.message)
    errdefer finish_boxed(stroke)
    # A clone is stamped over what is there; a blur replaces it by coverage,
    # so softened edges thin out instead of piling up alpha with each pass.
    if let given = source:
        try stroke.use_effect_source(&painter, try stroke_target(document, id, false, true), given, 1.0 if kind == retouch_clone else 2.0, brush.opacity)
    try canvas.remember(id, try stroke.original().clone(), name = retouch_name(kind))
    canvas.stroke = stroke
    canvas.stroke_layer = id

## Continue a smudge to (`x`, `y`): recorded for the worker, or
## walked here without one. The next frame shows it.
func extend_warp(canvas: Canvas*, warp: WarpStroke*, x: f64, y: f64) -> !:
    let started = time.now()
    if warp.walks_async():
        try warp.record(x, y)
    else:
        try warp.extend(x, y)
    if tracing():
        trace_extend(time.now() - started)

## Upload what a smudge changed since the last frame, once a frame
## however many pointer moves came in; a stroke finishing whose worker is done
## is kept.
func settle_warp(canvas: Canvas*, warp: WarpStroke*) -> !:
    let started = time.now()
    # The cells whose reads are done go to the worker; the next reads go out.
    if warp.walks_async():
        try warp.service(false)
    let serviced = time.now()
    if canvas.warp_finishing and warp.finished():
        try keep_warp(canvas, warp)
        return
    let cells = try upload_warp(canvas, warp, upload_budget_ns)
    if tracing():
        trace_frame(serviced - started, time.now() - serviced, cells, warp.worker_stats(), warp.depth())

## Upload what changed, within `budget` nanoseconds (0: all of it); how many
## cells went up.
func upload_warp(canvas: Canvas*, warp: WarpStroke*, budget: u64) -> usize!:
    let document = canvas.document else trap("stroke without a document")
    let layer = document.find(canvas.warped) else error(invalid, "the retouched layer is gone")
    let tiles = layer.tiles() else error(invalid, "the retouched layer has no pixels")
    let cells = try warp.flush(tiles, budget)
    if cells > 0:
        layer.revision += 1
    return cells

## End a smudge. Walked on a worker, it returns at once and the
## worker finishes the path; the stroke is kept once it is done.
func finish_warp(canvas: Canvas*, warp: WarpStroke*) -> !:
    if warp.walks_async():
        warp.end_path()
        canvas.warp_finishing = true
        return
    try keep_warp(canvas, warp)

## Keep a smudge whose path is walked (waiting for its worker if it
## is not yet): its last cells go up, and it stays where the selection allows.
func keep_warp(canvas: Canvas*, warp: WarpStroke*) -> !:
    canvas.warp = none
    canvas.warp_finishing = false
    defer:
        warp.destroy()
        free(warp) in memory.heap
    try warp.wait()
    _ = try upload_warp(canvas, warp, 0)
    if tracing():
        trace_end()
    try canvas.restrict_to_selection(canvas.warped, &canvas.history[canvas.history_count - 1].tiles)

## A retouching stroke's name for the history.
func retouch_name(kind: i64) -> str:
    if kind == retouch_clone:
        return "Clone Stamp"
    if kind == retouch_heal:
        return "Spot Healing"
    if kind == retouch_dodge:
        return "Dodge"
    if kind == retouch_burn:
        return "Burn"
    return "Blur Tool"

## A cell's half-float texels into the preview at (`at_x`, `at_y`), as sRGB bytes.
func copy_cell(out: u8[], side: usize, bytes: const u8[], at_x: i64, at_y: i64):
    for ty in 0..<(i64)tile_size:
        let py = at_y + ty
        if py < 0 or py >= (i64)side:
            continue
        for tx in 0..<(i64)tile_size:
            let px = at_x + tx
            if px < 0 or px >= (i64)side:
                continue
            let source = (usize)(ty * (i64)tile_size + tx) * 8
            let target = (usize)(py * (i64)side + px) * 4
            for channel in 0..<(usize)4:
                let value = (f64)from_half((u16)bytes[source + channel * 2] | ((u16)bytes[source + channel * 2 + 1] << 8))
                let shown = value if channel == 3 else transfer.srgb_encode(math.clamp(value, 0.0, 1.0))
                out[target + channel] = (u8)math.round(math.clamp(shown, 0.0, 1.0) * 255.0)

## A clone preview's cells being read: from (`first_column`, `first_row`),
## `columns` wide, into `out` (`side` square at `left`, `top`).
struct CloneRead:
    var canvas: Canvas*
    var layer: Layer*
    var out: u8[]
    var side: usize
    var left: i64
    var top: i64
    var first_column: i64
    var first_row: i64
    var columns: i64

func clone_piece(context: void*?, index: usize) -> Piece!:
    let read = (CloneRead*)(context else trap("a clone preview lost its state"))
    let column = (u32)(read.first_column + (i64)index % read.columns)
    let row = (u32)(read.first_row + (i64)index // read.columns)
    var texture: gpu.Texture? = none
    if read.canvas.clone_all:
        let composer = read.canvas.composer else error(invalid, "draw the document once before previewing a clone")
        let document = read.canvas.document else error(invalid, "draw the document once before previewing a clone")
        texture = try composer.tile(document, column, row, 0)
    elif let tiles = read.layer.tiles():
        texture = (try tiles.texture(column, row))
    let cell = texture else return no_piece()
    return Piece(texture = cell, region = gpu.Region(0, 0, tile_size, tile_size), present = true)

func clone_visit(context: void*?, index: usize, bytes: const u8[]) -> !:
    let read = (CloneRead*)(context else trap("a clone preview lost its state"))
    if bytes.length == 0:
        return
    let column = read.first_column + (i64)index % read.columns
    let row = read.first_row + (i64)index // read.columns
    copy_cell(read.out, read.side, bytes, column * (i64)tile_size - read.left, row * (i64)tile_size - read.top)