Class TextureAttributes


public class TextureAttributes extends NodeComponent
The TextureAttributes object defines attributes that apply to texture mapping. The texture attributes include the following:

  • Texture mode - defines how the object and texture colors are blended. The mode may be one of the following:
    • MODULATE - modulates the incoming color with the texture color.

        C' = C Ct
    • DECAL - applies the texture color to the incoming color as a decal.

        C'rgb = Crgb (1 - Cta) + Ctrgb Cta

        C'a = Ca

    • BLEND - blends the texture blend color with the incoming color.

        C'rgb = Crgb (1 - Ctrgb) + Cbrgb Ctrgb

        C'a = Ca Cta

      Note that if the texture format is INTENSITY, alpha is computed identically to red, green, and blue:

        C'a = Ca (1 - Cta) + Cba Cta
    • REPLACE - replaces the incoming color with the texture color.

        C' = Ct

    • COMBINE - combines the object color with the texture color or texture blend color according to the combine operation as specified in the texture combine mode.
    C = Incoming color to the texture unit state. For texture unit state 0, C is the object color Ct = Texture color
    Cb = Texture blend color

  • Combine Mode - defines the combine operation when texture mode specifies COMBINE. The combine mode includes the following:

    • COMBINE_REPLACE

        C' = C0

    • COMBINE_MODULATE

        C' = C0 C1
    • COMBINE_ADD

        C' = C0 + C1

    • COMBINE_ADD_SIGNED

        C' = C0 + C1 - 0.5

    • COMBINE_SUBTRACT

        C' = C0 - C1

    • COMBINE_INTERPOLATE

        C' = C0 C2 + C1 (1 - C2)

    • COMBINE_DOT3

        C' = 4 * ( (C0r - 0.5) * (C1r - 0.5) + (C0g - 0.5) * (C1g - 0.5) + (C0b - 0.5) * (C1b - 0.5))

        where CNx is the x component of the Nth color operand in the combine operation.

        The value C' will be placed to the all three r,g,b components or the a component of the output.

  • where C0, C1 and C2 are determined by the color source, and the color operand.

  • Combine Color Source - defines the source for a color operand in the combine operation. The color source includes the following:

    • COMBINE_OBJECT_COLOR - object color

    • COMBINE_TEXTURE_COLOR - texture color

    • COMBINE_CONSTANT_COLOR - texture blend color

    • COMBINE_PREVIOUS_TEXTURE_UNIT_STATE - color from the previous texture unit state. For texture unit state 0, this is equivalent to COMBINE_OBJECT_COLOR.

  • Combine Color Function - specifies the function for a color operand in the combine operation. The valid values are:

    • COMBINE_SRC_COLOR - the color function is f = Crgb

    • COMBINE_ONE_MINUS_SRC_COLOR - the color function is f = (1 - Crgb)

    • COMBINE_SRC_ALPHA - the color function is f = Ca

    • COMBINE_ONE_MINUS_SRC_ALPHA - the color function is f = (1 - Ca)

  • Combine scale factor - specifies the scale factor to be applied to the output color of the combine operation. The valid values include: 1, 2, or 4.
  • Transform - the texture transform object used to transform texture coordinates. The texture transform can translate, scale, or rotate the texture coordinates before the texture is applied to the object.
  • Blend color - the constant texture blend color
  • Perspective correction - the perspective correction mode used for color and texture coordinate interpolation. 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.
  • Texture color table - defines a table that is used to look up texture colors before applying the texture mode.
See Also:
  • Field Details

  • Constructor Details

    • TextureAttributes

      public TextureAttributes()
      Constructs a TextureAttributes object with default parameters. The default values are as follows:
        texture mode : REPLACE
        blend color : black (0,0,0,0)
        transform : identity
        perspective correction mode : NICEST
        texture color table : null
        combine rgb mode : COMBINE_MODULATE
        combine alpha mode : COMBINE_MODULATE
        combine rgb source :
          C0=COMBINE_TEXTURE_COLOR
          C1=COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
          C2=COMBINE_CONSTANT_COLOR
        combine alpha source :
          C0=COMBINE_TEXTURE_COLOR
          C1=COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
          C2=COMBINE_CONSTANT_COLOR
        combine rgb function : COMBINE_SRC_COLOR
        combine alpha function : COMBINE_SRC_ALPHA
        combine rgb scale : 1
        combine alpha scale : 1
    • TextureAttributes

      public TextureAttributes(int textureMode, Transform3D transform, javax.vecmath.Color4f textureBlendColor, int perspCorrectionMode)
      Constructs a TextureAttributes object with the specified values.
      Parameters:
      textureMode - the texture mode; one of MODULATE, DECAL, BLEND, REPLACE, or COMBINE
      transform - the transform object, used to transform texture coordinates
      textureBlendColor - the texture constant color
      perspCorrectionMode - the perspective correction mode to be used for color and/or texture coordinate interpolation; one of NICEST or FASTEST
      Throws:
      IllegalArgumentException - if textureMode is a value other than MODULATE, DECAL, BLEND, REPLACE, or COMBINE
      IllegalArgumentException - if mode value is other than FASTEST or NICEST.
  • Method Details

    • setTextureMode

      public void setTextureMode(int textureMode)
      Sets the texture mode parameter for this appearance component object.
      Parameters:
      textureMode - the texture mode, one of: MODULATE, DECAL, BLEND, REPLACE, or COMBINE
      Throws:
      IllegalArgumentException - if textureMode is a value other than MODULATE, DECAL, BLEND, REPLACE, or COMBINE
      See Also:
    • getTextureMode

      public int getTextureMode()
      Gets the texture mode parameter for this texture attributes object.
      Returns:
      textureMode the texture mode
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    • setTextureBlendColor

      public void setTextureBlendColor(javax.vecmath.Color4f textureBlendColor)
      Sets the texture constant color for this texture attributes object.
      Parameters:
      textureBlendColor - the texture constant color
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    • setTextureBlendColor

      public void setTextureBlendColor(float r, float g, float b, float a)
      Sets the texture blend color for this appearance component object.
      Parameters:
      r - the red component of the color
      g - the green component of the color
      b - the blue component of the color
      a - the alpha component of the color
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    • getTextureBlendColor

      public void getTextureBlendColor(javax.vecmath.Color4f textureBlendColor)
      Gets the texture blend color for this appearance component object.
      Parameters:
      textureBlendColor - the vector that will receive the texture constant color
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    • setTextureTransform

      public void setTextureTransform(Transform3D transform)
      Sets the texture transform object used to transform texture coordinates. A copy of the specified Transform3D object is stored in this TextureAttributes object.
      Parameters:
      transform - the new transform object
      Throws:
      CapabilityNotSetException - if the method is called when this object is part of live or compiled scene graph.
    • getTextureTransform

      public void getTextureTransform(Transform3D transform)
      Retrieves a copy of the texture transform object.
      Parameters:
      transform - the transform object that will receive the current texture transform
      Throws:
      CapabilityNotSetException - if the method is called when this object is part of live or compiled scene graph.
    • setPerspectiveCorrectionMode

      public void setPerspectiveCorrectionMode(int mode)
      Sets perspective correction mode to be used for color and/or texture coordinate interpolation. A value of NICEST indicates that perspective correction should be performed and that the highest quality method should be used. A value of FASTEST indicates that the most efficient perspective correction method should be used.
      Parameters:
      mode - one of NICEST or FASTEST The default value is NICEST.
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      IllegalArgumentException - if mode value is other than FASTEST or NICEST.
    • getPerspectiveCorrectionMode

      public int getPerspectiveCorrectionMode()
      Gets perspective correction mode value.
      Returns:
      mode the value of perspective correction mode
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
    • setTextureColorTable

      public void setTextureColorTable(int[][] table)
      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 and table[0].length defines the texture color table size. If the table is non-null, the number of color components must either be 3, for rgb data, or 4, for rgba data. The size of each array for each color component must be the same and must be a power of 2. If table 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.

      When enabled, the texture color table is applied after the texture filtering operation and before texture application. Each of the r, g, b, and a components are clamped to the range [0,1], multiplied by textureColorTableSize-1, and rounded to the nearest integer. The resulting value for each component is then used as an index into the respective table for that component. If the texture color table contains 3 components, alpha is passed through unmodified.

      Parameters:
      table - the new texture color table
      Throws:
      IllegalArgumentException - if table.length is not 3 or 4, or if the arrays for each component are not all the same length, or if the texture color table size is not a power of 2
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.2
      See Also:
    • getTextureColorTable

      public void getTextureColorTable(int[][] table)
      Retrieves the texture color table and copies it into the specified array. If the current texture color table is null, no values are copied.
      Parameters:
      table - the array that will receive a copy of the texture color table from this TextureAttributes object. The array must be allocated by the caller and must be large enough to hold the entire table (that is, int[numTextureColorTableComponents][textureColorTableSize]).
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.2
    • getNumTextureColorTableComponents

      public int getNumTextureColorTableComponents()
      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.
      Returns:
      the number of color components in the texture color table, or 0 if the table is null
      Since:
      Java 3D 1.2
    • getTextureColorTableSize

      public int getTextureColorTableSize()
      Retrieves the size of the current texture color table. A value of 0 is returned if the texture color table is null.
      Returns:
      the size of the texture color table, or 0 if the table is null
      Since:
      Java 3D 1.2
    • setCombineRgbMode

      public void setCombineRgbMode(int combineMode)
      Sets the combine mode for the rgb components of the output color for this object.
      Parameters:
      combineMode - the combine mode, one of: COMBINE_REPLACE, COMBINE_MODULATE, COMBINE_ADD, COMBINE_ADD_SIGNED, COMBINE_SUBTRACT, COMBINE_INTERPOLATE, or COMBINE_DOT3
      Throws:
      IllegalArgumentException - if combineMode is a value other than COMBINE_REPLACE, COMBINE_MODULATE, COMBINE_ADD, COMBINE_ADD_SIGNED, COMBINE_SUBTRACT, COMBINE_INTERPOLATE, or COMBINE_DOT3
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • setCombineAlphaMode

      public void setCombineAlphaMode(int combineMode)
      Sets the combine mode for the alpha component of the output color for this object.
      Parameters:
      combineMode - the combine mode, one of: COMBINE_REPLACE, COMBINE_MODULATE, COMBINE_ADD, COMBINE_ADD_SIGNED, COMBINE_SUBTRACT, COMBINE_INTERPOLATE, or COMBINE_DOT3
      Throws:
      IllegalArgumentException - if combineMode is a value other than COMBINE_REPLACE, COMBINE_MODULATE, COMBINE_ADD, COMBINE_ADD_SIGNED, COMBINE_SUBTRACT, COMBINE_INTERPOLATE, or COMBINE_DOT3
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • getCombineRgbMode

      public int getCombineRgbMode()
      Retrieves the combine mode for the rgb components of the output color for this object.
      Returns:
      the combine mode for the rgb components.
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • getCombineAlphaMode

      public int getCombineAlphaMode()
      Retrieves the combine mode for the alpha component of the output color for this object.
      Returns:
      the combine mode for the alpha component.
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • setCombineRgbSource

      public void setCombineRgbSource(int index, int src)
      Sets the source for the rgb components of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      src - the color source, one of: COMBINE_OBJECT_COLOR, COMBINE_TEXTURE_COLOR, COMBINE_CONSTANT_COLOR, or COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      IllegalArgumentException - if src is a value other than COMBINE_OBJECT_COLOR, COMBINE_TEXTURE_COLOR, COMBINE_CONSTANT_COLOR, or COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • setCombineAlphaSource

      public void setCombineAlphaSource(int index, int src)
      Sets the source for the alpha component of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      src - the color source, one of: COMBINE_OBJECT_COLOR, COMBINE_TEXTURE_COLOR, COMBINE_CONSTANT_COLOR, or COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      IllegalArgumentException - if src is a value other than COMBINE_OBJECT_COLOR, COMBINE_TEXTURE_COLOR, COMBINE_CONSTANT_COLOR, or COMBINE_PREVIOUS_TEXTURE_UNIT_STATE
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • getCombineRgbSource

      public int getCombineRgbSource(int index)
      Retrieves the source for the rgb components of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      Returns:
      the source for the rgb components of the specified color operand for this object
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • getCombineAlphaSource

      public int getCombineAlphaSource(int index)
      Retrieves the source for the alpha component of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      Returns:
      the source for the alpha component of the specified color operand for this object
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • setCombineRgbFunction

      public void setCombineRgbFunction(int index, int function)
      Sets the function for the rgb components of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      function - the color function, one of: COMBINE_SRC_COLOR, COMBINE_ONE_MINUS_SRC_COLOR, COMBINE_SRC_ALPHA, or COMBINE_ONE_MINUS_SRC_ALPHA
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      IllegalArgumentException - if function is a value other than COMBINE_SRC_COLOR, COMBINE_ONE_MINUS_SRC_COLOR, COMBINE_SRC_ALPHA, or COMBINE_ONE_MINUS_SRC_ALPHA
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • setCombineAlphaFunction

      public void setCombineAlphaFunction(int index, int function)
      Sets the function for the alpha component of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      function - the color function, one of: COMBINE_SRC_ALPHA, or COMBINE_ONE_MINUS_SRC_ALPHA
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      IllegalArgumentException - if function is a value other than COMBINE_SRC_ALPHA or COMBINE_ONE_MINUS_SRC_ALPHA
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • getCombineRgbFunction

      public int getCombineRgbFunction(int index)
      Retrieves the function for the rgb components of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      Returns:
      the function for the rgb components of the specified color operand for this object.
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • getCombineAlphaFunction

      public int getCombineAlphaFunction(int index)
      Retrieves the function for the alpha component of the specified color operand for this object.
      Parameters:
      index - color operand in the combine operation
      Returns:
      the function for the alpha component of the specified color operand for this object.
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > 2
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • setCombineRgbScale

      public void setCombineRgbScale(int scale)
      Sets the scale factor for the rgb components of the output color for this object.
      Parameters:
      scale - the scale factor for the rgb components of the output color. It must be one of the following: 1, 2, or 4.
      Throws:
      IllegalArgumentException - if scale is a value other than 1, 2, or 4.
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • setCombineAlphaScale

      public void setCombineAlphaScale(int scale)
      Sets the scale factor for the alpha component of the output color for this object.
      Parameters:
      scale - the scale factor for the alpha component of the output color. It must be one of the following: 1, 2, or 4.
      Throws:
      IllegalArgumentException - if scale is a value other than 1, 2, or 4.
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
      See Also:
    • getCombineRgbScale

      public int getCombineRgbScale()
      Retrieves the scale factor for the rgb components of the output color for this object.
      Returns:
      the scale factor for the rgb components of the output color
      Throws:
      CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
      Java 3D 1.3
    • getCombineAlphaScale

      public int getCombineAlphaScale()
      Retrieves the scale factor for the alpha component of the output color for this object.
      Returns:
      the scale factor for the alpha component of the output color
      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