javax.microedition.m3d
Class VertexBuffer

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.VertexBuffer

public class VertexBuffer

extends Object3D

VertexBuffer holds references to VertexArrays that contain the positions, colors, normals, and texture coordinates for a set of vertices. The elements of these arrays are called vertex attributes in the rest of this documentation. The structure of a VertexBuffer object is shown in the figure below.

There can be at most one position array, one color array, and one normal array in a VertexBuffer. The number of texture coordinate arrays, however, can be anything between zero and the number of texturing units supported by the implementation, which can be queried with Graphics3D.getProperties().

All vertex attribute arrays must be the same length; this is enforced by the set methods. The first array that is added to a previously empty VertexBuffer can have any number of elements. This is also the case if the sole previously set array is replaced with another. Any subsequently added arrays must have the same length as the first.

Vertex positions, texture coordinates, and normals are interpreted as homogeneous (4D) coordinates, where the fourth component is implicitly 1 for positions and texcoords, and 0 for normals. In other words, positions and texcoords are interpreted as 3D points, whereas normals are treated as 3D vectors. In the case of 2D texcoords, the third component is implicitly zero.

3D texture coordinates are supported, even though 3D texture maps are not. This allows some clever rendering tricks, such as cheap environment mapping by using normal vectors as texture coordinates.

Deferred exceptions

All vertex attribute arrays are initialized to null. The application can also set them to null at any time. This is a completely legal state, as long as the VertexBuffer is not rendered, either by itself or as part of a World, Group, or Mesh. Upon rendering, null attributes are treated as follows:

• If the position array is null, an exception is thrown.
• If the normal array is null, and lighting is enabled, an exception is thrown.
• If a texcoord array is null, and the corresponding texturing unit is enabled, an exception is thrown.
• If the color array is null, the default color is used instead.

The treatment of null values when picking is otherwise the same, except that the normal array is not checked.

Lighting can be disabled for a submesh by setting a null Material in Appearance. Similarly, a particular texturing unit can be turned off by setting its Texture2D to null.

See Also:

Binary format

Field Summary

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

VertexBuffer()
Constructs an empty vertex buffer, with all vertex attributes set to null.

Method Summary

VertexArray	getColors() Gets the current color array, or null if per-vertex colors are not set.
int	getDefaultColor() Retrieves the default color of this VertexBuffer.
VertexArray	getNormals() Gets the current normal vector array, or null if normals are not set.
VertexArray	getPositions(float[] scaleBias) Gets the current vertex position array, or null if positions are not set.
VertexArray	getTexCoords(int index, float[] scaleBias) Gets the current texture coordinate array for the specified texturing unit, or null if texture coordinates for that unit are not set.
int	getVertexCount() Retrieves the current number of vertices in this VertexBuffer.
void	setColors(VertexArray colors) Sets the per-vertex colors for this VertexBuffer.
void	setDefaultColor(int ARGB) Sets the color to use in absence of per-vertex colors.
void	setNormals(VertexArray normals) Sets the normal vectors for this VertexBuffer.
void	setPositions(VertexArray positions, float scale, float[] bias) Sets the vertex positions for this VertexBuffer.
void	setTexCoords(int index, VertexArray texCoords, float scale, float[] bias) Sets the texture coordinates for the specified texturing unit.

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

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

Constructor Detail

VertexBuffer

public VertexBuffer()

Constructs an empty vertex buffer, with all vertex attributes set to null. The default vertex color is initialized to 0xFFFFFFFF (opaque white). See the class description for information on how to fill in the attributes and what is the interpretation of null attributes.

Method Detail

getVertexCount

public int getVertexCount()

Retrieves the current number of vertices in this VertexBuffer. This is the same as the number of vertices in any of the associated VertexArrays, because they must all have the same length. If there are no VertexArrays currently in this VertexBuffer, the number of vertices is defined to be zero.

Returns:

the number of vertices currently in this VertexBuffer, or zero if no vertex arrays are set

setPositions

public void setPositions(VertexArray positions,
                         float scale,
                         float[] bias)

Sets the vertex positions for this VertexBuffer. Vertex positions are specified with a 3-component VertexArray. The components are interpreted as coordinates in (X, Y, Z) order, each component being a signed 8-bit or 16-bit integer. Vertex positions have associated with them a uniform scale and a per-component bias, which are common to all vertices in the VertexArray. The final position v' of a vertex is computed from the original position v as follows:

 v' = s × v + b

where s is the the uniform scale and b is the bias vector. For example, the application can map the 8-bit integers [-128, 127] to the real number range [-1,1] by setting the scale to 2/255 and the bias to 1/255.

Non-uniform scaling is not supported due to implementation constraints. A uniform scale factor introduces no per-vertex processing overhead, as implementations may combine the scale with the transformation from object space to world space or camera space. Combining a non-uniform scale with that transformation, in contrast, would distort the normal vectors and thereby cause undesirable side effects in lighting.

Parameters:

positions - a VertexArray with 3-component vertex positions, or null to disable vertex positions

scale - a constant uniform scale factor common to all vertex positions

bias - a constant (X, Y, Z) offset to add to vertex positions after scaling, or null to set a zero bias for all components

Throws:

java.lang.IllegalArgumentException - if positions.componentSize != [1,2]

java.lang.IllegalArgumentException - if positions.numComponents != 3

java.lang.IllegalArgumentException - if (positions.numVertices != getVertexCount) && (getVertexCount > 0)

java.lang.IllegalArgumentException - if bias.length < 3

See Also:

getPositions(float[])

setTexCoords

public void setTexCoords(int index,
                         VertexArray texCoords,
                         float scale,
                         float[] bias)

Sets the texture coordinates for the specified texturing unit. Texture coordinates are specified with a 2- or 3-component VertexArray. The components are interpreted in (S, T) or (S, T, R) order, each component being a signed 8-bit or 16-bit integer. Texture coordinates have associated with them a uniform scale and a per-component bias, which behave exactly the same way as with vertex positions (see setPositions). Non-uniform scaling is not supported, so as to make texture coordinates behave consistently with vertex positions.

Parameters:

index - index of the texturing unit to assign these texture coordinates to

texCoords - a VertexArray with 2- or 3-component texture coordinates, or null to disable texture coordinates for the specified unit

scale - a constant uniform scale factor common to all texture coordinates

bias - a constant (X, Y, Z) offset to add to texture coordinates after scaling, or null to set a zero bias for all components

Throws:

java.lang.IllegalArgumentException - if texCoords.componentSize != [1,2]

java.lang.IllegalArgumentException - if texCoords.numComponents != [2,3]

java.lang.IllegalArgumentException - if (texCoords.numVertices != getVertexCount) && (getVertexCount > 0)

java.lang.IllegalArgumentException - if bias.length < texCoords.numComponents

java.lang.IndexOutOfBoundsException - if index != [0,N] where N is the implementation specific maximum texture unit index

See Also:

getTexCoords(int, float[])

setNormals

public void setNormals(VertexArray normals)

Sets the normal vectors for this VertexBuffer. The scale and bias terms are not specified for normals. Instead, the components of the normals are mapped to [-1,1] such that the maximum positive integer maps to +1, the maximum negative integer to -1, and the mapping is linear in between. This is equivalent to having a scale of 2/255 and a bias of 1/255 for all components. Note that the number zero, for instance, cannot be represented accurately with this scheme.

Parameters:

normals - a VertexArray with 3-component normal vectors, or null to disable normals

Throws:

java.lang.IllegalArgumentException - if normals.componentSize != [1,2]

java.lang.IllegalArgumentException - if normals.numComponents != 3

java.lang.IllegalArgumentException - if (normals.numVertices != getVertexCount) && (getVertexCount > 0)

See Also:

getNormals()

setColors

public void setColors(VertexArray colors)

Sets the per-vertex colors for this VertexBuffer. The given VertexArray containing the color values must have either 3 (RGB) or 4 (RGBA) components per element, and the component size must be 8 bits. With RGB colors, the alpha component is implicitly set to 1 for all vertices.

The scale and bias terms are not specified for colors. Instead, color components are interpreted as unsigned integers between [0, 255], where 255 represents the maximum brightness (1.0). This is equivalent to having a scale of 1/255 and a bias of 128/255 for all components (the bias is needed because bytes are interpreted as signed by default).

Parameters:

colors - a VertexArray with RGB or RGBA color values, or null to use the default color instead

Throws:

java.lang.IllegalArgumentException - if colors.componentSize != 1

java.lang.IllegalArgumentException - if colors.numComponents != [3,4]

java.lang.IllegalArgumentException - if (colors.numVertices != getVertexCount) && (getVertexCount > 0)

See Also:

getColors()

getPositions

public VertexArray getPositions(float[] scaleBias)

Gets the current vertex position array, or null if positions are not set. The current scale and bias values are copied into the given array. The first four elements of the array are overwritten with the scale and bias, in that order. Any other elements in the array are left untouched. If the given array is null, only the VertexArray is returned.

Parameters:

scaleBias - a float array to populate with the current scale (1 entry) and bias (3 entries), or null to just return the vertex position array

Returns:

the current VertexArray for vertex positions, or null

Throws:

java.lang.IllegalArgumentException - if scaleBias.length < 4

See Also:

setPositions(javax.microedition.m3d.VertexArray, float, float[])

getTexCoords

public VertexArray getTexCoords(int index,
                                float[] scaleBias)

Gets the current texture coordinate array for the specified texturing unit, or null if texture coordinates for that unit are not set. The current scale and bias values are copied into the given array. The first 3 or 4 elements of the array are overwritten with the scale and bias, in that order. Any other elements in the array are left untouched. The number of elements written is equal to the number of components in the returned VertexArray, plus one for the scale. If the given array is null, only the VertexArray is returned.

Parameters:

index - index of the texturing unit to get the texture coordinates of

scaleBias - a float array to populate with the current scale (1 entry) and bias (2 or 3 entries), or null to just return the texcoord array

Returns:

VertexArray with the texture coordinates for the given texturing unit, or null

Throws:

java.lang.IllegalArgumentException - if scaleBias.length < numComponents+1

java.lang.IndexOutOfBoundsException - if index != [0,N] where N is the implementation specific maximum texture unit index

See Also:

setTexCoords(int, javax.microedition.m3d.VertexArray, float, float[])

getNormals

public VertexArray getNormals()

Gets the current normal vector array, or null if normals are not set.

Returns:

the current VertexArray for vertex normals, or null

See Also:

setNormals(javax.microedition.m3d.VertexArray)

getColors

public VertexArray getColors()

Gets the current color array, or null if per-vertex colors are not set.

Returns:

the current VertexArray for vertex colors, or null

See Also:

setColors(javax.microedition.m3d.VertexArray)

setDefaultColor

public void setDefaultColor(int ARGB)

Sets the color to use in absence of per-vertex colors. This color will be assigned to each vertex by default. If per-vertex colors are specified, this color is ignored.

Parameters:

ARGB - the default vertex color in 0xAARRGGBB format

See Also:

getDefaultColor()

getDefaultColor

public int getDefaultColor()

Retrieves the default color of this VertexBuffer.

Returns:

the default vertex color in 0xAARRGGBB format

See Also:

setDefaultColor(int)