vgpu-render 0.1.0 → 0.3.0

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

@@ -0,0 +1,286 @@
+/**
+ * 2D debug-draw commands and their drawList.
+ *
+ * The 2D layer is the same data flow as the 3D one — `FrameDrawList -> FrameCommand[] -> GPU` —
+ * reached through `frame.d2` instead of a second entry point, so a frame has one lifecycle, one
+ * layer mask and one set of defaults. The commands are separate types rather than 3D commands
+ * with a `space` flag because a 2D point is a `Vec2` and 2D strokes carry no surface normal;
+ * keeping them apart stops a 3D-only field from silently meaning something different here.
+ *
+ * See `camera-2d.ts` for what `world2d` and `screen` mean.
+ */
+import type { Space2D, Vec2 } from "./camera-2d.js";
+import { type Curve2D, type CurveTransform2D } from "./curve.js";
+import type { Color, LayerMask, LineJoint, RenderedJoint, ResolvedLineDefaults, ResolvedPointDefaults } from "./frame-draw-list.js";
+export type Line2DOptions = {
+    color?: Color;
+    colorEnd?: Color;
+    /** Stroke width in canvas pixels (`widthMode: "screen"`) or world2d units. */
+    width?: number;
+    widthMode?: "screen" | "world";
+    joint?: LineJoint;
+    /** Defaults to `world2d`; see `camera-2d.ts`. */
+    space?: Space2D;
+    layer?: LayerMask;
+};
+/** `arrow` options: the line style plus the head size and half-angle. */
+export type Arrow2DOptions = Line2DOptions & {
+    /** Head length in `world2d` units; defaults to a quarter of the shaft, clamped to 6..14. */
+    headLength?: number;
+    /** Half-angle of the head in radians; defaults to 30 degrees. */
+    headAngle?: number;
+};
+/** `curve` options: the line style plus sampling tolerance and placement. */
+export type Curve2DOptions = Line2DOptions & {
+    /** Approximate segment length in `world2d` units; smaller values subdivide each cubic further. */
+    readonly tolerance?: number;
+    readonly transform?: CurveTransform2D;
+};
+/** `grid` options: the 3D grid parameters in the XY plane, plus the line style. */
+export type Grid2DOptions = Line2DOptions & {
+    /** Anticlockwise rotation around the grid centre, in radians. */
+    rotation?: number;
+    /** Skew angles whose tangents shift the opposite family of lines. */
+    skew?: readonly [number, number];
+    /** Keep the x-axis or y-axis boundary lines (the 2D counterpart of 3D's x/z edges). */
+    outer?: "none" | "x" | "y" | "xy";
+};
+export type Point2DOptions = {
+    color?: Color;
+    size?: number;
+    sizeMode?: "screen" | "world";
+    round?: boolean;
+    space?: Space2D;
+    layer?: LayerMask;
+};
+/** Every filled/stroked 2D shape the layer can draw. */
+export type Shape2DKind = "rect" | "rounded-rect" | "circle" | "ellipse" | "arc" | "annulus" | "capsule" | "polygon" | "triangle" | "rhombus" | "sector" | "segment";
+export type Shape2DOptions = {
+    color?: Color;
+    /** Rotation in radians, anticlockwise in `world2d` and screen-clockwise in `screen`. */
+    rotation?: number;
+    /** Outline width in canvas pixels; the `<shape>` and `<shape>_d` variants read it. */
+    strokeWidth?: number;
+    /** Start angle of `arc`/`sector`/`segment` in radians. Defaults to `0`, the +x axis. */
+    startAngle?: number;
+    /** Sweep of `arc`/`sector`/`segment` in radians. Defaults to a full turn; negative turns the other way. */
+    sweep?: number;
+    space?: Space2D;
+    layer?: LayerMask;
+};
+export type Shape2DCommand = {
+    readonly kind: "shape2d";
+    readonly shape: Shape2DKind;
+    readonly center: Vec2;
+    /**
+     * Primary half-size, meaning depends on `shape`: box half extents, ellipse radii, circumradius,
+     * capsule `[radius, halfLength]`, annulus `[outer, inner]`, rhombus half diagonals, or a
+     * triangle's first vertex offset from the centroid.
+     */
+    readonly size: Vec2;
+    /** Second/third triangle vertices relative to the centroid; zero for every other shape. */
+    readonly vertexB: Vec2;
+    readonly vertexC: Vec2;
+    readonly cornerRadius: number;
+    /** Outline width in canvas pixels. */
+    readonly thickness: number;
+    readonly filled: boolean;
+    /**
+     * Dashed-outline pattern `[visible, gap, phase]` in shape-space units for the `_d` variants;
+     * absent for solid shapes and solid outlines.
+     */
+    readonly dash?: readonly [number, number, number];
+    readonly rotation: number;
+    readonly startAngle: number;
+    readonly sweep: number;
+    /** Vertex count of `polygon`; zero for every other shape. */
+    readonly sides: number;
+    readonly color: Color;
+    readonly space: Space2D;
+    readonly layer: LayerMask;
+};
+export type Point2DCommand = {
+    readonly kind: "point2d";
+    readonly position: Vec2;
+    readonly color: Color;
+    readonly size: number;
+    readonly sizeMode: "screen" | "world";
+    readonly round?: boolean;
+    readonly space: Space2D;
+    readonly layer: LayerMask;
+};
+export type Line2DCommand = {
+    readonly kind: "line2d";
+    readonly start: Vec2;
+    readonly end: Vec2;
+    readonly color: Color;
+    readonly colorEnd: Color;
+    readonly width: number;
+    readonly widthMode: "screen" | "world";
+    readonly dash?: readonly [number, number, number];
+    readonly joint?: LineJoint;
+    readonly space: Space2D;
+    readonly layer: LayerMask;
+};
+/**
+ * One path vertex of a `lineStrip`/`polyline`, the 2D twin of `JointCommand`. The renderer
+ * rebuilds the round/bevel/miter wedge from `previous`, `center` and `next`, exactly as the 3D
+ * joint pipeline does.
+ */
+export type Joint2DCommand = {
+    readonly kind: "joint2d";
+    readonly previous: Vec2;
+    readonly center: Vec2;
+    readonly next: Vec2;
+    readonly color: Color;
+    readonly width: number;
+    readonly widthMode: "screen" | "world";
+    readonly dash?: readonly [number, number, number];
+    readonly joint: RenderedJoint;
+    readonly space: Space2D;
+    readonly layer: LayerMask;
+};
+/** Everything a `FrameDrawList2D` can emit. */
+export type FrameCommand2D = Point2DCommand | Line2DCommand | Joint2DCommand | Shape2DCommand;
+/** The 3D drawList's resolved point/line styles, reused so 2D and 3D defaults cannot drift. */
+export type FrameDrawList2DStyleDefaults = {
+    readonly point: ResolvedPointDefaults;
+    readonly line: ResolvedLineDefaults;
+};
+/**
+ * Records 2D primitives for one frame. Obtained through `FrameDrawList.d2`; it seals with its
+ * parent, so a caller cannot keep drawing into a finished frame.
+ */
+export declare class FrameDrawList2D {
+    #private;
+    constructor(defaults: FrameDrawList2DStyleDefaults, assertOpen: () => void);
+    point(position: Vec2, options?: Point2DOptions): this;
+    /** Straight segment (the 3D `draw_line`). */
+    line(start: Vec2, end: Vec2, options?: Line2DOptions): this;
+    /** Straight segment dashed along its length (the 3D `draw_line_d`). */
+    line_d(start: Vec2, end: Vec2, dash: readonly [number, number, number], options?: Line2DOptions): this;
+    /**
+     * Arrow with an open V head, the 2D twin of `FrameDrawList.arrow`: the shaft runs to `origin +
+     * direction`, and the head is two lines back from the tip.
+     */
+    arrow(origin: Vec2, direction: Vec2, options?: Arrow2DOptions): this;
+    /** Arrow with a filled triangular head (`arrow` keeps the open line head). */
+    arrow_s(origin: Vec2, direction: Vec2, options?: Arrow2DOptions): this;
+    /** Arrow whose shaft is dashed; the two head lines stay solid like the filled head. */
+    arrow_d(origin: Vec2, direction: Vec2, dash: readonly [number, number, number], options?: Arrow2DOptions): this;
+    /** Arrow with a filled head and a dashed shaft. */
+    arrow_s_d(origin: Vec2, direction: Vec2, dash: readonly [number, number, number], options?: Arrow2DOptions): this;
+    ray(origin: Vec2, direction: Vec2, options?: Line2DOptions): this;
+    /** Ray dashed along its length. */
+    ray_d(origin: Vec2, direction: Vec2, dash: readonly [number, number, number], options?: Line2DOptions): this;
+    /**
+     * Path of segments, the 2D twin of `FrameDrawList.lineStrip`. Dash distance accumulates over
+     * the whole path and an open strip joins only its interior vertices, matching the 3D layer.
+     */
+    lineStrip(points: readonly Vec2[], options?: Line2DOptions, closed?: boolean): this;
+    /** Open strip dashed along its length. */
+    lineStrip_d(points: readonly Vec2[], dash: readonly [number, number, number], options?: Line2DOptions, closed?: boolean): this;
+    /** Closed strip: the last point joins the first (the 3D `draw_line_loop`). */
+    lineLoop(points: readonly Vec2[], options?: Line2DOptions): this;
+    /** Closed strip dashed along its length. */
+    lineLoop_d(points: readonly Vec2[], dash: readonly [number, number, number], options?: Line2DOptions): this;
+    polyline(points: readonly Vec2[], options?: Line2DOptions, closed?: boolean): this;
+    polyline_d(points: readonly Vec2[], dash: readonly [number, number, number], options?: Line2DOptions, closed?: boolean): this;
+    /**
+     * Cubic curve sampled into a polyline, the 2D twin of `FrameDrawList.curve`. The curve's own
+     * `closed` flag decides whether the last point joins the first.
+     */
+    curve(curve: Curve2D, options?: Curve2DOptions): this;
+    /** Cubic curve sampled into a dashed polyline. */
+    curve_d(curve: Curve2D, dash: readonly [number, number, number], options?: Curve2DOptions): this;
+    /**
+     * Axis-aligned grid of lines, the 2D twin of `FrameDrawList.grid` and reference `grid_2d`: `cells`
+     * are the cells per axis, so the drawn line count is one more on each side.
+     */
+    grid(center: Vec2, cells: readonly [number, number], spacing: Vec2, options?: Grid2DOptions): this;
+    /** Grid whose lines are dashed along their length. */
+    grid_d(center: Vec2, cells: readonly [number, number], spacing: Vec2, dash: readonly [number, number, number], options?: Grid2DOptions): this;
+    /**
+     * Rectangle with the given full width and height, stroked by default like the 3D `draw_rect`.
+     * `rect_s` fills it and `rect_d` dashes the outline.
+     */
+    rect(center: Vec2, size: Vec2, options?: Shape2DOptions): this;
+    /** Solid rectangle (reference `Rectangle`, the 3D `draw_rect_s`). */
+    rect_s(center: Vec2, size: Vec2, options?: Shape2DOptions): this;
+    /**
+     * Rectangle outline dashed along its perimeter (the 3D `draw_rect_d`). `dash` is
+     * `[visible, gap, phase]` in shape-space units, the same triple the line layer takes.
+     */
+    rect_d(center: Vec2, size: Vec2, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Rounded rectangle outline; the shader clamps the radius to half the shorter side. */
+    rect_r(center: Vec2, size: Vec2, cornerRadius: number, options?: Shape2DOptions): this;
+    /** Solid rounded rectangle (reference `RoundedRectangle`, the 3D `_s` counterpart). */
+    rect_r_s(center: Vec2, size: Vec2, cornerRadius: number, options?: Shape2DOptions): this;
+    /** Rounded rectangle outline dashed along its perimeter. */
+    rect_r_d(center: Vec2, size: Vec2, cornerRadius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Disc outline with the given radius (reference `Circle`, the 3D `draw_circle`). */
+    circle(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Solid disc (reference `Circle::new`, the 3D `draw_circle_s`). */
+    circle_s(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Dashed circle outline. */
+    circle_d(center: Vec2, radius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Ellipse outline with independent x and y radii (reference `Ellipse`). */
+    ellipse(center: Vec2, radii: Vec2, options?: Shape2DOptions): this;
+    /** Solid ellipse (reference `Ellipse::new`, the 3D `_s` counterpart). */
+    ellipse_s(center: Vec2, radii: Vec2, options?: Shape2DOptions): this;
+    /** Dashed ellipse outline. */
+    ellipse_d(center: Vec2, radii: Vec2, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /**
+     * Circular arc from `startAngle` through `sweep`. It is a curve without an interior, so it is
+     * only ever stroked; `arc_s` would have nothing to fill.
+     */
+    arc(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Arc outline dashed along its sweep. */
+    arc_d(center: Vec2, radius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Ring outline between two radii (reference `Annulus`). */
+    annulus(center: Vec2, innerRadius: number, outerRadius: number, options?: Shape2DOptions): this;
+    /** Filled ring band (reference `Annulus::new`, the 3D `_s` counterpart). */
+    annulus_s(center: Vec2, innerRadius: number, outerRadius: number, options?: Shape2DOptions): this;
+    /** Dashed annulus outline; both boundaries are stroked. */
+    annulus_d(center: Vec2, innerRadius: number, outerRadius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Capsule outline whose straight section is `length` long along y (reference `Capsule2d`). */
+    capsule(center: Vec2, radius: number, length: number, options?: Shape2DOptions): this;
+    /** Solid capsule (reference `Capsule2d::new`, the 3D `_s` counterpart). */
+    capsule_s(center: Vec2, radius: number, length: number, options?: Shape2DOptions): this;
+    /** Dashed capsule outline. */
+    capsule_d(center: Vec2, radius: number, length: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Regular polygon outline with a vertex on the +x axis (reference `RegularPolygon`). */
+    polygon(center: Vec2, circumradius: number, sides: number, options?: Shape2DOptions): this;
+    /** Solid regular polygon (reference `RegularPolygon::new`, the 3D `_s` counterpart). */
+    polygon_s(center: Vec2, circumradius: number, sides: number, options?: Shape2DOptions): this;
+    /** Dashed regular polygon outline. */
+    polygon_d(center: Vec2, circumradius: number, sides: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Triangle outline (reference `Triangle2d`); `rotation` turns about its centroid. */
+    triangle(a: Vec2, b: Vec2, c: Vec2, options?: Shape2DOptions): this;
+    /** Solid triangle (reference `Triangle2d::new`, the 3D `_s` counterpart). */
+    triangle_s(a: Vec2, b: Vec2, c: Vec2, options?: Shape2DOptions): this;
+    /** Dashed triangle outline. */
+    triangle_d(a: Vec2, b: Vec2, c: Vec2, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Diamond outline with the given full diagonals (reference `Rhombus`). */
+    rhombus(center: Vec2, diagonals: Vec2, options?: Shape2DOptions): this;
+    /** Solid diamond (reference `Rhombus::new`, the 3D `_s` counterpart). */
+    rhombus_s(center: Vec2, diagonals: Vec2, options?: Shape2DOptions): this;
+    /** Dashed diamond outline. */
+    rhombus_d(center: Vec2, diagonals: Vec2, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Disc sector outline from `startAngle` through `sweep` (reference `CircularSector`). */
+    sector(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Solid disc sector (reference `CircularSector`, the 3D `_s` counterpart). */
+    sector_s(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Dashed sector outline: the arc plus both radii. */
+    sector_d(center: Vec2, radius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    /** Disc segment outline between a chord and its arc (reference `CircularSegment`). */
+    segment(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Solid disc segment (reference `CircularSegment`, the 3D `_s` counterpart). */
+    segment_s(center: Vec2, radius: number, options?: Shape2DOptions): this;
+    /** Dashed segment outline: the arc plus the chord. */
+    segment_d(center: Vec2, radius: number, dash: readonly [number, number, number], options?: Shape2DOptions): this;
+    get points(): readonly Point2DCommand[];
+    get lines(): readonly Line2DCommand[];
+    get joints(): readonly Joint2DCommand[];
+    get shapes(): readonly Shape2DCommand[];
+}