com.jogamp.opengl.util.texture.spi

## Class DDSImage

- java.lang.Object
- - com.jogamp.opengl.util.texture.spi.DDSImage

-     public class DDSImage
      extends Object

  A reader and writer for DirectDraw Surface (.dds) files, which are used to describe textures. These files can contain multiple mipmap levels in one file. This class is currently minimal and does not support all of the possible file formats.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DDSImage.ImageInfo` Simple class describing images and data; does not encapsulate image format information.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `D3DFMT_A8R8G8B8`
    `static int` | `D3DFMT_DXT1`
    `static int` | `D3DFMT_DXT2`
    `static int` | `D3DFMT_DXT3`
    `static int` | `D3DFMT_DXT4`
    `static int` | `D3DFMT_DXT5`
    `static int` | `D3DFMT_R8G8B8`
    `static int` | `D3DFMT_UNKNOWN`
    `static int` | `D3DFMT_X8R8G8B8`
    `static int` | `DDPF_ALPHA`
    `static int` | `DDPF_ALPHAPIXELS`
    `static int` | `DDPF_COMPRESSED`
    `static int` | `DDPF_FOURCC`
    `static int` | `DDPF_PALETTEINDEXED1`
    `static int` | `DDPF_PALETTEINDEXED2`
    `static int` | `DDPF_PALETTEINDEXED4`
    `static int` | `DDPF_PALETTEINDEXED8`
    `static int` | `DDPF_PALETTEINDEXEDTO8`
    `static int` | `DDPF_RGB`
    `static int` | `DDPF_RGBTOYUV`
    `static int` | `DDPF_YUV`
    `static int` | `DDPF_ZBUFFER`
    `static int` | `DDPF_ZPIXELS`
    `static int` | `DDSCAPS_COMPLEX`
    `static int` | `DDSCAPS_MIPMAP`
    `static int` | `DDSCAPS_TEXTURE`
    `static int` | `DDSCAPS2_CUBEMAP`
    `static int` | `DDSCAPS2_CUBEMAP_NEGATIVEX`
    `static int` | `DDSCAPS2_CUBEMAP_NEGATIVEY`
    `static int` | `DDSCAPS2_CUBEMAP_NEGATIVEZ`
    `static int` | `DDSCAPS2_CUBEMAP_POSITIVEX`
    `static int` | `DDSCAPS2_CUBEMAP_POSITIVEY`
    `static int` | `DDSCAPS2_CUBEMAP_POSITIVEZ`
    `static int` | `DDSD_ALPHABITDEPTH`
    `static int` | `DDSD_BACKBUFFERCOUNT`
    `static int` | `DDSD_CAPS`
    `static int` | `DDSD_DEPTH`
    `static int` | `DDSD_HEIGHT`
    `static int` | `DDSD_LINEARSIZE`
    `static int` | `DDSD_LPSURFACE`
    `static int` | `DDSD_MIPMAPCOUNT`
    `static int` | `DDSD_PITCH`
    `static int` | `DDSD_PIXELFORMAT`
    `static int` | `DDSD_WIDTH`
    `static int` | `DDSD_ZBUFFERBITDEPTH`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ByteBuffer` | `allocateBlankBuffer(int width, int height, int openGLInternalFormat)` Allocates a temporary, empty ByteBuffer suitable for use in a call to glCompressedTexImage2D.
    `void` | `close()` Closes open files and resources associated with the open DDSImage.
    `static DDSImage` | `createFromData(int d3dFormat, int width, int height, ByteBuffer[] mipmapData)` Creates a new DDSImage from data supplied by the user.
    `void` | `debugPrint()`
    `DDSImage.ImageInfo[]` | `getAllMipMaps()` Returns an array of ImageInfos corresponding to all mipmap levels of this DDS file.
    `DDSImage.ImageInfo[]` | `getAllMipMaps(int side)` Returns an array of ImageInfos corresponding to all mipmap levels of this DDS file.
    `int` | `getCompressionFormat()` If this surface is compressed, returns the kind of compression used (DXT1..DXT5).
    `static String` | `getCompressionFormatName(int compressionFormat)` Converts e.g.
    `int` | `getDepth()` Total number of bits per pixel.
    `int` | `getHeight()` Height of the texture (or the top-most mipmap if mipmaps are present)
    `DDSImage.ImageInfo` | `getMipMap(int map)` Gets the ith mipmap data (0..getNumMipMaps() - 1)
    `DDSImage.ImageInfo` | `getMipMap(int side, int map)` Gets the ith mipmap data (0..getNumMipMaps() - 1)
    `int` | `getNumMipMaps()` Number of mip maps in the texture
    `int` | `getPixelFormat()` Gets the pixel format of this texture (D3DFMT_*) based on some heuristics.
    `int` | `getWidth()` Width of the texture (or the top-most mipmap if mipmaps are present)
    `boolean` | `isCompressed()` Indicates whether this texture is compressed.
    `boolean` | `isCubemap()` Indicates whether this texture is cubemap
    `boolean` | `isCubemapSidePresent(int side)` Indicates whethe this cubemap side present
    `static boolean` | `isDDSImage(InputStream in)` Determines from the magic number whether the given InputStream points to a DDS image.
    `boolean` | `isPixelFormatFlagSet(int flag)` Test for presence/absence of pixel format flags (DDPF_*)
    `boolean` | `isSurfaceDescFlagSet(int flag)` Test for presence/absence of surface description flags (DDSD_*)
    `static DDSImage` | `read(ByteBuffer buf)` Reads a DirectDraw surface from the specified ByteBuffer, returning the resulting DDSImage.
    `static DDSImage` | `read(File file)` Reads a DirectDraw surface from the specified file, returning the resulting DDSImage.
    `static DDSImage` | `read(String filename)` Reads a DirectDraw surface from the specified file name, returning the resulting DDSImage.
    `void` | `write(File file)` Writes this DDSImage to the specified file name.
    `void` | `write(String filename)` Writes this DDSImage to the specified file name.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DDSD_CAPS

          public static final int DDSD_CAPS

      See Also:
        Constant Field Values

    - #### DDSD_HEIGHT

          public static final int DDSD_HEIGHT

      See Also:
        Constant Field Values

    - #### DDSD_WIDTH

          public static final int DDSD_WIDTH

      See Also:
        Constant Field Values

    - #### DDSD_PITCH

          public static final int DDSD_PITCH

      See Also:
        Constant Field Values

    - #### DDSD_BACKBUFFERCOUNT

          public static final int DDSD_BACKBUFFERCOUNT

      See Also:
        Constant Field Values

    - #### DDSD_ZBUFFERBITDEPTH

          public static final int DDSD_ZBUFFERBITDEPTH

      See Also:
        Constant Field Values

    - #### DDSD_ALPHABITDEPTH

          public static final int DDSD_ALPHABITDEPTH

      See Also:
        Constant Field Values

    - #### DDSD_LPSURFACE

          public static final int DDSD_LPSURFACE

      See Also:
        Constant Field Values

    - #### DDSD_PIXELFORMAT

          public static final int DDSD_PIXELFORMAT

      See Also:
        Constant Field Values

    - #### DDSD_MIPMAPCOUNT

          public static final int DDSD_MIPMAPCOUNT

      See Also:
        Constant Field Values

    - #### DDSD_LINEARSIZE

          public static final int DDSD_LINEARSIZE

      See Also:
        Constant Field Values

    - #### DDSD_DEPTH

          public static final int DDSD_DEPTH

      See Also:
        Constant Field Values

    - #### DDPF_ALPHAPIXELS

          public static final int DDPF_ALPHAPIXELS

      See Also:
        Constant Field Values

    - #### DDPF_ALPHA

          public static final int DDPF_ALPHA

      See Also:
        Constant Field Values

    - #### DDPF_FOURCC

          public static final int DDPF_FOURCC

      See Also:
        Constant Field Values

    - #### DDPF_PALETTEINDEXED4

          public static final int DDPF_PALETTEINDEXED4

      See Also:
        Constant Field Values

    - #### DDPF_PALETTEINDEXEDTO8

          public static final int DDPF_PALETTEINDEXEDTO8

      See Also:
        Constant Field Values

    - #### DDPF_PALETTEINDEXED8

          public static final int DDPF_PALETTEINDEXED8

      See Also:
        Constant Field Values

    - #### DDPF_RGB

          public static final int DDPF_RGB

      See Also:
        Constant Field Values

    - #### DDPF_COMPRESSED

          public static final int DDPF_COMPRESSED

      See Also:
        Constant Field Values

    - #### DDPF_RGBTOYUV

          public static final int DDPF_RGBTOYUV

      See Also:
        Constant Field Values

    - #### DDPF_YUV

          public static final int DDPF_YUV

      See Also:
        Constant Field Values

    - #### DDPF_ZBUFFER

          public static final int DDPF_ZBUFFER

      See Also:
        Constant Field Values

    - #### DDPF_PALETTEINDEXED1

          public static final int DDPF_PALETTEINDEXED1

      See Also:
        Constant Field Values

    - #### DDPF_PALETTEINDEXED2

          public static final int DDPF_PALETTEINDEXED2

      See Also:
        Constant Field Values

    - #### DDPF_ZPIXELS

          public static final int DDPF_ZPIXELS

      See Also:
        Constant Field Values

    - #### DDSCAPS_TEXTURE

          public static final int DDSCAPS_TEXTURE

      See Also:
        Constant Field Values

    - #### DDSCAPS_MIPMAP

          public static final int DDSCAPS_MIPMAP

      See Also:
        Constant Field Values

    - #### DDSCAPS_COMPLEX

          public static final int DDSCAPS_COMPLEX

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP

          public static final int DDSCAPS2_CUBEMAP

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_POSITIVEX

          public static final int DDSCAPS2_CUBEMAP_POSITIVEX

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_NEGATIVEX

          public static final int DDSCAPS2_CUBEMAP_NEGATIVEX

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_POSITIVEY

          public static final int DDSCAPS2_CUBEMAP_POSITIVEY

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_NEGATIVEY

          public static final int DDSCAPS2_CUBEMAP_NEGATIVEY

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_POSITIVEZ

          public static final int DDSCAPS2_CUBEMAP_POSITIVEZ

      See Also:
        Constant Field Values

    - #### DDSCAPS2_CUBEMAP_NEGATIVEZ

          public static final int DDSCAPS2_CUBEMAP_NEGATIVEZ

      See Also:
        Constant Field Values

    - #### D3DFMT_UNKNOWN

          public static final int D3DFMT_UNKNOWN

      See Also:
        Constant Field Values

    - #### D3DFMT_R8G8B8

          public static final int D3DFMT_R8G8B8

      See Also:
        Constant Field Values

    - #### D3DFMT_A8R8G8B8

          public static final int D3DFMT_A8R8G8B8

      See Also:
        Constant Field Values

    - #### D3DFMT_X8R8G8B8

          public static final int D3DFMT_X8R8G8B8

      See Also:
        Constant Field Values

    - #### D3DFMT_DXT1

          public static final int D3DFMT_DXT1

      See Also:
        Constant Field Values

    - #### D3DFMT_DXT2

          public static final int D3DFMT_DXT2

      See Also:
        Constant Field Values

    - #### D3DFMT_DXT3

          public static final int D3DFMT_DXT3

      See Also:
        Constant Field Values

    - #### D3DFMT_DXT4

          public static final int D3DFMT_DXT4

      See Also:
        Constant Field Values

    - #### D3DFMT_DXT5

          public static final int D3DFMT_DXT5

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### read

          public static DDSImage read(String filename)
                               throws IOException

      Reads a DirectDraw surface from the specified file name, returning the resulting DDSImage.
      Parameters:
        `filename` - File name
      Returns:
        DDS image object
      Throws:
        `IOException` - if an I/O exception occurred

    - #### read

          public static DDSImage read(File file)
                               throws IOException

      Reads a DirectDraw surface from the specified file, returning the resulting DDSImage.
      Parameters:
        `file` - File object
      Returns:
        DDS image object
      Throws:
        `IOException` - if an I/O exception occurred

    - #### read

          public static DDSImage read(ByteBuffer buf)
                               throws IOException

      Reads a DirectDraw surface from the specified ByteBuffer, returning the resulting DDSImage.
      Parameters:
        `buf` - Input data
      Returns:
        DDS image object
      Throws:
        `IOException` - if an I/O exception occurred

    - #### close

          public void close()

      Closes open files and resources associated with the open DDSImage. No other methods may be called on this object once this is called.

    - #### createFromData

          public static DDSImage createFromData(int d3dFormat,
                                int width,
                                int height,
                                ByteBuffer[] mipmapData)
                                         throws IllegalArgumentException

      Creates a new DDSImage from data supplied by the user. The resulting DDSImage can be written to disk using the write() method.
      Parameters:
        `d3dFormat` - the D3DFMT_ constant describing the data; it is assumed that it is packed tightly
        `width` - the width in pixels of the topmost mipmap image
        `height` - the height in pixels of the topmost mipmap image
        `mipmapData` - the data for each mipmap level of the resulting DDSImage; either only one mipmap level should be specified, or they all must be
      Returns:
        DDS image object
      Throws:
        `IllegalArgumentException` - if the data does not match the specified arguments

    - #### isDDSImage

          public static boolean isDDSImage(InputStream in)
                                    throws IOException

      Determines from the magic number whether the given InputStream points to a DDS image. The given InputStream must return true from markSupported() and support a minimum of four bytes of read-ahead.
      Parameters:
        `in` - Stream to check
      Returns:
        true if input stream is DDS image or false otherwise
      Throws:
        `IOException` - if an I/O exception occurred

    - #### write

          public void write(String filename)
                     throws IOException

      Writes this DDSImage to the specified file name.
      Parameters:
        `filename` - File name to write to
      Throws:
        `IOException` - if an I/O exception occurred

    - #### write

          public void write(File file)
                     throws IOException

      Writes this DDSImage to the specified file name.
      Parameters:
        `file` - File object to write to
      Throws:
        `IOException` - if an I/O exception occurred

    - #### isSurfaceDescFlagSet

          public boolean isSurfaceDescFlagSet(int flag)

      Test for presence/absence of surface description flags (DDSD_*)
      Parameters:
        `flag` - DDSD_* flags set to test
      Returns:
        true if flag present or false otherwise

    - #### isPixelFormatFlagSet

          public boolean isPixelFormatFlagSet(int flag)

      Test for presence/absence of pixel format flags (DDPF_*)

    - #### getPixelFormat

          public int getPixelFormat()

      Gets the pixel format of this texture (D3DFMT_*) based on some heuristics. Returns D3DFMT_UNKNOWN if could not recognize the pixel format.

    - #### isCubemap

          public boolean isCubemap()

      Indicates whether this texture is cubemap
      Returns:
        true if cubemap or false otherwise

    - #### isCubemapSidePresent

          public boolean isCubemapSidePresent(int side)

      Indicates whethe this cubemap side present
      Parameters:
        `side` - Side to test
      Returns:
        true if side present or false otherwise

    - #### isCompressed

          public boolean isCompressed()

      Indicates whether this texture is compressed.

    - #### getCompressionFormat

          public int getCompressionFormat()

      If this surface is compressed, returns the kind of compression used (DXT1..DXT5).

    - #### getWidth

          public int getWidth()

      Width of the texture (or the top-most mipmap if mipmaps are present)

    - #### getHeight

          public int getHeight()

      Height of the texture (or the top-most mipmap if mipmaps are present)

    - #### getDepth

          public int getDepth()

      Total number of bits per pixel. Only valid if DDPF_RGB is present. For A8R8G8B8, would be 32.

    - #### getNumMipMaps

          public int getNumMipMaps()

      Number of mip maps in the texture

    - #### getMipMap

          public DDSImage.ImageInfo getMipMap(int map)

      Gets the ith mipmap data (0..getNumMipMaps() - 1)
      Parameters:
        `map` - Mipmap index
      Returns:
        Image object

    - #### getMipMap

          public DDSImage.ImageInfo getMipMap(int side,
                                     int map)

      Gets the ith mipmap data (0..getNumMipMaps() - 1)
      Parameters:
        `side` - Cubemap side or 0 for 2D texture
        `map` - Mipmap index
      Returns:
        Image object

    - #### getAllMipMaps

          public DDSImage.ImageInfo[] getAllMipMaps()

      Returns an array of ImageInfos corresponding to all mipmap levels of this DDS file.
      Returns:
        Mipmap image objects set

    - #### getAllMipMaps

          public DDSImage.ImageInfo[] getAllMipMaps(int side)

      Returns an array of ImageInfos corresponding to all mipmap levels of this DDS file.
      Parameters:
        `side` - Cubemap side or 0 for 2D texture
      Returns:
        Mipmap image objects set

    - #### getCompressionFormatName

          public static String getCompressionFormatName(int compressionFormat)

      Converts e.g. DXT1 compression format constant (see `getCompressionFormat()`) into "DXT1".
      Parameters:
        `compressionFormat` - Compression format constant
      Returns:
        String format code

    - #### allocateBlankBuffer

          public static ByteBuffer allocateBlankBuffer(int width,
                                       int height,
                                       int openGLInternalFormat)

      Allocates a temporary, empty ByteBuffer suitable for use in a call to glCompressedTexImage2D. This is used by the Texture class to expand non-power-of-two DDS compressed textures to power-of-two sizes on hardware not supporting OpenGL 2.0 and the NPOT texture extension. The specified OpenGL internal format must be one of GL_COMPRESSED_RGB_S3TC_DXT1_EXT, GL_COMPRESSED_RGBA_S3TC_DXT1_EXT, GL_COMPRESSED_RGBA_S3TC_DXT3_EXT, or GL_COMPRESSED_RGBA_S3TC_DXT5_EXT.

    - #### debugPrint

          public void debugPrint()

Copyright 2010 JogAmp Community.