Class Texture

Direct Known Subclasses:
Texture2D, Texture3D, TextureCubeMap

public abstract class Texture extends NodeComponent
The Texture object is a component object of an Appearance object that defines the texture properties used when texture mapping is enabled. The Texture object is an abstract class and all texture objects must be created as either a Texture2D object or a Texture3D object.

Each Texture object has the following properties:

  • Boundary color - the texture boundary color. The texture boundary color is used when the boundaryModeS and boundaryModeT parameters are set to CLAMP or CLAMP_TO_BOUNDARY and if the texture boundary is not specified.
  • Boundary Width - the texture boundary width, which must be 0 or 1. If the texture boundary width is 1, then all images for all mipmap levels will include a border. The actual texture image for level 0, for example, will be of dimension (width + 2*boundaryWidth) * (height + 2*boundaryWidth). The boundary texels will be used when linear filtering is to be applied.
  • Boundary ModeS and Boundary ModeT - the boundary mode for the S and T coordinates, respectively. The boundary modes are as follows:
    • CLAMP - clamps texture coordinates to be in the range [0,1]. Texture boundary texels or the constant boundary color if boundary width is 0 will be 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
    • CLAMP_TO_EDGE - clamps texture coordinates such that filtering will not sample a texture boundary texel. Texels at the edge of the texture will be used instead.
    • CLAMP_TO_BOUNDARY - clamps texture coordinates such that filtering will sample only texture boundary texels, that is, it will never get some samples from the boundary and some from the edge. This will ensure clean unfiltered boundaries. If the texture does not have a boundary, that is the boundary width is equal to 0, then the constant boundary color will be used.
  • Image - an image or an array of images for all the mipmap levels. If only one image is provided, the MIPmap mode must be set to BASE_LEVEL.
  • Magnification filter - the magnification filter function. Used when the pixel being rendered maps to an area less than or equal to one texel. The magnification filter functions are as follows:
    • 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 base level texture image.
    • BASE_LEVEL_LINEAR - performs a bilinear interpolation on the four nearest texels in the base level texture image. The texture value T' is computed as follows:
      • i0 = trunc(u - 0.5)

        j0 = trunc(v - 0.5)

        i1 = i0 + 1

        j1 = j0 + 1

        a = frac(u - 0.5)

        b = frac(v - 0.5)

        T' = (1-a)*(1-b)*Ti0j0 + a*(1-b)*Ti1j0 + (1-a)*b*Ti0j1 + a*b*Ti1j1

    • LINEAR_SHARPEN - sharpens the resulting image by extrapolating from the base level plus one image to the base level image of this texture object.
    • LINEAR_SHARPEN_RGB - performs linear sharpen filter for the rgb components only. The alpha component is computed using BASE_LEVEL_LINEAR filter.
    • LINEAR_SHARPEN_ALPHA - performs linear sharpen filter for the alpha component only. The rgb components are computed using BASE_LEVEL_LINEAR filter.
    • FILTER4 - applies an application-supplied weight function on the nearest 4x4 texels in the base level texture image. The texture value T' is computed as follows:
      • i1 = trunc(u - 0.5) i2 = i1 + 1 i3 = i2 + 1 i0 = i1 - 1
        j1 = trunc(v - 0.5) j3 = j2 + 1 j2 = j1 + 1 j0 = j1 - 1
        a = frac(u - 0.5)
        b = frac(v - 0.5)
        f(x) : filter4 function where 0<=x<=2

        T' = f(1+a) * f(1+b) * Ti0j0 + f(a) * f(1+b) * Ti1j0 + f(1-a) * f(1+b) * Ti2j0 + f(2-a) * f(1+b) * Ti3j0 +
        f(1+a) * f(b) * Ti0j1 + f(a) * f(b) * Ti1j1 + f(1-a) * f(b) * Ti2j1 + f(2-a) * f(b) * Ti3j1 +
        f(1+a) * f(1-b) * Ti0j2 + f(a) * f(1-b) * Ti1j2 + f(1-a) * f(1-b) * Ti2j2 + f(2-a) * f(1-b) * Ti3j2 +
        f(1+a) * f(2-b) * Ti0j3 + f(a) * f(2-b) * Ti1j3 + f(1-a) * f(2-b) * Ti2j3 + f(2-a) * f(2-b) * Ti3j3

  • Minification filter - the minification filter function. Used when the pixel being rendered maps to an area greater than one texel. The minifaction filter functions are as follows:
    • FASTEST - uses the fastest available method for processing geometry.
    • NICEST - uses the nicest available method for processing geometry.
    • BASE_LEVEL_POINT - selects the nearest level in the base level texture map.
    • BASE_LEVEL_LINEAR - performs a bilinear interpolation on the four nearest texels in the base level 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.
    • FILTER4 - applies an application-supplied weight function on the nearest 4x4 texels in the base level texture image.
  • MIPmap mode - the mode used for texture mapping for this object. The mode is one of the following:
    • BASE_LEVEL - indicates that this Texture object only has a base-level image. If multiple levels are needed, they will be implicitly computed.
    • MULTI_LEVEL_MIPMAP - indicates that this Texture object has multiple images. If MIPmap mode is set to MULTI_LEVEL_MIPMAP, images for Base Level through Max Level must be set.
  • Format - the data format. The format is one of the following:
    • INTENSITY - the texture image contains only texture values.
    • LUMINANCE - the texture image contains only luminance values.
    • ALPHA - the texture image contains only alpha values.
    • LUMINANCE_ALPHA - the texture image contains both luminance and alpha values.
    • RGB - the texture image contains red, green, and blue values.
    • RGBA - the texture image contains red, green, blue, and alpha values.
  • Base Level - specifies the mipmap level to be used when filter specifies BASE_LEVEL_POINT or BASE_LEVEL_LINEAR.
  • Maximum Level - specifies the maximum level of image that needs to be defined for this texture to be valid. Note, for this texture to be valid, images for Base Level through Maximum Level have to be defined.
  • Minimum LOD - specifies the minimum of the LOD range. LOD smaller than this value will be clamped to this value.
  • Maximum LOD - specifies the maximum of the LOD range. LOD larger than this value will be clamped to this value.
  • LOD offset - specifies the offset to be used in the LOD calculation to compensate for under or over sampled texture images.
  • Anisotropic Mode - defines how anisotropic filter is applied for this texture object. The anisotropic modes are as follows:
    • ANISOTROPIC_NONE - no anisotropic filtering.
    • ANISOTROPIC_SINGLE_VALUE - applies the degree of anisotropic filter in both the minification and magnification filters.
  • Anisotropic Filter Degree - controls the degree of anisotropy. This property applies to both minification and magnification filtering. If it is equal to 1.0, then an isotropic filtering as specified in the minification or magnification filter will be used. If it is greater than 1.0, and the anisotropic mode is equal to ANISOTROPIC_SINGLE_VALUE, then the degree of anisotropy will also be applied in the filtering.
  • Sharpen Texture Function - specifies the function of level-of-detail used in combining the texture value computed from the base level image and the texture value computed from the base level plus one image. The final texture value is computed as follows:
    • T' = ((1 + SharpenFunc(LOD)) * TBaseLevel) - (SharpenFunc(LOD) * TBaseLevel+1)

  • Filter4 Function - specifies the function to be applied to the nearest 4x4 texels. This property includes samples of the filter function f(x), 0<=x<=2. The number of function values supplied has to be equal to 2m + 1 for some integer value of m greater than or equal to 4.

Note that as of Java 3D 1.5, the texture width and height are no longer required to be an exact power of two. However, not all graphics devices supports non-power-of-two textures. If non-power-of-two texture mapping is unsupported on a particular Canvas3D, textures with a width or height that are not an exact power of two are ignored for that canvas.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Specifies that this Texture object allows reading its anistropic filter information (e.g., anisotropic mode, anisotropic filter)
    static final int
    Specifies that this Texture object allows reading its boundary color information.
    static final int
    Specifies that this Texture object allows reading its boundary mode information.
    static final int
    Specifies that this Texture object allows reading its enable flag.
    static final int
    Specifies that this Texture object allows writing its enable flag.
    static final int
    Specifies that this Texture object allows reading its filter information.
    static final int
    Specifies that this Texture object allows reading its filter4 function information.
    static final int
    Specifies that this Texture object allows reading its format information.
    static final int
    Specifies that this Texture object allows reading its image component information.
    static final int
    Specifies that this Texture object allows writing its image component information.
    static final int
    Specifies that this Texture object allows reading its LOD range information (e.g., base level, maximum level, minimum lod, maximum lod, lod offset)
    static final int
    Specifies that this Texture object allows writing its LOD range information (e.g., base level, maximum level, minimum lod, maximum lod, lod offset)
    static final int
    Specifies that this Texture object allows reading its mipmap mode information.
    static final int
    Specifies that this Texture object allows reading its sharpen texture function information.
    static final int
    Specifies that this Texture object allows reading its size information (e.g., width, height, number of mipmap levels, boundary width).
    static final int
    Specifies Texture contains only Alpha values.
    static final int
    No anisotropic filter.
    static final int
    Uses the degree of anisotropy in both the minification and magnification filters.
    static final int
    Indicates that Texture object only has one level.
    static final int
    Performs bilinear interpolation on the four nearest texels in level 0 texture map.
    static final int
    Select the nearest texel in level 0 texture map.
    static final int
    Clamps texture coordinates to be in the range [0, 1].
    static final int
    Clamps texture coordinates such that filtering will sample only texture boundary texels.
    static final int
    Clamps texture coordinates such that filtering will not sample a texture boundary texel.
    static final int
    Uses the fastest available method for processing geometry.
    static final int
    Applies an application-supplied weight function on the nearest 4x4 texels in the base level texture image.
    static final int
    Specifies Texture contains only Intensity values.
    static final int
    Sharpens the resulting image by extrapolating from the base level plus one image to the base level image of this texture object.
    static final int
    Performs linear sharpen filter for the alpha component only.
    static final int
    Performs linear sharpen filter for the rgb components only.
    static final int
    Specifies Texture contains only luminance values.
    static final int
    Specifies Texture contains Luminance and Alpha values.
    static final int
    Performs tri-linear interpolation of texels between four texels each from two nearest mipmap levels.
    static final int
    Indicates that this Texture object has multiple images, one for each mipmap level.
    static final int
    Selects the nearest texel in the nearest mipmap.
    static final int
    Uses the nicest available method for processing geometry.
    static final int
    Specifies Texture contains Red, Green and Blue color values.
    static final int
    Specifies Texture contains Red, Green, Blue color values and Alpha value.
    static final int
    Repeats the texture by wrapping texture coordinates that are outside the range [0,1].
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a Texture object with default parameters.
    Texture(int mipMapMode, int format, int width, int height)
    Constructs an empty Texture object with specified mipMapMode, format, width and height.
    Texture(int mipMapMode, int format, int width, int height, int boundaryWidth)
    Constructs an empty Texture object with specified mipMapMode, format, width, height, and boundaryWidth.
  • Method Summary

    Modifier and Type
    Method
    Description
    float
    Retrieves the anisotropic filter degree for this texture object.
    int
    Retrieves the anisotropic filter mode for this texture object.
    int
    Retrieves the base level for this texture object.
    void
    getBoundaryColor(javax.vecmath.Color4f boundaryColor)
    Retrieves the texture boundary color for this texture object.
    int
    Retrieves the boundary mode for the S coordinate.
    int
    Retrieves the boundary mode for the T coordinate.
    int
    Retrieves the width of the boundary of this Texture object.
    boolean
    Retrieves the state of the texture enable flag.
    void
    getFilter4Func(float[] weights)
    Copies the array of filter4 function values into the specified array.
    int
    Retrieves the number of filter4 function values for this texture object.
    int
    Retrieves the format of this Texture object.
    int
    Retrieves the height of this Texture object.
    getImage(int level)
    Retrieves the image for a specified mipmap level.
    Retrieves the array of images for all mipmap levels.
    void
    getLodOffset(javax.vecmath.Tuple3f offset)
    Retrieves the LOD offset for this texture object.
    int
    Retrieves the magnification filter.
    int
    Retrieves the maximum level for this texture object.
    float
    Retrieves the maximum level-of-detail for this texture object.
    int
    Retrieves the minification filter.
    float
    Retrieves the minimum level-of-detail for this texture object.
    int
    Retrieves current mipmap mode.
    void
    getSharpenTextureFunc(float[] lod, float[] pts)
    Copies the array of sharpen texture LOD function points into the specified arrays.
    void
    getSharpenTextureFunc(javax.vecmath.Point2f[] pts)
    Copies the array of sharpen texture LOD function points including the lod values and the corresponding function values into the specified array.
    int
    Gets the number of points in the sharpen texture LOD function for this texture object.
    int
    Retrieves the width of this Texture object.
    int
    Retrieves the number of mipmap levels needed for this Texture object.
    void
    Specifies the degree of anisotropy to be used when the anisotropic filter mode specifies ANISOTROPIC_SINGLE_VALUE.
    void
    Specifies the anisotropic filter mode for this texture object.
    void
    setBaseLevel(int baseLevel)
    Specifies the base level for this texture object.
    void
    setBoundaryColor(float r, float g, float b, float a)
    Sets the texture boundary color for this texture object.
    void
    setBoundaryColor(javax.vecmath.Color4f boundaryColor)
    Sets the texture boundary color for this texture object.
    void
    setBoundaryModeS(int boundaryModeS)
    Sets the boundary mode for the S coordinate in this texture object.
    void
    setBoundaryModeT(int boundaryModeT)
    Sets the boundary mode for the T coordinate in this texture object.
    void
    setEnable(boolean state)
    Enables or disables texture mapping for this appearance component object.
    void
    setFilter4Func(float[] weights)
    sets the filter4 function for this texture object.
    void
    setImage(int level, ImageComponent image)
    Sets the image for a specified mipmap level.
    void
    Sets the array of images for all mipmap levels.
    void
    setLodOffset(float s, float t, float r)
    Specifies the LOD offset for this texture object.
    void
    setLodOffset(javax.vecmath.Tuple3f offset)
    Specifies the LOD offset for this texture object.
    void
    setMagFilter(int magFilter)
    Sets the magnification filter function.
    void
    setMaximumLevel(int maximumLevel)
    Specifies the maximum level for this texture object.
    void
    setMaximumLOD(float maximumLod)
    Specifies the maximum level-of-detail for this texture object.
    void
    setMinFilter(int minFilter)
    Sets the minification filter function.
    void
    setMinimumLOD(float minimumLod)
    Specifies the minimum level-of-detail for this texture object.
    void
    setMipMapMode(int mipMapMode)
    Sets mipmap mode for texture mapping for this texture object.
    void
    setSharpenTextureFunc(float[] lod, float[] pts)
    sets the sharpen texture LOD function for this texture object.
    void
    setSharpenTextureFunc(javax.vecmath.Point2f[] pts)
    sets the sharpen texture LOD function for this texture object.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • ALLOW_ENABLE_READ

      public static final int ALLOW_ENABLE_READ
      Specifies that this Texture object allows reading its enable flag.
      See Also:
    • ALLOW_ENABLE_WRITE

      public static final int ALLOW_ENABLE_WRITE
      Specifies that this Texture object allows writing its enable flag.
      See Also:
    • ALLOW_BOUNDARY_MODE_READ

      public static final int ALLOW_BOUNDARY_MODE_READ
      Specifies that this Texture object allows reading its boundary mode information.
      See Also:
    • ALLOW_FILTER_READ

      public static final int ALLOW_FILTER_READ
      Specifies that this Texture object allows reading its filter information.
      See Also:
    • ALLOW_IMAGE_READ

      public static final int ALLOW_IMAGE_READ
      Specifies that this Texture object allows reading its image component information.
      See Also:
    • ALLOW_IMAGE_WRITE

      public static final int ALLOW_IMAGE_WRITE
      Specifies that this Texture object allows writing its image component information.
      Since:
      Java 3D 1.2
      See Also:
    • ALLOW_FORMAT_READ

      public static final int ALLOW_FORMAT_READ
      Specifies that this Texture object allows reading its format information.
      Since:
      Java 3D 1.2
      See Also:
    • ALLOW_SIZE_READ

      public static final int ALLOW_SIZE_READ
      Specifies that this Texture object allows reading its size information (e.g., width, height, number of mipmap levels, boundary width).
      Since:
      Java 3D 1.2
      See Also:
    • ALLOW_MIPMAP_MODE_READ

      public static final int ALLOW_MIPMAP_MODE_READ
      Specifies that this Texture object allows reading its mipmap mode information.
      See Also:
    • ALLOW_BOUNDARY_COLOR_READ

      public static final int ALLOW_BOUNDARY_COLOR_READ
      Specifies that this Texture object allows reading its boundary color information.
      See Also:
    • ALLOW_LOD_RANGE_READ

      public static final int ALLOW_LOD_RANGE_READ
      Specifies that this Texture object allows reading its LOD range information (e.g., base level, maximum level, minimum lod, maximum lod, lod offset)
      Since:
      Java 3D 1.3
      See Also:
    • ALLOW_LOD_RANGE_WRITE

      public static final int ALLOW_LOD_RANGE_WRITE
      Specifies that this Texture object allows writing its LOD range information (e.g., base level, maximum level, minimum lod, maximum lod, lod offset)
      Since:
      Java 3D 1.3
      See Also:
    • ALLOW_ANISOTROPIC_FILTER_READ

      public static final int ALLOW_ANISOTROPIC_FILTER_READ
      Specifies that this Texture object allows reading its anistropic filter information (e.g., anisotropic mode, anisotropic filter)
      Since:
      Java 3D 1.3
      See Also:
    • ALLOW_SHARPEN_TEXTURE_READ

      public static final int ALLOW_SHARPEN_TEXTURE_READ
      Specifies that this Texture object allows reading its sharpen texture function information.
      Since:
      Java 3D 1.3
      See Also:
    • ALLOW_FILTER4_READ

      public static final int ALLOW_FILTER4_READ
      Specifies that this Texture object allows reading its filter4 function information.
      Since:
      Java 3D 1.3
      See Also:
    • FASTEST

      @Native public static final int FASTEST
      Uses the fastest available method for processing geometry. This value can be used as a parameter to setMinFilter and setMagFilter.
      See Also:
    • NICEST

      @Native public static final int NICEST
      Uses the nicest available method for processing geometry. This value can be used as a parameter to setMinFilter and setMagFilter.
      See Also:
    • BASE_LEVEL_POINT

      @Native public static final int BASE_LEVEL_POINT
      Select the nearest texel in level 0 texture map. Maps to NEAREST.
      See Also:
    • BASE_LEVEL_LINEAR

      @Native public static final int BASE_LEVEL_LINEAR
      Performs bilinear interpolation on the four nearest texels in level 0 texture map. Maps to LINEAR.
      See Also:
    • MULTI_LEVEL_POINT

      @Native public static final int MULTI_LEVEL_POINT
      Selects the nearest texel in the nearest mipmap. Maps to NEAREST_MIPMAP_NEAREST.
      See Also:
    • MULTI_LEVEL_LINEAR

      @Native public static final int MULTI_LEVEL_LINEAR
      Performs tri-linear interpolation of texels between four texels each from two nearest mipmap levels. Maps to LINEAR_MIPMAP_LINEAR, but an implementation can fall back to LINEAR_MIPMAP_NEAREST or NEAREST_MIPMAP_LINEAR.
      See Also:
    • LINEAR_SHARPEN

      @Native public static final int LINEAR_SHARPEN
      Sharpens the resulting image by extrapolating from the base level plus one image to the base level image of this texture object.
      Since:
      Java 3D 1.3
      See Also:
    • LINEAR_SHARPEN_RGB

      @Native public static final int LINEAR_SHARPEN_RGB
      Performs linear sharpen filter for the rgb components only. The alpha component is computed using BASE_LEVEL_LINEAR filter.
      Since:
      Java 3D 1.3
      See Also:
    • LINEAR_SHARPEN_ALPHA

      @Native public static final int LINEAR_SHARPEN_ALPHA
      Performs linear sharpen filter for the alpha component only. The rgb components are computed using BASE_LEVEL_LINEAR filter.
      Since:
      Java 3D 1.3
      See Also:
    • FILTER4

      @Native public static final int FILTER4
      Applies an application-supplied weight function on the nearest 4x4 texels in the base level texture image.
      Since:
      Java 3D 1.3
      See Also:
    • CLAMP

      @Native public static final int CLAMP
      Clamps texture coordinates to be in the range [0, 1]. Texture boundary texels or the constant boundary color if boundary width is 0 will be used for U,V values that fall outside this range.
      See Also:
    • WRAP

      @Native public static final int 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.
      See Also:
    • CLAMP_TO_EDGE

      @Native public static final int CLAMP_TO_EDGE
      Clamps texture coordinates such that filtering will not sample a texture boundary texel. Texels at the edge of the texture will be used instead.
      Since:
      Java 3D 1.3
      See Also:
    • CLAMP_TO_BOUNDARY

      @Native public static final int CLAMP_TO_BOUNDARY
      Clamps texture coordinates such that filtering will sample only texture boundary texels. If the texture does not have a boundary, that is the boundary width is equal to 0, then the constant boundary color will be used.