com.sygem.jazz3d3
Class Object3d

java.lang.Object
  |
  +--com.sygem.jazz3d3.Object3d

Direct Known Subclasses:

Checkerboard3d, Cube3d, Cylinder3d, Freeform3d, Hemisphere3d, Landscape3d, Lathe3d, Line3d, Model3d, Pyramid3d, Quad3d, Sphere3d, Text3d, Torus3d, Triangle3d

public class Object3d

extends java.lang.Object

Contains all vertex and face information relating to a single object.

Version:

3.0a

Author:

SyGem Software

Constructor Summary

Object3d(double xx, double yy, double zz)
Default constructor.

Method Summary

int	addChild(Object3d child, double xp, double yp, double zp) Add a child object to this object.
void	addQuad(Quad t) Add a quad to this object.
void	addTriangle(Triangle t) Add a triangle to this object.
void	addVertex(int num, float xx, float yy, float zz) Add a vertex to the object.
void	applyFaceChanges() Forces Jazz3D to recalculate the vertex colours of an object.
void	cleanUp() Shrinks the vertex and face containers to their minimum size.
Vertex	getCenter() Returns a vertex representing the center point of this object.
Object3d[]	getChildObjects() Gets an array full of all the child objects this object currently has.
boolean	getCollidable() Find out if the object is collidable.
boolean	getCulling() Returns the status of the backface culling.
Shape	getFace(int faceid) Get a particular face from this object.
int	getFaceColour(int faceid) Returns the colour of the specified face.
int	getID() Get the numerical identifier of this object.
java.lang.String	getName() Get the name identifier of this object.
int	getNumberOfFaces() Get the number of faces in the object.
int	getNumberOfSubFaces() Get the number of faces in the object (including sub-objects).
int	getNumberOfSubVertices() Get the number of vertices in the object (including sub-objects).
int	getNumberOfVertices() Get the number of vertices in the object.
Render	getRenderer() Gets the current renderer being used with this object.
Shape[]	getShapeArray() Gets an array full of all the faces this object currently has.
boolean	getUseVertexUVCoords() Returns true if vertex UV coordinates are being used, false if not.
Vertex	getVertex(int vertid) Get a particular vertex from this object.
Vertex[]	getVertexArray() Gets an array full of all the vertices this object currently has.
boolean	getVisible() Returns the visibility of the object.
Vertex	getWorldVertex(int vertid) Get a particular vertex from this object, the coordinates of which will be in world-space.
boolean	pick(Vertex start, Vertex end) Casts a ray between 2 points in space, and tests to see if any of the faces in this object collide with it.
boolean	pickClosest(Vertex start, Vertex end) Casts a ray between 2 points in space, and tests to see if any of the faces in this object collide with it.
boolean	pickFace(Vertex start, Vertex end, int faceID) Casts a ray between 2 points in space, and tests to see if a particular face in this object collide with it.
void	prepForDisplay(boolean bbon) Finalizes any object creation activities (like bounding-box creation).
void	recreateVertexNormals() Force the recreation of all vertex normals.
void	rotateLocal(double xx, double yy, double zz) Rotates the object a given amount around the object's own axis.
void	rotateLocal(double xx, double yy, double zz, double px, double py, double pz) Rotates the object a given amount around a specified point, around the object's own axis.
void	rotateWorld(double xx, double yy, double zz) Rotates the object a given amount around the static world axis.
void	rotateWorld(double xx, double yy, double zz, double px, double py, double pz) Rotates the object a given amount around a specified point, around the static world axis.
void	scaleObject(double xs, double ys, double zs) Scales the object, relative to its current size.
void	setAllTextures(int texid) Sets the texture for all object faces.
void	setAmbientColour(int r, int g, int b) Sets the ambient colour of an object.
void	setCollidable(boolean collide) Toggles whether or not this object can be collided with.
void	setColour(int r, int g, int b) Sets the colour of the whole object.
void	setCulling(boolean cull) Toggles the use of backface culling for this object.
void	setFaceColour(int faceid, int r, int g, int b) Set the colour of an individual face.
void	setFaceColourQuick(int faceid, int r, int g, int b) Set the colour of an individual face.
void	setName(java.lang.String newName) Sets the name identifier of this object.
void	setPosition(double xx, double yy, double zz) Allows you to set the position of the object directly.
void	setRenderer(Render newRenderer) Sets the renderer to be used with this object.
void	setShapeArray(Shape[] s) Sets all of the faces for this object.
void	setTexture(int texid) Sets the texture for this object.
void	setTexture(int faceid, int texid) Sets the texture for a given face.
void	setUseVertexUVCoords(boolean uv) Instruct the texture mappers to use UV coordinates from vertices, not faces.
void	setVertexArray(Vertex[] v) Sets all of the vertices for this object.
void	setVertexTexture(int vertexid, int texid) Sets the image to be rendered at a given vertex.
void	setVisible(boolean visible) Toggles object visibility.
void	translateLocal(double xx, double yy, double zz) Translate the object relative to its own axis.
void	translateWorld(double xx, double yy, double zz) Translate the object relative to the static world axis.

Methods inherited from class java.lang.Object

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

Constructor Detail

Object3d

public Object3d(double xx,
                double yy,
                double zz)

Default constructor.

Parameters:

xx - The x position of the center of the object.

yy - The y position of the center of the object.

zz - The z position of the center of the object.

Method Detail

setName

public final void setName(java.lang.String newName)

Sets the name identifier of this object.

Parameters:

newName - The name of this object

See Also:

World.getObject(String), getName()

getName

public final java.lang.String getName()

Get the name identifier of this object.

Returns:

The name of this object

See Also:

World.getObject(String), setName(String)

getID

public final int getID()

Get the numerical identifier of this object.

Returns:

The id of this object

See Also:

World.getObject(String)

recreateVertexNormals

public final void recreateVertexNormals()

Force the recreation of all vertex normals.

addChild

public final int addChild(Object3d child,
                          double xp,
                          double yp,
                          double zp)

Add a child object to this object. This creates a hierarchy of objects, so when the parent is moved or rotated, the children move accordingly.

NOTE: The pivot point is a point in space relative to the center of the object.

Parameters:

child - Any valid object - primitive or model.

xp - The x position of the pivot point, used when rotating the child

yp - The y position of the pivot point, used when rotating the child

zp - The z position of the pivot point, used when rotating the child

addTriangle

public final void addTriangle(Triangle t)

Add a triangle to this object. The vertices referenced by the Triangle MUST have been added already, or an error will occur.

Parameters:

t - A Triangle

See Also:

addVertex(int, float, float, float), Triangle

addQuad

public final void addQuad(Quad t)

Add a quad to this object. The vertices referenced by the Quad MUST have been added already, or an error will occur.

Parameters:

t - A Quad

See Also:

addVertex(int, float, float, float), Quad

cleanUp

public final void cleanUp()

Shrinks the vertex and face containers to their minimum size. This should be called by any object that uses addVertex(), addTriangle() or addQuad().

setTexture

public final void setTexture(int texid)

Sets the texture for this object. This is used for animated textures.

Parameters:

texid - An integer as returned by the setTexture() method of the renderer.

See Also:

RenderTextured.setTexture(com.sygem.jazz3d3.Texture)

setTexture

public final void setTexture(int faceid,
                             int texid)

Sets the texture for a given face. This is used for animated textures.

Parameters:

faceid - The face (polygon) of the object. Numbered from zero.

texid - An integer as returned by the setTexture() method of the renderer.

See Also:

RenderTextured.setTexture(com.sygem.jazz3d3.Texture)

setAllTextures

public final void setAllTextures(int texid)

Sets the texture for all object faces. This is used for animated textures.

Parameters:

texid - An integer as returned by the setTexture() method of the renderer.

See Also:

RenderTextured.setTexture(com.sygem.jazz3d3.Texture)

getFace

public final Shape getFace(int faceid)

Get a particular face from this object.

Parameters:

faceid - The id of the face you want - starts from zero.

Returns:

The face, or null if faceid is out of range.

getNumberOfFaces

public final int getNumberOfFaces()

Get the number of faces in the object. Useful for impressing your friends! (joke)

Returns:

the number of faces in the object.

getNumberOfSubFaces

public final int getNumberOfSubFaces()

Get the number of faces in the object (including sub-objects).

Returns:

the number of faces in the object.

getVertex

public final Vertex getVertex(int vertid)

Get a particular vertex from this object.

Parameters:

vertid - The id of the vertex you want - starts from zero.

Returns:

The Vertex, or null if vertid is out of range.

getWorldVertex

public Vertex getWorldVertex(int vertid)

Get a particular vertex from this object, the coordinates of which will be in world-space.

Parameters:

vertid - The id of the vertex you want - starts from zero.

Returns:

The Vertex, or null if vertid is out of range.

getNumberOfVertices

public final int getNumberOfVertices()

Get the number of vertices in the object. Also useful for impressing your friends (if you still have any)!

Returns:

the number of vertices in the object.

getNumberOfSubVertices

public final int getNumberOfSubVertices()

Get the number of vertices in the object (including sub-objects).

Returns:

the number of vertices in the object.

getChildObjects

public final Object3d[] getChildObjects()

Gets an array full of all the child objects this object currently has. WARNING: This will return NULL if no children have been added, so don't forget to check for that case!

See Also:

addChild(com.sygem.jazz3d3.Object3d, double, double, double)

getVertexArray

public final Vertex[] getVertexArray()

Gets an array full of all the vertices this object currently has.

setVertexArray

public final void setVertexArray(Vertex[] v)

Sets all of the vertices for this object.

Parameters:

v - An array of Vertexes

See Also:

getVertexArray()

getShapeArray

public final Shape[] getShapeArray()

Gets an array full of all the faces this object currently has.

setShapeArray

public final void setShapeArray(Shape[] s)

Sets all of the faces for this object.

Parameters:

s - An array of Shapes

See Also:

getShapeArray()

addVertex

public final void addVertex(int num,
                            float xx,
                            float yy,
                            float zz)

Add a vertex to the object. Creates the vertex at a specified position in the vertex container, and at the world coordinates passed in.

See Also:

cleanUp()

getCenter

public final Vertex getCenter()

Returns a vertex representing the center point of this object.

Returns:

A vertex.

See Also:

Vertex

setRenderer

public final void setRenderer(Render newRenderer)

Sets the renderer to be used with this object. Note that this has no effect for the Line3d primitive, which can only use the RenderOutline renderer.

Parameters:

newRenderer - The renderer to be used.

getRenderer

public final Render getRenderer()

Gets the current renderer being used with this object.

Returns:

The renderer being used.

setUseVertexUVCoords

public final void setUseVertexUVCoords(boolean uv)

Instruct the texture mappers to use UV coordinates from vertices, not faces.

getUseVertexUVCoords

public final boolean getUseVertexUVCoords()

Returns true if vertex UV coordinates are being used, false if not.

translateWorld

public final void translateWorld(double xx,
                                 double yy,
                                 double zz)

Translate the object relative to the static world axis. This will also move any child objects present. You can think of the world axis as being the same as the screen axis.

Parameters:

xx - The distance along the x-axis to translate.

yy - The distance along the x-axis to translate.

zz - The distance along the x-axis to translate.

translateLocal

public final void translateLocal(double xx,
                                 double yy,
                                 double zz)

Translate the object relative to its own axis. This will also move any child objects present. The object axis starts off being the same as the world axis, but rotates along with the object. This way you can ensure that and object can always move in the correct direction.

Parameters:

xx - The distance along the x-axis to translate.

yy - The distance along the x-axis to translate.

zz - The distance along the x-axis to translate.

setPosition

public final void setPosition(double xx,
                              double yy,
                              double zz)

Allows you to set the position of the object directly. This will actually set the position of the center point of the object, as set when the object was created.

Parameters:

xx - The new x position of the center of the object

yy - The new y position of the center of the object

zz - The new z position of the center of the object

rotateWorld

public final void rotateWorld(double xx,
                              double yy,
                              double zz)

Rotates the object a given amount around the static world axis.

Parameters:

xx - The number of degrees to rotate the object around the x-axis.

yy - The number of degrees to rotate the object around the y-axis.

zz - The number of degrees to rotate the object around the z-axis.

See Also:

rotateWorld(double, double, double, double, double, double)

rotateWorld

public final void rotateWorld(double xx,
                              double yy,
                              double zz,
                              double px,
                              double py,
                              double pz)

Rotates the object a given amount around a specified point, around the static world axis.

Parameters:

xx - The number of degrees to rotate the object around the x-axis.

yy - The number of degrees to rotate the object around the y-axis.

zz - The number of degrees to rotate the object around the z-axis.

px - The x position of the point to rotate around.

py - The y position of the point to rotate around.

pz - The z position of the point to rotate around.

See Also:

rotateWorld(double, double, double)

rotateLocal

public final void rotateLocal(double xx,
                              double yy,
                              double zz)

Rotates the object a given amount around the object's own axis.

Parameters:

xx - The number of degrees to rotate the object around the x-axis.

yy - The number of degrees to rotate the object around the y-axis.

zz - The number of degrees to rotate the object around the z-axis.

See Also:

rotateLocal(double, double, double, double, double, double)

rotateLocal

public final void rotateLocal(double xx,
                              double yy,
                              double zz,
                              double px,
                              double py,
                              double pz)

Rotates the object a given amount around a specified point, around the object's own axis.

Parameters:

xx - The number of degrees to rotate the object around the x-axis.

yy - The number of degrees to rotate the object around the y-axis.

zz - The number of degrees to rotate the object around the z-axis.

px - The x position of the point to rotate around.

py - The y position of the point to rotate around.

pz - The z position of the point to rotate around.

See Also:

rotateLocal(double, double, double)

scaleObject

public final void scaleObject(double xs,
                              double ys,
                              double zs)

Scales the object, relative to its current size. A value of 1 would not scale along that axis. Any value less that 1 would indicate a reduction in size.

Parameters:

xs - The amount to scale along the x-axis

ys - The amount to scale along the y-axis

zs - The amount to scale along the z-axis

setFaceColour

public final void setFaceColour(int faceid,
                                int r,
                                int g,
                                int b)

Set the colour of an individual face. This will automatically recalculate the vertex colours, as required by the gourard shading renderers. Note that this can be a costly process, so for applying multiple changes, you should use setFaceColourQuick().

Parameters:

faceid - The face to change the colour of.

r - The red component of the new face colour.

g - The green component of the new face colour.

b - The blue component of the new face colour.

See Also:

setFaceColourQuick(int, int, int, int)

setFaceColourQuick

public final void setFaceColourQuick(int faceid,
                                     int r,
                                     int g,
                                     int b)

Set the colour of an individual face. This method will NOT automatically recalculate the vertex colours, as required by the gourard shading renderers. To force this you must use applyFaceChanges() once you have completed the face colour changes.

Parameters:

faceid - The face to change the colour of.

r - The red component of the new face colour.

g - The green component of the new face colour.

b - The blue component of the new face colour.

See Also:

applyFaceChanges(), setFaceColour(int, int, int, int)

applyFaceChanges

public final void applyFaceChanges()

Forces Jazz3D to recalculate the vertex colours of an object. This MUST be called after any calls to setFaceColourFast().

See Also:

setFaceColourQuick(int, int, int, int)

setColour

public final void setColour(int r,
                            int g,
                            int b)

Sets the colour of the whole object. Every face in the object will be set to the specified colour.

Parameters:

r - The red component of the new object colour.

g - The green component of the new object colour.

b - The blue component of the new object colour.

getFaceColour

public final int getFaceColour(int faceid)

Returns the colour of the specified face. Here's an example of how to get the RGB values of the colour:

int faceColour = myObject.getFaceColour(2);
int red = (faceColour & 0xFF0000) >> 16;
int green = (faceColour & 0x00FF00) >> 8;
int blue = (faceColour & 0x0000FF);


Parameters:

faceid - The face you want to find the colour of.

Returns:

The colour of the face.

setAmbientColour

public final void setAmbientColour(int r,
                                   int g,
                                   int b)

Sets the ambient colour of an object. The ambient colour is the colour the object will appear when there is no light falling on it.

Parameters:

r - The red component of the new ambient colour.

g - The green component of the new ambient colour.

b - The blue component of the new ambient colour.

setCulling

public final void setCulling(boolean cull)

Toggles the use of backface culling for this object. Backface culling is a very useful way of speeding up your program - basically, it works out if a face can be seen, and if not, it won't draw it! Simple, and very effective. By default, culling is enabled when you create your objects.

Parameters:

cull - True if backface culling is to be used, and false if not.

See Also:

getCulling()

getCulling

public final boolean getCulling()

Returns the status of the backface culling.

See Also:

setCulling(boolean)

setVisible

public final void setVisible(boolean visible)

Toggles object visibility. This provides an easy way of excluding an object from the scene temporarily.

Parameters:

visible - True if the object should be visible, and false if not.

getVisible

public final boolean getVisible()

Returns the visibility of the object.

See Also:

setVisible(boolean)

prepForDisplay

public final void prepForDisplay(boolean bbon)

Finalizes any object creation activities (like bounding-box creation). Should be called by all sub-classes of Object3d.

Parameters:

bbon - Set this to true if you want the object's bounding box to be created

setVertexTexture

public final void setVertexTexture(int vertexid,
                                   int texid)

Sets the image to be rendered at a given vertex. This is only applicable if you are going to use the RenderOutline renderer.

Parameters:

vertexid - An integer referencing a vertex in the object.

texid - An integer as returned by the setVertexImage() method of the renderer.

See Also:

RenderOutline.setVertexImage(com.sygem.jazz3d3.Texture)

setCollidable

public final void setCollidable(boolean collide)

Toggles whether or not this object can be collided with. This allows you to eliminate objects from collision tests, which can speed up the collision detection process considerably.

By default, all objects are collidable.

Parameters:

collide - True if this object should be collidable, false if not

getCollidable

public final boolean getCollidable()

Find out if the object is collidable.

Returns:

True if this object is collidable, false if not

pick

public final boolean pick(Vertex start,
                          Vertex end)

Casts a ray between 2 points in space, and tests to see if any of the faces in this object collide with it. If a collision is detected, the information is filled out in the static HitPoint class. Only one collision is recorded per object - as soon as a collision is detected, no more faces are tested.

Parameters:

start - The start point of the ray

end - The end point of the ray

See Also:

Vertex, HitPoint

pickClosest

public final boolean pickClosest(Vertex start,
                                 Vertex end)

Casts a ray between 2 points in space, and tests to see if any of the faces in this object collide with it. If a collision is detected, the information is filled out in the static HitPoint class. Only information about the closest collision is recorded.

Parameters:

start - The start point of the ray

end - The end point of the ray

See Also:

Vertex, HitPoint

pickFace

public final boolean pickFace(Vertex start,
                              Vertex end,
                              int faceID)

Casts a ray between 2 points in space, and tests to see if a particular face in this object collide with it. If a collision is detected, the information is filled out in the static HitPoint class.

Parameters:

start - The start point of the ray

end - The end point of the ray

faceID - The face to test

See Also:

Vertex, HitPoint