@miris-inc/core 0.0.8-e6a94a6 → 0.0.8-e7873f9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miris-inc/core",
-  "version": "0.0.8-e6a94a6",
+  "version": "0.0.8-e7873f9",
   "description": "Core scene-graph runtime for the Miris 3D streaming SDK. WASM-backed Engine, Client, Scene, Stream, and LOD primitives shared by all higher-level packages.",
   "keywords": [
     "3d",
@@ -17,6 +17,9 @@
   "author": "Miris, Inc.",
   "files": [
     "banner.svg",
+    "webshark.d.ts",
+    "webshark.js",
+    "webshark.wasm",
     "dist/*.js",
     "dist/*.d.ts",
     "dist/*.wasm",
@@ -37,6 +40,10 @@
       "import": "./dist/core.prod.js",
       "default": "./dist/core.prod.js"
     },
+    "./webshark": {
+      "types": "./webshark.d.ts",
+      "default": "./webshark.js"
+    },
     "./standalone": {
       "types": "./dist/core.d.ts",
       "development": "./dist/core.standalone.js",

package/webshark.d.ts

@@ -0,0 +1,318 @@
+export interface Camera {
+  dir: vec4;
+  U: vec4;
+  V: vec4;
+  eye: vec4;
+  l: number;
+  fov: number;
+  zNear: number;
+  zFar: number;
+  delete(): void;
+}
+
+export interface SortTypeValue {
+  value: number;
+}
+
+export interface TextureFormatValue {
+  value: number;
+}
+
+export interface SharkRenderInfo {
+  triangles: number;
+}
+
+export interface SharkInfo {
+  renderCalls: number;
+  render: SharkRenderInfo;
+  reset(): void;
+}
+
+export interface RendererWGPU {
+  getProgramCount(): number;
+  getTextureCount(): number;
+  getEstimatedTextureSize(): number;
+  getTotalBufferSize(): number;
+  info: SharkInfo;
+  delete(): void;
+}
+
+export interface RenderState {
+  delete(): void;
+  initRenderState(
+    renderer: RendererWGPU,
+    width: number,
+    height: number,
+    vertices: number,
+    splats: number,
+    cubes: number,
+    sortThreads: number,
+    sortGroupSize: number,
+    sortKeySize: number,
+  ): void;
+  initGraphicsState(
+    width: number,
+    height: number,
+    renderTextureFormat: TextureFormatValue,
+    depthTextureFormat: TextureFormatValue,
+  ): void;
+  updateRenderDetails(
+    width: number,
+    height: number,
+    splatTriangles: number,
+  ): void;
+  // Decodes Radiance .hdr bytes into roughness-ladder level `level` (0 is the sharp mirror).
+  // hdrPtr must address THIS module's heap - _malloc here and copy the bytes in.
+  // Returns false for bytes that are not a usable Radiance image, or a level out of range.
+  uploadEnvironmentLadderLevelFromHdr(
+    level: number,
+    sigmaDeg: number,
+    hdrPtr: number,
+    hdrSizeBytes: number,
+  ): boolean;
+  // Republish the ladder's shape. Call after any level lands, or it is sampled at whatever shape
+  // the last uploadSplatSetData declared. Pass SplatSet.hasReflectionParams().
+  uploadReflectionLadderParams(reflectionsEnabled: boolean): void;
+  // Debug controls. Drop the reflection term, or replace the surfel colour with one of the layers
+  // it is shaded from, numbered as RenderViewModes.h's AOV_* defines. setRenderView below sets
+  // the AOV together with the rest of a named view.
+  setReflectionsEnabled(enabled: boolean): void;
+  // Render textured gaussians on pixels no surfel covers, resolved as fvdb's open gate does.
+  // Off by default: those pixels show the clear colour.
+  setSurfelLessTextureSplatsEnabled(enabled: boolean): void;
+  setDebugAovMode(mode: number): void;
+}
+
+export interface vec4 {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+  delete(): void;
+}
+
+export interface SplatSet {
+  splatCount: number;
+  // Number of splats actually drawn: ordering[0, activeSplats) holds the unmasked splat indices.
+  // Set alongside orderingView() to restrict the draw to unmasked octant ranges.
+  activeSplats: number;
+  // Selects which ellipsoid layout to allocate and what ellipsoidsView() exposes:
+  // packed (16 bytes/splat) or uncompressed (48). Must be set before the first resize.
+  usePackedEllipsoids: boolean;
+  // direct-write upload: resize -> write into the views -> finalize.
+  // views are valid only until the next resize.
+  resize(splatCount: number): void;
+  ellipsoidsView(): Uint32Array;
+  colorsView(): Uint32Array;
+  sh1View(): Uint32Array;
+  sh2View(): Uint32Array;
+  sh3aView(): Uint32Array;
+  sh3bView(): Uint32Array;
+  // mod_depth is a half-float per primitive slot (dense, padded for non-surfels), so this is a
+  // Uint16Array unlike every other view here -- do not address it with the uint32 splat strides
+  // used for ellipsoids/colors/sh*.
+  modDepthView(): Uint16Array;
+  // Per-chunk fade (opacity multiplier), one float per chunk, defaults to 1.0.
+  // Also sizes the chunk slot to model root slot map below, since both are indexed by chunk slot
+  resizeChunkFades(chunkCount: number): void;
+  chunkFadesView(): Float32Array;
+  // Per-splat chunk index, defaults to slot 0. Write before finalize()
+  chunkIndicesView(): Int32Array;
+  // Model transforms, resolved per splat as
+  //   modelRootTransforms[chunkModelRoots[chunkIndices[splat]]]
+  // Slot 0 of both tables is reserved as identity, so real slots start at 1 and a set that
+  // never writes them renders untransformed.
+  resizeModelRootSlots(modelRootCount: number): void;
+  // 16 floats per model root, COLUMN-major - i.e. write THREE's Matrix4.toArray() straight in
+  modelRootTransformsView(): Float32Array;
+  // The inverses, same slots and layout. The true-perspective projection (Project.glsl) transforms
+  // a quadratic form and needs them; writing a transform without its inverse leaves that path
+  // projecting the splat as if untransformed. Use Matrix4.invert() on a copy
+  modelRootInverseTransformsView(): Float32Array;
+  // Sized by resizeChunkFades. Defaults to slot 0 (identity) for every chunk
+  chunkModelRootsView(): Int32Array;
+  // resizeModelRootSlots resets every slot to the absolute decode. False for a slot outside the table
+  setModelRootRootRelativeDecode(
+    slot: number,
+    originX: number,
+    originY: number,
+    originZ: number,
+    step: number,
+  ): boolean;
+  // int32 render-order buffer (sized 2*splatCount after finalize). Valid only until the next resize.
+  orderingView(): Int32Array;
+  finalize(): void;
+  // like finalize() but keeps splats in their delivered (octant-sorted) order — no kd-tree reorder —
+  // so sparse-octant range masking can index child-octant ranges directly. RADIX_SORT only.
+  finalizeBounds(): void;
+  // Whether the asset carries per-surfel reflectance records, which is what decides whether
+  // reflections are shaded at all. Pass to RenderState.uploadReflectionLadderParams.
+  hasReflectionParams(): boolean;
+  // Widens packed 26-byte reflectanceDataV1 records into the per-splat GPU records at
+  // bufferOffset. wirePtr must address THIS module's heap - _malloc here and copy the bytes in,
+  // since the attribute lives in the engine module's. Records cover a node's surfel range, which
+  // starts at its first splat. Returns the records written; 0 if the data was rejected.
+  decodeReflectionParams(
+    wirePtr: number,
+    wireSizeBytes: number,
+    elementCount: number,
+    bufferOffset: number,
+    nodeSplatCount: number,
+    logId: number,
+  ): number;
+  // Zeroes records in [startSplat, endSplat). Needed wherever splats are re-packed at fresh
+  // offsets, or a reused slot shades its splat from the previous occupant's material.
+  clearReflectionParams(startSplat: number, endSplat: number): void;
+  // Splats in [0, count) holding a non-zero record. Diagnostic.
+  populatedReflectionParamCount(count: number): number;
+  delete(): void;
+}
+
+export interface GlassMeshRegistry {
+  // Decodes one octree node's glass payload and registers it, replacing any previous entry for
+  // that object. False for a malformed or empty payload, leaving the registry unchanged.
+  //
+  // The two slot arguments are different numbers here, unlike on the native path, and swapping
+  // them renders glass that does not follow its asset: modelRootSlot scopes the panel dedupe to
+  // one asset instance, while chunkModelRootIndex is stamped into every vertex and read back as
+  // chunkModelRoots[pos.w], so that one takes the chunk's fade slot.
+  //
+  // geometryPtr/panelPtr address THIS module's heap - _malloc here and copy the bytes in, since
+  // the attributes live in the engine module's. The AABB is the geometry attribute's own range.
+  registerObject(
+    objectId: number,
+    lodIndex: number,
+    modelRootSlot: number,
+    chunkModelRootIndex: number,
+    geometryPtr: number,
+    geometryByteCount: number,
+    panelPtr: number,
+    panelByteCount: number,
+    aabbMinX: number,
+    aabbMinY: number,
+    aabbMinZ: number,
+    aabbMaxX: number,
+    aabbMaxY: number,
+    aabbMaxZ: number,
+  ): boolean;
+  // Returns true if the object had glass, which is what says the buffers need rebuilding.
+  removeObject(objectId: number): boolean;
+  clear(): void;
+  isDirty(): boolean;
+  // Rebuilds the flattened buffers, keeping each panel from its deepest resident LOD. Stays dirty
+  // so uploadIfDirty still fires. Walks every registered object, so not per frame.
+  flattenIfDirty(): void;
+  uploadIfDirty(renderState: RenderState): void;
+  vertexCount(): number;
+  panelCount(): number;
+  delete(): void;
+}
+
+export interface WebGPUInterface {
+  importJsAdapter(adapter: GPUAdapter, parentPtr?: number): number;
+  importJsDevice(device: GPUDevice, parentPtr?: number): number;
+  importJsTexture(obj: GPUTexture, parentPtr?: number): number;
+}
+
+export interface MainModule {
+  Camera: new () => Camera;
+  RenderState: new () => RenderState;
+  SplatSet: new () => SplatSet;
+  GlassMeshRegistry: new () => GlassMeshRegistry;
+  vec4: new (x: number, y: number, z: number, w: number) => vec4;
+
+  SortType: {
+    RADIX_SORT: SortTypeValue;
+    OCTREE_SORT: SortTypeValue;
+    KDTREE_SORT: SortTypeValue;
+    STD_SORT: SortTypeValue;
+  };
+
+  TextureFormat: {
+    RGBA32_Float: TextureFormatValue;
+    RGBA16_Float: TextureFormatValue;
+    RG16_Float: TextureFormatValue;
+    RGBA32_UInt: TextureFormatValue;
+    RGBA32_SInt: TextureFormatValue;
+    RGBA16_UInt: TextureFormatValue;
+    RGBA16_SInt: TextureFormatValue;
+    RGBA8_UInt: TextureFormatValue;
+    RGBA8_SInt: TextureFormatValue;
+    RGBA8_UNorm: TextureFormatValue;
+    RGBA8_SNorm: TextureFormatValue;
+    RGBA16_UNorm: TextureFormatValue;
+    RGBA16_SNorm: TextureFormatValue;
+    BGRA8_UNorm: TextureFormatValue;
+    BC6HRGB_UFloat: TextureFormatValue;
+    BC6HRGB_Float: TextureFormatValue;
+    BC7RGBA_UNorm: TextureFormatValue;
+    BC7RGBA_UNormSrgb: TextureFormatValue;
+    BC3RGBA_UNorm: TextureFormatValue;
+    BC3RGBA_UNormSrgb: TextureFormatValue;
+    Depth16Unorm: TextureFormatValue;
+    Depth24Plus: TextureFormatValue;
+    Depth32Float: TextureFormatValue;
+  };
+
+  WebGPU: WebGPUInterface;
+
+  // Emscripten runtime, exported by modules/shark/CMakeLists.txt. The pointer-taking bindings
+  // above address THIS heap, so bytes from the engine module have to be staged through it.
+  // HEAPU8 is replaced whenever the heap grows, so read it fresh rather than caching it.
+  _malloc(byteCount: number): number;
+  _free(ptr: number): void;
+  readonly HEAPU8: Uint8Array;
+
+  uploadSplatSetData(
+    set: SplatSet,
+    renderState: RenderState,
+    start: number,
+  ): void;
+  uploadChunkFades(set: SplatSet, renderState: RenderState): void;
+  // One mat4 per model root, so cheap enough to call every frame while an asset is moving
+  uploadModelRootTransforms(set: SplatSet, renderState: RenderState): void;
+  processSplatSet(
+    camera: Camera,
+    set: SplatSet,
+    renderState: RenderState,
+    width: number,
+    height: number,
+    triangles: number,
+    projectOnGPU: boolean,
+    cullEllipsoid: boolean,
+    useAffineApprox: boolean,
+    depthSortOnGPU: boolean,
+    useInvZ: boolean,
+    rasterizeWithCompute: boolean,
+    useSOGS: boolean,
+    sortType: SortTypeValue,
+    skipSort: boolean,
+  ): number;
+  createRendererWGPUWithoutSurface(
+    colorTargetFormat: TextureFormatValue,
+  ): RendererWGPU;
+  /// Gives back the reference WebGPU.importJsTexture returned for a texture.
+  releaseImportedTexture(texture: number): void;
+  renderSplatSetToSceneTextures(
+    splatSet: SplatSet,
+    renderState: RenderState,
+    colorTarget: number,
+    depthTarget: number,
+    renderGES: boolean,
+  ): void;
+  // Render view registry, indexed as RenderViews.h orders it. setRenderView ignores an index
+  // Shark cannot produce.
+  setRenderView(viewIndex: number): void;
+  renderView(): number;
+  renderViewCount(): number;
+  renderViewName(viewIndex: number): string;
+  renderViewSupported(viewIndex: number): boolean;
+  // The next supported view, forwards for direction 1 and backwards for -1.
+  stepRenderView(from: number, direction: number): number;
+}
+
+declare function WebShark(
+  moduleArg?: Record<string, unknown>,
+): Promise<MainModule>;
+
+export default WebShark;