Skip to content

Code-first video & image, rendered natively on WebGPU.

5.6 KB
Raw Blame
/**
 * The host: what framefields injects into components. framefields bundles
 * this package, so components can't import from it without a cycle; instead
 * framefields binds each component to an object implementing `Host`.
 *
 * Types here are structural on purpose: framefields' real `AnimatableNode`
 * satisfies `Animatable`, and its binding restores the full types for users.
 */
import type {
	BoxNode,
	FlexNode,
	LayoutNode,
	ShapeNode,
	ShapeType,
	TextNode,
} from "@framefields/compositions/program";
import type { MeasureFn } from "./text.js";

/** Photoshop-style layer styles (framefields' `LayerStyle`). Omitted styles are off. */
export interface LayerStyleConfig {
	dropShadow?: {
		color?: string;
		opacity?: number;
		/** Light angle in degrees (90 = shadow straight down). */
		angle?: number;
		distance?: number;
		spread?: number;
		size?: number;
		blendMode?: string;
	};
	outerGlow?: {
		color?: string;
		opacity?: number;
		size?: number;
		spread?: number;
		blendMode?: string;
	};
	innerShadow?: {
		color?: string;
		opacity?: number;
		/** Degrees, as for drop shadows: 90 shades the bottom inside edge, 270 the top. */
		angle?: number;
		distance?: number;
		size?: number;
		choke?: number;
		/** Default `"multiply"` (a light color then does nothing: use `"normal"` or `"screen"`). */
		blendMode?: string;
	};
	stroke?: {
		size?: number;
		position?: "inside" | "center" | "outside";
		color?: string;
		opacity?: number;
	};
}

export interface MediaOptions {
	id?: string;
	position?: "absolute" | "relative";
	x?: number;
	y?: number;
	width?: number;
	height?: number;
	fit?: "cover" | "contain" | "fill";
}

/** The part of framefields' `AnimatableNode` components rely on. */
export interface AnimatableMethods {
	animate(...anims: unknown[]): unknown;
}

export type Animatable<T> = T & AnimatableMethods;

export interface Host {
	box(options: Partial<BoxNode>): Animatable<BoxNode>;
	flex(options: Partial<FlexNode>): Animatable<FlexNode>;
	text(content: string, options?: Partial<TextNode>): Animatable<TextNode>;
	shape(type: ShapeType, options?: Partial<ShapeNode>): Animatable<ShapeNode>;
	/** `FontManager.measure`. */
	measure: MeasureFn;
	/** Registered font families. */
	fonts(): readonly string[];
	/** A default id: stable per run (a counter per prefix), like `Layer.*` ids. */
	autoId(prefix: string): string;
	/** A video, image or SVG layer, by file extension. */
	media(source: string, options: MediaOptions): Animatable<LayoutNode>;
	/** Attach layer styles (shadow, glow, stroke) to `node`; returns it. */
	style<T extends Animatable<LayoutNode>>(node: T, config: LayerStyleConfig): T;
	/**
	 * Mask `node` by `matte`'s alpha (a box: solid or CSS-gradient
	 * background), or by its inverse (`"alpha-inverted"`: show `node`
	 * everywhere the matte is not). The matte is laid out like a sibling of
	 * `node`; returns `node`.
	 */
	matte<T extends Animatable<LayoutNode>>(
		node: T,
		matte: LayoutNode,
		mode?: "alpha" | "alpha-inverted",
	): T;
	/**
	 * A video showing only its person / subject (vision segmentation), the
	 * rest transparent: stacked over captions so text passes behind them.
	 */
	cutout(source: string, options: CutoutOptions): Animatable<LayoutNode>;
	/** A GPU particle system layer. */
	particles(options: ParticleOptions): Animatable<LayoutNode>;
	/**
	 * A per-frame signal from values (framefields' `Signal.fromArray`), for
	 * `LayerAnimation.signal`. Signals read the composition's frame: value
	 * `k` drives composition frame `k`.
	 */
	signal(values: readonly number[], fps: number): object;
	/**
	 * An animated film-grain layer to put over other layers: neutral grey
	 * carrying framefields' `FilmGrain`, soft-light blended. (Effects only
	 * attach to media layers, so grain can't go on a box.)
	 */
	grain(options: GrainOptions): Animatable<LayoutNode>;
	/** Solid extruded 3D text (framefields' `Layer3D.extrudedText`), centred on x, y. */
	extrudedText(options: ExtrudedTextOptions): Animatable<LayoutNode>;
}

export interface GrainOptions {
	id?: string;
	x: number;
	y: number;
	width: number;
	height: number;
	/** 0–100, the engine's scale. */
	strength: number;
	size?: number;
}

export interface ExtrudedTextOptions {
	id?: string;
	text: string;
	/** Centre of the text. */
	x: number;
	y: number;
	depth: number;
	fontFamily?: string;
	fontSize: number;
	fontWeight?: number;
	fill?: string;
	bevelColor?: string;
	material?: "lit" | "glass";
	metallic?: number;
	roughness?: number;
	shininess?: number;
	opacity?: number;
}

/** A GPU particle system (framefields' `Layer.particles`), as plain data. */
export interface ParticleOptions {
	id?: string;
	x: number;
	y: number;
	width: number;
	height: number;
	seed?: number;
	/** Most particles alive at once. */
	max?: number;
	emitter: {
		shape: "point";
		x: number;
		y: number;
		/** Particles a second (0 for bursts only). */
		rate: number;
		bursts: Array<{ frame: number; count: number }>;
	};
	/** Seconds each particle lives. */
	lifetime?: [number, number];
	/** Launch speed, px/s. */
	speed?: [number, number];
	/** Degrees, 0 = right, -90 = up. */
	direction?: number;
	spread?: number;
	/** px/s², down. */
	gravity?: number;
	drag?: number;
	noise?: { strength: number; scale: number; speed: number };
	/** A floor line (layer px) particles bounce on and settle. */
	floor?: number;
	bounce?: number;
	/** px at birth → death. */
	size?: [number, number];
	sizeJitter?: number;
	fade?: [number, number];
	shape?: "circle" | "soft" | "square" | "spark";
	stretch?: number;
	blend?: "normal" | "add" | "screen";
	color?: string | string[];
	opacity?: number;
}

export interface CutoutOptions extends MediaOptions {
	mode?: "person" | "subject";
}