@forgeax/engine-debug-draw 0.1.2

package/dist/debug-draw.d.ts

@@ -0,0 +1,65 @@
+import type { ColorLike, Mat4, Vec3 } from '@forgeax/engine-math';
+import type { BindGroup, Buffer, RenderPipeline, RhiCommandEncoder, RhiDevice, RhiRenderPassEncoder, TextureView } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { DebugDrawError } from './errors';
+import type { DebugDraw as DebugDrawInterface, DebugDrawOptions } from './types';
+export declare class DebugDraw implements DebugDrawInterface {
+    private stagingArr;
+    private stagingLen;
+    private lastFlushedVertexCount;
+    private capVal;
+    private gpuVbo;
+    private gpuPipeline;
+    private gpuUniformBuffer;
+    private gpuBindGroup;
+    private maxCapVal;
+    private readonly rhiDevice;
+    private isDestroyed;
+    private destroyedWarnedOnce;
+    private truncationWarned;
+    /**
+     * Depth texture view for less-equal depth mode.
+     * Set via {@link _setDepthView} before flush() when depthMode is 'less-equal'.
+     * The runtime auto-attach path receives depth from the render-graph context;
+     * low-path callers (test harnesses, smoke runners) set this explicitly.
+     */
+    private depthView;
+    constructor(device: RhiDevice, pipeline: RenderPipeline, vbo: Buffer, uniformBuffer: Buffer, bindGroup: BindGroup, initialCapacity: number, maxCapacity: number);
+    /** @internal CPU staging vertex count (exposed for unit tests). */
+    get _stagingVertexCount(): number;
+    hasPendingWork(): boolean;
+    /** @internal Vertex count passed to the most recent non-empty draw call. */
+    get _lastFlushVertexCount(): number;
+    /** @internal Current GPU vertex buffer capacity in vertex count. */
+    get _capacity(): number;
+    /** @internal Whether destroy() has been called. */
+    get _destroyed(): boolean;
+    /**
+     * @internal Set the depth texture view for less-equal depth mode.
+     * Required before flush() when depthMode is 'less-equal'.
+     * Used by test harnesses and smoke runners that don't have a scene
+     * depth buffer; the runtime auto-attach path receives depth from
+     * the render-graph context.
+     */
+    _setDepthView(view: TextureView): void;
+    /** @internal Read position of vertex at `index` in CPU staging (for unit tests). */
+    _getVertexPosition(index: number): [number, number, number];
+    /** @internal Read color of vertex at `index` as packed u32 (for unit tests). */
+    _getVertexPackedColor(index: number): number;
+    private postDestroyWarnOnce;
+    private pushVertex;
+    private warnTruncationOnce;
+    private ensureCapacity;
+    private colorToRGBA;
+    line(a: Vec3, b: Vec3, color: ColorLike): void;
+    aabb(min: Vec3, max: Vec3, color: ColorLike): void;
+    sphere(center: Vec3, radius: number, color: ColorLike, segments?: number): void;
+    frustum(viewProj: Mat4, color: ColorLike): void;
+    arrow(start: Vec3, end: Vec3, color: ColorLike, tipLength?: number): void;
+    axes(worldMat: Mat4, length: number): void;
+    flush(encoder: RhiCommandEncoder, view: TextureView, viewProj: Mat4): Result<void, DebugDrawError>;
+    encode(pass: RhiRenderPassEncoder, viewProj: Mat4): Result<void, DebugDrawError>;
+    destroy(): void;
+}
+export declare function createDebugDraw(opts: DebugDrawOptions): Promise<Result<DebugDraw, DebugDrawError>>;
+//# sourceMappingURL=debug-draw.d.ts.map

package/dist/debug-draw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-draw.d.ts","sourceRoot":"","sources":["../src/debug-draw.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,65 @@
+import { type Result } from '@forgeax/engine-types';
+/** {@link pipeline-create-failed} payload: carries the RHI-level error detail. */
+export interface PipelineCreateFailedDetail {
+    readonly code: 'pipeline-create-failed';
+    readonly rhiError: string;
+}
+/** {@link buffer-allocation-failed} payload: carries the RHI-level error detail. */
+export interface BufferAllocationFailedDetail {
+    readonly code: 'buffer-allocation-failed';
+    readonly rhiError: string;
+}
+/** {@link flushed-after-destroy} payload: carries the instance identifier. */
+export interface FlushedAfterDestroyDetail {
+    readonly code: 'flushed-after-destroy';
+}
+/** {@link viewProj-required} payload: carries the missing parameter name. */
+export interface ViewProjRequiredDetail {
+    readonly code: 'viewProj-required';
+}
+interface DebugDrawErrorDetailByCode {
+    'pipeline-create-failed': PipelineCreateFailedDetail;
+    'buffer-allocation-failed': BufferAllocationFailedDetail;
+    'flushed-after-destroy': FlushedAfterDestroyDetail;
+    'viewProj-required': ViewProjRequiredDetail;
+}
+/**
+ * Closed {@link DebugDrawErrorCode} union.
+ * Exhaustive `switch (err.code)` needs no default fallback.
+ *
+ * | code | trigger |
+ * |:--|:--|
+ * | `'pipeline-create-failed'` | `device.createRenderPipeline(...)` rejected or threw |
+ * | `'buffer-allocation-failed'` | `device.createBuffer(...)` for GPU vbo allocation failed |
+ * | `'flushed-after-destroy'` | `flush()` called on an already-destroyed DebugDraw instance |
+ * | `'viewProj-required'` | `flush()` called with `undefined` or missing `viewProj` |
+ */
+export type DebugDrawErrorCode = keyof DebugDrawErrorDetailByCode;
+/**
+ * Discriminated detail union for {@link DebugDrawError}, narrowed per
+ * `DebugDrawError.code`. AI users obtain the concrete shape via
+ * `switch (err.code)` without a fallback `as` cast.
+ */
+export type DebugDrawErrorDetail = DebugDrawErrorDetailByCode[DebugDrawErrorCode];
+/**
+ * Structured debug-draw error -- four-field surface
+ * (`.code` / `.expected` / `.hint` / `.detail`).
+ *
+ * AI users consume the structured triple by fields, not by parsing `.message`.
+ */
+type DebugDrawErrorVariant<C extends DebugDrawErrorCode> = {
+    readonly code: C;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: DebugDrawErrorDetailByCode[C];
+};
+export type DebugDrawError = {
+    [C in DebugDrawErrorCode]: DebugDrawErrorVariant<C>;
+}[DebugDrawErrorCode];
+/** Result-returning helpers consuming engine-types `Result<T, E>` + `err()`. */
+export declare function pipelineCreateFailed(rhiError: string): Result<never, DebugDrawError>;
+export declare function bufferAllocationFailed(rhiError: string): Result<never, DebugDrawError>;
+export declare function flushedAfterDestroy(): Result<never, DebugDrawError>;
+export declare function viewProjRequired(): Result<never, DebugDrawError>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEzD,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;CACxC;AAED,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED,UAAU,0BAA0B;IAClC,wBAAwB,EAAE,0BAA0B,CAAC;IACrD,0BAA0B,EAAE,4BAA4B,CAAC;IACzD,uBAAuB,EAAE,yBAAyB,CAAC;IACnD,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,0BAA0B,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC,kBAAkB,CAAC,CAAC;AAElF;;;;;GAKG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,kBAAkB,IAAI;IACzD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;KAC1B,CAAC,IAAI,kBAAkB,GAAG,qBAAqB,CAAC,CAAC,CAAC;CACpD,CAAC,kBAAkB,CAAC,CAAC;AAoBtB,gFAAgF;AAEhF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CASpF;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CAStF;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CASnE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CAShE"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { INITIAL_VERTEX_CAPACITY, MAX_VERTEX_CAPACITY, VERTEX_STRIDE_BYTES } from './constants';
+export { createDebugDraw, DebugDraw } from './debug-draw';
+export type { DebugDrawError, DebugDrawErrorCode, DebugDrawErrorDetail, } from './errors';
+export type { CreateShaderModule, DebugDrawOptions, DepthMode } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}