javax.microedition.m3g
Class VertexBuffer

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.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 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 or tested for intersection with a pick ray. When rendering, null vertex 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, the normal vectors are undefined.
• If a texcoord array is null, and the corresponding texturing unit is enabled, the texture coordinates are undefined.
• If the color array is null, the default color is used instead.

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.

When picking, null vertex attributes are treated as follows:

• If the position array is null, an exception is thrown.
• If the normal array is null, the returned normal is undefined.
• If a texcoord array is null, the returned texcoords are undefined.

The color array and the default color are ignored when picking.

See Also:

Binary format

Constructor Summary

VertexBuffer()
Creates an empty VertexBuffer with default values.

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) Returns 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.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Constructor Detail

VertexBuffer

public VertexBuffer()

Creates an empty VertexBuffer with default values. The default values are:

• vertex count : 0
• vertex position array : null
• texture coordinate array(s) : null
• normal array : null
• color array : null (use default color)
• default color : 0xFFFFFFFF (opaque white)

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 != null) && (positions.getComponentCount != 3)

java.lang.IllegalArgumentException - if (positions != null) && (positions.getVertexCount != getVertexCount) && (at least one other VertexArray is set)

java.lang.IllegalArgumentException - if (positions != null) && (bias != null) && (bias.length < 3)

See Also:

getPositions

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 != null) && (texCoords.getComponentCount != {2,3})

java.lang.IllegalArgumentException - if (texCoords != null) && (texCoords.getVertexCount != getVertexCount) && (at least one other VertexArray is set)

java.lang.IllegalArgumentException - if (texCoords != null) && (bias != null) && (bias.length < texCoords.getComponentCount)

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

See Also:

getTexCoords

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. Note that the number zero, for instance, cannot be represented accurately with this scheme.

The normal vectors need not be unit length on input; they are automatically normalized prior to using them in the lighting computations. This implicit normalization does not modify the original values in the VertexArray.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if (normals != null) && (normals.getComponentCount != 3)

java.lang.IllegalArgumentException - if (normals != null) && (normals.getVertexCount != getVertexCount) && (at least one other VertexArray is set)

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 in Java are always interpreted as signed values).

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if (colors != null) && (colors.getComponentType != 1)

java.lang.IllegalArgumentException - if (colors != null) && (colors.getComponentCount != {3,4})

java.lang.IllegalArgumentException - if (colors != null) && (colors.getVertexCount != getVertexCount) && (at least one other VertexArray is set)

See Also:

getColors

getPositions

public VertexArray getPositions(float[] scaleBias)

Returns the current vertex position array, or null if positions are not set. The current scale and bias values are copied into the given array. If positions are not set, the scale and bias values are undefined. 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 VertexArray

Returns:

the current VertexArray for vertex positions, or null

Throws:

java.lang.IllegalArgumentException - if (scaleBias != null) && (scaleBias.length < 4)

See Also:

setPositions

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. If the texture coordinate array is null, the scale and bias values are undefined. 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 VertexArray

Returns:

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

Throws:

java.lang.IllegalArgumentException - if (scaleBias != null) && (scaleBias.length < texCoords.getComponentCount+1)

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

See Also:

setTexCoords

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

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

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