javax.media.j3d

## Class TextureCubeMap

- java.lang.Object
- - javax.media.j3d.SceneGraphObject
  - - javax.media.j3d.NodeComponent
    - - javax.media.j3d.Texture
      - - javax.media.j3d.TextureCubeMap

-     public class TextureCubeMap
      extends Texture

  TextureCubeMap is a subclass of Texture class. It defines a special kind of texture mapping which is composed of a set of six 2D images representating the six faces of a cube. The texture coordinate (s,t,r) is used as a 3D direction vector emanating from the center of a cube to select a particular face of the cube based on the largest magnitude coordinate (the major axis). A new 2D texture coordinate (s,t) is then determined by dividing the other two coordinates (the minor axes) by the major axis value. The new coordinate is then used for texel lookup from the selected texture image of this cube map. The TextureCubeMap image is defined by specifying the images for each face of the cube. The cube map texture can be thought of as centered at the orgin of and aligned to an XYZ coordinate system. The names of the cube faces are:
  - POSITIVE_X
  - NEGATIVE_X
  - POSITIVE_Y
  - NEGATIVE_Y
  - POSITIVE_Z
  - NEGATIVE_Z

  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.

  Since:
    Java 3D 1.3
  See Also:
    `Canvas3D.queryProperties()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `NEGATIVE_X` Specifies the face of the cube that is pierced by the negative x axis
    `static int` | `NEGATIVE_Y` Specifies the face of the cube that is pierced by the negative y axis
    `static int` | `NEGATIVE_Z` Specifies the face of the cube that is pierced by the negative z axis
    `static int` | `POSITIVE_X` Specifies the face of the cube that is pierced by the positive x axis
    `static int` | `POSITIVE_Y` Specifies the face of the cube that is pierced by the positive y axis
    `static int` | `POSITIVE_Z` Specifies the face of the cube that is pierced by the positive z axis

    - ### Fields inherited from class javax.media.j3d.Texture

      `ALLOW_ANISOTROPIC_FILTER_READ, ALLOW_BOUNDARY_COLOR_READ, ALLOW_BOUNDARY_MODE_READ, ALLOW_ENABLE_READ, ALLOW_ENABLE_WRITE, ALLOW_FILTER_READ, ALLOW_FILTER4_READ, ALLOW_FORMAT_READ, ALLOW_IMAGE_READ, ALLOW_IMAGE_WRITE, ALLOW_LOD_RANGE_READ, ALLOW_LOD_RANGE_WRITE, ALLOW_MIPMAP_MODE_READ, ALLOW_SHARPEN_TEXTURE_READ, ALLOW_SIZE_READ, ALPHA, ANISOTROPIC_NONE, ANISOTROPIC_SINGLE_VALUE, BASE_LEVEL, BASE_LEVEL_LINEAR, BASE_LEVEL_POINT, CLAMP, CLAMP_TO_BOUNDARY, CLAMP_TO_EDGE, FASTEST, FILTER4, INTENSITY, LINEAR_SHARPEN, LINEAR_SHARPEN_ALPHA, LINEAR_SHARPEN_RGB, LUMINANCE, LUMINANCE_ALPHA, MULTI_LEVEL_LINEAR, MULTI_LEVEL_MIPMAP, MULTI_LEVEL_POINT, NICEST, RGB, RGBA, WRAP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextureCubeMap()` Constructs a texture object using default values.
    `TextureCubeMap(int mipmapMode, int format, int width)` Constructs an empty TextureCubeMap object with specified mipmapMode format, and width.
    `TextureCubeMap(int mipmapMode, int format, int width, int boundaryWidth)` Constructs an empty TextureCubeMap object with specified mipmapMode format, width, and boundary width.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `duplicateNodeComponent(NodeComponent originalNodeComponent)` Deprecated. replaced with duplicateNodeComponent( NodeComponent originalNodeComponent, boolean forceDuplicate)
    `ImageComponent` | `getImage(int level)` This method is not supported for TextureCubeMap.
    `ImageComponent` | `getImage(int level, int face)` Retrieves the image for a specified mipmap level of a particular face of the cube map.
    `ImageComponent[]` | `getImages()` This method is not supported for TextureCubeMap.
    `ImageComponent[]` | `getImages(int face)` Retrieves the array of images for all mipmap level of a particular face of the cube map.
    `void` | `setImage(int level, ImageComponent image)` This method is not supported for TextureCubeMap.
    `void` | `setImage(int level, int face, ImageComponent2D image)` Sets the image for a specified mipmap level of a specified face of the cube map
    `void` | `setImages(ImageComponent[] images)` This method is not supported for TextureCubeMap.
    `void` | `setImages(int face, ImageComponent2D[] images)` Sets the array of images for mipmap levels from base level through max level for a specified face of the cube map

    - ### Methods inherited from class javax.media.j3d.Texture

      `getAnisotropicFilterDegree, getAnisotropicFilterMode, getBaseLevel, getBoundaryColor, getBoundaryModeS, getBoundaryModeT, getBoundaryWidth, getEnable, getFilter4Func, getFilter4FuncPointsCount, getFormat, getHeight, getLodOffset, getMagFilter, getMaximumLevel, getMaximumLOD, getMinFilter, getMinimumLOD, getMipMapMode, getSharpenTextureFunc, getSharpenTextureFunc, getSharpenTextureFuncPointsCount, getWidth, numMipMapLevels, setAnisotropicFilterDegree, setAnisotropicFilterMode, setBaseLevel, setBoundaryColor, setBoundaryColor, setBoundaryModeS, setBoundaryModeT, setEnable, setFilter4Func, setLodOffset, setLodOffset, setMagFilter, setMaximumLevel, setMaximumLOD, setMinFilter, setMinimumLOD, setMipMapMode, setSharpenTextureFunc, setSharpenTextureFunc`

    - ### Methods inherited from class javax.media.j3d.NodeComponent

      `cloneNodeComponent, cloneNodeComponent, 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

    - #### POSITIVE_X

          public static final int POSITIVE_X

      Specifies the face of the cube that is pierced by the positive x axis
      See Also:
        Constant Field Values

    - #### NEGATIVE_X

          public static final int NEGATIVE_X

      Specifies the face of the cube that is pierced by the negative x axis
      See Also:
        Constant Field Values

    - #### POSITIVE_Y

          public static final int POSITIVE_Y

      Specifies the face of the cube that is pierced by the positive y axis
      See Also:
        Constant Field Values

    - #### NEGATIVE_Y

          public static final int NEGATIVE_Y

      Specifies the face of the cube that is pierced by the negative y axis
      See Also:
        Constant Field Values

    - #### POSITIVE_Z

          public static final int POSITIVE_Z

      Specifies the face of the cube that is pierced by the positive z axis
      See Also:
        Constant Field Values

    - #### NEGATIVE_Z

          public static final int NEGATIVE_Z

      Specifies the face of the cube that is pierced by the negative z axis
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TextureCubeMap

          public TextureCubeMap()

      Constructs a texture object using default values. Note that the default constructor creates a texture object with a width of 0 and is, therefore, not useful.

    - #### TextureCubeMap

          public TextureCubeMap(int mipmapMode,
                        int format,
                        int width)

      Constructs an empty TextureCubeMap object with specified mipmapMode format, and width. Image at base level must be set by the application using 'setImage' method. If mipmapMode is set to MULTI_LEVEL_MIPMAP, images for base level through maximum level must be set. Note that cube map is square in dimensions, hence specifying width is sufficient. Note also that a texture with a non-power-of-two width will only be rendered on a graphics device that supports non-power-of-two textures.
      Parameters:
        `mipmapMode` - type of mipmap for this Texture: One of BASE_LEVEL, MULTI_LEVEL_MIPMAP.
        `format` - data format of Textures saved in this object. One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
        `width` - width (and height) of image at level 0.
      Throws:
        `java.lang.IllegalArgumentException` - if width is not greater than 0 OR invalid format/mipmapMode is specified.

    - #### TextureCubeMap

          public TextureCubeMap(int mipmapMode,
                        int format,
                        int width,
                        int boundaryWidth)

      Constructs an empty TextureCubeMap object with specified mipmapMode format, width, and boundary width. Image at base level must be set by the application using 'setImage' method. If mipmapMode is set to MULTI_LEVEL_MIPMAP, images for base level through maximum level must be set. Note that cube map is square in dimensions, hence specifying width is sufficient. Note also that a texture with a non-power-of-two width will only be rendered on a graphics device that supports non-power-of-two textures.
      Parameters:
        `mipmapMode` - type of mipmap for this Texture: One of BASE_LEVEL, MULTI_LEVEL_MIPMAP.
        `format` - data format of Textures saved in this object. One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
        `width` - width (and height) of image at level 0. This does not include the width of the boundary.
        `boundaryWidth` - width of the boundary, which must be 0 or 1.
      Throws:
        `java.lang.IllegalArgumentException` - if width is not greater than 0 OR invalid format/mipmapMode is specified.

  - ### Method Detail

    - #### setImage

          public void setImage(int level,
                      int face,
                      ImageComponent2D image)

      Sets the image for a specified mipmap level of a specified face of the cube map
      Parameters:
        `level` - mipmap level
        `face` - face of the cube map. One of: `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `image` - ImageComponent2D object containing the image
      Throws:
        `java.lang.IllegalArgumentException` - if `face` has a value other than `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
        `IllegalSharingException` - if this TextureCubeMap is live and the specified image is being used by a Canvas3D as an off-screen buffer.
        `IllegalSharingException` - if this TextureCubeMap is being used by an immediate mode context and the specified image is being used by a Canvas3D as an off-screen buffer.

    - #### setImages

          public void setImages(int face,
                       ImageComponent2D[] images)

      Sets the array of images for mipmap levels from base level through max level for a specified face of the cube map
      Parameters:
        `face` - face of the cube map. One of: `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `images` - array of ImageComponent2D objects containing the images
      Throws:
        `java.lang.IllegalArgumentException` - if `face` has a value other than `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
        `IllegalSharingException` - if this TextureCubeMap is live and any of the specified images are being used by a Canvas3D as an off-screen buffer.
        `IllegalSharingException` - if this TextureCubeMap is being used by an immediate mode context and any of the specified images are being used by a Canvas3D as an off-screen buffer.

    - #### getImage

          public ImageComponent getImage(int level,
                                int face)

      Retrieves the image for a specified mipmap level of a particular face of the cube map.
      Parameters:
        `level` - mipmap level to get.
        `face` - face of the cube map. One of: `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
      Returns:
        the ImageComponent object containing the texture image at the specified mipmap level.
      Throws:
        `java.lang.IllegalArgumentException` - if `face` has a value other than `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### getImages

          public ImageComponent[] getImages(int face)

      Retrieves the array of images for all mipmap level of a particular face of the cube map.
      Parameters:
        `face` - face of the cube map. One of: `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
      Returns:
        an array of ImageComponent object for the particular face of of the cube map.
      Throws:
        `java.lang.IllegalArgumentException` - if `face` has a value other than `POSITIVE_X`, `NEGATIVE_X`, `POSITIVE_Y`, `NEGATIVE_Y`, `POSITIVE_Z` or `NEGATIVE_Z`.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### setImage

          public void setImage(int level,
                      ImageComponent image)

      This method is not supported for TextureCubeMap. A face of the cube map has to be specified when setting an image for a particular level of the cube map.
      Overrides:
        `setImage` in class `Texture`
      Parameters:
        `level` - mipmap level to set: 0 is the base level
        `image` - ImageComponent object containing the texture image for the specified mipmap level
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      Since:
        Java 3D 1.3

    - #### setImages

          public void setImages(ImageComponent[] images)

      This method is not supported for TextureCubeMap. A face of the cube map has to be specified when setting images for the cube map.
      Overrides:
        `setImages` in class `Texture`
      Parameters:
        `images` - array of ImageComponent objects containing the texture images for all mipmap levels
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      Since:
        Java 3D 1.3

    - #### getImage

          public ImageComponent getImage(int level)

      This method is not supported for TextureCubeMap. A face of the cube map has to be specified when retrieving an image for a particular level of the cube map.
      Overrides:
        `getImage` in class `Texture`
      Parameters:
        `level` - mipmap level to get: 0 is the base level
      Returns:
        the ImageComponent object containing the texture image at the specified mipmap level.
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      Since:
        Java 3D 1.3

    - #### getImages

          public ImageComponent[] getImages()

      This method is not supported for TextureCubeMap. A face of the cube map has to be specified when retrieving images for the cube map.
      Overrides:
        `getImages` in class `Texture`
      Returns:
        the array of ImageComponent objects for this Texture.
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      Since:
        Java 3D 1.3

    - #### duplicateNodeComponent

          public void duplicateNodeComponent(NodeComponent originalNodeComponent)

      Deprecated. replaced with duplicateNodeComponent( NodeComponent originalNodeComponent, boolean forceDuplicate)
      NOTE: Applications should not call this method directly. It should only be called by the cloneNode method.
      Overrides:
        `duplicateNodeComponent` in class `NodeComponent`

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