net.jinx.video.model
Class Model

java.lang.Object
  net.jinx.video.DisplayList
      net.jinx.video.model.Model

All Implemented Interfaces:

Visible

public final class Model
extends DisplayList

Model objects are collections of MeshElement objects, along with coloration and per-vertex normal data (if used). They serve as the solid, visible objects within a rendered scene.
The following are valid MeshElement classes: LineLoop, Lines, LineStrip, Polygon, Quads, QuadStrip, TriangleFan, Triangles and TriangleStrip.
Models can be colored by any Coloration implementation. See the setColoration(Coloration) method for more info.
Models are normally unchanging, meaning that they're ideal for use with OpenGL display lists. That's the reason this class extends DisplayList (and to work around a texturing bug that only happened with display list wrapped models). There's almost no reason to not use display lists with Model objects, except memory requirements.

API Stability: Stable.

Constructor Summary

Model()
Constructs a Model with no Coloration.

Model(Coloration coloration)
Constructs a Model using the given Coloration object to color it.

Method Summary

void	activateColoration(java.lang.String name) Activates a secondary Coloration, using it's name to do so.
void	addColoration(java.lang.String name, Coloration coloration) Adds a secondary Coloration to this Model.
void	addMeshElement(MeshElement me) Adds a MeshElement to the model.
void	calcNormals() Calculates per-vertex normals for this Model by averaging the normals of the faces associated with those vertices.
java.lang.Object	clone() Duplicates this Model object.
void	draw(Context opt) Renders this Model with all of it's default settings.
Model	extrude(float dist) Constructs an extrusion Model from this Model.
MeshElement[]	getMeshElements() Provides an array of MeshElement objects used to construct this Model.
java.lang.String	getName() Provides the name of this Model.
float[][]	getNormals() Provides the array that normal vectors are being stored in.
java.lang.String	getSegment(int vertex) Provides the name of the segment for the given vertex.
java.lang.String	getTexture() Gets the name of the texture that this Model should use.
float[][]	getTextureCoordinates() Gets the texture coordinates for this Model.
float[][]	getVertices() Provides an array containing all of the vertices that are part of this Model.
void	nameSegment(int vertex, java.lang.String name) Names a segment of the Model.
void	setColoration(Coloration coloration) Sets the "Default" Coloration object used to color this Model and then activates it.
void	setName(java.lang.String name) Sets the name of this Model.
void	setNormals(float[][] n) Sets the array that normal vectors are stored in.
void	setTexture(java.lang.String texture) Sets the name of the texture that this Model should use.
void	setTextureCoordinates(float[][] tc) Sets the texture coordinates for this Model.
void	storeToHierarchy(Hierarchy h) Stores this Model to the given net.jinx.db.Hierarchy object, which can then be stored to XML or a java.util.Properties Object, or used to reconstruct the Model via the ModelUtil class.
void	subDraw(Context opt) The OpenGL calls in this method are what get wrapped in the display list.
void	subDraw(Context opt, Coloration coloration, boolean texture) Renders this Model with an arbitrary Coloration.
Model	toLineModel(float width) Produces a line version of this Model.
int	vertexCount() Returns the number of vertices this Model has, totaled from all it's MeshElements.

Methods inherited from class net.jinx.video.DisplayList

deinit, dispose, init, isListed, list, refresh

Methods inherited from class java.lang.Object

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

Constructor Detail

Model

public Model()

Constructs a Model with no Coloration.

Model

public Model(Coloration coloration)

Constructs a Model using the given Coloration object to color it. This calls setColoration(coloration).

Parameters:

coloration - the Coloration object.

Method Detail

getName

public java.lang.String getName()

Provides the name of this Model.

Returns:

the String name.

setName

public void setName(java.lang.String name)

Sets the name of this Model.

Parameters:

name - the String name.

setTexture

public void setTexture(java.lang.String texture)

Sets the name of the texture that this Model should use.

Parameters:

texture - the name. If this is null, no testure will be used.

getTexture

public java.lang.String getTexture()

Gets the name of the texture that this Model should use.

Returns:

the texture's name.

setTextureCoordinates

public void setTextureCoordinates(float[][] tc)

Sets the texture coordinates for this Model.

Parameters:

tc - the texture coordinate array.

getTextureCoordinates

public float[][] getTextureCoordinates()

Gets the texture coordinates for this Model.

Returns:

the texture coordinate array.

toLineModel

public Model toLineModel(float width)

Produces a line version of this Model. Because vertex counts will be different, Colorations are not carried over and will have to be moved manually, if desired.

Returns:

the new Model.

extrude

public Model extrude(float dist)

Constructs an extrusion Model from this Model. An extrusion model is normally slightly larger than a regular model (size determined by the parameter dist) and is scaled along the normals from the source Model. Any given vertex in the extruded Model will be exactly dist distance from the original vertex.

The results of this method are handy for displaying a force field around an object, but could also be used for a selection marker in a 3D user interface. Be creative ;-). I noticed while testing this feature that with a slight touch of cyan or blue, it can look like the object is encased in ice. Texture mapping it to look like ice would be very cool! Pun intended.

Parameters:

dist - the scaling distance that will be added to each vertice's position along it's normal vector.

Returns:

the new Model object for the extrusion. This is a very basic Model; if you need segments, texture coordinates, colorations, etc., you'll have to do it yourself. Fortunately, since you have the original on hand, this should be easy.

clone

public java.lang.Object clone()

Duplicates this Model object.

Overrides:

clone in class java.lang.Object

Returns:

a copy of this Model.

nameSegment

public void nameSegment(int vertex,
                        java.lang.String name)

Names a segment of the Model. Everything between this vertex and the next named segment will be colored the same.

Parameters:

vertex - the vertex index.

name - the name of the segment.

getSegment

public java.lang.String getSegment(int vertex)

Provides the name of the segment for the given vertex. If the given vertex has not been set, this will return null. If you absolutely must know what segment a vertex is in, you'll have to count backwards until you find a named vertex.

Parameters:

vertex - the vertex index top check.

Returns:

the name of the vertex.

setColoration

public void setColoration(Coloration coloration)

Sets the "Default" Coloration object used to color this Model and then activates it. This is done by calling addColoration("Default", coloration) and then activateColoration("Default").

Parameters:

coloration - the Coloration object to set as default and then activate.

Throws:

java.lang.NullPointerException - if coloration is null.

addColoration

public void addColoration(java.lang.String name,
                          Coloration coloration)

Adds a secondary Coloration to this Model.

Parameters:

name - the name of the Coloration; this can be used to activate it later.

coloration - the Coloration object to name and add.

Throws:

java.lang.NullPointerException - if name or coloration are null.

activateColoration

public void activateColoration(java.lang.String name)

Activates a secondary Coloration, using it's name to do so. This calls refresh(), as a natural consequence of the underlying display list becoming stale.

Parameters:

name - the name of the Coloration to activate.

Throws:

java.lang.IllegalArgumentException - if there is no Coloration with that name.

addMeshElement

public void addMeshElement(MeshElement me)

Adds a MeshElement to the model. This calls refresh() once it's through adding the MeshElement. This also sets the Model's normal array to null.

Parameters:

me - the MeshElement to add.

Throws:

java.lang.NullPointerException - if me is null.

storeToHierarchy

public void storeToHierarchy(Hierarchy h)

Stores this Model to the given net.jinx.db.Hierarchy object, which can then be stored to XML or a java.util.Properties Object, or used to reconstruct the Model via the ModelUtil class.

Parameters:

h - the Hierarchy object to store this Model to.

draw

public void draw(Context opt)

Renders this Model with all of it's default settings. This uses the currently active Coloration and activates it's texture. This will also use display lists to accelerate rendering (that's why Model extends DisplayList).

Specified by:

draw in interface Visible

Overrides:

draw in class DisplayList

Parameters:

opt - the rendering Context to use for rendering.

subDraw

public void subDraw(Context opt,
                    Coloration coloration,
                    boolean texture)

Renders this Model with an arbitrary Coloration.

Parameters:

opt - the rendering Context to use for rendering.

coloration - the Coloration object to draw with.

texture - should this Model's texture be activated? (If it has one.)

subDraw

public void subDraw(Context opt)

Description copied from class: DisplayList

The OpenGL calls in this method are what get wrapped in the display list.

Specified by:

subDraw in class DisplayList

vertexCount

public int vertexCount()

Returns the number of vertices this Model has, totaled from all it's MeshElements.

Returns:

the number of vertices.

getMeshElements

public MeshElement[] getMeshElements()

Provides an array of MeshElement objects used to construct this Model. They're returned in the natural order they're rendered in.

Returns:

the MeshElement array.

getVertices

public float[][] getVertices()

Provides an array containing all of the vertices that are part of this Model. This method is intensive, so use it sparingly.

Returns:

the vertex array. See the VertexUtil class for information on vertex arrays.

setNormals

public void setNormals(float[][] n)

Sets the array that normal vectors are stored in.

Parameters:

n - the array of normal vectors. This must be the same length as the number of vertices in this Model or null (if per-vertex normals are not desired).

calcNormals

public void calcNormals()

Calculates per-vertex normals for this Model by averaging the normals of the faces associated with those vertices.

getNormals

public float[][] getNormals()

Provides the array that normal vectors are being stored in.

Returns:

the array of normal vectors. This will be the same length as the number of vertices in this Model or it will be null (if per-vertex normals are not being used).