dymokomi/luce-image
Source of release 0.45.1
0.45.1 / src / document / module.lucb
#==============================================================================================
#
# document - A layered document
#
# DESCRIPTION:
# A tree of layers over a canvas of fixed size, each raster layer holding shared GPU tiles
# in document space. Groups hold layers bottom to top and are pass-through: their opacity
# multiplies into their children and their visibility gates them. Editing replaces a
# layer's tiles; every replacement bumps revisions that the compositor keys its cache on.
# Fragments, in ORDER:
#
# module.lucb the Document: its tree, edits, masks, selection and states for undo
# style.lucb a layer's styles (Photoshop's layer effects) and their numbered fields
# layer.lucb a Layer, the tree helpers, and TreeState (the tree at one moment)
#
#==============================================================================================
from luce_gpu import gpu
from luce_std import math
import memory
import strings
from luce_canvas.tiles import Tiles, CellRange, box, unbox
from extent import relocate
from selection import Selection
from curves import Curves
from luce_painting.mixing import Mixing
from luce_raster.errors import invalid, limit
from digest import fnv_start, fnv_mix
pub struct Document:
var owner: gpu.Device
var extent_x: u32
var extent_y: u32
## The selection, part of the document so history can cover it.
pub var selection: Selection
var root: Layer*
var next_id: u64
## Bumps whenever the tree changes shape or a layer's attributes change.
pub var revision: u64
## How many times history has swapped the tree: each swap moves every
## layer's revision into a band of its own (see `exchange`).
var generation: u64
## Quick Mask's layer while it is on: outside the tree, so never composited,
## exported or saved, but found by its id so every painting tool reaches
## its mask, which holds the selection being painted.
var quick: Layer*? = none
## While Quick Mask is on the selection clips nothing.
pub var selection_suspended: bool = false
## Photoshop's "Blend RGB Colors Using Gamma 1.0": colors mix in linear
## light. Off (the default), every place colors mix — compositing, painting,
## fills, gradients, filters, resampling — mixes their sRGB-encoded values,
## as Photoshop does, while the tiles keep holding linear light.
pub var linear_blend: bool = false
## Whether an edit mixes sRGB-encoded values: colors do unless the document
## blends in linear light; a mask's values (coverage) mix as they are.
pub func mixes_encoded(on_mask: bool = false) -> bool:
return not on_mask and not self.linear_blend
## `mixes_encoded` as the mixing shaders take it: 1 or 0.
pub func srgb_flag(on_mask: bool = false) -> f32:
return 1.0 if self.mixes_encoded(on_mask) else 0.0
## How an edit of this document (on a mask with `on_mask`) mixes (luce-painting's mixing).
pub func mixing(on_mask: bool = false) -> Mixing:
return Mixing(srgb = self.mixes_encoded(on_mask), mask = on_mask)
## An empty `width` by `height` document with no layers.
pub static func create(device: gpu.Device, width: u32, height: u32) -> Document!:
if width == 0 or height == 0 or width > 65536 or height > 65536:
error(invalid, "document dimensions must be in 1..65536")
var title: str = ""
with memory.heap:
title = try strings.copy("root")
let root = try new Layer(id = 0, name = title, group = true, pixels = none, revision = 0) in memory.heap
var selection = try Selection.create(width, height)
errdefer selection.destroy()
return Document(owner = device, extent_x = width, extent_y = height, selection = selection, root = root, next_id = 1, revision = 1, generation = 0)
pub func width() -> u32:
return self.extent_x
pub func height() -> u32:
return self.extent_y
pub func device() -> gpu.Device:
return self.owner
## The top-level layers, bottom to top.
pub func layers() -> Layer*[]:
return self.root.layers()
## The layer with `id`, borrowed: Quick Mask's too.
pub func find(id: u64) -> Layer*?:
if let quick = self.quick:
if quick.id == id:
return quick
return find_in(self.root, id)
## Put Quick Mask's layer up with `mask` (taken) as its mask; its id.
pub func begin_quick(mask: Tiles) -> u64!:
var owned_mask = mask
errdefer owned_mask.destroy()
if self.quick != none:
error(invalid, "Quick Mask is already on")
let pixels = try box(try Tiles.create(self.owner, self.extent_x, self.extent_y))
var name: str = ""
with memory.heap:
name = try strings.copy("Quick Mask")
let layer = try new Layer(id = self.next_id, name = name, group = false, pixels = pixels, revision = 1) in memory.heap
layer.mask = try box(owned_mask)
self.next_id += 1
self.quick = layer
self.selection_suspended = true
return layer.id
## Quick Mask's layer, while it is on.
pub func quick_layer() -> Layer*?:
return self.quick
## Take Quick Mask's layer down.
pub func end_quick():
self.selection_suspended = false
let quick = self.quick else return
self.quick = none
layer_destroy(quick)
## Add a transparent raster layer on top of `parent` (the root by default).
pub func add_layer(name: str, parent: u64? = none) -> u64!:
let tiles = try Tiles.create(self.owner, self.extent_x, self.extent_y)
return try self.add(name, parent, false, tiles)
## Add an adjustment layer of `kind` with `values` (at most 23) on top of
## `parent` (the root by default).
pub func add_adjustment(name: str, kind: i64, values: const f64[], parent: u64? = none) -> u64!:
let id = try self.add(name, parent, false, none)
try self.set_adjustment(id, kind, values)
return id
## Give Curves adjustment layer `id` its curves anew.
pub func set_curves(id: u64, curves: Curves) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
if layer.adjustment < 0:
error(invalid, "only an adjustment layer takes curves")
layer.curves = curves
layer.revision += 1
self.revision += 1
## Give adjustment layer `id` its kind and parameters anew.
pub func set_adjustment(id: u64, kind: i64, values: const f64[]) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
if layer.group or layer.pixels != none:
error(invalid, "only an adjustment layer takes adjustment settings")
if values.length > 23:
error(invalid, "an adjustment takes at most 23 parameters")
layer.adjustment = kind
for index in 0..<(usize)23:
layer.adjustment_values[index] = values[index] if index < values.length else 0.0
layer.revision += 1
self.revision += 1
## Add an empty group on top of `parent` (the root by default).
pub func add_group(name: str, parent: u64? = none) -> u64!:
return try self.add(name, parent, true, none)
## Give layer `id` a new name.
pub func rename(id: u64, name: str) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
var copied: str = ""
with memory.heap:
copied = try strings.copy(name)
strings.release(layer.name)
layer.name = copied
func add(name: str, parent: u64?, group: bool, tiles: Tiles?) -> u64!:
var holder: Tiles*? = none
if let owned = tiles:
holder = try box(owned)
errdefer release_tiles(&holder)
var target = self.root
if let id = parent:
target = self.find(id) else error(invalid, "no such parent layer")
if not target.group:
error(invalid, "only a group can hold layers")
try make_room(target)
var copied: str = ""
with memory.heap:
copied = try strings.copy(name)
errdefer strings.release(copied)
let id = self.next_id
let layer = try new Layer(id = id, name = copied, group = group, pixels = holder, revision = 1) in memory.heap
holder = none
target.children[target.child_count] = layer
target.child_count += 1
self.next_id += 1
self.revision += 1
return id
## Move a layer — a group with everything in it — into group `parent` (the
## top level when none) at `position` among its layers, 0 the bottom; past
## the top it goes on top. A group cannot go inside itself.
pub func move_to(id: u64, parent: u64?, position: usize) -> !:
let moving = self.find(id) else error(invalid, "no such layer")
var target = self.root
if let parent_id = parent:
target = self.find(parent_id) else error(invalid, "no such parent layer")
if not target.group:
error(invalid, "only a group can hold layers")
if parent_id == id or find_in(moving, parent_id) != none:
error(invalid, "a group cannot go inside itself")
# Room first, so a failed allocation leaves the tree as it was.
try make_room(target)
let source = parent_of(self.root, id) else error(invalid, "no such layer")
var index: usize = 0
while source.children[index].id != id:
index += 1
for shift in index..<(source.child_count - 1):
source.children[shift] = source.children[shift + 1]
source.child_count -= 1
let at = position if position < target.child_count else target.child_count
var shift = target.child_count
while shift > at:
target.children[shift] = target.children[shift - 1]
shift -= 1
target.children[at] = moving
target.child_count += 1
self.revision += 1
## The group holding `id`, or none at the top level.
pub func parent_id(id: u64) -> u64?:
let parent = parent_of(self.root, id) else return none
return none if parent == self.root else parent.id
## Where `id` sits among its parent's layers, 0 the bottom.
pub func position(id: u64) -> usize!:
let parent = parent_of(self.root, id) else error(invalid, "no such layer")
var index: usize = 0
while parent.children[index].id != id:
index += 1
return index
## A copy of layer `id` and all it holds, its tiles shared (cheap), for
## the layer clipboard; `release_snapshot` frees it.
pub func snapshot(id: u64) -> Layer*!:
let layer = self.find(id) else error(invalid, "no such layer")
return try clone_layer(layer)
## Put a copy of `layer` — a snapshot from this document or another, with
## all it holds — into group `parent` (the top level when none) at
## `position`, its pixels and mask moved by (`offset_x`, `offset_y`) onto
## this document's canvas. Every layer in it gets a new id, in pre-order
## from the one returned.
pub func adopt(layer: const Layer*, parent: u64?, position: usize, offset_x: f64, offset_y: f64) -> u64!:
var target = self.root
if let parent_id = parent:
target = self.find(parent_id) else error(invalid, "no such parent layer")
if not target.group:
error(invalid, "only a group can hold layers")
try make_room(target)
let first = self.next_id
let copy = try self.transplant(layer, offset_x, offset_y)
let at = position if position < target.child_count else target.child_count
var shift = target.child_count
while shift > at:
target.children[shift] = target.children[shift - 1]
shift -= 1
target.children[at] = copy
target.child_count += 1
self.revision += 1
return first
## `layer` copied onto this canvas with new ids: tiles shared when they
## land as they are, else drawn anew where they land.
func transplant(layer: const Layer*, offset_x: f64, offset_y: f64) -> Layer*!:
var copied: str = ""
with memory.heap:
copied = try strings.copy(layer.name)
errdefer strings.release(copied)
var pixels: Tiles*? = none
if let tiles = layer.pixels:
pixels = try box(try self.landed(tiles, offset_x, offset_y, false))
errdefer release_tiles(&pixels)
let copy = try new Layer(id = self.next_id, name = copied, group = layer.group, pixels = pixels, revision = 1) in memory.heap
self.next_id += 1
errdefer layer_destroy(copy)
copy.visible = layer.visible
copy.opacity = layer.opacity
copy.blend = layer.blend
copy.clipped = layer.clipped
copy.style = layer.style
copy.mask_enabled = layer.mask_enabled
copy.adjustment = layer.adjustment
copy.adjustment_values = layer.adjustment_values
copy.curves = layer.curves
if let mask = layer.mask:
copy.mask = try box(try self.landed(mask, offset_x, offset_y, true))
if layer.child_count > 0:
copy.children = try new Layer*[layer.child_count] --- in memory.heap
for index in 0..<layer.child_count:
copy.children[index] = try self.transplant(layer.children[index], offset_x, offset_y)
copy.child_count += 1
return copy
## `tiles` as they land on this canvas moved by (`offset_x`, `offset_y`);
## a `mask` reads white where nothing lands.
func landed(tiles: const Tiles*, offset_x: f64, offset_y: f64, mask: bool) -> Tiles!:
let device = tiles.device()
if not device.same(&self.owner):
error(invalid, "layers move only between documents on one GPU device")
if tiles.width() == self.extent_x and tiles.height() == self.extent_y and offset_x == 0.0 and offset_y == 0.0:
return try tiles.clone()
var moved = try Tiles.create(self.owner, self.extent_x, self.extent_y)
errdefer moved.destroy()
let empty = 1.0 if mask else 0.0
try relocate(tiles, &moved, 1.0, 1.0, offset_x, offset_y, false, gpu.Color(empty, empty, empty, empty))
return moved
## Keep a layer's mask but stop it hiding anything, or bring it back.
pub func enable_mask(id: u64, enabled: bool) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
layer.mask_enabled = enabled
layer.revision += 1
self.revision += 1
## Move a layer one step up (`step` 1) or down (-1) among its siblings.
pub func reorder(id: u64, step: i64) -> !:
let parent = parent_of(self.root, id) else error(invalid, "no such layer")
var index: usize = 0
while parent.children[index].id != id:
index += 1
let target = (i64)index + step
if target < 0 or target >= (i64)parent.child_count:
return
let moved = parent.children[index]
parent.children[index] = parent.children[(usize)target]
parent.children[(usize)target] = moved
self.revision += 1
## Copy a raster layer with its mask and appearance, placed just above it.
pub func duplicate(id: u64, name: str) -> u64!:
let source = self.find(id) else error(invalid, "no such layer")
if source.group:
error(invalid, "groups cannot be duplicated yet")
let tiles = source.tiles() else error(invalid, "no pixels to duplicate")
var copy = try tiles.clone()
errdefer copy.destroy()
let parent = parent_of(self.root, id) else error(invalid, "no such layer")
let created = try self.add(name, none if parent == self.root else parent.id, false, copy)
let layer = self.find(created) else trap("just added")
layer.visible = source.visible
layer.opacity = source.opacity
layer.blend = source.blend
layer.clipped = source.clipped
if let mask = source.mask_tiles():
var mask_copy = try mask.clone()
errdefer mask_copy.destroy()
layer.mask = try box(mask_copy)
# Place it right above the source.
var origin: usize = 0
while parent.children[origin].id != created:
origin += 1
var to: usize = 0
while parent.children[to].id != id:
to += 1
let moved = parent.children[origin]
var index = origin
while index > to + 1:
parent.children[index] = parent.children[index - 1]
index -= 1
parent.children[to + 1] = moved
self.revision += 1
return created
## The sibling directly below `id`, if any.
pub func below(id: u64) -> Layer*?:
let parent = parent_of(self.root, id) else return none
var index: usize = 0
while parent.children[index].id != id:
index += 1
if index == 0:
return none
return parent.children[index - 1]
## Remove a layer or a group with everything in it.
pub func remove(id: u64) -> !:
if not remove_in(self.root, id):
error(invalid, "no such layer")
self.revision += 1
## Replace a raster layer's pixels, taking ownership of `tiles`.
pub func set_tiles(id: u64, tiles: Tiles) -> !:
var holder: Tiles*? = try box(tiles)
errdefer release_tiles(&holder)
let layer = self.find(id) else error(invalid, "no such layer")
if layer.group or tiles.width() != self.extent_x or tiles.height() != self.extent_y:
error(invalid, "tiles must match a raster layer of the document's size")
if let previous = layer.pixels:
unbox(previous)
layer.pixels = holder
layer.revision += 1
## Replace a raster layer's pixels with `tiles` and hand back the pixels it
## had, for history.
pub func take_tiles(id: u64, tiles: Tiles) -> Tiles!:
var holder: Tiles*? = try box(tiles)
errdefer release_tiles(&holder)
let layer = self.find(id) else error(invalid, "no such layer")
let previous = layer.pixels else error(invalid, "a group has no pixels")
if tiles.width() != self.extent_x or tiles.height() != self.extent_y:
error(invalid, "tiles must match the document's size")
layer.pixels = holder
layer.revision += 1
let taken = *previous
free(previous) in memory.heap
return taken
## Adopt new extents after every layer has been rebuilt for them.
## The tree, extent and selection as they are, for undo.
pub func capture() -> TreeState!:
let root = try clone_layer(self.root)
errdefer layer_destroy(root)
var selection = try self.selection.copy()
errdefer selection.destroy()
var quick: Layer*? = none
if let layer = self.quick:
quick = try clone_layer(layer)
return TreeState(root = root, next_id = self.next_id, extent_x = self.extent_x, extent_y = self.extent_y, selection = selection, quick = quick,
linear_blend = self.linear_blend)
## The document as it is now, on the heap, sharing its tiles: what a
## stroke reads while it paints (a Clone Stamp sampling every layer).
## `unbox_document` frees it.
pub func frozen() -> Document*!:
let root = try clone_layer(self.root)
errdefer layer_destroy(root)
var selection = try self.selection.copy()
errdefer selection.destroy()
return try new Document(owner = self.owner, extent_x = self.extent_x, extent_y = self.extent_y, selection = selection,
root = root, next_id = self.next_id, revision = self.revision, generation = self.generation,
linear_blend = self.linear_blend) in memory.heap
## Take `state` as the document and leave what was in its place: undo and
## redo swap, never copy.
pub func exchange(state: TreeState*):
let root = self.root
self.root = state.root
state.root = root
let next_id = self.next_id
self.next_id = state.next_id
state.next_id = next_id
let width = self.extent_x
self.extent_x = state.extent_x
state.extent_x = width
let height = self.extent_y
self.extent_y = state.extent_y
state.extent_y = height
let selection = self.selection
self.selection = state.selection
state.selection = selection
# Quick Mask comes and goes with the steps that turned it on and off.
let quick = self.quick
self.quick = state.quick
state.quick = quick
self.selection_suspended = self.quick != none
let linear_blend = self.linear_blend
self.linear_blend = state.linear_blend
state.linear_blend = linear_blend
# History keeps the cells alone, not their GPU tiles.
state.selection.drop_gpu_tiles()
self.revision += 1
# The layers coming back carry the revisions they had when taken, and
# counting on from there would reach numbers the compositor's cache
# holds for other pixels: move them into a band of their own.
self.generation += 1
restamp(self.root, self.generation)
pub func set_extent(width: u32, height: u32) -> !:
self.extent_x = width
self.extent_y = height
var replacement = try Selection.create(width, height)
self.selection.destroy()
self.selection = replacement
self.revision += 1
## The selection's GPU tiles, or none when nothing is selected.
pub func selection_tiles() -> Tiles*?!:
if self.selection_suspended:
return none
return try self.selection.gpu_tiles(self.owner)
## As `selection_tiles`, catching up only the cells in `wanted` and `extra`
## more (see `Selection.gpu_tiles_within`): for drawing the ants.
pub func selection_tiles_within(wanted: CellRange, extra: usize) -> Tiles*?!:
if self.selection_suspended:
return none
return try self.selection.gpu_tiles_within(self.owner, wanted, extra)
## Whether the selection's GPU tiles still lag it somewhere.
pub func selection_behind() -> bool:
return self.selection.gpu_behind()
## Give a layer or a group an empty mask (revealing everything) or take it away.
pub func set_mask(id: u64, present: bool) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
if present and layer.mask == none:
let tiles = try Tiles.create(self.owner, self.extent_x, self.extent_y)
layer.mask = try box(tiles)
elif not present:
if let tiles = layer.mask:
unbox(tiles)
layer.mask = none
layer.revision += 1
self.revision += 1
## Replace a layer's mask with `tiles` and hand back the mask it had.
pub func take_mask(id: u64, tiles: Tiles) -> Tiles!:
var holder: Tiles*? = try box(tiles)
errdefer release_tiles(&holder)
let layer = self.find(id) else error(invalid, "no such layer")
let previous = layer.mask else error(invalid, "the layer has no mask")
if tiles.width() != self.extent_x or tiles.height() != self.extent_y:
error(invalid, "tiles must match the document's size")
layer.mask = holder
layer.revision += 1
let taken = *previous
free(previous) in memory.heap
return taken
## Clip a layer to the one below, or unclip it.
pub func set_clipped(id: u64, clipped: bool) -> !:
let layer = self.find(id) else error(invalid, "no such layer")
layer.clipped = clipped
self.revision += 1
## Set a layer's visibility, opacity and blend mode.
pub func set_appearance(id: u64, visible: bool, opacity: f64, blend: u32 = 0) -> !:
if not (opacity >= 0.0 and opacity <= 1.0):
error(invalid, "opacity must be in 0..1")
if blend > blend_mode_count - 1:
error(invalid, "no such blend mode")
let layer = self.find(id) else error(invalid, "no such layer")
layer.visible = visible
layer.opacity = opacity
layer.blend = blend
self.revision += 1
pub func destroy():
self.end_quick()
self.selection.destroy()
layer_destroy(self.root)
## Move a document onto the heap, for holders that keep a pointer.
pub func box_document(document: Document) -> Document*!:
# Not zeroable, so field by field: a new field must be added here too.
return try new Document(owner = document.owner, extent_x = document.extent_x, extent_y = document.extent_y, selection = document.selection,
root = document.root, next_id = document.next_id, revision = document.revision, generation = document.generation,
linear_blend = document.linear_blend) in memory.heap
## Destroy a boxed document and free the box.
pub func unbox_document(document: Document*):
document.destroy()
free(document) in memory.heap
test "document layers, groups, removal and appearance":
var device = gpu.Device.open() catch failure:
assert(failure.code == gpu.unavailable)
return
defer device.destroy()
var document = try Document.create(device, 64, 48)
defer document.destroy()
let background = try document.add_layer("Background")
let group = try document.add_group("Group")
let inner = try document.add_layer("Inner", group)
assert(document.layers().length == 2 and document.layers()[1].id == group)
let found = document.find(inner) else trap("missing layer")
assert(found.name == "Inner" and found.tiles() != none and found.revision == 1)
assert((document.find(group) else trap("missing group")).layers()[0].id == inner)
try document.set_appearance(background, false, 0.5)
assert(not (document.find(background) else trap("missing")).visible)
var rejected = false
_ = document.add_layer("Bad", inner) catch failure:
assert(failure.code == invalid)
rejected = true
recover 0
assert(rejected)
let replacement = try Tiles.create(device, 64, 48)
try document.set_tiles(inner, replacement)
assert(found.revision == 2)
try document.remove(group)
assert(document.find(inner) == none and document.layers().length == 1)
let second = try document.add_layer("Second")
try document.set_appearance(second, true, 0.5, 6)
let copy = try document.duplicate(second, "Second copy")
assert(document.layers().length == 3 and document.layers()[2].id == copy and (document.find(copy) else trap("copy")).blend == 6)
try document.reorder(copy, -3)
assert(document.layers()[2].id == copy)
try document.reorder(copy, -1)
assert(document.layers()[1].id == copy and document.layers()[2].id == second)
assert((document.below(second) else trap("below")).id == copy and document.below(background) == none)