BuildableModel
A BuildableModel is a Model that provides a "stateful builder" API through which you can procedurally generate xeogl content.
Overview
- A BuilderModel implements the Builder pattern.
- Create various assets within a BuilderModel, such as Geometries and Materials, then create Meshes that use those assets.
- The BuilderModel then owns those components and will destroy them when you call its clear() or destroy() methods.
- A BuildableModel can be transformed within World space by attaching it to a Transform.
- A BuildableModel provides its World-space boundary as a Boundary3D.
Examples
Usage
A BuildableModel containing ten textured boxes with random sizes and positions:
var model = new xeogl.BuildableModel();
// Add a BoxGeometry asset
buildableModel.createAsset("boxGeometry", {
type: "xeogl.BoxGeometry"
});
// Add a PhongMaterial asset
buildableModel.createAsset("gridMaterial", {
type: "xeogl.PhongMaterial",
ambient: [0.9, 0.3, 0.9],
shininess: 30,
diffuseMap: {
src: "textures/diffuse/gridMaterial.jpg"
}
});
// Set the BoxGeometry asset as the current geometry
buildableModel.setGeometry("boxGeometry");
// Set the PhongMaterial asset as the current material
buildableModel.setMaterial("gridMaterial");
// Build ten meshes with random sizes and positions,
// that each get the current geometry and material
for (var i = 0; i < 10; i++) {
buildableModel.setScale(Math.random() * 10 + 1, Math.random() * 10 + 1, Math.random() * 10 + 1);
buildableModel.setPosition(Math.random() * 100 - 50, Math.random() * 100 - 50, Math.random() * 100 - 50);
buildableModel.createMesh();
}
Constructor
BuildableModel
-
[scene]
-
[cfg]
Parameters:
-
[scene]
Scene optional -
[cfg]
optionalConfigs
-
[id]
String optionalOptional ID, unique among all components in the parent Scene, generated automatically when omitted.
-
[entityType]
String optionalOptional entity classification when using within a semantic data model. See the Object documentation for usage.
-
[meta]
String:Object optionalOptional map of user-defined metadata to attach to this BuildableModel.
-
[position=[0,0,0]
Float32Array optionalThe BuildableModel's local 3D position.
-
[scale=[1,1,1]
Float32Array optionalThe BuildableModel's local scale.
-
[rotation=[0,0,0]
Float32Array optionalThe BuildableModel's local rotation, as Euler angles given in degrees.
-
[matrix=[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
Float32Array optionalThe BuildableModel's local transform matrix. Overrides the position, scale and rotation parameters.
-
Index
Methods
Properties
- aabb
- aabbVisible
- castShadow
- center
- childIDs
- childMap
- children
- clippable
- collidable
- colorize
- components
- culled
- DEGTORAD
- destroyed
- edges
- entities
- entityIds
- entityType
- entityTypeIds
- entityTypes
- ghosted
- guid
- guidObjects
- highlighted
- id
- matrix
- meshes
- metadata
- model
- numChildren
- numComponents
- objects
- opacity
- outlined
- parent
- pickable
- position
- quaternion
- RADTODEG
- receiveShadow
- rotation
- scale
- scene
- selected
- type
- types
- visible
- worldMatrix
- worldNormalMatrix
Events
Methods
angleVec3
-
v
-
w
Gets the angle between two vectors
Returns:
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]
optionalConfiguration for the component instance.
Returns:
createAsset
-
assetId
-
cfg
Adds an asset to this BuildableModel.
The asset is given as a configuration object, to be lazy-instantiated as soon as an mesh is built from it with BuildableModel/mesh:method.
Usage
Adding a PhongMaterial asset with ID "gridMaterial":
buildableModel.createAsset("gridMaterial", {
type: "xeogl.PhongMaterial",
ambient: [0.9, 0.3, 0.9],
shininess: 30,
diffuseMap: {
src: "textures/diffuse/uvGrid2.jpg"
}
});
Adding a BoxGeometry asset with ID "boxGeometry":
buildableModel.createAsset("boxGeometry", {
type: "xeogl.BoxGeometry",
xSize: 1.0,
ySize: 1.0,
zSize: 1.0
});
Parameters:
-
assetId
String | NumberA unique ID for the asset.
-
cfg
Configuration object for the asset.
createMesh
-
[id]
Creates an Mesh with whatever assets and states are currently set on this BuildableModel.
Parameters:
-
[id]
String | Number optionalA unique ID for the new Mesh.
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
StringThe 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
StringThe event type name
-
value
ObjectThe event parameters
-
[forget=false]
Boolean optionalWhen true, does not retain for subsequent subscribers
geometry
-
assetId
Selects the Geometry asset that will be added to each Mesh subsequently created with BuildableModel/mesh:method.
The given ID must belong to a Geometry asset that was added previously with BuildableModel/asset:method.
Parameters:
-
assetId
String | NumberThe asset ID.
hasSubs
-
event
Returns true if there are any subscribers to the given event on this component.
Parameters:
-
event
StringThe event
Returns:
True if there are any subscribers to the given event on this component.
isType
-
type
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 | FunctionComponent type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.
Returns:
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>
Parameters:
-
message
StringThe message to log
lookAtMat4v
-
pos
-
target
-
up
-
dest
Returns a 4x4 'lookat' viewing transform matrix.
Parameters:
Returns:
dest if specified, a new mat4 otherwise
off
-
subId
Cancels an event subscription that was previously made with Component#on() or Component#once().
Parameters:
-
subId
StringPublication subId
on
-
event
-
callback
-
[scope=this]
Subscribes to an event on this component.
The callback is be called with this component as scope.
Parameters:
-
event
StringThe event
-
callback
FunctionCalled fired on the event
-
[scope=this]
Object optionalScope for the callback
Returns:
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
StringData event to listen to
-
callback
Function(data)Called when fresh data is available at the event
-
[scope=this]
Object optionalScope for the callback
removeChildren
()
Removes all children.
reset
()
Resets the state of this BuildableModel to defaults.
rotate
-
angle
Rotates about the given local axis by the given increment.
Parameters:
-
angle
NumberAngle increment in degrees.
rotateX
-
angle
Rotates about the local X-axis by the given increment.
Parameters:
-
angle
NumberAngle increment in degrees.
rotateY
-
angle
Rotates about the local Y-axis by the given increment.
Parameters:
-
angle
NumberAngle increment in degrees.
rotateZ
-
angle
Rotates about the local Z-axis by the given increment.
Parameters:
-
angle
NumberAngle increment in degrees.
scaleMat4c
-
x
-
y
-
z
-
m
Efficiently post-concatenates a scaling to the given matrix.
setColorize
-
r
-
g
-
b
-
z
Sets the RGBA colorize factors each Mesh subsequently created with BuildableModel/mesh:method.
Usage
buildableModel.setColorize(0.4, 0.4, 0.4, 1.0);
Parameters:
-
r
NumberIndicates the amount of red.
-
g
NumberIndicates the amount of green.
-
b
NumberIndicates the amount of blue.
-
z
NumberIndicates the alpha.
setMaterial
-
assetId
Selects the Material asset that will be added to each Mesh subsequently created with BuildableModel/mesh:method.
The given ID must belong to a Material asset that was added previously with BuildableModel/asset:method.
Parameters:
-
assetId
String | NumberThe asset ID.
setPosition
-
x
-
y
-
z
Sets the 3D position of each Mesh subsequently created with BuildableModel/mesh:method.
Parameters:
-
x
NumberPosition on X-axis.
-
y
NumberPosition on Y-axis.
-
z
NumberPosition on Z-axis.
setRotation
-
x
-
y
-
z
Sets the 3D Euler rotation angles for each Mesh subsequently created with BuildableModel/mesh:method.
Parameters:
-
x
NumberAngle on X-axis in degrees.
-
y
NumberAngle on Y-axis in degrees.
-
z
NumberAngle on Z-axis in degrees.
setRotationAaxis
-
a
-
b
-
c
Sets the order of 3D rotations for each Mesh subsequently created with BuildableModel/mesh:method.
Usage
The X, Y and Z axis are identified as 0, 1, 2
respectively.
buildableModel.setRotationAxis(0,1,2); // X, Y, Z
buildableModel.setRotationAxis(2,0,1); // Z, X, Y
buildableModel.setRotationAxis(1,2,0); // Y, Z, X
Parameters:
-
a
NumberIndicates the first rotation axis.
-
b
NumberIndicates the second rotation axis.
-
c
NumberIndicates the third rotation axis.
setScale
-
x
-
y
-
z
Sets the 3D scale of each Mesh subsequently created with BuildableModel/mesh:method.
Parameters:
-
x
NumberScale on X-axis.
-
y
NumberScale on Y-axis.
-
z
NumberScale on Z-axis.
translate
-
axis
-
distance
Translates along local space vector by the given increment.
Parameters:
-
axis
Float32ArrayNormalized local space 3D vector along which to translate.
-
distance
NumberDistance to translate along the vector.
translateX
-
distance
Translates along the local X-axis by the given increment.
Parameters:
-
distance
NumberDistance to translate along the X-axis.
Properties
aabb
Float32Array
final
World-space 3D axis-aligned bounding box (AABB).
Represented by a six-element Float32Array containing the min/max extents of the
axis-aligned volume, ie. [xmin, ymin,zmin,xmax,ymax, zmax]
.
aabbVisible
Boolean
Indicates if the 3D World-space axis-aligned bounding box (AABB) is visible.
Default: false
castShadow
Boolean
Indicates if casting shadows.
Default: true
center
Float32Array
final
World-space 3D center.
clippable
Boolean
Indicates if clippable.
Clipping is done by the Scene's Clips component.
Default: true
collidable
Boolean
Indicates if included in boundary calculations.
Default: true
colorize
Float32Array
RGB colorize color, multiplies by the rendered fragment color.
Default: [1.0, 1.0, 1.0]
components
String:Component
All contained Components, mapped to their IDs.
culled
Boolean
Default: false
DEGTORAD
Number
The number of radiians in a degree (0.0174532925).
destroyed
Boolean
True as soon as this Component has been destroyed
edges
Boolean
Indicates if edges are emphasized.
Default: false
entities
String:Object
final
Objects in this Model that have entity types, mapped to their IDs.
Each Object is registered in this map when its entityType is set to value.
entityType
String
final
Optional entity classification when using within a semantic data model.
See the Object documentation on "Applying a semantic data model" for usage.
Default: null
entityTypes
String:{String:xeogl.Component}
final
For each entity type, a map of IDs to Objects of that entity type.
Each Object is registered in this map when its entityType is assigned a value.
ghosted
Boolean
Indicates if ghosted.
Each ghosted Object is registered in its Scene's ghostedEntities map while its entityType is set to a value.
Default: false
guid
String
final
Globally unique identifier.
This is unique not only within the Scene, but throughout the entire universe.
Only defined when given to the constructor.
guidObjects
String:Object
final
highlighted
Boolean
Indicates if highlighted.
Each highlighted Object is registered in its Scene's highlightedEntities map while its entityType is set to a value.
Default: false
matrix
Float32Array
Local matrix.
Default: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
model
Model
final
The Model which contains this Component, if any.
Will be null if this Component is not in a Model.
numComponents
Number
Number of contained Components.
opacity
Number
Opacity factor, multiplies by the rendered fragment alpha.
This is a factor in range [0..1]
.
Default: 1.0
outlined
Boolean
Indicates if outlined.
Default: false
parent
Group
The parent.
The parent Group may also be set by passing the Object to the Group/Model's Group/addChild:method method.
pickable
Boolean
Whether or not to allow picking.
Picking is done via calls to Scene#pick().
Default: true
position
Float32Array
Local translation.
Default: [0,0,0]
quaternion
Float32Array
Local rotation quaternion.
Default: [0,0,0, 1]
RADTODEG
Number
The number of degrees in a radian.
receiveShadow
Boolean
Indicates if receiving shadows.
Default: true
rotation
Float32Array
Local rotation, as Euler angles given in degrees, for each of the X, Y and Z axis.
Default: [0,0,0]
scale
Float32Array
Local scale.
Default: [1,1,1]
selected
Boolean
Indicates if selected.
Each selected Object is registered in its Scene's selectedEntities map while its entityType is set to a value.
Default: false
type
String
final
JavaScript class name for this Component.
For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.
types
String:{String:xeogl.Component}
visible
Boolean
Indicates if visible.
Only rendered when visible is true and culled is false.
Each visible Object is registered in its Scene's visibleEntities map while its entityType is set to a value.
Default: true
worldMatrix
Float32Array
The World matrix.
worldNormalMatrix
Float32Array
This World normal matrix.
Default: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
Events
destroyed
Fired when this Component is destroyed.