Java Doc for GeometryArray.java in  » 6.0-JDK-Modules » java-3d » javax » media » j3d » Java Source Code / Java DocumentationJava Source Code and Java Documentation

• By Copying: The existing methods for setting positional coordinates, colors, normals, texture coordinates, and vertex attributes (such as setCoordinate, setColors, etc.) copy the data into this GeometryArray. This is appropriate for many applications and offers an application much flexibility in organizing its data. This is the default mode.
• By Reference: A new set of methods in Java 3D version 1.2 allows data to be accessed by reference, directly from the user's arrays. To use this feature, set the BY_REFERENCE bit in the vertexFormat field of the constructor for this GeometryArray. In this mode, the various set methods for coordinates, normals, colors, texture coordinates, and vertex attributes are not used. Instead, new methods are used to set a reference to user-supplied coordinate, color, normal, texture coordinate, and vertex attribute arrays (such as setCoordRefFloat, setColorRefFloat, etc.). Data in any array that is referenced by a live or compiled GeometryArray object may only be modified via the updateData method (subject to the ALLOW_REF_DATA_WRITE capability bit). Applications must exercise care not to violate this rule. If any referenced geometry data is modified outside of the updateData method, the results are undefined.

All colors used in the geometry array object must be in the range [0.0,1.0]. Values outside this range will cause undefined results. All normals used in the geometry array object must be unit length vectors. That is their geometric length must be 1.0. Normals that are not unit length vectors will cause undefined results.

Note that the term coordinate, as used in the method names and method descriptions, actually refers to a set of x, y, and z coordinates representing the position of a single vertex. The term coordinates (plural) is used to indicate sets of x, y, and z coordinates for multiple vertices. This is somewhat at odds with the mathematical definition of a coordinate, but is used as a convenient shorthand. Similarly, the term texture coordinate is used to indicate a set of texture coordinates for a single vertex, while the term texture coordinates (plural) is used to indicate sets of texture coordinates for multiple vertices.

Parameters:
  vertexFormat - a mask indicating which components arepresent in each vertex.

texCoordSetCount : 1
texCoordSetMap : { 0 }
vertexAttrCount : 0
vertexAttrSizes : null
validVertexCount : vertexCount
initialVertexIndex : 0
initialCoordIndex : 0
initialColorIndex : 0
initialNormalIndex : 0
initialTexCoordIndex : 0
initialVertexAttrIndex : 0
all data array values : 0.0
all data array references : null

exception:
  IllegalArgumentException - if vertexCount < 0
exception:
  IllegalArgumentException - if vertexFormat does notinclude COORDINATES
exception:
  IllegalArgumentException - if the USE_COORD_INDEX_ONLYbit or the BY_REFERENCE_INDICES bit is set for non-indexed geometry arrays (that is, GeometryArray objectsthat are not a subclass of IndexedGeometryArray)
exception:
  IllegalArgumentException - if the INTERLEAVEDbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the USE_NIO_BUFFERbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the INTERLEAVEDbit and the VERTEX_ATTRIBUTES bit are both set
exception:
  IllegalArgumentException - if the BY_REFERENCE_INDICESbit is set without the BY_REFERENCE and USE_COORD_INDEX_ONLY bits being set

Parameters:
  vertexFormat - a mask indicating which components arepresent in each vertex. This is specified as one or moreindividual flags that are bitwise "OR"ed together to describethe per-vertex data.The flags include: COORDINATES, to signal the inclusion ofvertex positions--always present; NORMALS, to signalthe inclusion of per vertex normals; one of COLOR_3 orCOLOR_4, to signal the inclusion of per vertexcolors (without or with alpha information); one ofTEXTURE_COORDINATE_2 or TEXTURE_COORDINATE_3or TEXTURE_COORDINATE_4,to signal theinclusion of per-vertex texture coordinates (2D , 3D or 4D);BY_REFERENCE, to indicate that the data is passedby referencerather than by copying; INTERLEAVED, to indicatethat the referenceddata is interleaved in a single array;USE_NIO_BUFFER, to indicate that the referenced datais accessed via a J3DBuffer object that wraps an NIO buffer;USE_COORD_INDEX_ONLY,to indicate that only the coordinate indices are used for indexedgeometry arrays;BY_REFERENCE_INDICES, to indicatethat the indices are accessed by reference in indexedgeometry arrays.

Parameters:
  texCoordSetCount - the number of texture coordinate setsin this GeometryArray object. If vertexFormatdoes not include one of TEXTURE_COORDINATE_2 orTEXTURE_COORDINATE_3, thetexCoordSetCount parameter is not used.

Parameters:
  texCoordSetMap - an array that maps texture coordinatesets to texture units. The array is indexed by texture unitnumber for each texture unit in the associated Appearanceobject. The values in the array specify the texture coordinateset within this GeometryArray object that maps to thecorresponding textureunit. All elements within the array must be less thantexCoordSetCount. A negative value specifies thatno texture coordinate set maps to the texture unitcorresponding to the index. If there are more texture units inany associated Appearance object than elements in the mappingarray, the extra elements are assumed to be -1. The sametexture coordinate set may be used for more than one textureunit. Each texture unit in every associated Appearance musthave a valid source of texture coordinates: either anon-negative texture coordinate set must be specified in themapping array or texture coordinate generation must be enabled.Texture coordinate generation will take precedence for thosetexture units for which a texture coordinate set is specifiedand texture coordinate generation is enabled. IfvertexFormat does not include one ofTEXTURE_COORDINATE_2 orTEXTURE_COORDINATE_3 orTEXTURE_COORDINATE_4, thetexCoordSetMap array is not used. The following exampleillustrates the use of the texCoordSetMap array.

Index	Element	Description
0	1	Use tex coord set 1 for tex unit 0
1	-1	Use no tex coord set for tex unit 1
2	0	Use tex coord set 0 for tex unit 2
3	1	Reuse tex coord set 1 for tex unit 3

exception:
  IllegalArgumentException - if vertexCount < 0
exception:
  IllegalArgumentException - if vertexFormat does notinclude COORDINATES
exception:
  IllegalArgumentException - if the USE_COORD_INDEX_ONLYbit or the BY_REFERENCE_INDICES bit is set for non-indexed geometry arrays (that is, GeometryArray objectsthat are not a subclass of IndexedGeometryArray)
exception:
  IllegalArgumentException - if the INTERLEAVEDbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the USE_NIO_BUFFERbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the INTERLEAVEDbit and the VERTEX_ATTRIBUTES bit are both set
exception:
  IllegalArgumentException - if the BY_REFERENCE_INDICESbit is set without the BY_REFERENCE and USE_COORD_INDEX_ONLY bits being set
exception:
  IllegalArgumentException - iftexCoordSetCount < 0
exception:
  IllegalArgumentException - if any element intexCoordSetMap[] >= texCoordSetCount.
since:
   Java 3D 1.2

Parameters:
  vertexFormat - a mask indicating which components arepresent in each vertex. This is specified as one or moreindividual flags that are bitwise "OR"ed together to describethe per-vertex data.The flags include: COORDINATES, to signal the inclusion ofvertex positions--always present; NORMALS, to signalthe inclusion of per vertex normals; one of COLOR_3 orCOLOR_4, to signal the inclusion of per vertexcolors (without or with alpha information); one ofTEXTURE_COORDINATE_2 or TEXTURE_COORDINATE_3or TEXTURE_COORDINATE_4,to signal theinclusion of per-vertex texture coordinates (2D , 3D or 4D);VERTEX_ATTRIBUTES, to signalthe inclusion of one or more arrays of vertex attributes;BY_REFERENCE, to indicate that the data is passedby referencerather than by copying; INTERLEAVED, to indicatethat the referenceddata is interleaved in a single array;USE_NIO_BUFFER, to indicate that the referenced datais accessed via a J3DBuffer object that wraps an NIO buffer;USE_COORD_INDEX_ONLY,to indicate that only the coordinate indices are used for indexedgeometry arrays;BY_REFERENCE_INDICES, to indicatethat the indices are accessed by reference in indexedgeometry arrays.

Parameters:
  texCoordSetCount - the number of texture coordinate setsin this GeometryArray object. If vertexFormatdoes not include one of TEXTURE_COORDINATE_2 orTEXTURE_COORDINATE_3, thetexCoordSetCount parameter is not used.

Parameters:
  texCoordSetMap - an array that maps texture coordinatesets to texture units. The array is indexed by texture unitnumber for each texture unit in the associated Appearanceobject. The values in the array specify the texture coordinateset within this GeometryArray object that maps to thecorresponding textureunit. All elements within the array must be less thantexCoordSetCount. A negative value specifies thatno texture coordinate set maps to the texture unitcorresponding to the index. If there are more texture units inany associated Appearance object than elements in the mappingarray, the extra elements are assumed to be -1. The sametexture coordinate set may be used for more than one textureunit. Each texture unit in every associated Appearance musthave a valid source of texture coordinates: either anon-negative texture coordinate set must be specified in themapping array or texture coordinate generation must be enabled.Texture coordinate generation will take precedence for thosetexture units for which a texture coordinate set is specifiedand texture coordinate generation is enabled. IfvertexFormat does not include one ofTEXTURE_COORDINATE_2 orTEXTURE_COORDINATE_3 orTEXTURE_COORDINATE_4, thetexCoordSetMap array is not used. The following exampleillustrates the use of the texCoordSetMap array.

Index	Element	Description
0	1	Use tex coord set 1 for tex unit 0
1	-1	Use no tex coord set for tex unit 1
2	0	Use tex coord set 0 for tex unit 2
3	1	Reuse tex coord set 1 for tex unit 3

Parameters:
  vertexAttrCount - the number of vertex attributesin this GeometryArray object. If vertexFormatdoes not include VERTEX_ATTRIBUTES, thevertexAttrCount parameter must be 0.

Parameters:
  vertexAttrSizes - is an array that specifes the size ofeach vertex attribute. Each element in the array specifies thenumber of components in the attribute, from 1 to 4. The lengthof the array must be equal to vertexAttrCount.

exception:
  IllegalArgumentException - if vertexCount < 0
exception:
  IllegalArgumentException - if vertexFormat does notinclude COORDINATES
exception:
  IllegalArgumentException - if the USE_COORD_INDEX_ONLYbit or the BY_REFERENCE_INDICES bit is set for non-indexed geometry arrays (that is, GeometryArray objectsthat are not a subclass of IndexedGeometryArray)
exception:
  IllegalArgumentException - if the INTERLEAVEDbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the USE_NIO_BUFFERbit is set without the BY_REFERENCE bit being set
exception:
  IllegalArgumentException - if the INTERLEAVEDbit and the VERTEX_ATTRIBUTES bit are both set
exception:
  IllegalArgumentException - if the BY_REFERENCE_INDICESbit is set without the BY_REFERENCE and USE_COORD_INDEX_ONLY bits being set
exception:
  IllegalArgumentException - iftexCoordSetCount < 0
exception:
  IllegalArgumentException - if any element intexCoordSetMap[] >= texCoordSetCount.
exception:
  IllegalArgumentException - ifvertexAttrCount > 0 and theVERTEX_ATTRIBUTES bit is not set
exception:
  IllegalArgumentException - ifvertexAttrCount < 0
exception:
  IllegalArgumentException - ifvertexAttrSizes.length != vertexAttrCount
exception:
  IllegalArgumentException - if any element invertexAttrSizes[] is < 1 or> 4.
since:
   Java 3D 1.4