@webspatial/core-sdk 0.0.1-alpha

package/src/core/SpatialEntity.ts

@@ -0,0 +1,146 @@
+import { SpatialObject } from './SpatialObject'
+import { SpatialTransform } from './SpatialTransform'
+import { SpatialWindowContainer } from './SpatialWindowContainer'
+import { WebSpatial } from './private/WebSpatial'
+import { SpatialComponent } from './component'
+
+/**
+ * Entity used to describe an object that can be added to the scene
+ */
+export class SpatialEntity extends SpatialObject {
+  /**
+   * Transform corresponding to the entity
+   * note: updateTransform must be called for transform to be synced to rendering
+   */
+  transform = new SpatialTransform()
+
+  /** @hidden */
+  private _destroyed = false
+  /** @hidden */
+  private get _entity() {
+    return this._resource
+  }
+
+  /**
+   * Syncs the transform with the renderer, must be called to observe updates
+   */
+  async updateTransform() {
+    await WebSpatial.updateResource(this._entity, this.transform)
+  }
+
+  /**
+   * Syncs the zIndex with the renderer
+   */
+  async updateZIndex(zIndex: number) {
+    await WebSpatial.updateResource(this._entity, { zIndex })
+  }
+
+  private components: Map<Function, SpatialComponent> = new Map()
+
+  /**
+   * Attaches a component to the entity to be displayed
+   * [TODO] review pass by value vs ref and ownership model for this
+   */
+  async setComponent(component: SpatialComponent) {
+    await WebSpatial.setComponent(this._entity, component._resource)
+    this.components.set(component.constructor, component)
+  }
+
+  /**
+   * Removes a component from the entity
+   */
+  async removeComponent<T extends SpatialComponent>(
+    type: new (...args: any[]) => T,
+  ) {
+    var c = this.getComponent(type)
+    if (c != undefined) {
+      await WebSpatial.removeComponent(this._entity, c._resource)
+      this.components.delete(c.constructor)
+    }
+  }
+
+  /**
+   * Gets a component from the entity
+   */
+  getComponent<T extends SpatialComponent>(
+    type: new (...args: any[]) => T,
+  ): T | undefined {
+    return this.components.get(type) as T | undefined
+  }
+
+  /**
+   * @hidden
+   * Sets the window container that this entity should be rendered by (this does not effect resource ownership)
+   * @param wg the window container that should render this entity
+   */
+  async _setParentWindowContainer(wg: SpatialWindowContainer) {
+    await WebSpatial.updateResource(this._entity, {
+      setParentWindowContainerID: wg._wg.id,
+    })
+  }
+
+  /**
+   * Sets a parent entity, if that entity or its parents are attached to a window container, this entity will be displayed
+   * @param e parent entity or null to remove current parent
+   */
+  async setParent(e: SpatialEntity | null) {
+    await WebSpatial.updateResource(this._entity, {
+      setParent: e ? e._entity.id : '',
+    })
+  }
+
+  /**
+   * Sets the coordinate space of this entity (Default: App)
+   * "App" = game engine style coordinates in meters
+   * "Dom" = Windowing coordinates in dom units (eg. 0,0,0 is top left of window)
+   * "Root" = Coordinate space is ignored and content is displayed and updated as window container's root object, window containers can only have one root entity
+   * [TODO] review this api
+   * @param space coordinate space mode
+   */
+  async setCoordinateSpace(space: 'App' | 'Dom' | 'Root') {
+    await WebSpatial.updateResource(this._entity, { setCoordinateSpace: space })
+  }
+
+  /**
+   * Query the 3d boudning box of the entity
+   * @returns The bounding box of the entity
+   */
+  async getBoundingBox() {
+    var res: any = await WebSpatial.updateResource(this._entity, {
+      getBoundingBox: true,
+    })
+    return res.data as {
+      center: { x: number; y: number; z: number }
+      extents: { x: number; y: number; z: number }
+    }
+  }
+
+  /**
+   * Sets if the entity should be visible (default: True)
+   * @param visible
+   */
+  async setVisible(visible: boolean) {
+    await WebSpatial.updateResource(this._entity, { visible })
+  }
+
+  /**
+   * Removes a reference to the entity by the renderer and this object should no longer be used. [TODO] Attached components will not be destroyed
+   */
+  async destroy() {
+    this._destroyed = true
+    await WebSpatial.destroyResource(this._entity)
+  }
+
+  /**
+   * Check if destroy has been called
+   */
+  isDestroyed() {
+    return this._destroyed
+  }
+
+  // Set Entity name. Currently for debugging only.
+  /** @hidden */
+  async _setName(name: string) {
+    return WebSpatial.updateResource(this._entity, { name })
+  }
+}

package/src/core/SpatialHelper.ts

@@ -0,0 +1,197 @@
+import { SpatialViewComponent, StyleParam } from './component'
+import { Spatial } from './Spatial'
+import { SpatialEntity } from './SpatialEntity'
+import { SpatialSession } from './SpatialSession'
+import { Vec3 } from './SpatialTransform'
+
+/**
+ * Helper class used to quickly add spatial content to standard web pages
+ * [Experimental] expect APIs to potentially change in future versions
+ */
+export class SpatialHelper {
+  private static _instance: SpatialHelper | null = null
+  static get instance() {
+    if (this._instance) {
+      return this._instance
+    } else {
+      let spatial = new Spatial()
+      if (spatial.isSupported()) {
+        let session = spatial.requestSession()
+        if (session) {
+          this._instance = new SpatialHelper(session)
+          return this._instance
+        }
+      }
+    }
+    return null
+  }
+
+  constructor(public session: SpatialSession) {}
+
+  shape = {
+    createShapeEntity: async (shape = 'box') => {
+      var box = await this.session.createMeshResource({ shape: shape })
+      var mat = await this.session.createPhysicallyBasedMaterialResource()
+      await mat.update()
+
+      var customModel = await this.session.createModelComponent()
+      customModel.setMaterials([mat])
+      customModel.setMesh(box)
+
+      var boxEntity = await this.session.createEntity()
+      await boxEntity.setComponent(customModel)
+      boxEntity.transform.position.z = 0
+      boxEntity.transform.scale = new Vec3(0.5, 0.5, 0.5)
+      await boxEntity.updateTransform()
+      return boxEntity
+    },
+    createModelEntity: async (url: string) => {
+      var customModel = await this.session.createModelComponent({ url })
+      var boxEntity = await this.session.createEntity()
+      await boxEntity.setComponent(customModel)
+      await boxEntity.updateTransform()
+      return boxEntity
+    },
+    wrapInBoundingBoxEntity: async (entityToWrap: SpatialEntity) => {
+      var bb = await entityToWrap.getBoundingBox()
+
+      // Scale to fit
+      var targetSize = 1.0
+      var scale =
+        targetSize / Math.max(bb.extents.x, bb.extents.y, bb.extents.z)
+      entityToWrap.transform.scale.x = scale
+      entityToWrap.transform.scale.y = scale
+      entityToWrap.transform.scale.z = scale
+
+      // Center within view
+      entityToWrap.transform.position.x = -bb.center.x * scale
+      entityToWrap.transform.position.y = -bb.center.y * scale
+      entityToWrap.transform.position.z = -bb.center.z * scale
+      await entityToWrap.updateTransform()
+
+      // wrap in boudning box
+      var boudningEntity = await SpatialHelper.instance?.session.createEntity()!
+      await entityToWrap.setParent(boudningEntity!)
+      return boudningEntity
+    },
+  }
+
+  navigation = {
+    openPanel: async (
+      url: string,
+      options?: { resolution: { width: number; height: number } },
+    ) => {
+      if (options?.resolution) {
+        await this.session
+          .getCurrentWindowContainer()
+          ._setOpenSettings({ resolution: options.resolution })
+      }
+
+      // Create window container
+      var wg = await this.session.createWindowContainer({ style: 'Plain' })
+
+      // Create a root entity displaying a webpage
+      var ent = await this.session!.createEntity()
+      var i = await this.session!.createWindowComponent({ windowContainer: wg })
+      await i.loadURL(url)
+      await ent.setCoordinateSpace('Root')
+      await ent.setComponent(i)
+
+      // Add enitity the window container
+      await wg.setRootEntity(ent)
+
+      // Restore default size
+      await this.session
+        .getCurrentWindowContainer()
+        ._setOpenSettings({ resolution: { width: 900, height: 700 } })
+    },
+    openVolume: async (
+      url: string,
+      options?: { resolution: { width: number; height: number } },
+    ) => {
+      var wg = await this.session.createWindowContainer({ style: 'Volumetric' })
+
+      // Create a root view entity within the window container
+      var rootEnt = await this.session!.createEntity()
+      await rootEnt.setComponent(
+        await this.session!.createViewComponent({ windowContainer: wg }),
+      )
+      await rootEnt.setCoordinateSpace('Root')
+      await wg.setRootEntity(rootEnt)
+
+      // Add webpage to the window container
+      var ent = await this.session!.createEntity()
+      var i = await this.session!.createWindowComponent({ windowContainer: wg })
+      await i.loadURL(url)
+      if (options?.resolution) {
+        await i.setResolution(options.resolution.width, options.resolution.height)
+      } else {
+        await i.setResolution(1000, 1000)
+      }
+      ent.transform.position.z = -0.49
+      await ent.updateTransform()
+      await ent.setCoordinateSpace('App')
+      await ent.setComponent(i)
+      await ent.setParent(rootEnt)
+    },
+  }
+
+  dom = {
+    attachSpatialView: async (divOnPage: HTMLElement) => {
+      // Create SpatialView
+      var viewEnt = await this.session.createEntity()
+      await viewEnt.setCoordinateSpace('Dom') // Set coordinate space so its transform is relative to the webpage's pixels
+      await viewEnt.setComponent(await this.session.createViewComponent())
+
+      // Add to the root window component to display
+      var wc = await this.session.getCurrentWindowComponent()
+      var ent = await wc.getEntity()
+      await viewEnt.setParent(ent!)
+
+      // Keep spatialView positioned where the div is
+      var update = () => {
+        var rect = divOnPage.getBoundingClientRect()
+        viewEnt.transform.position.x = rect.x + rect.width / 2
+        viewEnt.transform.position.y = rect.y + rect.height / 2 + window.scrollY
+        viewEnt.updateTransform()
+        viewEnt
+          .getComponent(SpatialViewComponent)!
+          .setResolution(rect.width, rect.height)
+      }
+      var mo = new MutationObserver(update)
+      mo.observe(divOnPage, { attributes: true })
+      var ro = new ResizeObserver(update)
+      ro.observe(divOnPage)
+      const addRemoveObserver = new MutationObserver(mutations => {
+        mutations.forEach(mutation => {
+          mutation.removedNodes.forEach(node => {
+            if (node instanceof HTMLElement) {
+              update()
+            }
+          })
+          mutation.addedNodes.forEach(node => {
+            if (node instanceof HTMLElement) {
+              update()
+            }
+          })
+        })
+      })
+      addRemoveObserver.observe(document.body, {
+        childList: true,
+        subtree: true,
+      })
+      update()
+      return {
+        entity: viewEnt,
+      }
+    },
+  }
+
+  setBackgroundStyle = async (
+    style: StyleParam,
+    backgroundColor = '#00000000',
+  ) => {
+    document.documentElement.style.backgroundColor = backgroundColor
+    await this.session!.getCurrentWindowComponent().setStyle(style)
+  }
+}

package/src/core/SpatialObject.ts

@@ -0,0 +1,24 @@
+import { WebSpatial } from './private/WebSpatial'
+import { WebSpatialResource } from './private/WebSpatial'
+
+/**
+ * @hidden
+ * Parent class of spatial objects, should not be used directly
+ */
+export class SpatialObject {
+  /** @hidden */
+  constructor(
+    /** @hidden */
+    public _resource: WebSpatialResource,
+  ) {}
+
+  /**
+   * Marks resource to be released (it should no longer be used)
+   */
+  async destroy() {
+    await WebSpatial.destroyResource(this._resource)
+    await this.onDestroy()
+  }
+
+  protected async onDestroy() {}
+}