Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor clip path handling and enhance SVG support

konstantin-paulus8a1313b77711
diff --git a/apps/desktop/src/source.ts b/apps/desktop/src/source.ts
index 99ec8a74..c1ea7a69 100644
--- a/apps/desktop/src/source.ts
+++ b/apps/desktop/src/source.ts
@@ -28,10 +28,12 @@ const COMPOSITION_COMPONENTS = new Map<string, string>(
// These composition names also exist in SVG. An SVG fragment is DOM content
// only while it has an SVG container in the same JSX tree; elsewhere the tag
-// keeps its composition meaning.
-const AMBIGUOUS_SVG_TAGS: ReadonlySet<string> = new Set(["rect", "ellipse", "polygon", "path", "text", "image"]);
+// keeps its composition meaning. `<mask>` and `<clipPath>` are SVG containers
+// too, but as such they only ever sit in an `<svg>`, so they are not counted
+// as one: a composition `<mask>` keeps the shapes under it composition ones.
+const AMBIGUOUS_SVG_TAGS: ReadonlySet<string> = new Set(["rect", "ellipse", "polygon", "path", "text", "image", "mask", "clipPath"]);
const SVG_CONTAINERS: ReadonlySet<string> = new Set([
- "svg", "g", "defs", "symbol", "marker", "mask", "clipPath", "pattern",
+ "svg", "g", "defs", "symbol", "marker", "pattern",
"filter", "linearGradient", "radialGradient", "textPath", "tspan", "switch",
]);
diff --git a/apps/web/src/components/sidebar-right/inspector/clip-paths.tsx b/apps/web/src/components/sidebar-right/inspector/clip-paths.tsx
index 1775ccfb..6e95771f 100644
--- a/apps/web/src/components/sidebar-right/inspector/clip-paths.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/clip-paths.tsx
@@ -23,13 +23,11 @@ type ClipPathsSettingsProps = {
};
/**
- * The clip path children of the selected node (`<rect clipPath>`,
- * `<ellipse clipPath>`, `<polygon clipPath>`, `<path clipPath>`): the shapes it is clipped to
- * (several intersect). A clip path is a shape like any other, so it
- * has no inspector of its own — a row selects it and the transform, time and
- * appearance panels are then its own. The plus picks up the clip path tool,
- * whose bar over the canvas turns the shapes selected there into clip paths
- * of this node.
+ * The `<clipPath>`s of the selected node, one row each (several intersect).
+ * A clip path is the shapes under it and has no inspector of its own: a row
+ * selects its shapes, whose transform, time and appearance panels are then
+ * the ones shown. The plus picks up the clip path tool, whose bar over the
+ * canvas puts the shapes selected there into a new clip path of this node.
*/
export function ClipPathsSettings(props: ClipPathsSettingsProps) {
const world = useWorld();
@@ -61,7 +59,7 @@ export function ClipPathsSettings(props: ClipPathsSettingsProps) {
{(clipPath) => (
<ClipPathRow
clipPath={clipPath}
- onSelect={() => editor.select(clipPath)}
+ onSelect={() => editor.select(clipPath.get(Cache)?.children ?? [])}
onRemove={() => editor.remove(clipPath)}
/>
)}
diff --git a/apps/web/src/components/sidebar-right/inspector/inspector.tsx b/apps/web/src/components/sidebar-right/inspector/inspector.tsx
index 7955d0e3..c63eb83d 100644
--- a/apps/web/src/components/sidebar-right/inspector/inspector.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/inspector.tsx
@@ -11,7 +11,7 @@ import {
isAudio,
isCaption,
isGroup,
- isClipPath,
+ isClipShape,
isPath,
isScene,
isSequence,
@@ -62,7 +62,7 @@ export type SelectionTarget =
function classifyNode(entity: Entity): SelectionTarget {
if (isScene(entity)) return "scene";
- if (isClipPath(entity)) return "clip-path";
+ if (isClipShape(entity)) return "clip-path";
if (isSequence(entity)) return "sequence";
if (isCaption(entity)) return "caption";
if (isAudio(entity)) return "audio";
diff --git a/apps/web/src/components/timeline/layers/context.tsx b/apps/web/src/components/timeline/layers/context.tsx
index 12d20948..ed6384b8 100644
--- a/apps/web/src/components/timeline/layers/context.tsx
+++ b/apps/web/src/components/timeline/layers/context.tsx
@@ -4,7 +4,7 @@
import { createContext, createSignal, onCleanup, useContext, type JSX, type Signal } from "solid-js";
import { useWorld } from "@diffusionstudio/koota-solid";
-import { Expanded, getEntityTree, isClipPath, isSequence } from "@diffusionstudio/runtime";
+import { Expanded, getEntityTree, isSequence } from "@diffusionstudio/runtime";
import { useEditor, useTimelineIndex } from "@/engine/hooks";
import { useTimeline } from "@/context/timeline";
@@ -51,7 +51,7 @@ export function LayerContextProvider(props: { children: JSX.Element }) {
const [target, setTarget] = createSignal<DropTarget | null>(null);
let pending: { entity: Entity; startX: number; startY: number } | null = null;
- let active: { entity: Entity; forbidden: Set<Entity>; isClipPath: boolean } | null = null;
+ let active: { entity: Entity; forbidden: Set<Entity> } | null = null;
let dwell: { entity: Entity; since: number } | null = null;
let pointerX = 0;
let pointerY = 0;
@@ -74,7 +74,6 @@ export function LayerContextProvider(props: { children: JSX.Element }) {
active = {
entity,
forbidden: new Set(getEntityTree(world, entity)),
- isClipPath: isClipPath(entity),
};
dirty = true;
setDragging(entity);
@@ -190,7 +189,6 @@ export function LayerContextProvider(props: { children: JSX.Element }) {
root,
dragged: active.entity,
forbidden: active.forbidden,
- draggedIsClipPath: active.isClipPath,
containerRect,
listBottom: getListBottom(layersEl, containerRect),
};
diff --git a/apps/web/src/components/timeline/layers/drag.ts b/apps/web/src/components/timeline/layers/drag.ts
index 6dec6c22..bd25a52f 100644
--- a/apps/web/src/components/timeline/layers/drag.ts
+++ b/apps/web/src/components/timeline/layers/drag.ts
@@ -13,7 +13,7 @@
* rect, depth and ancestor chain without the rows registering anything.
*/
-import { isGroupLike, isClipPath, isSequence } from '@diffusionstudio/runtime';
+import { isGroupLike, isSequence } from '@diffusionstudio/runtime';
import { NESTED_INDENT_PX } from './config';
import type { Accessor } from 'solid-js';
@@ -70,8 +70,6 @@ export type GapContext = {
dragged: Entity;
/** The dragged subtree: nothing in it may become the parent of the drop. */
forbidden: Set<Entity>;
- /** Clip paths stack apart from plain layers; anchors must stay in their bucket. */
- draggedIsClipPath: boolean;
containerRect: DOMRect;
/** Client Y just below the last row of the whole list. */
listBottom: number;
@@ -216,9 +214,7 @@ export function resolveGap(gapIndex: number, rows: FlatRow[], x: number, context
/**
* The document sibling to insert before: the nearest row above the gap at
- * the chosen depth. Restricted to the dragged layer's stacking bucket —
- * clip paths and plain layers render as separate runs, so an anchor from the
- * other bucket would land the row somewhere the line never was.
+ * the chosen depth.
*/
function scanAnchor(
rows: FlatRow[],
@@ -233,7 +229,7 @@ function scanAnchor(
if (row.depth > depth) continue;
if (row.parent !== parent) break;
if (row.node.entity === context.dragged) continue;
- if (isClipPath(row.node.entity) === context.draggedIsClipPath) return row.node.entity;
+ return row.node.entity;
}
return undefined;
diff --git a/apps/web/src/components/timeline/layers/node.tsx b/apps/web/src/components/timeline/layers/node.tsx
index 5a819eb7..53e5e760 100644
--- a/apps/web/src/components/timeline/layers/node.tsx
+++ b/apps/web/src/components/timeline/layers/node.tsx
@@ -19,7 +19,7 @@ import {
isAdjustmentLayer,
isCaption,
isGroup,
- isClipPath,
+ isClipShape,
isEllipse,
isPath,
isPolygon,
@@ -354,7 +354,7 @@ export function NodeLayer(props: LayerRowProps) {
function getLayerIcon(world: World, layer: TimelineNode) {
const entity = layer.entity;
- if (isClipPath(entity)) return "mask-small";
+ if (isClipShape(entity)) return "mask-small";
if (isAdjustmentLayer(entity)) return "adjustment-layer";
if (isScene(entity)) return "scene-frame-small";
if (isSequence(entity)) return "timeline-sequence-small";
diff --git a/apps/web/src/components/timeline/layers/sub-item.tsx b/apps/web/src/components/timeline/layers/sub-item.tsx
index d87a5f9d..1e068460 100644
--- a/apps/web/src/components/timeline/layers/sub-item.tsx
+++ b/apps/web/src/components/timeline/layers/sub-item.tsx
@@ -5,10 +5,12 @@
import { createMemo, Show } from 'solid-js';
import { useTag, useWorld } from '@diffusionstudio/koota-solid';
import {
+ ClipPath,
ColorStop,
Effect,
Expanded,
Hovering,
+ Mask,
Name,
Paint,
PaintType,
@@ -40,9 +42,10 @@ const PAINT_NAMES: Partial<Record<PaintType, string>> = {
};
/**
- * A row for one of a clip's parts — a fill, a stroke, a shadow, an effect —
- * which is here only so the keyframe rows under it have something to hang
- * from. It has no clip of its own on the canvas beside it.
+ * A row for one of a clip's parts — a fill, a stroke, a shadow, an effect, a
+ * clip path or mask — which is here only so the keyframe rows and layers
+ * under it have something to hang from. It has no clip of its own on the
+ * canvas beside it.
*/
export function SubItemLayer(props: LayerRowProps) {
const world = useWorld();
@@ -105,6 +108,8 @@ function describe(entity: Entity): string {
if (entity.has(Stroke)) return 'Stroke';
if (entity.has(Shadow)) return 'Shadow';
if (entity.has(ColorStop)) return 'Stop';
+ if (entity.has(ClipPath)) return 'Clip Path';
+ if (entity.has(Mask)) return 'Mask';
if (entity.has(Paint)) {
return PAINT_NAMES[entity.get(Paint)!.value as PaintType] ?? 'Fill';
diff --git a/apps/web/src/dapi/handlers/check.ts b/apps/web/src/dapi/handlers/check.ts
index 8e4f6488..875666ef 100644
--- a/apps/web/src/dapi/handlers/check.ts
+++ b/apps/web/src/dapi/handlers/check.ts
@@ -4,8 +4,9 @@
import {
AdjustmentLayer, Audio, Cache, Caption, Computed, FrameRate, Geometry,
- Group, Hidden, IsClipPath, Opacity, PaintType, Scene, Sequential, Source,
- SourceError, Workarea, framesToSeconds, getIntrinsicPaint, isText,
+ Group, Hidden, Opacity, PaintType, Scene, Sequential, Source,
+ SourceError, Workarea, framesToSeconds, getIntrinsicPaint, getParentEntity,
+ isClipPath, isMaskContainer, isText,
} from "@diffusionstudio/runtime";
import { resolveNode } from "../lib/nodes";
@@ -18,7 +19,8 @@ import type { ToolHandler } from "../handler";
type Interval = { start: number; end: number };
function kindOf(entity: Entity): string {
- if (entity.has(IsClipPath)) return "clip-path";
+ const parent = getParentEntity(entity);
+ if (parent && isMaskContainer(parent)) return isClipPath(parent) ? "clip-path" : "mask";
if (entity.has(Scene)) return "scene";
if (entity.has(Group)) return entity.has(Sequential) ? "sequence" : "group";
if (entity.has(AdjustmentLayer)) return "adjustment-layer";
@@ -34,15 +36,14 @@ function kindOf(entity: Entity): string {
}
// Whether the node itself puts pixels on screen. Containers don't (their
-// leaves do), adjustment layers and clip paths only shape what others draw, and a
-// scene's implicit background is exactly what a "black frame" looks like —
-// so none of those count as coverage.
+// leaves do), adjustment layers and the nodes of clip paths and masks only
+// shape what others draw, and a scene's implicit background is exactly what a
+// "black frame" looks like — so none of those count as coverage.
function drawsPixels(entity: Entity): boolean {
return entity.has(Geometry)
&& !entity.has(Scene)
&& !entity.has(Group)
&& !entity.has(AdjustmentLayer)
- && !entity.has(IsClipPath)
&& !entity.has(Audio);
}
@@ -128,8 +129,18 @@ function visit(entity: Entity, window: Interval | null, depth: number, state: Wa
const cache = entity.get(Cache);
for (const child of cache?.children ?? []) visit(child, visible, depth + 1, state);
- // Clip paths are nodes worth counting and checking, but they add no pixels.
- for (const clipPath of cache?.clipPaths ?? []) visit(clipPath, null, depth + 1, state);
+ // The nodes of clip paths and masks are worth counting and checking, but
+ // they add no pixels.
+ const containers = [
+ ...cache?.clipPaths ?? [],
+ ...cache?.masks ?? [],
+ ...(cache?.effects ?? []).flatMap((effect) => effect.get(Cache)?.masks ?? []),
+ ];
+ for (const container of containers) {
+ for (const child of container.get(Cache)?.children ?? []) {
+ visit(child, null, depth + 1, state);
+ }
+ }
}
/** The spans of `window` no coverage interval touches. */
@@ -148,62 +159,62 @@ function findGaps(window: Interval, coverage: Interval[]): Interval[] {
}
export const check: ToolHandler<"check"> = async ({ id }, ctx) => {
- const { world } = ctx.requireSession();
- const target = resolveNode(world, id);
- const fps = world.get(FrameRate)?.value ?? 30;
-
- const computed = target.get(Computed)!;
-
- // The span the node actually plays: its bounds, narrowed by a workarea
- // when one is set (workarea frames count from the node's start, the way
- // the encoder and playback read them).
- let window: Interval = { start: computed.start, end: computed.end };
- const workarea = target.get(Workarea);
- if (workarea) {
- const start = Math.min(computed.end, computed.start + Math.max(0, workarea.start));
- const end = Math.max(start, Math.min(computed.end, workarea.end ? computed.start + workarea.end : computed.end));
- window = { start, end };
- }
-
- const rel = (frames: number) => Math.round(framesToSeconds(frames - computed.start, fps) * 1000) / 1000;
- const state: WalkState = { nodes: 0, byKind: {}, depth: 0, issues: [], coverage: [], rel };
- visit(target, window, 0, state);
+ const { world } = ctx.requireSession();
+ const target = resolveNode(world, id);
+ const fps = world.get(FrameRate)?.value ?? 30;
+
+ const computed = target.get(Computed)!;
+
+ // The span the node actually plays: its bounds, narrowed by a workarea
+ // when one is set (workarea frames count from the node's start, the way
+ // the encoder and playback read them).
+ let window: Interval = { start: computed.start, end: computed.end };
+ const workarea = target.get(Workarea);
+ if (workarea) {
+ const start = Math.min(computed.end, computed.start + Math.max(0, workarea.start));
+ const end = Math.max(start, Math.min(computed.end, workarea.end ? computed.start + workarea.end : computed.end));
+ window = { start, end };
+ }
- const issues: CheckIssue[] = [];
- if (window.end > window.start) {
- if (state.coverage.length === 0) {
- // A group of only audio clips is a legitimate thing to check; an
- // empty visual subtree is not.
- const audioOnly = (state.byKind["audio"] ?? 0) > 0;
+ const rel = (frames: number) => Math.round(framesToSeconds(frames - computed.start, fps) * 1000) / 1000;
+ const state: WalkState = { nodes: 0, byKind: {}, depth: 0, issues: [], coverage: [], rel };
+ visit(target, window, 0, state);
+
+ const issues: CheckIssue[] = [];
+ if (window.end > window.start) {
+ if (state.coverage.length === 0) {
+ // A group of only audio clips is a legitimate thing to check; an
+ // empty visual subtree is not.
+ const audioOnly = (state.byKind["audio"] ?? 0) > 0;
+ issues.push({
+ code: "no-visuals",
+ severity: audioOnly ? "warning" : "error",
+ message: audioOnly
+ ? "No visual content in the subtree — fine for audio-only nodes, black frames otherwise"
+ : "No visual content anywhere in the subtree — every frame renders empty",
+ });
+ } else {
+ const gaps = findGaps(window, state.coverage);
+ if (gaps.length > 0) {
+ const total = gaps.reduce((sum, gap) => sum + (gap.end - gap.start), 0);
issues.push({
- code: "no-visuals",
- severity: audioOnly ? "warning" : "error",
- message: audioOnly
- ? "No visual content in the subtree — fine for audio-only nodes, black frames otherwise"
- : "No visual content anywhere in the subtree — every frame renders empty",
+ code: "black-frames",
+ severity: "error",
+ message: `No visuals scheduled in ${gaps.length} span${gaps.length === 1 ? "" : "s"} totaling ${rel(computed.start + total)}s — likely black frames`,
+ ranges: gaps.map((gap) => ({ start: rel(gap.start), end: rel(gap.end) })),
});
- } else {
- const gaps = findGaps(window, state.coverage);
- if (gaps.length > 0) {
- const total = gaps.reduce((sum, gap) => sum + (gap.end - gap.start), 0);
- issues.push({
- code: "black-frames",
- severity: "error",
- message: `No visuals scheduled in ${gaps.length} span${gaps.length === 1 ? "" : "s"} totaling ${rel(computed.start + total)}s — likely black frames`,
- ranges: gaps.map((gap) => ({ start: rel(gap.start), end: rel(gap.end) })),
- });
- }
}
}
- issues.push(...state.issues);
-
- return {
- stats: {
- nodes: state.nodes,
- byKind: state.byKind,
- depth: state.depth,
- duration: rel(computed.start + (window.end - window.start)),
- },
- issues,
- };
+ }
+ issues.push(...state.issues);
+
+ return {
+ stats: {
+ nodes: state.nodes,
+ byKind: state.byKind,
+ depth: state.depth,
+ duration: rel(computed.start + (window.end - window.start)),
+ },
+ issues,
+ };
};
diff --git a/apps/web/src/engine/clip-path.ts b/apps/web/src/engine/clip-path.tsx
similarity index 73%
rename from apps/web/src/engine/clip-path.ts
rename to apps/web/src/engine/clip-path.tsx
index a7f1e267..a9fdfd5b 100644
--- a/apps/web/src/engine/clip-path.ts
+++ b/apps/web/src/engine/clip-path.tsx
@@ -2,6 +2,7 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+import { ClipPath as ClipPathElement } from '@diffusionstudio/reconciler';
import {
Computed,
Flip,
@@ -14,9 +15,10 @@ import {
entityWorldMat,
getEntityTree,
getIntrinsicPaint,
+ getParentEntity,
getSelection,
invert2D,
- isClipPath,
+ isMaskContainer,
isShape,
multiply2D,
store,
@@ -55,15 +57,17 @@ export function clearClipPathTarget(): void {
}
/**
- * Whether `entity` can become a clip path of `target`: a plain shape (a clip
- * path is a `<rect>`, `<ellipse>`, `<polygon>` or `<path>`, so media, text and
- * containers are out), not one
- * already, and not the target or something the target sits inside — a node
- * cannot be moved into its own subtree.
+ * Whether `entity` can clip `target`: a plain shape (what a `<clipPath>`
+ * clips by is `<rect>`, `<ellipse>`, `<polygon>` or `<path>`, so media, text
+ * and containers are out), not cutting something already, and not the target
+ * or something the target sits inside — a node cannot be moved into its own
+ * subtree.
*/
export function canClipWith(world: World, target: Entity, entity: Entity): boolean {
if (entity === target || !entity.isAlive() || !entity.get(Source)?.value) return false;
- if (!isShape(entity) || isClipPath(entity) || getIntrinsicPaint(entity) !== undefined) return false;
+ if (!isShape(entity) || getIntrinsicPaint(entity) !== undefined) return false;
+ const parent = getParentEntity(entity);
+ if (parent && isMaskContainer(parent)) return false;
return !getEntityTree(world, entity).includes(target);
}
@@ -75,12 +79,14 @@ export function getClipPathPicks(world: World): Entity[] {
}
/**
- * Makes the picked shapes clip paths of the target, one undo step, and puts
- * the tool down with the target selected. Each shape keeps its place on the
- * canvas: its matrix is carried from the parent it had into the target's
- * space and written back as `x`, `y` and `rotation`, with whatever scale the
- * move adds (a target drawn at half size, say) folded into its `width` and
- * `height` rather than its own scale.
+ * Gives the target a new `<clipPath>` holding the picked shapes, one undo
+ * step, and puts the tool down with the target selected: the target then
+ * shows only inside their outlines together, and within any clip path it had
+ * before. Each shape keeps its place on the canvas: its matrix is carried
+ * from the parent it had into the target's space (the clip path's) and
+ * written back as `x`, `y` and `rotation`, with whatever scale the move adds
+ * (a target drawn at half size, say) folded into its `width` and `height`
+ * rather than its own scale.
*/
export function applyClipPaths(world: World): void {
const target = getClipPathTarget();
@@ -92,6 +98,13 @@ export function applyClipPaths(world: World): void {
const flip = store(world, Flip);
const targetInverse = invert2D(entityWorldMat(world, target));
+ const [clipPath] = editor.insertElement(target, () => <ClipPathElement />);
+ if (!clipPath) {
+ leaveClipPathTool(world, target);
+ return;
+ }
+
+ let moved = 0;
for (const shape of picks) {
const eid = shape.id();
const width = computed.width[eid] ?? 0;
@@ -99,14 +112,15 @@ export function applyClipPaths(world: World): void {
const pivot = entityPivot(world, shape);
// Where it is drawn now, pivot folded in (see `bakeContainerInto`),
- // taken into the target's space before the move changes its parent.
+ // taken into the target's space (which the clip path shares) before
+ // the move changes its parent.
const placed = decompose2D(multiply2D(
targetInverse,
multiply2D(entityWorldMat(world, shape), translate2D(pivot.x, pivot.y)),
));
- if (!editor.reparent(shape, target)) continue;
- editor.editProperty(shape, 'clipPath', true);
+ if (!editor.reparent(shape, clipPath)) continue;
+ moved++;
// The scale the shape carries of its own stays its own; the rest is the move's.
const ownX = (computed.scaleX[eid] ?? 1) * (flip.x[eid] ?? 1);
@@ -129,6 +143,9 @@ export function applyClipPaths(world: World): void {
if (writes.length) editTransform(world, editor, shape, writes);
}
+ // An empty clip path would clip nothing; it is not worth the file.
+ if (moved === 0) editor.remove(clipPath);
+
leaveClipPathTool(world, target);
}
diff --git a/apps/web/src/engine/group.tsx b/apps/web/src/engine/group.tsx
index 6f970415..20800931 100644
--- a/apps/web/src/engine/group.tsx
+++ b/apps/web/src/engine/group.tsx
@@ -10,7 +10,6 @@ import {
FrameRate,
Geometry,
Group,
- IsClipPath,
Position,
Scene,
Selected,
@@ -27,11 +26,12 @@ import {
getNextName,
getParentEntity,
getTimelineOrigin,
+ isClipShape,
multiply2D,
store,
translate2D,
} from '@diffusionstudio/runtime';
-import { Not, Or } from 'koota';
+import { Or } from 'koota';
import { getDocumentEditor } from './editor';
import { editTransform } from './input/interactions';
@@ -72,7 +72,7 @@ function isIdentity(mat: Mat2D): boolean {
*/
export function groupSelection(world: World): void {
const editor = getDocumentEditor(world);
- const selected = new Set(world.query(Selected, NODES, Not(IsClipPath)));
+ const selected = new Set([...world.query(Selected, NODES)].filter((entity) => !isClipShape(entity)));
const first = [...selected][0];
if (!first) return;
@@ -102,7 +102,7 @@ export function groupSelection(world: World): void {
*/
export function wrapSelectionInSequence(world: World): void {
const editor = getDocumentEditor(world);
- const selected = [...world.query(Selected, NODES, Not(IsClipPath))];
+ const selected = [...world.query(Selected, NODES)].filter((entity) => !isClipShape(entity));
if (!selected.length) return;
const sequence = editor.wrap(selected, () => <SequenceElement name={getNextName(world, 'Sequence')} />);
@@ -115,7 +115,7 @@ export function wrapSelectionInSequence(world: World): void {
/** The children of `entity` that are nodes of the container, in file order. */
function nodeChildren(world: World, entity: Entity): Entity[] {
return getEntityChildren(world, entity).filter(
- (child) => (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) && !child.has(IsClipPath),
+ (child) => child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer),
);
}
@@ -175,7 +175,7 @@ function measure(world: World, entities: Entity[]): { minX: number; minY: number
*/
export function wrapSelectionInScene(world: World): void {
const editor = getDocumentEditor(world);
- const selected = new Set(world.query(Selected, NODES, Not(IsClipPath)));
+ const selected = new Set([...world.query(Selected, NODES)].filter((entity) => !isClipShape(entity)));
const first = [...selected][0];
if (!first) return;
diff --git a/apps/web/src/engine/timeline/style.ts b/apps/web/src/engine/timeline/style.ts
index 7addb173..09585df0 100644
--- a/apps/web/src/engine/timeline/style.ts
+++ b/apps/web/src/engine/timeline/style.ts
@@ -10,7 +10,7 @@ import {
isAdjustmentLayer,
isCaption,
isGroup,
- isClipPath,
+ isClipShape,
isEllipse,
isPath,
isPolygon,
@@ -37,7 +37,7 @@ export function getClipStyle(entity: Entity, asset: Asset | null, errored = fals
if (isText(entity)) return COLORS.clip.text;
if (isScene(entity)) return COLORS.clip.scene;
if (isGroup(entity)) return COLORS.clip.group;
- if (isClipPath(entity)) return COLORS.clip.clipPath;
+ if (isClipShape(entity)) return COLORS.clip.clipPath;
if (isAdjustmentLayer(entity)) return COLORS.clip.adjustment;
if (hasHtmlPaint(entity) || hasSurfacePaint(entity)) return COLORS.clip.html;
@@ -72,7 +72,7 @@ export function getClipFallbackName(world: World, entity: Entity): string {
if (isScene(entity)) return 'Scene';
if (isSequence(entity)) return 'Sequence';
if (isGroup(entity)) return 'Group';
- if (isClipPath(entity)) return 'Clip Path';
+ if (isClipShape(entity)) return 'Clip Path';
if (isAdjustmentLayer(entity)) return 'Adjustment';
if (hasHtmlPaint(entity)) return 'HTML';
if (hasSurfacePaint(entity)) return 'Surface';
diff --git a/docs/reference/jsx/README.md b/docs/reference/jsx/README.md
index b4dbd09f..2fd86f3a 100644
--- a/docs/reference/jsx/README.md
+++ b/docs/reference/jsx/README.md
@@ -37,6 +37,7 @@ export default function Project() {
| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, the `fonts` tool |
| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>`, `<imagePaint>` / `<videoPaint>` |
| [styles.md](./styles.md) | `<stroke>`, `<shadow>`, `<effect>`: outlines, drop shadows and filters |
+| [masks.md](./masks.md) | `<clipPath>`, `<mask>`: cutting an element by outlines or by a picture |
| [html.md](./html.md) | `<html>`: reactive HTML children drawn into the box |
| [surface-paint.md](./surface-paint.md) | `<surface>`: a ref-provided canvas you draw into, sampled every frame |
| [shader-paint.md](./shader-paint.md) | `<shaderPaint>`: a WGSL fragment shader over the media paint below it |
diff --git a/docs/reference/jsx/elements.md b/docs/reference/jsx/elements.md
index 665a5ce0..aea960bd 100644
--- a/docs/reference/jsx/elements.md
+++ b/docs/reference/jsx/elements.md
@@ -15,7 +15,7 @@ camelCase composition elements map 1:1 onto entities. Lowercase DOM vocabulary i
| Element | What it is |
| ------- | ---------- |
-| [`<rect>`](./rect.md) | A rectangle. Takes paints, strokes, shadows and effects. With `clipPath` it clips its parent instead of drawing. |
+| [`<rect>`](./rect.md) | A rectangle. Takes paints, strokes, shadows, effects, clip paths and masks. |
| [`<ellipse>`](./ellipse.md) | An ellipse inscribed in its box. Takes what a rect takes. |
| [`<polygon>`](./polygon.md) | A regular polygon (`pointCount` corners, a triangle by default) stretched to fill its box. Takes what a rect takes. |
| [`<path>`](./path.md) | A vector outline from SVG path data (`d`), in its box's pixels or stretched from a `viewBox`; morphs between keyframes and trims. Takes what a rect takes. |
@@ -45,14 +45,15 @@ Children of a node, stacked in document order over its intrinsic fill. See [pain
## Styles and motion
-Sub-entity children of the node (or paint) that holds them. See [styles.md](./styles.md), [animations.md](./animations.md), [keyframes.md](./keyframes.md).
+Sub-entity children of the node (or paint) that holds them. See [styles.md](./styles.md), [masks.md](./masks.md), [animations.md](./animations.md), [keyframes.md](./keyframes.md).
| Element | What it is |
| ------- | ---------- |
| `<stroke>` | An outline of the parent's box or glyphs, in its `color` or its solid and gradient paint children. Several stack. |
| `<shadow>` | A drop shadow beneath the parent's silhouette. Several stack. |
| `<effect>` | A CSS-style filter over the parent's rendered pixels. Several stack. |
-| `<mask>` | A matte limiting the `<effect>` holding it: the alpha of a tracked frame sequence. Under an `opacity` effect, the cut-out. See [styles.md](./styles.md#mask). |
+| `<clipPath>` | Clips the node holding it to the outlines of the shapes under it. See [masks.md](./masks.md). |
+| `<mask>` | A matte: keeps only what its picture covers — the elements under it, or a mask file — on the node holding it, or limits the `<effect>` holding it. See [masks.md](./masks.md). |
| `<animation>` | One preset in/out animation of the node holding it. |
| `<keyframeTrack>` | The keyframes of one prop of the element holding it. |
| `<keyframe>` | One keyframe of the track holding it. |
@@ -70,7 +71,6 @@ User-defined components are ordinary Solid components; they compose the elements
| `<scene>` | required — the frame's own size |
| `<rect>`, `<ellipse>`, `<polygon>`, `<path>`, `<html>`, `<surface>` | 100 × 100 |
| `<audio>` | 500 × 150 (the waveform box on the canvas) |
-| `<rect clipPath>` | 500 × 500 |
| `<text>` | fits its glyphs |
| `<captions>` | the preset's — it lays out the caption block against the scene's frame |
| `<group>`, `<sequence>` | fits its children |
diff --git a/docs/reference/jsx/ellipse.md b/docs/reference/jsx/ellipse.md
index dbb16c5a..1659b83e 100644
--- a/docs/reference/jsx/ellipse.md
+++ b/docs/reference/jsx/ellipse.md
@@ -13,6 +13,5 @@ All [common props](./elements.md#common-props), plus:
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
| `fill` | `string` | none | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child, drawn beneath any paint children. |
-| `clipPath` | `boolean` | `false` | Makes the ellipse a clip path of its parent instead of a drawn shape: the parent shows only inside the curve. Works like [`<rect clipPath>`](./rect.md#clip-paths). |
Without `width`/`height` an ellipse is 100×100. Fills, strokes, shadows and [masked effects](./styles.md) follow the curve, and the canvas only picks it up inside the curve rather than anywhere in its box.
diff --git a/docs/reference/jsx/masks.md b/docs/reference/jsx/masks.md
new file mode 100644
index 00000000..43906176
--- /dev/null
+++ b/docs/reference/jsx/masks.md
@@ -0,0 +1,87 @@
+# `<clipPath>` and `<mask>`
+
+Two ways to cut an element, both as SVG has them: a **clip path** shows the element only inside a set of outlines, hard-edged; a **mask** keeps only what a picture covers, by its alpha, so it can be soft, fade, or be text. Either one is a child of the element it cuts — any node: `<rect>`, `<text>`, `<video>`, `<image>`, `<group>`, `<scene>` — and holds the elements that cut it.
+
+```tsx
+<group>
+ <clipPath>
+ <ellipse x={560} y={140} width={800} height={800} />
+ </clipPath>
+ <mask>
+ <text fontSize={180} color="#FFFFFF">HELLO</text>
+ </mask>
+ <video src="footage/beach.mp4" width={1920} height={1080} />
+</group>
+```
+
+The elements under a clip path or mask sit in the **space and time of the element they cut**, as its children do: the same coordinates, its transform applied on top of their own, and its timeline. Each keeps its own transform, timing and keyframes, so a cut that moves, grows or comes in late is keyframes or timing on those elements. They are never drawn on their own and never picked up on the canvas.
+
+Both cut after the element's own [effects](./styles.md#effect): a blur on a clipped element stops at the clip's edge. To blur the edge of the cut instead, put the clip path or mask on an inner `<group>` and the effect on an outer one.
+
+Several clip paths and masks on one element **intersect**: it shows only where every one of them lets it.
+
+## `<clipPath>`
+
+Clips the element holding it to the outlines of the shapes under it: `<rect>`, `<ellipse>`, `<polygon>` and `<path>`. Their outlines **add up** — the element shows inside any of them — united by the nonzero rule, so two outlines drawn opposite ways round cut a hole where they overlap; a lone `<path>` keeps its own `fillRule`.
+
+```tsx
+<text fontSize={120} color="#FFFFFF" textAlign="center" textBaseline="middle">
+ Hello World
+ <clipPath>
+ <rect height={300}>
+ <keyframeTrack property="width">
+ <keyframe time={0} value={0} />
+ <keyframe time={1} value={1920} easing="easeOut" />
+ </keyframeTrack>
+ </rect>
+ </clipPath>
+</text>
+```
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `hidden` | `boolean` | absent | Switches the clip path off without removing it. |
+
+- Only the outline of a shape counts, so its `fill`, `opacity`, `blendMode` and paint / stroke / shadow / effect children have no effect. Text, media and groups under a clip path are ignored: a cut shaped like text is a `<mask>`.
+- A shape outside its own time window drops out of the clip path, and a clip path none of whose shapes is in its time clips nothing: a shape keyframed across a text is a wipe, one that ends early lets go, one that starts late is a reveal.
+
+## `<mask>`
+
+Keeps only what its **picture** covers, by the picture's alpha: opaque keeps, transparent cuts. The picture is the elements under it — shapes, text, media, groups, drawn the way they would be on the canvas and taken together — or a mask file named by `src`.
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `inverted` | `boolean` | `false` | Covers what the picture does not instead. |
+| `blur` | `number` | `0` | Feather: radius in px the edge falls off over. |
+| `opacity` | `number` | `1` | How strongly the mask cuts, `0`–`1`. `1` leaves nothing outside it; lower lets that much through outside; `0` is no mask. |
+| `src` | `string` | none | A mask file: the frames of an object tracked through footage, see below. |
+| `sourceIn` | `Time` | `0` | The holder's source time the first frame of `src` belongs to, so the mask stays on the footage it was made from whatever the trim. |
+| `frameRate` | `number` | `30` | Frames per second the frames of `src` were written at (the composition's). |
+| `smoothing` | `number` | `0.25` | How much a mask file's edge is smoothed, `0`–`1`. At `0` it is exactly where the model put it; the more, the rounder, and the more of what is thin or small melts away. Sharp at any size either way. |
+| `hidden` | `boolean` | absent | Switches the mask off without removing it. |
+
+`blur` and `opacity` take a [`<keyframeTrack>`](./keyframes.md). A mask with neither elements in their time nor a `src` does nothing.
+
+```tsx
+<image src="stills/sky.jpg" width={1920} height={1080}>
+ <mask blur={40}>
+ <ellipse x={460} y={40} width={1000} height={1000} fill="#FFFFFF" />
+ </mask>
+</image>
+```
+
+### Mask files
+
+A mask file is what the editor's object mask tool makes — pick an object in a video clip, track it, and the frames it found are written to the library — and what [`generate`](../tools/generate.md)'s [`sam-2.1`](../tools/segment.md) makes from a tool call. `src` names it, and its picture is fitted into the holder's box the way the holder fits its footage, so it stays on the object.
+
+```tsx
+<video src="footage/skater.mp4" width={1920} height={1080}>
+ <effect type="opacity" value={1}>
+ <mask src="masks/skater" sourceIn={2} frameRate={30} blur={6} />
+ </effect>
+</video>
+```
+
+### Under an `<effect>`
+
+A mask under an [`<effect>`](./styles.md#effect) limits where the effect applies instead of cutting the element, held to the element's box. Under an `"opacity"` effect that is the cut-out: the clip shows inside the mask and goes transparent outside, as a mask on Premiere's Opacity does. Under any other effect the effect shows through inside the mask and the picture is untouched outside: an inverted mask on a `"blur"` blurs the background behind a person. It takes the same props and the same picture, elements or a file.
diff --git a/docs/reference/jsx/path.md b/docs/reference/jsx/path.md
index 6027dc25..2176fb56 100644
--- a/docs/reference/jsx/path.md
+++ b/docs/reference/jsx/path.md
@@ -21,9 +21,8 @@ All [common props](./elements.md#common-props), plus:
| `trimStart`, `trimEnd` | `number` | `0`, `1` | Draw only the part of each subpath between these two fractions of its length (After Effects' Trim Paths). The part that is left is also what is filled and picked up on the canvas. |
| `trimOffset` | `number` | `0` | Slides the trimmed part along the path, as a fraction of its length. It wraps, so `1` is once round: across the start of a closed subpath, into a second piece on an open one. |
| `fill` | `string` | none | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child, drawn beneath any paint children. |
-| `clipPath` | `boolean` | `false` | Makes the path a clip path of its parent instead of a drawn shape: the parent shows only inside its outline. Works like [`<rect clipPath>`](./rect.md#clip-paths); a keyframed `d` on one is an animated mask. |
-A `d` that does not parse draws what came before the error, as SVG does, and the error is logged. Without `width`/`height` a path's box is 100×100. A fill closes open subpaths with a straight line; a [`<stroke>`](./styles.md#stroke) does not, and ends them with its `cap`.
+A `d` that does not parse draws what came before the error, as SVG does, and the error is logged. Under a [`<clipPath>`](./masks.md#clippath) a path clips by its outline, and a keyframed `d` there is an animated clip. Without `width`/`height` a path's box is 100×100. A fill closes open subpaths with a straight line; a [`<stroke>`](./styles.md#stroke) does not, and ends them with its `cap`.
## Coordinates and the box
diff --git a/docs/reference/jsx/polygon.md b/docs/reference/jsx/polygon.md
index 2988625b..23e8f0be 100644
--- a/docs/reference/jsx/polygon.md
+++ b/docs/reference/jsx/polygon.md
@@ -16,6 +16,5 @@ All [common props](./elements.md#common-props), plus:
| ---- | ---- | ------- | ------- |
| `pointCount` | `number` | `3` | How many corners. Rounded to a whole number; anything under 3 is 3. Not animatable. |
| `fill` | `string` | none | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child, drawn beneath any paint children. |
-| `clipPath` | `boolean` | `false` | Makes the polygon a clip path of its parent instead of a drawn shape: the parent shows only inside its outline. Works like [`<rect clipPath>`](./rect.md#clip-paths). |
Without `width`/`height` a polygon is 100×100. The corners sit on an ellipse and are then stretched so the outline touches every side of the box, so a triangle fills its box's full height rather than leaving a gap below its base. The canvas only picks it up inside the outline.
diff --git a/docs/reference/jsx/rect.md b/docs/reference/jsx/rect.md
index 63ee3bab..08fe8786 100644
--- a/docs/reference/jsx/rect.md
+++ b/docs/reference/jsx/rect.md
@@ -1,6 +1,6 @@
# `<rect>`
-A rectangle. Takes [paint children](./paints.md), plus [`<stroke>`, `<shadow>`, `<effect>`](./styles.md), [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md); use `cornerRadius` for rounded corners.
+A rectangle. Takes [paint children](./paints.md), plus [`<stroke>`, `<shadow>`, `<effect>`](./styles.md), [`<clipPath>`, `<mask>`](./masks.md), [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md); use `cornerRadius` for rounded corners.
```tsx
<rect x={40} y={40} width={640} height={360} cornerRadius={24} fill="#FF0055" />
@@ -13,30 +13,9 @@ All [common props](./elements.md#common-props), plus:
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
| `fill` | `string` | none | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child, drawn beneath any paint children. |
-| `clipPath` | `boolean` | `false` | Makes the rect a clip path of its parent instead of a drawn shape — see below. `mask` is the old spelling and still works. |
-A rect with neither `fill` nor a paint child draws nothing; it is still a box: its clip paths cut it, it carries children, and it takes up its place in the timeline. Without `width`/`height` a rect is 100×100.
+A rect with neither `fill` nor a paint child draws nothing; it is still a box: it carries children, its clip paths and masks still cut them, and it takes up its place in the timeline. Without `width`/`height` a rect is 100×100.
-## Clip paths
+## Clip paths and masks
-A `<rect clipPath>` clips the element holding it instead of drawing: the parent's fills, strokes, shadows and children show only inside the rect's box. [`<ellipse clipPath>`](./ellipse.md), [`<polygon clipPath>`](./polygon.md) and [`<path clipPath>`](./path.md) work the same way and clip to their curve or outline; everything below applies to them too. It is still a rect — same coordinates, `cornerRadius`, transform and timing — so it can be moved, rotated, keyframed and animated independently of what it clips: a clip path whose `width` is keyframed across a text is a wipe, one that starts later than its parent is a reveal.
-
-```tsx
-<text fontSize={120} color="#FFFFFF" textAlign="center" textBaseline="middle">
- Hello World
- <rect clipPath>
- <keyframeTrack property="width">
- <keyframe time={0} value={0} />
- <keyframe time={1} value={1920} easing="easeOut" />
- </keyframeTrack>
- </rect>
-</text>
-```
-
-- Any node can hold clip paths (`<rect>`, `<text>`, `<video>`, `<image>`, `<group>`, `<scene>`); the clip path clips that element as a whole.
-- Several clip paths under one element **intersect**: content shows only where every clip path covers it.
-- Outside the clip path's own time window it does not clip and the parent shows in full. Without `end` (or `sourceOut`) a clip path clips for the parent's whole window, not the usual 16 s default.
-- Never rendered and never hit on the canvas, so `fill`, `opacity`, `blendMode` and paint / stroke / shadow / effect children have no effect on it.
-- Without `width`/`height` a clip path is 500×500 (a plain rect is 100×100).
-- `hidden` on a clip path does not switch it off (it is skipped by role before hiding is looked at); use timing, or set `clipPath={false}`.
-- `<rect mask>` is the old spelling of `<rect clipPath>` and still reads the same; when both are set, `clipPath` wins.
+A rect can be cut by a [`<clipPath>` or `<mask>`](./masks.md) child, and a rect under one is what that clip path or mask cuts by.
diff --git a/docs/reference/jsx/styles.md b/docs/reference/jsx/styles.md
index 1db086d3..ffdb56e2 100644
--- a/docs/reference/jsx/styles.md
+++ b/docs/reference/jsx/styles.md
@@ -70,7 +70,7 @@ A drop shadow beneath the parent's silhouette: a blurred, offset copy of it in `
## `<effect>`
-A filter over the parent's **rendered pixels** — its fills, strokes and children together. On a [`<group>`](./group.md) that is the group as a whole; on a [`<video>`](./video.md) it is the frame after the media is drawn. A [`<mask>`](#mask) child limits where the effect applies.
+A filter over the parent's **rendered pixels** — its fills, strokes and children together. On a [`<group>`](./group.md) that is the group as a whole; on a [`<video>`](./video.md) it is the frame after the media is drawn. A [`<mask>`](./masks.md#under-an-effect) child limits where the effect applies.
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
@@ -99,30 +99,7 @@ A filter over the parent's **rendered pixels** — its fills, strokes and childr
## `<mask>`
-A matte limiting the `<effect>` holding it: a **picture** whose alpha says where the effect applies, fitted into the node's box the way the node fits its footage. It is what the editor's object mask tool makes — pick an object in a video clip, track it, and the frames it found are written to the library and named by `src` — and what [`generate`](../tools/generate.md)'s [`sam-2.1`](../tools/segment.md) makes from a tool call. Several under one effect intersect. Without a `src` a `<mask>` does nothing.
-
-Under an `"opacity"` effect the mask is the cut-out: the clip shows inside the mask and goes transparent outside, as a mask on Premiere's Opacity does. Under any other effect the effect shows through inside the mask and the picture is untouched outside: an inverted mask on a `"blur"` blurs the background behind a person.
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| `src` | `string` | none | The frames, a directory of numbered images whose alpha is the mask. |
-| `sourceIn` | `Time` | `0` | The node's source time the first frame belongs to, so the mask stays on the footage it was made from whatever the trim. |
-| `frameRate` | `number` | `30` | Frames per second the frames were written at (the composition's). |
-| `blur` | `number` | `0` | Feather: radius in px the edge falls off over. |
-| `opacity` | `number` | `1` | How strongly the mask limits the effect. `1` stops the effect at the edge; lower lets that much of it through outside; `0` is no mask. |
-| `inverted` | `boolean` | `false` | Covers what the picture does not instead. |
-| `smoothing` | `number` | `0.25` | How much a mask file's edge is smoothed, `0`–`1`. At `0` it is exactly where the model put it; the more, the rounder, and the more of what is thin or small melts away. Sharp at any size either way. |
-| `hidden` | `boolean` | absent | Switches the mask off without removing it. |
-
-`blur` and `opacity` take a [`<keyframeTrack>`](./keyframes.md).
-
-```tsx
-<video src="footage/skater.mp4" width={1920} height={1080}>
- <effect type="opacity" value={1}>
- <mask src="masks/skater" sourceIn={2} frameRate={30} blur={6} />
- </effect>
-</video>
-```
+A `<mask>` under an effect limits where the effect applies; under an `"opacity"` effect it is the cut-out. See [masks.md](./masks.md#under-an-effect).
## Animating them
diff --git a/docs/reference/models.md b/docs/reference/models.md
index 12dcd507..73e4ed27 100644
--- a/docs/reference/models.md
+++ b/docs/reference/models.md
@@ -105,4 +105,4 @@ These run in the app, on this machine's GPU: no account, no credits. A job is sh
| Model | | Makes | Fields |
| --- | --- | --- | --- |
-| `sam-2.1` | SAM 2.1 — segments an object in a video and tracks it through the footage; `size` tiny (default), small, base-plus or large | a mask file (`.mask`) for a [`<mask src>`](./jsx/styles.md#mask) | [segment.md](./tools/segment.md) |
+| `sam-2.1` | SAM 2.1 — segments an object in a video and tracks it through the footage; `size` tiny (default), small, base-plus or large | a mask file (`.mask`) for a [`<mask src>`](./jsx/masks.md#mask-files) | [segment.md](./tools/segment.md) |
diff --git a/docs/reference/tools/check.md b/docs/reference/tools/check.md
index 03513c17..72249ab8 100644
--- a/docs/reference/tools/check.md
+++ b/docs/reference/tools/check.md
@@ -19,7 +19,7 @@ The analysis is structural, from the resolved timeline alone, so it is instant a
## What counts as visual coverage
-Video, image, HTML, shape, text, and caption nodes draw pixels; their scheduled spans cover the timeline. Groups and scenes are covered only where their descendants draw — a scene's background alone is exactly what a black frame looks like, so it never counts. Audio nodes, clip paths, and adjustment layers add no pixels; neither does anything hidden, fully transparent, or scheduled outside the window its ancestors play. When a scene has a workarea, coverage is judged against the workarea instead of the full span.
+Video, image, HTML, shape, text, and caption nodes draw pixels; their scheduled spans cover the timeline. Groups and scenes are covered only where their descendants draw — a scene's background alone is exactly what a black frame looks like, so it never counts. Audio nodes, the shapes of clip paths and the elements of masks, and adjustment layers add no pixels; neither does anything hidden, fully transparent, or scheduled outside the window its ancestors play. When a scene has a workarea, coverage is judged against the workarea instead of the full span.
## Output
@@ -29,7 +29,7 @@ One JSON object:
{
stats: {
nodes: number; // nodes in the subtree, the checked node included
- byKind: Record<string, number>; // "scene" | "sequence" | "group" | "video" | "image" | "html" | "shape" | "text" | "caption" | "audio" | "clip-path" | "adjustment-layer"
+ byKind: Record<string, number>; // "scene" | "sequence" | "group" | "video" | "image" | "html" | "shape" | "text" | "caption" | "audio" | "clip-path" | "mask" | "adjustment-layer"
depth: number; // deepest nesting level below the checked node (0 = no children)
duration: number; // seconds the checked node plays (its workarea, when one is set)
};
diff --git a/docs/reference/tools/segment.md b/docs/reference/tools/segment.md
index 3af32834..90c98136 100644
--- a/docs/reference/tools/segment.md
+++ b/docs/reference/tools/segment.md
@@ -1,6 +1,6 @@
# sam-2.1
-SAM 2.1 segments an object in a video and tracks it through the footage, making the mask file (`.mask`) a [`<mask src>`](../jsx/styles.md#mask) names — the file the editor's object mask tool makes. It runs in the app, on this machine's GPU: no account, no credits. Like every [local model](../models.md#local), its job is polled with [`job`](./job.md) and lasts only as long as the app.
+SAM 2.1 segments an object in a video and tracks it through the footage, making the mask file (`.mask`) a [`<mask src>`](../jsx/masks.md#mask-files) names — the file the editor's object mask tool makes. It runs in the app, on this machine's GPU: no account, no credits. Like every [local model](../models.md#local), its job is polled with [`job`](./job.md) and lasts only as long as the app.
| | |
| --- | --- |
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index f2428b2a..8e6f3404 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -38,6 +38,7 @@ export type {
CameraMatrix,
CaptionPreset,
CaptionsProps,
+ ClipPathProps,
ColorStopProps,
Easing,
EffectProps,
diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.ts
index 03eb88cc..064b29fd 100644
--- a/packages/jsx/src/jsx-runtime.ts
+++ b/packages/jsx/src/jsx-runtime.ts
@@ -25,6 +25,7 @@ import type {
AudioProps,
CaptionsProps,
ColorStopProps,
+ ClipPathProps,
EffectProps,
MaskProps,
LinearGradientPaintProps,
@@ -69,7 +70,7 @@ type HtmlElementTags = Omit<SolidJSX.HTMLElementTags, "canvas" | "audio" | "vide
type ImgTag = Omit<SolidJSX.HTMLElementTags["img"], "src"> & { src?: string };
// The shared names are re-declared below as unions with the composition props.
-type SvgElementTags = Omit<SolidJSX.SVGElementTags, "rect" | "ellipse" | "polygon" | "path" | "text" | "image">;
+type SvgElementTags = Omit<SolidJSX.SVGElementTags, "rect" | "ellipse" | "polygon" | "path" | "text" | "image" | "mask" | "clipPath">;
export declare namespace JSX {
// Solid's Element type keeps Solid's control flow (<For>, <Show>, …) and
@@ -107,7 +108,8 @@ export declare namespace JSX {
stroke: StrokeProps & SourceProps;
shadow: ShadowProps & SourceProps;
effect: EffectProps & SourceProps;
- mask: MaskProps & SourceProps;
+ clipPath: (ClipPathProps & SourceProps) | SolidJSX.SVGElementTags["clipPath"];
+ mask: (MaskProps & SourceProps) | SolidJSX.SVGElementTags["mask"];
animation: AnimationProps & SourceProps;
keyframeTrack: KeyframeTrackProps & SourceProps;
keyframe: KeyframeProps & SourceProps;
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
index 7b1be951..4b307653 100644
--- a/packages/jsx/src/source.ts
+++ b/packages/jsx/src/source.ts
@@ -114,6 +114,7 @@ export const COMPOSITION_TAGS = [
"stroke",
"shadow",
"effect",
+ "clipPath",
"mask",
"animation",
"keyframeTrack",
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 7ea82d19..0cfa582f 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -548,7 +548,7 @@ export type SceneProps = IdentityProps & PositionProps & Required<Pick<SizeProps
};
export type GroupProps = CommonProps & FillProps & {
- /** Element children, plus `<Effect>` (filtering the group as a whole), `<Animation>` and `<KeyframeTrack>` children. */
+ /** Element children, plus `<Effect>` (filtering the group as a whole), `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
@@ -578,38 +578,20 @@ export type AdjustmentLayerProps =
};
export type RectProps = CommonProps & FillProps & {
- /**
- * Makes the rect a clip path of its parent: it clips the parent (its fills,
- * strokes and children show only inside the rect's box) instead of drawing.
- * The rect keeps its transform, `cornerRadius` and timing — a keyframed
- * clip path sliding across a text is a wipe, one that ends early lets go —
- * and several clip paths under one parent intersect. A clip path is never
- * rendered or hit, so its `fill`, `opacity`, `blendMode` and paint children
- * have no effect. Without `width`/`height` a clip path is 500×500, and
- * without `end` it clips for the parent's whole window.
- */
- clipPath?: boolean;
- /** @deprecated The old spelling of `clipPath`, read when `clipPath` is not set. */
- mask?: boolean;
/**
* Paint children (`<SolidPaint>`, `<LinearGradientPaint>`,
* `<RadialGradientPaint>`, `<AngularGradientPaint>`), plus `<Stroke>`, `<Shadow>`, `<Effect>`,
- * `<Animation>` and `<KeyframeTrack>` children.
+ * `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children.
*/
children?: SolidJSX.Element;
};
/** `<ellipse>` — an ellipse inscribed in its box. Takes the same children as `<rect>`. */
export type EllipseProps = CommonProps & FillProps & {
- /**
- * Makes the ellipse a clip path of its parent, as `<rect clipPath>` does:
- * the parent shows only inside the curve. Never rendered or hit.
- */
- clipPath?: boolean;
/**
* Paint children (`<SolidPaint>`, `<LinearGradientPaint>`,
* `<RadialGradientPaint>`, `<AngularGradientPaint>`), plus `<Stroke>`, `<Shadow>`, `<Effect>`,
- * `<Animation>` and `<KeyframeTrack>` children.
+ * `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children.
*/
children?: SolidJSX.Element;
};
@@ -621,15 +603,10 @@ export type EllipseProps = CommonProps & FillProps & {
export type PolygonProps = CommonProps & FillProps & {
/** How many corners, a whole number of at least 3. Default 3. */
pointCount?: number;
- /**
- * Makes the polygon a clip path of its parent, as `<rect clipPath>` does:
- * the parent shows only inside its outline. Never rendered or hit.
- */
- clipPath?: boolean;
/**
* Paint children (`<SolidPaint>`, `<LinearGradientPaint>`,
* `<RadialGradientPaint>`, `<AngularGradientPaint>`), plus `<Stroke>`, `<Shadow>`, `<Effect>`,
- * `<Animation>` and `<KeyframeTrack>` children.
+ * `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children.
*/
children?: SolidJSX.Element;
};
@@ -673,15 +650,10 @@ export type PathProps = CommonProps & FillProps & {
* it wraps, so 1 is once round. Default 0.
*/
trimOffset?: number;
- /**
- * Makes the path a clip path of its parent, as `<rect clipPath>` does: the
- * parent shows only inside its outline. Never rendered or hit.
- */
- clipPath?: boolean;
/**
* Paint children (`<SolidPaint>`, `<LinearGradientPaint>`,
* `<RadialGradientPaint>`, `<AngularGradientPaint>`), plus `<Stroke>`, `<Shadow>`, `<Effect>`,
- * `<Animation>` and `<KeyframeTrack>` children.
+ * `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children.
*/
children?: SolidJSX.Element;
};
@@ -755,27 +727,55 @@ export type EffectProps = Pick<CompositeProps, "hidden"> & {
};
/**
- * `<mask>` — a matte limiting the `<effect>` holding it: a picture whose
- * alpha says where the effect applies, fitted into the node's box the way
- * the node fits its footage. Under an `"opacity"` effect it is the cut-out:
- * what is outside the mask goes transparent. What the editor's object mask
- * tool makes: it tracks an object through a video and writes the frames it
- * found as a directory of numbered images, which `src` names. Several under
- * one effect intersect. Without a `src` a mask does nothing.
+ * `<clipPath>` — clips the element holding it: its fills, strokes, effects
+ * and children show only inside the outlines of the shapes under the clip
+ * path, applied after its effects. The shapes (`<rect>`, `<ellipse>`,
+ * `<polygon>`, `<path>`) are placed, keyframed and timed in the holder's
+ * box and timeline like its children, and are never rendered or hit, so
+ * their paints, `opacity` and `blendMode` have no effect. Several shapes in
+ * one clip path add up, united by the nonzero rule (a lone `<path>` keeps its
+ * `fillRule`); several clip paths on one element intersect. A shape out of
+ * its time drops out, and a clip path with none in its time clips nothing:
+ * a keyframed shape sliding across a text is a wipe, one that ends early
+ * lets go. Text and other elements under a clip path are ignored; a soft or
+ * textual cut is a `<mask>`.
*/
-export type MaskProps = Pick<CompositeProps, "hidden"> & TrackChildren & {
+export type ClipPathProps = Pick<CompositeProps, "hidden"> & {
+ /** The shape children whose outlines the holder shows inside. */
+ children?: SolidJSX.Element;
+};
+
+/**
+ * `<mask>` — a matte on the element holding it, or on the `<effect>` holding
+ * it. On an element it keeps only what its picture covers (by the picture's
+ * alpha), applied after the element's effects (SVG's `mask`; After Effects' track matte). On an effect
+ * it limits where the effect applies, held to the element's box; under an
+ * `"opacity"` effect that is the cut-out: what is outside the mask goes
+ * transparent.
+ *
+ * The picture is the elements under the mask, or a mask file named by `src`.
+ * Elements (shapes, text, media, groups) are placed, keyframed and timed in
+ * the holder's box and timeline like its children, and are drawn only into
+ * the picture, never on their own; together they make one picture. A mask
+ * file is what the editor's object mask tool makes: it tracks an object
+ * through a video and writes the frames it found as a directory of numbered
+ * images, fitted into the holder's box the way it fits its footage.
+ *
+ * Several masks on one holder intersect. A mask with neither elements in
+ * their time nor a `src` does nothing.
+ */
+export type MaskProps = Pick<CompositeProps, "hidden"> & {
/** The mask's frames: a directory of numbered images whose alpha is the mask. */
src?: string;
- /** The parent's source time the first frame belongs to, so the frames stay on the footage they were made from whatever the trim. Default 0. */
+ /** The parent's source time the first frame of `src` belongs to, so the frames stay on the footage they were made from whatever the trim. Default 0. */
sourceIn?: Time;
- /** Frames per second the frames were written at (the composition's). Default 30. */
+ /** Frames per second the frames of `src` were written at (the composition's). Default 30. */
frameRate?: number;
/** Feather: radius in px the edge falls off over. Default 0. */
blur?: number;
/**
- * How strongly the mask limits the effect, 0–1. At 1 the effect stops at
- * the mask's edge; lower lets that much of it through outside; 0 is no
- * mask. Default 1.
+ * How strongly the mask cuts, 0–1. At 1 nothing outside it is left;
+ * lower lets that much through outside; 0 is no mask. Default 1.
*/
opacity?: number;
/** Covers what the picture does not instead. Default false. */
@@ -787,6 +787,8 @@ export type MaskProps = Pick<CompositeProps, "hidden"> & TrackChildren & {
* either way. Default 0.25.
*/
smoothing?: number;
+ /** The elements drawing the picture, and `<KeyframeTrack>` children. */
+ children?: SolidJSX.Element;
};
/**
@@ -921,12 +923,12 @@ export type ColorStopProps = ColorProps & OpacityProps & TrackChildren & {
export type MediaPaintProps = PaintProps & MediaProps & FitProps & FrameRateProps & TrackChildren;
export type VideoProps = CommonProps & MediaProps & FitProps & FrameRateProps & AudioTrackProps & {
- /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>` children. */
+ /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
export type ImageProps = CommonProps & MediaProps & FitProps & FrameRateProps & {
- /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>` children. */
+ /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<ClipPath>`, `<Mask>`, `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
@@ -1030,8 +1032,8 @@ export type TextProps = CommonProps & Partial<ColorProps> & FontProps & {
leading?: number;
/**
* The text content, required; alongside it, `<TextRange>`, paint,
- * `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>`
- * children.
+ * `<Stroke>`, `<Shadow>`, `<Effect>`, `<ClipPath>`, `<Mask>`, `<Animation>`
+ * and `<KeyframeTrack>` children.
*/
children: SolidJSX.Element;
};
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index c5352371..ad8cbcd6 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, Constraint, ConstraintCache, ConstraintType, CornerRadius, clampPointCount, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, EvenOdd, Expanded, FontStyle, FramePromises, FrameRate, getActiveEntity, Loop, LoadRequest, Mask, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsClipPath, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, LINEAR_GRADIENT_DEFAULTS, LinearGradient, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Pivot, Paint, PaintType, parseColor, parsePath, PathTrim, PendingSource, PendingSync, Playback, PlaybackRate, PointCount, Position, ELLIPTICAL_GRADIENT_DEFAULTS, EllipticalGradient, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceFrameRate, setCameraMatrix, setPlayhead, setTimelineView, Stroke, StrokeCap, StrokeDash, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, Transition, TransitionType, Trim, UniformScale, VectorPath, ViewBox, Volume, Workarea } from '@diffusionstudio/runtime';
+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, Constraint, ConstraintCache, ConstraintType, CornerRadius, clampPointCount, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, EvenOdd, Expanded, FontStyle, FramePromises, FrameRate, getActiveEntity, Loop, LoadRequest, Mask, ClipPath, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, LINEAR_GRADIENT_DEFAULTS, LinearGradient, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Pivot, Paint, PaintType, parseColor, parsePath, PathTrim, PendingSource, PendingSync, Playback, PlaybackRate, PointCount, Position, ELLIPTICAL_GRADIENT_DEFAULTS, EllipticalGradient, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceFrameRate, setCameraMatrix, setPlayhead, setTimelineView, Stroke, StrokeCap, StrokeDash, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, Transition, TransitionType, Trim, UniformScale, VectorPath, ViewBox, Volume, Workarea } from '@diffusionstudio/runtime';
import { DEFAULT_MASK_SMOOTHING } from '@diffusionstudio/assets';
import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createSignal } from 'solid-js';
@@ -709,6 +709,11 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
entity.set(Effect, { type: EffectType.LAYER_BLUR, value: 0 });
break;
}
+ case 'clipPath': {
+ entity = createEntity(this.world);
+ entity.add(ClipPath);
+ break;
+ }
case 'mask': {
entity = createEntity(this.world);
entity.add(Mask);
@@ -1082,15 +1087,6 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
entity.set(BlendMode, { value: mode });
return;
}
- case 'clipPath':
- case 'mask': {
- if (value === true && entity !== this.stage.entity) {
- entity.add(IsClipPath);
- } else {
- entity.remove(IsClipPath);
- }
- return;
- }
case 'inverted': {
if (!entity.has(Mask)) return;
entity.set(Mask, { inverted: value === true });
diff --git a/packages/reconciler/src/elements.ts b/packages/reconciler/src/elements.ts
index c09a619e..e513c78b 100644
--- a/packages/reconciler/src/elements.ts
+++ b/packages/reconciler/src/elements.ts
@@ -23,6 +23,7 @@ import type {
AnimationProps,
AudioProps,
CaptionsProps,
+ ClipPathProps,
ColorStopProps,
EffectProps,
EllipseProps,
@@ -116,6 +117,7 @@ export const ColorStop = hostElement<ColorStopProps>("ColorStop");
export const Stroke = hostElement<StrokeProps>("Stroke");
export const Shadow = hostElement<ShadowProps>("Shadow");
export const Effect = hostElement<EffectProps>("Effect");
+export const ClipPath = hostElement<ClipPathProps>("ClipPath");
export const Mask = hostElement<MaskProps>("Mask");
export const Animation = hostElement<AnimationProps>("Animation");
export const KeyframeTrack = hostElement<KeyframeTrackProps>("KeyframeTrack");
diff --git a/packages/runtime/src/actions/cache.ts b/packages/runtime/src/actions/cache.ts
index bdf5769f..ec3301e3 100644
--- a/packages/runtime/src/actions/cache.ts
+++ b/packages/runtime/src/actions/cache.ts
@@ -11,7 +11,7 @@ import { Not, Or } from 'koota';
import { store } from '../world/store';
import {
ChildOf, Cache,
- Geometry, Group, AdjustmentLayer, IsClipPath, Mask, Paint, Stroke, Shadow, Effect,
+ Geometry, Group, AdjustmentLayer, ClipPath, Mask, Paint, Stroke, Shadow, Effect,
TextRange, KeyframeTrack, Keyframe, Animation,
} from '../traits';
import { isStage } from '../queries/predicates';
@@ -39,12 +39,12 @@ export function rebuildCaches(world: World, entity: Entity, parent: Entity | nul
if (entity.has(Geometry) || entity.has(Group) || entity.has(AdjustmentLayer)) {
cache.children[pid] = collect(
- Or(Geometry, Group, AdjustmentLayer), ChildOf(parent), Not(IsClipPath),
+ Or(Geometry, Group, AdjustmentLayer), ChildOf(parent),
).sort(sortByItemIndex);
}
- if (entity.has(IsClipPath)) {
- cache.clipPaths[pid] = collect(Geometry, IsClipPath, ChildOf(parent))
+ if (entity.has(ClipPath)) {
+ cache.clipPaths[pid] = collect(ClipPath, ChildOf(parent))
.sort(sortByItemIndex);
}
@@ -138,28 +138,6 @@ export function evictFromCaches(world: World, entity: Entity, parent: Entity | n
}
}
-/**
- * Move an attached geometry between its parent's `children` and `clipPaths` when
- * its `IsClipPath` tag is toggled in place. `rebuildCaches` files by trait on
- * attach; here the queries cannot be trusted (koota fires onRemove before the
- * tag is cleared), so the two lists are edited by hand.
- */
-export function refileClipPath(world: World, entity: Entity, parent: Entity | null, clipPath: boolean): void {
- if (parent === null || isStage(parent)) return;
- if (!parent.has(Cache)) parent.add(Cache);
-
- const cache = store(world, Cache);
- const pid = parent.id();
- const without = (list: Entity[] | undefined) => (list ?? []).filter((e) => e !== entity);
-
- const clipPaths = without(cache.clipPaths[pid]);
- const children = without(cache.children[pid]);
- (clipPath ? clipPaths : children).push(entity);
-
- cache.clipPaths[pid] = clipPaths.sort(sortByItemIndex);
- cache.children[pid] = children.sort(sortByItemIndex);
-}
-
function isNodeEntity(entity: Entity): boolean {
return entity.has(Geometry) || entity.has(Group) || entity.has(AdjustmentLayer);
}
diff --git a/packages/runtime/src/actions/interactive.ts b/packages/runtime/src/actions/interactive.ts
index f5a89fea..3e14dc70 100644
--- a/packages/runtime/src/actions/interactive.ts
+++ b/packages/runtime/src/actions/interactive.ts
@@ -11,7 +11,7 @@ import { Not, Or } from 'koota';
import {
AdjustmentLayer, ChildOf, Culled, Geometry, Group, Hovering, Interactive,
- IsClipPath, Root, Sequential,
+ Root, Sequential,
} from '../traits';
import { isScene } from '../queries/predicates';
import { isPointerInEntity } from '../queries/interaction';
@@ -52,7 +52,7 @@ export function syncInteractiveState(world: World): void {
/** The topmost child of `parent` under a device-pixel point, or null. */
export function findChildAt(world: World, parent: Entity, point: Point): Entity | null {
- const children = world.query(Or(Geometry, Group), ChildOf(parent), Not(IsClipPath), Not(Culled));
+ const children = world.query(Or(Geometry, Group), ChildOf(parent), Not(Culled));
for (let i = children.length - 1; i >= 0; i--) {
const child = children[i]!;
diff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.ts
index da46afef..0e890b5e 100644
--- a/packages/runtime/src/actions/timing.ts
+++ b/packages/runtime/src/actions/timing.ts
@@ -11,10 +11,10 @@ import { DEFAULT_DURATION_FRAMES } from '../constants';
import {
Geometry, Group, AdjustmentLayer, Paint, Caption, Cache, Computed,
Delay, Trim, PlaybackRate, CaptionDecoderHandle, AssetId, FrameRate,
- FramePromises,
+ FramePromises, ClipPath, Mask, Effect,
} from '../traits';
import { isGroupLike } from '../queries/predicates';
-import { getParentNode } from '../queries/hierarchy';
+import { getMaskContainers, getParentNode } from '../queries/hierarchy';
import { findAssetDuration, getSourceFrameAt, isPaintEntity, secondsToFrames } from '../utils/time';
import { getAsset } from './assets';
import { getTranscriptDuration, primeTranscriptDuration } from '../media/caption/utils';
@@ -194,12 +194,33 @@ export function propagateTimeRangeDown(world: World, entity: Entity, ignore?: Ig
for (const child of entity.get(Cache)?.children ?? []) {
propagateTimeRangeDown(world, child);
}
- for (const clipPath of entity.get(Cache)?.clipPaths ?? []) {
- propagateTimeRangeDown(world, clipPath);
- }
+ placeMaskedTime(world, entity);
recomputeEntityTimeRange(world, entity, ignore);
}
+/**
+ * Places the nodes under `node`'s `<clipPath>`s and `<mask>`s in its time:
+ * each container takes `node`'s clock, so the nodes under it, which measure
+ * against their parent, run on the timeline of the node they cut.
+ */
+function placeMaskedTime(world: World, node: Entity): void {
+ const computed = store(world, Computed);
+ const nid = node.id();
+
+ for (const container of getMaskContainers(world, node)) {
+ const cid = container.id();
+ computed.origin[cid] = computed.origin[nid] ?? 0;
+ computed.playbackRate[cid] = computed.playbackRate[nid] || 1;
+ computed.start[cid] = computed.start[nid] ?? 0;
+ computed.end[cid] = computed.end[nid] ?? 0;
+ computed.duration[cid] = computed.duration[nid] ?? 0;
+
+ for (const child of container.get(Cache)?.children ?? []) {
+ propagateTimeRangeDown(world, child);
+ }
+ }
+}
+
/**
* Walk upward recomputing any ancestor whose bounds depend on its children
* (group-like without a trimmed end). Call with the entity that changed.
@@ -334,6 +355,15 @@ export function reactToChildAttached(world: World, child: Entity) {
return;
}
+ // JSX attaches bottom-up: a container meets its holder (or an effect
+ // carrying masks meets its node) after its nodes were placed against it.
+ if (child.has(ClipPath) || child.has(Mask) || child.has(Effect)) {
+ let holder = getParentNode(child);
+ if (holder?.has(Effect)) holder = getParentNode(holder);
+ if (holder !== null) placeMaskedTime(world, holder);
+ return;
+ }
+
if (child.has(Paint)) {
reactToPaintChange(world, child);
}
diff --git a/packages/runtime/src/queries/hierarchy.ts b/packages/runtime/src/queries/hierarchy.ts
index 5bfb1f28..70879edb 100644
--- a/packages/runtime/src/queries/hierarchy.ts
+++ b/packages/runtime/src/queries/hierarchy.ts
@@ -2,7 +2,8 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { ChildOf, Computed, Name, Playback } from '../traits';
+import { Cache, ChildOf, Computed, Name, Playback } from '../traits';
+import { store } from '../world/store';
import { isStage, isScene } from './predicates';
// Direct module, not the utils barrel: utils/time reaches back into this file.
import { sortByItemIndex } from '../utils/sort';
@@ -29,6 +30,31 @@ export function getParentNode(entity: Entity | null | undefined): Entity | null
return parent;
}
+const NO_CONTAINERS: Entity[] = [];
+
+/**
+ * The `<clipPath>`s and `<mask>`s cutting `node`: its own, then the masks
+ * limiting its effects. The nodes under them are placed in `node`'s space and
+ * time, and each container carries `node`'s matrix and clock for them (see
+ * the transform and playback systems), so a walk that places a node's
+ * children places these too.
+ */
+export function getMaskContainers(world: World, node: Entity): Entity[] {
+ const cache = store(world, Cache);
+ const nid = node.id();
+ const clipPaths = cache.clipPaths[nid];
+ const masks = cache.masks[nid];
+ const effects = cache.effects[nid];
+ if (!clipPaths?.length && !masks?.length && !effects?.length) return NO_CONTAINERS;
+
+ const containers = [...clipPaths ?? [], ...masks ?? []];
+ for (const effect of effects ?? []) {
+ const limits = cache.masks[effect.id()];
+ if (limits?.length) containers.push(...limits);
+ }
+ return containers;
+}
+
/**
* Nearest ancestor of `entity` (excluding `entity` itself) that is a scene, or null.
*/
diff --git a/packages/runtime/src/queries/predicates.ts b/packages/runtime/src/queries/predicates.ts
index 5ff4221d..2848d72a 100644
--- a/packages/runtime/src/queries/predicates.ts
+++ b/packages/runtime/src/queries/predicates.ts
@@ -3,8 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import {
- Scene, Group, Sequential, Audio, AdjustmentLayer, Caption, Geometry, IsClipPath,
- Paint, Cache, Stage,
+ Scene, Group, Sequential, Audio, AdjustmentLayer, Caption, Geometry, ClipPath, Mask,
+ Paint, Cache, Stage, ChildOf,
} from '../traits';
import { GeometryType, PaintType } from '../constants';
@@ -81,7 +81,21 @@ export function isShape(entity: Entity): boolean {
}
export function isClipPath(entity: Entity): boolean {
- return entity.has(IsClipPath);
+ return entity.has(ClipPath);
+}
+
+/** A shape under a `<clipPath>`: one of the outlines it clips by, drawn nowhere itself. */
+export function isClipShape(entity: Entity): boolean {
+ return entity.targetFor(ChildOf)?.has(ClipPath) ?? false;
+}
+
+export function isMask(entity: Entity): boolean {
+ return entity.has(Mask);
+}
+
+/** A `<clipPath>` or a `<mask>`: a container whose nodes cut its holder rather than draw. */
+export function isMaskContainer(entity: Entity): boolean {
+ return entity.has(ClipPath) || entity.has(Mask);
}
export function hasHtmlPaint(entity: Entity): boolean {
diff --git a/packages/runtime/src/queries/timeline-index.ts b/packages/runtime/src/queries/timeline-index.ts
index 1df8548d..b029b76b 100644
--- a/packages/runtime/src/queries/timeline-index.ts
+++ b/packages/runtime/src/queries/timeline-index.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import {
- ChildOf, Keyframe, KeyframeTrack, IsClipPath, Geometry, Group,
+ ChildOf, Keyframe, KeyframeTrack, Geometry, Group,
AdjustmentLayer, Expanded,
} from '../traits';
import { isSequence } from './predicates';
@@ -31,7 +31,6 @@ export function buildTimelineLayers(world: World, parent: Entity): TimelineNode[
const tracks: Entity[] = [];
const geoms: Entity[] = [];
- const clipPaths: Entity[] = [];
const subitems: Entity[] = [];
for (const child of world.query(ChildOf(parent))) {
@@ -40,8 +39,6 @@ export function buildTimelineLayers(world: World, parent: Entity): TimelineNode[
if (child.has(KeyframeTrack)) {
tracks.push(child);
- } else if (child.has(IsClipPath)) {
- clipPaths.push(child);
} else if (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) {
geoms.push(child);
} else {
@@ -51,7 +48,6 @@ export function buildTimelineLayers(world: World, parent: Entity): TimelineNode[
tracks.sort(sortByItemIndex).reverse();
geoms.sort(sortByItemIndex).reverse();
- clipPaths.sort(sortByItemIndex).reverse();
subitems.sort(sortByItemIndex).reverse();
const nodes: TimelineNode[] = [];
@@ -77,10 +73,6 @@ export function buildTimelineLayers(world: World, parent: Entity): TimelineNode[
nodes.push(buildNode(world, geom, 'geometry'));
}
- for (const clipPath of clipPaths) {
- nodes.push(buildNode(world, clipPath, 'geometry'));
- }
-
return nodes;
}
@@ -119,7 +111,6 @@ function isExpandable(world: World, parent: Entity): boolean {
if (child.has(Keyframe)) continue;
if (sequence && !hasKeyframes(world, child)) continue;
if (
- child.has(IsClipPath) ||
child.has(Geometry) ||
child.has(Group) ||
child.has(AdjustmentLayer) ||
diff --git a/packages/runtime/src/systems/playback.ts b/packages/runtime/src/systems/playback.ts
index e25f2ea1..3121e632 100644
--- a/packages/runtime/src/systems/playback.ts
+++ b/packages/runtime/src/systems/playback.ts
@@ -12,7 +12,7 @@ import { Not, Or } from 'koota';
import { store } from '../world/store';
import { PaintType } from '../constants';
import {
- ChildOf, Hidden, Culled, Dragging, AssetId, Cache, Mask,
+ ChildOf, Hidden, Culled, Dragging, AssetId, Mask,
Geometry, Group, AdjustmentLayer, Paint, Audio, Caption, Muted, Soloed,
Sequential, Transition, Playback, Workarea,
AudioPlayback, Computed,
@@ -20,7 +20,7 @@ import {
Mode, Silent, FrameRate, Time, AudioEngine, FramePromises, Tickers,
Root,
} from '../traits';
-import { getParentNode } from '../queries/hierarchy';
+import { getMaskContainers, getParentNode } from '../queries/hierarchy';
import { getIntrinsicPaint, getSourceWindow } from '../utils/time';
import { clamp } from '../math/common';
import { getTransitionWindow } from '../utils/transition';
@@ -222,15 +222,14 @@ function forwardImageDecoder(world: World, _scene: Entity, _entity: Entity, fill
}
/**
- * Seeks the frame sequences of the masks under the entity's effects: a
+ * Seeks the frame sequences of the masks cutting the entity or its effects: a
* mask's frame `i` belongs to source frame `offset + i` of the clip, so the
* seek is the clip's own source frame less the offset, at the rate the
* sequence was written at (the composition's, authored as its frameRate).
*/
function forwardMaskDecoders(world: World, scene: Entity, entity: Entity): void {
- const cache = store(world, Cache);
- const effects = cache.effects[entity.id()];
- if (!effects?.length) return;
+ const containers = getMaskContainers(world, entity);
+ if (!containers.length) return;
const computed = store(world, Computed);
const maskStore = store(world, Mask);
@@ -248,19 +247,17 @@ function forwardMaskDecoders(world: World, scene: Entity, entity: Entity): void
const source = getSourceWindow(entity);
const sourceFrame = clamp(localFrame, source.in, source.out);
- for (const effect of effects) {
- if (effect.has(Hidden)) continue;
- for (const mask of cache.masks[effect.id()] ?? []) {
- if (mask.has(Hidden) || !mask.has(AssetId)) continue;
-
- const decoder = resolveVideoDecoder(world, mask);
- if (!decoder) continue;
- const frame = Math.max(0, sourceFrame - (maskStore.offset[mask.id()] ?? 0));
- // Seek first: the editor keeps no promise list, and an optional call
- // skips its arguments along with itself.
- const seek = decoder.seekTo(frame, fps);
- framePromises(world)?.push(seek ?? null);
- }
+ for (const mask of containers) {
+ if (!mask.has(Mask) || mask.has(Hidden) || !mask.has(AssetId)) continue;
+ if (getParentNode(mask)?.has(Hidden)) continue;
+
+ const decoder = resolveVideoDecoder(world, mask);
+ if (!decoder) continue;
+ const frame = Math.max(0, sourceFrame - (maskStore.offset[mask.id()] ?? 0));
+ // Seek first: the editor keeps no promise list, and an optional call
+ // skips its arguments along with itself.
+ const seek = decoder.seekTo(frame, fps);
+ framePromises(world)?.push(seek ?? null);
}
}
@@ -313,7 +310,7 @@ function forwardDecoders(world: World, scene: Entity, entity: Entity): void {
}
}
- if (visualsEnabled && entity.has(Geometry)) {
+ if (visualsEnabled) {
forwardMaskDecoders(world, scene, entity);
}
}
@@ -329,6 +326,13 @@ function forwardDecoders(world: World, scene: Entity, entity: Entity): void {
for (const child of world.query(ChildOf(entity), Or(Geometry, Group, AdjustmentLayer), Not(Hidden))) {
forwardDecoders(world, scene, child);
}
+
+ for (const container of getMaskContainers(world, entity)) {
+ if (container.has(Hidden)) continue;
+ for (const child of world.query(ChildOf(container), Or(Geometry, Group, AdjustmentLayer), Not(Hidden))) {
+ forwardDecoders(world, scene, child);
+ }
+ }
}
function updateVisibility(world: World, scene: Entity, entity: Entity): void {
@@ -353,6 +357,16 @@ function updateVisibility(world: World, scene: Entity, entity: Entity): void {
for (const child of world.query(Or(Geometry, Group, AdjustmentLayer), ChildOf(entity))) {
updateVisibility(world, scene, child);
}
+
+ // A `<clipPath>` or `<mask>` runs on the clock of the node it cuts.
+ for (const container of getMaskContainers(world, entity)) {
+ const cid = container.id();
+ computed.localTime[cid] = computed.localTime[eid]!;
+ computed.visibility[cid] = computed.visibility[eid]!;
+ for (const child of world.query(Or(Geometry, Group, AdjustmentLayer), ChildOf(container))) {
+ updateVisibility(world, scene, child);
+ }
+ }
}
function resetDecoders(world: World, entity: Entity): void {
diff --git a/packages/runtime/src/systems/render.ts b/packages/runtime/src/systems/render.ts
index dd48e8c2..a98fc1bb 100644
--- a/packages/runtime/src/systems/render.ts
+++ b/packages/runtime/src/systems/render.ts
@@ -17,7 +17,7 @@ import {
TransitionType,
} from '../constants';
import {
- ChildOf, Hidden, Culled, Interactive, IsClipPath, AssetId,
+ ChildOf, Hidden, Culled, Interactive, AssetId,
ClipsContent, Geometry, Group, Paint, Color, Caption, ScaleMode, Shader,
BlendMode, Effect, Mask, Transition, MixedCornerRadius, PointCount, EvenOdd,
LocalTransform, WorldTransform, Computed, Cache,
@@ -76,6 +76,12 @@ let shapeFillRule: CanvasFillRule = 'nonzero';
*/
export function drawShapePath(world: World, entity: Entity): void {
const ctx = getCtx(world);
+ ctx.beginPath();
+ traceShapePath(world, ctx, entity);
+}
+
+/** Adds the outline `drawShapePath` draws to `ctx` as subpaths of its current path. */
+function traceShapePath(world: World, ctx: CanvasPath, entity: Entity): void {
const computed = store(world, Computed);
const eid = entity.id();
const w = computed.width[eid]!;
@@ -84,7 +90,6 @@ export function drawShapePath(world: World, entity: Entity): void {
const type = entity.has(Geometry) ? store(world, Geometry).value[eid]! : GeometryType.RECT;
shapeFillRule = 'nonzero';
if (type === GeometryType.PATH) {
- ctx.beginPath();
const geometry = getDrawnPath(world, entity);
if (geometry !== null) tracePath(ctx, geometry, getPathTransform(world, entity));
if (entity.has(EvenOdd)) shapeFillRule = 'evenodd';
@@ -92,7 +97,6 @@ export function drawShapePath(world: World, entity: Entity): void {
}
if (type !== GeometryType.RECT && isShapeGeometry(type)) {
const pointCount = entity.has(PointCount) ? store(world, PointCount).value[eid]! : 3;
- ctx.beginPath();
traceShape(ctx, type, w, h, pointCount);
return;
}
@@ -103,8 +107,6 @@ export function drawShapePath(world: World, entity: Entity): void {
let br = hasMixed ? computed.cornerRadiusBottomRight[eid]! : tl;
let bl = hasMixed ? computed.cornerRadiusBottomLeft[eid]! : tl;
- ctx.beginPath();
-
if (tl === 0 && tr === 0 && br === 0 && bl === 0) {
ctx.rect(0, 0, w, h);
} else if (tl === tr && tr === br && br === bl) {
@@ -962,7 +964,7 @@ export function renderNode(world: World, entity: Entity): void {
});
}
- if (entity.has(IsClipPath) || entity.has(Hidden)) return;
+ if (entity.has(Hidden)) return;
ctx.save();
@@ -977,12 +979,12 @@ export function renderNode(world: World, entity: Entity): void {
);
for (const clipPath of store(world, Cache).clipPaths[eid] ?? []) {
- if (computed.visibility[clipPath.id()] === 0) continue;
clipTo(world, clipPath);
}
- // An effect limited by a `<mask>` takes the node through layers.
+ // A `<mask>` on the node, or one limiting an effect, takes it through layers.
const passes = effectPasses(world, entity);
+ const masks = activeMasks(world, entity);
// Opacity and blend mode. The store slot may hold a destroyed entity's
// value (ids are recycled), so it is only readable behind has().
@@ -990,8 +992,8 @@ export function renderNode(world: World, entity: Entity): void {
const bi = entity.has(BlendMode) ? store(world, BlendMode).value[eid] ?? 0 : 0;
if (bi !== 0) ctx.globalCompositeOperation = COMPOSITE_OPERATIONS[bi]!;
- if (passes) {
- renderLayered(world, entity, passes);
+ if (passes || masks.length > 0) {
+ renderLayered(world, entity, passes, masks);
} else {
renderContent(world, entity, buildEffects(world, entity));
}
@@ -1001,27 +1003,51 @@ export function renderNode(world: World, entity: Entity): void {
ctx.restore();
}
-/** Clips the current context to the box of `clipPath`, in world space. */
+/**
+ * Clips the current context to the outlines of the shapes under `clipPath`,
+ * each where its own transform puts it, united by the nonzero rule (a lone
+ * path keeps its own `fillRule`). One switched off, or none of whose shapes
+ * is in its time, lets go: it clips nothing.
+ */
function clipTo(world: World, clipPath: Entity): void {
+ if (clipPath.has(Hidden)) return;
+
+ const computed = store(world, Computed);
+ const geometry = store(world, Geometry);
+ const outline = new Path2D();
+ let count = 0;
+
+ for (const shape of store(world, Cache).children[clipPath.id()] ?? []) {
+ const sid = shape.id();
+ if (computed.visibility[sid] === 0 || shape.has(Hidden) || !shape.has(Geometry)) continue;
+ if (!isShapeGeometry(geometry.value[sid])) continue;
+
+ const traced = new Path2D();
+ traceShapePath(world, traced, shape);
+ outline.addPath(traced, worldMatrix(world, shape));
+ count++;
+ }
+ if (count === 0) return;
+
+ // The outline is in device pixels; the clip outlives the transform.
const ctx = getCtx(world);
- ctx.save();
- setWorldTransform(world, ctx, clipPath);
- drawShapePath(world, clipPath);
- ctx.restore();
- ctx.clip(shapeFillRule);
+ const transform = ctx.getTransform();
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.clip(outline, count === 1 ? shapeFillRule : 'nonzero');
+ ctx.setTransform(transform);
}
-function setWorldTransform(world: World, ctx: Ctx2D, entity: Entity): void {
+function worldMatrix(world: World, entity: Entity): DOMMatrix {
const worldTransform = store(world, WorldTransform);
const eid = entity.id();
- ctx.setTransform(
+ return new DOMMatrix([
worldTransform.a[eid]!,
worldTransform.b[eid]!,
worldTransform.c[eid]!,
worldTransform.d[eid]!,
worldTransform.e[eid]!,
worldTransform.f[eid]!,
- );
+ ]);
}
/** The node's own pixels and its children on the current context, under `filter` when one is given. */
@@ -1119,19 +1145,33 @@ function effectPasses(world: World, entity: Entity): EffectPass[] | null {
const NO_MATTES: Entity[] = [];
-/** The effect's masks that have a picture and are switched on. */
-function activeMasks(world: World, effect: Entity): Entity[] {
- const all = store(world, Cache).masks[effect.id()];
+/**
+ * The masks under `holder` (a node or an effect) that are switched on and
+ * have a picture: a mask file, or a node under them in its time. One whose
+ * nodes are all out of their time lets go, as a clip path does.
+ */
+function activeMasks(world: World, holder: Entity): Entity[] {
+ const all = store(world, Cache).masks[holder.id()];
if (!all?.length) return NO_MATTES;
let active: Entity[] | null = null;
for (const mask of all) {
- if (mask.has(Hidden) || !mask.has(AssetId)) continue;
+ if (mask.has(Hidden)) continue;
+ if (!mask.has(AssetId) && pictureNodes(world, mask).length === 0) continue;
(active ??= []).push(mask);
}
return active ?? NO_MATTES;
}
+/** The nodes under `mask` that draw its picture this frame. */
+function pictureNodes(world: World, mask: Entity): Entity[] {
+ const children = store(world, Cache).children[mask.id()];
+ if (!children?.length) return NO_MATTES;
+
+ const visibility = store(world, Computed).visibility;
+ return children.filter((child) => visibility[child.id()] !== 0 && !child.has(Hidden));
+}
+
// ── Layers ───────────────────────────────────────────────────
type Layer = { canvas: OffscreenCanvas; ctx: OffscreenCanvasRenderingContext2D };
@@ -1181,13 +1221,15 @@ function blit(target: Layer, source: OffscreenCanvas, operation: GlobalComposite
const IDENTITY = new DOMMatrix();
/**
- * Draws the node through layers: its content unfiltered onto one, then
- * each effect pass from one layer to the next (a filter run is a filtered
- * copy; a masked effect combines the copy with the unfiltered picture by
- * its masks' coverage), and the layer lands on the surface under the
- * node's opacity and blend mode, which the caller has already set.
+ * Draws the node through layers: its content onto one (unfiltered when
+ * effect passes follow, under its filter when none do), then each effect
+ * pass from one layer to the next (a filter run is a filtered copy; a masked
+ * effect combines the copy with the unfiltered picture by its masks'
+ * coverage), then its own masks cut what that left, and the layer lands on
+ * the surface under the node's opacity and blend mode, which the caller has
+ * already set.
*/
-function renderLayered(world: World, entity: Entity, passes: EffectPass[]): void {
+function renderLayered(world: World, entity: Entity, passes: EffectPass[] | null, masks: Entity[]): void {
const ctx = getCtx(world);
const surface = world.get(RenderSurface)!.canvas!;
const base = layerDepth;
@@ -1196,19 +1238,24 @@ function renderLayered(world: World, entity: Entity, passes: EffectPass[]): void
try {
let front = acquireLayer(surface.width, surface.height);
resetLayer(front, local);
- drawOnto(front.ctx, () => renderContent(world, entity, null));
-
- let back = acquireLayer(surface.width, surface.height);
- for (const pass of passes) {
- if (pass.kind === 'filter') {
- resetLayer(back, IDENTITY);
- blit(back, front.canvas, 'source-over', pass.filter);
- } else {
- applyMaskedEffect(world, entity, pass, front, back, local);
+ const effects = passes ? null : buildEffects(world, entity);
+ drawOnto(front.ctx, () => renderContent(world, entity, effects));
+
+ if (passes) {
+ let back = acquireLayer(surface.width, surface.height);
+ for (const pass of passes) {
+ if (pass.kind === 'filter') {
+ resetLayer(back, IDENTITY);
+ blit(back, front.canvas, 'source-over', pass.filter);
+ } else {
+ applyMaskedEffect(world, entity, pass, front, back, local);
+ }
+ [front, back] = [back, front];
}
- [front, back] = [back, front];
}
+ if (masks.length > 0) applyMasks(world, entity, masks, front, local);
+
ctx.save();
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.drawImage(front.canvas, 0, 0);
@@ -1239,7 +1286,7 @@ function applyMaskedEffect(world: World, entity: Entity, pass: Extract<EffectPas
coverage.ctx.fill(shapeFillRule);
for (const mask of pass.masks) {
const strength = Math.min(1, Math.max(0, opacities[mask.id()] ?? 1));
- if (strength <= EPSILON || !drawMaskRemoval(world, entity, mask, scratch, local)) continue;
+ if (strength <= EPSILON || !drawMaskRemoval(world, entity, mask, scratch, local, true)) continue;
blit(coverage, scratch.canvas, 'destination-out', 'none', strength);
}
@@ -1257,43 +1304,89 @@ function applyMaskedEffect(world: World, entity: Entity, pass: Extract<EffectPas
}
/**
- * Draws onto `layer` what `mask` takes away from the node: the node's box
- * less the mask's picture, or the picture itself when the mask is
- * inverted, fitted into the box the way the node fits its footage so it lands
- * on the frame it was made from, and softened by the mask's blur. A mask
- * file's picture is its outline, filled at the size it lands at so its edge
- * stays sharp at any scale, smoothed as much as the mask asks. False, and nothing drawn, while the picture's frame is not decoded yet.
+ * The node's own masks cut from `front`, which keeps only what all of them
+ * cover: each takes away what its picture does not cover (or, inverted, what
+ * it does), weighted by the mask's opacity. Unlike an effect's masks they
+ * are not held to the node's box, so a group is cut as a whole.
*/
-function drawMaskRemoval(world: World, entity: Entity, mask: Entity, layer: Layer, local: DOMMatrix): boolean {
+function applyMasks(world: World, entity: Entity, masks: Entity[], front: Layer, local: DOMMatrix): void {
+ const { width, height } = front.canvas;
+ const coverage = acquireLayer(width, height);
+ const scratch = acquireLayer(width, height);
+ const opacities = store(world, Computed).opacity;
+
+ try {
+ resetLayer(coverage, IDENTITY);
+ coverage.ctx.fillStyle = '#000000';
+ coverage.ctx.fillRect(0, 0, width, height);
+ for (const mask of masks) {
+ const strength = Math.min(1, Math.max(0, opacities[mask.id()] ?? 1));
+ if (strength <= EPSILON || !drawMaskRemoval(world, entity, mask, scratch, local, false)) continue;
+ blit(coverage, scratch.canvas, 'destination-out', 'none', strength);
+ }
+
+ blit(front, coverage.canvas, 'destination-in');
+ } finally {
+ layerDepth -= 2;
+ }
+}
+
+/**
+ * Draws onto `layer` what `mask` takes away from the node: everything (or,
+ * when `bounded`, the node's box) less the mask's picture, or the picture
+ * itself when the mask is inverted, softened by the mask's blur. The picture
+ * is the nodes under the mask, drawn where their transforms put them and
+ * read by their alpha, or else its mask file: fitted into the
+ * box the way the node fits its footage so it lands on the frame it was
+ * made from, and filled as an outline at the size it lands at so its edge
+ * stays sharp at any scale, smoothed as much as the mask asks. False, and
+ * nothing drawn, while the file's frame is not decoded yet.
+ */
+function drawMaskRemoval(world: World, entity: Entity, mask: Entity, layer: Layer, local: DOMMatrix, bounded: boolean): boolean {
const computed = store(world, Computed);
- const eid = entity.id();
+ const masks = store(world, Mask);
const mid = mask.id();
+ const feather = computed.blur[mid] ?? 0;
+ const inverted = masks.inverted[mid] ?? false;
+
+ const nodes = pictureNodes(world, mask);
+ if (nodes.length > 0) {
+ const { width, height } = layer.canvas;
+ const picture = acquireLayer(width, height);
+ try {
+ resetLayer(picture, local);
+ drawOnto(picture.ctx, () => {
+ for (const node of nodes) renderNode(world, node);
+ });
+ const { ctx } = layer;
+ beginRemoval(world, entity, layer, local, inverted, bounded);
+ if (feather > EPSILON) ctx.filter = `blur(${feather}px)`;
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.drawImage(picture.canvas, 0, 0);
+ ctx.restore();
+ } finally {
+ layerDepth--;
+ }
+ return true;
+ }
+
+ const eid = entity.id();
const w = computed.width[eid]!;
const h = computed.height[eid]!;
const decoder = resolveVideoDecoder(world, mask);
- const smoothing = store(world, Mask).smoothing[mid] ?? DEFAULT_MASK_SMOOTHING;
+ const smoothing = masks.smoothing[mid] ?? DEFAULT_MASK_SMOOTHING;
const outline = decoder instanceof MaskDecoder ? decoder.getOutline(smoothing) : null;
const frame = outline ? null : decoder?.toBitmap();
const picture = outline ?? frame;
if (!picture) return false;
- const feather = computed.blur[mid] ?? 0;
- const inverted = store(world, Mask).inverted[mid] ?? false;
const source = findGeometryAssetSource(world, entity);
const mode = (source && store(world, ScaleMode).value[source.id()]) ?? ScaleModeType.COVER;
const [dx, dy, sw, sh] = getScaledImageProps(mode, picture.width, picture.height, w, h);
const { ctx } = layer;
- resetLayer(layer, local);
- ctx.save();
- drawOnto(ctx, () => drawShapePath(world, entity));
- if (!inverted) {
- ctx.fillStyle = '#000000';
- ctx.fill(shapeFillRule);
- }
- ctx.clip(shapeFillRule);
- ctx.globalCompositeOperation = inverted ? 'source-over' : 'destination-out';
+ beginRemoval(world, entity, layer, local, inverted, bounded);
if (feather > EPSILON) ctx.filter = `blur(${feather}px)`;
if (outline) {
// The path is placed in the box rather than the context scaled, so the
@@ -1310,6 +1403,30 @@ function drawMaskRemoval(world: World, entity: Entity, mask: Entity, layer: Laye
return true;
}
+/**
+ * Clears `layer` under `local` and saves its state, ready for a mask's
+ * picture to be drawn as what the mask takes away: over a fill of
+ * everything (or of the node's box, which then also clips, when `bounded`)
+ * that the picture is cut from, or onto nothing when `inverted`, where the
+ * picture is itself what goes. The caller draws and restores.
+ */
+function beginRemoval(world: World, entity: Entity, layer: Layer, local: DOMMatrix, inverted: boolean, bounded: boolean): void {
+ const { ctx, canvas } = layer;
+ resetLayer(layer, local);
+ ctx.save();
+ ctx.fillStyle = '#000000';
+ if (bounded) {
+ drawOnto(ctx, () => drawShapePath(world, entity));
+ if (!inverted) ctx.fill(shapeFillRule);
+ ctx.clip(shapeFillRule);
+ } else if (!inverted) {
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.fillRect(0, 0, canvas.width, canvas.height);
+ ctx.setTransform(local);
+ }
+ ctx.globalCompositeOperation = inverted ? 'source-over' : 'destination-out';
+}
+
/**
* Render system entry point. Call after transformSystem.
*
diff --git a/packages/runtime/src/systems/transform.ts b/packages/runtime/src/systems/transform.ts
index a7decad7..7487af21 100644
--- a/packages/runtime/src/systems/transform.ts
+++ b/packages/runtime/src/systems/transform.ts
@@ -6,12 +6,12 @@ import { Not, Or } from 'koota';
import { store } from '../world/store';
import {
- ChildOf, Geometry, Group, Hidden, IsClipPath, Sequential, AdjustmentLayer,
+ ChildOf, Geometry, Group, Hidden, Sequential, AdjustmentLayer,
Culled, Flip, Computed, Cache, LocalTransform, WorldTransform,
WorldBounds, RenderSurface,
Root,
} from '../traits';
-import { getParentNode } from '../queries/hierarchy';
+import { getMaskContainers, getParentNode } from '../queries/hierarchy';
import { getViewMatrix } from '../queries/camera';
import { entityPivot } from '../queries/interaction';
@@ -231,7 +231,7 @@ export function computeGroupBounds(world: World, entity: Entity): void {
let maxY = -Infinity;
let any = false;
- for (const child of world.query(Or(Geometry, Group), ChildOf(entity), Not(Hidden), Not(IsClipPath))) {
+ for (const child of world.query(Or(Geometry, Group), ChildOf(entity), Not(Hidden))) {
const cid = child.id();
const mat: Mat2D = {
a: localStore.a[cid] ?? 1, b: localStore.b[cid] ?? 0,
@@ -332,6 +332,15 @@ function placeSubtree(world: World, entity: Entity, parentEntity: Entity | null,
placeSubtree(world, child, entity, childMode, local);
}
+ // The nodes under a `<clipPath>` or `<mask>` sit in the space of the node
+ // they cut: the container takes its matrix, and they are placed under it.
+ for (const container of getMaskContainers(world, entity)) {
+ holdTransform(world, container, entity);
+ for (const child of world.query(Or(Geometry, Group), ChildOf(container))) {
+ placeSubtree(world, child, container, childMode, local);
+ }
+ }
+
if (group) {
computeGroupBounds(world, entity);
computeWorldBounds(world, entity);
@@ -339,6 +348,28 @@ function placeSubtree(world: World, entity: Entity, parentEntity: Entity | null,
}
}
+/** Gives `container` the world matrix of `holder` and an identity local one. */
+function holdTransform(world: World, container: Entity, holder: Entity): void {
+ const worldStore = store(world, WorldTransform);
+ const localStore = store(world, LocalTransform);
+ const cid = container.id();
+ const hid = holder.id();
+
+ localStore.a[cid] = 1;
+ localStore.b[cid] = 0;
+ localStore.c[cid] = 0;
+ localStore.d[cid] = 1;
+ localStore.e[cid] = 0;
+ localStore.f[cid] = 0;
+
+ worldStore.a[cid] = worldStore.a[hid];
+ worldStore.b[cid] = worldStore.b[hid];
+ worldStore.c[cid] = worldStore.c[hid];
+ worldStore.d[cid] = worldStore.d[hid];
+ worldStore.e[cid] = worldStore.e[hid];
+ worldStore.f[cid] = worldStore.f[hid];
+}
+
/**
* Transform system entry point. Call once per frame before the render system.
*/
diff --git a/packages/runtime/src/traits/node.ts b/packages/runtime/src/traits/node.ts
index fd8ba781..e2ecd8f2 100644
--- a/packages/runtime/src/traits/node.ts
+++ b/packages/runtime/src/traits/node.ts
@@ -30,9 +30,11 @@ export const Audio = trait();
export const AdjustmentLayer = trait();
-// Tag marking an entity as a clip path (`<rect clipPath>`). Clip paths are
-// ChildOf their target; Cache.clipPaths on the target is derived from IsClipPath + ChildOf queries.
-export const IsClipPath = trait();
+// A `<clipPath>`: the node holding it shows only inside the outlines of the
+// shapes under it. ChildOf its target, which files it in Cache.clipPaths; its
+// shapes are ChildOf it and sit in the target's space and time (see
+// `getMaskContainers`).
+export const ClipPath = trait();
// Tag for shadow sub-entities (distinguishes them from other Effect
// sub-entities in ChildOf queries).
diff --git a/packages/runtime/src/traits/relations.ts b/packages/runtime/src/traits/relations.ts
index b01335ed..79668b65 100644
--- a/packages/runtime/src/traits/relations.ts
+++ b/packages/runtime/src/traits/relations.ts
@@ -11,6 +11,6 @@ import { relation } from 'koota';
* exclusive: an entity has at most one parent; re-parenting replaces the
* previous target. autoDestroy 'orphan': destroying a parent destroys its
* whole subtree. Children are distinguished by their type tags (Shadow,
- * Stroke, IsClipPath, ...). Sibling order is encoded via ItemIndex on each child.
+ * Stroke, ClipPath, Mask, ...). Sibling order is encoded via ItemIndex on each child.
*/
export const ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' });
diff --git a/packages/runtime/src/traits/style.ts b/packages/runtime/src/traits/style.ts
index 6d2b8965..b2619c50 100644
--- a/packages/runtime/src/traits/style.ts
+++ b/packages/runtime/src/traits/style.ts
@@ -59,7 +59,10 @@ export const Effect = trait({
value: 0,
});
-// A `<mask>`: limits the effect holding it to where its picture is, ChildOf the effect.
+// A `<mask>`: limits the node or the effect holding it to where its picture
+// is, ChildOf that holder. The picture is a mask file (its AssetId) or the
+// nodes under it, which sit in the holder's space and time (see
+// `getMaskContainers`).
export const Mask = trait({
offset: 0,
inverted: false,
diff --git a/packages/runtime/src/utils/time.ts b/packages/runtime/src/utils/time.ts
index c7981717..913080e3 100644
--- a/packages/runtime/src/utils/time.ts
+++ b/packages/runtime/src/utils/time.ts
@@ -5,7 +5,7 @@
import { CONONICAL_TIME_BASE, PaintType } from '../constants';
import {
Audio, AssetId, Cache, Computed, Geometry, Paint, Trim, Library, FrameRate,
- Delay, IsClipPath, PlaybackRate, SourceFrameRate,
+ Delay, PlaybackRate, SourceFrameRate,
} from '../traits';
import { getParentNode } from '../queries/hierarchy';
import { getSourceDuration } from '../actions/assets';
@@ -171,7 +171,7 @@ export type TimeTrait = typeof Delay | typeof PlaybackRate | typeof SourceFrameR
* koota fires onRemove before it clears the trait, so a removal handler has to
* ask for the length the node will have once it is gone.
*/
-export type Ignorable = TimeTrait | typeof Trim | typeof AssetId | typeof IsClipPath;
+export type Ignorable = TimeTrait | typeof Trim | typeof AssetId;
/**
* Intrinsic duration (in project frames) of the media asset attached to an
diff --git a/packages/runtime/src/world/observers.ts b/packages/runtime/src/world/observers.ts
index 485f7aac..441b3210 100644
--- a/packages/runtime/src/world/observers.ts
+++ b/packages/runtime/src/world/observers.ts
@@ -9,13 +9,13 @@ import {
Delay, Trim, PlaybackRate, SourceFrameRate, Keyframe, ItemIndex,
Position, Offset, Rotation, Scale, UniformScale, Skew, Anchor, Pivot, Flip,
Opacity, Color, Blur, Volume, Effect, CornerRadius, MixedCornerRadius,
- ColorStop, LinearGradient, EllipticalGradient, PathTrim, StrokeStyle, StrokeDash, Size, Computed, Active, Stage, IsClipPath,
+ ColorStop, LinearGradient, EllipticalGradient, PathTrim, StrokeStyle, StrokeDash, Size, Computed, Active, Stage,
ImageDecoderHandle, VideoDecoderHandle,
AudioDecoderHandle, CaptionDecoderHandle, WaveformHandle,
ShaderHostHandle, AudioBusHandle, TextStyle, TextRange,
} from '../traits';
import { getParentEntity } from '../queries/hierarchy';
-import { evictFromCaches, rebuildCaches, refileClipPath } from '../actions/cache';
+import { evictFromCaches, rebuildCaches } from '../actions/cache';
import { syncStagePlayback } from '../actions/playback';
import { disposeDecoders, disconnectAudioBus } from '../media/dispose';
import {
@@ -106,14 +106,6 @@ export function observeWorld(world: World): () => void {
entity.remove(Position, Offset, Rotation, Scale, Skew, Anchor, Pivot, Flip);
}));
- const refile = (clipPath: boolean) => (entity: Entity) => {
- const parent = getParentEntity(entity);
- if (parent === null || !world.has(parent)) return;
- refileClipPath(world, entity, parent, clipPath);
- };
- subs.push(world.onAdd(IsClipPath, refile(true)));
- subs.push(world.onRemove(IsClipPath, refile(false)));
-
// One active entity per world, and only a root.
subs.push(world.onAdd(Active, (entity) => {
for (const other of [...world.query(Active)]) {
diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.ts
index fa008dd1..3dd84929 100644
--- a/packages/runtime/src/world/serialize.ts
+++ b/packages/runtime/src/world/serialize.ts
@@ -4,7 +4,7 @@
import {
ChildOf,
- Geometry, Paint, Group, Scene, Audio, AdjustmentLayer, IsClipPath, Shadow, Stroke,
+ Geometry, Paint, Group, Scene, Audio, AdjustmentLayer, ClipPath, Shadow, Stroke,
Hidden, ClipsContent, Name, Key, AssetId, ItemIndex, MountScript, MountPath,
Caption,
Position, Offset, Rotation, Scale, UniformScale, Anchor, Pivot, Skew, Size, Flip,
@@ -53,7 +53,7 @@ export interface EntityRecord {
colors?: number[];
verticalAlign?: number;
};
- IsClipPath?: {};
+ ClipPath?: {};
Shadow?: {};
Stroke?: {};
Name?: string;
@@ -268,8 +268,8 @@ export function serializeEntity(entity: Entity): EntityRecord {
if (parent !== undefined && !parent.has(Stage)) {
record.ChildOf = parent;
}
- if (entity.has(IsClipPath)) {
- record.IsClipPath = {};
+ if (entity.has(ClipPath)) {
+ record.ClipPath = {};
}
if (entity.has(Position)) {
const position = entity.get(Position)!;
@@ -554,8 +554,8 @@ export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): voi
if (e.Expanded !== undefined) {
entity.add(Expanded);
}
- if (e.IsClipPath !== undefined) {
- entity.add(IsClipPath);
+ if (e.ClipPath !== undefined) {
+ entity.add(ClipPath);
}
if (e.Position !== undefined) {
entity.add(Position);
@@ -749,7 +749,7 @@ export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): voi
entity.set(TextStyle, defined(e.TextStyle));
}
// Attach to parent last so add/change observers see every trait this entity
- // has (KeyframeTrack, Keyframe, Animation, IsClipPath, ...). Otherwise derived
+ // has (KeyframeTrack, Keyframe, Animation, ClipPath, ...). Otherwise derived
// caches stay empty and the UI/motion system can't find them after reload.
if (e.ChildOf !== undefined) {
entity.add(ChildOf(e.ChildOf as Entity));