API Docs for: 1.0.0

ZSpaceEffect

Extends Component
Module: zspace
Parent Module: xeogl

A ZSpaceEffect makes its Scene viewable with a zSpace viewer.

Overview

  • Plug-and-play: just create a ZSpaceEffect within your xeogl Scene to make it viewable with a ZSpace display.
  • Activate or disable the ZSpaceEffect at any time to switch between zSpace mode and normal mono viewing mode.
  • Requires WebGL2 and WebVR support, which you'll have if you're running on a zSpace viewer.
  • Attaches to a Camera, defaults to its Scene's default camera if none is specified.
  • Don't attach different view or projection transform components to the Camera while the ZSpaceEffect is active.
  • You can however update the Camera's view transformation at any time, to move the viewpoint around.
  • Use a ZSpaceStylusControl to drag Entities around with the stylus.

Examples

Use these examples as boilerplates to get started:

Usage

In the following example we're going to set up a ZSpace-viewable scene with xeogl, defining the scene step-by-step to emphasize the plug-and-play design of xeogl's API. We'll assume that you've included all the required JavaScript libraries in your page - use the examples listed above as a boilerplate to get started.

1. Create an entity

First we'll create a simple torus-shaped Entity, which will be within xeogl's default Scene, since we're not defining the Scene component explicitly. Our Entity is also implicitly connected to the Scene's default Camera, since we didn't explicitly create a Camera for it either.

var entity = new xeogl.Entity({
    geometry: new xeogl.TorusGeometry(),
    material: new xeogl.PhongMaterial({
       diffuseMap: new xeogl.Texture({
           src: "textures/diffuse/uvGrid2.jpg"
       })
    })
});

2. Enable mouse/keyboard camera interaction

At this point we've got a textured torus floating in the middle of the canvas (which is also created automatically since we didn't specify one). Now we'll create a CameraControl, which immediately allows us to move our viewpoint around with the mouse and keyboard. This component is also within xeogl's default Scene and connected to the Scene's default Camera.

new CameraControl();

3. Enable ZSpace viewing

Now we can orbit, pan and zoom around the torus with the mouse and keyboard. Let's view it on a ZSpace display by dropping a ZSpaceEffect into our default Scene.

var zspaceEffect = new ZSpaceEffect();

The ZSpaceEffect immediately activates, so at this point if we're running on a ZSpace device we'll have a stereo view of the torus, which we can view with the stereo glasses.

At any point we can always disable the ZSpaceEffect effect to switch between normal WebGL mono viewing mode:

zspaceEffect.active = false; // Back to normal mono viewing..
zspaceEffect.active = true; // ..and then back to ZSpace stereo mode.

Detecting support

The ZSpaceEffect will fire a "supported" event once it has determined whether or not the browser supports a zSpace viewer:

zspaceEffect.on("supported", function (supported) {

       if (!supported) {

           // Not a zSpace device

           this.error("This computer is not a ZSpace viewer!"); // Log error on the xeogl.ZSpaceEffect

           // At this point you could just destroy the xeogl.ZSpaceEffect to make it detach from the Camera
       }
   });

Handling stylus input

Reading the current World-space position and direction of the stylus:

var stylusPos = zspaceEffect.stylusPos;
var stylusDir = zspaceEffect.stylusDir;

Note that these properties only have meaningful values once the ZSpaceEffect has fired at least one stylusMoved event.

Subscribing to stylus movement:

zspaceEffect.on("stylusMoved", function() {
    var stylusPos = zspaceEffect.stylusPos;
    var stylusDir = zspaceEffect.stylusDir;
    //...
});

Reading the current state of each stylus button:

var button0 = zspaceEffect.stylusButton0; // Boolean
var button1 = zspaceEffect.stylusButton1;
var button2 = zspaceEffect.stylusButton2;

Subscribing to change of state of each stylus button:

zspaceEffect.on("stylusButton0", function(value) { // Boolean value
    this.log("stylusButton0 = " + value);
});

zspaceEffect.on("stylusButton1", function(value) {
    this.log("stylusButton1 = " + value);
});

zspaceEffect.on("stylusButton2", function(value) {
    this.log("stylusButton2 = " + value);
});

Picking an Entity with the stylus when button 0 is pressed:

zspaceEffect.on("stylusButton0", function() {

   var hit = zspaceEffect.scene.pick({
       pickSurface: true,
       origin: zspaceEffect.stylusPos,
       direction: zspaceEffect.stylusDir
   });

   if (hit) { // Picked an Entity

       var entity = hit.entity;

       // Other properties on the hit result:

       var primitive = hit.primitive; // Type of primitive that was picked, usually "triangles"
       var primIndex = hit.primIndex; // Position of triangle's first index in the picked Entity's Geometry's indices array
       var indices = hit.indices; // UInt32Array containing the triangle's vertex indices
       var localPos = hit.localPos; // Float32Array containing the picked Local-space position within the triangle
       var worldPos = hit.worldPos; // Float32Array containing the picked World-space position within the triangle
       var viewPos = hit.viewPos; // Float32Array containing the picked View-space position within the triangle
       var bary = hit.bary; // Float32Array containing the picked barycentric position within the triangle
       var normal = hit.normal; // Float32Array containing the interpolated normal vector at the picked position on the triangle
       var uv = hit.uv; // Float32Array containing the interpolated UV coordinates at the picked position on the triangle

       //...
   }
});

Constructor

ZSpaceEffect

(
  • [scene]
  • [cfg]
)

Parameters:

  • [scene] Scene optional

    Parent Scene - creates this ZSpaceEffect in the default Scene when omitted.

  • [cfg] optional

    Configs

    • [id] String optional

      Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

    • [meta] String:Object optional

      Optional map of user-defined metadata to attach to this ZSpaceEffect.

    • [camera] String | Camera optional

      ID or instance of a Camera for this ZSpaceEffect. Must be within the same Scene as this ZSpaceEffect. Defaults to the parent Scene's default instance, camera.

    • [nearClip=0.1] Number optional

      Position of the near clipping plane on the View-space Z-axis.

    • [farClip=10000] Number optional

      Position of the far clipping plane on the View-space Z-axis.

    • [displaySize=0.521,0.293] Float32Array optional

      The viewer display size.

    • [displayResolution=1920,1080] Float32Array optional

      The viewer display resolution.

    • [canvasOffset=0,0] Float32Array optional

      The offset of the canvas' corner from the edge of the screen - needed for correct tracking of glasses and stylus. Leave this at its default value if the canvas is to fill the entire screen.

    • [active=true] Boolean optional

      Whether or not this ZSpaceEffect is initially active.

Methods

create

(
  • [cfg]
  • [instanceId]
)

Convenience method for creating a Component within this Component's Scene.

You would typically use this method to conveniently instantiate components that you'd want to share (ie. "instance") among your Entities.

The method is given a component type, configuration and optional instance ID, like so:

var material = myComponent.create(xeogl.PhongMaterial, {
     diffuse: [1,0,0],
     specular: [1,1,0]
}, "myMaterial");

The first time you call this method for the given type and instanceId, this method will create the PhongMaterial, passing the given attributes to the component's constructor.

If you call this method again, specifying the same type and instanceId, the method will return the same component instance that it returned the first time, and will ignore the configuration:

var material2 = component.create(xeogl.PhongMaterial, { specular: [1,1,0] }, "myMaterial");

So in this example, our PhongMaterial will continue to have the red specular and diffuse color that we specified the first time.

Each time you call this method with the same type and instanceId, the Scene will internally increment a reference count for the component instance. You can release the shared component instance with a call to Scene/putSharedComponent:method, and once you have released it as many times as you got it, the Scene will destroy the component.

Parameters:

  • [cfg] optional

    Configuration for the component instance - only used if this is the first time you are getting the component, ignored when reusing an existing instance.

  • [instanceId] String | Number optional

    Identifies the shared component instance. Note that this is not used as the ID of the component - you can specify the component ID in the cfg parameter.

Returns:

:

destroy

()

Destroys this component.

Fires a destroyed event on this Component.

Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.

TODO: describe effect with respect to #create

error

(
  • message
)

Logs an error for this component to the JavaScript console.

The console message will have this format: [ERROR] [<component type> =<component id>: <message>

Also fires the message as an error event on the parent Scene.

Parameters:

  • message String

    The message to log

fire

(
  • event
  • value
  • [forget=false]
)

Fires an event on this component.

Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.

Parameters:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

isType

(
  • type
)
Boolean

Tests if this component is of the given type, or is a subclass of the given type.

The type may be given as either a string or a component constructor.

This method works by walking up the inheritance type chain, which this component provides in property superTypes, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.

Examples:

var myRotate = new xeogl.Rotate({ ... });

myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Entity); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Entity

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

True if this component is of given type or is subclass of the given type.

log

(
  • message
)

Logs a console debugging message for this component.

The console message will have this format: [LOG] [<component type> <component id>: <message>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • handle
)

Cancels an event subscription that was previously made with on or once.

Parameters:

  • handle String

    Publication handle

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

Handle to the subscription, which may be used to unsubscribe with {@link #off}.

once

(
  • event
  • callback
  • [scope=this]
)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is handled.

This is equivalent to calling on, and then calling off inside the callback function.

Parameters:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

Properties

active

Boolean

Flag which indicates whether this ZSpaceEffect is active or not.

Note that this ZSpaceEffect can still be activated when the browser does not support ZSpace.

Fires an active event on change.

Default: true

active

Boolean

Flag which indicates whether this ZSpaceEffect is active or not.

Note that this ZSpaceEffect can still be activated when the browser does not support ZSpace.

Fires an active event on change.

Default: true

camera

Camera

The Camera attached to this ZSpaceEffect.

The ZSpaceEffect will attach a Projection to its Camera if the Camera does not have one already, replacing whatever projection transform component was already attached.

Must be within the same Scene as this ZSpaceEffect. Defaults to the parent Scene's default camera when set to a null or undefined value.

No other component should modify the state of the Camera while it's attached to this ZSpaceEffect. There is no prevention or check for that, so if that happens you'll get unexpected results.

camera

Camera

The Camera attached to this ZSpaceEffect.

The ZSpaceEffect will attach a Projection to its Camera if the Camera does not have one already, replacing whatever projection transform component was already attached.

Must be within the same Scene as this ZSpaceEffect. Defaults to the parent Scene's default camera when set to a null or undefined value.

No other component should modify the state of the Camera while it's attached to this ZSpaceEffect. There is no prevention or check for that, so if that happens you'll get unexpected results.

canvasOffset

Float32Array

The offset of the canvas' corner from the edge of the screen - needed for correct tracking of glasses and stylus.

Leave this at it's default value of [0,0] if the canvas is to fill the entire screen.

Fires a canvasOffset event on change.

Default: [0, 0]

canvasOffset

Float32Array

The offset of the canvas' corner from the edge of the screen - needed for correct tracking of glasses and stylus.

Leave this at it's default value of [0,0] if the canvas is to fill the entire screen.

Fires a canvasOffset event on change.

Default: [0, 0]

destroyed

Boolean

True as soon as this Component has been destroyed

displayResolution

Float32Array

The display resolution.

Fires a displayResolution event on change.

Default: [1920, 1080]

displayResolution

Float32Array

The display resolution.

Fires a displayResolution event on change.

Default: [1920, 1080]

displaySize

Float32Array

The display size.

Fires a displaySize event on change.

Default: [0.521, 0.293]

displaySize

Float32Array

The display size.

Fires a displaySize event on change.

Default: [0.521, 0.293]

farClip

Number

Position of this ZSpaceEffect's far plane on the positive View-space Z-axis.

Fires a farClip event on change.

Default: 10000.0

farClip

Number

Position of this ZSpaceEffect's far plane on the positive View-space Z-axis.

Fires a farClip event on change.

Default: 10000.0

id

String final

Unique ID for this Component within its parent Scene.

isDefault

Boolean

Indicates whether this is one of the Scene's built-in Components.

json

JSON final

JSON object containing the state of this Component.

metadata

Object

Arbitrary, user-defined metadata on this component.

nearClip

Number

Position of this ZSpaceEffect's near plane on the positive View-space Z-axis.

Fires a nearClip event on change.

Default: 0.1

nearClip

Number

Position of this ZSpaceEffect's near plane on the positive View-space Z-axis.

Fires a nearClip event on change.

Default: 0.1

scene

Scene final

The parent Scene that contains this Component.

string

String final

Inherited from Component but overwritten in src/component.js:1058

String containing the serialized JSON state of this Component.

stylusButton0

Boolean final

Whether or not the first button is down on the stylus.

Fires a stylusButton0 event on change.

Default: false

stylusButton0

Boolean final

Whether or not the first button is down on the stylus.

Fires a stylusButton0 event on change.

Default: false

stylusButton1

Boolean final

Whether or not the second button is down on the stylus.

Fires a stylusButton1 event on change.

Default: false

stylusButton1

Boolean final

Whether or not the second button is down on the stylus.

Fires a stylusButton1 event on change.

Default: false

stylusButton2

Boolean final

Whether or not the third button is down on the stylus.

Fires a stylusButton2 event on change.

Default: false

stylusButton2

Boolean final

Whether or not the third button is down on the stylus.

Fires a stylusButton2 event on change.

Default: false

stylusCameraMatrix

Float32Array final

The current world matrix for the stylus.

Fires a stylusMoved event on change.

stylusCameraMatrix

Float32Array final

The current camera matrix for the stylus.

Fires a stylusMoved event on change.

stylusCameraMatrix

Float32Array final

The current camera matrix for the stylus.

Fires a stylusMoved event on change.

stylusCameraMatrix

Float32Array final

The current world matrix for the stylus.

Fires a stylusMoved event on change.

stylusOrientation

Float32Array final

The current World-space direction of the stylus.

Fires a stylusMoved event on change.

stylusOrientation

Float32Array final

The current World-space direction of the stylus.

Fires a stylusMoved event on change.

stylusPos

Float32Array final

The current World-space position of the stylus.

Fires a stylusMoved event on change.

stylusPos

Float32Array final

The current World-space position of the stylus.

Fires a stylusMoved event on change.

superTypes

Array of String final

An array of strings that indicates the chain of super-types within this component's inheritance hierarchy.

For example, if this component is a Rotate, which extends Transform, which in turn extends Component, then this property will have the value:

["xeogl.Component", "xeogl.Transform"]
                    

Note that the chain is ordered downwards in the hierarchy, ie. from super-class down towards sub-class.

type

String final

JavaScript class name for this Component.

This is used when loading Scenes from JSON, and is included in the JSON representation of this Component, so that this class may be instantiated when loading it from the JSON representation.

For example: "xeogl.AmbientLight", "xeogl.ColorTarget", "xeogl.Lights" etc.

viewerScale

Number final

The current viewer scale factor.

The ZSpaceEffect automatically calculates this from the distance between the eye and the point of interest.

Fires a stylusButton2 event on change.

Default: 1

viewerScale

Number final

The current viewer scale factor.

The ZSpaceEffect automatically calculates this from the distance between the eye and the point of interest.

Fires a stylusButton2 event on change.

Default: 1

Events

active

Fired whenever this ZSpaceEffect's active property changes.

Event Payload:

  • value Object

    The property's new value

active

Fired whenever this ZSpaceEffect's active property changes.

Event Payload:

  • value Object

    The property's new value

camera

Fired whenever this ZSpaceEffect's camera property changes.

Event Payload:

  • value Object

    The property's new value

camera

Fired whenever this ZSpaceEffect's camera property changes.

Event Payload:

  • value Object

    The property's new value

canvasOffset

Float32Array

Fired whenever this ZSpaceEffect's canvasOffset property changes.

Event Payload:

  • value Object

    The property's new value

canvasOffset

Float32Array

Fired whenever this ZSpaceEffect's canvasOffset property changes.

Event Payload:

  • value Object

    The property's new value

destroyed

Fired when this Component is destroyed.

displayResolution

Float32Array

Fired whenever this ZSpaceEffect's displayResolution property changes.

Event Payload:

  • value Object

    The property's new value

displayResolution

Float32Array

Fired whenever this ZSpaceEffect's displayResolution property changes.

Event Payload:

  • value Object

    The property's new value

displaySize

Float32Array

Fired whenever this ZSpaceEffect's displaySize property changes.

Event Payload:

  • value Object

    The property's new value

displaySize

Float32Array

Fired whenever this ZSpaceEffect's displaySize property changes.

Event Payload:

  • value Object

    The property's new value

farClip

Fired whenever this ZSpaceEffect's farClip property changes.

Event Payload:

  • value Object

    The property's new value

farClip

Fired whenever this ZSpaceEffect's farClip property changes.

Event Payload:

  • value Object

    The property's new value

nearClip

Fired whenever this ZSpaceEffect's nearClip property changes.

Event Payload:

  • value Object

    The property's new value

nearClip

Fired whenever this ZSpaceEffect's nearClip property changes.

Event Payload:

  • value Object

    The property's new value

stylusButton0

Fired whenever this ZSpaceEffect's first button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusButton0

Fired whenever this ZSpaceEffect's first button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusButton1

Fired whenever this ZSpaceEffect's second button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusButton1

Fired whenever this ZSpaceEffect's second button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusButton2

Fired whenever this ZSpaceEffect's third button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusButton2

Fired whenever this ZSpaceEffect's third button is pressed or released.

Event Payload:

  • value Object

    True if the button is down.

stylusMoved

Fired whenever this ZSpaceEffect's stylus moves.

stylusMoved

Fired whenever this ZSpaceEffect's stylus moves.

supported

Boolean

Notifies whether or not zSpace is supported in this browser.

Event Payload:

  • value Object

    Indicates whether or not zSpace is supported.

supported

Boolean

Notifies whether or not zSpace is supported in this browser.

Event Payload:

  • value Object

    Indicates whether or not zSpace is supported.