filmcraft/docs/graphics.md

Graphics

FilmCraft's graphics work like Premiere's Essential Graphics: a graphic clip on a video track holds text and shape layers. Text is set by the text engine in crates/text (README): bundled OFL fonts plus system fonts, OpenType shaping with kerning and ligatures, bidi, line breaking, all drawn as vectors in linear light.

Model

• A graphic clip's project item is an ItemKind::Graphic { width, height, rate }: a transparent canvas the size of the sequence frame, with unlimited duration. These items are internal and do not appear in the Project panel.
• Its layers are effect instances graphic_text / graphic_shape in the clip's effect list, in paint order (first = back). They are hidden from the Effects panel. Because they are effect instances they save with the project, take keyframes on every animatable property (Source Text keyframes hold), appear in Effect Controls and copy with the clip. Standard effects on a graphic clip apply to the composed graphic; Motion and Opacity apply last.
• filmcraft_project::graphic::eval_layer evaluates a layer at a time into a LayerSpec.
• Projects with graphics need no schema migration: everything is additive (new item kind, new effect ids). Builds older than this one refuse such files with a parse error.

Layer properties

Group	Properties (parameter ids)
Text	text (Source Text), font, font_style, size (px), align (Left/Center/Right/Justify), tracking (1/1000 em), kerning, ligatures, leading (px added to the natural line height), baseline_shift, faux_bold, faux_italic, caps (Normal/All Caps/Small Caps), underline, box_width (0 = point text, else area text wrapped at that width)
Shape	shape (Rectangle/Ellipse/Polygon/Path), size [w, h], sides, corner_radius, points (path vertices relative to the layer origin)
Appearance	fill, fill_color; stroke, stroke_color, stroke_width, stroke_type (Outer/Center/Inner) and the same for stroke2; background, background_color, background_opacity, background_size (padding), background_radius; shadow, shadow_color, shadow_opacity, shadow_angle (135° = down-right), shadow_distance, shadow_size, shadow_blur
Transform	position (graphic canvas px), anchor (layer px), scale, scale_width, uniform_scale, rotation, opacity

Point text's origin is its alignment point on the first baseline (the click point of the Type tool); a shape's origin is its centre. Colours are #rrggbb (sRGB).

Rendering

crates/render/src/graphic_clip.rs rasterises each layer straight to the output transform (sequence Motion × layer transform), so text stays sharp at any scale or rotation. Fill coverage comes from the text engine; strokes come from a Euclidean distance transform of that coverage (outer strokes sit under the fill, centre and inner strokes over it); the shadow is the union of all parts, spread by Size, offset and blurred. Each layer's raster is cached while it stays the same. The GPU plan receives one tight image per graphic clip and places it with a translation. The Timecode and Clip Name effects also draw with the text engine.

Commands

Command	Menu / shortcut	Params
graphics.newText	Graphics and Titles ▸ New Layer ▸ Text (⌘T)	text, position, clip (add to this graphic), size, font, fontStyle, seconds (5), track, time
graphics.newShape	Graphics and Titles ▸ New Layer ▸ Shape	shape (rectangle/ellipse/polygon/path), position, size, points, clip
graphics.setText	typing on the monitor	clip, layer, text, merge (coalesce one typing session into one undo step)
graphics.set	Properties panel	clip, layer, props {parameter id or camelCase alias: value; choices by index or name}, time
graphics.selectLayer	layer list / monitor click	clip, layers
graphics.deleteLayer, graphics.arrangeLayer	layer list	clip, layer, to (front/back/forward/backward/index)
graphics.align	Align and Transform	align (left/hcenter/right/top/vcenter/bottom), to (frame/selection), layers
graphics.distribute	Align and Transform	axis (horizontal/vertical), layers (3+)
graphics.list	(query)	clip — layers with names, kinds, text, position and on-canvas quads
fonts.list	(query)	system (scan system font folders, default true) — families and styles

Without clip, commands use the selected graphic clip, else the topmost graphic clip under the playhead. Without layer, they use the selected layer, else the front one. New graphic clips are placed at the playhead on the first video track above the clips there that is free for the duration (a track is added if needed).

Program monitor

Tool	On the Program monitor
Type (T)	Click empty picture: new text layer with a caret. Click a text layer: caret there. Type; ←/→ (⌥ word, ⌘ line), ↑/↓, Home/End, Shift to select, ⌘A, ⌘C/⌘X/⌘V, Return = new line, Backspace/Delete, Esc = stop editing. Drag inside the edited text to select.
Selection (V)	Click a layer to select it (box with handles and anchor point); drag to move; drag a corner handle to scale; double-click a text layer to edit it.
Rectangle / Ellipse	Drag to draw a shape layer.
Pen (P)	Click to place points; click the first point (or Return) to close the path; Esc cancels.

Automation ids: program.layer.<clip>.<layer>, program.layer.<clip>.<layer>.handle.<n>, program.textEdit (while editing).

Properties / Essential Graphics panels

With a graphic clip selected, the Properties panel (and Essential Graphics) shows: Layers (front first; new text / rectangle / ellipse, bring forward / send backward, delete, visibility), Align and Transform (six align buttons, two distribute buttons, position, anchor, scale, rotation, opacity), Text (Source Text field, font family and style, size, paragraph alignment, tracking, leading, baseline shift, box width, faux bold / faux italic / all caps / small caps / underline, kerning and ligatures), Shape, and Appearance (fill, two strokes, background, shadow). Automation ids: graphics.layers.<n>, graphics.prop.<parameter id>, graphics.align.<how>, graphics.distribute.<axis>, graphics.sourceText, graphics.NewTextLayer, graphics.NewRectangle, graphics.NewEllipse, graphics.deleteLayer, graphics.section.<name>.

Not yet

Per-character styling inside one text layer, responsive design pins and rolls/crawls (M10.3), motion graphics templates, the Browse tab, mask-with-text, gradient fills, per-layer blend modes, and Bézier curves in the pen tool (paths are polygons).