com.badlogic.gdx.graphics.g3d

Class ModelInstance

java.lang.Object

com.badlogic.gdx.graphics.g3d.ModelInstance

All Implemented Interfaces:

RenderableProvider

public class ModelInstance
extends Object
implements RenderableProvider

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

Fields

Modifier and Type	Field and Description
Array<Animation>	animations animations of the model, modifying node transformations
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
Model	model the Model this instances derives from
Array<Node>	nodes root nodes of the model
Matrix4	transform the world transform
Object	userData user definable value, which is passed to the shader.

Constructor Summary

Constructors

Constructor and Description
ModelInstance(Model model) Constructs a new ModelInstance with all nodes and materials of the given model.
ModelInstance(Model model, Array<String> rootNodeIds) Constructs a new ModelInstance with only the specified nodes and materials of the given model.
ModelInstance(Model model, float x, float y, float z) Constructs a new ModelInstance at the specified position.
ModelInstance(ModelInstance copyFrom) Constructs a new ModelInstance which is an copy of the specified ModelInstance.
ModelInstance(ModelInstance copyFrom, Matrix4 transform) Constructs a new ModelInstance which is an copy of the specified ModelInstance.
ModelInstance(Model model, Matrix4 transform) Constructs a new ModelInstance with the specified transform.
ModelInstance(Model model, Matrix4 transform, Array<String> rootNodeIds) Constructs a new ModelInstance with only the specified nodes and materials of the given model.
ModelInstance(Model model, Matrix4 transform, String... rootNodeIds) Constructs a new ModelInstance with only the specified nodes and materials of the given model.
ModelInstance(Model model, Matrix4 transform, String nodeId, boolean mergeTransform)
ModelInstance(Model model, Matrix4 transform, String nodeId, boolean parentTransform, boolean mergeTransform) Recursively searches the mode for the specified node.
ModelInstance(Model model, Matrix4 transform, String nodeId, boolean recursive, boolean parentTransform, boolean mergeTransform)
ModelInstance(Model model, String... rootNodeIds) Constructs a new ModelInstance with only the specified nodes and materials of the given model.
ModelInstance(Model model, String nodeId, boolean mergeTransform)
ModelInstance(Model model, String nodeId, boolean parentTransform, boolean mergeTransform) Recursively searches the mode for the specified node.
ModelInstance(Model model, String nodeId, boolean recursive, boolean parentTransform, boolean mergeTransform)
ModelInstance(Model model, Vector3 position) Constructs a new ModelInstance at the specified position.

Method Summary

Methods

Modifier and Type	Method and Description
BoundingBox	calculateBoundingBox(BoundingBox out) Calculate the bounding box of this model instance.
void	calculateTransforms() Calculates the local and world transform of all Node instances in this model, recursively.
ModelInstance	copy()
BoundingBox	extendBoundingBox(BoundingBox out) Extends the bounding box with the bounds of this model instance.
Animation	getAnimation(String id)
Animation	getAnimation(String id, boolean ignoreCase)
Material	getMaterial(String id)
Material	getMaterial(String id, boolean ignoreCase)
Node	getNode(String id)
Node	getNode(String id, boolean recursive)
Node	getNode(String id, boolean recursive, boolean ignoreCase)
Renderable	getRenderable(Renderable out)
Renderable	getRenderable(Renderable out, Node node)
Renderable	getRenderable(Renderable out, Node node, NodePart nodePart)
void	getRenderables(Array<Renderable> renderables, Pool<Renderable> pool) Traverses the Node hierarchy and collects Renderable instances for every node with a graphical representation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

materials

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

nodes

public final Array<Node> nodes

root nodes of the model

animations

public final Array<Animation> animations

animations of the model, modifying node transformations

model

public final Model model

the Model this instances derives from

transform

public Matrix4 transform

the world transform

userData

public Object userData

user definable value, which is passed to the shader.

Constructor Detail

ModelInstance

public ModelInstance(Model model)

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

Parameters:

model - The Model to create an instance of.

ModelInstance

public ModelInstance(Model model,
             String nodeId,
             boolean mergeTransform)

Parameters:

model - The source Model

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

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

ModelInstance

public ModelInstance(Model model,
             Matrix4 transform,
             String nodeId,
             boolean mergeTransform)

Parameters:

model - The source Model

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

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

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

ModelInstance

public ModelInstance(Model model,
             String nodeId,
             boolean parentTransform,
             boolean mergeTransform)

Recursively searches the mode for the specified node.

Parameters:

model - The source Model

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

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

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

ModelInstance

public ModelInstance(Model model,
             Matrix4 transform,
             String nodeId,
             boolean parentTransform,
             boolean mergeTransform)

Recursively searches the mode for the specified node.

Parameters:

model - The source Model

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

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

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

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

ModelInstance

public ModelInstance(Model model,
             String nodeId,
             boolean recursive,
             boolean parentTransform,
             boolean mergeTransform)

Parameters:

model - The source Model

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

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

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

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

ModelInstance

public ModelInstance(Model model,
             Matrix4 transform,
             String nodeId,
             boolean recursive,
             boolean parentTransform,
             boolean mergeTransform)

Parameters:

model - The source Model

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

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

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

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

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

ModelInstance

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

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

ModelInstance

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

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

ModelInstance

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

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

ModelInstance

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

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

ModelInstance

public ModelInstance(Model model,
             Vector3 position)

Constructs a new ModelInstance at the specified position.

ModelInstance

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

Constructs a new ModelInstance at the specified position.

ModelInstance

public ModelInstance(Model model,
             Matrix4 transform)

Constructs a new ModelInstance with the specified transform.

ModelInstance

public ModelInstance(ModelInstance copyFrom)

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

ModelInstance

public ModelInstance(ModelInstance copyFrom,
             Matrix4 transform)

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

Method Detail

copy

public ModelInstance copy()

Returns:

A newly created ModelInstance which is a copy of this ModelInstance

getRenderables

public void getRenderables(Array<Renderable> renderables,
                  Pool<Renderable> pool)

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.

Specified by:

getRenderables in interface RenderableProvider

Parameters:

renderables - the output array

pool - the pool to obtain Renderables from

getRenderable

public Renderable getRenderable(Renderable out)

Returns:

The renderable of the first node's first part.

getRenderable

public Renderable getRenderable(Renderable out,
                       Node node)

Returns:

The renderable of the node's first part.

getRenderable

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

calculateTransforms

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.

calculateBoundingBox

public BoundingBox calculateBoundingBox(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 - the BoundingBox that will be set with the bounds.

Returns:

the out parameter for chaining

extendBoundingBox

public BoundingBox extendBoundingBox(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 - the BoundingBox that will be extended with the bounds.

Returns:

the out parameter for chaining

getAnimation

public Animation getAnimation(String id)

Parameters:

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

Returns:

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

getAnimation

public Animation getAnimation(String id,
                     boolean ignoreCase)

Parameters:

id - The ID of the animation to fetch.

ignoreCase - whether to use case sensitivity when comparing the animation id.

Returns:

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

getMaterial

public Material getMaterial(String id)

Parameters:

id - The ID of the material to fetch.

Returns:

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

getMaterial

public Material getMaterial(String id,
                   boolean ignoreCase)

Parameters:

id - The ID of the material to fetch.

ignoreCase - whether to use case sensitivity when comparing the material id.

Returns:

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

getNode

public Node getNode(String id)

Parameters:

id - The ID of the node to fetch.

Returns:

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

getNode

public Node getNode(String id,
           boolean recursive)

Parameters:

id - The ID of the node to fetch.

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

Returns:

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

getNode

public Node getNode(String id,
           boolean recursive,
           boolean ignoreCase)

Parameters:

id - The ID of the node to fetch.

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

ignoreCase - whether to use case sensitivity when comparing the node id.

Returns:

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