Provides input and output facilities for both loading OpenGL
textures from disk and streams as well as writing textures already
in memory back to disk.
The TextureIO class supports an arbitrary number of plug-in
readers and writers via TextureProviders and TextureWriters.
TextureProviders know how to produce TextureData objects from
files, InputStreams and URLs. TextureWriters know how to write
TextureData objects to disk in various file formats. The
TextureData class represents the raw data of the texture before it
has been converted to an OpenGL texture object. The Texture class
represents the OpenGL texture object and provides easy facilities
for using the texture.
There are several built-in TextureProviders and TextureWriters
supplied with the TextureIO implementation. The most basic
provider uses the platform's Image I/O facilities to read in a
BufferedImage and convert it to a texture. This is the baseline
provider and is registered so that it is the last one consulted.
All others are asked first to open a given file.
There are three other providers registered by default as of
the time of this writing. One handles SGI RGB (".sgi", ".rgb")
images from both files and streams. One handles DirectDraw Surface
(".dds") images read from files, though can not read these images
from streams. One handles Targa (".tga") images read from both
files and streams. These providers are executed in an arbitrary
order. Some of these providers require the file's suffix to either
be specified via the newTextureData methods or for the file to be
named with the appropriate suffix. In general a file suffix should
be provided to the newTexture and newTextureData methods if at all
possible.
Note that additional TextureProviders, if reading images from
InputStreams, must use the mark()/reset() methods on InputStream
when probing for e.g. magic numbers at the head of the file to
make sure not to disturb the state of the InputStream for
downstream TextureProviders.
There are analogous TextureWriters provided for writing
textures back to disk if desired. As of this writing, there are
four TextureWriters registered by default: one for Targa files,
one for SGI RGB files, one for DirectDraw surface (.dds) files,
and one for ImageIO-supplied formats such as .jpg and .png. Some
of these writers have certain limitations such as only being able
to write out textures stored in GL_RGB or GL_RGBA format. The DDS
writer supports fetching and writing to disk of texture data in
DXTn compressed format. Whether this will occur is dependent on
whether the texture's internal format is one of the DXTn
compressed formats and whether the target file is .dds format.
DDS
public static final String DDS
Constant which can be used as a file suffix to indicate a
DirectDraw Surface file.
GIF
public static final String GIF
Constant which can be used as a file suffix to indicate a GIF
file.
JPG
public static final String JPG
Constant which can be used as a file suffix to indicate a JPEG
file.
PNG
public static final String PNG
Constant which can be used as a file suffix to indicate a PNG
file.
SGI
public static final String SGI
Constant which can be used as a file suffix to indicate an SGI
RGB file.
SGI_RGB
public static final String SGI_RGB
Constant which can be used as a file suffix to indicate an SGI
RGB file.
TGA
public static final String TGA
Constant which can be used as a file suffix to indicate a Targa
file.
TIFF
public static final String TIFF
Constant which can be used as a file suffix to indicate a TIFF
file.
addTextureProvider
public static void addTextureProvider(TextureProvider provider)
Adds a TextureProvider to support reading of a new file
format.
addTextureWriter
public static void addTextureWriter(TextureWriter writer)
Adds a TextureWriter to support writing of a new file
format.
isTexRectEnabled
public static boolean isTexRectEnabled()
Indicates whether the GL_ARB_texture_rectangle extension is
allowed to be used for non-power-of-two textures; see
setTexRectEnabled
.
newTexture
public static Texture newTexture(BufferedImage image,
boolean mipmap)
throws GLException
Creates an OpenGL texture object from the specified BufferedImage
using the current OpenGL context.
image
- the BufferedImage from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture by autogenerating them
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTexture
public static Texture newTexture(File file,
boolean mipmap)
throws IOException,
GLException
Creates an OpenGL texture object from the specified file using
the current OpenGL context.
file
- the file from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTexture
public static Texture newTexture(InputStream stream,
boolean mipmap,
String fileSuffix)
throws IOException,
GLException
Creates an OpenGL texture object from the specified stream using
the current OpenGL context.
stream
- the stream from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTexture
public static Texture newTexture(URL url,
boolean mipmap,
String fileSuffix)
throws IOException,
GLException
Creates an OpenGL texture object from the specified URL using the
current OpenGL context.
url
- the URL from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTexture
public static Texture newTexture(TextureData data)
throws GLException,
IllegalArgumentException
Creates an OpenGL texture object from the specified TextureData
using the current OpenGL context.
data
- the texture data to turn into an OpenGL texture
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTexture
public static Texture newTexture(int target)
throws GLException
Creates an OpenGL texture object associated with the given OpenGL
texture target using the current OpenGL context. The texture has
no initial data. This is used, for example, to construct cube
maps out of multiple TextureData objects.
target
- the OpenGL target type, eg GL.GL_TEXTURE_2D,
GL.GL_TEXTURE_RECTANGLE_ARB
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
newTextureData
public static TextureData newTextureData(BufferedImage image,
boolean mipmap)
Creates a TextureData from the given BufferedImage. Does no
OpenGL work.
image
- the BufferedImage containing the texture datamipmap
- whether mipmaps should be produced for this
texture by autogenerating them
- the texture data from the image
newTextureData
public static TextureData newTextureData(BufferedImage image,
int internalFormat,
int pixelFormat,
boolean mipmap)
throws IllegalArgumentException
Creates a TextureData from the given BufferedImage, using the
specified OpenGL internal format and pixel format for the texture
which will eventually result. The internalFormat and pixelFormat
must be specified and may not be zero; to use default values, use
the variant of this method which does not take these
arguments. Does no OpenGL work.
image
- the BufferedImage containing the texture datainternalFormat
- the OpenGL internal format of the texture
which will eventually result from the TextureDatapixelFormat
- the OpenGL pixel format of the texture
which will eventually result from the TextureDatamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.
- the texture data from the image
newTextureData
public static TextureData newTextureData(File file,
boolean mipmap,
String fileSuffix)
throws IOException
Creates a TextureData from the given file. Does no OpenGL work.
file
- the file from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the file, or null if none of the
registered texture providers could read the file
newTextureData
public static TextureData newTextureData(File file,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
throws IOException,
IllegalArgumentException
Creates a TextureData from the given file, using the specified
OpenGL internal format and pixel format for the texture which
will eventually result. The internalFormat and pixelFormat must
be specified and may not be zero; to use default values, use the
variant of this method which does not take these arguments. Does
no OpenGL work.
file
- the file from which to read the texture datainternalFormat
- the OpenGL internal format of the texture
which will eventually result from the TextureDatapixelFormat
- the OpenGL pixel format of the texture
which will eventually result from the TextureDatamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the file, or null if none of the
registered texture providers could read the file
newTextureData
public static TextureData newTextureData(InputStream stream,
boolean mipmap,
String fileSuffix)
throws IOException
Creates a TextureData from the given stream. Does no OpenGL work.
stream
- the stream from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the stream, or null if none of the
registered texture providers could read the stream
newTextureData
public static TextureData newTextureData(InputStream stream,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
throws IOException,
IllegalArgumentException
Creates a TextureData from the given stream, using the specified
OpenGL internal format and pixel format for the texture which
will eventually result. The internalFormat and pixelFormat must
be specified and may not be zero; to use default values, use the
variant of this method which does not take these arguments. Does
no OpenGL work.
stream
- the stream from which to read the texture datainternalFormat
- the OpenGL internal format of the texture
which will eventually result from the TextureDatapixelFormat
- the OpenGL pixel format of the texture
which will eventually result from the TextureDatamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the stream, or null if none of the
registered texture providers could read the stream
newTextureData
public static TextureData newTextureData(URL url,
boolean mipmap,
String fileSuffix)
throws IOException
Creates a TextureData from the given URL. Does no OpenGL work.
url
- the URL from which to read the texture datamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the URL, or null if none of the
registered texture providers could read the URL
newTextureData
public static TextureData newTextureData(URL url,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
throws IOException,
IllegalArgumentException
Creates a TextureData from the given URL, using the specified
OpenGL internal format and pixel format for the texture which
will eventually result. The internalFormat and pixelFormat must
be specified and may not be zero; to use default values, use the
variant of this method which does not take these arguments. Does
no OpenGL work.
url
- the URL from which to read the texture datainternalFormat
- the OpenGL internal format of the texture
which will eventually result from the TextureDatapixelFormat
- the OpenGL pixel format of the texture
which will eventually result from the TextureDatamipmap
- whether mipmaps should be produced for this
texture either by autogenerating them or
reading them from the file. Some file formats
support multiple mipmaps in a single file in
which case those mipmaps will be used rather
than generating them.fileSuffix
- the suffix of the file name to be used as a
hint of the file format to the underlying
texture provider, or null if none and should be
auto-detected (some texture providers do not
support this)
- the texture data from the URL, or null if none of the
registered texture providers could read the URL
setTexRectEnabled
public static void setTexRectEnabled(boolean enabled)
Toggles the use of the GL_ARB_texture_rectangle extension by the
TextureIO classes. By default, on hardware supporting this
extension, the TextureIO classes may use the
GL_ARB_texture_rectangle extension for non-power-of-two
textures. (If the hardware supports the
GL_ARB_texture_non_power_of_two extension, that one is
preferred.) In some situations, for example when writing
shaders, it is advantageous to force the texture target to
always be GL_TEXTURE_2D in order to have one version of the
shader, even at the expense of texture memory in the case where
NPOT textures are not supported. This method allows the use of
the GL_ARB_texture_rectangle extension to be turned off globally
for this purpose. The default is that the use of the extension
is enabled.
write
public static void write(Texture texture,
File file)
throws IOException,
GLException
Writes the given texture to a file. The type of the file is
inferred from its suffix. An OpenGL context must be current in
order to fetch the texture data back from the OpenGL pipeline.
This method causes the specified Texture to be bound to the
GL_TEXTURE_2D state. If no suitable writer for the requested file
format was found, throws an IOException.
Reasonable attempts are made to produce good results in the
resulting images. The Targa, SGI and ImageIO writers produce
results in the correct vertical orientation for those file
formats. The DDS writer performs no vertical flip of the data,
even in uncompressed mode. (It is impossible to perform such a
vertical flip with compressed data.) Applications should keep
this in mind when using this routine to save textures to disk for
later re-loading.
Any mipmaps for the specified texture are currently discarded
when it is written to disk, regardless of whether the underlying
file format supports multiple mipmaps in a given file.
GLException
- if no OpenGL context was current or an
OpenGL-related error occurred