@aura3d/engine 4.0.2 → 4.0.4

package/dist/engine/agent-api/nodes/texture.d.ts

@@ -0,0 +1,114 @@
+/**
+ * threejs-parity §6 Lane L4 (docs/workflows/threejs-parity-gaps.md):
+ * ST-01 `texture.*` factories, ST-02 handle semantics (three's `Texture`
+ * field surface), ST-03 runtime upload (revision-driven), ST-07 real
+ * `texture.load` over `@aura3d/assets`.
+ *
+ * Every factory returns a `TextureHandle` — an `AuraTextureRef` — wrapping a
+ * live `R/Texture.ts` `Texture`. Material texture slots accept the handle
+ * through the frozen `AuraMaterialTextureInput` union; `AA/compiler/
+ * textures.ts` resolves it to `{ texture, sampler, transform }` bindings.
+ *
+ * Defaults follow three's per-kind conventions: `flipY`/`generateMipmaps`/
+ * color space mirror `THREE.Texture`, `CanvasTexture`, `VideoTexture`,
+ * `DataTexture`, `CompressedTexture`, `DepthTexture`, `CubeTexture` and
+ * `TextureLoader` output respectively.
+ */
+import { Texture } from "../../../rendering/index.js";
+import { AssetManager } from "../../../assets/browser-index.js";
+import type { AuraTextureCanvasOptions, AuraTextureColorSpace, AuraTextureCompressedOptions, AuraTextureCubeOptions, AuraTextureDataArrayOptions, AuraTextureDataOptions, AuraTextureDepthOptions, AuraTextureLoadOptions, AuraTextureMagFilter, AuraTextureMinFilter, AuraTextureRef, AuraTextureVideoOptions, AuraTextureWrapMode } from "./types.js";
+/** Internal bridge (compiler/textures.ts): the live `Texture` behind a ref. */
+export declare function auraTextureRefTexture(ref: AuraTextureRef | null | undefined): Texture | null;
+/**
+ * ST-02: live handle for a user-created texture — three's `Texture` field
+ * surface (`wrapS/T`, `repeat`, `offset`, `rotation`, `center`, filters,
+ * `anisotropy`, `generateMipmaps`, `colorSpace`, `flipY`, `needsUpdate`,
+ * `dispose`). `AuraTextureRef` (frozen, `nodes/types.ts`) is what material
+ * texture slots and `AuraUniformValue` accept.
+ *
+ * Upload-facing fields (`colorSpace`, `flipY`, `generateMipmaps`,
+ * `needsUpdate`) write through to the backing `Texture` and mark it dirty;
+ * sampling/transform fields are compiled into the slot's sampler and
+ * `AuraTextureTransform` by `resolveAuraTextureRef`.
+ */
+export declare class TextureHandle implements AuraTextureRef {
+    readonly kind: "aura-texture-ref";
+    readonly id: string;
+    wrapS: AuraTextureWrapMode;
+    wrapT: AuraTextureWrapMode;
+    repeat: readonly [number, number];
+    offset: readonly [number, number];
+    rotation: number;
+    center: readonly [number, number];
+    anisotropy: number;
+    minFilter: AuraTextureMinFilter;
+    magFilter: AuraTextureMagFilter;
+    /** The backing device texture — do not mutate it from user code. */
+    readonly texture: Texture;
+    constructor(texture: Texture, defaults?: {
+        readonly wrapS?: AuraTextureWrapMode;
+        readonly wrapT?: AuraTextureWrapMode;
+        readonly anisotropy?: number;
+        readonly minFilter?: AuraTextureMinFilter;
+        readonly magFilter?: AuraTextureMagFilter;
+    });
+    get colorSpace(): AuraTextureColorSpace;
+    set colorSpace(value: AuraTextureColorSpace);
+    get flipY(): boolean;
+    set flipY(value: boolean);
+    get generateMipmaps(): boolean;
+    set generateMipmaps(value: boolean);
+    /**
+     * ST-03: set after mutating pixels/source. Bumps the device revision
+     * exactly once per dirty cycle; the device clears it once the revision
+     * has been uploaded.
+     */
+    get needsUpdate(): boolean;
+    set needsUpdate(value: boolean);
+    dispose(): void;
+}
+/** Test hook: replace the shared manager (custom loaders/baseUrl). */
+export declare function setTextureAssetManager(manager: AssetManager | null): void;
+/**
+ * ST-01: the `texture.*` namespace. Every factory returns a live
+ * `TextureHandle`; `load` is the async three `TextureLoader` parity path.
+ */
+export declare const texture: {
+    /**
+     * `new THREE.DataTexture(data, width, height)` — raw pixel data. `format`
+     * accepts the frozen option strings; `rgb8`/`r8` expand to RGBA8 (the
+     * device's supported format family).
+     */
+    data(options: AuraTextureDataOptions): TextureHandle;
+    /**
+     * `new THREE.CanvasTexture(canvas)` — a live 2D canvas. `needsUpdate`
+     * re-uploads on the next bind (ST-03).
+     */
+    canvas(options: AuraTextureCanvasOptions): TextureHandle;
+    /**
+     * `new THREE.VideoTexture(video)` — per-frame upload: the device polls the
+     * source each bind and re-uploads when `currentTime` advanced (ST-03). Like
+     * three's VideoTexture, mipmaps are off and filtering is linear.
+     */
+    video(options: AuraTextureVideoOptions): TextureHandle;
+    /** `new THREE.CompressedTexture(mipmaps, w, h, format)` — device-ready blocks. */
+    compressed(options: AuraTextureCompressedOptions): TextureHandle;
+    /** `new THREE.DepthTexture(w, h)` — a depth24 attachment texture. */
+    depth(options: AuraTextureDepthOptions): TextureHandle;
+    /**
+     * `new THREE.CubeTexture(images)` — six faces in WebGPU/cube order
+     * px, nx, py, ny, pz, nz. Each face is a typed pixel array (square size
+     * inferred), `{ width, height, data, format? }`, or an image source
+     * (canvas/ImageBitmap/image — read back through a 2D canvas).
+     */
+    cube(facesOrOptions: readonly unknown[] | AuraTextureCubeOptions): TextureHandle;
+    /** `new THREE.DataArrayTexture(data, w, h, depth)` — layer-stacked 2D data. */
+    dataArray(options: AuraTextureDataArrayOptions): TextureHandle;
+    /**
+     * `new THREE.TextureLoader().load(url)` — real async decode over
+     * `@aura3d/assets` (`ImageLoader` → `TextureLoader`). Progress/error events
+     * flow to `createAuraApp({ onAssetProgress, onAssetError })` (ST-06).
+     */
+    load(url: string, options?: AuraTextureLoadOptions): Promise<TextureHandle>;
+};
+//# sourceMappingURL=texture.d.ts.map

package/dist/engine/agent-api/nodes/texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/texture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,OAAO,EAOR,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAqH,MAAM,wBAAwB,CAAC;AAIzK,OAAO,KAAK,EACV,wBAAwB,EACxB,qBAAqB,EACrB,4BAA4B,EAC5B,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAyBpB,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAG5F;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,mBAAmB,CAAW;IACrC,KAAK,EAAE,mBAAmB,CAAW;IACrC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAU;IAC3C,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAU;IAC3C,QAAQ,SAAK;IACb,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAU;IAC3C,UAAU,SAAK;IACf,SAAS,EAAE,oBAAoB,CAA0B;IACzD,SAAS,EAAE,oBAAoB,CAAY;IAE3C,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAGxB,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE;QACR,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;QACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;QACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;QAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;KACtC;IAYR,IAAI,UAAU,IAAI,qBAAqB,CAEtC;IAED,IAAI,UAAU,CAAC,KAAK,EAAE,qBAAqB,EAI1C;IAED,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,OAAO,EAIvB;IAED,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,IAAI,eAAe,CAAC,KAAK,EAAE,OAAO,EAIjC;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,EAE7B;IAED,OAAO,IAAI,IAAI;CAGhB;AAkQD,sEAAsE;AACtE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAEzE;AAED;;;GAGG;AAKH,eAAO,MAAM,OAAO;IAClB;;;;OAIG;kBACW,sBAAsB,GAAG,aAAa;IAepD;;;OAGG;oBACa,wBAAwB,GAAG,aAAa;IAkBxD;;;;OAIG;mBACY,uBAAuB,GAAG,aAAa;IAoBtD,kFAAkF;wBAC9D,4BAA4B,GAAG,aAAa;IAiBhE,qEAAqE;mBACtD,uBAAuB,GAAG,aAAa;IActD;;;;;OAKG;yBACkB,SAAS,OAAO,EAAE,GAAG,sBAAsB,GAAG,aAAa;IAiChF,+EAA+E;uBAC5D,2BAA2B,GAAG,aAAa;IAwC9D;;;;OAIG;cACa,MAAM,YAAW,sBAAsB,GAAQ,OAAO,CAAC,aAAa,CAAC;CAgDpF,CAAC"}