APIdia Launch Partner
Top Description Fields Constructors Methods
com.badlogic.gdx.graphics.g3d

public Class ModelInstance

extends Object
implements RenderableProvider
Class Inheritance
All Implemented Interfaces
com.badlogic.gdx.graphics.g3d.RenderableProvider
Imports
com.badlogic.gdx.graphics.g3d.model.Animation, .Node, .NodeAnimation, .NodeKeyframe, .NodePart, com.badlogic.gdx.math.Matrix4, .Quaternion, .Vector3, com.badlogic.gdx.math.collision.BoundingBox, com.badlogic.gdx.utils.Array, .ArrayMap, .Pool

An instance of a Model, allows to specify global transform and modify the materials, as it has a copy of the model's materials. Multiple instances can be created from the same Model, all sharing the meshes and textures of the Model. The Model owns the meshes and textures, to dispose of these, the Model has to be disposed. Therefor, the Model must outlive all its ModelInstances

The ModelInstance creates a full copy of all materials, nodes and animations.
Author
badlogic, xoppa

Field Summary

Modifier and TypeField and Description
public final Array<Animation>
animations

animations of the model, modifying node transformations

public static boolean
defaultShareKeyframes

Whether, by default, NodeKeyframe's are shared amongst Model and ModelInstance.

public final Array<Material>
materials

the materials of the model, used by nodes that have a graphical representation FIXME not sure if superfluous, allows modification of materials without having to traverse the nodes

public final Model
model

the Model this instances derives from

public final Array<Node>
nodes

root nodes of the model

public Matrix4
transform

the world transform

public Object
userData

user definable value, which is passed to the Shader.

Constructor Summary

AccessConstructor and Description
public
ModelInstance(final Model
The Model to create an instance of.
model
)

Constructs a new ModelInstance with all nodes and materials of the given model.

public
ModelInstance(final Model
The source Model
model
,
final String
The ID of the root Node of the Model for the instance to contain
nodeId
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

public
ModelInstance(final Model
The source Model
model
,
final Matrix4
The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.
transform
,
final String
The ID of the root Node of the Model for the instance to contain
nodeId
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

public
ModelInstance(final Model
The source Model
model
,
final String
The ID of the Node within the Model for the instance to contain
nodeId
,
boolean
True to apply the parent's node transform to the instance (only applicable if recursive is true).
parentTransform
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

Recursively searches the mode for the specified node.

public
ModelInstance(final Model
The source Model
model
,
final Matrix4
The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.
transform
,
final String
The ID of the Node within the Model for the instance to contain
nodeId
,
boolean
True to apply the parent's node transform to the instance (only applicable if recursive is true).
parentTransform
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

Recursively searches the mode for the specified node.

public
ModelInstance(final Model
The source Model
model
,
final String
The ID of the Node within the Model for the instance to contain
nodeId
,
boolean
True to recursively search the Model's node tree, false to only search for a root node
recursive
,
boolean
True to apply the parent's node transform to the instance (only applicable if recursive is true).
parentTransform
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

public
ModelInstance(final Model
The source Model
model
,
final Matrix4
The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.
transform
,
final String
The ID of the Node within the Model for the instance to contain
nodeId
,
boolean
True to recursively search the Model's node tree, false to only search for a root node
recursive
,
boolean
True to apply the parent's node transform to the instance (only applicable if recursive is true).
parentTransform
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
)

public
ModelInstance(final Model
The source Model
model
,
final Matrix4
The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.
transform
,
final String
The ID of the Node within the Model for the instance to contain
nodeId
,
boolean
True to recursively search the Model's node tree, false to only search for a root node
recursive
,
boolean
True to apply the parent's node transform to the instance (only applicable if recursive is true).
parentTransform
,
boolean
True to apply the source node transform to the instance transform, resetting the node transform.
mergeTransform
,
boolean shareKeyframes)

public
ModelInstance(final Model model, final String... rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

public
ModelInstance(final Model model, final Matrix4 transform, final String... rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

public
ModelInstance(final Model model, final Array<String> rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

public
ModelInstance(final Model model, final Matrix4 transform, final Array<String> rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

public
ModelInstance(final Model model, final Matrix4 transform, final Array<String> rootNodeIds, boolean shareKeyframes)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

public
ModelInstance(final Model model, Vector3 position)

Constructs a new ModelInstance at the specified position.

public
ModelInstance(final Model model, float x, float y, float z)

Constructs a new ModelInstance at the specified position.

public
ModelInstance(final Model model, Matrix4 transform)

Constructs a new ModelInstance with the specified transform.

public
ModelInstance(ModelInstance copyFrom)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

public
ModelInstance(ModelInstance copyFrom, final Matrix4 transform)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

public
ModelInstance(ModelInstance copyFrom, final Matrix4 transform, boolean shareKeyframes)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

Method Summary

Modifier and TypeMethod and Description
public BoundingBox

Returns:

the out parameter for chaining
calculateBoundingBox
(final BoundingBox
the BoundingBox that will be set with the bounds.
out
)

Calculate the bounding box of this model instance.

public void
calculateTransforms()

Calculates the local and world transform of all Node instances in this model, recursively.

public ModelInstance
copy()

Returns: A newly created ModelInstance which is a copy of this ModelInstance

public void
copyAnimation(Animation
The source animation Animation
sourceAnim
)

Copy the source animation to this ModelInstance

public void
copyAnimation(Animation
The source animation Animation
sourceAnim
,
boolean
Shallow copy of NodeKeyframe's if it's true, otherwise make a deep copy.
shareKeyframes
)

Copy the source animation to this ModelInstance

public void
copyAnimations(final Iterable<Animation>
Iterable collection of source animations Animation
source
)

Copy source animations to this ModelInstance

public void
copyAnimations(final Iterable<Animation>
Iterable collection of source animations Animation
source
,
boolean
Shallow copy of NodeKeyframe's if it's true, otherwise make a deep copy.
shareKeyframes
)

Copy source animations to this ModelInstance

private void
private void
copyNodes(Array<Node> nodes, final String... nodeIds)

private void
copyNodes(Array<Node> nodes, final Array<String> nodeIds)

public BoundingBox

Returns:

the out parameter for chaining
extendBoundingBox
(final BoundingBox
the BoundingBox that will be extended with the bounds.
out
)

Extends the bounding box with the bounds of this model instance.

public Animation
getAnimation(final String
The ID of the animation to fetch (case sensitive).
id
)

Returns: The Animation with the specified id, or null if not available.

public Animation
getAnimation(final String
The ID of the animation to fetch.
id
,
boolean
whether to use case sensitivity when comparing the animation id.
ignoreCase
)

Returns: The Animation with the specified id, or null if not available.

public Material
getMaterial(final String
The ID of the material to fetch.
id
)

Returns: The Material with the specified id, or null if not available.

public Material
getMaterial(final String
The ID of the material to fetch.
id
,
boolean
whether to use case sensitivity when comparing the material id.
ignoreCase
)

Returns: The Material with the specified id, or null if not available.

public Node
getNode(final String
The ID of the node to fetch.
id
)

Returns: The Node with the specified id, or null if not found.

public Node
getNode(final String
The ID of the node to fetch.
id
,
boolean
false to fetch a root node only, true to search the entire node tree for the specified node.
recursive
)

Returns: The Node with the specified id, or null if not found.

public Node
getNode(final String
The ID of the node to fetch.
id
,
boolean
false to fetch a root node only, true to search the entire node tree for the specified node.
recursive
,
boolean
whether to use case sensitivity when comparing the node id.
ignoreCase
)

Returns: The Node with the specified id, or null if not found.

public Renderable
getRenderable(final Renderable out)

Returns: The renderable of the first node's first part.

public Renderable
getRenderable(final Renderable out, final Node node)

Returns: The renderable of the node's first part.

public Renderable
getRenderable(final Renderable out, final Node node, final NodePart nodePart)

public void
getRenderables(Array<Renderable>
the output array
renderables
,
Pool<Renderable>
the pool to obtain Renderables from
pool
)

Implements com.badlogic.gdx.graphics.g3d.RenderableProvider.getRenderables.

Traverses the Node hierarchy and collects Renderable instances for every node with a graphical representation.

protected void
getRenderables(Node node, Array<Renderable> renderables, Pool<Renderable> pool)

private void
invalidate(Node node)

Makes sure that each NodePart of the Node and its sub-nodes, doesn't reference a node outside this node tree and that all materials are listed in the materials array.

private void
invalidate()

Makes sure that each NodePart of each Node doesn't reference a node outside this node tree and that all materials are listed in the materials array.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

animationsback to summary
public final Array<Animation> animations

animations of the model, modifying node transformations

defaultShareKeyframesback to summary
public static boolean defaultShareKeyframes

Whether, by default, NodeKeyframe's are shared amongst Model and ModelInstance. Can be overridden per ModelInstance using the constructor argument.

materialsback to summary
public final Array<Material> materials

the materials of the model, used by nodes that have a graphical representation FIXME not sure if superfluous, allows modification of materials without having to traverse the nodes

modelback to summary
public final Model model

the Model this instances derives from

nodesback to summary
public final Array<Node> nodes

root nodes of the model

transformback to summary
public Matrix4 transform

the world transform

userDataback to summary
public Object userData

user definable value, which is passed to the Shader.

Constructor Detail

ModelInstanceback to summary
public ModelInstance(final Model model)

Constructs a new ModelInstance with all nodes and materials of the given model.

Parameters
model:Model

The Model to create an instance of.

ModelInstanceback to summary
public ModelInstance(final Model model, final String nodeId, boolean mergeTransform)
Parameters
model:Model

The source Model

nodeId:String

The ID of the root Node of the Model for the instance to contain

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final String nodeId, boolean mergeTransform)
Parameters
model:Model

The source Model

transform:Matrix4

The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.

nodeId:String

The ID of the root Node of the Model for the instance to contain

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final String nodeId, boolean parentTransform, boolean mergeTransform)

Recursively searches the mode for the specified node.

Parameters
model:Model

The source Model

nodeId:String

The ID of the Node within the Model for the instance to contain

parentTransform:boolean

True to apply the parent's node transform to the instance (only applicable if recursive is true).

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final String nodeId, boolean parentTransform, boolean mergeTransform)

Recursively searches the mode for the specified node.

Parameters
model:Model

The source Model

transform:Matrix4

The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.

nodeId:String

The ID of the Node within the Model for the instance to contain

parentTransform:boolean

True to apply the parent's node transform to the instance (only applicable if recursive is true).

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final String nodeId, boolean recursive, boolean parentTransform, boolean mergeTransform)
Parameters
model:Model

The source Model

nodeId:String

The ID of the Node within the Model for the instance to contain

recursive:boolean

True to recursively search the Model's node tree, false to only search for a root node

parentTransform:boolean

True to apply the parent's node transform to the instance (only applicable if recursive is true).

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final String nodeId, boolean recursive, boolean parentTransform, boolean mergeTransform)
Parameters
model:Model

The source Model

transform:Matrix4

The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.

nodeId:String

The ID of the Node within the Model for the instance to contain

recursive:boolean

True to recursively search the Model's node tree, false to only search for a root node

parentTransform:boolean

True to apply the parent's node transform to the instance (only applicable if recursive is true).

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final String nodeId, boolean recursive, boolean parentTransform, boolean mergeTransform, boolean shareKeyframes)
Parameters
model:Model

The source Model

transform:Matrix4

The Matrix4 instance for this ModelInstance to reference or null to create a new matrix.

nodeId:String

The ID of the Node within the Model for the instance to contain

recursive:boolean

True to recursively search the Model's node tree, false to only search for a root node

parentTransform:boolean

True to apply the parent's node transform to the instance (only applicable if recursive is true).

mergeTransform:boolean

True to apply the source node transform to the instance transform, resetting the node transform.

ModelInstanceback to summary
public ModelInstance(final Model model, final String... rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final String... rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

ModelInstanceback to summary
public ModelInstance(final Model model, final Array<String> rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final Array<String> rootNodeIds)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

ModelInstanceback to summary
public ModelInstance(final Model model, final Matrix4 transform, final Array<String> rootNodeIds, boolean shareKeyframes)

Constructs a new ModelInstance with only the specified nodes and materials of the given model.

ModelInstanceback to summary
public ModelInstance(final Model model, Vector3 position)

Constructs a new ModelInstance at the specified position.

ModelInstanceback to summary
public ModelInstance(final Model model, float x, float y, float z)

Constructs a new ModelInstance at the specified position.

ModelInstanceback to summary
public ModelInstance(final Model model, Matrix4 transform)

Constructs a new ModelInstance with the specified transform.

ModelInstanceback to summary
public ModelInstance(ModelInstance copyFrom)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

ModelInstanceback to summary
public ModelInstance(ModelInstance copyFrom, final Matrix4 transform)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

ModelInstanceback to summary
public ModelInstance(ModelInstance copyFrom, final Matrix4 transform, boolean shareKeyframes)

Constructs a new ModelInstance which is an copy of the specified ModelInstance.

Method Detail

calculateBoundingBoxback to summary
public BoundingBox calculateBoundingBox(final BoundingBox out)

Calculate the bounding box of this model instance. This is a potential slow operation, it is advised to cache the result.

Parameters
out:BoundingBox

the BoundingBox that will be set with the bounds.

Returns:BoundingBox

the out parameter for chaining

calculateTransformsback to summary
public void calculateTransforms()

Calculates the local and world transform of all Node instances in this model, recursively. First each Node#localTransform transform is calculated based on the translation, rotation and scale of each Node. Then each Node#calculateWorldTransform() is calculated, based on the parent's world transform and the local transform of each Node. Finally, the animation bone matrices are updated accordingly.

This method can be used to recalculate all transforms if any of the Node's local properties (translation, rotation, scale) was modified.
copyback to summary
public ModelInstance copy()
Returns:ModelInstance

A newly created ModelInstance which is a copy of this ModelInstance

copyAnimationback to summary
public void copyAnimation(Animation sourceAnim)

Copy the source animation to this ModelInstance

Parameters
sourceAnim:Animation

The source animation Animation

copyAnimationback to summary
public void copyAnimation(Animation sourceAnim, boolean shareKeyframes)

Copy the source animation to this ModelInstance

Parameters
sourceAnim:Animation

The source animation Animation

shareKeyframes:boolean

Shallow copy of NodeKeyframe's if it's true, otherwise make a deep copy.

copyAnimationsback to summary
public void copyAnimations(final Iterable<Animation> source)

Copy source animations to this ModelInstance

Parameters
source:Iterable<Animation>

Iterable collection of source animations Animation

copyAnimationsback to summary
public void copyAnimations(final Iterable<Animation> source, boolean shareKeyframes)

Copy source animations to this ModelInstance

Parameters
source:Iterable<Animation>

Iterable collection of source animations Animation

shareKeyframes:boolean

Shallow copy of NodeKeyframe's if it's true, otherwise make a deep copy.

copyNodesback to summary
private void copyNodes(Array<Node> nodes)
copyNodesback to summary
private void copyNodes(Array<Node> nodes, final String... nodeIds)
copyNodesback to summary
private void copyNodes(Array<Node> nodes, final Array<String> nodeIds)
extendBoundingBoxback to summary
public BoundingBox extendBoundingBox(final BoundingBox out)

Extends the bounding box with the bounds of this model instance. This is a potential slow operation, it is advised to cache the result.

Parameters
out:BoundingBox

the BoundingBox that will be extended with the bounds.

Returns:BoundingBox

the out parameter for chaining

getAnimationback to summary
public Animation getAnimation(final String id)
Parameters
id:String

The ID of the animation to fetch (case sensitive).

Returns:Animation

The Animation with the specified id, or null if not available.

getAnimationback to summary
public Animation getAnimation(final String id, boolean ignoreCase)
Parameters
id:String

The ID of the animation to fetch.

ignoreCase:boolean

whether to use case sensitivity when comparing the animation id.

Returns:Animation

The Animation with the specified id, or null if not available.

getMaterialback to summary
public Material getMaterial(final String id)
Parameters
id:String

The ID of the material to fetch.

Returns:Material

The Material with the specified id, or null if not available.

getMaterialback to summary
public Material getMaterial(final String id, boolean ignoreCase)
Parameters
id:String

The ID of the material to fetch.

ignoreCase:boolean

whether to use case sensitivity when comparing the material id.

Returns:Material

The Material with the specified id, or null if not available.

getNodeback to summary
public Node getNode(final String id)
Parameters
id:String

The ID of the node to fetch.

Returns:Node

The Node with the specified id, or null if not found.

getNodeback to summary
public Node getNode(final String id, boolean recursive)
Parameters
id:String

The ID of the node to fetch.

recursive:boolean

false to fetch a root node only, true to search the entire node tree for the specified node.

Returns:Node

The Node with the specified id, or null if not found.

getNodeback to summary
public Node getNode(final String id, boolean recursive, boolean ignoreCase)
Parameters
id:String

The ID of the node to fetch.

recursive:boolean

false to fetch a root node only, true to search the entire node tree for the specified node.

ignoreCase:boolean

whether to use case sensitivity when comparing the node id.

Returns:Node

The Node with the specified id, or null if not found.

getRenderableback to summary
public Renderable getRenderable(final Renderable out)
Returns:Renderable

The renderable of the first node's first part.

getRenderableback to summary
public Renderable getRenderable(final Renderable out, final Node node)
Returns:Renderable

The renderable of the node's first part.

getRenderableback to summary
public Renderable getRenderable(final Renderable out, final Node node, final NodePart nodePart)
getRenderablesback to summary
public void getRenderables(Array<Renderable> renderables, Pool<Renderable> pool)

Implements com.badlogic.gdx.graphics.g3d.RenderableProvider.getRenderables.

Traverses the Node hierarchy and collects Renderable instances for every node with a graphical representation. Renderables are obtained from the provided pool. The resulting array can be rendered via a ModelBatch.

Parameters
renderables:Array<Renderable>

the output array

pool:Pool<Renderable>

the pool to obtain Renderables from

getRenderablesback to summary
protected void getRenderables(Node node, Array<Renderable> renderables, Pool<Renderable> pool)
invalidateback to summary
private void invalidate(Node node)

Makes sure that each NodePart of the Node and its sub-nodes, doesn't reference a node outside this node tree and that all materials are listed in the materials array.

invalidateback to summary
private void invalidate()

Makes sure that each NodePart of each Node doesn't reference a node outside this node tree and that all materials are listed in the materials array.