API Docs for:

# CubicBezierCurve

Extends Curve
Module: curves
Parent Module: xeogl

A CubicBezierCurve is a Curve along which a 3D position can be animated.

## Overview

• As shown in the diagram below, a CubicBezierCurve is defined by four control points.
• You can sample a point and a CubicBezierCurve/tangent:property vector on a CubicBezierCurve for any given value of t in the range [0..1].
• When you set t on a CubicBezierCurve, its point and CubicBezierCurve/tangent:property properties will update accordingly.
• To build a complex path, you can combine an unlimited combination of CubicBezierCurves, QuadraticBezierCurves and SplineCurves into a Path.

## Usage

#### Animation along a CubicBezierCurve

Let's create a CubicBezierCurve, subscribe to updates on its point, tangent and t properties, then vary its t property over time:

``````var curve = new xeogl.CubicBezierCurve({
v0: [-10, 0, 0],
v1: [-5, 15, 0],
v2: [20, 15, 0],
v3: [10, 0, 0]
});

curve.on("point", function(point) {
this.log("curve.point=" + JSON.stringify(point));
});

curve.on("tangent", function(tangent) {
this.log("curve.tangent=" + JSON.stringify(tangent));
});

curve.on("t", function(t) {
this.log("curve.t=" + t);
});

curve.scene.on("tick", function(e) {
curve.t = (e.time - e.startTime) * 0.01;
});``````

#### Randomly sampling points

Use CubicBezierCurve's getPoint and getTangent methods to sample the point and vector at a given t:

``````curve.scene.on("tick", function(e) {

var t = (e.time - e.startTime) * 0.01;

var point = curve.getPoint(t);
var tangent = curve.getTangent(t);

this.log("t=" + t + ", point=" + JSON.stringify(point) + ", tangent=" + JSON.stringify(tangent));
});``````

#### Sampling multiple points

Use CubicBezierCurve's getPoints method to sample a list of equidistant points along it. In the snippet below, we'll build a Geometry that renders a line along the curve. Note that we need to flatten the points array for consumption by the Geometry.

``````var geometry = new xeogl.Geometry({
positions: xeogl.math.flatten(curve.getPoints(50))
});``````

## Constructor

### `CubicBezierCurve`

(
• `[scene]`
• `[cfg]`
)

#### Parameters:

• `[scene]` Scene optional

Parent Scene.

• `[cfg]` optional

Configuration

• `[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 CubicBezierCurve.

• `[v0=[0,0,0]` optional

The starting point.

• `[v1=[0,0,0]` optional

The first control point.

• `[v2=[0,0,0]` optional

The middle control point.

• `[v3=[0,0,0]` optional

The ending point.

• `[t=0]` optional

Current position on this CubicBezierCurve, in range between 0..1.

## 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.

:

### `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

### `getPoint`

(
• `t`
)
Array of Number

Returns point on this CubicBezierCurve at the given position.

#### Parameters:

• `t` Number

Position to get point at.

Array of Number:

}

### `getPoints`

(
• `divisions`
)
Array of Array

Samples points on this Curve, at the given number of equally-spaced divisions.

#### Parameters:

• `divisions` Number

The number of divisions.

#### Returns:

Array of Array:

Array of sampled 3D points.

### `getTangent`

(
• `t`
)
Array of Number

Returns a normalized tangent vector on this Curve at the given position.

#### Parameters:

• `t` Number

Position to get tangent at.

#### Returns:

Array of Number:

} Normalized tangent vector

### `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 Component/superTypes:property, 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.Mesh); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Mesh``````

#### 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`

(
• `subId`
)

Cancels an event subscription that was previously made with Component#on() or Component#once().

#### Parameters:

• `subId` String

Publication subId

### `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 subIdd.

This is equivalent to calling Component#on(), and then calling Component#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

### `destroyed`

Boolean

True as soon as this Component has been destroyed

### `id`

String final

Unique ID for this Component within its parent Scene.

### `length`

Number

Length of this Curve.

### `metadata`

Object

Arbitrary, user-defined metadata on this component.

### `model`

Model final

The Model which contains this Component, if any.

Will be null if this Component is not in a Model.

### `point`

Array of Number

Point on this CubicBezierCurve at position t.

### `scene`

Scene final

The parent Scene that contains this Component.

### `t`

Number

Current position of progress along this CubicBezierCurve.

Automatically clamps to range [0..1].

Fires a t event on change.

Default: 0

### `tangent`

Array of Number

Tangent on this Curve at position t.

### `type`

String final

JavaScript class name for this Component.

For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.

### `v0`

Float32Array

Starting point on this CubicBezierCurve.

Fires a v0 event on change.

Default: [0.0, 0.0, 0.0]

### `v1`

Float32Array

First control point on this CubicBezierCurve.

Fires a v1 event on change.

Default: [0.0, 0.0, 0.0]

### `v2`

Float32Array

Second control point on this CubicBezierCurve.

Fires a v2 event on change.

Default: [0.0, 0.0, 0.0]

### `v3`

Float32Array

End point on this CubicBezierCurve.

Fires a v3 event on change.

Default: [0.0, 0.0, 0.0]

## Events

### `destroyed`

Fired when this Component is destroyed.

### `t`

Fired whenever this CubicBezierCurve's t property changes.

• `value` Object

The property's new value

### `v0`

Fired whenever this CubicBezierCurve's v0 property changes.

• `value` Object

The property's new value

### `v1`

Fired whenever this CubicBezierCurve's v1 property changes.

• `value` Object

The property's new value

### `v2`

Fired whenever this CubicBezierCurve's v2 property changes.

• `value` Object

The property's new value

### `v3`

Fired whenever this CubicBezierCurve's v3 property changes.

• `value` Object