com.sun.opengl.util.texture.spi
Class DDSImage

java.lang.Object
  com.sun.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

static class

DDSImage.ImageInfo Simple class describing images and data; does not encapsulate image format information.

Field Summary

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

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

clone, equals, finalize, 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()