## javax.media.j3d
Class TexCoordGeneration

    java.lang.Object
      javax.media.j3d.SceneGraphObject
          javax.media.j3d.NodeComponent
              javax.media.j3d.TexCoordGeneration

    public class TexCoordGeneration

extends NodeComponent

The TexCoordGeneration object contains all parameters needed for automatic texture coordinate generation. It is included as part of an Appearance component object.

Texture coordinates determine which texel in the texture map is assigned to a given vertex. Texture coordinates are interpolated between vertices, similarly to how colors are interpolated between two vertices of lines and polygons.

Texture coordinates consist of two, three or four coordinates. These coordinates are referred to as the S, T, R, and Q coordinates. 2D textures use the S and T coordinates. 3D textures use the S, T and R coordinates. The Q coordinate, similar to the w coordinate of the (x, y, z, w) object coordinates, is used to create homogeneous coordinates.

Rather than the programmer having to explicitly assign texture coordinates, Java 3D can automatically generate the texture coordinates to achieve texture mapping onto contours. The TexCoordGeneration attributes specify the functions for automatically generating texture coordinates. The texture attributes that can be defined are:

- Texture format - defines whether the generated texture coordinates are 2D, 3D, or 4D:

  - TEXTURE_COORDINATE_2 - generates 2D texture coordinates (S and T).

  - TEXTURE_COORDINATE_3 - generates 3D texture coordinates (S, T, and R).

  - TEXTURE_COORDINATE_4 - generates 4D texture coordinates (S, T, R, and Q).

- Texture generation mode - defines how the texture coordinates are generated:

  - OBJECT_LINEAR - texture coordinates are generated as a linear function in object coordinates. The function used is:

    `g = p1xo + p2yo + p3zo + p4wo`

    where

    `g` is the value computed for the coordinate.
    `p1`, `p2`, `p3`, and `p4` are the plane equation coefficients (described below).
    xo, yo, zo, and wo are the object coordinates of the vertex.

  - EYE_LINEAR - texture coordinates are generated as a linear function in eye coordinates. The function used is:

    `g = p1'xe + p2'ye + p3'ze + p4'we`

    where

    `xe`, `ye`, `ze`, and we are the eye coordinates of the vertex.
    `p1'`, `p2'`, `p3'`, and `p4'` are the plane equation coefficients transformed into eye coordinates.

  - SPHERE_MAP - texture coordinates are generated using spherical reflection mapping in eye coordinates. Used to simulate the reflected image of a spherical environment onto a polygon.

  - NORMAL_MAP - texture coordinates are generated to match vertices' normals in eye coordinates. This is only available if TextureCubeMap is available.

  - REFLECTION_MAP - texture coordinates are generated to match vertices' reflection vectors in eye coordinates. This is only available if TextureCubeMap is available.

- Plane equation coefficients - defines the coefficients for the plane equations used to generate the coordinates in the OBJECT_LINEAR and EYE_LINEAR texture generation modes. The coefficients define a reference plane in either object coordinates or in eye coordinates, depending on the texture generation mode.

  The equation coefficients are set by the `setPlaneS`, `setPlaneT`, `setPlaneR`, and `setPlaneQ` methods for each of the S, T, R, and Q coordinate functions, respectively. By default the equation coefficients are set as follows:

  plane S = (1.0, 0.0, 0.0, 0.0)
  plane T = (0.0, 1.0, 0.0, 0.0)
  plane R = (0.0, 0.0, 0.0, 0.0)
  plane Q = (0.0, 0.0, 0.0, 0.0)

Texture coordinate generation is enabled or disabled by the `setEnable` method. When enabled, the specified texture coordinate is computed according to the generating function associated with the coordinate. When disabled, subsequent vertices take the specified texture coordinate from the current set of texture coordinates.

See Also:
  `Canvas3D.queryProperties()`

Field Summary
`static int` `ALLOW_ENABLE_READ` Specifies that this TexCoordGeneration object allows reading its enable flag.
`static int` `ALLOW_ENABLE_WRITE` Specifies that this TexCoordGeneration object allows writing its enable flag.
`static int` `ALLOW_FORMAT_READ` Specifies that this TexCoordGeneration object allows reading its format information.
`static int` `ALLOW_MODE_READ` Specifies that this TexCoordGeneration object allows reading its mode information.
`static int` `ALLOW_PLANE_READ` Specifies that this TexCoordGeneration object allows reading its planeS, planeR, and planeT component information.
`static int` `ALLOW_PLANE_WRITE` Specifies that this TexCoordGeneration object allows writing its planeS, planeR, and planeT component information.
`static int` `EYE_LINEAR` Generates texture coordinates as a linear function in eye coordinates.
`static int` `NORMAL_MAP` Generates texture coordinates that match vertices' normals in eye coordinates.
`static int` `OBJECT_LINEAR` Generates texture coordinates as a linear function in object coordinates.
`static int` `REFLECTION_MAP` Generates texture coordinates that match vertices' reflection vectors in eye coordinates.
`static int` `SPHERE_MAP` Generates texture coordinates using a spherical reflection mapping in eye coordinates.
`static int` `TEXTURE_COORDINATE_2` Generates 2D texture coordinates (S and T).
`static int` `TEXTURE_COORDINATE_3` Generates 3D texture coordinates (S, T, and R).
`static int` `TEXTURE_COORDINATE_4` Generates 4D texture coordinates (S, T, R, and Q).

Constructor Summary
`TexCoordGeneration()` Constructs a TexCoordGeneration object with default parameters.
`TexCoordGeneration(int genMode, int format)` Constructs a TexCoordGeneration object with the specified genMode and format.
`TexCoordGeneration(int genMode, int format, Vector4f planeS)` Constructs a TexCoordGeneration object with the specified genMode, format, and the S coordinate plane equation.
`TexCoordGeneration(int genMode, int format, Vector4f planeS, Vector4f planeT)` Constructs a TexCoordGeneration object with the specified genMode, format, and the S and T coordinate plane equations.
`TexCoordGeneration(int genMode, int format, Vector4f planeS, Vector4f planeT, Vector4f planeR)` Constructs a TexCoordGeneration object with the specified genMode, format, and the S, T, and R coordinate plane equations.
`TexCoordGeneration(int genMode, int format, Vector4f planeS, Vector4f planeT, Vector4f planeR, Vector4f planeQ)` Constructs a TexCoordGeneration object with the specified genMode, format, and the S, T, R, and Q coordinate plane equations.

Method Summary
`NodeComponent` `cloneNodeComponent()` Deprecated. replaced with cloneNodeComponent(boolean forceDuplicate)
`boolean` `getEnable()` Retrieves the state of the texCoordGeneration enable flag.
`int` `getFormat()` Retrieves the current TexCoordGeneration format.
`int` `getGenMode()` Retrieves the current TexCoordGeneration generation mode.
`void` `getPlaneQ(Vector4f planeQ)` Retrieves a copy of the plane equation used to generate the Q coordinate.
`void` `getPlaneR(Vector4f planeR)` Retrieves a copy of the plane equation used to generate the R coordinate.
`void` `getPlaneS(Vector4f planeS)` Retrieves a copy of the plane equation used to generate the S coordinate.
`void` `getPlaneT(Vector4f planeT)` Retrieves a copy of the plane equation used to generate the T coordinate.
`void` `setEnable(boolean state)` Enables or disables texture coordinate generation for this appearance component object.
`void` `setFormat(int format)` Sets the TexCoordGeneration format to the specified value.
`void` `setGenMode(int genMode)` Sets the TexCoordGeneration generation mode to the specified value.
`void` `setPlaneQ(Vector4f planeQ)` Sets the Q coordinate plane equation.
`void` `setPlaneR(Vector4f planeR)` Sets the R coordinate plane equation.
`void` `setPlaneS(Vector4f planeS)` Sets the S coordinate plane equation.
`void` `setPlaneT(Vector4f planeT)` Sets the T coordinate plane equation.

Methods inherited from class javax.media.j3d.NodeComponent
`cloneNodeComponent, duplicateNodeComponent, duplicateNodeComponent, getDuplicateOnCloneTree, setDuplicateOnCloneTree`

Methods inherited from class javax.media.j3d.SceneGraphObject
`clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString, updateNodeReferences`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### ALLOW_ENABLE_READ

    public static final int ALLOW_ENABLE_READ

  Specifies that this TexCoordGeneration object allows reading its enable flag.

  See Also:
    Constant Field Values

### ALLOW_ENABLE_WRITE

    public static final int ALLOW_ENABLE_WRITE

  Specifies that this TexCoordGeneration object allows writing its enable flag.

  See Also:
    Constant Field Values

### ALLOW_FORMAT_READ

    public static final int ALLOW_FORMAT_READ

  Specifies that this TexCoordGeneration object allows reading its format information.

  See Also:
    Constant Field Values

### ALLOW_MODE_READ

    public static final int ALLOW_MODE_READ

  Specifies that this TexCoordGeneration object allows reading its mode information.

  See Also:
    Constant Field Values

### ALLOW_PLANE_READ

    public static final int ALLOW_PLANE_READ

  Specifies that this TexCoordGeneration object allows reading its planeS, planeR, and planeT component information.

  See Also:
    Constant Field Values

### ALLOW_PLANE_WRITE

    public static final int ALLOW_PLANE_WRITE

  Specifies that this TexCoordGeneration object allows writing its planeS, planeR, and planeT component information.

  Since:
    Java 3D 1.3
  See Also:
    Constant Field Values

### OBJECT_LINEAR

    public static final int OBJECT_LINEAR

  Generates texture coordinates as a linear function in object coordinates.

  See Also:
    `setGenMode(int)`, Constant Field Values

### EYE_LINEAR

    public static final int EYE_LINEAR

  Generates texture coordinates as a linear function in eye coordinates.

  See Also:
    `setGenMode(int)`, Constant Field Values

### SPHERE_MAP

    public static final int SPHERE_MAP

  Generates texture coordinates using a spherical reflection mapping in eye coordinates.

  See Also:
    `setGenMode(int)`, Constant Field Values

### NORMAL_MAP

    public static final int NORMAL_MAP

  Generates texture coordinates that match vertices' normals in eye coordinates.

  Since:
    Java 3D 1.3
  See Also:
    `setGenMode(int)`, `Canvas3D.queryProperties()`, Constant Field Values

### REFLECTION_MAP

    public static final int REFLECTION_MAP

  Generates texture coordinates that match vertices' reflection vectors in eye coordinates.

  Since:
    Java 3D 1.3
  See Also:
    `setGenMode(int)`, `Canvas3D.queryProperties()`, Constant Field Values

### TEXTURE_COORDINATE_2

    public static final int TEXTURE_COORDINATE_2

  Generates 2D texture coordinates (S and T).

  See Also:
    `setFormat(int)`, Constant Field Values

### TEXTURE_COORDINATE_3

    public static final int TEXTURE_COORDINATE_3

  Generates 3D texture coordinates (S, T, and R).

  See Also:
    `setFormat(int)`, Constant Field Values

### TEXTURE_COORDINATE_4

    public static final int TEXTURE_COORDINATE_4

  Generates 4D texture coordinates (S, T, R, and Q).

  Since:
    Java 3D 1.3
  See Also:
    `setFormat(int)`, Constant Field Values

Constructor Detail

### TexCoordGeneration

    public TexCoordGeneration()

  Constructs a TexCoordGeneration object with default parameters. The default values are as follows:
  enable flag : true
  texture generation mode : OBJECT_LINEAR
  format : TEXTURE_COORDINATE_2
  plane S : (1,0,0,0)
  plane T : (0,1,0,0)
  plane R : (0,0,0,0)
  plane Q : (0,0,0,0)

### TexCoordGeneration

    public TexCoordGeneration(int genMode,
                              int format)

  Constructs a TexCoordGeneration object with the specified genMode and format. Defaults will be used for the rest of the state variables.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3, or TEXTURE_COORDINATE_4
  See Also:
    `Canvas3D.queryProperties()`

### TexCoordGeneration

    public TexCoordGeneration(int genMode,
                              int format,
                              Vector4f planeS)

  Constructs a TexCoordGeneration object with the specified genMode, format, and the S coordinate plane equation. Defaults will be used for the rest of the state variables.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3 or TEXTURE_COORDINATE_4
    `planeS` - plane equation for the S coordinate
  See Also:
    `Canvas3D.queryProperties()`

### TexCoordGeneration

    public TexCoordGeneration(int genMode,
                              int format,
                              Vector4f planeS,
                              Vector4f planeT)

  Constructs a TexCoordGeneration object with the specified genMode, format, and the S and T coordinate plane equations. Defaults will be used for the rest of the state variables.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3 or TEXTURE_COORDINATE_4
    `planeS` - plane equation for the S coordinate
    `planeT` - plane equation for the T coordinate
  See Also:
    `Canvas3D.queryProperties()`

### TexCoordGeneration

    public TexCoordGeneration(int genMode,
                              int format,
                              Vector4f planeS,
                              Vector4f planeT,
                              Vector4f planeR)

  Constructs a TexCoordGeneration object with the specified genMode, format, and the S, T, and R coordinate plane equations.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3 or TEXTURE_COORDINATE_4
    `planeS` - plane equation for the S coordinate
    `planeT` - plane equation for the T coordinate
    `planeR` - plane equation for the R coordinate
  See Also:
    `Canvas3D.queryProperties()`

### TexCoordGeneration

    public TexCoordGeneration(int genMode,
                              int format,
                              Vector4f planeS,
                              Vector4f planeT,
                              Vector4f planeR,
                              Vector4f planeQ)

  Constructs a TexCoordGeneration object with the specified genMode, format, and the S, T, R, and Q coordinate plane equations.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3 or TEXTURE_COORDINATE_4
    `planeS` - plane equation for the S coordinate
    `planeT` - plane equation for the T coordinate
    `planeR` - plane equation for the R coordinate
    `planeQ` - plane equation for the Q coordinate
  Since:
    Java 3D 1.3
  See Also:
    `Canvas3D.queryProperties()`

Method Detail

### setEnable

    public void setEnable(boolean state)

  Enables or disables texture coordinate generation for this appearance component object.

  Parameters:
    `state` - true or false to enable or disable texture coordinate generation
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### getEnable

    public boolean getEnable()

  Retrieves the state of the texCoordGeneration enable flag.

  Returns:
    true if texture coordinate generation is enabled, false if texture coordinate generation is disabled
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setFormat

    public void setFormat(int format)

  Sets the TexCoordGeneration format to the specified value.

  Parameters:
    `format` - texture format, one of: TEXTURE_COORDINATE_2, TEXTURE_COORDINATE_3 or TEXTURE_COORDINATE_4
  Throws:
    `RestrictedAccessException` - if the method is called when this object is part of live or compiled scene graph.

### getFormat

    public int getFormat()

  Retrieves the current TexCoordGeneration format.

  Returns:
    the texture format
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setGenMode

    public void setGenMode(int genMode)

  Sets the TexCoordGeneration generation mode to the specified value.

  Parameters:
    `genMode` - texture generation mode, one of: OBJECT_LINEAR, EYE_LINEAR, SPHERE_MAP, NORMAL_MAP, or REFLECTION_MAP.
  Throws:
    `RestrictedAccessException` - if the method is called when this object is part of live or compiled scene graph.
    `java.lang.IllegalArgumentException` - if `genMode` is a value other than `OBJECT_LINEAR`, `EYE_LINEAR`, `SPHERE_MAP`, `NORMAL_MAP`, or `REFLECTION_MAP`.
  See Also:
    `Canvas3D.queryProperties()`

### getGenMode

    public int getGenMode()

  Retrieves the current TexCoordGeneration generation mode.

  Returns:
    the texture generation mode
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setPlaneS

    public void setPlaneS(Vector4f planeS)

  Sets the S coordinate plane equation. This plane equation is used to generate the S coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes.

  Parameters:
    `planeS` - plane equation for the S coordinate
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### getPlaneS

    public void getPlaneS(Vector4f planeS)

  Retrieves a copy of the plane equation used to generate the S coordinate.

  Parameters:
    `planeS` - the S coordinate plane equation
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setPlaneT

    public void setPlaneT(Vector4f planeT)

  Sets the T coordinate plane equation. This plane equation is used to generate the T coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes.

  Parameters:
    `planeT` - plane equation for the T coordinate
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### getPlaneT

    public void getPlaneT(Vector4f planeT)

  Retrieves a copy of the plane equation used to generate the T coordinate.

  Parameters:
    `planeT` - the T coordinate plane equation
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setPlaneR

    public void setPlaneR(Vector4f planeR)

  Sets the R coordinate plane equation. This plane equation is used to generate the R coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes.

  Parameters:
    `planeR` - plane equation for the R coordinate
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### getPlaneR

    public void getPlaneR(Vector4f planeR)

  Retrieves a copy of the plane equation used to generate the R coordinate.

  Parameters:
    `planeR` - the R coordinate plane equation
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

### setPlaneQ

    public void setPlaneQ(Vector4f planeQ)

  Sets the Q coordinate plane equation. This plane equation is used to generate the Q coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes.

  Parameters:
    `planeQ` - plane equation for the Q coordinate
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
  Since:
    Java 3D 1.3

### getPlaneQ

    public void getPlaneQ(Vector4f planeQ)

  Retrieves a copy of the plane equation used to generate the Q coordinate.

  Parameters:
    `planeQ` - the Q coordinate plane equation
  Throws:
    `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
  Since:
    Java 3D 1.3

### cloneNodeComponent

    public NodeComponent cloneNodeComponent()

  Deprecated. replaced with cloneNodeComponent(boolean forceDuplicate)

  Overrides:
    `cloneNodeComponent` in class `NodeComponent`

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.