@miris-inc/core 0.0.8-dd086db → 0.0.8-dd65fc3

package/dist/core.d.ts

@@ -1,16 +1,58 @@
+export declare const AssetFormat: {
+    readonly GaussianSplats: 1;
+    readonly GES: 2;
+};
+
 declare interface AttributeInfo extends EmbindObject {
-    readonly dataType: number;
-    readonly componentCount: number;
-    readonly dataPtr: number;
-    readonly dataByteLength: number;
+    // Logical elements from the drop metadata: splats for a per-splat attribute, records for a
+    // per-surfel one. Not necessarily dataSizeBytes / bytesPerElement.
+    readonly elementCount: number;
+    readonly dataSizeBytes: number;
     readonly clientSideId: bigint;
+    // An embind CompressionType value, compared by identity against MainModule.CompressionType
+    readonly compressionType: unknown;
+    readonly minValue: { x: number; y: number; z: number; w: number };
     readonly maxValue: { x: number; y: number; z: number };
 }
 
+export declare class AttributeNames {
+    static readonly SPARK_PACKED_SPLAT: string;
+    static readonly SPARK_EXTENDED_SPLAT_LOW: string;
+    static readonly SPARK_EXTENDED_SPLAT_HIGH: string;
+    static readonly SPARK_PACKED_SH1: string;
+    static readonly SPARK_PACKED_SH2: string;
+    static readonly SPARK_PACKED_SH3: string;
+    static readonly SPARK_EXTENDED_SH1: string;
+    static readonly SPARK_EXTENDED_SH2: string;
+    static readonly SPARK_EXTENDED_SH3_A: string;
+    static readonly SPARK_EXTENDED_SH3_B: string;
+    static readonly UNUSED: string;
+    static readonly SHARK_ELLIPSOIDS: string;
+    static readonly SHARK_ELLIPSOIDS_COMPRESSED: string;
+    static readonly SHARK_SPHERICAL_HARMONICS: string;
+    static readonly COLOR: string;
+    static readonly OCTANT_OFFSETS: string;
+    static readonly SURFEL_OCTANT_OFFSETS: string;
+    static readonly SURFEL_COUNT: string;
+    static readonly SURFEL_OWNER_GROUPS: string;
+    static readonly OCTANT_CELL: string;
+    static readonly REFLECTANCE_DATA_V1: string;
+    static readonly GLASS_MESH_GEOMETRY: string;
+    static readonly GLASS_MESH_PANELS: string;
+    static readonly MOD_DEPTH: string;
+}
+
+declare type CachedAttribute = {
+    paddedData: Uint32Array<ArrayBuffer>;
+    originalSizeInUints: number;
+};
+
 export declare class Camera {
     #private;
     readonly id: number;
     update(): void;
+    get viewportHeight(): number;
+    set viewportHeight(viewportHeight: number);
     get aspect(): number;
     set aspect(aspect: number);
     get fov(): number;
@@ -24,7 +66,7 @@ export declare class Camera {
     readonly engine: Engine;
     readonly miris: Miris;
     readonly scene: Scene;
-    constructor({ aspect, fov, near, far, matrix, scene }: CameraInit);
+    constructor({ aspect, fov, near, far, matrix, scene, viewportHeight, }: CameraInit);
 }
 
 export declare type CameraInit = {
@@ -34,6 +76,7 @@ export declare type CameraInit = {
     far: number;
     matrix: Matrix4x4Tuple;
     scene: Scene;
+    viewportHeight?: number;
 };
 
 export declare class Change {
@@ -43,7 +86,7 @@ export declare class Change {
 }
 
 export declare type ChangeInit = {
-    type: "created" | "activated" | "modified" | "deactivated" | "deleted";
+    type: "created" | "activated" | "modified" | "deactivated" | "deleted" | "remasked";
     lod: Lod;
 };
 
@@ -69,6 +112,7 @@ declare class Client {
     getSceneMetadata(...args: ClientMethodParameters["getSceneMetadata"]): number;
     getSceneObjectParent(...args: ClientMethodParameters["getSceneObjectParent"]): number;
     getSceneObjectType(...args: ClientMethodParameters["getSceneObjectType"]): SceneObjectType;
+    getDrawnOctantMask(...args: ClientMethodParameters["getDrawnOctantMask"]): number;
     getLocalTransform(...args: ClientMethodParameters["getLocalTransform"]): AquaStatus;
     getWorldTransform(...args: ClientMethodParameters["getWorldTransform"]): AquaStatus;
     hasAttribute(...args: ClientMethodParameters["hasAttribute"]): boolean;
@@ -84,6 +128,8 @@ declare class Client {
     hasFeature(...args: ClientMethodParameters["hasFeature"]): boolean;
     getFeatureVersion(...args: ClientMethodParameters["getFeatureVersion"]): number;
     getFeatureState(...args: ClientMethodParameters["getFeatureState"]): number;
+    getAssetFormatVersion(...args: ClientMethodParameters["getAssetFormatVersion"]): number;
+    getDrMapLadderRoughnessLevels(...args: ClientMethodParameters["getDrMapLadderRoughnessLevels"]): number[];
     getName(...args: ClientMethodParameters["getName"]): string;
     setVariantSelection(...args: ClientMethodParameters["setVariantSelection"]): AquaStatus;
     takeAttribute(...args: ClientMethodParameters["takeAttribute"]): AquaStatus;
@@ -91,7 +137,6 @@ declare class Client {
     takeRenderRequired(...args: ClientMethodParameters["takeRenderRequired"]): boolean;
     unlockScene(...args: ClientMethodParameters["unlockScene"]): boolean;
     updateSceneExecution(...args: ClientMethodParameters["updateSceneExecution"]): AquaStatus;
-    recordFrameTime(...args: ClientMethodParameters["recordFrameTime"]): AquaStatus;
 }
 
 declare type ClientInit = {
@@ -155,6 +200,10 @@ declare class Engine {
     get module(): MainModule;
     constructor(moduleOptions?: Record<string, unknown>);
     get AttributeInfo(): new () => AttributeInfo;
+    get CompressionType(): {
+        SHARK_ELLIPSOID_COMPRESSED: unknown;
+        SHARK_ELLIPSOID_COMPRESSED_ROOT_RELATIVE: unknown;
+    };
     get Handedness(): {
         Right: number;
         Left: number;
@@ -190,6 +239,8 @@ declare class Engine {
     deletedObjectIdsView(...args: [sceneChangeIds: SceneChangeIds]): Uint32Array;
     dataPtrView(...args: [attributeInfo: AttributeInfo]): Uint32Array;
     deactivatedObjectIdsView(...args: [sceneChangeIds: SceneChangeIds]): Uint32Array;
+    remaskedObjectIdsView(...args: [sceneChangeIds: SceneChangeIds]): Uint32Array;
+    getDrawnOctantMask(...args: [handle: AquaClientHandle, sceneObjectId: number]): number;
     destroyClient(...args: [handle: AquaClientHandle]): AquaStatus;
     free(...args: [size: number]): number;
     getAssetsAsync(...args: [handle: AquaClientHandle, tags: StringVector]): AssetInfo[];
@@ -199,8 +250,8 @@ declare class Engine {
     attributeName: string,
     attributeInfo: AttributeInfo
     ]): AquaStatus;
-    getDefaultCameraId(...args: [handle: AquaClientHandle]): number;
-    getViewingVolumeId(...args: [handle: AquaClientHandle]): number;
+    getDefaultCameraId(...args: [handle: AquaClientHandle, streamObjectId: number]): number;
+    getViewingVolumeId(...args: [handle: AquaClientHandle, streamObjectId: number]): number;
     getLocalBoundingBox(...args: [handle: AquaClientHandle, sceneObjectId: number, boxData: number]): AquaStatus;
     getWorldBoundingBox(...args: [handle: AquaClientHandle, sceneObjectId: number, boxData: number]): AquaStatus;
     getLodIndex(...args: [handle: AquaClientHandle, sceneObjectId: number]): number;
@@ -256,9 +307,11 @@ declare class Engine {
     aspectRatio: number,
     verticalFov: number,
     nearPlane: number,
-    farPlane: number
+    farPlane: number,
+    viewportHeightPixels: number
     ]): AquaStatus;
     setMaxCacheSize(...args: [maxSizeBytes: number]): void;
+    setPreferSharkEncodingProfiles(...args: [preferShark: boolean]): void;
     setSceneObjectTransform(...args: [
     handle: AquaClientHandle,
     sceneObjectId: number,
@@ -267,6 +320,8 @@ declare class Engine {
     hasFeature(...args: [handle: AquaClientHandle, sceneObjectId: number, feature: number]): boolean;
     getFeatureVersion(...args: [handle: AquaClientHandle, sceneObjectId: number, feature: number]): number;
     getFeatureState(...args: [handle: AquaClientHandle, sceneObjectId: number, feature: number]): number;
+    getDrMapLadderRoughnessLevels(...args: [handle: AquaClientHandle, sceneObjectId: number]): number[];
+    getAssetFormatVersion(...args: [handle: AquaClientHandle, sceneObjectId: number]): number;
     getName(...args: [handle: AquaClientHandle, sceneObjectId: number]): string;
     setVariantSelection(...args: [handle: AquaClientHandle, sceneObjectId: number]): AquaStatus;
     takeAttribute(...args: [
@@ -279,8 +334,15 @@ declare class Engine {
     getActiveClientSideIdsCheckSum(): number;
     unlockScene(...args: [handle: AquaClientHandle]): boolean;
     updateSceneExecution(...args: [handle: AquaClientHandle]): AquaStatus;
-    recordFrameTime(...args: [handle: AquaClientHandle, frameTimeMs: number]): AquaStatus;
     takeRenderRequired(...args: [handle: AquaClientHandle]): boolean;
+    /**
+     * Advances the runtime by one frame and recomputes the streaming budget. Call once per
+     * displayed frame per context, before the per-client updateSceneExecution() calls.
+     * `previousFrameTimeMs` is how long the previous frame took; pass 0 when there is no plausible
+     * measurement (first frame, or a resume from a stall) and the frame advances without recording
+     * one.
+     */
+    beginFrame(...args: [contextHandle: AquaContextHandle, previousFrameTimeMs: number]): AquaStatus;
     createDeserializeWorker(_url: string, _workerUrl: string, poolSize: number): boolean;
     cancelRequest(requestIdLow: number, requestIdHigh: number): boolean;
     submitToWorker(requestIdLow: number, requestIdHigh: number, descriptorBuffer: ArrayBuffer, contextPtr: number): boolean;
@@ -298,25 +360,9 @@ export declare class Lod {
     #private;
     readonly id: LodInit["id"];
     readonly store: LodStore;
-    useExtSplats: boolean;
-    splatsExtendedData: Uint32Array<ArrayBuffer> | null;
-    sh1Data: Uint32Array<ArrayBuffer> | null;
-    sh1Max: number;
-    sh2Data: Uint32Array<ArrayBuffer> | null;
-    sh2Max: number;
-    sh3Data: Uint32Array<ArrayBuffer> | null;
-    sh3Max: number;
-    sh3ExtendedData: Uint32Array<ArrayBuffer> | null;
     get key(): unknown;
     set key(key: unknown);
     readonly modelRoot: ModelRoot;
-    set splats(splats: Uint32Array<ArrayBuffer> | null);
-    get splats(): Uint32Array<ArrayBuffer> | null;
-    /**
-     * Sets the cached world bounds of this object
-     *
-     * @deprecated set the local bounds and transform as needed
-     */
     set bounds(bounds: Float32Array<ArrayBuffer> | null);
     /**
      * Retrieves the cached world bounds of this object
@@ -334,21 +380,32 @@ export declare class Lod {
     get localBounds(): Float32Array<ArrayBuffer> | null;
     set lodIndex(index: number);
     get lodIndex(): number | null;
-    set paddingCount(count: number);
-    get paddingCount(): number;
+    set paddingSplatsCount(count: number);
+    get paddingSplatsCount(): number;
     set transform(transform: Float32Array<ArrayBuffer> | null);
     get transform(): Float32Array<ArrayBuffer> | null;
-    setSh1(sh1Data: Uint32Array<ArrayBuffer>, sh1Max: number): void;
-    setSh2(sh2Data: Uint32Array<ArrayBuffer>, sh2Max: number): void;
-    setSh3(sh3Data: Uint32Array<ArrayBuffer>, sh3Max: number): void;
+    get _drawnOctantMask(): number;
+    set _drawnOctantMask(mask: number);
+    get _octantOffsets(): Uint32Array<ArrayBuffer> | null;
+    get _hasOctantOffsets(): boolean;
+    get _surfelOctantOffsets(): Uint32Array<ArrayBuffer> | null;
+    get _surfelCount(): number;
+    get _surfelOwnerGroups(): Uint32Array<ArrayBuffer> | null;
+    get _octantCell(): Uint32Array<ArrayBuffer> | null;
+    _readOctantOffsets(engine: Engine): void;
+    hasAttribute(attributeName: string): boolean;
+    getDataFromAttribute(engine: Engine, attributeName: string, attributeInfo: AttributeInfo): CachedAttribute | null;
+    _getRawByteAttribute(engine: Engine, attributeName: string): Uint8Array<ArrayBuffer> | null;
+    _getRawByteAttributeWithBounds(engine: Engine, attributeName: string): RawByteAttributeWithBounds | null;
     dispose(): void;
-    constructor({ id, modelRoot, lodStore }: LodInit);
+    constructor({ id, modelRoot, lodStore, client }: LodInit);
 }
 
 export declare type LodInit = {
     id: number;
     modelRoot: ModelRoot;
     lodStore: LodStore;
+    client: Client;
 };
 
 export declare class LodStore {
@@ -364,6 +421,10 @@ export declare class LodStore {
 
 declare interface MainModule {
     AttributeInfo: new () => AttributeInfo;
+    CompressionType: {
+        SHARK_ELLIPSOID_COMPRESSED: unknown;
+        SHARK_ELLIPSOID_COMPRESSED_ROOT_RELATIVE: unknown;
+    };
     Handedness: { Right: number; Left: number };
     HEAPF32: Float32Array<ArrayBuffer>;
     HEAPU8: Uint8Array<ArrayBuffer>;
@@ -389,7 +450,9 @@ declare interface MainModule {
     createdObjectIdsView(sceneChangeIds: SceneChangeIds): Uint32Array;
     dataPtrView(attributeInfo: AttributeInfo): Uint32Array;
     deactivatedObjectIdsView(sceneChangeIds: SceneChangeIds): Uint32Array;
+    remaskedObjectIdsView(sceneChangeIds: SceneChangeIds): Uint32Array;
     deletedObjectIdsView(sceneChangeIds: SceneChangeIds): Uint32Array;
+    GetDrawnOctantMask(handle: number, sceneObjectId: number): number;
     GetAssetsAsync(handle: number, tags: StringVector): unknown[];
     GetSceneChanges(handle: number, sceneChangeIds: SceneChangeIds): void;
     GetSceneChangesCounts(handle: number, sceneChangeIds: SceneChangeIds): void;
@@ -398,13 +461,17 @@ declare interface MainModule {
     HasFeature(handle: number, sceneObjectId: number, feature: number): boolean;
     GetFeatureVersion(handle: number, sceneObjectId: number, feature: number): number;
     GetFeatureState(handle: number, sceneObjectId: number, feature: number): number;
+    GetAssetFormatVersion(handle: number, sceneObjectId: number): number;
+    GetDrMapLadderRoughnessLevels(handle: number, sceneObjectId: number): number[];
     SetClientSpatialFormat(handle: number, spatialFormat: SpatialFormat): { value: number };
     SetRuntimeSettings(handle: number, settings: RuntimeSettings): { value: number };
     TakeEvictedClientSideAttributeIds(handle: number): EmbindVector<bigint>;
     GetActiveClientSideIdsCheckSum(): number;
     TakeRenderRequired(handle: number): boolean;
+    BeginFrame(contextHandle: number, previousFrameTimeMs: number): number;
     modifiedObjectIdsView(sceneChangeIds: SceneChangeIds): Uint32Array;
     setMaxCacheSize(maxSizeBytes: number): void;
+    SetPreferSharkEncodingProfiles(prefer: boolean): void;
 }
 
 /**
@@ -417,6 +484,7 @@ declare interface MainModule {
  */
 export declare class Miris {
     #private;
+    static tryUseShark: boolean;
     static _instance: Miris;
     static instance<T extends typeof Miris>(this: T): Promise<InstanceType<T>>;
     readonly engine: Engine;
@@ -435,17 +503,27 @@ export declare class Miris {
     protected _xrSession: XRSession | null;
     protected _requestAnimationFrame: RequestAnimationFrameFn | null;
     signalResumeFromIdle(): void;
+    get _splatCountBudget(): number;
     /**
      * Why 43? Because the AVP throttles down to 45Hz :(
      */
     static readonly _XR_TARGET_FRAME_RATE = 43;
+    /* Excluded from this release type: _XR_SPLAT_COUNT_BUDGET */
+    /* Excluded from this release type: _SHARK_SPLAT_CAPACITY_MOBILE */
+    static readonly _SHARK_SPLAT_CAPACITY_DESKTOP = 3000000;
+    /* Excluded from this release type: _SHARK_SPLAT_BUDGET_CAP_MOBILE */
+    static readonly _SHARK_SPLAT_BUDGET_CAP_DESKTOP = 2500000;
+    /* Excluded from this release type: _isMobileDevice */
+    /* Excluded from this release type: _sharkSplatCapacity */
+    /* Excluded from this release type: _limitSharkSplatCapacity */
+    /* Excluded from this release type: _sharkSplatBudgetCap */
     /* Excluded from this release type: _setTargetFrameRate */
     /* Excluded from this release type: _setXRModeActive */
     /* Excluded from this release type: _setSplatCountBudgetOverride */
     /* Excluded from this release type: _update */
     getLocalTransform(client: Client, sceneObjectId: number): Float32Array<ArrayBuffer> | undefined;
     getWorldTransform(client: Client, sceneObjectId: number): Float32Array<ArrayBuffer> | undefined;
-    update(): boolean;
+    /* Excluded from this release type: _updateForScene */
     applyChanges(_entries: Change[]): void;
     _computeAdditionalRenderNeeded(): boolean;
     onColorSpaceDetected(_isLinear: boolean): void;
@@ -474,6 +552,28 @@ export declare type ModelRootInit = {
     stream: Stream;
 };
 
+/**
+ * The byte-exact counterpart of getRawUint32Attribute above: same no-padding, no-takeAttribute
+ * contract, returning bytes rather than words.
+ *
+ * Use this rather than that one wherever the stride is not a whole number of words:
+ * reflectanceDataV1's 26-byte record is not, and an odd record count would lose that record's
+ * last field to dataPtrView's truncation.
+ */
+export declare type RawByteAttributeWithBounds = {
+    bytes: Uint8Array<ArrayBuffer>;
+    minValue: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    maxValue: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+
 declare type RequestAnimationFrameFn = ((callback: FrameRequestCallback) => number) | ((callback: XRFrameRequestCallback) => void);
 
 declare interface RuntimeSettings extends EmbindObject {
@@ -482,6 +582,7 @@ declare interface RuntimeSettings extends EmbindObject {
     targetFramesPerSecond: number;
     xrModeActive: boolean;
     splatCountBudget: number;
+    splatCountBudgetCap: number;
 }
 
 export declare class Scene extends EventTarget {
@@ -493,6 +594,7 @@ export declare class Scene extends EventTarget {
     readonly id: number;
     get key(): unknown;
     set key(key: unknown);
+    /* Excluded from this release type: _assetFormat */
     get viewerKey(): string | null;
     set viewerKey(viewerKey: string | null);
     get streams(): Set<Stream>;
@@ -502,21 +604,33 @@ export declare class Scene extends EventTarget {
     readonly client: Client;
     readonly handle?: number;
     constructor({ miris, viewerKey }: SceneInit);
+    /**
+     * Drives a frame and answers whether *this* scene's canvas needs repainting. Call it once per
+     * displayed frame from the host's animation loop, and render when it returns true.
+     *
+     * Every scene on the page calls this from its own loop. The first call in a displayed frame
+     * drives one engine tick for all of them; the rest recognise the frame and reuse it.
+     *
+     * @param ts the host's frame timestamp. Optional - the document timeline supplies one, and it
+     *   reads the same for every scene in a displayed frame. Pass it when the host runs its own
+     *   clock, as an immersive XR session does, because XRFrame time is not the document timeline.
+     */
+    update(ts?: DOMHighResTimeStamp): boolean;
     dispose(): void;
-    /* Excluded from this release type: _getViewingVolumeBounds */
     fetchAssets(tags?: string | Iterable<string>): Promise<{
         name: string;
         thumbnailUrl: string;
         uuid: string;
         tags: string[];
     }[]>;
-    getDefaultCameraTransform(): Float32Array<ArrayBuffer> | null | undefined;
     add(stream: Stream): void;
     getStreamForId(streamObjectId: number): Stream | undefined;
     getStreamForDescendentId(descendentObjectId: number): Stream | null;
     getModelRootForDescendentId(descendentObjectId: number): ModelRoot | null;
+    _recordAssetFormat(modelRoot: ModelRoot, formatVersion: number): void;
     /* Excluded from this release type: _getFeatureMesh */
     /* Excluded from this release type: _getDrMap */
+    /* Excluded from this release type: _onDrMapLadder */
     /* Excluded from this release type: _onFeatureData */
     /* Excluded from this release type: _onSceneLoaded */
     delete(stream: Stream): void;
@@ -529,6 +643,7 @@ declare interface SceneChangeIds extends EmbindObject {
     readonly modifiedObjectsCount: number;
     readonly deactivatedObjectsCount: number;
     readonly deletedObjectsCount: number;
+    readonly remaskedObjectsCount: number;
 }
 
 export declare type SceneInit = {
@@ -540,6 +655,13 @@ declare interface SceneMetadata extends EmbindObject {
     readonly inputColorSpace: string;
 }
 
+declare type SparkAttributeInfo = {
+    elementsPerSplat: number;
+    discard: boolean;
+};
+
+export declare const sparkAttributeList: Record<string, SparkAttributeInfo>;
+
 declare interface SpatialFormat extends EmbindObject {
     metersPerUnit: number;
     upAxis: number;
@@ -567,6 +689,8 @@ export declare class Stream extends EventTarget {
     set key(key: unknown);
     get matrix(): Matrix4x4Tuple;
     set matrix(matrix: Matrix4x4Tuple);
+    get opacity(): number;
+    set opacity(opacity: number);
     get boundingBox(): {
         min: {
             x: number;
@@ -597,6 +721,8 @@ export declare class Stream extends EventTarget {
     constructor(options: StreamInit);
     _initStream({ uuid }: StreamInit): void;
     /* Excluded from this release type: _onStreamLoaded */
+    getDefaultCameraTransform(): Float32Array<ArrayBuffer> | null | undefined;
+    /* Excluded from this release type: _getViewingVolumeObb */
     /* Excluded from this release type: _onRootLoaded */
     add(modelRoot: ModelRoot): void;
     end(): void;