vmm.core3D
Class Grid3D

java.lang.Object
  vmm.core3D.Grid3D

public class Grid3D
extends java.lang.Object

A Grid3D represents a surface in three-space as an array of vectors. The first index of the array represents the "u" direction on the surface, while the second index represents the "v" directions. Methods are provided for drawing the surface a View3D or View3DLit. The surface is considered to be made up of "patches" which can be further divided into "subpatches". The surface can be drawn in wireframe form, by drawing each sub-patch, or just by drawing the large patches. When drawn in patch form, the lighting of the surface is derived from the View in which it is drawn. The intrinsic color of each individual patch can be set as part of the surface data. Drawing of the Grid3D will normally be done by calling methods in View3D and View3DLit, which will make sure that the data needed to complete the drawing correctly is done correctly.

It is possible to construct a surface from several copies of a basic grid, where each copy is obtained by applying a TransformMatrix to the basic grid. These transforms are specified by the method addGridTransform(GridTransformMatrix). See also setUseIdentityTransform(boolean).

Constructor Summary

Grid3D(int uPatchCount, int vPatchCount)
Creates a surface grid with the specified numbers of patches in the U and V directions and with 6 subpatches per patch (in each direction).

Grid3D(int uPatchCount, int vPatchCount, int subPatchesPerPatch)
Creates a surface grid with the specified numbers of patches in the U and V directions and with a specified number of subpatches per patch (in each direction).

Method Summary

void	addGridTransform(GridTransformMatrix transform) Adds a transformed copy of the basic grid to the surface.
void	applyTransform(Transform3D transform, View3D view3D) Applies a transform the all vertices of the surface, to produce a set of transformed vertices.
void	clearNormals() Removes all normal vectors that were set using setNormal(int, int, Vector3D).
void	clearPatchColors() Resets all individual patch colors, as set by setPatchColor(int, int, Color), to the default value.
void	discardGridTransforms() Discards any grid transforms that have been added by addGridTransform(GridTransformMatrix).
void	drawCurves(View3D view, java.awt.Graphics2D g) Draws a wireframe rendering of the surface by drawing some or all of the grid lines in the U and V directions.
void	drawMajorPatches(View3DLit view, java.awt.Graphics2D g) Draws a "rough" version of the surface by drawing the (major) patches rather than the subpatches.
void	drawSubPatches(View3DLit view, java.awt.Graphics2D g, double startPercent, double endPercent) Draws some or all of the subpatches that make up the surface as shaded, lighted color patches.
java.awt.Color	getDefaultBackColor() Get the default color for the back face of a patch.
java.awt.Color	getDefaultPatchColor() Get the default patch color.
Vector3D	getNormal(int uIndex, int vIndex) Returns a normal vector (not assumed to be a unit vector) at a specified vertex of the basic grid.
java.awt.Color	getPatchColor(int uIndex, int vIndex, boolean frontFace) Gets the intrinsic color of a subpatch.
int	getPatchCountInGrid() Gets the total number of (major) patches in the basic grid.
int	getPatchCountInSurface() Gets the total number of (major) patches in the surface, which might consist of several copies of the baic grid.
int	getSubPatchCountInGrid() Gets the total number of subpatches in the basic grid.
int	getSubPatchCountInSurface() Gets the total number of subpatches in the surface, which might consist of several copies of the baic grid.
int	getSubpatchesPerPatch() Gets the number of subpatches that lie along each edge of a (major) patch, as specified in the constructor.
int	getUCount() Gets the number of vertices along the U direction of the basic grid.
int	getUCurveIncrement() Gets the U increment value, which is used to decide which grid lines to draw.
Vector3D	getUnitNormal(int uIndex, int vIndex) Returns a unit normal vector at a specified vertex in the basic grid.
int	getUPatchCount() Gets the number of (major) patches in the U direction, as specfied in the contructor or in setPatchCount(int, int).
boolean	getUseIdentityTransform() Gets the value of the useIdentityTransform property.
int	getVCount() Gets the number of vertices along the V direction of the basic grid.
int	getVCurveIncrement() Gets the V increment value, which is used to decide which grid lines to draw.
Vector3D	getVertex(int uIndex, int vIndex) Get one of the points in the basic grid.
int	getVPatchCount() Gets the number of (major) patches in the V direction, as specfied in the contructor or in setPatchCount(int, int).
void	setDefaultBackColor(java.awt.Color defaultBackColor) Set the default color for the back face of a patch.
void	setDefaultPatchColor(java.awt.Color c) Set the default color that is used as the intrinsic color of a patch for which no other color has been set.
void	setNormal(int uIndex, int vIndex, Vector3D normalVector) Set a normal vector at one of the vertices in the basic grid.
void	setPatchColor(int uIndex, int vIndex, java.awt.Color c) Sets the intrinsic color of a subpatch.
void	setUCurveIncrement(int curveIncrement) Sets the U increment value, which is used to decide which grid lines to draw.
void	setUseIdentityTransform(boolean useIdentityTransform) Sets the value of the useIdentityTransform property.
void	setVCurveIncrement(int curveIncrement) Sets the V increment value, which is used to decide which grid lines to draw.
void	setVertex(int uIndex, int vIndex, Vector3D v) Assign one of the points in the basic grid.

Methods inherited from class java.lang.Object

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

Constructor Detail

Grid3D

public Grid3D(int uPatchCount,
              int vPatchCount)

Creates a surface grid with the specified numbers of patches in the U and V directions and with 6 subpatches per patch (in each direction). Initially, all vertices of the surface are undefined. They can be set by calling setVertex(int, int, Vector3D).

Parameters:

uPatchCount - the number of major patches in the U direction. The number of subpatches is 6*uPatchCount. Must be positive.

vPatchCount - the number of major patches in the V direction. The number of subpatches is 6*vPatchCount. Must be positive.

Grid3D

public Grid3D(int uPatchCount,
              int vPatchCount,
              int subPatchesPerPatch)

Creates a surface grid with the specified numbers of patches in the U and V directions and with a specified number of subpatches per patch (in each direction). Initially, all vertices of the surface are undefined. They can be set by calling setVertex(int, int, Vector3D).

Parameters:

uPatchCount - the number of major patches in the U direction. The number of subpatches is subPatchesPerPatch*uPatchCount. Must be positive.

vPatchCount - the number of major patches in the V direction. The number of subpatches is subPatchesPerPatch*vPatchCount. Must be positive.

subPatchesPerPatch - the number of sub-patches that lie along each side of a patch. Note that the actual number of subpatches in a patch is the square of this number.

Method Detail

addGridTransform

public void addGridTransform(GridTransformMatrix transform)

Adds a transformed copy of the basic grid to the surface.

Parameters:

transform - A transform matrix that is applied to the basic grid to produce a transformed copy. This should be non-null (but null values are simply ignored).

discardGridTransforms

public void discardGridTransforms()

Discards any grid transforms that have been added by addGridTransform(GridTransformMatrix).

getUseIdentityTransform

public boolean getUseIdentityTransform()

Gets the value of the useIdentityTransform property.

See Also:

setUseIdentityTransform(boolean)

setUseIdentityTransform

public void setUseIdentityTransform(boolean useIdentityTransform)

Sets the value of the useIdentityTransform property. The default value is true. This property has an effect only if one or more extra transformed copied of the basic grid have been added with the addGridTransform(GridTransformMatrix) method. If the value of this property is set to false, then the basic grid is NOT part of the data -- that is, the surface represented by this Grid3D object consists ONLY of the transformed copies of the basic grid.

setVertex

public final void setVertex(int uIndex,
                            int vIndex,
                            Vector3D v)

Assign one of the points in the basic grid.

Parameters:

uIndex - The first index of the array position that is being set. This index ranges from 0 to the value of getUCount() minus 1.

vIndex - The second index of the array position that is being set. This index ranges from 0 to the value of getVCount() minus 1.

v - The vector the gives the coordinates of the point on the surface. A pointer to this vector, not a copy of the vector, is stored. This parameter can be null, indicating a missing point on the surface. In that case, any grid line or patch that has the point as a vertex is not drawn.

getVertex

public final Vector3D getVertex(int uIndex,
                                int vIndex)

Get one of the points in the basic grid.

See Also:

setVertex(int, int, Vector3D)

getUCount

public int getUCount()

Gets the number of vertices along the U direction of the basic grid. This number is one plus the total number of subpatches in that direction, and is computed as 1 + uPatchCount*subPatchesPerPatch. Note that vertices are numbered from 0 to getUCount()-1 while subpatches are numbered from 0 to getUCount()-2 in the U direction.

getUPatchCount

public int getUPatchCount()

Gets the number of (major) patches in the U direction, as specfied in the contructor or in setPatchCount(int, int). The number of vertices in the U direction is this value multiplied by subPatchesPerPatch.

getVCount

public int getVCount()

Gets the number of vertices along the V direction of the basic grid. This number is one plus the total number of subpatches in that direction, and is computed as 1 + vPatchCount*subPatchesPerPatch. Note that vertices are numbered from 0 to getVCount()-1 while subpatches are numbered from 0 to getVCount()-2 in the U direction.

getVPatchCount

public int getVPatchCount()

Gets the number of (major) patches in the V direction, as specfied in the contructor or in setPatchCount(int, int). The number of subpatches in the V direction is this value multiplied by subPatchesPerPatch.

getSubPatchCountInGrid

public int getSubPatchCountInGrid()

Gets the total number of subpatches in the basic grid. This is equal to (getUCount()-1)*(getVCount()-1). It is also the same as getPatchCount()*subPatchesPerPatch*subPatchesPerPatch

getPatchCountInGrid

public int getPatchCountInGrid()

Gets the total number of (major) patches in the basic grid. This is equal to getUPatchCount()*getVPatchCount()

getSubPatchCountInSurface

public int getSubPatchCountInSurface()

Gets the total number of subpatches in the surface, which might consist of several copies of the baic grid. This is equal to the number of copies of the gird times (getUCount()-1)*(getVCount()-1).

getPatchCountInSurface

public int getPatchCountInSurface()

Gets the total number of (major) patches in the surface, which might consist of several copies of the baic grid. This is equal to the number of copies of the grid times getUPatchCount()*getVPatchCount()

getSubpatchesPerPatch

public int getSubpatchesPerPatch()

Gets the number of subpatches that lie along each edge of a (major) patch, as specified in the constructor.

getUCurveIncrement

public int getUCurveIncrement()

Gets the U increment value, which is used to decide which grid lines to draw.

See Also:

setUCurveIncrement(int)

setUCurveIncrement

public void setUCurveIncrement(int curveIncrement)

Sets the U increment value, which is used to decide which grid lines to draw. When drawing u grid lines, the n-th line is drawn only if n is a multiple of uIncrement (except that the final grid line is always drawn). A value of zero indicates that no u grid lines are to be drawn, except that when both uIncrement and vIncrement are zero and a wireframe rendering is being drawn, uIncrement and vIncrement are both forced equal to subPatchesPerPatch, since otherwise nothing would be drawn.

Parameters:

curveIncrement - the U increment value. Any value less than zero is changed to zero.

getVCurveIncrement

public int getVCurveIncrement()

Gets the V increment value, which is used to decide which grid lines to draw.

See Also:

setUCurveIncrement(int)

setVCurveIncrement

public void setVCurveIncrement(int curveIncrement)

Sets the V increment value, which is used to decide which grid lines to draw. When drawing v grid lines, the n-th line is drawn only if n is a multiple of uIncrement (except that the final grid line is always drawn). A value of zero indicates that no u grid lines are to be drawn, except that when both uIncrement and vIncrement are zero and a wireframe rendering is being drawn, uIncrement and vIncrement are both forced equal to subPatchesPerPatch, since otherwise nothing would be drawn.

Parameters:

curveIncrement - the V increment value. Any value less than zero is changed to zero.

setPatchColor

public void setPatchColor(int uIndex,
                          int vIndex,
                          java.awt.Color c)

Sets the intrinsic color of a subpatch. If the specified color is null, then the default color is used. If no color is ever set for a patch, then the default color is used. The color set by this method is used for both the front and back color of a patch.

Parameters:

uIndex - The u index of the subpatch, in the range 0 to getUCount()-2

vIndex - The v index of the subpatch, in the range 0 to getVCount()-2

c - The new color of the patch, or zero to use the default color.

See Also:

setDefaultPatchColor(Color)

getPatchColor

public java.awt.Color getPatchColor(int uIndex,
                                    int vIndex,
                                    boolean frontFace)

Gets the intrinsic color of a subpatch.

Parameters:

uIndex - The u index of the subpatch, in the range 0 to getUCount()-2

vIndex - The v index of the subpatch, in the range 0 to getVCount()-2

frontFace - Tells whether this is a front or back face

See Also:

setPatchColor(int, int, Color)

clearPatchColors

public void clearPatchColors()

Resets all individual patch colors, as set by setPatchColor(int, int, Color), to the default value.

setNormal

public void setNormal(int uIndex,
                      int vIndex,
                      Vector3D normalVector)

Set a normal vector at one of the vertices in the basic grid. The vector is not meant to be a unit vector.

Parameters:

uIndex - the u index of the vertex, in the range 0 to getUCount(), inclusive

vIndex - the v index of the vertex, in the range 0 to getVCount(), inclusive

normalVector - the vector at vertex at position (uIndex,vIndex). This can be null; in that case, an approximate normal vector is computed using vectors to neighboring points on the surface.

See Also:

getNormal(int, int), getUnitNormal(int, int)

getNormal

public Vector3D getNormal(int uIndex,
                          int vIndex)

Returns a normal vector (not assumed to be a unit vector) at a specified vertex of the basic grid. If a non-null normal vector for this vertex was specified by setNormal(int, int, Vector3D), then that vector is returned. Otherwise, an approximate normal vector is computed vectors from the specified vertex to two neighboring vertices on the surface.

Parameters:

uIndex - the u index of the vertex, in the range 0 to getUCount(), inclusive

vIndex - the v index of the vertex, in the range 0 to getVCount(), inclusive

getUnitNormal

public Vector3D getUnitNormal(int uIndex,
                              int vIndex)

Returns a unit normal vector at a specified vertex in the basic grid. The return value is obtained by normalizing the return value of getNormal(int, int). However, if this yields an undefined result, a default value of (1,0,0) is returned.

Parameters:

uIndex - the u index of the vertex, in the range 0 to getUCount(), inclusive

vIndex - the v index of the vertex, in the range 0 to getVCount(), inclusive

clearNormals

public void clearNormals()

Removes all normal vectors that were set using setNormal(int, int, Vector3D).

setDefaultPatchColor

public void setDefaultPatchColor(java.awt.Color c)

Set the default color that is used as the intrinsic color of a patch for which no other color has been set. The default default patch color is white. The default color is used for any patch for which no color has been set with setPatchColor(int, int, Color).

Parameters:

c - the default patch color; if null, white is used as the default color

getDefaultPatchColor

public java.awt.Color getDefaultPatchColor()

Get the default patch color.

See Also:

setDefaultPatchColor(Color)

getDefaultBackColor

public java.awt.Color getDefaultBackColor()

Get the default color for the back face of a patch.

See Also:

setDefaultBackColor(Color)

setDefaultBackColor

public void setDefaultBackColor(java.awt.Color defaultBackColor)

Set the default color for the back face of a patch. This color is used only if no specific color has been set for the patch using the setPatchColor(int, int, Color) method.

Parameters:

defaultBackColor - The default backface color; if null, the back color is the same as the front color.

applyTransform

public void applyTransform(Transform3D transform,
                           View3D view3D)

Applies a transform the all vertices of the surface, to produce a set of transformed vertices. It must be called before the drawing routines in this class are called. This method, like the drawing routines in this class, is called by the surface drawing routines in the View3D and View3DLit classes -- most programmers will use those routines to draw the surface and will not have to call this routine directly.

Parameters:

view3D - used for clipping

drawCurves

public void drawCurves(View3D view,
                       java.awt.Graphics2D g)

Draws a wireframe rendering of the surface by drawing some or all of the grid lines in the U and V directions. The choice of which lines to draw is determined by the uCurveIncrement and vCurveIncrement properties. This method is called by the drawing routines in the View3D and View3DLit classes, and will not generally be called directly. This must be called after applyTransform(Transform3D, View3D) has been called.

See Also:

setUCurveIncrement(int), setVCurveIncrement(int)

drawSubPatches

public void drawSubPatches(View3DLit view,
                           java.awt.Graphics2D g,
                           double startPercent,
                           double endPercent)

Draws some or all of the subpatches that make up the surface as shaded, lighted color patches. This method is called by View3DLit.drawSurface(Grid3D, double, double) and will probably not be used directly. If it is, it is essential that applyTransform(Transform3D, View3D) be called before this method is called. The startPercent and endPercent are in the range 0 to 1, and they specify the subset of patches that are to be drawn. Lighting settings from the View3DLit are applied to the patches that are drawn. This method must be called after applyTransform(Transform3D, View3D).

drawMajorPatches

public void drawMajorPatches(View3DLit view,
                             java.awt.Graphics2D g)

Draws a "rough" version of the surface by drawing the (major) patches rather than the subpatches. The drawing uses flat shading; other than that, lighting settings are taken from the View3DLit. This method is called by View3DLit.drawSurface(Grid3D, double, double) and will probably not be used directly. If it is, it is essential that applyTransform(Transform3D, View3D) be called before this method is called.