|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.sun.opengl.util.texture.TextureIO
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.
Field Summary | |
static String |
DDS
Constant which can be used as a file suffix to indicate a DirectDraw Surface file. |
static String |
GIF
Constant which can be used as a file suffix to indicate a GIF file. |
static String |
JPG
Constant which can be used as a file suffix to indicate a JPEG file. |
static String |
PNG
Constant which can be used as a file suffix to indicate a PNG file. |
static String |
SGI
Constant which can be used as a file suffix to indicate an SGI RGB file. |
static String |
SGI_RGB
Constant which can be used as a file suffix to indicate an SGI RGB file. |
static String |
TGA
Constant which can be used as a file suffix to indicate a Targa file. |
static String |
TIFF
Constant which can be used as a file suffix to indicate a TIFF file. |
Constructor Summary | |
TextureIO()
|
Method Summary | |
static void |
addTextureProvider(TextureProvider provider)
Adds a TextureProvider to support reading of a new file format. |
static void |
addTextureWriter(TextureWriter writer)
Adds a TextureWriter to support writing of a new file format. |
static Texture |
newTexture(BufferedImage image,
boolean mipmap)
Creates an OpenGL texture object from the specified BufferedImage using the current OpenGL context. |
static Texture |
newTexture(File file,
boolean mipmap)
Creates an OpenGL texture object from the specified file using the current OpenGL context. |
static Texture |
newTexture(InputStream stream,
boolean mipmap,
String fileSuffix)
Creates an OpenGL texture object from the specified stream using the current OpenGL context. |
static Texture |
newTexture(int target)
Creates an OpenGL texture object associated with the given OpenGL texture target using the current OpenGL context. |
static Texture |
newTexture(TextureData data)
Creates an OpenGL texture object from the specified TextureData using the current OpenGL context. |
static Texture |
newTexture(URL url,
boolean mipmap,
String fileSuffix)
Creates an OpenGL texture object from the specified URL using the current OpenGL context. |
static TextureData |
newTextureData(BufferedImage image,
boolean mipmap)
Creates a TextureData from the given BufferedImage. |
static TextureData |
newTextureData(BufferedImage image,
int internalFormat,
int pixelFormat,
boolean mipmap)
Creates a TextureData from the given BufferedImage, using the specified OpenGL internal format and pixel format for the texture which will eventually result. |
static TextureData |
newTextureData(File file,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given file. |
static TextureData |
newTextureData(File file,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given file, using the specified OpenGL internal format and pixel format for the texture which will eventually result. |
static TextureData |
newTextureData(InputStream stream,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given stream. |
static TextureData |
newTextureData(InputStream stream,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given stream, using the specified OpenGL internal format and pixel format for the texture which will eventually result. |
static TextureData |
newTextureData(URL url,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given URL. |
static TextureData |
newTextureData(URL url,
int internalFormat,
int pixelFormat,
boolean mipmap,
String fileSuffix)
Creates a TextureData from the given URL, using the specified OpenGL internal format and pixel format for the texture which will eventually result. |
static void |
write(Texture texture,
File file)
Writes the given texture to a file. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final String DDS
public static final String SGI
public static final String SGI_RGB
public static final String GIF
public static final String JPG
public static final String PNG
public static final String TGA
public static final String TIFF
Constructor Detail |
public TextureIO()
Method Detail |
public static TextureData newTextureData(File file, boolean mipmap, String fileSuffix) throws IOException
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)
IOException
- if an error occurred while reading the filepublic static TextureData newTextureData(InputStream stream, boolean mipmap, String fileSuffix) throws IOException
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)
IOException
- if an error occurred while reading the streampublic static TextureData newTextureData(URL url, boolean mipmap, String fileSuffix) throws IOException
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)
IOException
- if an error occurred while reading the URLpublic static TextureData newTextureData(BufferedImage image, boolean mipmap)
image
- the BufferedImage containing the texture datamipmap
- whether mipmaps should be produced for this
texture by autogenerating them
public static TextureData newTextureData(File file, int internalFormat, int pixelFormat, boolean mipmap, String fileSuffix) throws IOException, IllegalArgumentException
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)
IllegalArgumentException
- if either internalFormat or
pixelFormat was 0
IOException
- if an error occurred while reading the filepublic static TextureData newTextureData(InputStream stream, int internalFormat, int pixelFormat, boolean mipmap, String fileSuffix) throws IOException, IllegalArgumentException
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)
IllegalArgumentException
- if either internalFormat or
pixelFormat was 0
IOException
- if an error occurred while reading the streampublic static TextureData newTextureData(URL url, int internalFormat, int pixelFormat, boolean mipmap, String fileSuffix) throws IOException, IllegalArgumentException
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)
IllegalArgumentException
- if either internalFormat or
pixelFormat was 0
IOException
- if an error occurred while reading the URLpublic static TextureData newTextureData(BufferedImage image, int internalFormat, int pixelFormat, boolean mipmap) throws IllegalArgumentException
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.
IllegalArgumentException
- if either internalFormat or
pixelFormat was 0public static Texture newTexture(TextureData data) throws GLException, IllegalArgumentException
data
- the texture data to turn into an OpenGL texture
GLException
- if no OpenGL context is current or if an
OpenGL error occurred
IllegalArgumentException
- if the passed TextureData was nullpublic static Texture newTexture(File file, boolean mipmap) throws IOException, GLException
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.
IOException
- if an error occurred while reading the file
GLException
- if no OpenGL context is current or if an
OpenGL error occurredpublic static Texture newTexture(InputStream stream, boolean mipmap, String fileSuffix) throws IOException, GLException
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)
IOException
- if an error occurred while reading the stream
GLException
- if no OpenGL context is current or if an
OpenGL error occurredpublic static Texture newTexture(URL url, boolean mipmap, String fileSuffix) throws IOException, GLException
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)
IOException
- if an error occurred while reading the URL
GLException
- if no OpenGL context is current or if an
OpenGL error occurredpublic static Texture newTexture(BufferedImage image, boolean mipmap) throws GLException
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 occurredpublic static Texture newTexture(int target) throws GLException
GLException
- if no OpenGL context is current or if an
OpenGL error occurredpublic static void write(Texture texture, File file) throws IOException, GLException
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.
IOException
- if an error occurred during writing or no
suitable writer was found
GLException
- if no OpenGL context was current or an
OpenGL-related error occurredpublic static void addTextureProvider(TextureProvider provider)
public static void addTextureWriter(TextureWriter writer)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |