vgpu-render 0.0.0-stage → 0.2.0

package/dist/frame-draw-list.d.ts

@@ -0,0 +1,413 @@
+import { type Curve3D, type CurveTransform } from "./curve.js";
+import { FrameDrawList2D, type FrameCommand2D } from "./frame-draw-list-2d.js";
+import { type TextAnchor, type TextFontStyle, type TextFontWidth, type TextJustify, type TextLineBreak } from "./text-layout.js";
+export type Vec3 = readonly [number, number, number];
+export type Color = readonly [number, number, number, number];
+export type LayerMask = number;
+export type PointOptions = {
+    color?: Color;
+    size?: number;
+    sizeMode?: "screen" | "world";
+    round?: boolean;
+    layer?: LayerMask;
+};
+export type LineJoint = "none" | "round" | "bevel" | "miter";
+/** Joint kinds the reference renders as geometry (`_is_rendered_line_joint`). */
+export type RenderedJoint = Exclude<LineJoint, "none">;
+export type LineOptions = {
+    color?: Color;
+    colorEnd?: Color;
+    width?: number;
+    widthMode?: "screen" | "world";
+    dash?: readonly [number, number, number];
+    normal?: Vec3;
+    /**
+     * Per-vertex normals for path primitives (reference `*_n` variants). Every segment uses
+     * the normal of its **start** vertex, matching `_emit_normal_line_strip` /
+     * `_emit_normal_line_loop`, and the joints between them interpolate the two normals. A
+     * closed path needs one entry per vertex, an open one per segment (as the reference
+     * accepts). Takes precedence over `normal` when both are given.
+     */
+    normals?: readonly Vec3[];
+    joint?: LineJoint;
+    layer?: LayerMask;
+};
+export type PointCommand = {
+    readonly kind: "point";
+    readonly position: Vec3;
+    readonly color: Color;
+    readonly size: number;
+    readonly sizeMode: "screen" | "world";
+    readonly round?: boolean;
+    readonly layer: LayerMask;
+};
+export type LineCommand = {
+    readonly kind: "line";
+    readonly start: Vec3;
+    readonly end: Vec3;
+    readonly color: Color;
+    readonly colorEnd: Color;
+    readonly width: number;
+    readonly widthMode: "screen" | "world";
+    readonly dash?: readonly [number, number, number];
+    readonly normal?: Vec3;
+    readonly joint?: LineJoint;
+    readonly layer: LayerMask;
+};
+/**
+ * One path vertex of a `lineStrip`/`lineLoop` that the reference turns into a joint
+ * instance (`_emit_joint`). The renderer rebuilds the round/bevel/miter wedge on the GPU
+ * from `previous`, `center`, and `next`, so no CPU-side expansion happens here.
+ */
+export type JointCommand = {
+    readonly kind: "joint";
+    readonly previous: Vec3;
+    readonly center: Vec3;
+    readonly next: Vec3;
+    readonly color: Color;
+    readonly width: number;
+    readonly widthMode: "screen" | "world";
+    /**
+     * Same `[visible, space, offset]` shape as `LineCommand.dash`, with the accumulated
+     * path distance of this vertex already folded into `offset` so the wedge keeps the
+     * dash phase of the segments that meet it.
+     */
+    readonly dash?: readonly [number, number, number];
+    /**
+     * Normal of the previous path vertex and of this one, mirroring
+     * `_emit_normal_joint(previous, center, next, previous_normal, next_normal, ...)`.
+     * The wedge interpolates between them so a normal-aware joint keeps the shading of the
+     * segments it joins. Both are absent for plain joints.
+     */
+    readonly previousNormal?: Vec3;
+    readonly nextNormal?: Vec3;
+    readonly joint: RenderedJoint;
+    readonly layer: LayerMask;
+};
+export type ArrowOptions = LineOptions & {
+    headLength?: number;
+    headAngle?: number;
+};
+export type FrameCommand = PointCommand | LineCommand | JointCommand | TriangleCommand | TextCommand | FrameCommand2D;
+export type TriangleCommand = {
+    readonly kind: "triangle";
+    readonly a: Vec3;
+    readonly b: Vec3;
+    readonly c: Vec3;
+    readonly color: Color;
+    readonly layer: LayerMask;
+};
+/**
+ * Where a text block is placed, mirroring reference split between world-space `Text2d` and the
+ * screen-space UI `Text`:
+ *
+ * - `world-plane` puts the block on a fixed local XY plane at a world position, so it
+ *   foreshortens with the camera like the reference `Label3D`.
+ * - `world-billboard` keeps that plane facing the camera at all times.
+ * - `screen` places the block at a **top-left origin pixel position** (`position.z` is
+ *   ignored) at a fixed pixel size, independent of projection and depth.
+ */
+export type TextSpace = "world-plane" | "world-billboard" | "screen";
+/** One section of a text block, the equivalent of a reference `TextSpan`. */
+export type TextSpanOptions = {
+    readonly text: string;
+    readonly color?: Color;
+    readonly fontSize?: number;
+    readonly fontFamily?: string;
+    /** reference `TextFont::weight`, 1 to 1000. Defaults to the block's, then to 400. */
+    readonly weight?: number;
+    /** reference `TextFont::style`, minus `Oblique`: Canvas2D drops the slant angle. */
+    readonly style?: TextFontStyle;
+    /** reference `TextFont::width`, as a `font-stretch` keyword. Inert unless the face has a `wdth` axis. */
+    readonly width?: TextFontWidth;
+};
+export type TextOptions = {
+    color?: Color;
+    /**
+     * Outline width in font pixels, drawn around every glyph in the block. `0` (the default) draws no
+     * outline. Font pixels rather than screen pixels keeps the outline proportional to the glyphs:
+     * a block scaled up by `pixelSize` carries its outline with it, and a `screen` block's outline is
+     * in screen pixels, since there is nothing between those two units.
+     */
+    outlineWidth?: number;
+    /**
+     * Outline colour, its alpha giving how opaque the ring is. Defaults to the block's own colour,
+     * which widens the glyphs rather than ringing them; give it a contrasting colour to make a block
+     * readable against whatever it is drawn over.
+     */
+    outlineColor?: Color;
+    /**
+     * Block font size in pixels. It is both the layout unit and the glyph atlas' rasterisation
+     * size, exactly as in the reference `Label3D.font_size`; the two world spaces scale it by
+     * `pixelSize`, and `screen` uses it directly.
+     */
+    fontSize?: number;
+    /**
+     * World units per font pixel in the two world spaces, the reference `Label3D.pixel_size`.
+     * Ignored by `screen`, which is already in pixels. Raise `fontSize` and lower this together
+     * to keep a block's world size while gaining rasterisation detail.
+     */
+    pixelSize?: number;
+    fontFamily?: string;
+    /**
+     * reference `TextFont::weight`, 1 to 1000, default `400`. A face that does not carry the weight is
+     * emboldened by the browser in one synthesised step, so the advance does not change.
+     */
+    weight?: number;
+    /**
+     * reference `TextFont::style`. `italic` is the only slant Canvas2D honours: its shorthand drops the
+     * angle of `Oblique(a)`, so a synthesised slant is all an oblique could mean here.
+     */
+    style?: TextFontStyle;
+    /**
+     * reference `TextFont::width`, spelled as a `font-stretch` keyword. Canvas2D keeps the keyword only when
+     * the face has a `wdth` axis; the bundled static subset has none, so every stop draws identically.
+     */
+    width?: TextFontWidth;
+    /**
+     * Absolute line height in pixels, reference `LineHeight::Px`. Exclusive with `lineHeightScale`;
+     * omitting both leaves the line height at reference default, `RelativeToFont(1.2)`.
+     */
+    lineHeight?: number;
+    /**
+     * Line height as a multiple of the line's own largest span, reference `LineHeight::RelativeToFont`.
+     * Exclusive with `lineHeight`.
+     */
+    lineHeightScale?: number;
+    letterSpacing?: number;
+    justify?: TextJustify;
+    lineBreak?: TextLineBreak;
+    /**
+     * `TextBounds`. Only `width` feeds layout: it is the wrap width. `height` is deliberately not a
+     * layout input, matching reference, whose `Text2d` never truncates against it — a block that runs
+     * past the height still draws every line.
+     */
+    bounds?: readonly [number, number];
+    anchor?: TextAnchor;
+    space?: TextSpace;
+    /**
+     * Local rotation of a `world-plane` block, in radians, as reference `Label3D.rotation` Euler angles
+     * (applied Y, then X, then Z). The reference `Label3D` labels use `[-PI/2, 0, 0]` to lay the block
+     * flat on the XZ plane, readable from above; the two camera-relative spaces ignore it.
+     */
+    rotation?: readonly [number, number, number];
+    /**
+     * Which registered glyph source draws this block: its encoding and raster scale. Blocks that name
+     * nothing use the first source, so a frame can mix a sharp pass and a cheap pass.
+     */
+    source?: string;
+    /** Whether geometry in front of the block occludes it. Defaults to `true`, like reference `Text2d`. */
+    depthTest?: boolean;
+    layer?: LayerMask;
+};
+/** A span after the block defaults have been folded in, so the renderer never re-resolves them. */
+export type ResolvedTextSpan = {
+    readonly text: string;
+    readonly color: Color;
+    readonly fontSize: number;
+    readonly fontFamily: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
+};
+export type TextCommand = {
+    readonly kind: "text";
+    readonly position: Vec3;
+    readonly spans: readonly ResolvedTextSpan[];
+    readonly color: Color;
+    readonly outlineWidth: number;
+    readonly outlineColor: Color;
+    readonly fontSize: number;
+    readonly pixelSize: number;
+    readonly fontFamily: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
+    /**
+     * Resolved line height in pixels: the value a `LineHeight::Px` block asked for, or
+     * `1.2 × fontSize` for the default, which `lineHeightScale` then marks as resolved per line.
+     * Only block measurements read this; layout uses whichever of the two fields applies.
+     */
+    readonly lineHeight: number;
+    /**
+     * `LineHeight::RelativeToFont` multiple, present only when the block left the line height at
+     * the default. Layout then resolves each line against that line's own largest span.
+     */
+    readonly lineHeightScale?: number;
+    readonly letterSpacing: number;
+    readonly justify: TextJustify;
+    readonly lineBreak: TextLineBreak;
+    readonly bounds?: readonly [number, number];
+    readonly anchor: TextAnchor;
+    readonly space: TextSpace;
+    readonly rotation: readonly [number, number, number];
+    readonly source?: string;
+    readonly depthTest: boolean;
+    readonly layer: LayerMask;
+};
+export type MeshOptions = {
+    color?: Color;
+    solid?: boolean;
+    layer?: LayerMask;
+};
+export type CurveOptions = LineOptions & {
+    tolerance?: number;
+    transform?: CurveTransform;
+};
+export type GridOptions = LineOptions & {
+    rotation?: readonly [number, number, number];
+    skew?: readonly [number, number];
+    outer?: "none" | "x" | "z" | "xz";
+};
+export type PointDefaults = {
+    color?: Color;
+    size?: number;
+    sizeMode?: "screen" | "world";
+    layer?: LayerMask;
+};
+export type LineDefaults = {
+    color?: Color;
+    colorEnd?: Color;
+    width?: number;
+    widthMode?: "screen" | "world";
+    dash?: readonly [number, number, number];
+    normal?: Vec3;
+    joint?: LineJoint;
+    layer?: LayerMask;
+};
+export type TextDefaults = {
+    color?: Color;
+    outlineWidth?: number;
+    outlineColor?: Color;
+    fontSize?: number;
+    pixelSize?: number;
+    fontFamily?: string;
+    /** Default reference `TextFont::weight`, 1 to 1000. */
+    weight?: number;
+    /** Default reference `TextFont::style`. */
+    style?: TextFontStyle;
+    /** Default reference `TextFont::width`, as a `font-stretch` keyword. */
+    width?: TextFontWidth;
+    /**
+     * Absolute line height in pixels, reference `LineHeight::Px`. Omitted means reference default,
+     * `RelativeToFont(1.2)`: every line is 1.2 times its own largest span, so a line holding a
+     * larger span gets a taller box.
+     */
+    lineHeight?: number;
+    /** Line height as a multiple of the line's largest span, reference `LineHeight::RelativeToFont`. */
+    lineHeightScale?: number;
+    letterSpacing?: number;
+    justify?: TextJustify;
+    lineBreak?: TextLineBreak;
+    anchor?: TextAnchor;
+    space?: TextSpace;
+    rotation?: readonly [number, number, number];
+    source?: string;
+    depthTest?: boolean;
+    layer?: LayerMask;
+};
+export type FrameDrawListDefaults = {
+    point?: PointDefaults;
+    line?: LineDefaults;
+    text?: TextDefaults;
+};
+export declare const DEFAULT_COLOR: Color;
+export declare const DEFAULT_LAYER = 1;
+/** Default block font size in pixels; the world spaces scale it by `DEFAULT_TEXT_PIXEL_SIZE`. */
+export declare const DEFAULT_TEXT_SIZE = 16;
+/** Default world units per font pixel, i.e. a 0.32 world-unit glyph at the default size. */
+export declare const DEFAULT_TEXT_PIXEL_SIZE = 0.02;
+/** `world-plane` blocks face +Z until a rotation lays them down, like a reference `Label3D`. */
+export declare const DEFAULT_TEXT_ROTATION: readonly [number, number, number];
+/** reference `LineHeight` default is `RelativeToFont(1.2)`. */
+export declare const DEFAULT_LINE_HEIGHT_RATIO = 1.2;
+export type ResolvedPointDefaults = {
+    color: Color | undefined;
+    size: number | undefined;
+    sizeMode: "screen" | "world" | undefined;
+    layer: LayerMask | undefined;
+};
+export type ResolvedLineDefaults = {
+    color: Color | undefined;
+    colorEnd: Color | undefined;
+    width: number | undefined;
+    widthMode: "screen" | "world" | undefined;
+    dash: readonly [number, number, number] | undefined;
+    normal: Vec3 | undefined;
+    joint: LineJoint | undefined;
+    layer: LayerMask | undefined;
+};
+export type ResolvedTextDefaults = {
+    color: Color | undefined;
+    outlineWidth: number | undefined;
+    outlineColor: Color | undefined;
+    fontSize: number | undefined;
+    pixelSize: number | undefined;
+    fontFamily: string | undefined;
+    weight: number | undefined;
+    style: TextFontStyle | undefined;
+    width: TextFontWidth | undefined;
+    lineHeight: number | undefined;
+    lineHeightScale: number | undefined;
+    letterSpacing: number | undefined;
+    justify: TextJustify | undefined;
+    lineBreak: TextLineBreak | undefined;
+    anchor: TextAnchor | undefined;
+    space: TextSpace | undefined;
+    rotation: readonly [number, number, number] | undefined;
+    source: string | undefined;
+    depthTest: boolean | undefined;
+    layer: LayerMask | undefined;
+};
+export type ResolvedFrameDrawListDefaults = {
+    point: ResolvedPointDefaults;
+    line: ResolvedLineDefaults;
+    text: ResolvedTextDefaults;
+};
+/** Validates and resolves style defaults so invalid values fail at construction time. */
+export declare function resolveFrameDrawListDefaults(defaults?: FrameDrawListDefaults): ResolvedFrameDrawListDefaults;
+/**
+ * One frame's draw list: records primitives, then hands them to `GpuDebugDraw3D` as
+ * `FrameCommand[]`. This is the `ImDrawList` / `GizmoBuffer` layer; GPU command encoding
+ * happens later in the renderer.
+ */
+export declare class FrameDrawList {
+    #private;
+    constructor(defaults?: FrameDrawListDefaults);
+    /**
+     * The 2D layer: `Vec2` primitives on the reference-style `Camera2d` spaces described in
+     * `camera-2d.ts`. Drawing here records into the same frame and layer mask as the 3D methods.
+     */
+    get d2(): FrameDrawList2D;
+    point(position: Vec3, options?: PointOptions): this;
+    line(start: Vec3, end: Vec3, options?: LineOptions): this;
+    ray(origin: Vec3, direction: Vec3, options?: LineOptions): this;
+    arrow(origin: Vec3, direction: Vec3, options?: ArrowOptions): this;
+    axes(origin: Vec3, length?: number, width?: number): this;
+    lineStrip(points: readonly Vec3[], options?: LineOptions, closed?: boolean): this;
+    polyline(points: readonly Vec3[], options?: LineOptions, closed?: boolean): this;
+    triangle(a: Vec3, b: Vec3, c: Vec3, options?: {
+        color?: Color;
+        layer?: LayerMask;
+    }): this;
+    mesh(mesh: {
+        readonly triangles: readonly (readonly [Vec3, Vec3, Vec3])[];
+        readonly segments: readonly (readonly [Vec3, Vec3])[];
+    }, options?: MeshOptions): this;
+    curve(curve: Curve3D, options?: CurveOptions): this;
+    grid(center: Vec3, cells: readonly [number, number], spacing: readonly [number, number], options?: GridOptions): this;
+    /**
+     * Records one text block. `text` is either the block's string or a list of spans, mirroring
+     * reference `Text2d`/`Text` root plus its child `TextSpan`s; a span's own style overrides the
+     * block default. Layout happens at draw time, because only the renderer knows where the
+     * glyph atlas placed each character.
+     */
+    text(position: Vec3, text: string | readonly TextSpanOptions[], options?: TextOptions): this;
+    get points(): readonly PointCommand[];
+    get lines(): readonly LineCommand[];
+    get joints(): readonly JointCommand[];
+    get texts(): readonly TextCommand[];
+    commands(visibleLayers?: LayerMask): readonly FrameCommand[];
+    seal(): void;
+    private assertOpen;
+}