Skip to main content

Layer System & Alpha Lock 📚

In Fuderu, artwork is composed of stacked transparent layers (like clear plastic acetate animation cels). Working with layers allows non-destructive drawing: you can ink on one layer, color underneath on another, and shade with blend modes on top without damaging your underlying lines.

import { Canvas } from "fuderu";

const painter = new Canvas({
canvas: "#my-canvas",
document: { width: 1200, height: 800 },
});

1. Creating and Managing Layers​

Every new Canvas starts with a default background layer. You can create additional layers at any time:

// 1. Create a new layer
const inkLayer = painter.createLayer("Inking");

// 2. Make it the active layer you draw onto
painter.setActiveLayer(inkLayer.id);

// 3. Inspect all layers currently in the stack (bottom to top)
const layers = painter.getLayers();
console.log(layers.map((l) => l.name)); // ["Background", "Inking"]

Layer Management Methods​

All layer operations are invoked directly on the Canvas instance:

MethodDescription
painter.createLayer(name?, options?)Creates and inserts a new layer at the top of the stack.
painter.getLayers()Returns an immutable, frozen list of LayerSnapshot objects.
painter.getActiveLayer()Returns the currently active Layer being painted onto.
painter.setActiveLayer(layerId)Switches active drawing target to the specified layer.
painter.updateLayer(layerId, options)Updates properties (opacity, blend mode, visibility, locks).
painter.deleteLayer(layerId)Removes a layer. (Cannot delete the last remaining layer).
painter.duplicateLayer(layerId)Clones a layer and all its raster pixels.
painter.reorderLayer(layerId, newIndex)Moves a layer up or down in the rendering stack.
painter.mergeLayerDown(layerId)Merges a layer with the one directly beneath it.

2. Layer Properties​

You can update any layer's properties on the fly:

painter.updateLayer(inkLayer.id, {
name: "Clean Lineart",
opacity: 0.85, // Value between 0.0 (transparent) and 1.0 (opaque)
visible: true, // Toggle layer visibility on/off
blendMode: "multiply", // How pixels blend with layers below
alphaLock: false, // Stencil lock to existing pixels
locked: false, // Prevent any modifications or accidental drawing
});

3. Alpha Lock: Color Inside the Lines 🔒​

alphaLock is an artist's favorite feature. When enabled, transparent pixels are completely protected. Any new paint, brush stroke, or fill operation will only modify existing colored pixels.

// Step 1: Draw a black circle on a transparent layer
painter.drawEllipse(200, 200, 80, 80, { fill: true, stroke: false });

// Step 2: Lock the alpha channel
painter.updateLayer(activeLayer.id, { alphaLock: true });

// Step 3: Switch brush color to gold and paint across the entire canvas
painter.loadConfig({ color: "#f59e0b", size: 40 });
// Even if your stroke covers the whole screen, only the circle turns gold!

💡 Tip: Alpha Lock is great for cell shading, recoloring lineart, adding highlights, and applying textures without needing complex clipping masks.


4. Layer Lock: Protecting Finished Work 🛡️​

To prevent accidental edits, deletions, or cuts on a finished layer, set locked: true:

painter.updateLayer(backgroundLayer.id, { locked: true });

// Attempting to draw or cut on a locked layer throws a descriptive error:
// Error: Cannot paint onto locked layer

5. Blend Modes​

Fuderu supports 16 standard W3C blend modes mapping to globalCompositeOperation:

  • Normal: source-over
  • Darkening: multiply, darken, color-burn
  • Lightening: screen, lighten, color-dodge
  • Contrast: overlay, soft-light, hard-light
  • Comparative: difference, exclusion
  • HSL Components: hue, saturation, color, luminosity

For visual demonstrations and mathematical explanations of each mode, see the Blend Modes Guide.


6. Reactive UI Synchronization​

Fuderu dispatches layer:change whenever any layer is added, removed, reordered, or edited:

painter.on("layer:change", (snapshot) => {
console.log("Current layer stack:", snapshot.layers);
console.log("Active layer:", snapshot.activeLayerId);
// Re-render your UI layer list or thumbnails
});

7. Immutable Layer Snapshots (getLayerSnapshots())​

To integrate cleanly with reactive state management (such as React useSyncExternalStore, Zustand, Svelte stores, or Vue ref), Canvas exposes painter.getLayerSnapshots():

const layerSnapshots = painter.getLayerSnapshots();

for (const snap of layerSnapshots) {
console.log(snap.id, snap.name, snap.visible, snap.opacity, snap.locked);
}

Each item in the returned array is an immutable, frozen LayerSnapshot Data Transfer Object (DTO). Snapshots are cached internally, ensuring painter.getLayerSnapshots() executes in constant time, O(1), without re-allocating objects unless a layer property has mutated.