Scene3D
Scene3D is a root node of 3d scene graph, other kinds of 3D object need to be add as children into it. This class provides operating functions to control nodes in scene tree and record which nodes are changed in current frame. The effect and renderable content also can be managed here.
Scene3D is a root node of 3d scene graph, other kinds of 3D object need to be add as children into it. This class provides operating functions to control nodes in scene tree and record which nodes are changed in current frame. The effect and renderable content also can be managed here.
Extends
Constructors
Constructor
new Scene3D():
Scene3D
Returns
Scene3D
Overrides
Properties
DefaultUp
staticDefaultUp:Vector3
Every objects in 3D space must have a default up direction.
Default Value
Vector3(0, 1, 0)
Inherited from
id
id:
number
Unique number for each object3D instance.
Inherited from
categoryId
categoryId:
string
Reserved attribute
Inherited from
sourceType
sourceType:
string
Record the object rendered as instance or other type.
Inherited from
updateDirtyId
updateDirtyId:
number
The number is the frame id which this object is changed or participates change of scene graph. If this value equals to frame id - 1,
Default Value
-1 means no change happen
Inherited from
name
name:
string
The name of this object, it is empty if useless.
Inherited from
isObject3D
isObject3D:
boolean
Used to check type of this or extended instance. This value should not be changed by user.
Inherited from
parent
parent:
Nullable<Object3D>
Object’s parent node in the scene graph. An object can have at most one parent.
Inherited from
children
children:
Object3D[]
Array with object’s children.
Remarks
See Group| Group for information on manually grouping objects.
Inherited from
up
up:
Vector3
This is used by the lookAt method, for example, to determine the orientation of the result. Default is DefaultUp.
Inherited from
worldMatrixUpdateTimestamp
worldMatrixUpdateTimestamp:
number
Record when this object’s world matrix last updated.
Inherited from
Object3D.worldMatrixUpdateTimestamp
transformChanged
transformChanged:
boolean
Record whether the object’s any attribute| attribute is updated.
Inherited from
visibleChanged
visibleChanged:
boolean
Inherited from
matrixWorld
matrixWorld:
Matrix4
The global transform of the object. If the Object3D has no parent, then it’s identical to the local transform matrix.
Inherited from
matrixWorldNeedsUpdate
matrixWorldNeedsUpdate:
boolean
When this is set, it calculates the matrixWorld in that frame and resets this property to false.
Default Value
false
Inherited from
Object3D.matrixWorldNeedsUpdate
netVisibility
netVisibility:
boolean
Record if the object is really visible in rendering process. If the Object3D has no parent, it would be set by visible;
Inherited from
localMatrixNeedUpdate
localMatrixNeedUpdate:
boolean
When this is set, it calculates the model matrix in that frame and resets this property to false.
Default Value
false
Inherited from
Object3D.localMatrixNeedUpdate
sceneId
readonlysceneId:number
Mark this scene with a unique number.
scene
readonlyscene:Scene3D
The scene which this object belong to.
Overrides
attachedNodes
readonlyattachedNodes:Map<number,Object3D>
lights
lights:
Set<Light>
Store all lights source which need to apply on the models of scene.
clippingPlanes
clippingPlanes:
Plane[]
Clipping planes setting for scene. When setting changed, should call notifyClippingChanged to update
enableSceneClipping
enableSceneClipping:
boolean
If enable the scene level clipping
type
type:
string
The type of current Object3D.
Deprecated
coordSysHelper
coordSysHelper:
Nullable<CoordinateSystemHelper>
The CoordinateSystemHelper| coordSysHelper of this scene, if it needs to be rendered.
renderProxyManager
renderProxyManager:
RenderProxyManager
The instance of RenderProxyManager that is used to process some optimization.
anyDrawableChanged
anyDrawableChanged:
boolean
If any nodes of scene is added, deleted or changed, this would be set to true.
Default Value
false
shadowMapNeedsUpdate
shadowMapNeedsUpdate:
boolean
userData
readonlyuserData:Record<keyofany,any>
Inherited from
_uuid
_uuid:
any
Inherited from
uuid
uuid:
string
Inherited from
_listeners
_listeners:
Map<Symbol,Listener<never>[]>
Inherited from
Accessors
layers
Get Signature
get layers():
Layers
Returns
Set Signature
set layers(
v):void
Parameters
v
Returns
void
Inherited from
interactionLayers
Get Signature
get interactionLayers():
Layers|undefined
Returns
Layers | undefined
Set Signature
set interactionLayers(
v):void
Parameters
v
Layers | undefined
Returns
void
Inherited from
groupLayer
Get Signature
get groupLayer():
Layers|undefined
Returns
Layers | undefined
Set Signature
set groupLayer(
v):void
Parameters
v
Layers | undefined
Returns
void
Inherited from
position
Get Signature
get position():
Vector3
Returns
Set Signature
set position(
_position):void
A vector representing the object’s local position.
Parameters
_position
Returns
void
Inherited from
rotation
Get Signature
get rotation():
Euler
Returns
Set Signature
set rotation(
rotation):void
Object’s local rotation, in radians.
Parameters
rotation
Returns
void
Inherited from
quaternion
Get Signature
get quaternion():
Quaternion
Returns
Set Signature
set quaternion(
_quaternion):void
Object’s local rotation as a Quaternion.
Remarks
See Quaternion for more details.
Parameters
_quaternion
Returns
void
Inherited from
scale
Get Signature
get scale():
Vector3
Returns
Set Signature
set scale(
_scale):void
The object’s local scale.
Default Value
Vector3( 1, 1, 1 )
Parameters
_scale
Returns
void
Inherited from
matrix
Get Signature
get matrix():
Matrix4
The local transform matrix.
Returns
Set Signature
set matrix(
value):void
Parameters
value
Returns
void
Inherited from
visible
Get Signature
get visible():
boolean
Object gets rendered if true.
Default Value
true
Returns
boolean
Set Signature
set visible(
value):void
Parameters
value
boolean
Returns
void
Inherited from
isAnythingChanged
Get Signature
get isAnythingChanged():
boolean
Get Scene3D.anythingChanged| anythingChanged to know if any change of node happen in scene graph. When there is any change happening on the sets which store the all nodes of this scene, the value will be set to true, it does not allow user to arrange.
Returns
boolean
isShadowMapNeedsUpdate
Get Signature
get isShadowMapNeedsUpdate():
boolean
Returns
boolean
businessTag
Get Signature
get businessTag():
string
Returns
string
Set Signature
set businessTag(
v):void
Parameters
v
string
Returns
void
Inherited from
Methods
freeGPU()
freeGPU():
void
Returns
void
Inherited from
syncData()
syncData():
void
Returns
void
Inherited from
updateVisibility()
updateVisibility():
boolean
Scene will check the object’s visibility in each render and make change netVisibility based on its and parent’s visible.
Returns
boolean
Inherited from
clearChangeMark()
clearChangeMark():
void
Set marks of change to false include attributeChanged| attribute, transform and visible.
Returns
void
Inherited from
setMatrixUpdated()
setMatrixUpdated():
void
If the local matrix is changed, use this method to manually refresh data in scene graph.
Returns
void
Tips
It’s better to use notifySceneChange() as an alternative.
Inherited from
notifySceneChange()
notifySceneChange():
void
Use this method to manually refresh data in scene graph and draw again. The engine may not notify every change of the scene. If any effect is not changed with the parameters, use this may solve.
Returns
void
Inherited from
setMatrixDirty()
setMatrixDirty():
void
If the local matrix or world matrix is changed, use this method to make engine refresh data in scene graph automatically. This method will set matrixWorldNeedsUpdate and localMatrixNeedUpdate to true.
Returns
void
Inherited from
updateWorldRenderData()
updateWorldRenderData(
updateID):boolean
Change matrixWorldNeedsUpdate and worldMatrixUpdateTimestamp state. This method will refresh data of world matrix by updateMatrixWorld
Parameters
updateID
number
This number is used to identify the render.
Returns
boolean
Inherited from
Object3D.updateWorldRenderData
isFlipped()
isFlipped():
boolean
If there are zero or two negative numbers in xyz, return false, otherwise return true.
Returns
boolean
Inherited from
localToWorld()
localToWorld(
vector):Vector3
Converts the vector from local space to world space.
Parameters
vector
A vector represents a position in local (object) coordinate.
Returns
Inherited from
worldToLocal()
worldToLocal(
vector):Vector3
Updates the vector from world space to local space.
Parameters
vector
A vector in world coordinate.
Returns
Inherited from
applyMatrix()
applyMatrix(
matrix):void
Applies the matrix transform to the object and updates the object’s position, rotation and scale.
Parameters
matrix
A matrix represents the information of transform.
Returns
void
Inherited from
applyQuaternion()
applyQuaternion(
q):this
Applies the rotation represented by the quaternion to the object.
Parameters
q
A Quaternion represents the information of rotation.
Returns
this
Inherited from
setRotationFromAxisAngle()
setRotationFromAxisAngle(
axis,angle):void
Calls setFromAxisAngle( axis, angle ) on the Quaternion.
Parameters
axis
A normalized vector in object space.
angle
number
Angle in radians.
Returns
void
Inherited from
Object3D.setRotationFromAxisAngle
setRotationFromEuler()
setRotationFromEuler(
euler):void
Calls Quaternion.setRotationFromEuler| setRotationFromEuler(euler, true) on the Quaternion.
Parameters
euler
Euler angle specifying rotation amount.
Returns
void
Inherited from
setRotationFromMatrix()
setRotationFromMatrix(
m):void
Calls setFromRotationMatrix(m) on the Quaternion.
Parameters
m
Euler angle specifying rotation amount.
Returns
void
Inherited from
Object3D.setRotationFromMatrix
setRotationFromQuaternion()
setRotationFromQuaternion(
q):void
Copy the given quaternion to object’s quaternion.
Parameters
q
Euler angle specifying rotation amount.
Returns
void
Inherited from
Object3D.setRotationFromQuaternion
rotateOnAxis()
rotateOnAxis(
axis,angle):this
Rotate an object along an axis in object space. The axis is assumed to be normalized.
Parameters
axis
A normalized vector in object space.
angle
number
Angle in radians.
Returns
this
Inherited from
rotateOnWorldAxis()
rotateOnWorldAxis(
axis,angle):this
Rotate an object along an axis in world space. The axis is assumed to be normalized. Method Assumes no rotated parent.
Parameters
axis
A normalized vector in object space.
angle
number
Angle in radians.
Returns
this
Inherited from
rotateX()
rotateX(
angle):this
Rotates the object around x axis in local space.
Parameters
angle
number
The angle to rotate in radians.
Returns
this
Inherited from
rotateY()
rotateY(
angle):this
Rotates the object around x axis in local space.
Parameters
angle
number
The angle to rotate in radians.
Returns
this
Inherited from
rotateZ()
rotateZ(
angle):this
Rotates the object around x axis in local space.
Parameters
angle
number
The angle to rotate in radians.
Returns
this
Inherited from
translateOnAxis()
translateOnAxis(
axis,distance):this
Translate an object by distance along an axis in object space. The axis is assumed to be normalized.
Parameters
axis
A normalized vector in object space.
distance
number
The distance to translate.
Returns
this
Inherited from
translateX()
translateX(
distance):this
Translates object along x axis in object space by distance units.
Parameters
distance
number
The distance to translate.
Returns
this
Inherited from
translateY()
translateY(
distance):this
Translates object along y axis in object space by distance units.
Parameters
distance
number
The distance to translate.
Returns
this
Inherited from
translateZ()
translateZ(
distance):this
Translates object along z axis in object space by distance units.
Parameters
distance
number
The distance to translate.
Returns
this
Inherited from
lookAt()
lookAt(
_x):void
Rotates the object to face to a point in world space. This method does not support objects having non-uniformly-scaled parent(s)
Parameters
_x
A vector representing position of target in world space.
Returns
void
Inherited from
lookAtLocalPoint()
lookAtLocalPoint(
_x):void
Rotates the object to face a point in local space.
Parameters
_x
A vector representing position of target in local space.
Returns
void
Inherited from
add()
add(
o):this
Adds object as child of this object. An arbitrary number of objects may be added. Any current parent on an object passed in here will be removed, since an object can have at most one parent. The scene graph change will be immediately notify by engine after adding nodes.
Parameters
o
Parameter can be one object or objects array, all of them is added to this object.
Returns
this
Inherited from
remove()
remove(
object):this
Remove the specified object form children.
Parameters
object
The object which needs to be removed.
Returns
this
Inherited from
removeFromParent()
removeFromParent():
void
Returns
void
Inherited from
removeAllChildren()
removeAllChildren():
Object3D[]
Remove all children of this object.
Returns
Object3D[]
Inherited from
removeObjects()
removeObjects(
objects):this
Remove all children in specified objects from this objects. Migrate from tools common
Parameters
objects
Object3D[]
An array of objects which need to be removed.
Returns
this
Inherited from
getObjectById()
getObjectById(
id):Object3D
Searches through an object and its children, starting with the object itself, and returns the first with a matching id. Note that ids are assigned in chronological order: 1, 2, 3, …, incrementing by one for each new object.
Parameters
id
number
Unique number of the object instance.
Returns
Inherited from
getObjectByName()
getObjectByName(
name):Object3D
Searches through an object and its children, starting with the object itself, and returns the first with a matching name. Note that for most objects the name is an empty string by default. You will have to set it manually to make use of this method.
Parameters
name
string
String to match to the children’s Object3D.name property.
Returns
Inherited from
getObjectByProperty()
getObjectByProperty(
name,value):Object3D
Searches through an object and its children, starting with the object itself, and returns the first with a property that matches the value given.
Parameters
name
string
The property name to search for.
value
any
Value of the given property.
Returns
Inherited from
getWorldPosition()
getWorldPosition(
target):Vector3
Return a vector representing the position of the object in world space.
Parameters
target
the result will be copied into this Vector3.
Returns
Inherited from
getWorldQuaternion()
getWorldQuaternion(
target):Quaternion
Return a quaternion representing the rotation of the object in world space.
Parameters
target
the result will be copied into this Quaternion.
Returns
Inherited from
getWorldScale()
getWorldScale(
target):Vector3
Return a vector of the scaling factors applied to the object for each axis in world space.
Parameters
target
the result will be copied into this Vector3.
Returns
Inherited from
getWorldDirection()
getWorldDirection(
target):Vector3
Return a vector representing the direction of object’s positive z-axis in world space.
Parameters
target
the result will be copied into this Vector3.
Returns
Inherited from
traverse()
traverse(
callback):void
Execute the callback on this object and all descendants.
Parameters
callback
(object) => any
A function with as first argument an object3D object.
Returns
void
Inherited from
traverseWithChildrenSkip()
traverseWithChildrenSkip(
callback):void
Execute the callback when return is false, stop traverse the object’s descendants.
Parameters
callback
(object) => boolean
A function with as first argument an object3D object, return boolean.
Returns
void
Inherited from
Object3D.traverseWithChildrenSkip
traverseVisible()
traverseVisible(
callback):void
Execute the callback on this object and all descendants which is visible.
Parameters
callback
(object) => any
A function with as first argument an object3D object.
Returns
void
Inherited from
traverseAncestors()
traverseAncestors(
callback):void
Execute the callback on this object and all ancestors.
Parameters
callback
(object) => any
A function with as first argument an object3D object.
Returns
void
Inherited from
updateMatrix()
updateMatrix():
void
Update the matrix local transform.
Returns
void
Inherited from
updateMatrixWorld()
updateMatrixWorld(
force?):void
Update the object’s and its descendants’ matrix of global transform with. If the parameter or matrixWorldNeedsUpdate is true, matrix will not skip updates.
Parameters
force?
boolean
Whether or not force to updates the matrix.
Returns
void
Inherited from
updateWorldMatrix()
updateWorldMatrix(
updateParents,updateChildren,force?):void
Update the object’s and its descendants’ matrix of global transform with. will update parent or children according to the parameters
Parameters
updateParents
boolean
update parents.
updateChildren
boolean
update children.
force?
boolean
Whether or not force to updates the matrix.
Returns
void
Inherited from
getLocalBounds()
getLocalBounds(
localBox?):Box3
Get the whole bounding box of current object cover all children’s.
Parameters
localBox?
If this is not undefined, result will be stored to it.
Returns
Inherited from
getUUID()
getUUID():
string
Get UUID of this object instance. This value is automatically assigned, so this shouldn’t be edited.
Returns
string
Inherited from
serialize()
serialize(
ctx):void
Store the attributes of this class into string as serializing format.
Parameters
ctx
Serializer
this parameter has not supported external Serializer yet. It may cause that this method can not be used directly.
Returns
void
Inherited from
deserialize()
deserialize(
ctx):void
Parse the data for this class from string according to serializing format.
Parameters
ctx
Deserializer
this parameter has not supported external Deserializer yet. It may cause that this method can not be used directly.
Returns
void
Inherited from
clone()
clone(
recursive?):Object3D
Return a cloned instance of this class and optionally all descendants.
Parameters
recursive?
boolean
if true, descendants of the object are also cloned. Default is true.
Returns
Inherited from
notifyClippingChanged()
notifyClippingChanged():
void
Returns
void
className()
className():
string
The name of instance’s class.
Returns
string
Overrides
destroy()
destroy():
void
Clears this scene related data.
Returns
void
Overrides
onNodeAdd()
onNodeAdd(
o):void
When any node is added to scene, this method will record which nodes are added or just changed.
Parameters
o
added node.
Returns
void
onNodeChanged()
onNodeChanged(
o):void
When any changes occur at the node, this method will be used to record which nodes are changed.
Parameters
o
changed node.
Returns
void
onNodeDelete()
onNodeDelete(
o):void
When any node is deleted, this method will be used to record which nodes are deleted.
Parameters
o
deleted node.
Returns
void
popParentChanges()
popParentChanges():
void
change updateDirtyId of all node’s parent to current update id in order to avoid loop checking.
Returns
void
refreshChangeSets()
refreshChangeSets():
void
Synchronize the changes of scene nodes to renderProxyManager and clear these cache.
Returns
void
update()
update(
forceRefreshChanges?):void
When isAnythingChanged is true, all nodes of this scene will be checked if there is any change and increase update id. The update id is used to compare with nodes’ dirty mark and decide it needs to update in current frame.
Parameters
forceRefreshChanges?
boolean
Returns
void
afterRender()
afterRender():
void
Returns
void
updateRegistryAndActive()
updateRegistryAndActive(
renderer,camera):void
Update data and render the effect of shader components whose corresponding config is active.
Parameters
renderer
IRenderer
give renderer the shaderComponentRegistry| shaderComponentRegistry of this scene.
camera
this is used to update corresponding data.
Returns
void
copy()
copy(
source,recursive?):this
Ues copy() of Object3D to copy Object3D.matrixAutoUpdate| matrixAutoUpdate, Object3D.overrideMaterial| overrideMaterial and data from source.
Parameters
source
Scene3D
the data source.
recursive?
boolean
if true, all nodes of this scene are also cloned. Default is true.
Returns
this
Overrides
markBusinessTag()
markBusinessTag(
v):this
Parameters
v
string
Returns
this
Inherited from
isDestroyed()
isDestroyed():
boolean
Returns
boolean
Inherited from
validate()
validate():
void
Returns
void
Inherited from
destroyAllResourcesOwned()
destroyAllResourcesOwned():
void
Returns
void
Inherited from
Object3D.destroyAllResourcesOwned
freeAllGpuResourceOwned()
freeAllGpuResourceOwned():
void
Returns
void
Inherited from
Object3D.freeAllGpuResourceOwned
on()
on<
T>(_type,_listener):void
Adds a listener to an event type.
Type Parameters
T
T
Parameters
_type
EventType<T>
_listener
Listener<T>
Returns
void
Inherited from
once()
once<
T>(_type,_listener):void
Only active the listener one times and then off it| it.
Type Parameters
T
T
Parameters
_type
EventType<T>
_listener
Listener<T>
Returns
void
Inherited from
has()
has<
T>(_type,_listener):boolean
Checks if listener is added to an event type.
Type Parameters
T
T
Parameters
_type
EventType<T>
_listener
Listener<T>
Returns
boolean
Inherited from
off()
off<
T>(_type,_listener):void
Removes a listener from listening list.
Type Parameters
T
T
Parameters
_type
EventType<T>
_listener
Listener<T>
Returns
void
Inherited from
emit()
Call Signature
emit(
type):void
Active the event and call the registered listener.
Parameters
type
EventType<never>
Returns
void
Inherited from
Call Signature
emit<
T>(type,payload):void
Type Parameters
T
T
Parameters
type
EventType<T>
payload
T
Returns
void
Inherited from
clearAllListeners()
clearAllListeners():
void
Removes all listeners from listening list.
Returns
void