The Java 3D API Specification |
C H A P T E R8 |
Node Component Objects |
8.1
Node objects by themselves do not fully specify their exact semantics. They contain information that further refines their exact meaning. Some of that information is specified as an attribute and an associated floating-point or integer value. In many cases, however, the information consists of references to more complex entities called node component objects. Node component objects encapsulate related state information in a single entity. See Figure 8-1.Node Component Objects: Attributes
8.1.1
The Alpha node component object provides common methods for converting a time value into an alpha value (a value in the range 0.0 to 1.0). See Section 10.6, "Interpolator Behaviors," for a description of the Alpha object.Alpha Object
8.1.2
The Appearance object is a component object of a Shape3D node that defines all rendering state attributes for that shape node. If the Appearance object in a Shape3D node isAppearance Object null
, default values will be used for all rendering state attributes.
Constants
The Appearance component object defines the following flags:
Figure 8-1 Attribute Component Object Hierarchy
public static final int ALLOW_MATERIAL_READ public static final int ALLOW_MATERIAL_WRITE public static final int ALLOW_TEXTURE_READ public static final int ALLOW_TEXTURE_WRITE public static final int ALLOW_TEXGEN_READ public static final int ALLOW_TEXGEN_WRITE public static final int ALLOW_TEXTURE_ATTRIBUTES_READ public static final int ALLOW_TEXTURE_ATTRIBUTES_WRITE public static final int ALLOW_COLORING_ATTRIBUTES_READ public static final int ALLOW_COLORING_ATTRIBUTES_WRITE public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_READ public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE public static final int ALLOW_RENDERING_ATTRIBUTES_READ public static final int ALLOW_RENDERING_ATTRIBUTES_WRITE public static final int ALLOW_POLYGON_ATTRIBUTES_READ public static final int ALLOW_POLYGON_ATTRIBUTES_WRITE public static final int ALLOW_LINE_ATTRIBUTES_READ public static final int ALLOW_LINE_ATTRIBUTES_WRITE public static final int ALLOW_POINT_ATTRIBUTES_READ public static final int ALLOW_POINT_ATTRIBUTES_WRITE public static final int ALLOW_TEXTURE_UNIT_STATE_READ public static final int ALLOW_TEXTURE_UNIT_STATE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read and write the specified component object reference (material, texture, texture coordinate generation, and so forth). These capability flags are enforced only when the object is part of a live or compiled scene graph.
Constructors
The Appearance object has the following constructor:public Appearance()Constructs and initializes an Appearance object using defaults for all state variables. All component object references are initialized to null.
Methods
The Appearance object has the following methods:public void setMaterial(Material material) public Material getMaterial()The Material object specifies the desired material properties used for lighting. Setting it tonull
disables lighting.public void setTexture(Texture texture) public Texture getTexture()The Texture object specifies the desired texture map and texture parameters. Setting it tonull
disables texture mapping. Applications must not set individual texture component objects (texture, textureAttributes, or texCoordGeneration) and the texture unit state array in the same Appearance object. Doing so will result in an exception being thrown.public void setTextureAttributes(TextureAttributes textureAttributes) public TextureAttributes getTextureAttributes()These methods set and retrieve the TextureAttributes object. Setting it tonull
results in default attribute use. Applications must not set individual texture component objects (texture, textureAttributes, or texCoordGeneration) and the texture unit state array in the same Appearance object. Doing so will result in an exception being thrown.public void setColoringAttributes(ColoringAttributes coloringAttributes) public ColoringAttributes getColoringAttributes()These methods set and retrieve the ColoringAttributes object. Setting it tonull
results in default attribute use.public void setTransparencyAttributes( TransparencyAttributes transparencyAttributes) public TransparencyAttributes getTransparencyAttributes()These methods set and retrieve the TransparencyAttributes object. Setting it tonull
results in default attribute use.public void setRenderingAttributes(RenderingAttributes renderingAttributes) public RenderingAttributes getRenderingAttributes()These methods set and retrieve the RenderingAttributes object. Setting it tonull
results in default attribute use.public void setPolygonAttributes(PolygonAttributes polygonAttributes) public PolygonAttributes getPolygonAttributes()These methods set and retrieve the PolygonAttributes object. Setting it tonull
results in default attribute use.public void setLineAttributes(LineAttributes lineAttributes) public LineAttributes getLineAttributes()These methods set and retrieve the LineAttributes object. Setting it tonull
results in default attribute use.public void setPointAttributes(PointAttributes pointAttributes) public PointAttributes getPointAttributes()These methods set and retrieve the PointAttributes object. Setting it tonull
results in default attribute use.public void setTexCoordGeneration(TexCoordGeneration texCoordGeneration) public TexCoordGeneration getTexCoordGeneration()These methods set and retrieve the TexCoordGeneration object. Setting it tonull
disables texture coordinate generation.public void setTextureUnitState(TextureUnitState[] stateArray) public void setTextureUnitState(int index, TextureUnitState state) public TextureUnitState[] getTextureUnitState() public TextureUnitState getTextureUnitState(int index)These methods set and retrieve the texture-unit state for this Appearance object (see Section 8.1.15, "TextureUnitState Object"). The first method sets the texture unit state array to the specified array. A shallow copy of the array of references to the TextureUnitState objects is made. If the specified array is null or if the length of the array is 0, multitexture is disabled. Within the array, a null TextureUnitState element disables the corresponding texture unit. The second method sets the texture unit state array object at the specified index within the texture unit state array to the specified object. If the specified object is null, the corresponding texture unit is disabled. The index must be within the range [0, stateArray.length-1]. Applications must not set individual texture component objects (texture, textureAttributes, or texCoordGeneration) and the texture unit state array in the same Appearance object. Doing so will result in an exception being thrown.public int getTextureUnitCount()This method retrieves the length of the texture unit state array from this Appearance object. The length of this array specifies the maximum number of texture units that will be used by this appearance object. If the array is null, a count of 0 is returned.
8.1.3
The ColoringAttributes object defines attributes that apply to color mapping.ColoringAttributes Object public static final int ALLOW_COLOR_READ public static final int ALLOW_COLOR_WRITE public static final int ALLOW_SHADE_MODEL_READ public static final int ALLOW_SHADE_MODEL_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write its color component and shade model component information.public ColoringAttributes()Constructs a ColoringAttributes node with default parameters:
Parameter Default Value color white (1,1,1) shadeModel SHADE_GOURAUD
public ColoringAttributes(Color3f color, int shadeModel) public ColoringAttributes(float red, float green, float blue, int shadeModel)These constructors create a ColoringAttributes object with the specified values.public void setColor(Color3f color) public void setColor(float r, float g, float b) public void getColor(Color3f color)These methods set and retrieve the intrinsic color of this ColoringAttributes component object. This color is used only for unlit geometry. If lighting is enabled, the material colors are used in the lighting equation to produce the final color. When vertex colors are present in unlit geometry, those vertex colors are used in place of this ColoringAttributes color unless the vertex colors are ignored.public void setShadeModel(int shadeModel) public int getShadeModel()These methods set and retrieve the shade model for this ColoringAttributes component object. The shade model is one of the following:
- FASTEST: Uses the fastest available method for shading.
- NICEST: Uses the nicest (highest quality) available method for shading.
- SHADE_FLAT: Does not interpolate color across the primitive.
- SHADE_GOURAUD: Smoothly interpolates the color at each vertex across the primitive.
8.1.4
The LineAttributes object defines attributes that apply to line primitives.LineAttributes Object
Constants
The LineAttributes object specifies the following variables:public static final int ALLOW_WIDTH_READ public static final int ALLOW_WIDTH_WRITE public static final int ALLOW_PATTERN_READ public static final int ALLOW_PATTERN_WRITE public static final int ALLOW_ANTIALIASING_READ public static final int ALLOW_ANTIALIASING_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read and write its individual component field information.public static final int PATTERN_SOLIDDraws a solid line with no pattern.public static final int PATTERN_DASHDraws a dashed line. Ideally, this will be drawn with a repeating pattern of eight pixels on and eight pixels off.public static final int PATTERN_DOTDraws a dotted line. Ideally, this will be drawn with a repeating pattern of one pixel on and seven pixels off.public static final int PATTERN_DASH_DOTDraws a dashed-dotted line. Ideally, this will be drawn with a repeating pattern of seven pixels on, four pixels off, one pixel on, and four pixels off.public static final int PATTERN_USER_DEFINEDDraws lines with a user-defined line pattern. The line pattern is specified with a pattern mask and a scale factor.public LineAttributes()Constructs a LineAttributes object with default parameters:
Parameter Default Value lineWidth 1 linePattern PATTERN_SOLID lineAntialiasing false
public LineAttributes(float lineWidth, int linePattern, boolean lineAntialiasing)Constructs a LineAttributes object with specified values of line width, pattern, and whether antialiasing is enabled or disabled.public void setLineWidth(float lineWidth) public float getLineWidth()These methods respectively set and retrieve the line width, in pixels, for this Line-Attributes component object.public void setLinePattern(int linePattern) public int getLinePattern()These methods respectively set and retrieve the line pattern for this LineAttributes component object. ThelinePattern
value describes the line pattern to be used, which is one of the following:PATTERN_SOLID
,PATTERN_DASH
,PATTERN_DOT
, orPATTERN_DASH_DOT
.public void setLineAntialiasingEnable(boolean state) public boolean getLineAntialiasingEnable()Theset
method enables or disables line antialiasing for this LineAttributes component object. Theget
method retrieves the state of the line antialiasing flag. The flag istrue
if line antialiasing is enabled,false
if line antialiasing is disabled.public void setPatternMask(int mask) public int getPatternMask()These methods respectively set and retrieve the line pattern mask. The line pattern mask is used when the linePattern attribute is set toPATTERN_USER_DEFINED
.public void setPatternScaleFactor(int scaleFactor) public int getPatternScaleFactor()These methods respectively set and retrieve the line pattern scale factor. The line pattern scale factor is used in conjunction with the patternMask when the linePattern attribute is set toPATTERN_USER_DEFINED
. The pattern is multiplied by the scale factor such that each bit in the pattern mask corresponds to that many consecutive pixels. For example, a scale factor of 3 applied to a pattern mask of 0x001f would produce a repeating pattern of 15 pixels on followed by 33 pixels off. The valid range for this attribute is [1,15]. Values outside this range are clamped.
8.1.5
The PointAttributes object defines attributes that apply to point primitives.PointAttributes Object
Constants
The PointAttributes object specifies the following variables:public static final int ALLOW_SIZE_READ public static final int ALLOW_SIZE_WRITE public static final int ALLOW_ANTIALIASING_READ public static final int ALLOW_ANTIALIASING_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read and write its individual component field information.public PointAttributes()Constructs a PointAttributes object with default parameters:
Parameter Default Value pointSize 1 pointAntialiasingEnable false
public PointAttributes(float pointSize, boolean pointAntialiasing)Constructs a PointAttributes object with specified values.public void setPointSize(float pointSize) public float getPointSize()These methods set and retrieve the point size, in pixels, for this Appearance component object.public void setPointAntialiasingEnable(boolean state) public boolean getPointAntialiasingEnable()Theset
method enables or disables point antialiasing for this PointAttributes component object. Theget
method retrieves the state of the point antialiasing flag. The flag istrue
if point antialiasing is enabled;false
if point antialiasing is disabled.
8.1.6
The PolygonAttributes object defines attributes for rendering polygon primitives.PolygonAttributes Object
Constants
The PolygonAttributes object specifies the following variables:public static final int ALLOW_CULL_FACE_READ public static final int ALLOW_CULL_FACE_WRITE public static final int ALLOW_MODE_READ public static final int ALLOW_MODE_WRITE public static final int ALLOW_OFFSET_READ public static final int ALLOW_OFFSET_WRITE public static final int ALLOW_NORMAL_FLIP_READ public static final int ALLOW_NORMAL_FLIP_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read and write its individual component field information.public PolygonAttributes()Constructs a PolygonAttributes object with default parameters:
Parameter Default Value cullFace CULL_BACK backFaceNormalFlip false polygonMode POLYGON_FILL polygonOffset 0.0 polygonOffsetFactor 0.0
public PolygonAttributes(int polygonMode, int cullFace, float polygonOffset) public PolygonAttributes(int polygonMode, int cullFace, float polygonOffset, boolean backFaceNormalFlip) public PolygonAttributes(int polygonMode, int cullFace, float polygonOffset, boolean backFaceNormalFlip, float polygonOffsetFactor)These constructors create a new PolygonAttributes object with the specified values.public void setCullFace(int cullFace) public int getCullFace()These methods set and retrieve the face culling flag for this PolygonAttributes component object. The face culling flag is one of the following:
- CULL_NONE: Performs no face culling.
- CULL_FRONT: Culls all front-facing polygons.
- CULL_BACK: Culls all back-facing polygons.
public void setBackFaceNormalFlip(boolean backFaceNormalFlip) public boolean getBackFaceNormalFlip()These methods set and retrieve the back-face normal flip flag. This flag indicates whether vertex normals of back-facing polygons should be flipped (negated) prior to lighting. When this flag is set to true and back-face culling is disabled, polygons are rendered as if the polygon had two sides with opposing normals. This feature is disabled by default.public void setPolygonMode(int polygonMode) public int getPolygonMode()These methods set and retrieve the polygon rasterization mode for this Appearance component object. The polygon rasterization mode is one of the following:
- POLYGON_POINT: Renders polygonal primitives as points drawn at the vertices of the polygon.
- POLYGON_LINE: Renders polygonal primitives as lines drawn between consecutive vertices of the polygon.
- POLYGON_FILL: Renders polygonal primitives by filling the interior of the polygon.
public void setPolygonOffset(float polygonOffset) public float getPolygonOffset()These methods set and retrieve the constant polygon offset. This screen-space offset is added to the final, device coordinate z value of polygon primitives.public void setPolygonOffsetFactor(float polygonOffsetFactor) public float getPolygonOffsetFactor()These methods set and retrieve the polygon offset factor. This factor is multiplied by the slope of the polygon and then added to the final device coordinate z value of polygon primitives.
8.1.7
The RenderingAttributes object defines common rendering attributes for all primitive types.RenderingAttributes Object public static final int ALLOW_ALPHA_TEST_VALUE_READ public static final int ALLOW_ALPHA_TEST_VALUE_WRITE public static final int ALLOW_ALPHA_TEST_FUNCTION_READ public static final int ALLOW_ALPHA_TEST_FUNCTION_WRITE public static final int ALLOW_DEPTH_ENABLE_READ public static final int ALLOW_VISIBLE_READ public static final int ALLOW_VISIBLE_WRITE public static final int ALLOW_IGNORE_VERTEX_COLORS_READ public static final int ALLOW_IGNORE_VERTEX_COLORS_WRITE public static final int ALLOW_RASTER_OP_READ public static final int ALLOW_RASTER_OP_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write its individual test value and function information.public RenderingAttributes()Constructs a RenderingAttributes object with default parameters:
Parameter Default Value depthBufferEnable true depthBufferWriteEnable true alphaTestFunction ALWAYS alphaTestValue 0.0 visible true ignoreVertexColors false rasterOpEnable false rasterOp ROP_COPY
public RenderingAttributes(boolean depthBufferEnable, boolean depthBufferWriteEnable, float alphaTestValue, int alphaTestFunction) public RenderingAttributes(boolean depthBufferEnable, boolean depthBufferWriteEnable, float alphaTestValue, int alphaTestFunction, boolean visible, boolean ignoreVertexColors, boolean rasterOpEnable, int rasterOp)Constructs a RenderingAttributes object with specified values.public void setDepthBufferEnable(boolean state) public boolean getDepthBufferEnable()These methods set and retrieve the depth buffer enable flag for this RenderingAttributes component object. The flag istrue
if the depth buffer mode is enabled,false
if disabled.public void setDepthBufferWriteEnable(boolean state) public boolean getDepthBufferWriteEnable()These methods set and retrieve the depth buffer write enable flag for this RenderingAttributes component object. The flag istrue
if the depth buffer mode is writable,false
if the depth buffer is read-only.public void setAlphaTestValue(float value) public float getAlphaTestValue()These methods set and retrieve the alpha test value used by the alpha test function. This value is compared to the alpha value of each rendered pixel.public void setAlphaTestFunction(int function) public int getAlphaTestFunction()These methods set and retrieve the alpha test function. The alpha test function is one of the following:
- ALWAYS: Indicates pixels are always drawn irrespective of the alpha value. This effectively disables alpha testing.
- NEVER: Indicates pixels are never drawn irrespective of the alpha value.
- EQUAL: Indicates pixels are drawn if the pixel alpha value is equal to the alpha test value.
- NOT_EQUAL: Indicates pixels are drawn if the pixel alpha value is not equal to the alpha test value.
- LESS: Indicates pixels are drawn if the pixel alpha value is less than the alpha test value.
- LESS_OR_EQUAL: Indicates pixels are drawn if the pixel alpha value is less than or equal to the alpha test value.
- GREATER: Indicates pixels are drawn if the pixel alpha value is greater than the alpha test value.
- GREATER_OR_EQUAL: Indicates pixels are drawn if the pixel alpha value is greater than or equal to the alpha test value.
public void setVisible(boolean visible) public boolean getVisible()These methods set and retrieve the visibility flag for this RenderingAttributes component object. Invisible objects are not rendered (subject to the visibility policy for the current view), but they can be picked or collided with.public void setIgnoreVertexColors(boolean ignoreVertexColors) public boolean getIgnoreVertexColors()These methods set and retrieve the flag that indicates whether vertex colors are ignored for this RenderingAttributes object. IfignoreVertexColors
is false, per-vertex colors are used, when present in the associated Geometry objects, taking precedence over the ColoringAttributes color and Material diffuse color. IfignoreVertexColors
is true, per-vertex colors are ignored. In this case, if lighting is enabled, the Material diffuse color will be used as the object color. If lighting is disabled, the ColoringAttributes color will be used. The default value is false.public void setRasterOpEnable(boolean rasterOpEnable) public boolean getRasterOpEnable()These methods set and retrieve the rasterOp enable flag for this RenderingAttributes component object. When set to true, this enables logical raster operations as specified by thesetRasterOp
method. Enabling raster operations effectively disables alpha blending, which is used for transparency and antialiasing. Raster operations, especially XOR mode, are primarily useful when rendering to the front buffer in immediate mode. Most applications will not wish to enable this mode.public void setRasterOp(int rasterOp) public int getRasterOp()These methods set and retrieve the raster operation function for this Rendering-Attributes component object. The rasterOp is one of the following:
- ROP_COPY:
DST = SRC
- ROP_XOR:
DST = SRC ^ DST
8.1.8
The TextureAttributes object defines attributes that apply to texture mapping.TextureAttributes Object public static final int ALLOW_MODE_READ public static final int ALLOW_MODE_WRITE public static final int ALLOW_BLEND_COLOR_READ public static final int ALLOW_BLEND_COLOR_WRITE public static final int ALLOW_TRANSFORM_READ public static final int ALLOW_TRANSFORM_WRITE public static final int ALLOW_COLOR_TABLE_READ public static final int ALLOW_COLOR_TABLE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write its individual component field information.public TextureAttributes()Constructs a TextureAttributes object with default parameters:
Parameter Default Value textureMode REPLACE textureBlendColor black (0,0,0,0) transform identity perspectiveCorrectionMode NICEST textureColorTable null
public TextureAttributes(int textureMode, Transform3D transform, Color4f textureBlendColor, int perspCorrectionMode)These constructors create a new TextureAttributes object with the specified parameters.public void setTextureMode(int textureMode) public int getTextureMode()These methods set and retrieve the texture mode parameter for this Texture-Attributes component object. The texture mode is one of the following:
- MODULATE: Modulates the object color with the texture color.
- DECAL: Applies the texture color to the object as a decal.
- BLEND: Blends the texture blend color with the object color.
- REPLACE: Replaces the object color with the texture color.
public void setTextureBlendColor(Color4f textureBlendColor) public void setTextureBlendColor(float r, float g, float b, float a) public void getTextureBlendColor(Color4f textureBlendColor)These methods set and retrieve the texture blend color for this TextureAttributes component object. The texture blend color is used when the texture mode parameter isBLEND
.public void setTextureColorTable(int[][] table)This method sets the texture color table from the specified table. The individual integer array elements are copied. The array is indexed first by color component (r, g, b, and a, respectively) and then by color value;table.length
defines the number of color components, andtable[0].length
defines the texture color table size. If the table is non-null, the number of color components must be either three, for rgb data, or four, for rgba data. The size of each array for each color component must be the same and must be a power of 2. Iftable
is null or if the texture color table size is 0, the texture color table is disabled. If the texture color table size is greater than the device-dependent maximum texture color table size for a particular Canvas3D, the texture color table is ignored for that canvas.public void getTextureColorTable(int[][] table)This method retrieves the texture color table and copies it into the specified array. If the current texture color table is null, no values are copied. The array must be allocated by the caller and must be large enough to hold the entire table (that is,int[numTextureColorTableComponents][textureColorTableSize]
).public int getNumTextureColorTableComponents()This method retrieves the number of color components in the current texture color table. A value of 0 is returned if the texture color table is null.public int getTextureColorTableSize()This method retrieves the size of the current texture color table. A value of 0 is returned if the texture color table is null.public void setTextureTransform(Transform3D transform) public void getTextureTransform(Transform3D transform)These methods set and retrieve the texture transform object used to transform texture coordinates. A copy of the specified Transform3D object is stored in this TextureAttributes object.public void setPerspectiveCorrectionMode(int mode) public int getPerspectiveCorrectionMode()These methods set and retrieve the perspective correction mode to be used for color and texture coordinate interpolation. The perspective correction mode is one of the following:
- NICEST: Uses the nicest (highest quality) available method for texture mapping perspective correction.
- FASTEST: Uses the fastest available method for texture mapping perspective correction.
8.1.9
The TransparencyAttributes object defines all attributes affecting the transparency of the object.TransparencyAttributes Object public static final int ALLOW_MODE_READ public static final int ALLOW_MODE_WRITE public static final int ALLOW_VALUE_READ public static final int ALLOW_VALUE_WRITE public static final int ALLOW_BLEND_FUNCTION_READ public static final int ALLOW_BLEND_FUNCTION_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write its individual component field information.public TransparencyAttributes()Constructs a new TransparencyAttributes object with default values:
Parameter Default Value transparencyMode NONE transparencyValue 0.0 srcBlendFunction BLEND_SRC_ALPHA dstBlendFunction BLEND_ONE_MINUS_SRC_ALPHA
public TransparencyAttributes(int tMode, float tVal) public TransparencyAttributes(int tMode, float tVal, int srcBlendFunction, int dstBlendFunction)Constructs a new TransparencyAttributes object with specified values.public void setTransparencyMode(int transparencyMode) public int getTransparencyMode()These methods set and retrieve the transparency mode for this Appearance component object. The transparency mode is one of the following:
- FASTEST: Uses the fastest available method for transparency.
- NICEST: Uses the nicest available method for transparency.
- SCREEN_DOOR: Uses screen-door transparency. This is done using an on/off stipple pattern in which the percentage of transparent pixels is approximately equal to the value specified by the transparency parameter.
- BLENDED: Uses alpha blended transparency. The blend equation is specified by the
srcBlendFunction
anddstBlendFunction
attributes. The default equation is:alpha*src + (1-alpha)*dst
, wherealpha
is 1 -transparency
.
- NONE: No transparency; opaque object.
public void setTransparency(float transparency) public float getTransparency()These methods set and retrieve this Appearance object's transparency value. The transparency value is in the range [0.0, 1.0], with 0.0 being fully opaque and 1.0 being fully transparent.public void setSrcBlendFunction(int blendFunction) public int getSrcBlendFunction()These methods set and retrieve the source blend function used in blended transparency and antialiasing operations. The source function specifies the factor that is multiplied by the source color. This value is added to the product of the destination factor and the destination color. The default source blend function isBLEND_SRC_ALPHA
. The source blend function is one of the following:
- BLEND_ZERO: The blend function is
f = 0
.
- BLEND_ONE: The blend function is
f = 1
.
- BLEND_SRC_ALPHA: The blend function is
f = alpha
src.
- BLEND_ONE_MINUS_SRC_ALPHA: The blend function is
f = 1 - alpha
src.public void setDstBlendFunction(int blendFunction) public int getDstBlendFunction()These methods set and retrieve the destination blend function used in blended transparency and antialiasing operations. The destination function specifies the factor that is multiplied by the destination color. This value is added to the product of the source factor and the source color. The default destination blend function isBLEND_ONE_MINUS_SRC_ALPHA
.
8.1.10
The Material object is a component object of an Appearance object that defines the material properties used when lighting is enabled. If the Material object in an Appearance object isMaterial Object null
, lighting is disabled for all nodes that use that Appearance object.
Constants
The Material object defines two flags.public static final int ALLOW_COMPONENT_READ public static final int ALLOW_COMPONENT_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that respectively read and write its individual component field information.
Constructors
The Material object has the following constructors:public Material()Constructs and initializes a Material object using default values for all attributes. The default values are as follows:
Parameter Default Value lightingEnable true ambientColor (0.2, 0.2, 0.2) emissiveColor (0.0, 0.0, 0.0) diffuseColor (1.0, 1.0, 1.0) specularColor (1.0, 1.0, 1.0) shininess 64
public Material(Color3f ambientColor, Color3f emissiveColor, Color3f diffuseColor, Color3f specularColor, float shininess)Constructs and initializes a new Material object using the specified parameters. The ambient color, emissive color, diffuse color, specular color, and shininess parameters are specified.
Methods
The Material object has the following methods:public void setAmbientColor(Color3f color) public void setAmbientColor(float r, float g, float b) public void getAmbientColor(Color3f color)This parameter specifies this material's ambient color, that is, how much ambient light is reflected by the material's surface.public void setEmissiveColor(Color3f color) public void setEmissiveColor(float r, float g, float b) public void getEmissiveColor(Color3f color)This parameter specifies the color of light, if any, that the material emits. This color is added to the color produced by applying the lighting equation.public void setDiffuseColor(Color3f color) public void setDiffuseColor(float r, float g, float b) public void setDiffuseColor(float r, float g, float b, float a) public void getDiffuseColor(Color3f color)This parameter specifies the color of the material when illuminated by a light source. In addition to the diffuse color (red, green, and blue), the alpha value is used to specify transparency such that transparency = (1 - alpha). When vertex colors are present in geometry that is being lit, those vertex colors are used in place of this diffuse color in the lighting equation unless the vertex colors are ignored.public void setSpecularColor(Color3f color) public void setSpecularColor(float r, float g, float b) public void getSpecularColor(Color3f color)This parameter specifies the specular highlight color of the material.public void setShininess(float shininess) public float getShininess()This parameter specifies a material specular scattering exponent, or shininess. It takes a floating-point number in the range [1.0, 128.0], with 1.0 being not shiny and 128.0 being very shiny.public void setLightingEnable(boolean state) public boolean getLightingEnable()These methods set and retrieve the current state of the lighting enable flag (true
orfalse
) for this Appearance component object.public String toString()This method returns a string representation of this Material's values. If the scene graph is live, only those values with their capability bit set will be displayed.
8.1.11
The Texture object is a component object of an Appearance object that defines the texture properties used when texture mapping is enabled. If the Texture object in an Appearance object isTexture Object null
, then texture mapping is disabled for all nodes that use that Appearance object. The Texture object is an abstract class. As such, all texture objects must be created as either a Texture2D object or a Texture3D object.
Constants
The Texture object defines the following flags:public static final int ALLOW_ENABLE_READ public static final int ALLOW_ENABLE_WRITE public static final int ALLOW_BOUNDARY_MODE_READ public static final int ALLOW_FILTER_READ public static final int ALLOW_IMAGE_READ public static final int ALLOW_IMAGE_WRITE public static final int ALLOW_MIPMAP_MODE_READ public static final int ALLOW_BOUNDARY_COLOR_READ public static final int ALLOW_FORMAT_READ public static final int ALLOW_SIZE_READThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read, and in some cases write, its individual component field information. The size information includes width, height, and number of mipmap levels.
Constructors
The Texture object has the following constructor:public Texture()This constructor is not very useful as the default width and height are 0. The other default values are as follows:
public Texture(int mipMapMode, int format, int width, int height)Constructs an empty Texture object with specifiedmipmapMode
format, width, and height. Defaults are used for all other parameters. IfmipMapMode
is set toBASE_LEVEL
, the image at level 0 must be set by the application using theset-Image
method or thesetImages
method. IfmipMapMode
is set toMULTI_LEVEL_MIPMAP
, then images for all levels must be set. ThemipmapMode
can be one of the following:
- BASE_LEVEL: Indicates that this Texture object has only a base-level image. If multiple levels are needed, they will be implicitly computed.
The
- MULTI_LEVEL_MIPMAP: Indicates that this Texture object has multiple images-one for each mipmap level (that is, log2(max(width,height)) + 1 separate images). If
mipmapMode
is set toMULTI_LEVEL_MIPMAP
, images for all levels must be set.format
is the data of textures saved in this object. Theformat
can be one of the following:
- INTENSITY: Specifies Texture contains only intensity values.
- LUMINANCE: Specifies Texture contains only luminance values.
- ALPHA: Specifies Texture contains only alpha values.
- LUMINANCE_ALPHA: Specifies Texture contains luminance and alpha values.
- RGB: Specifies Texture contains red, green, and blue color values.
- RGBA: Specifies Texture contains red, green, and blue color values and an alpha value.
Methods
The Texture object has the following methods:public void setBoundaryModeS(int boundaryModeS) public int getBoundaryModeS() public void setBoundaryModeT(int boundaryModeT) public int getBoundaryModeT()These parameters specify the boundary mode for the S and T coordinates in this Texture object. The boundary mode is as follows:
- CLAMP: Clamps texture coordinates to be in the range [0, 1]. A constant boundary color is used for U,V values that fall outside this range.
- WRAP: Repeats the texture by wrapping texture coordinates that are outside the range [0, 1]. Only the fractional portion of the texture coordinates is used; the integer portion is discarded.
public void setMinFilter(int minFilter) public int getMinFilter()This parameter specifies the minification filter function. This function is used when the pixel being rendered maps to an area greater than one texel. The minification filter is one of the following:
- FASTEST: Uses the fastest available method for processing geometry.
- NICEST: Uses the nicest available method for processing geometry.
- BASE_LEVEL_POINT: Selects the nearest texel in the level 0 texture map.
- BASE_LEVEL_LINEAR: Performs a bilinear interpolation on the four nearest texels in the level 0 texture map.
- MULTI_LEVEL_POINT: Selects the nearest texel in the nearest mipmap.
- MULTI_LEVEL_LINEAR: Performs trilinear interpolation of texels between four texels each from the two nearest mipmap levels.
public void setMagFilter(int magFilter) public int getMagFilter()This parameter specifies the magnification filter function. This function is used when the pixel being rendered maps to an area less than or equal to one texel. The value is one of the following:
- FASTEST: Uses the fastest available method for processing geometry.
- NICEST: Uses the nicest available method for processing geometry.
- BASE_LEVEL_POINT: Selects the nearest texel in the level 0 texture map.
- BASE_LEVEL_LINEAR: Performs a bilinear interpolation on the four nearest texels in the level 0 texture map.
public void setImage(int level, ImageComponent image) public ImageComponent getImage(int level)These methods set and retrieve the image for a specified mipmap level. Level 0 is the base level.public void setImages(ImageComponent[] images) public ImageComponent[] getImages()These methods set and retrieve the array of images for all mipmap levels.public void setBoundaryColor(Color4f boundaryColor) public void setBoundaryColor(float r, float g, float b, float a) public void getBoundaryColor(Color4f boundaryColor)This parameter specifies the texture boundary color for this Texture object. The texture boundary color is used whenboundaryModeS
orboundaryModeT
is set toCLAMP
. The magnification filter affects the boundary color as follows: For BASE_LEVEL_POINT, the boundary color is ignored since the filter size is 1 and the border is unused. For BASE_LEVEL_LINEAR, the boundary color is used.public void setEnable(boolean state) public boolean getEnable()These methods set and retrieve the state of texture mapping for this Texture object. A value oftrue
means that texture mapping is enabled;false
means that texture mapping is disabled.public void setMipMapMode(int mipMapMode) public int getMipMapMode()These methods set and retrieve the mipmap mode for texture mapping for this Texture object. The mipmap mode is eitherBASE_LEVEL
orMULTI_LEVEL_MIP_MAP
.public int numMipMapLevels()This method retrieves the number of mipmap levels needed for this Texture object.public int getFormat()This method retrieves the format of this Texture object.public int getWidth()This method retrieves the width of this Texture object.public int getHeight()This method retrieves the height of this Texture object.
8.1.12
The Texture2D object is a subclass of the Texture class. It extends the Texture class by adding a constructor for setting a 2D texture image.Texture2D Object
Constructors
The Texture2D object has the following constructors:public Texture2D()This constructor is not very useful as the default width and height are 0.public Texture2D(int mipmapMode, int format, int width, int height)Constructs and initializes a Texture2D object with the specified attributes. ThemipmapMode
parameter is eitherBASE_LEVEL
orMULTI_LEVEL_MIPMAP
. Theformat
parameter is one of the following:INTENSITY
,LUMINANCE
,ALPHA
,LUMI-NANCE_ALPHA
,RGB
, orRGBA
.
8.1.13
The Texture3D object is a subclass of the Texture class. It extends the Texture class by adding a third texture coordinate and by adding a constructor for setting a 3D texture image. If 3D texture mapping is not supported on a particular Canvas3D, 3D texture mapping is ignored for that canvas.Texture3D Object
Constructors
The Texture3D object has the following constructors:public Texture3D()Constructs a Texture3D object with default parameters.
Parameter Default Value depth 0 boundaryModeR WRAP
public Texture3D(int mipmapMode, int format, int width, int height, int depth)Constructs and initializes a Texture3D object using the specified attributes. ThemipmapMode
parameter is eitherBASE_LEVEL
orMULTI_LEVEL_MIPMAP
. Theformat
parameter is one ofINTENSITY
,LUMINANCE
,ALPHA
,LUMINANCE_ALPHA
,RGB
, orRGBA
. The default value for a Texture3D object is as follows:
Parameter Default Value boundaryModeR WRAP
Methods
The Texture3D object has the following methods:public void setBoundaryModeR(int boundaryModeR) public int getBoundaryModeR()This parameter specifies the boundary mode for the R coordinate in this Texture object. The boundary mode is as follows:
- CLAMP: Clamps texture coordinates to be in the range [0, 1]. A constant boundary color is used for R values that fall outside this range.
- WRAP: Repeats the texture by wrapping texture coordinates that are outside the range [0, 1]. Only the fractional portion of the texture coordinates is used; the integer portion is discarded.
public int getDepth()This method retrieves the depth of this Texture3D object.
8.1.14
The TexCoordGeneration object is a component object of an Appearance object that defines the parameters used when texture coordinate generation is enabled. If the TexCoordGeneration object in an Appearance object isTexCoordGeneration Object null
, texture coordinate generation is disabled for all nodes that use that Appearance object.
Constants
The TexCoordGeneration object specifies the following variables:public static final int ALLOW_ENABLE_READ public static final int ALLOW_ENABLE_WRITE public static final int ALLOW_FORMAT_READ public static final int ALLOW_MODE_READ public static final int ALLOW_PLANE_READThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read, and in some cases write, its individual component field information.public static final int OBJECT_LINEARGenerates texture coordinates as a linear function in object coordinates.public static final int EYE_LINEARGenerates texture coordinates as a linear function in eye coordinates.public static final int SPHERE_MAPGenerates texture coordinates using a spherical reflection mapping in eye coordinates.public static final int TEXTURE_COORDINATE_2Generates 2D texture coordinates (S and T).public static final int TEXTURE_COORDINATE_3Generates 3D texture coordinates (S, T, and R).
Constructors
The TexCoordGeneration object has the following constructors:public TexCoordGeneration()Constructs a TexCoordGeneration object with the following default parameters:
Parameter Default Value enable true genMode OBJECT_LINEAR format TEXTURE_COORDINATE_2 planeS (1,0,0,0) planeT (0,1,0,0) planeR (0,0,0,0)
public TexCoordGeneration(int genMode, int format) public TexCoordGeneration(int genMode, int format, Vector4f planeS) public TexCoordGeneration(int genMode, int format, Vector4f planeS, Vector4f planeT) public TexCoordGeneration(int genMode, int format, Vector4f planeS, Vector4f planeT, Vector4f planeR)These constructors construct a TexCoordGeneration object by initializing the specified fields. Default values are used for those state variables not specified in the constructor. The parameters are as follows:
- genMode: Texture generation mode. One of
OBJECT_LINEAR
,EYE_LINEAR
, orSPHERE_MAP
.
- format: Texture format (2D or 3D). Either
TEXTURE_COORDINATE_2
orTEXTURE_COORDINATE_3
.
- planeS: Plane equation for the S coordinate.
- planeT: Plane equation for the T coordinate.
- planeR: Plane equation for the R coordinate.
Methods
The TexCoordGeneration object has the following methods:public void setEnable(boolean state) public boolean getEnable()This parameter enables or disables texture coordinate generation for this Appearance component object. The value istrue
if texture coordinate generation is enabled,false
if texture coordinate generation is disabled.public void setFormat(int format) public int getFormat()This parameter specifies the format, or dimension, of the generated texture coordinates. The format value is eitherTEXTURE_COORDINATE_2
orTEXTURE_COOR-D-INATE_3
.public void setGenMode(int genMode) public int getGenMode()This parameter specifies the texture coordinate generation mode. The value is one ofOBJECT_LINEAR
,EYE_LINEAR
, orSPHERE_MAP
.public void setPlaneS(Vector4f planeS) public void getPlaneS(Vector4f planeS)This parameter specifies the S coordinate plane equation. This plane equation is used to generate the S coordinate inOBJECT_LINEAR
andEYE_LINEAR
texture generation modes.public void setPlaneT(Vector4f planeT) public void getPlaneT(Vector4f planeT)This parameter specifies the T coordinate plane equation. This plane equation is used to generate the T coordinate inOBJECT_LINEAR
andEYE_LINEAR
texture generation modes.public void setPlaneR(Vector4f planeR) public void getPlaneR(Vector4f planeR)This parameter specifies the R coordinate plane equation. This plane equation is used to generate the R coordinate inOBJECT_LINEAR
andEYE_LINEAR
texture generation modes.
8.1.15
The TextureUnitState object defines all texture mapping state for a single texture unit. An Appearance object contains an array of texture unit state objects to define the state for multiple texture mapping units. The texture unit state consists of the following:TextureUnitState Object
- Texture: Defines the texture image and filtering parameters used when texture mapping is enabled. These attributes are defined in a Texture object.
- Texture attributes: Defines the attributes that apply to texture mapping, such as the texture mode, texture transform, blend color, and perspective correction mode. These attributes are defined in a TextureAttributes object.
- Texture coordinate generation: Defines the attributes that apply to texture coordinate generation, such as whether texture coordinate generation is enabled; coordinate format (2D or 3D coordinates); coordinate generation mode (object linear, eye linear, or spherical reflection mapping); and the R, S, and T coordinate plane equations. These attributes are defined in a TexCoordGeneration object.
Constants
The TextureUnitState object has the following flags:public static final int ALLOW_STATE_READ public static final int ALLOW_STATE_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read or write this object's texture, texture attribute, or texture coordinate generation component information.
Constructors
The TextureUnitState object has the following constructors:public TextureUnitState() public TextureUnitState(Texture texture, TextureAttributes textureAttributes, TexCoordGeneration texCoordGeneration)Construct and initialize a TextureUnitState component object. The first constructor uses defaults for all state variables. All component object references are initialized to null. The second constructor uses the specified component objects.
Methods
The TextureUnitState object has the following methods:public void set(Texture texture, TextureAttributes textureAttributes, TexCoordGeneration texCoordGeneration)This method sets the texture, texture attributes, and texture coordinate generation components in this TextureUnitState object to the specified component objects.public void setTexture(Texture texture) public Texture getTexture()These methods set and retrieve the texture object. Setting it to null disables texture mapping for the texture unit corresponding to this TextureUnitState object.public void setTextureAttributes(TextureAttributes textureAttributes) public TextureAttributes getTextureAttributes()These methods set and retrieve the textureAttributes object. Setting it to null will result in default attribute usage for the texture unit corresponding to this TextureUnitState object.public void setTexCoordGeneration(TexCoordGeneration texCoordGeneration) public TexCoordGeneration getTexCoordGeneration()These methods set and retrieve the texCoordGeneration object. Setting it to null disables texture coordinate generation for the texture unit corresponding to this TextureUnitState object.
8.1.16
The MediaContainer object defines all sound data: cached state flag and associated sound media. Currently, this references the sound media in one of three forms: URL string, URL object, or InputStream object. In a future release of Java 3D, media data will include references to Java Media Player objects.MediaContainer Object
Constants
The MediaContainer object has the following flags:public static final int ALLOW_CACHE_READ public static final int ALLOW_CACHE_WRITE public static final int ALLOW_URL_READ public static final int ALLOW_URL_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read or write its cached flag and its URL string.
Constructors
The MediaContainer object has the following constructors:public MediaContainer()Constructs and initializes a new MediaContainer object using the following default values:
Parameter Default Value URLString data null URLObject data null inputStream data null cacheEnable true
public MediaContainer(String path) public MediaContainer(URL url) public MediaContainer(InputStream stream)Construct and initialize a new MediaContainer object using the specified parameters.
Methods
The Sound object has the following methods:public void setCacheEnable(boolean flag) public boolean getCacheEnable()This parameter specifies whether this component contains a noncached reference to the sound data or explicit cached sound data.public void setURL(String path) public void setURL(URL url) public String getURL()These methods are deprecated in Java 3D version 1.2. Use thesetURLString
,setURLObject
, andgetURLString
methods instead.public void setURLString(String path) public String getURLString()These methods set and retrieve the string of URL containing the sound data.public void setURLObject(URL url) public URL getURLObject()These methods set and retrieve the URL containing the sound data.public void setInputStream(InputStream stream) public InputStream getInputStream()These methods set and retrieve the input stream object containing the sound data.
8.1.17
The AuralAttributes object is a component object of a Soundscape node that defines environmental audio parameters that affect sound rendering. These attributes include gain scale factor; atmospheric rolloff; and parameters controlling reverberation, distance frequency filtering, and velocity-activated Doppler effect.AuralAttributes Object
8.1.17.1
The rolloff scale factor is used to model atmospheric changes from the normal speed of sound. The base value, 0.344 meters per millisecond used to approximate the speed of sound through air at room temperature, is multiplied by this scale factor whenever the speed of sound is applied during spatialization calculations. Valid values are 0.0. Values > 1.0 increase the speed of sound, while values < 1.0 decrease its speed. A value of zero makes the sound silent (although the sound continues to play).Attribute Gain Rolloff
8.1.17.2
Within Java 3D's simple model for auralization, there are three components to sound reverberation for a particular listening space:Reverberation
- Delay time: Approximates the time from the start of a sound until it reaches the listener, after reflecting once off the surfaces in the region.
- Reflection coefficient: Attenuates the reverberated sound uniformly (for all frequencies) as it bounces off surfaces.
None of these parameters is affected by sound position. Figure 8-2 shows the interaction of these parameters.
- Feedback loop: Controls the maximum number of times a sound is reflected off the surfaces.
Figure 8-2 Sound Reverberation Parameters
8.1.17.3
Doppler effect can be used to create a greater sense of movement of sound sources and can help unambiguate front-to-back localization errors. The frequency of sound waves emanating from the source are raised or lowered based on the speed of the source in relation to the listener and on severalDoppler Effect AuralAttributes
parameters.
Constants
The AuralAttributes object has the following flags:public static final int ALLOW_ATTRIBUTE_GAIN_READ public static final int ALLOW_ATTRIBUTE_GAIN_WRITE public static final int ALLOW_ROLLOFF_READ public static final int ALLOW_ROLLOFF_WRITE public static final int ALLOW_REFLECTION_COEFFICIENT_READ public static final int ALLOW_REFLECTION_COEFFICIENT_WRITE public static final int ALLOW_REVERB_DELAY_READ public static final int ALLOW_REVERB_DELAY_WRITE public static final int ALLOW_REVERB_ORDER_READ public static final int ALLOW_REVERB_ORDER_WRITE public static final int ALLOW_DISTANCE_FILTER_READ public static final int ALLOW_DISTANCE_FILTER_WRITE public static final int ALLOW_FREQUENCY_SCALE_FACTOR_READ public static final int ALLOW_FREQUENCY_SCALE_FACTOR_WRITE public static final int ALLOW_VELOCITY_SCALE_FACTOR_READ public static final int ALLOW_VELOCITY_SCALE_FACTOR_WRITEThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read or write the associated parameters.
Constructors
The AuralAttributes object has the following constructors:public AuralAttributes()Constructs and initializes a new AuralAttributes object using the following default values:
public AuralAttributes(float gain, float rolloff, float reflectionCoefficient, float reverbDelay, int reverbOrder, Point2f distanceFilter[], float frequencyScaleFactor, float velocityScaleFactor) public AuralAttributes(float gain, float rolloff, float reflectionCoefficient, float reverbDelay, int reverbOrder, float distance[], float frequencyCutoff, float frequencyScaleFactor, float velocityScaleFactor)Construct and initialize a new AuralAttributes object using the specified parameters.
Methods
The AuralAttributes object has the following methods:public void setAttributeGain(float gain) public float getAttributeGain()This parameter specifies an amplitude scale factor applied to all sounds amplitude active within this region. This factor attenuates both direct and reflected/reverberated amplitudes. Valid values are 0.0.public void setRolloff(float rolloff) public float getRolloff()The rolloff scale factor is used to model atmospheric changes from the normal speed of sound. The base value of 0.344 meters per millisecond is used to approximate the speed factor whenever the speed of sound is applied during spatialization calculations. Valid values are 0.0. Values > 1.0 increase the speed of sound; a value of 0.0 makes the sound silent (although the sound continues to play).public void setReflectionCoefficient(float coefficient) public float getReflectionCoefficient()This parameter specifies an average amplitude scale factor used to approximate the average reflective or absorptive characteristics of the composite surfaces in the region the listener is in. This scale factor is applied to the sound's amplitude regardless of the sound's position. There is currently no method to assign different reflective audio properties to individual surfaces. The range of values is 0.0 to 1.0. A value of 1.0 denotes that reflections are unattenuated-the amplitude of reflected sound waves is not decreased. A value of 0.0 represents full absorption of reflections by the surfaces in the listening space.public void setReverbDelay(float reverbDelay) public float getReverbDelay()This parameter specifies the delay time between each order of reflection while reverberation is being rendered. In the first form ofsetReverbDelay
, an explicit delay time is given in milliseconds. In the second form, a reverberation bounds volume is specified, and then the delay time is calculated, becoming the new reverb time delay. A value of 0.0 for delay time disables reverberation.public void setReverbDelay(Bounds reverbVolume)This method is deprecated in Java 3D 1.2. UsesetReverbBounds(Bounds)
method instead.public void setReverbBounds(Bounds reverbVolume) public Bounds getReverbBounds()These methods set and retrieve the reverberation bounds volume. In this form the reverberation bounds volume parameter is used to calculate the reverb delay time and the reverb decay. Specification of a non-null bounding volume causes the explicit values given for reverb delay and decay to be overridden by the implicit values calculated from these bounds.public void setReverbOrder(int reverbOrder) public int getReverbOrder()This parameter limits the number of times reflections are added to the reverberation being rendered. When the amplitude of the nth reflection reaches effective zero, no further reverberations need be added to the sound image. A value of 0 disables reverberation. A nonpositive value specifies an unbounded number of reflections.public void setDistanceFilter(Point2f attenuation[]) public void setDistanceFilter(float distance[], float frequencyCutoff[]) public int getDistanceFilterLength() public void getDistanceFilter(Point2f attenuation[]) public void getDistanceFilter(float distance[], float frequencyCutoff[])This parameter specifies a (distance, filter) attenuation pairs array. If this is not set, no distance filtering is performed (equivalent to using a distance filter ofSound.NO_FILTER
for all distances). Currently, this filter is a low-pass cutoff frequency. This array of pairs defines a piecewise linear slope for a range of values. This attenuation array is similar to the PointSound node'sdistanceAttenuation
pair array, except that frequency values are paired with distances in this list. Using these pairs, distance-based, low-pass frequency filtering can be applied during sound rendering. Distances, specified in the local coordinate system in meters, must be > 0. Frequencies (in Hz) must be > 0.public void setFrequencyScaleFactor(float frequencyScaleFactor) public float getFrequencyScaleFactor()This parameter specifies a scale factor applied to the frequency of sound during rendering playback. If the Doppler effect is disabled, this scale factor can be used to increase or decrease the original pitch of the sound. During rendering, this scale factor expands or contracts the usual frequency shift applied to the sound source due to Doppler-effect calculations. Valid values are 0.0; a value of 0.0 pauses the sound.public void setVelocityScaleFactor(float velocityScaleFactor) public float getVelocityScaleFactor()This parameter specifies a scale factor applied to the relative velocity of the sound relative to the listener's position and movement in relation to the sound's position and movement over time. This scale factor is multiplied by the calculated velocity portion of the Doppler-effect equation used during sound rendering. This allows the application to exaggerate or reduce the relative velocity calculated by the standard Doppler equation. Valid values are 0.0. A value of 0.0 disables any Doppler calculation.
8.1.18
The ImageComponent classes are used for texture and background images. The ImageComponent object is an abstract class that is used to define 2D or 3D ImageComponent classes used in a Java 3D scene graph.ImageComponent Object
- By copying: By default, the set and get image methods copy the image data into or out of this ImageComponent object. This is appropriate for many applications since the application may reuse the RenderedImage object after copying it to the ImageComponent.
An image component object also specifies whether the orientation of its image data is "y-up" or "y-down" (the default). y-up mode causes images to be interpreted as having their origin at the lower left (rather than the default upper left) of a texture or raster image with successive scan lines moving up. This is more consistent with texture mapping data onto a surface, and maps directly into the way textures are used in OpenGL and other 3D APIs. Setting the
- By reference: A new feature in Java 3D version 1.2 allows image data to be accessed by reference, directly from the RenderedImage object. To use this feature, you need to construct an ImageComponent object with the
byReference
flag set to true. In this mode, a reference to the input data is saved but the data itself is not necessarily copied (although it may be, depending on the value of theyUp
flag, the format of the ImageComponent, and the format of the RenderedImage). Image data referenced by an ImageComponent object must not be modified. Applications must exercise care not to violate this rule. If any referenced RenderedImage is modified after it has been passed to an ImageComponent object, the results are undefined. Another restriction in by-reference mode is that if the specified RenderedImage is not an instance of BufferedImage, this ImageComponent cannot be used for readRaster or off-screen rendering operations, since these operations modify the ImageComponent data.yUp
flag to true in conjunction with setting thebyReference
flag to true makes it possible for Java 3D to avoid copying the texture map in some cases.byteVariable = (byte) intValue; // intValue can be > 127IfintValue
is greater than 127,byteVariable
will be negative. The correct value will be extracted when it is used (by masking off the upper bits).
Constants
The ImageComponent object has the following flags:public static final int ALLOW_SIZE_READ public static final int ALLOW_FORMAT_READ public static final int ALLOW_IMAGE_READThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read the associated parameters.public static final int FORMAT_RGBSpecifies that each pixel contains three eight-bit channels, one each for red, green, and blue. This is the same asFORMAT_RGB8
.public static final int FORMAT_RGBASpecifies that each pixel contains four eight-bit channels, one each for red, green, blue, and alpha. This is the same asFORMAT_RGBA8
.public static final int FORMAT_RGB8Specifies that each pixel contains three eight-bit channels, one each for red, green, and blue. This is the same asFORMAT_RGB
.public static final int FORMAT_RGBA8Specifies that each pixel contains four eight-bit channels, one each for red, green, blue, and alpha. This is the same asFORMAT_RGBA
.public static final int FORMAT_RGB5Specifies that each pixel contains three five-bit channels, one each for red, green, and blue.public static final int FORMAT_RGB5_A1Specifies that each pixel contains three five-bit channels, one each for red, green, and blue, and a one-bit channel for alpha.public static final int FORMAT_RGB4Specifies that each pixel contains three four-bit channels, one each for red, green, and blue.public static final int FORMAT_RGBA4Specifies that each pixel contains four four-bit channels, one each for red, green, blue, and alpha.public static final int FORMAT_LUM4_ALPHA4Specifies that each pixel contains two four-bit channels, one each for luminance and alpha.public static final int FORMAT_LUM8_ALPHA8Specifies that each pixel contains two eight-bit channels, one each for luminance and alpha.public static final int FORMAT_R3_G3_B2Specifies that each pixel contains two three-bit channels, one each for red and green, and a two-bit channel for blue.public static final int FORMAT_CHANNEL8Specifies that each pixel contains one eight-bit channel. The channel can be used only for luminance, alpha, or intensity.
Constructors
The ImageComponent object defines the following constructor:public ImageComponent(int format, int width, int height)This constructor constructs and initializes a new ImageComponent object using the specified format, width, and height. Default values are used for all other parameters. The default values are as follows:
Parameter Default Value byReference false yUp false
public ImageComponent(int format, int width, int height, boolean byReference, boolean yUp)Constructs an image component object using the specifiedformat
,width
,height
,byReference
flag, andyUp
flag.
Methods
The ImageComponent object defines the following methods:public int getWidth() public int getHeight() public int getFormat()These methods retrieve the width, height, and format of this image component object.public boolean isByReference()This method retrieves the data access mode for this ImageComponent object.public void setYUp(boolean yUp)This method sets the y-orientation of this ImageComponent object to y-up or y-down.public boolean isYUp()This method retrieves the y-orientation for this ImageComponent object.
8.1.19
The ImageComponent2D class defines a 2D image component. This is used for texture images, background images, and raster components of Shape3D nodes. Prior to Java 3D 1.2, only BufferedImage objects could be used as the input to an ImageComponent2D object. As of Java 3D 1.2, an ImageComponent2D accepts any RenderedImage object (BufferedImage is an implementation of the RenderedImage interface). The methods that set/get a BufferedImage object are left in for compatibility. The new methods that set/get a RenderedImage are a superset of the old methods. In particular, the two set methods in the following example are equivalent:ImageComponent2D Object
BufferedImage bi; RenderedImage ri = bi; ImageComponent2D ic; // Set the image to the specified BufferedImage ic.set(bi); // Set the image to the specified RenderedImage ic.set(ri);Constructors
The ImageComponent2D object defines the following constructors:public ImageComponent2D(int format, int width, int height) public ImageComponent2D(int format, BufferedImage image) public ImageComponent2D(int format, RenderedImage image)The first constructor constructs and initializes a 2D image component object using the specified format, width, height, and a null image. The second and third constructors construct and initialize a 2D image component object using the specified format and image. A copy of the image is made.public ImageComponent2D(int format, int width, int height, boolean byReference, boolean yUp) public ImageComponent2D(int format, BufferedImage image, boolean byReference, boolean yUp) public ImageComponent2D(int format, int width, int height, boolean byReference, boolean yUp)The first constructor constructs a 2D image component object using the specifiedformat
,width
,height
,byReference
flag,yUp
flag, and a null image. The second and third constructors construct a 2D image component object using the specifiedformat
,image
,byReference
flag, andyUp
flag.
Methods
The ImageComponent2D object defines the following methods:public void set(BufferedImage image) public void set(RenderedImage image)These methods set the image in this ImageComponent2D object to the specified BufferedImage or RenderedImage object. If the data access mode is not by-reference, the image data is copied into this object. If the data access mode is by-reference, a reference to the image is saved, but the data is not necessarily copied.public BufferedImage getImage() public RenderedImage getRenderedImage()These methods retrieve the image from this ImageComponent2D object. If the data access mode is not by-reference, a copy of the image is made. If the data access mode is by-reference, the reference is returned.
8.1.20
The ImageComponent3D class defines a 3D image component. This is used for texture images. Prior to Java 3D 1.2, only BufferedImage objects could be used as the input to an ImageComponent3D object. As of Java 3D 1.2, an Image-Component3D accepts an array of arbitrary RenderedImage object (BufferedImage is an implementation of the RenderedImage interface). The methods that set/get a BufferedImage object are left in for compatibility. The new methods that set/get a RenderedImage are a superset of the old methods. In particular, the two set methods in the following example are equivalent:ImageComponent3D Object
BufferedImage bi; RenderedImage ri = bi; ImageComponent3D ic; // Set image 0 to the specified BufferedImage ic.set(0, bi); // Set image 0 to the specified RenderedImage ic.set(0, ri);Constructors
The ImageComponent3D object defines the following constructors:public ImageComponent3D(int format, int width, int height, int depth)Constructs and initializes a 3D image component object using the specifiedformat
,width
,height
, anddepth
. Default values are used for all other parameters. The default values are as follows:
Parameter Default Value array of images null
public ImageComponent3D(int format, BufferedImage[] images) public ImageComponent3D(int format, RenderedImage[] images)These two constructors construct and initialize a 3D image component object using the specifiedformat
and array of images. Default values are used for all other parameters.public ImageComponent3D(int format, int width, int height, int depth, boolean byReference, boolean yUp)This constructor constructs a 3D image component object using the specifiedformat
,width
,height
,depth
,byReference
flag, andyUp
flag. Default values are used for all other parameters.public ImageComponent3D(int format, BufferedImage[] images, boolean byReference, boolean yUp) public ImageComponent3D(int format, RenderedImage[] images, boolean byReference, boolean yUp)These two constructors construct a 3D image component object using the specifiedformat
, BufferedImage or RenderedImage array,byReference
flag, andyUp
flag. Default values are used for all other parameters.
Methods
The ImageComponent3D object defines the following methods:public int getDepth()This method retrieves the depth of this 3D image component object.public void set(RenderedImage[] images) public void set(BufferedImage[] images)These methods set the array of images in this image component to the specified array of RenderedImage or BufferedImage objects. If the data access mode is not by-reference, the data is copied into this object. If the data access mode is by-reference, a shallow copy of the array of references to the objects is made, but the data is not necessarily copied.public RenderedImage[] getRenderedImage() public RenderedImage getRenderedImage(int index)These methods retrieve the images or image from this ImageComponent3D object. If the data access mode is not by-reference, a copy of the images is made. If the data access mode is by-reference, the references are returned.public BufferedImage[] getImage() public BufferedImage getImage(int index)These methods retrieve a copy of the images in this ImageComponent3D object. If the data access mode is not by-reference, a copy of the images is made. If the data access mode is by-reference, the references are returned.public void set(int index, RenderedImage image) public void set(int index, BufferedImage image)These methods set this image component at the specified index to the specified RenderedImage or BufferedImage object. If the data access mode is not by-reference, the data is copied into this object. If the data access mode is by-reference, a reference to the image is saved, but the data is not necessarily copied.
8.1.21
The DepthComponent object is an abstract base class that defines a 2D array of depth (z) values.DepthComponent Object
Constants
The DepthComponent object has the following flags:public static final int ALLOW_SIZE_READ public static final int ALLOW_DATA_READThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read the associated parameters.public int getWidth() public int getHeight()These methods get the width and height of this object.
8.1.22
The DepthComponentFloat object extends the DepthComponent object and defines a 2D array of depth (z) values in floating-point format in the range [0, 1]. A value of 0.0 indicates the closest z value to the user, while a value of 1.0 indicates the farthest z value.DepthComponentFloat Object
Constructors
The DepthComponentFloat object defines the following constructors:public DepthComponentFloat(int width, int height)Constructs a new floating-point depth (z-buffer) component object with the specified width and height.public void setDepthData(float depthData[]) public void getDepthData(float depthData[])These methods set and retrieve the specified depth data for this object.
8.1.23
The DepthComponentInt object extends the DepthComponent object and defines a 2D array of depth (z) values in integer format. Values are in the range [0, (2n) - 1], where n is the z-buffer pixel depth.DepthComponentInt Object
Constructors
The DepthComponentInt object defines the following constructor:public DepthComponentInt(int width, int height)Constructs a new integer depth (z-buffer) component object with the specified width and height.public void setDepthData(int depthData[]) public void getDepthData(int depthData[])These methods set and retrieve the specified depth data for this object.
8.1.24
The DepthComponentNative object extends the DepthComponent object and defines a 2D array of depth (z) values stored in the most efficient format for a particular device. Values are not accessible by the user and may be used only to read the z values and subsequently to write them back.DepthComponentNative Object
Constructors
The DepthComponentNative object defines the following constructor:public DepthComponentNative(int width, int height)Constructs a new native depth (z-buffer) component object with the specified width and height.
8.1.25
Bounds objects define three varieties of containing volumes. Java 3D uses these containing volumes to support various culling operations. The types of bounds include an axis-aligned-box volume, a spherical volume, and a bounding polytope.Bounds Object
Constructors
The Bounds object defines the following constructor:public Bounds()Constructs a new Bounds object.
Methods
The Bounds object defines the following methods:public abstract Object clone()Clones this object.public abstract void set(Bounds boundsObject)This method sets the value of this Bounds object to enclose the specified bounding object.public abstract boolean intersect(Point3d origin, Point3d direction) public abstract boolean intersect(Point3d point) public abstract boolean intersect(Bounds boundsObject) public abstract boolean intersect(Bounds boundsObjects[])These methods test for the intersection of this Bounds object with a ray, a point, another Bounds object, or an array of Bounds objects, respectively.public abstract Bounds closestIntersection(Bounds boundsObjects[])This method finds the closest bounding object that intersects this bounding object.public abstract void combine(Bounds boundsObject) public abstract void combine(Bounds boundsObjects[]) public abstract void combine(Point3d point) public abstract void combine(Point3d points[])These methods combine this Bounds object with a bounding object, an array of bounding objects, a point, or an array of points, respectively.public abstract void transform(Bounds bounds, Transform3D trans) public abstract void transform(Transform3D trans)The first method tranforms a Bounds object so that it bounds a volume that is the result of transforming the given bounding object by the given transform. The second method transforms the Bounds object by the given transform.public abstract boolean equals(Object bounds)This method indicates whether the specifiedbounds
object is equal to this Bounds object. They are equal if both the specifiedbounds
object and this Bounds are instances of the same Bounds subclass and all of the data members ofbounds
are equal to the corresponding data members in this Bounds.public abstract int hashCode()This method returns a hash code for this Bounds object based on the data values in this object. Two different Bounds objects of the same type with identical data values (that is,Bounds.equals
returns true) will return the same hash code. Two Bounds objects with different data members may return the same hash code value, although this is not likely.public abstract boolean isEmpty()This method tests whether the bounds is empty. A bounds is empty if it isnull
(either by construction or as the result of a null intersection) or if its volume is negative. A bounds with a volume of zero is not empty.
8.1.26
BoundingBox objects are axis-aligned bounding box volumes.BoundingBox Object
Constructors
The BoundingBox object defines the following constructors:public BoundingBox() public BoundingBox(Point3d lower, Point3d upper) public BoundingBox(Bounds boundsObject) public BoundingBox(Bounds bounds[])The first constructor constructs and initializes a 2X unity BoundingBox about the origin. The second constructor constructs and initializes a BoundingBox from the given minimum and maximum in x, y, and z. The third constructor constructs and initializes a BoundingBox from a bounding object. The fourth constructor constructs and initializes a BoundingBox from an array of bounding objects.
Methods
The BoundingBox object defines the following methods:public void getLower(Point3d p1) public void setLower(Point3d p1) public void setLower(double xmin, double ymin, double zmin)This parameter specifies the lower corner of this bounding box.public void getUpper(Point3d p1) public void setUpper(Point3d p1) public void setUpper(double xmax, double ymax, double zmax)This parameter specifies the upper corner of this bounding box.public void set(Bounds boundsObject)Sets the value of this bounding region to enclose the specified bounding object.public Object clone()Creates a copy of this bounding box.public void combine(Bounds boundsObject) public void combine(Bounds boundsObjects[]) public void combine(Point3d point) public void combine(Point3d points[])These methods combine this bounding box with a bounding object, an array of bounding objects, a point, or an array of points, respectively.public void transform(Bounds boundsObject, Transform3D matrix) public void transform(Transform3D matrix)The first method transforms a bounding box so that it bounds a volume that is the result of transforming the given bounding object by the given transform. The second method transforms the bounding box by the given transform.public boolean intersect(Point3d origin, Vector3d direction) public boolean intersect(Point3d point) public boolean intersect(Bounds boundsObject) public boolean intersect(Bounds boundsObjects[])These methods test for the intersection of this bounding box with a ray, a point, another Bounds object, and an array of Bounds objects, respectively.public boolean intersect(Bounds boundsObject, BoundingBox newBoundBox) public boolean intersect(Bounds boundsObjects[], BoundingBox newBoundBox)These methods compute a new BoundingBox that bounds the volume created by the intersection of this BoundingBox with another Bounds object or array of Bounds objects.public Bounds closestIntersection(Bounds boundsObjects[])This method finds the closest bounding object that intersects this bounding box.public boolean equals(Object bounds)This method indicates whether the specifiedbounds
object is equal to this BoundingBox object. They are equal if the specifiedbounds
object is an instance of BoundingBox and all of the data members ofbounds
are equal to the corresponding data members in this BoundingBox.public int hashCode()This method returns a hash code value for this BoundingBox object based on the data values in this object. Two different BoundingBox objects with identical data values (that is,BoundingBox.equals
returns true) will return the same hash code value. Two BoundingBox objects with different data members may return the same hash code value, although this is not likely.public boolean isEmpty()This method tests whether the bounding box is empty. A bounding box is empty if it isnull
(either by construction or as the result of a null intersection) or if its volume is negative. A bounding box with a volume of zero is not empty.
8.1.27
The BoundingSphere object defines a spherical bounding volume. It has two associated values: the center point and the radius of the sphere.BoundingSphere Object
Constructors
The BoundingSphere object defines the following constructors:public BoundingSphere() public BoundingSphere(Point3D center, double radius) public BoundingSphere(Bounds boundsObject) public BoundingSphere(Bounds boundsObjects[])The first constructor constructs and initializes a BoundingSphere to unity (radius = 1.0 and center at 0.0, 0.0, 0.0). The second constructor constructs and initializes a BoundingSphere from a center and radius. The third constructor constructs and initializes a BoundingSphere from a bounding object. The fourth constructor constructs and initializes a BoundingSphere from an array of bounding objects.
Methods
The BoundingSphere object defines the following methods:public double getRadius() public void setRadius(double r)This parameter specifies the bounding sphere radius.public void getCenter(Point3d center) public void setCenter(Point3d center)This parameter defines the position of the bounding sphere.public void set(Bounds boundsObject)Sets the value of this bounding sphere to enclose the volume specified by the Bounds object.public Object clone()Creates a copy of the bounding sphere.public void combine(Bounds boundsObject) public void combine(Bounds boundsObjects[]) public void combine(Point3d point) public void combine(Point3d points[])These methods combine this bounding sphere with a bounding object, an array of bounding objects, a point, or an array of points, respectively.public boolean intersect(Point3d origin, Point3d direction) public boolean intersect(Point3d point) public boolean intersect(Bounds boundsObject) public boolean intersect(Bounds boundsObjects[])These methods test for the intersection of this bounding sphere with the given ray, point, another Bounds object, or an array of Bounds objects.public boolean intersect(Bounds boundsObject, BoundingSphere newBoundSphere) public boolean intersect(Bounds boundsObjects[], BoundingSphere newBoundSphere)These methods compute a new BoundingSphere that bounds the volume created by the intersection of this BoundingSphere with another Bounds object or array of Bounds objects.public Bounds closestIntersection(Bounds boundsObjects[])This method finds the closest bounding object that intersects this bounding sphere.public void transform(Bounds boundsObject, Transform3D matrix) public void transform(Transform3D matrix)The first method transforms a bounding sphere so that it bounds a volume that is the result of transforming the given bounding object by the given transform. The second method transforms the bounding sphere by the given transform. Note that when transforming a bounding sphere by a transformation matrix containing a nonuniform scale or a shear, the result is a bounding sphere with a radius equal to the maximal scale in any direction-the bounding sphere does not transform into an ellipsoid.public boolean equals(Object bounds)This method indicates whether the specifiedbounds
object is equal to this BoundingSphere object. They are equal if the specifiedbounds
object is an instance of BoundingSphere and all of the data members ofbounds
are equal to the corresponding data members in this BoundingSphere.public int hashCode()This method returns a hash code value for this BoundingSphere object based on the data values in this object. Two different BoundingSphere objects with identical data values (that is,BoundingSphere.equals
returns true) will return the same hash code value. Two BoundingSphere objects with different data members may return the same hash code value, although this is not likely.public String toString()This method returns a string representation of this class.public boolean isEmpty()This method tests whether the bounding sphere is empty. A bounding sphere is empty if it isnull
(either by construction or as the result of a null intersection) or if its volume is negative. A bounding sphere with a volume of zero is not empty.
8.1.28
A BoundingPolytope object defines a polyhedral bounding region using the intersection of three or more half spaces. The region defined by a BoundingPolytope is always convex and must be closed.BoundingPolytope Object Each plane in the BoundingPolytope specifies a half space defined by the equation:
The parameters are passed in the x, y, z, and w fields, respectively, of a Vector4d object. The intersection of the set of half spaces corresponding to the planes in this BoundingPolytope defines the bounding region.
- where A, B, C, D are the parameters that specify the plane.
Constructors
The BoundingPolytope object defines the following constructors:public BoundingPolytope()This constructor constructs and initializes a BoundingPolytope to a set of six planes that define a cube, such that -1 x,y,z 1. The values of the planes are as follows:
planes[0] x 1 (1,0,0,-1) planes[1] -x 1 (-1,0,0,-1) planes[2] y 1 (0,1,0,-1) planes[3] -y 1 (0,-1,0,-1) planes[4] z 1 (0,0,1,-1) planes[5] -z 1 (0,0,-1,-1)
public BoundingPolytope(Vector4d planes[]) public BoundingPolytope(Bounds boundsObject) public BoundingPolytope(Bounds boundsObjects[])The first constructor constructs and initializes a BoundingPolytope from an array of bounding planes. The second constructor constructs and initializes a BoundingPolytope from a Bounds object. The new polytope will circumscribe the region specified by the input bounds. The final constructor constructs and initializes a BoundingPolytope from an array of Bounds objects. The new polytope will circumscribe the union of the regions specified by the input bounds objects.
Methods
The BoundingPolytope object defines the following methods:public void setPlanes(Vector4d planes[]) public void getPlanes(Vector4d planes[])These methods set and retrieve the bounding planes for this BoundingPolytope object.public int getNumPlanes()This method returns the number of bounding planes for this bounding polytope.public void set(Bounds boundsObject)This method sets the planes for this BoundingPolytope by keeping its current number and direction of the planes and by computing new plane positions to enclose the given Bounds object.public Object clone()This method creates a copy of the BoundingPolytope object.public void combine(Bounds boundsObject) public void combine(Bounds boundsObjects[]) public void combine(Point3d point) public void combine(Point3d points[])These methods combine this BoundingPolytope with a bounding object, an array of bounding objects, a point, or an array of points, respectively.public void transform(Bounds bounds, Transform3D matrix) public void transform(Transform3D matrix)The first method tranforms a bounding polytope so that it bounds a volume that is the result of transforming the given bounding object by the given transform. The second method transforms the bounding polytope by the given transform.public boolean intersect(Point3d origin, Vector3d direction) public boolean intersect(Point3d point) public boolean intersect(Bounds boundsObject) public boolean intersect(Bounds boundsObjects[])These methods test for the intersection of this BoundingPolytope with the given ray, point, another Bounds object, or array of Bounds objects, respectively.public boolean intersect(Bounds boundsObject, BoundingPolytope newBoundPolytope) public boolean intersect(Bounds boundsObjects[], BoundingPolytope newBoundPolytope)These methods compute a new BoundingPolytope that bounds the volume created by the intersection of this BoundingPolytope with another Bounds object or array of Bounds objects.public Bounds closestIntersection(Bounds boundsObjects[])This method finds the closest bounding object that intersects this bounding polytope.public boolean equals(Object bounds)This method indicates whether the specifiedbounds
object is equal to this BoundingPolytope object. They are equal if the specifiedbounds
object is an instance of BoundingPolytope and all of the data members ofbounds
are equal to the corresponding data members in this BoundingPolytope.public int hashCode()This method returns a hash code value for this BoundingPolytope object based on the data values in this object. Two different BoundingPolytope objects with identical data values (that is,BoundingPolytope.equals
returns true) will return the same hash code value. Two BoundingPolytope objects with different data members may return the same hash code value, although this is not likely.public boolean isEmpty()This method tests whether the bounding polytope is empty. A bounding polytope is empty if it isnull
(either by construction or as the result of a null intersection) or if its volume is negative. A bounding polytope with a volume of zero is not empty.
8.1.29
Transformations are represented by matrix multiplication and include such operations as rotation, scaling, and translation. The Transform3D object is represented internally as a 4 x 4 double-precision floating-point matrix. The mathematical representation is row major, as in traditional matrix mathematics.Transform3D Object public static final int ZERO public static final int IDENTITY public static final int SCALE public static final int TRANSLATION public static final int ORTHOGONAL public static final int RIGID public static final int CONGRUENT public static final int AFFINE public static final int NEGATIVE_DETERMINANTA Transform3D has an associated type that is internally computed when the transform object is constructed and updated any time it is modified. A matrix will typically have multiple types. For example, the type associated with an identity matrix is the result of ORing all of the types, except forZERO
andNEGATIVE_DETERMINANT
, together. There are public methods available to get the ORed type of the transformation, the sign of the determinant, and the least general matrix type. The matrix type flags are defined as follows:
- ZERO: Zero matrix.
- IDENTITY: Identity matrix.
- SCALE: This matrix is a uniform scale matrix-there are no rotational or translation components.
- TRANSLATION: This matrix has translation components only. The scale is unity, and there are no rotational components.
- ORTHOGONAL: The four row vectors that make up an orthogonal matrix form a basis, meaning that they are mutually orthogonal. The scale is unity, and there are no translation components.
- RIGID: The upper 3 x 3 of the matrix is orthogonal, and there is a translation component-the scale is unity.
- CONGRUENT: This is an angle- and length-preserving matrix, meaning that it can translate, rotate, and reflect about an axis and scale by an amount that is uniform in all directions. These operations preserve the distance between any two points and the angle between any two intersecting lines.
A matrix is also classified by the sign of its determinant:
- AFFINE: An affine matrix can translate, rotate, reflect, scale anisotropically, and shear. Lines remain straight, and parallel lines remain parallel, but the angle between intersecting lines can change.
The Java 3D model for 4 x 4 transformations is
- NEGATIVE_DETERMINANT: This matrix has a negative determinant. An orthogonal matrix with a positive determinant is a rotation matrix. An orthogonal matrix with a negative determinant is a reflection and rotation matrix.
Note: When transforming a Point3f or a Point3d, the input w is set to 1. When transforming a Vector3f or Vector3d, the input w is set to 0.
Constructors
The Transform3D object defines the following constructors:public Transform3D()This constructs and initializes a new Transform3D object to the identity transformation.public Transform3D(Transform3D t1)This constructs and initializes a new Transform3D object from the specified transform.public Transform3D(Matrix3f m1, Vector3d t1, double s) public Transform3D(Matrix3d m1, Vector3d t1, double s) public Transform3D(Matrix3f m1, Vector3f t1, float s)These construct and initialize a new Transform3D object from the rotation matrix, translation, and scale values. The scale is applied only to the rotational component of the matrix (upper 3 x 3) and not to the translational components of the matrix.public Transform3D(Matrix4f m1) public Transform3D(Matrix4d m1)These construct and initialize a new Transform3D object from the 4 x 4 matrix. The type of the constructed transform is classified automatically.public Transform3D(float matrix[]) public Transform3D(double matrix[])These construct and initialize a new Transform3D object from the array of length 16. The top row of the matrix is initialized to the first four elements of the array, and so on. The type of the constructed transform is classified automatically.public Transform3D(Quat4d q1, Vector3d t1, double s) public Transform3D(Quat4f q1, Vector3d t1, double s) public Transform3D(Quat4f q1, Vector3f t1, float s)These construct and initialize a new Transform3D object from the quaternionq1
, the translationt1
, and the scales
. The scale is applied only to the rotational components of the matrix (the upper 3 x 3) and not to the translational components of the matrix.public Transform3D(GMatrix m1)This constructs and initializes a new Transform3D object and initializes it to the upper 4 x 4 of the specified GMatrix. If the specified matrix is smaller than 4 x 4, the remaining elements in the transformation matrix are assigned to zero.
Methods
The Transform3D object defines the following methods:public final int getType()This method retrieves the type of this matrix. The type is an ORed bitmask of all of the type classifications to which it belongs.public final int getBestType()This method retrieves the least general type of this matrix. The order of generality from least to most is as follows:ZERO
,IDENTITY
,SCALE
,TRANSLATION
,ORTHOGONAL
,RIGID
,CONGRUENT
, andAFFINE
. If the matrix isORTHOGONAL
, calling the methodgetDeterminantSign
will yield more information.public final void setAutoNormalize(boolean autoNormalize) public final boolean getAutoNormalize()These methods set and retrieve the state of autonormalization. Autonormalization performs an automatic singular value decomposition (SVD) normalization of the rotational components (upper 3 x 3) of this matrix after every subsequent matrix operation on this object, unless the boolean is subsequently set tofalse
. The default value for this parameter isfalse
.public final boolean getDeterminantSign()This method returns the sign of the determinant of this matrix. A return value oftrue
indicates a positive determinant; a return value offalse
indicates a negative determinant. In general, an orthogonal matrix with a positive determinant is a pure rotation matrix; an orthogonal matrix with a negative determinant is both a rotation and a reflection matrix.public final void setIdentity()This method sets this transform to the identity matrix.public final void setZero()This method sets this transform to all zeros.public final void setEuler(Vector3d euler)This method sets the rotational component (upper 3 x 3) of this transform to the rotation matrix converted from the Euler angles provided. Theeuler
parameter is a Vector3d consisting of three rotation angles applied first about the x, then the y, then the z axis. These rotations are applied using a static frame of reference. In other words, the orientation of the y rotation axis is not affected by the x rotation and the orientation of the z rotation axis is not affected by the x or y rotation.public final void setRotation(Matrix3d m1) public final void setRotation(Matrix3f m1)These methods set the rotational component (upper 3 x 3) of this transform to the values in the specified matrix; the other elements of this transform are unchanged. A singular value decomposition is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3 x 3 matrix components are replaced by the input rotational components, and finally the scale is reapplied to the rotational components.public final void setRotation(Quat4f q1) public final void setRotation(Quat4d q1)These methods set the rotational component (upper 3 x 3) of this transform to the appropriate values derived from the specified quaternion; the other elements of this transform are unchanged. A singular value decomposition is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3 x 3 matrix components are replaced by the matrix equivalent of the quaternion, and finally the scale is reapplied to the rotational components.public final void setRotation(AxisAngle4d a1) public final void setRotation(AxisAngle4f a1)These methods set the rotational component (upper 3 x 3) of this transform to the appropriate values derived from the specified axis angle; the other elements of this transform are unchanged. A singular value decomposition is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3 x 3 matrix components are replaced by the matrix equivalent of the axis angle, and finally the scale is reapplied to the rotational components.public final void setScale(double scale) public final double getScale()Theset
method sets the scale component of this transform by factoring out the current scale from the rotational component and multiplying by the new scale. Theget
method performs an SVD normalization of this transform to calculate and return the scale factor; this transform is not modified. If the matrix has nonuniform scale factors, the largest of the x, y, and z scale factors will be returned.public final void setScale(Vector3d scale) public final void getScale(Vector3d scale)Theset
method sets the possibly nonuniform scale component to the current transform. Any existing scale is first factored out of the existing transform before the new scale is applied. Theget
method returns the possibly no-uniform scale components of the current transform and places them into the scale vector.public final void setNonUniformScale(double xScale, double yScale, double zScale)This is a deprecated method; usesetScale(Vector3d)
instead. Note that thesetScale
method modifies only the scale component.public final void scaleAdd(double s, Transform3D t1, Transform3D t2) public final void scaleAdd(double s, Transform3D t1)The first method scales transformt1
by a uniform scale matrix with scale factors
, then adds transformt2
(this = S * t1 + t2). The second method scales this transform by a uniform scale matrix with scale factors
, then adds transform t1 (this = S * this + t1).public final void setRotationScale(Matrix3f m1) public final void setRotationScale(Matrix3d m1) public final void getRotationScale(Matrix3f m1) public final void getRotationScale(Matrix3d m1)Theset
methods replace the upper 3 x 3 matrix values of this transform with the values in the matrixm1
. Theget
methods retrieve the upper 3 x 3 matrix values of this transform and place them in the matrixm1
.public String toString()This method returns the matrix elements of this transform as a string.public final void add(Transform3D t1) public final void add(Transform3D t1, Transform3D t2) public final void sub(Transform3D t1) public final void sub(Transform3D t1, Transform3D t2)The firstadd
method adds this transform to the transformt1
and places the result back intothis
. The secondadd
method adds the transformst1
andt2
and places the result intothis
. The firstsub
method subtracts transformt1
from this transform and places the result back intothis
. The secondsub
method subtracts transformt2
fromt1
and places the result intothis
.public final void add(double scalar) public final void add(double scalar, Transform3D t1)The first method adds a scalar to each component of this transform. The second method adds a scalar to each component of the transformt1
and places the result intothis
. Transformt1
is not modified.public final void transpose() public final void transpose(Transform3D t1)The first method transposes this matrix in place. The second method transposes transformt1
and places the value into this transform. The transform t1 is not modified.public void rotX(double angle) public void rotY(double angle) public void rotZ(double angle)These three methods set the value of this matrix to a rotation matrix about the specified axis. The matrices rotate in a counter-clockwise (right-handed) direction. The angle to rotate is specified in radians.public final void setTranslation(Vector3f trans) public final void setTranslation(Vector3d trans)This method modifies the translational components of this transform to the values of the argument. The other values of this transform are not modified.public final void set(Quat4f q1) public final void set(Quat4d q1)These methods set the value of this transform to the matrix conversion of the quaternion argument.public final void set(Quat4d q1, Vector3d t1, double s) public final void set(Quat4f q1, Vector3d t1, double s) public final void set(Quat4f q1, Vector3f t1, float s)These methods set the value of this matrix from the rotation expressed by the quaternionq1
, the translationt1
, and the scales
.public final void set(Vector3d trans) public final void set(Vector3f trans)These methods set the translational value of this matrix to the specified vector parameter values and set the other components of the matrix as if this transform were an identity matrix.public final void set(Vector3d v1, double scale) public final void set(Vector3f v1, float scale)These methods set the value of this transform to a scale and translation matrix; the translation is scaled by the scale factor, and all of the matrix values are modified.public final void set(Transform3D t1)This method sets the matrix, type, and state of this transform to the matrix, type, and state of the transformt1
.public final void set(double matrix[]) public final void set(float matrix[])These methods set the matrix values of this transform to the specified matrix values.public final void set(double scale) public final void set(double scale, Vector3d v1) public final void set(float scale, Vector3f v1)The first method sets the value of this transform to a uniform scale; all of the matrix values are modified. The next two methods set the value of this transform to a scale and translation matrix; the scale is not applied to the translation, and all of the matrix values are modified.public final void set(Matrix4d m1) public final void set(Matrix4f m1)These methods set the matrix values of this transform to the matrix values in the specified matrix.public final void set(Matrix3f m1) public final void set(Matrix3d m1)These methods set the rotational and scale components (upper 3 x 3) of this transform to the matrix values in the specified matrix. The remaining matrix values are set to the identity matrix. All values of the matrix are modified.public final void set(Matrix3f m1, Vector3f t1, float s) public final void set(Matrix3f m1, Vector3d t1, double s) public final void set(Matrix3d m1, Vector3d t1, double s)These methods set the value of this matrix from the rotation expressed by the rotation matrixm1
, the translationt1
, and the scales
. The scale is applied only to the rotational component of the matrix (upper 3 x 3) and not to the translational component of the matrix.public final void set(GMatrix matrix)These methods set the matrix values of this transform to the matrix values in the specified matrix. The GMatrix object must specify a 4 x 4, 3 x 4, or 3 x 3 matrix.public final void set(AxisAngle4f a1) public final void set(AxisAngle4d a1)These methods set the rotational component (upper 3 x 3) of this transform to the matrix conversion of the specified axis-angle argument. The remaining matrix values are set to the identity matrix. All values of the matrix are modified.public final void get(double matrix[]) public final void get(float matrix[])These methods place the values of this transform into the specified matrix of length 16. The first four elements of the array will contain the top row of the transform matrix, and so on.public final void get(Matrix4d matrix) public final void get(Matrix4f matrix)These methods place the values of this transform into thematrix
argument.public final void get(Matrix3d m1) public final void get(Matrix3f m1)These methods place the normalized rotational component of this transform into the 3 x 3 matrix argument.public final double get(Matrix3d m1, Vector3d t1) public final float get(Matrix3f m1, Vector3f t1) public final double get(Matrix3f m1, Vector3d t1)These methods place the normalized rotational component of this transform into them1
parameter and the translational component into thet1
parameter.public final void get(Quat4d q1) public final void get(Quat4f q1)These methods perform an SVD normalization of this matrix to acquire the normalized rotational component. The values are placed into the quaternionq1
parameter.public final double get(Quat4d q1, Vector3d t1) public final float get(Quat4f q1, Vector3f t1) public final double get(Quat4f q1, Vector3d t1)These methods perform an SVD normalization of this transform to calculate the rotation as a quaternion, the translation, and the scale. None of the matrix values is modified.public final void get(Vector3d trans) public final void get(Vector3f trans)These methods retrieve the translational components of this transform.public final void invert() public final void invert(Transform3D t1)The first method inverts this transform in place. The second method sets the value of this transform to the inverse of the transformt1
. Both of these methods use the transform type to determine the optimal algorithm for inverting the transform.public final double determinant()This method calculates and returns the determinant ofthis
transform.public final void mul(Transform3D t1) public final void mul(Transform3D t1, Transform3D t2)The first method sets the value of this transform to the result of multiplying itself with transformt1
(this = this * t1). The second method sets the value of this transform to the result of multiplying transformt1
by transformt2
(this = t1 * t2).public final void mul(double scalar) public final void mul(double scalar, Transform3D t1)The first method multiplies this transform by the scalar constant. The second method multiplies transform t1 by the scalar constant and places the value intothis
transform.public final void mulInverse(Transform3D t1) public final void mulInverse(Transform3D t1, Transform3D t2)The first method multiplies this transform by the inverse of transformt1
and places the result intothis
transform (this = this * t1-1). The second method multiplies transformt1
by the inverse of transformt2
and places the result intothis
transform (this = t1 * t2-1).public final void mulTransposeRight(Transform3D t1,Transform3D t2) public final void mulTransposeLeft(Transform3D t1, Transform3D t2) public final void mulTransposeBoth(Transform3D t1, Transform3D t2)The first method multiplies the transformt1
by the transpose of transformt2
and places the result into this transform (this = t1 * transpose(t2)). The second method multiplies the transpose of transformt1
by transformt2
and places the result intothis
transform (this = transpose(t1) * t2). The third method multiplies the transpose of transformt1
by the transpose oft2
and places the result intothis
transform (this = transpose(t1) * transpose(t2)).public final void normalize() public final void normalize(Transform3D t1)Both of these methods use an SVD normalization. The firstnormalize
method normalizes the rotational components (upper 3 x 3) of matrixthis
and places the results back intothis
. The secondnormalize
method normalizes the rotational components (upper 3 x 3) of transformt1
and places the result inthis
.public final void normalizeCP() public final void normalizeCP(Transform3D t1)Both of these methods use a cross-product (CP) normalization. The firstnormalizeCP
method normalizes the rotational components (upper 3 x 3) of this transform and places the result into this transform. The secondnormalizeCP
method normalizes the rotational components (upper 3 x 3) of transformt1
and places the result intothis
transform.public boolean equals(Transform3D t1) public boolean equals(Object o1)The first method returnstrue
if all of the data members of transformt1
are equal to the corresponding data members inthis
transform. The second method returns true if the Objecto1
is of type Transform3D and all of the data members ofo1
are equal to the corresponding data members in this Transform3D.public boolean epsilonEquals(Transform3D t1, double epsilon)This method returnstrue
if the L distance between this transform and transformm1
is less than or equal to the epsilon parameter; otherwise, it returnsfalse
. The L distance is equal to
- MAX[i=0,1,2,3 ; j=0,1,2,3 ; abs[(this.m(i,j) - m1.m(i,j)]
public int hashCode()This method returns a hash number based on the data values in this object. Two different Transform3D objects with identical data values (that is,true
is returned fortrans.equals(Transform3D)
) will return the same hash number. Two Transform3D objects with different data members may return the same hash value, although this is not likely.public final void transform(Vector4d vec, vector4d vecOut) public final void transform(Vector4f vec, Vector4f vecOut) public final void transform(Vector4d vec) public final void transform(Vector4f vec)The first two methods transform the vectorvec
by this transform and place the result intovecOut
. The last two methods transform the vectorvec
by this transform and place the result back intovec
.public final void transform(Point3d point, Point3d pointOut) public final void transform(Point3f point, point3f pointOut) public final void transform(Point3d point) public final void transform(Point3f point)The first two methods transform thepoint
parameter by this transform and place the result intopointOut
. The last two methods transform thepoint
parameter by this transform and place the result back intopoint
. In both cases, the fourth element of thepoint
input parameter is assumed to be 1.public final void transform(Vector3d normal, Vector3d normalOut) public final void transform(Vector3f normal, Vector3f normalOut) public final void transform(Vector3d normal) public final void transform(Vector3f normal)The first two methods transform thenormal
parameter by this transform and place the value intonormalOut
. The third and fourth methods transform thenormal
parameter by this transform and place the value back intonormal
.
8.1.29.1
View Model Compatibility Mode Methods: Viewing Matrix public void lookAt(Point3d eye, Point3d center, Vector3d up)This is a utility method that specifies the position and orientation of a viewing transformation. It works very much like the similar function in OpenGL. The inverse of this transform can be used to control the ViewPlatform object within the scene graph. Alternatively, this transform can be passed directly to the View'sVpcToEc
transform via the compatibility mode viewing functions defined in Section C.11.2, "Using the Camera-Based View Model."
8.1.29.2
View Model Compatibility Mode Methods: Projection Matrix public void frustum(double left, double right, double bottom, double top, double near, double far) public void perspective(double fovx, double aspect, double zNear, double zFar) public void ortho(double left, double right, double bottom, double top, double near, double far)These three utility methods allow an application to create a perspective or parallel (orthographic) projection matrix. These three methods work very much like the similar functions in OpenGL. The resulting Transform3D can be used to set directly the View's left and right projection transforms when in compatibility mode. See Section C.11.2, "Using the Camera-Based View Model," for details. Thefovx
parameter specifies the field of view in the x direction in radians.
8.2
A Geometry object is an abstract class that specifies the geometry component information required by a Shape3D node. Geometry objects describe both the geometry and topology of the Shape3D nodes that reference them. Geometry objects consist of four generic geometric types: CompressedGeometry, Geometry-Array, Raster, and Text3D (see Figure 8-3). Each of these geometric types defines a visible object or set of objects. A Geometry object is used as a component object of a Shape3D leaf node.Node Component Objects: Geometry
Figure 8-3 Geometry Component Object Hierarchy
Constants
The Geometry object defines the following constant:public static final int ALLOW_INTERSECTThis flag specifies that this Geometry object allows the intersect operation.public Geometry()Constructs a new Geometry object.
8.2.1
A GeometryArray object is an abstract class from which several classes are derived to specify a set of geometric primitives. A GeometryArray contains separate arrays of the following vertex components: coordinates, colors, normals, and texture coordinates and a bitmask indicating which of these components are present.GeometryArray Object
- By copying: The existing methods for setting positional coordinates, colors, normals, and texture coordinates (such as
setCoordinate and setColors
) 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.A single GeometryArray contains a predefined collection of per-vertex information; all of the vertices in a GeometryArray object have the same format and primitive type. Different GeometryArrays can contain different per-vertex information. One GeometryArray might contain only three-space coordinates; another might contain per-vertex coordinates, normals, colors, and texture coordinates; yet another might contain any subset of the previous example.
- 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 thevertexFormat
field of the constructor for this GeometryArray. In this mode, the various set methods for coordinates, normals, colors, and texture coordinates are not used. Instead, new methods are used to set a reference to user-supplied coordinate, color, normal, and texture coordinate arrays (such assetCoordRefFloat and setColorRefFloat
). Data in any array that is referenced by a live or compiled GeometryArray object may be modified only via theupdateData
method (subject to theALLOW_REF_DATA_WRITE
capability bit). Applications must exercise care not to violate this rule. If any referenced geometry data is modified outside of theupdateData
method, the results are undefined.
Constants
The GeometryArray object defines the following flags:public static final int ALLOW_COORDINATE_READ public static final int ALLOW_COORDINATE_WRITEThese flags specify that the GeometryArray object allows reading or writing of the array of coordinates.public static final int ALLOW_COLOR_READ public static final int ALLOW_COLOR_WRITEThese flags specify that the GeometryArray object allows reading or writing of the array of colors.public static final int ALLOW_NORMAL_READ public static final int ALLOW_NORMAL_WRITEThese flags specify that the GeometryArray object allows reading or writing of the array of normals.public static final int ALLOW_TEXCOORD_READ public static final int ALLOW_TEXCOORD_WRITEThese flags specify that the GeometryArray object allows reading or writing of the array of texture coordinates.public static final int ALLOW_COUNT_READ public static final int ALLOW_COUNT_WRITEThese flags specify that the GeometryArray object allows reading or writing of any count or initial index data (such as the vertex count) associated with the GeometryArray.public static final int ALLOW_FORMAT_READThis flag specifies that the GeometryArray object allows reading the vertex format associated with the GeometryArray.public static final int ALLOW_REF_DATA_READ public static final int ALLOW_REF_DATA_WRITEThese flags specify that this GeometryArray allows reading or writing the geometry data reference information for this object. The second flag also enables writing the referenced data itself, via the GeometryUpdater interface. These are used only in by-reference geometry mode.public static final int BY_REFERENCEThis flag specifies that the position, color, normal, and texture coordinate data for this GeometryArray are accessed by reference.public static final int INTERLEAVEDThis flag specifies that the position, color, normal, and texture coordinate data for this GeometryArray are accessed via a single interleaved, floating-point array reference. All of the data values for each vertex are stored in consecutive memory locations. This is valid only in conjunction with theBY_REFERENCE
flag.
Constructors
The GeometryArray object has the following constructors:public GeometryArray(int vertexCount, int vertexFormat)Constructs an empty GeometryArray object with the specified vertex format and number of vertices. ThevertexCount
parameter specifies the number of vertex elements in this array. ThevertexFormat
parameter is a mask indicating which vertex components are present in each vertex. The vertex format is specified as a set of flags that are bitwise ORed together to describe the per-vertex data. The following vertex formats are supported:
COORDINATES
: Specifies that this vertex array contains coordinates. This bit must be set.
NORMALS
: Specifies that this vertex array contains normals.
COLOR_3
: Specifies that this vertex array contains colors without alpha. Colors are specified as floating-point values in the range [0.0, 1.0].
COLOR_4
: Specifies that this vertex array contains colors with alpha. Colors are specified as floating-point values in the range [0.0, 1.0]. This takes precedence overCOLOR_3
.
TEXTURE_COORDINATE_2
: Specifies that this vertex array contains 2D texture coordinates (S and T).
TEXTURE_COORDINATE_3
: Specifies that this vertex array contains 3D texture coordinates (S, T, and R). This takes precedence overTEXTURE_COORDINATE_2
.
BY_REFERENCE
: Indicates that the data is passed by reference rather than by copying.The GeometryArray object is constructed with the following default values:
INTERLEAVED
: Indicates that the referenced data is interleaved in a single array.
public GeometryArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap)Constructs an empty GeometryArray object with the specified number of vertices, vertex format, number of texture coordinate sets, and texture coordinate mapping array. Defaults are used for all other parameters.
Methods
GeometryArray methods provide access (get
andset
methods) to individual vertex component arrays in two different modes: as individual elements or as arrays of multiple elements.public int getVertexCount()Retrieves the number of vertices in the GeometryArray.public int getVertexFormat()Retrieves the vertex format of the GeometryArray.public void updateData(GeometryUpdater updater)This method updates geometry array data that is accessed by reference. This method calls the updateData method of the specified GeometryUpdater object to synchronize updates to vertex data that is referenced by this GeometryArray object. Applications that wish to modify such data must perform all updates via this method.public void setValidVertexCount(int validVertexCount) public int getValidVertexCount()Sets or retrieves the valid vertex count for this GeometryArray object. This count specifies the number of vertices actually used in rendering or other operations such as picking and collision. This attribute is initialized tovertexCount
.public void setInitialVertexIndex(int initialVertexIndex) public int getInitialVertexIndex()Sets or retrieves the initial vertex index for this GeometryArray object. This index specifies the first vertex within this geometry array that is actually used in rendering or other operations such as picking and collision. This attribute is initialized to 0. This attribute is used only when the data mode for this geometry array object is notBY_REFERENCE
.public void setCoordinate(int index, float coordinate[]) public void getCoordinate(int index, float coordinate[]) public void setCoordinate(int index, double coordinate[]) public void getCoordinate(int index, double coordinate[])Sets or retrieves the coordinate associated with the vertex at the specifiedindex
of this object. Theindex
parameter is the vertex index in this geometry array. Thecoordinate
parameter is an array of three values containing the new coordinate.public void setCoordinate(int index, Point3f coordinate) public void getCoordinate(int index, Point3f coordinate) public void setCoordinate(int index, Point3d coordinate) public void getCoordinate(int index, Point3d coordinate)Sets or retrieves the coordinate associated with the vertex at the specifiedindex
. Theindex
parameter is the vertex index in this geometry array. Thecoordinate
parameter is a vector containing the new coordinate.public void setCoordinates(int index, float coordinates[]) public void getCoordinates(int index, float coordinates[]) public void setCoordinates(int index, double coordinates[]) public void getCoordinates(int index, double coordinates[])Sets or retrieves the coordinates associated with the vertices starting at the specifiedindex
. Theindex
parameter is the starting vertex index in this geometry array. Thecoordinates
parameter is an array of 3n values containing n new coordinates. The length of thecoordinates
array determines the number of vertices copied.public void setCoordinates(int index, Point3f coordinates[]) public void getCoordinates(int index, Point3f coordinates[]) public void setCoordinates(int index, Point3d coordinates[]) public void getCoordinates(int index, Point3d coordinates[])Sets or retrieves the coordinates associated with the vertices starting at the specifiedindex
. Theindex
parameter is the starting vertex index in this geometry array. Thecoordinates
parameter is an array of points containing new coordinates. The length of thecoordinates
array determines the number of vertices copied.public void setCoordinates(int index, Point3d coordinates[], int start, int length) public void setCoordinates(int index, Point3f coordinates[], int start, int length) public void setCoordinates(int index, float coordinates[], int start, int length) public void setCoordinates(int index, double coordinates[], int start, int length)These methods set the coordinates associated with the vertices starting at the specified index for this object, using coordinate data starting from vertex indexstart
forlength
vertices. Theindex
parameter is the starting destination vertex index in this geometry array.public void setColor(int index, float color[]) public void getColor(int index, float color[]) public void setColor(int index, byte color[]) public void getColor(int index, byte color[])Sets or retrieves the color associated with the vertex at the specified index. Theindex
parameter is the vertex index in this geometry array. Thecolor
parameter is an array of three or four values containing the new color.public void setColor(int index, Color3f color) public void getColor(int index, Color3f color) public void setColor(int index, Color4f color) public void getColor(int index, Color4f color) public void setColor(int index, Color3b color) public void getColor(int index, Color3b color) public void setColor(int index, Color4b color) public void getColor(int index, Color4b color)Sets or retrieves the color associated with the vertex at the specified index. Theindex
parameter is the vertex index in this geometry array. Thecolor
parameter is a vector containing the new color.public void setColors(int index, float colors[]) public void getColors(int index, float colors[]) public void setColors(int index, byte colors[]) public void getColors(int index, byte colors[])Sets or retrieves the colors associated with the vertices starting at the specified index. Theindex
parameter is the starting vertex index in this geometry array. Thecolors
parameter is an array of 3n or 4n values containing n new colors. The length of thecolors
array determines the number of vertices copied.public void setColors(int index, Color3f colors[]) public void getColors(int index, Color3f colors[]) public void setColors(int index, Color4f colors[]) public void getColors(int index, Color4f colors[]) public void setColors(int index, Color3b colors[]) public void getColors(int index, Color3b colors[]) public void setColors(int index, Color4b colors[]) public void getColors(int index, Color4b colors[])Sets or retrieves the colors associated with the vertices starting at the specified index. Theindex
parameter is the starting vertex index in this geometry array. Thecolors
parameter is an array of vectors containing the new colors. The length of thecolors
array determines the number of vertices copied.public void setColors(int index, float colors[], int start, int length) public void setColors(int index, byte colors[], int start, int length)These methods set the colors associated with the vertices starting at the specified index for this object, using data incolors
starting at indexstart
forlength
colors. Theindex
parameter is the starting destination vertex index in this geometry array. Thecolors
parameter is an array of 3n or 4n values containing n new colors.public void setColors(int index, Color3f colors[], int start, int length) public void setColors(int index, Color4f colors[], int start, int length) public void setColors(int index, Color3b colors[], int start, int length) public void setColors(int index, Color4b colors[], int start, int length)These methods set the colors associated with the vertices starting at the specified index for this object, using data incolors
starting at indexstart
forlength
colors. Theindex
parameter is the starting destination vertex index in this geometry array. Thecolors
parameter is an array of vectors containing new colors.public void setNormal(int index, float normal[]) public void getNormal(int index, float normal[])Sets or retrieves the normal associated with the vertex at the specified index. Theindex
parameter is the vertex index in this geometry array. Thenormal
parameter is the new normal.public void setNormal(int index, Vector3f normal) public void getNormal(int index, Vector3f normal)Sets or retrieves the normal associated with the vertex at the specified index. Theindex
parameter is the vertex index in this geometry array. Thenormal
parameter is a vector containing the new normal.public void setNormals(int index, float normals[]) public void getNormals(int index, float normals[])Sets or retrieves the normals associated with the vertices starting at the specified index. Theindex
parameter is the starting vertex index in this geometry array. Thenormals
parameter is an array of 3n values containing n new normals. The length of thenormals
array determines the number of vertices copied.public void setNormals(int index, Vector3f normals[]) public void getNormals(int index, Vector3f normals[])Sets or retrieves the normals associated with the vertices starting at the specified index. Theindex
parameter is the starting vertex index in this geometry array. Thenormals
parameter is an array of vectors containing new normals. The length of thenormals
array determines the number of vertices copied.public void setNormals(int index, float normals[], int start, int length) public void setNormals(int index, Vector3f normals[], int start, int length)These methods set the normals associated with the vertices starting at the specified index for this object, using data innormals
starting at indexstart
and ending at indexstart+length
. Theindex
parameter is the starting destination vertex index in this geometry array.public int getTexCoordSetCount()This method retrieves the number of texture coordinate sets in this Geometry-Array object.public int getTexCoordSetMapLength()This method retrieves the length of the texture coordinate set mapping array of this GeometryArray object.public void getTexCoordSetMap(int[] texCoordSetMap)This method retrieves the texture coordinate set mapping array from this GeometryArray object.public void setTextureCoordinate(int texCoordSet, int index, float[] texCoord) public void setTextureCoordinate(int texCoordSet, int index, TexCoord2f texCoord) public void setTextureCoordinate(int texCoordSet, int index, TexCoord3f texCoord) public void getTextureCoordinate(int texCoordSet, int index, float[] texCoord) public void getTextureCoordinate(int texCoordSet, int index, TexCoord2f texCoord) public void getTextureCoordinate(int texCoordSet, int index, TexCoord3f texCoord)These methods set and retrieve the texture coordinate associated with the vertex at the specified index in the specified texture coordinate set for this object.public void setTextureCoordinates(int texCoordSet, int index, float[] texCoords) public void setTextureCoordinates(int texCoordSet, int index, TexCoord2f[] texCoords) public void setTextureCoordinates(int texCoordSet, int index, TexCoord3f[] texCoords) public void getTextureCoordinates(int texCoordSet, int index, float[] texCoords) public void getTextureCoordinates(int texCoordSet, int index, TexCoord2f[] texCoords) public void getTextureCoordinates(int texCoordSet, int index, TexCoord3f[] texCoords)These methods set and retrieve the texture coordinates associated with the vertices starting at the specified index in the specified texture coordinate set for this object. The set methods copy the entire source array to this geometry array. For the get methods, the length of the destination array determines the number of texture coordinates copied.public void setTextureCoordinates(int texCoordSet, int index, float[] texCoords, int start, int length) public void setTextureCoordinates(int texCoordSet, int index, TexCoord2f[] texCoords, int start, int length) public void setTextureCoordinates(int texCoordSet, int index, TexCoord3f[] texCoords, int start, int length)These methods set and retrieve the texture coordinates associated with the vertices starting at the specified index in the specified texture coordinate set for this object using data in texCoords starting at index start and ending at index start+length.public void setTextureCoordinate(int index, float texCoord[]) public void getTextureCoordinate(int index, float texCoord[]) public void setTextureCoordinate(int index, Point2f texCoord) public void getTextureCoordinate(int index, Point2f texCoord) public void setTextureCoordinate(int index, Point3f texCoord) public void getTextureCoordinate(int index, Point3f texCoord) public void setTextureCoordinates(int index, float texCoords[]) public void getTextureCoordinates(int index, float texCoords[]) public void setTextureCoordinates(int index, Point2f texCoords[]) public void getTextureCoordinates(int index, Point2f texCoords[]) public void setTextureCoordinates(int index, Point3f texCoords[]) public void getTextureCoordinates(int index, Point3f texCoords[]) public void setTextureCoordinates(int index, float texCoords[], int start, int length) public void setTextureCoordinates(int index, Point2f texCoords[], int start, int length) public void setTextureCoordinates(int index, Point3f texCoords[], int start, int length)These methods are deprecated in Java 3D version 1.2.public void setInitialCoordIndex(int initialCoordIndex) public int getInitialCoordIndex()Sets or retrieves the initial coordinate index for this GeometryArray object. This index specifies the first coordinate within the array of coordinates referenced by this geometry array that is actually used in rendering or in other operations such as picking and collision. This attribute is initialized to 0. This attribute is used only when the data mode for this geometry array object isBY_REFERENCE
.public void setInitialColorIndex(int initialColorIndex) public int getInitialColorIndex()Sets or retrieves the initial color index for this GeometryArray object. This index specifies the first color within the array of colors referenced by this geometry array that is actually used in rendering or other operations such as picking and collision. This attribute is initialized to 0. This attribute is used only when the data mode for this geometry array object isBY_REFERENCE
.public void setInitialNormalIndex(int initialNormalIndex) public int getInitialNormalIndex()Sets or retrieves the initial normal index for this GeometryArray object. This index specifies the first normal within the array of normals referenced by this geometry array that is actually used in rendering or other operations such as picking and collision. This attribute is initialized to 0. This attribute is used only when the data mode for this geometry array object isBY_REFERENCE
.public void setInitialTexCoordIndex(int texCoordSet, int initialTexCoordIndex) public int getInitialTexCoordIndex(int texCoordSet)Sets or retrieves the initial texture coordinate index for the specified texture coordinate set for this GeometryArray object. This index specifies the first texture coordinate within the array of texture coordinates referenced by this geometry array that is actually used in rendering or other operations such as picking and collision. This attribute is initialized to 0. This attribute is used only when the data mode for this geometry array object isBY_REFERENCE
.public void setCoordRefFloat(float[] coords) public float[] getCoordRefFloat() public void setCoordRefDouble(double[] coords) public double[] getCoordRefDouble()Sets or retrieves the coordinate array reference to the specified array. The array contains x, y, and z values for each vertex (for a total of 3*n values, where n is the number of vertices). Only one ofcoordRefFloat
,coordRefDouble
,coordRef3f
, orcoordRef3d
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all coordinate array references are null, the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setCoordRef3f(Point3f[] coords) public Point3f[] getCoordRef3f() public void setCoordRef3d(Point3d[] coords) public Point3d[] getCoordRef3d()Sets or retrieves the coordinate array reference to the specified array. The array contains a Point3f or Point3d object for each vertex. Only one ofcoordRefFloat
,coordRefDouble
,coordRef3f
, orcoordRef3d
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all coordinate array references are null, the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setColorRefFloat(float[] colors) public float[] getColorRefFloat() public void setColorRefByte(byte[] colors) public byte[] getColorRefByte()Sets or retrieves the color array reference to the specified array. The array contains red, green, blue, and, optionally, alpha values for each vertex (for a total of 3*n or 4*n values, where n is the number of vertices). Only one ofcolorRefFloat
,colorRefByte
,colorRef3f
,colorRef4f
,colorRef3b
, orcolorRef4b
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all color array references are null and colors are enabled (that is, the vertexFormat includes eitherCOLOR_3
orCOLOR_4
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setColorRef3f(Color3f[] colors) public Color3f[] getColorRef3f() public void setColorRef4f(Color4f[] colors) public Color4f[] getColorRef4f() public void setColorRef3b(Color3b[] colors) public Color3b[] getColorRef3b() public void setColorRef4b(Color4b[] colors) public Color4b[] getColorRef4b()Sets or retrieves the color array reference to the specified array. The array contains a Color 3f, Color4f, Color3b, or Color4b object for each vertex. Only one ofcolorRefFloat
,colorRefByte
,colorRef3f
,colorRef4f
,colorRef3b
, orcolorRef4b
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all color array references are null and colors are enabled (that is, the vertexFormat includes eitherCOLOR_3
orCOLOR_4
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setNormalRefFloat(float[] normals) public float[] getNormalRefFloat()Sets or retrieves the float normal array reference to the specified array. The array contains floating-point nx, ny, and nz values for each vertex (for a total of 3*n values, where n is the number of vertices). Only one ofnormalRefFloat
ornormalRef3f
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all normal array references are null and normals are enabled (that is, the vertexFormat includesNORMAL
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setNormalRef3f(Vector3f[] normals) public Vector3f[] getNormalRef3f()Sets or retrieves the normal array reference to the specified array. The array contains a Vector3f object for each vertex. Only one ofnormalRefFloat
ornormalRef3f
may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all normal array references are null and normals are enabled (that is, the vertexFormat includesNORMAL
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setTexCoordRefFloat(int texCoordSet, float[] texCoords) public float[] getTexCoordRefFloat(int texCoordSet)Sets or retrieves the float texture coordinate array reference for the specified texture coordinate set to the specified array. The array contains floating-point s, t, and, optionally, r values for each vertex (for a total of 2*n or 3*n values, where n is the number of vertices). Only one oftexCoordRefFloat
,texCoordRef2f
, or texCoordRef3f may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all texCoord array references are null and texture coordinates are enabled (that is, the vertexFormat includes eitherTEXTURE_COORDINATE_2
orTEXTURE_COORDINATE_3
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setTexCoordRef2f(int texCoordSet, TexCoord2f[] texCoords) public TexCoord2f[] getTexCoordRef2f(int texCoordSet) public void setTexCoordRef3f(int texCoordSet, TexCoord3f[] texCoords) public TexCoord3f[] getTexCoordRef3f(int texCoordSet)Sets the texture coordinate array reference for the specified texture coordinate set to the specified array. The array contains a TexCoord2f or TexCoord3f object for each vertex. Only one oftexCoordRefFloat
,texCoordRef2f
, or texCoordRef3f may be non-null (or they may all be null). An attempt to set more than one of these attributes to a non-null reference will result in an exception being thrown. If all texCoord array references are null and texture coordinates are enabled (that is, the vertexFormat includes eitherTEXTURE_COORDINATE_2
orTEXTURE_COORDINATE_3
), the entire geometry array object is treated as if it were null-any Shape3D or Morph node that uses this geometry array will not be drawn.public void setInterleavedVertices(float[] vertexData) public float[] getInterleavedVertices()Sets or retrieves the interleaved vertices array reference to the specified array. The vertex components must be stored in a predetermined order in the array. The order is texture coordinates, colors, normals, and positional coordinates. Only those components that are enabled appear in the vertex. The number of words per vertex depends on which vertex components are enabled. Texture coordinates, if enabled, use two words per vertex forTEXTURE_COORDINATE_2
or three words per vertex forTEXTURE_COORDINATE_3
. Colors, if enabled, use three words per vertex forCOLOR_3
or four words per vertex forCOLOR_4
. Normals, if enabled, use three words per vertex. Positional coordinates, which are always enabled, use three words per vertex. For example, the format of interleaved data for a GeometryArray object whose vertexFormat includesCOORDINATES
,COLOR_3
, andNORMALS
would be red, green, blue, Nx, Ny, Nz, x, y, z. All components of a vertex are stored in adjacent memory locations. The first component of vertex 0 is stored beginning at index 0 in the array. The first component of vertex 1 is stored beginning at index words_per_vertex in the array. The total number of words needed to store n vertices is words_per_vertex*n.
8.2.2
The GeometryUpdater interface is used in updating geometry data that is accessed by reference from a live or compiled GeometryArray object (see Section 8.2.1, "GeometryArray Object"). Applications that wish to modify such data must define a class that implements this interface. An instance of that class is then passed to theGeometryUpdater Interface updateData
method of the GeometryArray object to be modified.public void updateData(Geometry geometry)This method updates geometry data that is accessed by reference. This method is called by theupdateData
method of a GeometryArray object to effect safe updates to vertex data that is referenced by that object. Applications that wish to modify such data must implement this method and perform all updates within it.
Note: Applications should not call this method directly.
8.2.3
The PointArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual points.PointArray Object public PointArray(int vertexCount, int vertexFormat)Constructs an empty PointArray object with the specified vertex format and number of vertices.public PointArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap)Constructs an empty PointArray object with the specified number of vertices, vertex format, number of texture coordinate sets, and texture coordinate mapping array.
8.2.4
The LineArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual line segments. Each pair of vertices defines a line segment to be drawn.LineArray Object public LineArray(int vertexCount, int vertexFormat)Constructs an empty LineArray object with the specified vertex format and number of vertices.public LineArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap)Constructs an empty LineArray object with the specified number of vertices, vertex format, number of texture coordinate sets, and texture coordinate mapping array.
8.2.5
The TriangleArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual triangles. Each group of three vertices defines a triangle to be drawn.TriangleArray Object public TriangleArray(int vertexCount, int vertexFormat)Constructs an empty TriangleArray object with the specified vertex format and number of vertices.public TriangleArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap)Constructs an empty TriangleArray object with the specified number of vertices, vertex format, number of texture coordinate sets, and texture coordinate mapping array.
8.2.6
The QuadArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual quadrilaterals. Each group of four vertices defines a quadrilateral to be drawn. A quadrilateral must be planar and convex or results are undefined. A quadrilateral may be rendered as a pair of triangles with either diagonal line arbitrarily chosen to split the quad.QuadArray Object public QuadArray(int vertexCount, int vertexFormat)Constructs an empty QuadArray object with the specified vertex format and number of vertices.public QuadArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap)Constructs an empty QuadArray object with the specified number of vertices, vertex format, number of texture coordinate sets, and texture coordinate mapping array.
8.2.7
GeometryStripArray is an abstract class from which all strip primitives (line strip, triangle strip, and triangle fan) are derived. In addition to specifying the array of vertex elements, which is inherited from GeometryArray, the GeometryStripArray class specifies an array of per-strip vertex counts that specifies where the separate strips appear in the vertex array.GeometryStripArray Object
Constructors
The GeometryStripArray object has the following constructors:public GeometryStripArray(int vertexCount, int vertexFormat, int stripVertexCounts[])Constructs an empty GeometryStripArray object with the specified number of vertices, vertex format, and an array of vertex counts per strip. ThevertexCount
parameter specifies the number of vertex elements in this array.public GeometryStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int[] stripVertexCounts)Constructs an empty GeometryStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and array of per-strip vertex counts.
Methods
The GeometryStripArray object has the following methods:public int getNumStrips()This method returns the number of strips in the GeometryStripArray.public void getStripVertexCounts(int stripVertexCounts[])This method gets an array containing a list of vertex counts for each strip.
8.2.8
The LineStripArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected line strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the second vertex in the array, defines a line segment to be drawn from the previous vertex to the current vertex.LineStripArray Object public LineStripArray(int vertexCount, int vertexFormat, int stripVertexCounts[])Constructs an empty LineStripArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.public LineStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int[] stripVertexCounts)Constructs an empty LineStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and array of per-strip vertex counts.
8.2.9
The TriangleStripArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex and the two previous vertices.TriangleStripArray Object public TriangleStripArray(int vertexCount, int vertexFormat, int stripVertexCounts[])Constructs an empty TriangleStripArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.public TriangleStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int[] stripVertexCounts)Constructs an empty TriangleStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and array of per-strip vertex counts.
8.2.10
The TriangleFanArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle fans. An array of per-strip vertex counts specifies where the separate strips (fans) appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex, the previous vertex, and the first vertex. This can be thought of as a collection of convex polygons.TriangleFanArray Object public TriangleFanArray(int vertexCount, int vertexFormat, int stripVertexCounts[])Constructs an empty TriangleFanArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.public TriangleFanArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int[] stripVertexCounts)Constructs an empty TriangleFanArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and array of per-strip vertex counts.
8.2.11
An IndexedGeometryArray object is an abstract class that extends Geometry-Array to allow vertex data to be accessed via a level of indirection. In addition to the separate arrays of coordinates, colors, normals, and texture coordinates-inherited from GeometryArray-an IndexedGeometryArray object adds corresponding arrays of coordinate indices, color indices, normal indices, and texture coordinate indices.IndexedGeometryArray Object
Constants
The IndexedGeometryArray object defines the following flags:public static final int ALLOW_COORDINATE_INDEX_READ public static final int ALLOW_COORDINATE_INDEX_WRITEThese flags specify that the IndexedGeometryArray object allows reading or writing of the array of coordinate indices.public static final int ALLOW_COLOR_INDEX_READ public static final int ALLOW_COLOR_INDEX_WRITEThese flags specify that the IndexedGeometryArray object allows reading or writing of the array of color indices.public static final int ALLOW_NORMAL_INDEX_READ public static final int ALLOW_NORMAL_INDEX_WRITEThese flags specify that the IndexedGeometryArray object allows reading or writing of the array of normal indices.public static final int ALLOW_TEXCOORD_INDEX_READ public static final int ALLOW_TEXCOORD_INDEX_WRITEThese flags specify that the IndexedGeometryArray object allows reading or writing of the array of texture coordinate indices.
Constructors
The IndexedGeometryArray object has two constructors that accept the same parameters as GeometryArray.public IndexedGeometryArray(int vertexCount, int vertexFormat, int indexCount)Constructs an empty IndexedGeometryArray object with the specified number of vertices, vertex format, and number of indices. The index values in each of the four index arrays (coordinates, colors, normals, and texture coordinates) are all initialized to 0.public IndexedGeometryArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount)Constructs an empty IndexedGeometryArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and number of indices. The index values in each of the four index arrays (coordinates, colors, normals, and texture coordinates) are all initialized to zero.
Methods
IndexedGeometryArray methods provide access (get
andset
methods) to the individual vertex component index arrays that are used when rendering the geometry. This access is allowed in two different modes: as individual index elements or as arrays of multiple index elements.public void setCoordinateIndex(int index, int coordinateIndex) public int getCoordinateIndex(int index)Sets or retrieves the coordinate index associated with the vertex at the specified index.public void setCoordinateIndices(int index, int coordinateIndices[]) public void getCoordinateIndices(int index, int coordinateIndices[])Sets or retrieves the coordinate indices associated with the vertices starting at the specified index.public void setColorIndex(int index, int colorIndex) public int getColorIndex(int index)Sets or retrieves the color index associated with the vertex at the specified index.public void setColorIndices(int index, int colorIndices[]) public void getColorIndices(int index, int colorIndices[])Sets or retrieves the color indices associated with the vertices starting at the specified index.public void setNormalIndex(int index, int normalIndex) public int getNormalIndex(int index)Sets or retrieves the normal index associated with the vertex at the specified index.public void setnormalIndices(int index, int normalIndices[]) public void getNormalIndices(int index, int normalIndices[])Sets or retrieves the normal indices associated with the vertices starting at the specified index.public void setTextureCoordinateIndex(int texCoordSet, int index, int texCoordIndex) public int getTextureCoordinateIndex(int texCoordSet, int index)These methods set and retrieve the texture coordinate index associated with the vertex at the specified index in the specified texture coordinate set for this object.public void setTextureCoordinateIndices(int texCoordSet, int index, int[] texCoordIndices) public void getTextureCoordinateIndices(int texCoordSet, int index, int[] texCoordIndices)These methods set and retrieve the texture coordinate indices associated with the vertices starting at the specified index in the specified texture coordinate set for this object.public void setTextureCoordinateIndex(int index, int texCoordIndex) public int getTextureCoordinateIndex(int index) public void setTextureCoordinateIndices(int index, int texCoordIndices[]) public void getTextureCoordinateIndices(int index, int texCoordIndices[])These methods are deprecated in Java 3D version 1.2.public int getIndexCount()Retrieves the number of indices for this IndexedGeometryArray.
8.2.12
The IndexedPointArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual points.IndexedPointArray Object
Constructors
The IndexedPointArray object has the following constructors:public IndexedPointArray(int vertexCount, int vertexFormat, int indexCount)Constructs an empty IndexedPointArray object with the specified number of vertices, vertex format (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats), and the number of indices in this array.public IndexedPointArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount)Constructs an empty IndexedPointArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and number of indices.
8.2.13
The IndexedLineArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual line segments. Each pair of vertices defines a line segment to be drawn.IndexedLineArray Object
Constructors
The IndexedLineArray object has the following constructors:public IndexedLineArray(int vertexCount, int vertexFormat, int indexCount)Constructs an empty IndexedLineArray object with the specified number of vertices, vertex format, and the number of indices in this array. ThevertexFormat
is a mask indicating which components are present in each vertex (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats).public IndexedLineArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount)Constructs an empty IndexedLineArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and number of indices.
8.2.14
The IndexedTriangleArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual triangles. Each group of three vertices defines a triangle to be drawn.IndexedTriangleArray Object
Constructors
The IndexedTriangleArray object has the following constructors:public IndexedTriangleArray(int vertexCount, int vertexFormat, int indexCount)Constructs an empty IndexedTriangleArray object with the specified number of vertices, vertex format, and the number of indices in this array. ThevertexFormat
is a mask indicating which components are present in each vertex (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats).public IndexedTriangleArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount)Constructs an empty IndexedTriangleArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and number of indices.
8.2.15
The IndexedQuadArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual quadrilaterals. Each group of four vertices defines a quadrilateral to be drawn. A quadrilateral must be planar and convex or results are undefined. A quadrilateral may be rendered as a pair of triangles with either diagonal line arbitrarily chosen to split the quad.IndexedQuadArray Object
Constructors
The IndexedQuadArray object has the following constructors:public IndexedQuadArray(int vertexCount, int vertexFormat, int indexCount)Constructs an empty IndexedQuadArray object with the specified number of vertices, vertex format (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats), and the number of indices in this array.public IndexedQuadArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount)Constructs an empty IndexedQuadArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, and number of indices.
8.2.16
IndexedGeometryStripArray is an abstract class from which all strip primitives (line strip, triangle strip, and triangle fan) are derived. In addition to specifying the array of vertex elements, which is inherited from IndexedGeometryArray, the IndexedGeometryArrayStrip class specifies an array of per-strip index counts that specifies where the separate strips appear in the indexed vertex array.IndexedGeometryStripArray Object
Constructors
The IndexedGeometryStripArray object has the following constructors:public IndexedGeometryStripArray(int vertexCount, int vertexFormat, int indexCount, int stripIndexCounts[])Constructs an empty IndexedGeometryStripArray object with the specified number of vertices, vertex format, number of indices in the array, and an array of index counts per strip. ThevertexCount
parameter specifies the number of vertex elements in this array. ThevertexFormat
parameter is a mask indicating which vertex components are present in each vertex. TheindexCount
parameter specifies the number of indices in this array. ThestripIndexCounts
parameter is an array that specifies the count of the number of indices for each separate strip. The length of this array specifies the number of separate strips. The sum of the index counts for all strips, as specified by thestripIndexCounts
array, must equal the total count of all indices as specified by theindexCount
parameter.public IndexedGeometryStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount, int[] stripIndexCounts)Constructs an empty IndexedGeometryStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, number of indices, and array of per-strip index counts.
Methods
The IndexedGeometryArrayStrip object has the following methods:public int getNumStrips()Gets the number of strips in the IndexedGeometryStripArray.public void getStripIndexCounts(int stripIndexCounts[])Gets a list of theindexCounts
for each strip.
8.2.17
The IndexedLineStripArray extends IndexedGeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected line strips. An array of per-strip index counts specifies where the separate strips appear in the indexed vertex array. For every strip in the set, each vertex, beginning with the second vertex in the array, defines a line segment to be drawn from the previous vertex to the current vertex.IndexedLineStripArray Object
Constructors
The IndexedLineStripArray object has the following constructors:public IndexedLineStripArray(int vertexCount, int vertexFormat, int indexCount, int stripIndexCounts[])Constructs an empty IndexedLineStrip object with the specified number of vertices, vertex format, number of indices in this array, and an array that specifies the number of indices for each strip. ThevertexFormat
parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats).public IndexedLineStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount, int[] stripIndexCounts)Constructs an empty IndexedLineStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, number of indices, and array of per-strip index counts.
8.2.18
The IndexedTriangleStripArray extends IndexedGeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle strips. An array of per-strip index counts specifies where the separate strips appear in the indexed vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex and the two previous vertices.IndexedTriangleStripArray Object
Constructors
The IndexedTriangleStripArray object has the following constructors:public IndexedTriangleStripArray(int vertexCount, int vertexFormat, int indexCount, int stripIndexCounts[])Constructs an empty IndexedTriangleStripArray object with the specified number of vertices, vertex format, number of indices in this array, and an array of index counts per strip. ThevertexFormat
parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats).public IndexedTriangleStripArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount, int[] stripIndexCounts)Constructs an empty IndexedTriangleStripArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, number of indices, and array of per-strip index counts.
8.2.19
The IndexedTriangleFanArray extends IndexedGeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle fans. An array of per-strip index counts specifies where the separate strips (fans) appear in the indexed vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex, the previous vertex, and the first vertex. This can be thought of as a collection of convex polygons.IndexedTriangleFanArray Object
Constructors
The IndexedTriangleFanArray object has the following constructors:public IndexedTriangleFanArray(int vertexCount, int vertexFormat, int indexCount, int stripIndexCounts[])Constructs an empty IndexedTriangleFanArray object with the specified number of vertices, vertex format, number of indices in this array, and an array of index counts per strip. ThevertexFormat
parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 8.2.1, "GeometryArray Object," for a description of the supported vertex formats).public IndexedTriangleFanArray(int vertexCount, int vertexFormat, int texCoordSetCount, int[] texCoordSetMap, int indexCount, int[] stripIndexCounts)Constructs an empty IndexedTriangleFanArray object with the specified number of vertices, vertex format, number of texture coordinate sets, texture coordinate mapping array, number of indices, and array of per-strip index counts.
8.2.20
The CompressedGeometry object is used to store geometry in a compressed format. CompressedGeometry objects use a special format for representing geometric information in one order of magnitude less space. The representation, though lossy, preserves significant object quality during compression. There will be parameters to allow the user to specify the degree of lossy-ness (for example, a space versus quality knob).CompressedGeometry Object For more information, see Appendix B, "3D Geometry Compression."
- By copying: The existing CompressedGeometry constructor copies the buffer of compressed geometry data into this CompressedGeometry object. This is appropriate for many applications and allows Java 3D to verify the data once and then not to worry about it again.
- By reference: A new constructor and set of methods in Java 3D version 1.2 allows compressed geometry data to be accessed by reference, directly from the user's array. To use this feature, you need to construct a CompressedGeometry object with the
byReference
flag set totrue
. In this mode, a reference to the input data is saved, but the data itself is not necessarily copied. Note that the compressed geometry header is still copied into this compressed geometry object. Data referenced by a CompressedGeometry object must not be modified after the CompressedGeometry object has been constructed. Applications must exercise care not to violate this rule. If any referenced compressed geometry data is modified after construction, the results are undefined.Constants
The CompressedGeometry object specifies the following variables:public static final int ALLOW_COUNT_READ public static final int ALLOW_HEADER_READ public static final int ALLOW_GEOMETRY_READThese flags, when enabled using thesetCapability
method, allow an application to invoke methods that read its individual component field information.public static final int ALLOW_REF_DATA_READThis flag specifies that this CompressedGeometry allows reading the geometry data reference information for this object. This is used only in by-reference geometry mode.public CompressedGeometry(CompressedGeometryHeader hdr, byte geometry[])Constructs a CompressedGeometry NodeComponent by copying the specified compressed geometry data into this object. Thehdr
field is copied into the CompressedGeometry object. Thegeometry
parameter must conform to the compressed geometry format as described in Appendix B, "3D Geometry Compression." If the version number of compressed geometry, as specified by the CompressedGeometryHeader, is incompatible with the supported version of compressed geometry in the current version of Java 3D, the compressed geometry object will not be rendered.public CompressedGeometry(CompressedGeometryHeader hdr, byte[] compressedGeometry, boolean byReference)Creates a new CompressedGeometry NodeComponent. The specified compressed geometry data is either copied into this object or accessed by reference. If the version number of compressed geometry, as specified by the CompressedGeometryHeader, is incompatible with the supported version of compressed geometry in the current version of Java 3D, the compressed geometry object will not be rendered.public int getByteCount()This method retrieves the size, in bytes, of the compressed geometry buffer.public void getCompressedGeometryHeader (CompressedGeometryHeader hdr)This method retrieves the header for this CompressedGeometry object (see Section 8.2.21, "CompressedGeometryHeader Object"). The header is copied into the CompressedGeometryHeader object provided.public void getCompressedGeometry(byte compGeom[])This method retrieves the compressed geometry associated with the CompressedGeometry object. It copies the compressed geometry from the CompressedGeometry object into the given array.public byte[] getCompressedGeometryRef()This method retrieves the compressed geometry data reference with which this CompressedGeometry object was constructed. It is valid only in by-reference mode.public Shape3D[] decompress()This method decompresses the compressed geometry. It returns an array of Shape nodes containing the decompressed geometry objects.public boolean isByReference()This method retrieves the data access mode for this CompressedGeometry object.
8.2.21
The CompressedGeometryHeader object is used in conjunction with the CompressedGeometry object. The CompressedGeometryHeader object contains information specific to the compressed geometry data stored in the CompressedGeometry NodeComponent object. This header is used to aid in the processing of the compressed geometry by decompression routines. All members in the CompressedGeometryHeader node are public, so noCompressedGeometryHeader Object get
orset
routines are provided. The CompressedGeometryHeader object should be created, and all values should be set, by the geometry compression utility.public static final int POINT_BUFFER public static final int LINE_BUFFER public static final int TRIANGLE_BUFFERThese flags indicate whether the compressed geometry is made up of individual points, line segments, or triangles.public static final int COLOR_IN_BUFFER public static final int ALPHA_IN_BUFFER public static final int NORMAL_IN_BUFFERThese flags indicate whether RGB, alpha color, or normal information is initialized in the compressed geometry buffer.public int majorVersionNumber public int minorVersionNumber public int minorMinorVersionNumberThese flags indicate the major, minor, and minor-minor version numbers for the compressed geometry format that was used to compress the geometry. If the version number of compressed geometry is incompatible with the supported version of compressed geometry in the current version of Java 3D, the compressed geometry object will not be rendered.public int bufferTypeThis flag describes the type of data in the compressed geometry buffer. Only one type may be present in any given compressed geometry buffer.public int bufferDataPresentThis flag indicates whether a particular data component (for example, color) is present in the compressed geometry buffer, preceding any geometric data. If a particular data type is not present then this information will be inherited from the Appearance object.public int sizeThis flag indicates the size of the compressed geometry, in bytes, that needs to be applied to every point in the compressed geometry buffer to restore the geometry to its original (uncompressed) position.public int startThis flag contains the offset in bytes of the start of the compressed geometry from the beginning of the compressed geometry buffer.public Point3d lowerBound public Point3d upperBoundThese two flags specify two points that specify the upper and lower bounds of the x, y, and z components for all positions in the compressed geometry buffer. If null, a lower bound of (-1,-1,-1) and an upper bound of (1,1,1) is assumed. Java 3D will use this information to construct a bounding box around compressed geometry objects that are used in nodes for which the auto compute bounds flag is true. The default value for both points is null.public CompressedGeometryHeader()Creates a new CompressedGeometryHeader object used for the creation of a CompressedGeometry NodeComponent object. All instance data is declared public, and noget
orset
methods are provided. All values are set to 0 by default and must be filled in by the application.
8.2.22
The Raster object extends Geometry to allow drawing a raster image that is attached to a 3D location in the virtual world. The Raster object contains a point that is defined in the local object coordinate system of the Shape3D node that references the Raster. The Raster object also contains a type specifier, a reference to an ImageComponent2D object or a DepthComponent object, an integer x,y offset, and a size (width, height) to allow reading or writing of a portion of the referenced image. In addition to being used as a type of geometry for drawing, a Raster object may be used to read back pixel data (color and z-buffer) from the frame buffer in immediate mode.Raster Object
Constants
The Raster object defines the following flags:public static final int ALLOW_POSITION_READ public static final int ALLOW_POSITION_WRITE public static final int ALLOW_OFFSET_READ public static final int ALLOW_OFFSET_WRITE public static final int ALLOW_IMAGE_READ public static final int ALLOW_IMAGE_WRITE public static final int ALLOW_DEPTH_COMPONENT_READ public static final int ALLOW_DEPTH_COMPONENT_WRITE public static final int ALLOW_SIZE_READ public static final int ALLOW_SIZE_WRITE public static final int ALLOW_TYPE_READThese flags specify that the Raster object allows reading or writing of the position, offset, image, depth component, or size, or reading of the type.public static final int RASTER_COLORSpecifies a Raster object with color data. In this mode, the ImageComponent reference must point to a valid ImageComponent object.public static final int RASTER_DEPTHSpecifies a Raster object with depth (z-buffer) data. In this mode, the depth component reference must point to a valid DepthComponent object.public static final int RASTER_COLOR_DEPTHSpecifies a Raster object with both color and depth (z-buffer) data. In this mode, the image component reference must point to a valid ImageComponent object, and the depth component reference must point to a valid DepthComponent object.public Raster()Constructs and initializes a new Raster object with default values:
Parameter Default Value type RASTER_COLOR position (0,0,0) offset (0,0) size (0,0) image null depthComponent null
public Raster(Point3f pos, int type, int xOffset, int yOffset, int width, int height, ImageComponent2D image, DepthComponent depthComponent) public Raster(Point3f pos, int type, Point offset, Dimension size, ImageComponent2D image, DepthComponent depthComponent)Constructs and initializes a new Raster object with the specified values.public void setPosition(Point3f pos) public void getPosition(Point3f pos)These methods set and retrieve the position, in object coordinates, of this raster. This position is transformed into device coordinates and is used as the upper-left corner of the raster.public void setType(int type) public int getType()These methods set and retrieve the type of this Raster object. Thetype
is one of the following:RASTER_COLOR
,RASTER_DEPTH
, orRASTER_COLOR_DEPTH
.public void setOffset(int xOffset, int yOffset) public void setOffset(Point offset) public void getOffset(Point offset)These methods set and retrieve the offset within the array of pixels at which to start copying.public void setSize(int width, int height) public void setSize(Dimension size) public void getSize(Dimension size)These methods set and retrieve the number of pixels to be copied from the pixel array.public void setImage(ImageComponent2D image) public ImageComponent2D getImage()These methods set and retrieve the pixel array used to copy pixels to or from a Canvas3D. This is used when the type is RASTER_COLOR or RASTER_COLOR_DEPTH.public void setDepthComponent(DepthComponent depthComponent) public DepthComponent getDepthComponent()These methods set and retrieve the DepthComponent used to copy pixels to or from a Canvas3D. This is used when thetype
isRASTER_DEPTH
orRASTER_COLOR_DEPTH
.
8.2.23
The Font3D object is used to contain 3D glyphs used in rendering 3D text. These 3D glyphs are constructed from a Java 2D font object and a FontExtrusion object (see Section 8.2.24, "FontExtrusion Object"). To ensure correct rendering, the 2D font object should be created with the default transform.Font3D Object public Font3D(java.awt.Font font, FontExtrusion extrudePath)Creates a Font3D object from the specified Font and FontExtrusion objects, using the default value for the tesselation tolerance. The default value is as follows:
Parameter Default Value tesselationTolerance 0.01
The FontExtrusion object (see Section 8.2.24, "FontExtrusion Object") contains the extrusion path to use on the 2D font glyphs. To ensure correct rendering, the font must be created with the default AffineTransform. Passing in a
null
Font-Extrusion object results in no extrusion being done.public Font3D(Font font, double tessellationTolerance, FontExtrusion extrudePath)Creates a Font3D object from the specified Font and FontExtrusion objects, using the specified tessellation tolerance. The FontExtrusion object (see Section 8.2.24, "FontExtrusion Object") contains the extrusion path to use on the 2D Font glyphs. To ensure correct rendering, the font must be created with the default AffineTransform. Passing in anull
FontExtrusion object results in no extrusion being done. ThetessellationTolerance
parameter corresponds to theflatness
parameter in thejava.awt.Shape.getPathIterator
method.public void getBoundingBox(int glyphCode, BoundingBox bounds)This method returns the 3D bounding box of the specified glyph code.public Font getFont()This method returns the Java 2D font used to create this Font3D object.public void getFontExtrusion(FontExtrusion extrudePath)This method retrieves the FontExtrusion object used to create this Font3D object and copies it into the specified parameter. For information about the FontExtrusion object, see Section 8.2.24, "FontExtrusion Object."public double getTessellationTolerance()This method returns the tessellation tolerance with which this Font3D was created.
8.2.24
The FontExtrusion object is used to describe the extrusion path for a Font3D object (see Section 8.2.23, "Font3D Object"). The extrusion path is used in conjunction with a Font2D object. The extrusion path defines the edge contour of 3D text. This contour is perpendicular to the face of the text. The contour has its origin at the edge of the glyph, with 1.0 being the height of the tallest glyph. Contour must be monotonic in x. The user is responsible for data sanity and must make sure that extrusionShape does not cause intersection of adjacent glyphs or within a single glyph, otherwise undefined output may be generated.FontExtrusion Object public FontExtrusion()Creates a FontExtrusion object with default parameters. The default parameters are as follows:
Parameter Default Value extrusionShape null tesselationTolerance 0.01
A null extrusion shape specifies that a straight line from 0.0 to 0.2 (straight bevel) is used.
public FontExtrusion(java.awt.Shape extrusionShape)Creates a FontExtrusion object with the specified extrusion shape, using the default tesselation tolerance. TheextrusionShape
parameter is used to construct the edge contour of a Font3D object. Each shape begins with an implicit point at 0.0. Contour must be monotonic in x. An IllegalArgumentException is thrown if multiple contours inextrusionShape
, contour is not monotonic, or least x-value of a contour point is not 0.0f.public FontExtrusion(Shape extrusionShape, double tessellationTolerance)Creates a FontExtrusion object with the specified shape, using the specified tessellation tolerance. The specified shape is used to construct the edge contour of a Font3D object. Each shape begins with an implicit point at 0.0. Contour must be monotonic in x. ThetessellationTolerance
parameter corresponds to theflatness
parameter in thejava.awt.Shape.getPathIterator
method.public void setExtrusionShape(java.awt.Shape extrusionShape) public java.awt.Shape getExtrusionShape()These methods set and retrieve the 2D shape object associated with this FontExtrusion object. The Shape object describes the extrusion path used to create a 3D glyph from a 2D glyph. Theset
method sets the FontExtrusion's shape parameter. Theget
method gets the FontExtrusion's shape parameter.public double getTessellationTolerance()This method returns the tessellation tolerance with which this FontExtrusion was created.
8.2.25
A Text3D object is a text string that has been converted to 3D geometry. The Font3D object (see Section 8.2.23, "Font3D Object") determines the appearance of the Text3D NodeComponent object. Each Text3D object has a text position-a point in 3D space where the text should be placed. The 3D text can be placed around this position using different alignments and paths. An OrientedShape3D node may also be used for drawing screen-aligned text (see Section 6.2.1, "OrientedShape3D Node").Text3D Geometry Object
Constants
The Text3D object defines the following flags:public static final int ALLOW_FONT3D_READ public static final int ALLOW_FONT3D_WRITE public static final int ALLOW_STRING_READ public static final int ALLOW_STRING_WRITE public static final int ALLOW_POSITION_READ public static final int ALLOW_POSITION_WRITE public static final int ALLOW_ALIGNMENT_READ public static final int ALLOW_ALIGNMENT_WRITE public static final int ALLOW_PATH_READ public static final int ALLOW_PATH_WRITE public static final int ALLOW_CHARACTER_SPACING_READ public static final int ALLOW_CHARACTER_SPACING_WRITE public static final int ALLOW_BOUNDING_BOX_READThese flags control reading and writing of the Font3D component information for Font3D, the String object, the text position value, the text alignment value, the text path value, the character spacing, and the bounding box.public Text3D()Creates a new Text3D object with the following default parameters:
Parameter Default Value font3D null string null position (0,0,0) alignment ALIGN_FIRST path PATH_RIGHT characterSpacing 0.0
public Text3D(Font3D font3D) public Text3D(Font3D font3D, String string) public Text3D(Font3D font3D, String string, Point3f position) public Text3D(Font3D font3D, String string, Point3f position, int alignment, int path)Create a new Text3D object with the defined parameters.public Font3D getFont3D() public void setFont3D(Font3D font3d)These methods get and set the Font3D object associated with this Text3D object.public String getString() public void setString(String string)These methods get and set the character string associated with this Text3D object.public void getPosition(Point3f position) public void setPosition(Point3f position)These methods get and set the text position. Theposition
parameter is used to determine the initial placement of the string. The text position is used in conjunction with the alignment and path to determine how the glyphs are to be placed in the scene. The default value is (0.0, 0.0, 0.0).public void setAlignment(int alignment) public int getAlignment()These methods set and get the text alignment policy for this Text3D NodeComponent object (see Figure 8-4). Thealignment
parameter is used to specify how glyphs in the string are placed in relation to theposition
field. Valid values for the alignment field are
- ALIGN_CENTER: places the center of the string on the position point.
- ALIGN_FIRST: places the first character of the string on the position point.
The default value of this field is
- ALIGN_LAST: places the last character of the string on the position point.
ALIGN_FIRST
.public void setPath(int path) public int getPath()These methods set and get the node's path field. This field is used to specify how succeeding glyphs in the string are placed in relation to the previous glyph (see Figure 8-4). The path is relative to the local coordinate system of the Text3D node. The default coordinate system (see Section 4.4, "Coordinate Systems") is right-handed with +y being up, +x horizontal to the right, and +z directed toward the viewer. Valid values for this field are as follows:
- PATH_LEFT: places succeeding glyphs to the left (the -x direction) of the current glyph.
- PATH_RIGHT: places succeeding glyphs to the right (the +x direction) of the current glyph.
- PATH_UP: places succeeding glyphs above (the +y direction) the current glyph.
The default value of this field is
- PATH_DOWN: places succeeding glyphs below (the -y direction) the current glyph.
PATH_RIGHT
.public void getBoundingBox(BoundingBox bounds)This method retrieves the 3D bounding box that encloses this Text3D object.
Figure 8-4 Various Text Alignments and Paths
public void setCharacterSpacing(float characterSpacing) public float getCharacterSpacing()These methods set and get the character spacing used to construct the Text3D string. This spacing is in addition to the regular spacing between glyphs as defined in the Font object. A value of 1.0 in this space is measured as the width of the largest glyph in the 2D font. The default value is 0.0.
8.3
Java 3D defines a number of additional objects that are used in the construction and manipulation of other Java 3D objects. These objects provide low-level storage and manipulation control for users. They provide methods for representing vertex components (for example, color and position), volumes, vectors, and matrices.Math Component Objects The tuple and matrix math classes are not part of Java 3D per se, but they are needed by Java 3D and are defined here for convenience. Java 3D uses these classes internally and also makes them available for use by applications. These classes will be delivered in a separate
javax.vecmath
package. The tuple and matrix math classes are described in detail in Appendix A, "Math Objects."
8.3.1
The tuple objects, listed in Table 8-1, store tuples of length two, three, and four. Java 3D tuples are used to store various kinds of information such as colors, normals, texture coordinates, vertices, and so forth.Tuple Objects
These are described in more detail in Appendix A, "Math Objects."
8.3.2
The matrix objects, listed in Table 8-2, define a complete 3 x 3 or 4 x 4 floating-point transformation matrix. All the vector subclasses operate using this one matrix type.Matrix Objects
These are described in more detail in Appendix A, "Math Objects."
The Java 3D API Specification |