Package com.jme3.scene

Class Spatial

java.lang.Object
com.jme3.scene.Spatial
All Implemented Interfaces:
HasLocalTransform, CloneableSmartAsset, Collidable, Savable, JmeCloneable, Cloneable
Direct Known Subclasses:
Geometry, Node
public abstract class Spatial extends Object implements Savable, Cloneable, Collidable, CloneableSmartAsset, JmeCloneable, HasLocalTransform
Spatial defines the base class for scene graph nodes. It maintains a link to a parent, its local transforms and the world's transforms. All other scene graph elements, such as Node and Geometry are subclasses of Spatial.

  • Field Details

  • Constructor Details

    • Spatial

      protected Spatial()
      Serialization only. Do not use. Not really. This class is never instantiated directly but the subclasses like to use the no-arg constructor for their own no-arg constructor... which is technically weaker than forward supplying defaults.

    • Spatial

      protected Spatial(String name)
      Constructor instantiates a new Spatial object, setting the rotation, translation, and scale values to their defaults.
      Parameters:
      name - the name of the scene element. This is required for identification and comparison purposes.

  • Method Details

    • setKey

      public void setKey(AssetKey key)
      Description copied from interface: CloneableSmartAsset
      Assigns the specified AssetKey to the asset. This is invoked by the AssetManager. Only clones of the asset have non-null keys. The original copy that was loaded has no key assigned. Only the clones are tracked for garbage collection.
      Specified by:
      setKey in interface CloneableSmartAsset
      Parameters:
      key - The AssetKey to assign

    • getKey

      public AssetKey getKey()
      Description copied from interface: CloneableSmartAsset
      Returns the asset key that is used to track this asset for garbage collection.
      Specified by:
      getKey in interface CloneableSmartAsset
      Returns:
      the asset key that is used to track this asset for garbage collection.

    • setRequiresUpdates

      protected void setRequiresUpdates(boolean f)
      Subclasses can call this with true to denote that they require updateLogicalState() to be called even if they contain no controls. Setting this to false reverts to the default behavior of only updating if the spatial has controls. This is not meant to indicate dynamic state in any way and must be called while unattached or an IllegalStateException is thrown. It is designed to be called during object construction and then never changed, ie: it's meant to be subclass specific state and not runtime state. Subclasses of Node or Geometry that do not set this will get the old default behavior as if this was set to true. Subclasses should call setRequiresUpdate(false) in their constructors to receive optimal behavior if they don't require updateLogicalState() to be called even if there are no controls.
      Parameters:
      f - true→require updates, false→don't require updates

    • setTransformRefresh

      protected void setTransformRefresh()
      Indicate that the transform of this spatial has changed and that a refresh is required.

    • setLightListRefresh

      protected void setLightListRefresh()

    • setMatParamOverrideRefresh

      protected void setMatParamOverrideRefresh()

    • setBoundRefresh

      protected void setBoundRefresh()
      Indicate that the bounding of this spatial has changed and that a refresh is required.

    • forceRefresh

      public void forceRefresh(boolean transforms, boolean bounds, boolean lights)
      (Internal use only) Forces a refresh of the given types of data.
      Parameters:
      transforms - Refresh world transform based on parents'
      bounds - Refresh bounding volume data based on child nodes
      lights - Refresh light list based on parents'

    • checkCulling

      public boolean checkCulling(Camera cam)
      checkCulling checks the spatial with the camera to see if it should be culled.

      This method is called by the renderer. Usually it should not be called directly.

      Parameters:
      cam - The camera to check against.
      Returns:
      true if inside or intersecting camera frustum (should be rendered), false if outside.

    • setName

      public void setName(String name)
      Sets the name of this spatial.
      Parameters:
      name - The spatial's new name.

    • getName

      public String getName()
      Returns the name of this spatial.
      Returns:
      This spatial's name.

    • getLocalLightList

      public LightList getLocalLightList()
      Returns the local LightList, which are the lights that were directly attached to this Spatial through the addLight(com.jme3.light.Light) and removeLight(com.jme3.light.Light) methods.
      Returns:
      The local light list

    • getWorldLightList

      public LightList getWorldLightList()
      Returns the world LightList, containing the lights combined from all this Spatial's parents up to and including this Spatial's lights.
      Returns:
      The combined world light list

    • getLocalMatParamOverrides

      public SafeArrayList<MatParamOverride> getLocalMatParamOverrides()
      Get the local material parameter overrides.
      Returns:
      The list of local material parameter overrides.

    • getWorldMatParamOverrides

      public SafeArrayList<MatParamOverride> getWorldMatParamOverrides()
      Get the world material parameter overrides. Note that this list is only updated on a call to updateGeometricState(). After update, the world overrides list will contain the parent's world overrides combined with this spatial's local overrides.
      Returns:
      The list of world material parameter overrides.

    • getWorldRotation

      public Quaternion getWorldRotation()
      getWorldRotation retrieves the absolute rotation of the Spatial.
      Returns:
      the Spatial's world rotation quaternion.

    • getWorldTranslation

      public Vector3f getWorldTranslation()
      getWorldTranslation retrieves the absolute translation of the spatial.
      Returns:
      the Spatial's world translation vector.

    • getWorldScale

      public Vector3f getWorldScale()
      getWorldScale retrieves the absolute scale factor of the spatial.
      Returns:
      the Spatial's world scale factor.

    • getWorldTransform

      public Transform getWorldTransform()
      getWorldTransform retrieves the world transformation of the spatial.
      Returns:
      the world transform.

    • rotateUpTo

      public void rotateUpTo(Vector3f newUp)
      rotateUpTo is a utility function that alters the local rotation to point the Y axis in the direction given by newUp.
      Parameters:
      newUp - the up vector to use - assumed to be a unit vector.

    • lookAt

      public void lookAt(Vector3f position, Vector3f upVector)
      lookAt is a convenience method for auto-setting the local rotation based on a position in world space and an up vector. It computes the rotation to transform the z-axis to point onto 'position' and the y-axis to 'up'. Unlike Quaternion.lookAt(com.jme3.math.Vector3f, com.jme3.math.Vector3f) this method takes a world position to look at and not a relative direction. Note : 28/01/2013 this method has been fixed as it was not taking into account the parent rotation. This was resulting in improper rotation when the spatial had rotated parent nodes. This method is intended to work in world space, so no matter what parent graph the spatial has, it will look at the given position in world space.
      Parameters:
      position - where to look at in terms of world coordinates
      upVector - a vector indicating the (local) up direction. (typically {0, 1, 0} in jME.)

    • updateWorldBound

      protected void updateWorldBound()
      Should be overridden by Node and Geometry.

    • updateWorldLightList

      protected void updateWorldLightList()

    • updateMatParamOverrides

      protected void updateMatParamOverrides()

    • addMatParamOverride

      public void addMatParamOverride(MatParamOverride override)
      Adds a local material parameter override.
      Parameters:
      override - The override to add.
      See Also:

    • removeMatParamOverride

      public void removeMatParamOverride(MatParamOverride override)
      Remove a local material parameter override if it exists.
      Parameters:
      override - The override to remove.
      See Also:

    • clearMatParamOverrides

      public void clearMatParamOverrides()
      Remove all local material parameter overrides.
      See Also:

    • updateWorldTransforms

      protected void updateWorldTransforms()
      Should only be called from updateGeometricState(). In most cases should not be subclassed.

    • runControlRender

      public void runControlRender(RenderManager rm, ViewPort vp)
      Called when the Spatial is about to be rendered, to notify controls attached to this Spatial using the Control.render() method.
      Parameters:
      rm - The RenderManager rendering the Spatial.
      vp - The ViewPort to which the Spatial is being rendered to.
      See Also:

    • addControl

      public void addControl(Control control)
      Add a control to the list of controls.
      Parameters:
      control - The control to add.
      See Also:

    • addControlAt

      public void addControlAt(int index, Control control)
      Adds the specified control to the list, at the specified index. Any controls with indices greater than or equal to the specified index will have their indices increased by one.
      Parameters:
      index - the index at which to add the control (0→first, ≥0)
      control - the control to add (not null)
      Throws:
      IllegalStateException - if the control is already added here

    • removeControl

      public void removeControl(Class<? extends Control> controlType)
      Removes the first control that is an instance of the given class.
      Parameters:
      controlType - the type of Control to remove
      See Also:

    • removeControl

      public boolean removeControl(Control control)
      Removes the given control from this spatial's controls.
      Parameters:
      control - The control to remove
      Returns:
      True if the control was successfully removed. False if the control is not assigned to this spatial.
      See Also:

    • getControl

      public <T extends Control> T getControl(Class<T> controlType)
      Returns the first control that is an instance of the given class, or null if no such control exists.
      Type Parameters:
      T - the type of control to look for
      Parameters:
      controlType - The superclass of the control to look for.
      Returns:
      The first instance in the list of the controlType class, or null.
      See Also:

    • getControl

      public Control getControl(int index)
      Returns the control at the given index in the list.
      Parameters:
      index - The index of the control in the list to find.
      Returns:
      The control at the given index.
      Throws:
      IndexOutOfBoundsException - If the index is outside the range [0, getNumControls()-1]
      See Also:

    • getNumControls

      public int getNumControls()
      Returns:
      The number of controls attached to this Spatial.
      See Also:

    • updateLogicalState

      public void updateLogicalState(float tpf)
      updateLogicalState calls the update() method for all controls attached to this Spatial.
      Parameters:
      tpf - Time per frame.
      See Also:

    • updateGeometricState

      public void updateGeometricState()
      updateGeometricState updates the light list, computes the world transforms, and computes the world bounds for this Spatial. Calling this when the Spatial is attached to a node will cause undefined results. User code should only call this method on Spatials having no parent.
      See Also:

    • localToWorld

      public Vector3f localToWorld(Vector3f in, Vector3f store)
      Convert a vector (in) from this spatial's local coordinate space to world coordinate space.
      Parameters:
      in - vector to read from
      store - where to write the result (null to create a new vector, may be same as in)
      Returns:
      the result (store)

    • worldToLocal

      public Vector3f worldToLocal(Vector3f in, Vector3f store)
      Convert a vector (in) from world coordinate space to this spatial's local coordinate space.
      Parameters:
      in - vector to read from
      store - where to write the result
      Returns:
      the result (store)

    • getParent

      public Node getParent()
      getParent retrieves this node's parent. If the parent is null this is the root node.
      Returns:
      the parent of this node.

    • setParent

      protected void setParent(Node parent)
      Called by Node.attachChild(Spatial) and Node.detachChild(Spatial) - don't call directly. setParent sets the parent of this node.
      Parameters:
      parent - the parent of this node.

    • removeFromParent

      public boolean removeFromParent()
      removeFromParent removes this Spatial from its parent.
      Returns:
      true if it has a parent and performed the remove.

    • hasAncestor

      public boolean hasAncestor(Node ancestor)
      determines if the provided Node is the parent, or parent's parent, etc. of this Spatial.
      Parameters:
      ancestor - the ancestor object to look for.
      Returns:
      true if the ancestor is found, false otherwise.

    • getLocalRotation

      public Quaternion getLocalRotation()
      getLocalRotation retrieves the local rotation of this node.
      Returns:
      the local rotation of this node.

    • setLocalRotation

      public void setLocalRotation(Matrix3f rotation)
      setLocalRotation sets the local rotation of this node by using a Matrix3f.
      Parameters:
      rotation - the new local rotation.

    • setLocalRotation

      public void setLocalRotation(Quaternion quaternion)
      setLocalRotation sets the local rotation of this node.
      Parameters:
      quaternion - the new local rotation (not null, quaternion.norm() approximately equal to 1, unaffected)

    • getLocalScale

      public Vector3f getLocalScale()
      getLocalScale retrieves the local scale of this node.
      Returns:
      the local scale of this node.

    • setLocalScale

      public void setLocalScale(float localScale)
      setLocalScale sets the local scale of this node.
      Parameters:
      localScale - the new local scale, applied to x, y and z

    • setLocalScale

      public void setLocalScale(float x, float y, float z)
      setLocalScale sets the local scale of this node.
      Parameters:
      x - the desired scale factor for the X axis
      y - the desired scale factor for the Y axis
      z - the desired scale factor for the Z axis

    • setLocalScale

      public void setLocalScale(Vector3f localScale)
      setLocalScale sets the local scale of this node.
      Parameters:
      localScale - the new local scale.

    • getLocalTranslation

      public Vector3f getLocalTranslation()
      getLocalTranslation retrieves the local translation of this node.
      Returns:
      the local translation of this node.

    • setLocalTranslation

      public void setLocalTranslation(Vector3f localTranslation)
      setLocalTranslation sets the local translation of this spatial.
      Parameters:
      localTranslation - the local translation of this spatial.

    • setLocalTranslation

      public void setLocalTranslation(float x, float y, float z)
      setLocalTranslation sets the local translation of this spatial.
      Parameters:
      x - the desired offset in the +X direction
      y - the desired offset in the +Y direction
      z - the desired offset in the +Z direction

    • setLocalTransform

      public void setLocalTransform(Transform t)
      setLocalTransform sets the local transform of this spatial.
      Specified by:
      setLocalTransform in interface HasLocalTransform
      Parameters:
      t - the desired local transform (not null, t.rot.norm() approximately equal to 1, unaffected)

    • getLocalTransform

      public Transform getLocalTransform()
      getLocalTransform retrieves the local transform of this spatial.
      Specified by:
      getLocalTransform in interface HasLocalTransform
      Returns:
      the local transform of this spatial.

    • setMaterial

      public void setMaterial(Material material)
      Applies the given material to the Spatial, this will propagate the material down to the geometries in the scene graph.
      Parameters:
      material - The material to set.

    • addLight

      public void addLight(Light light)
      addLight adds the given light to the Spatial; causing all child Spatials to be affected by it.
      Parameters:
      light - The light to add.

    • removeLight

      public void removeLight(Light light)
      removeLight removes the given light from the Spatial.
      Parameters:
      light - The light to remove.
      See Also:

    • move

      public Spatial move(float x, float y, float z)
      Translates the spatial by the given translation vector.
      Parameters:
      x - the offset to apply in the +X direction
      y - the offset to apply in the +Y direction
      z - the offset to apply in the +Z direction
      Returns:
      The spatial on which this method is called, e.g this.

    • move

      public Spatial move(Vector3f offset)
      Translates the spatial by the given translation vector.
      Parameters:
      offset - the desired offset (not null, unaffected)
      Returns:
      The spatial on which this method is called, e.g this.

    • scale

      public Spatial scale(float s)
      Scales the spatial by the given value
      Parameters:
      s - the scaling factor to apply to all axes
      Returns:
      The spatial on which this method is called, e.g this.

    • scale

      public Spatial scale(float x, float y, float z)
      Scales the spatial by the given scale vector.
      Parameters:
      x - the scaling factor to apply to the X axis
      y - the scaling factor to apply to the Y axis
      z - the scaling factor to apply to the Z axis
      Returns:
      The spatial on which this method is called, e.g this.

    • rotate

      public Spatial rotate(Quaternion rot)
      Rotates the spatial by the given rotation.
      Parameters:
      rot - the intrinsic rotation to apply (not null, unaffected)
      Returns:
      The spatial on which this method is called, e.g this.

    • rotate

      public Spatial rotate(float xAngle, float yAngle, float zAngle)
      Rotates the spatial by the xAngle, yAngle and zAngle angles (in radians), (aka pitch, yaw, roll) in the local coordinate space.
      Parameters:
      xAngle - the angle of rotation around the +X axis (in radians)
      yAngle - the angle of rotation around the +Y axis (in radians)
      zAngle - the angle of rotation around the +Z axis (in radians)
      Returns:
      The spatial on which this method is called, e.g this.

    • center

      public Spatial center()
      Centers the spatial in the origin of the world bound.
      Returns:
      The spatial on which this method is called, e.g this.

    • getCullHint

      public Spatial.CullHint getCullHint()
      Returns:
      the cull mode of this spatial, or if set to CullHint.Inherit, the cull mode of its parent.
      See Also:

    • getBatchHint

      public Spatial.BatchHint getBatchHint()

    • getQueueBucket

      public RenderQueue.Bucket getQueueBucket()
      Returns this spatial's render-queue bucket. If the mode is set to inherit, then the spatial gets its render-queue bucket from its parent.
      Returns:
      The spatial's current render-queue bucket.

    • getShadowMode

      public RenderQueue.ShadowMode getShadowMode()
      Returns:
      The shadow mode of this spatial, if the local shadow mode is set to inherit, then the parent's shadow mode is returned.
      See Also:

    • setLodLevel

      public void setLodLevel(int lod)
      Sets the level of detail to use when rendering this Spatial, this call propagates to all geometries under this Spatial.
      Parameters:
      lod - The lod level to set.

    • updateModelBound

      public abstract void updateModelBound()
      updateModelBound recalculates the bounding object for this Spatial.

    • setModelBound

      public abstract void setModelBound(BoundingVolume modelBound)
      setModelBound sets the bounding object for this Spatial.
      Parameters:
      modelBound - the bounding object for this spatial.

    • getVertexCount

      public abstract int getVertexCount()
      Returns:
      The sum of all vertices under this Spatial.

    • getTriangleCount

      public abstract int getTriangleCount()
      Returns:
      The sum of all triangles under this Spatial.

    • clone

      public Spatial clone(boolean cloneMaterial)
      Parameters:
      cloneMaterial - true to clone materials, false to share them
      Returns:
      A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated.
      See Also:

    • oldClone

      @Deprecated public Spatial oldClone(boolean cloneMaterial)
      Deprecated.
      The old clone() method that did not use the new Cloner utility.
      Parameters:
      cloneMaterial - ignored
      Returns:
      never

    • clone

      public Spatial clone()
      Description copied from interface: CloneableSmartAsset
      Creates a clone of the asset. Please see Object.clone() for more info on how this method should be implemented.
      Specified by:
      clone in interface CloneableSmartAsset
      Overrides:
      clone in class Object
      Returns:
      A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated.
      See Also:

    • deepClone

      public Spatial deepClone()
      Returns:
      Similar to Spatial.clone() except will create a deep clone of all geometries' meshes. Normally this method shouldn't be used. Instead, use Spatial.clone()
      See Also:

    • jmeClone

      public Spatial jmeClone()
      Called internally by com.jme3.util.clone.Cloner. Do not call directly.
      Specified by:
      jmeClone in interface JmeCloneable
      Returns:
      a new instance

    • cloneFields

      public void cloneFields(Cloner cloner, Object original)
      Called internally by com.jme3.util.clone.Cloner. Do not call directly.
      Specified by:
      cloneFields in interface JmeCloneable
      Parameters:
      cloner - The cloner that is performing the cloning operation. The cloneFields method can call back into the cloner to make clones of its subordinate fields.
      original - The original object from which this object was cloned. This is provided for the very rare case that this object needs to refer to its original for some reason. In general, all of the relevant values should have been transferred during the shallow clone, and this object need only clone what it wants.

    • setUserData

      public void setUserData(String key, Object data)

    • getUserData

      public <T> T getUserData(String key)

    • getUserDataKeys

      public Collection<String> getUserDataKeys()

    • matches

      public boolean matches(Class<? extends Spatial> spatialSubclass, String nameRegex)
      Note that we are matching the pattern, therefore the pattern must match the entire pattern (i.e. it behaves as if it is sandwiched between "^" and "$"). You can set regex modes, like case insensitivity, by using the (?X) or (?X:Y) constructs.
      Parameters:
      spatialSubclass - Subclass which this must implement. Null causes all Spatials to qualify.
      nameRegex - Regular expression to match this name against. Null causes all Names to qualify.
      Returns:
      true if this implements the specified class and this's name matches the specified pattern.
      See Also:

    • write

      public void write(JmeExporter ex) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(JmeImporter im) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • getWorldBound

      public BoundingVolume getWorldBound()
      getWorldBound retrieves the world bound at this node level.
      Returns:
      the world bound at this level.

    • setCullHint

      public void setCullHint(Spatial.CullHint hint)
      setCullHint alters how view frustum culling will treat this spatial.
      Parameters:
      hint - one of: CullHint.Dynamic, CullHint.Always, CullHint.Inherit, or CullHint.Never

      The effect of the default value (CullHint.Inherit) may change if the spatial gets re-parented.

    • setBatchHint

      public void setBatchHint(Spatial.BatchHint hint)
      setBatchHint alters how batching will treat this spatial.
      Parameters:
      hint - one of: BatchHint.Never, BatchHint.Always, or BatchHint.Inherit

      The effect of the default value (BatchHint.Inherit) may change if the spatial gets re-parented.

    • getLocalCullHint

      public Spatial.CullHint getLocalCullHint()
      Returns:
      the cull mode of this Spatial

    • getLocalBatchHint

      public Spatial.BatchHint getLocalBatchHint()
      Returns:
      the batch hint for this Spatial

    • setQueueBucket

      public void setQueueBucket(RenderQueue.Bucket queueBucket)
      setQueueBucket determines at what phase of the rendering process this Spatial will rendered. See the RenderQueue.Bucket enum for an explanation of the various render queue buckets.
      Parameters:
      queueBucket - The bucket to use for this Spatial.

    • setShadowMode

      public void setShadowMode(RenderQueue.ShadowMode shadowMode)
      Sets the shadow mode of the spatial The shadow mode determines how the spatial should be shadowed, when a shadowing technique is used. See the documentation for the class RenderQueue.ShadowMode for more information.
      Parameters:
      shadowMode - The local shadow mode to set.
      See Also:

    • getLocalQueueBucket

      public RenderQueue.Bucket getLocalQueueBucket()
      Returns:
      The locally set queue bucket mode
      See Also:

    • getLocalShadowMode

      public RenderQueue.ShadowMode getLocalShadowMode()
      Returns:
      The locally set shadow mode
      See Also:

    • getLastFrustumIntersection

      public Camera.FrustumIntersect getLastFrustumIntersection()
      Returns this spatial's last frustum intersection result. This int is set when a check is made to determine if the bounds of the object fall inside a camera's frustum. If a parent is found to fall outside the frustum, the value for this spatial will not be updated.
      Returns:
      The spatial's last frustum intersection result.

    • setLastFrustumIntersection

      public void setLastFrustumIntersection(Camera.FrustumIntersect intersects)
      Overrides the last intersection result. This is useful for operations that want to start rendering at the middle of a scene tree and don't want the parent of that node to influence culling.
      Parameters:
      intersects - the new value

    • toString

      public String toString()
      Returns the Spatial's name followed by the class of the spatial
      Example: "MyNode (com.jme3.scene.Spatial)"
      Overrides:
      toString in class Object
      Returns:
      Spatial's name followed by the class of the Spatial

    • getLocalToWorldMatrix

      public Matrix4f getLocalToWorldMatrix(Matrix4f store)
      Creates a transform matrix that will convert from this spatials' local coordinate space to the world coordinate space based on the world transform.
      Parameters:
      store - Matrix where to store the result, if null, a new one will be created and returned.
      Returns:
      store if not null, otherwise, a new matrix containing the result.
      See Also:

    • depthFirstTraversal

      public void depthFirstTraversal(SceneGraphVisitor visitor)
      Visit each scene graph element ordered by DFS with the default post order mode.
      Parameters:
      visitor - the action to take for each visited Spatial
      See Also:

    • depthFirstTraversal

      public abstract void depthFirstTraversal(SceneGraphVisitor visitor, Spatial.DFSMode mode)
      Visit each scene graph element ordered by DFS. There are two modes: pre order and post order.
      Parameters:
      visitor - the action to take for each visited Spatial
      mode - the traversal mode: pre order or post order

    • breadthFirstTraversal

      public void breadthFirstTraversal(SceneGraphVisitor visitor)
      Visit each scene graph element ordered by BFS
      Parameters:
      visitor - the action to take for each visited Spatial

    • breadthFirstTraversal

      protected abstract void breadthFirstTraversal(SceneGraphVisitor visitor, Queue<Spatial> queue)