API Docs for: 0.7.0

Entity

Extends Component
Module: entities
Parent Module: xeogl

An Entity is a 3D object within a Scene.

Overview

  • An Entity represents a WebGL draw call.
  • Each Entity has six components: Geometry, Material, Transform, an EmphasisMaterial for ghosting, an EmphasisMaterial for highlighting, and an OutlineMaterial for outlining.
  • By default, Entities in the same Scene share the same "global" flyweight instances of those components amongst themselves. The default component instances are provided by the Scene's geometry, material, transform, ghostMaterial, outlineMaterial, highlightMaterial properties, respectively.
  • An Entity with all defaults is a white unit-sized box centered at the World-space origin.
  • Customize your Entities by attaching your own instances of those component types, to override the defaults as needed.
  • For best performance, reuse as many of the same component instances among your Entities as possible.

Usage

Creating an Entity

Creating a minimal Entity that has all the default components:

var entity = new xeogl.Entity(); // A white unit-sized box centered at the World-space origin

Since our Entity has all the default components, we can get those off either the Entity or its Scene:

entity.material.diffuse = [1.0, 0.0, 0.0];  // This is the same Material component...

var scene = entity.scene;
scene.material.diffuse  = [1.0, 0.0, 0.0];  // ...as this one.

In practice, we would provide (at least) our own Geometry and Material for the Entity:

var entity = new xeogl.Entity({
    geometry: new xeogl.TeapotGeometry(),
    material: new xeogl.MetallicMaterial({
        baseColor: [1.0, 1.0, 1.0]
    })
});

Controlling visibility

Show or hide an Entity by setting its visible property:

entity.visible = false; // Hide
entity.visible = true; // Show (default)

Controlling clipping

By default, an Entity will be clipped by the Scene's clipping planes (if you've created some).

Make an Entity unclippable by setting its clippable property false:

entity.clippable = false; // Default is true

Controlling rendering order

Control the order in which an Entity is rendered relative to others by setting its layer property. You would normally do this when you need to ensure that transparent Entities are rendered in back-to-front order for correct alpha blending.

Assign entity to layer 0 (all Entities are in layer 0 by default):

entity.layer = 0;

Create another Entity in a higher layer, that will get rendered after layer 0:

var entity2 = new xeogl.Entity({
    geometry: new xeogl.Sphere(),
    layer: 1
});

Geometry

An Entity has a Geometry which describes its shape. When we don't provide it with a Geometry, it will have the Scene's geometry by default.

Creating an Entity with its own Geometry:

var entity = new xeogl.Entity({
    geometry: new xeogl.TeapotGeometry()
});

Dynamically replacing the Geometry:

entity.geometry = new xeogl.CylinderGeometry();

Getting geometry arrays:

ver geometry = entity.geometry;

var primitive = geometry,primitive;        // Default is "triangles"
var positions = geometry.positions;        // Local-space vertex positions
var normals = geometry.normals;            // Local-space vertex Normals
var uv = geometry.uv;                      // UV coordinates
var indices = entity.geometry.indices;     // Vertex indices for pimitives

The Entity also has a convenience property which provides the vertex positions in World-space, ie. after they have been transformed by the Entity's Transform:

// These are internally generated on-demand and cached. To free the cached
// vertex World positions when you're done with them, set this property to null or undefined
var worldPositions = entity.worldPositions;

Material

An Entity has a Material, which describes its appearance. When we don't provide it with a Material, it will have the Scene's material by default.

Creating an Entity with its own custom Geometry and Material:

var entity = new xeogl.Entity({
    geometry: new xeogl.TeapotGeometry(),
    material: new xeogl.MetallicMaterial({
        baseColor: [0.0, 0.0, 1.0],
        metallic: 1.0,
        roughness: 1.0,
        emissive: [0.0, 0.0, 0.0],
        alpha: 1.0
    })
});

Dynamically replacing the Material:

entity.material = new xeogl.SpecularMaterial({
    diffuse: [1.0, 1.0, 1.0],
    specular: [1.0, 1.0, 1.0],
    glossiness: 1.0,
    emissive: [0.0, 0.0, 0.0]
    alpha: 1.0
})

Animating the Material's diffuse color - making the Entity rapidly pulse red:

entity.scene.on("tick", function(e) {
   var t = e.time - e.startTime; // Millisecs
   entity.material.diffuse = [0.5 + Math.sin(t * 0.01), 0.0, 0.0]; // RGB
});

Transforming

An Entity has a Transform, which positions, sizes and orients it within the World-space coordinate system. When we don't provide it with a Transform, it will have the Scene's transform by default (which is the identity transform unless modified).

Transforms can also be connected into hierarchies.

Creating an Entity with its own Geometry and Transform hierarchy:

var entity = new xeogl.Entity({

    geometry: new xeogl.TeapotGeometry(),

    transform: new xeogl.Translate({eapot
       xyz: [-5, 0, 0],
       parent: new xeogl.Rotate({
           xyz: [0,1,0],
           angle: 45
       })
    })
});

Dynamically replacing the Entity's Transform hierarchy:

entity.transform = new xeogl.Rotate({
    xyz: [0,1,0],
    angle: 45
    parent: new xeogl.Rotate({
        xyz: [1,0,0],
        angle: 180
    })
});

Animating the Transform hierarchy:

entity.scene.on("tick", function() {
   entity.transform.angle += 0.5;
   entity.transform.parent.angle += 0.5;
});

Ghosting

Ghost an Entity by setting its ghosted property true. The Entity's EmphasisMaterial then controls its appearance while ghosted.

When we don't provide it with a EmphasisMaterial, it will have the Scene's ghostMaterial by default.

In the example below, we'll create a ghosted Entity with its own EmphasisMaterial.

var entity = new xeogl.Entity({
   geometry: new xeogl.TeapotGeometry(),
   material: new xeogl.PhongMaterial({
       diffuse: [0.2, 0.2, 1.0]
   }),
   ghostMaterial: new xeogl.EmphasisMaterial({
       edges: true,
       edgeColor: [0.2, 1.0, 0.2],
       edgeAlpha: 1.0,
       edgeWidth: 2,
       vertices: true,
       vertexColor: [0.6, 1.0, 0.6],
       vertexAlpha: 1.0,
       vertexSize: 8,
       fill: true,
       fillColor: [0, 0, 0],
       fillAlpha: 0.7
   }),
   ghosted: true
});

Examples

Highlighting

Highlight an Entity by setting its highlighted property true. The Entity's highlighting EmphasisMaterial then controls its appearance while highlighted.

When we don't provide it with a EmphasisMaterial for highlighting, it will have the Scene's highlightMaterial by default.

In the example below, we'll create a highlighted Entity with its own EmphasisMaterial.

var entity = new xeogl.Entity({
   geometry: new xeogl.TeapotGeometry(),
   material: new xeogl.PhongMaterial({
       diffuse: [0.2, 0.2, 1.0]
   }),
   highlightMaterial: new xeogl.EmphasisMaterial({
       color: [1.0, 1.0, 0.0],
       alpha: 0.6
   }),
   highlighted: true
});

Examples

Outlining

Outline an Entity by setting its outlined property true. The Entity's OutlineMaterial then controls its appearance while outlined.

When we don't provide it with an OutlineMaterial, it will have the Scene's outlineMaterial by default.

In the example below, we'll create a outlined Entity with its own OutlineMaterial.

var entity = new xeogl.Entity({
   geometry: new xeogl.TeapotGeometry(),
   material: new xeogl.PhongMaterial({
       diffuse: [0.2, 0.2, 1.0]
   }),
   outlineMaterial: new xeogl.OutlineMaterial({
       color: [1.0, 1.0, 0.0],
       alpha: 0.6,
       width: 5
   }),
   outlined: true
});

Local-space boundary

We can get an Entity's Local-space boundary at any time, as both an axis-aligned bounding box (AABB) and an object-aligned bounding box (OBB).

The Local-space boundary is the boundary of the Entity's Geometry, without any transforms applied.

Getting the Local-space boundary as an AABB:

var aabb = entity.geometry.aabb; // [xmin, ymin, zmin, xmax, ymax, zmax]

Getting the Local-space boundary as an OBB:

var obb = entity.geometry.obb; // Flat array containing eight 3D corner vertices of a box

Examples

World-space boundary

We can get an Entity's World-space boundary at any time, as both an axis-aligned bounding box (AABB) and an object-aligned bounding box (OBB).

The World-space boundary is the boundary of the Entity's Geometry after the Entity's Transform has been applied to it.

Getting the World-space boundary as an AABB:

var aabb = entity.aabb; // [xmin, ymin, zmin, xmax, ymax, zmax]

Getting the World-space boundary as an OBB:

var obb = entity.obb; // Flat array containing eight 3D corner vertices of a box

Subscribing to updates of the World-space boundary, which occur whenever the Entity's Transform or Geometry have been updated.

entity.on("boundary", function() {
    var aabb = entity.aabb;
    var obb = entity.obb;
});

An Entity's Scene also has an getAABB, which returns the collective World-space axis-aligned boundary of the Entities and/or Models with the given IDs:

var scene = entity.scene;

scene.getAABB(); // Gets collective boundary of all entities in the viewer
scene.getAABB("saw"); // Gets collective boundary of all entities in a model
scene.getAABB(["saw", "gearbox"]); // Gets collective boundary of all entities in two models
scene.getAABB("saw#0.1"); // Get boundary of an entity
scene.getAABB(["saw#0.1", "saw#0.2"]); // Get collective boundary of two entities

Excluding from boundary calculations

The Scene aabb and Model aabb properties provide AABBs that include the boundaries of all contained Entities, except those Entities that have their collidable properties set false.

Toggle that inclusion like so:

entity.collidable = false; // Exclude entity from calculation of its Scene/Model boundary
entity.collidable = true; // Include entity in calculation of its Scene/Model boundary

Setting this false is useful when an Entity represents some object, such as a control gizmo, that you don't want to consider as being a contributor to a Scene or Model boundary. It also helps performance, since boundaries will not need dynamically re-calculated whenever the Entity's boundary changes after a Transform or Geometry update.

Examples

Skyboxing

An Entity has a stationary property that will cause it to never translate with respect to the viewpoint, while still rotationg, as if always far away.

This is useful for using Entities as skyboxes, like this:

new xeogl.Entity({

    geometry: new xeogl.BoxGeometry({
        xSize: 1000,
        ySize: 1000,
        zSize: 1000
    }),

    material: new xeogl.PhongMaterial({
        diffuseMap: new xeogl.Texture({
           src: "textures/diffuse/uvGrid2.jpg"
        })
    }),

    stationary: true // Locks position with respect to viewpoint
});

Examples

Billboarding

An Entity has a billboard property that can make it behave as a billboard.

Two billboard types are supported:

  • Spherical billboards are free to rotate their Entities in any direction and always face the Camera perfectly.
  • Cylindrical billboards rotate their Entities towards the Camera, but only about the Y-axis.

Note that Scale transformations to have no effect on billboarded Entities.

The example below shows a box that remains rotated directly towards the viewpoint, using spherical billboarding:

new xeogl.Entity({

    geometry: new xeogl.BoxGeometry(),

    material: new xeogl.PhongMaterial({
        diffuseMap: new xeogl.Texture({
           src: "textures/diffuse/uvGrid2.jpg"
        })
    }),

    billboard: "spherical" // Or "cylindrical"
});

Examples

Shadows

[Work-in-progress]

Constructor

Entity

(
  • [scene]
  • [cfg]
)

Parameters:

  • [scene] Scene optional

    Parent Scene - creates this Entity within xeogl's default Xeogl/scene:property by default.

  • [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 Entity.

    • [geometry] String | Geometry optional

      ID or instance of a Geometry to attach to this Entity. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, geometry, which is a 2x2x2 box.

    • [material] String | Material optional

      ID or instance of a Material to attach to this Entity. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, material.

    • [transform] String | Transform optional

      ID or instance of a modelling transform to attach to this Entity. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, transform (which is an identity matrix which performs no transformation).

    • [visible=true] Boolean optional

      Indicates if this Entity is visible.

    • [culled=true] Boolean optional

      Indicates if this Entity is culled from view.

    • [pickable=true] Boolean optional

      Indicates if this Entity is pickable.

    • [clippable=true] Boolean optional

      Indicates if this Entity is clippable by Clips.

    • [collidable=true] Boolean optional

      Whether this Entity is included in boundary calculations.

    • [castShadow=true] Boolean optional

      Whether this Entity casts shadows.

    • [receiveShadow=true] Boolean optional

      Whether this Entity receives shadows.

    • [outlined=false] Boolean optional

      Whether an outline is rendered around this entity, as configured by the Entity's OutlineMaterial component.

    • [outlineMaterial] String | OutlineMaterial optional

      ID or instance of an OutlineMaterial to attach to this Entity. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, outlineMaterial.

    • [ghosted=false] Boolean optional

      Whether this entity is rendered ghosted, as configured by ghostMaterial.

    • [ghostMaterial] String | EmphasisMaterial optional

      ID or instance of an EmphasisMaterial to attach to this Entity. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, ghostMaterial.

    • [highlight=false] Boolean optional

      Whether this entity is rendered highlighted, as configured by highlightMaterial.

    • [highlightMaterial] String | EmphasisMaterial optional

      ID or instance of an EmphasisMaterial to attach to this Entity to define highlighted appearance. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, highlightMaterial.

    • [selected=false] Boolean optional

      Whether this entity is rendered selected, as configured by selectedMaterial.

    • [selectedMaterial] String | EmphasisMaterial optional

      ID or instance of an EmphasisMaterial to attach to this Entity to define selected appearance. Must be within the same Scene as this Entity. Defaults to the parent Scene's default instance, selectedMaterial.

    • [layer=0] Number optional

      Indicates this Entity's rendering priority, typically used for transparency sorting,

    • [stationary=false] Boolean optional

      Disables the effect of view transform translations for this Entity. This is useful for skybox Entities.

    • [billboard="none"] String optional

      Specifies the billboarding behaviour for this Entity. Options are "none", "spherical" and "cylindrical".

    • [loading=false] Boolean optional

      Flag which indicates that this Entity is freshly loaded.

Methods

create

(
  • [cfg]
)

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

The method is given a component configuration, like so:

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

Parameters:

  • [cfg] optional

    Configuration for the component instance.

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

hasSubs

(
  • event
)
Boolean

Returns true if there are any subscribers to the given event on this component.

Parameters:

  • event String

    The event

Returns:

Boolean:

True if there are any subscribers to the given event on this component.

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

aabb

Float32Array final

World-space axis-aligned 3D boundary (AABB) of this Entity.

The AABB is represented by a six-element Float32Array containing the min/max extents of the axis-aligned volume, ie. [xmin, ymin,zmin,xmax,ymax, zmax].

billboard

String

Specifies the billboarding behaviour for this Entity.

Options are:

  • "none" - (default) - No billboarding.
  • "spherical" - Entity is billboarded to face the viewpoint, rotating both vertically and horizontally.
  • "cylindrical" - Entity is billboarded to face the viewpoint, rotating only about its vertically axis. Use this mode for things like trees on a landscape.

Default: "none"

castShadow

Boolean

Indicates whether this Entity casts shadows.

Default: true

center

Float32Array final

World-space 3D center of this Entity.

clippable

Boolean

Indicates whether this Entity is clippable by Clips components.

Default: true

collidable

Boolean

Indicates whether this Entity is included in boundary calculations.

Default: true

colorize

Float32Array

RGBA colorize color, multiplies by the outgoing fragment color and transparency.

Default: [1.0, 1.0, 1.0, 1.0]

culled

Boolean

Indicates whether or not this Entity is currently culled from view.

The Entity is only rendered when visible is true and culled is false.

Default: false

destroyed

Boolean

True as soon as this Component has been destroyed

geometry

Geometry

The Geometry attached to this Entity.

Must be within the same Scene as this Entity. Defaults to the parent Scene's default geometry (a simple box) when set to a null or undefined value.

Updates Entity/boundary, Entity/worldObb and Entity/center

ghosted

Boolean

Flag which indicates if this Entity is rendered with ghost effect.

The ghost effect is configured via the Entity's ghostMaterial.

Default: false

ghostMaterial

EmphasisMaterial

The EmphasisMaterial attached to this Entity.

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

highlighted

Boolean

Indicates whether this Entity is highlighted.

The highlight effect is configured via the Entity's highlightMaterial.

Default: false

highlightMaterial

EmphasisMaterial

The EmphasisMaterial attached to this Entity.

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

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.

layer

Number

Indicates this Entity's rendering order.

This can be set on multiple transparent Entities, to make them render in a specific order for correct alpha blending.

Default: 0

material

Material

The Material attached to this Entity.

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

metadata

Object

Arbitrary, user-defined metadata on this component.

obb

Float32Array final

World-space oriented 3D boundary (OBB) of this Entity.

The OBB is represented by a 32-element Float32Array containing the eight vertices of the box, where each vertex is a homogeneous coordinate having [x,y,z,w] elements.

outlined

Boolean

Indicates whether this Entity is rendered with an outline.

The outline effect is configured via the Entity's outlineMaterial component.

Default: false

outlineMaterial

OutlineMaterial

The OutlineMaterial attached to this Entity.

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

pickable

Boolean

Indicates whether this entity is pickable or not.

Picking is done via calls to Canvas/pick:method.

Default: true

receiveShadow

Boolean

Indicates whether this Entity receives shadows.

Default: true

scene

Scene final

The parent Scene that contains this Component.

selected

Boolean

Indicates whether this Entity is selected.

The selected effect is configured via the Entity's selectedMaterial.

Default: false

selectedMaterial

EmphasisMaterial

The EmphasisMaterial attached to this Entity.

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

stationary

Boolean

Flag which indicates whether this Entity is stationary or not.

Setting this true will disable the effect of view transform translations for this Entity, while still alowing it to rotate. This is useful for skybox Entities.

Default: false

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.

transform

Transform

The Local-to-World-space (modelling) Transform attached to this Entity.

Must be within the same Scene as this Entity. Defaults to the parent Scene's default transform (an identity matrix) when set to a null or undefined value.

Updates Entity/boundary, Entity/worldObb and Entity/center

type

String final

JavaScript class name for this Component.

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

visible

Boolean

Indicates whether this Entity is visible or not.

The Entity is only rendered when visible is true and culled is false.

Default: true

worpdPositions

Float32Array final

World-space vertex positions of this Entity.

These are internally generated on-demand and cached. To free the cached vertex World positions when you're done with them, set this property to null or undefined.

Events

boundary

Fired whenever this Entity's World-space boundary changes.

Get the latest boundary from the Entity's aabb and obb properties.

destroyed

Fired when this Component is destroyed.

picked

Fired when this Entity is picked via a call to the Canvas/pick:method method on the parent Scene's Canvas.

Event Payload:

  • entityId String

    The ID of this Entity.

  • canvasX Number

    The X-axis Canvas coordinate that was picked.

  • canvasY Number

    The Y-axis Canvas coordinate that was picked.