API Docs for: 1.0.0

Modes

Extends Component
Module: rendering
Parent Module: xeogl

A Modes toggles various xeogl modes and capabilities for attached Entities.

Overview

  • Though the rendering modes are defined by various different components attached to the Entities, Modes components provide a single point through which you can toggle them on or off.
  • A Modes may be shared among multiple Entities to toggle rendering modes for them as a group.

Usage

In this example we have a Modes that toggles rendering modes for two Entities. The properties of the Modes are initialised to their default values.

// Create a Modes with default properties
var modes = new xeogl.Modes(scene, {
   collidable: true,           // Include Entities in boundary calculations
   pickable: true,             // Enable picking
   clippable true,             // Enable effect of xeogl.Clip components
   transparent : false,        // Disable transparency
   backfaces : true,           // Render backfaces
   frontface : "ccw",          // Front faces have counter-clockwise vertex winding
   outline: false              // Don't outline for emphasis
});

var boxGeometry = new xeogl.BoxGeometry();

// Create two Entities whose rendering modes will be controlled by our Modes

var entity1 = new xeogl.Entity({
    geometry: boxGeometry,
    modes: modes,
    translate: new xeogl.Translate({
       xyz: [3, 0, 0]
    })
});

var entity2 = new xeogl.Entity(scene, {
    geometry: boxGeometry,
    modes: modes,
    translate: new xeogl.Translate({
       xyz: [3, 0, 0]
    })
});

Constructor

Modes

(
  • [scene]
  • [cfg]
)

Parameters:

  • [scene] Scene optional

    Parent Scene - creates this Modes 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 Modes.

    • [pickable=true] Boolean optional

      Whether to enable picking.

    • [clippable=true] Boolean optional

      Whether to enable clippable by Clips.

    • [transparent=false] Boolean optional

      Whether to enable the transparency effect created by Materials when they have opacity < 1.0. This mode will set attached Entities transparent (ie. to be rendered in a transparency pass with blending enabled etc), while the opacity will indicate the degree of their transparency (ie. where opacity of 0.0 indicates maximum translucency and opacity of 1.0 indicates minimum translucency).

    • [backfaces=false] Boolean optional

      Whether to render Geometry backfaces.

    • [frontface="ccw"] Boolean optional

      The winding order for Geometry front faces - "cw" for clockwise, or "ccw" for counter-clockwise.

    • [collidable=true] Boolean optional

      Whether attached Entities are included in boundary-related calculations. Set this false if the Entities are things like helpers or indicators that should not be included in boundary calculations.

    • [castShadow=true] Boolean optional

      Whether attached Entities cast shadows.

    • [receiveShadow=true] Boolean optional

      Whether attached Entities receive shadows.

    • [outline=false] Boolean optional

      Whether an outline is drawn around the attached Entities.

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

backfaces

Boolean

Whether this Modes enables backfaces to be visible on attached Entities.

The backfaces will belong to Geometry compoents that are also attached to the Entities.

Fires a backfaces event on change.

Default: false

castShadow

Boolean

Whether attached Entities casts shadows.

Fires a castShadow event on change.

Default: true

clippable

Boolean

Whether this Modes enables clippable of attached Entities.

clippable is done by Clips that are also attached to the Entities.

Fires a clippable event on change.

Default: true

collidable

Boolean

Whether attached Entities are included in boundary-related calculations.

Set this false if the Entities are things like helpers or indicators that should not be included in boundary calculations.

For example, when set false, the World-space boundary of all attached Entities would not be considered when calculating the World-space boundary of their Scene.

Fires a collidable event on change.

Default: true

destroyed

Boolean

True as soon as this Component has been destroyed

frontface

String

Indicates the winding direction of front faces on attached Entities.

The faces will belong to Geometry components that are also attached to the Entities.

Fires a frontface event on change.

Default: "ccw"

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.

outline

Boolean

Whether an outline is drawn around attached Entities.

Fires a outline event on change.

Default: false

pickable

Boolean

Whether this Modes enables picking of attached Entities.

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

Fires a pickable event on change.

Default: true

receiveShadow

Boolean

Whether attached Entities receives shadows.

Fires a receiveShadow event on change.

Default: true

scene

Scene final

The parent Scene that contains this Component.

string

String final

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

String containing the serialized JSON state of this Component.

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.

transparent

Boolean

Whether this Modes sets attached Entities transparent.

When true. this property will set attached Entities transparent (ie. to be rendered in a transparency pass with blending enabled etc), while the opacity will be used to indicate the degree of their transparency (ie. where opacity of 0.0 indicates maximum translucency and opacity of 1.0 indicates minimum translucency).

Fires a transparent event on change.

Default: false

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.

Events

backfaces

Fired whenever this Modes' backfaces property changes.

Event Payload:

  • value Object

    The property's new value

castShadow

Fired whenever this Modes' castShadow property changes.

Event Payload:

  • value Object

    The property's new value

clippable

Fired whenever this Modes' clippable property changes.

Event Payload:

  • value Object

    The property's new value

collidable

Fired whenever this Modes' collidable property changes.

Event Payload:

  • value Object

    The property's new value

destroyed

Fired when this Component is destroyed.

frontface

Fired whenever this Modes' frontface property changes.

Event Payload:

  • value Object

    The property's new value

outline

Fired whenever this Modes' outline property changes.

Event Payload:

  • value Object

    The property's new value

pickable

Fired whenever this Modes' pickable property changes.

Event Payload:

  • value Object

    The property's new value

receiveShadow

Fired whenever this Modes' receiveShadow property changes.

Event Payload:

  • value Object

    The property's new value

transparent

Fired whenever this Modes' transparent property changes.

Event Payload:

  • value Object

    The property's new value