com.threed.jpct
Class TextureManager

java.lang.Object
  com.threed.jpct.TextureManager

public final class TextureManager

extends java.lang.Object

The TextureManager is a singleton for storing and retrieving textures. Each texture managed by this class can be identified by a unique name. A texture managed by this class is an instance of Texture.

See Also:

Texture

Field Summary

static int

TEXTURE_NOTFOUND The id of a none-existent texture

Method Summary

void	addTexture(java.lang.String name) Adds a texture with the given name to the manager.
void	addTexture(java.lang.String name, Texture tex) Adds a texture with the given name to the manager.
boolean	containsTexture(java.lang.String name) Checks if a texture has already been added to the texture-manager (or better: if a texture with this name exists within the manager instance).
void	flush() Flushes the textures in the manager.
Texture	getDummyTexture() Returns the current dummy texture.
static TextureManager	getInstance() Returns an instance of the TextureManager.
long	getMemoryUsage(boolean localOnly) Returns the memory usage of all texture in the texture manager and in the GPU's memory.
java.lang.String	getNameByID(int id) Gets the name with which the texture with the given ID has been added to the manager.
java.lang.String	getNameByTexture(Texture texture) Returns the name with which the texture has been added to the manager.
java.util.Enumeration	getNames() Gets all the names of the textures that have been added to the manager.
java.util.Vector	getState() Dumps the current state of the TextureManager to a Vector.
Texture	getTexture(java.lang.String name) Returns the texture being named 'name'.
Texture	getTextureByID(int id) Returns the texture with the ID or null if no such texture can be found.
int	getTextureCount() Returns the number of textures the TextureManager holds.
int	getTextureID(java.lang.String name) Returns the numerical ID of the texture.
boolean	isForgiving() Returns if the TextureManager is in "forgiving" mode or not (default).
void	preWarm(FrameBuffer buffer) Does some work that may otherwise happen during runtime and can cause hick-ups.
boolean	preWarm(FrameBuffer buffer, int count) Special purpose version of preWarm(), which takes a count value in addition.
void	removeAndUnload(java.lang.String name, FrameBuffer from) Combines removal and unload of a texture.
void	removeTexture(java.lang.String name) Removes a texture from the manager.
void	replaceTexture(int id, Texture tex) Replaces a texture with the given id with another one.
void	replaceTexture(java.lang.String name, Texture tex) Replaces a texture with the given name with another one.
void	setDummyTexture(Texture texture) Sets a texture as dummy texture.
void	setForgiving(boolean forgiving) Sets "forgiving" mode.
void	setState(java.util.Vector dump) Sets the state of the TextureManager.
void	unloadTexture(FrameBuffer from, Texture texture) Unloads a texture from the contexts of the renderers of the given frame buffer.

Methods inherited from class java.lang.Object

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

Field Detail

TEXTURE_NOTFOUND

public static final int TEXTURE_NOTFOUND

The id of a none-existent texture

See Also:

getTextureID(java.lang.String), Constant Field Values

Method Detail

getInstance

public static TextureManager getInstance()

Returns an instance of the TextureManager. Because the manager is a singleton, only one instance per VM will be created (this is also done by getInstance() if none exists but that's a "don't care").

Returns:

the instance of the TextureManager

getState

public java.util.Vector getState()

Dumps the current state of the TextureManager to a Vector. If you are serializing this Vector, you may later setup the TextureManager at once with the deserialized dump. If you are not using serialization, ignore this method.

Returns:

the current state

setState

public void setState(java.util.Vector dump)

Sets the state of the TextureManager. You can use this to setup the TextureManager from a deserialized state dump. If you are not using serialization, ignore this method.

Parameters:

dump - the state dump

getMemoryUsage

public long getMemoryUsage(boolean localOnly)

Returns the memory usage of all texture in the texture manager and in the GPU's memory.

Parameters:

localOnly - if true, the GPU's memory usage won't be taken into account.

Returns:

the size in bytes

addTexture

public void addTexture(java.lang.String name)

Adds a texture with the given name to the manager. The name has to be unique, otherwise no texture will be added. The added texture will be filled with a dummy texture and may be replaced by another one later. This could be useful to render something without every texture being loaded (for slow connections for example).

Parameters:

name - the (unique) name for this texture

See Also:

replaceTexture(java.lang.String, com.threed.jpct.Texture)

addTexture

public void addTexture(java.lang.String name,
                       Texture tex)

Adds a texture with the given name to the manager. The name has to be unique, otherwise no texture will be added.

Parameters:

name - the (unique) name for this texture

tex - the texture

unloadTexture

public void unloadTexture(FrameBuffer from,
                          Texture texture)

Unloads a texture from the contexts of the renderers of the given frame buffer. This isn't done immediatly but in the next render pass for that buffer. You can try to unload any texture, it doesn't have to belong to the manager (...any longer). If a texture hasn't been uploaded, it will be ignored. If it's used after the unload, the renderer will upload it again. This is not needed if you disable a renderer, because that will unload the textures automatically.

Parameters:

from - the FrameBuffer

texture - the texture to unload

See Also:

removeAndUnload(java.lang.String, com.threed.jpct.FrameBuffer)

removeTexture

public void removeTexture(java.lang.String name)

Removes a texture from the manager. Because the manager doesn't know if a texture is still in use by some object, you have to be sure that it isn't before calling this method. This method removes the texture from the manager only. That doesn't mean, that it will be unloaded from video memory if OpenGL is being used. To ensure this, call unloadTexture() in addition or use removeAndUnload().
Please note that you can't expect an object that uses this texture to get a new texture that you might add with the same name after removing this one. If you want to replace textures on objects, use replaceTexture() instead.

Parameters:

name - the name of the texture to be removed

See Also:

unloadTexture(com.threed.jpct.FrameBuffer, com.threed.jpct.Texture), removeAndUnload(java.lang.String, com.threed.jpct.FrameBuffer), replaceTexture(int, com.threed.jpct.Texture)

removeAndUnload

public void removeAndUnload(java.lang.String name,
                            FrameBuffer from)

Combines removal and unload of a texture. Everything mentioned in the single methods applies here too.

Parameters:

name - the texture's name

from - the FrameBuffer

See Also:

unloadTexture(com.threed.jpct.FrameBuffer, com.threed.jpct.Texture), removeTexture(java.lang.String)

replaceTexture

public void replaceTexture(java.lang.String name,
                           Texture tex)

Replaces a texture with the given name with another one. It might be required to call unloadTexture() before to ensure that the old texture has been unloaded from the GPU in case it's no longer used somewhere else.

Parameters:

name - the (unique) name of the texture to replace

tex - the new texture

replaceTexture

public void replaceTexture(int id,
                           Texture tex)

Replaces a texture with the given id with another one. It might be required to call unloadTexture() before to ensure that the old texture has been unloaded from the GPU in case it's no longer used somewhere else.

Parameters:

id - the id of the texture to replace

tex - the new texture

flush

public void flush()

Flushes the textures in the manager. In other words: The manager doesn't contain any textures after calling flush(). Could be helpful in applets (for reloading).

preWarm

public void preWarm(FrameBuffer buffer)

Does some work that may otherwise happen during runtime and can cause hick-ups. This method isn't guaranteed to do anything, if the renderer doesn't offer any pre-warming.

Parameters:

buffer - the current frame buffer. The desired renderer should be enabled.

preWarm

public boolean preWarm(FrameBuffer buffer,
                       int count)

Special purpose version of preWarm(), which takes a count value in addition. This method will stop if it has processed the given amount of texture instances.
This can be used to prewarm textures in a loop and update some kind of progress bar.

Parameters:

buffer - the current frame buffer. The desired renderer should be enabled.

count - the maximum number of processing requests

Returns:

true, if all available resources have been processed (i.e. no more work to do). Otherwise false.

setDummyTexture

public void setDummyTexture(Texture texture)

Sets a texture as dummy texture. If no dummy texture is set, a default one (256*256, all white) will be used.

Parameters:

texture - the new dummy texture

getDummyTexture

public Texture getDummyTexture()

Returns the current dummy texture.

Returns:

the dummy texture

containsTexture

public boolean containsTexture(java.lang.String name)

Checks if a texture has already been added to the texture-manager (or better: if a texture with this name exists within the manager instance).

Parameters:

name - the name of the texture

Returns:

true, if the manager has such a texture, otherwise false

getTextureCount

public int getTextureCount()

Returns the number of textures the TextureManager holds.

Returns:

the number

getTextureID

public int getTextureID(java.lang.String name)

Returns the numerical ID of the texture. This value is used internally to access textures faster than by using their names. Some methods use this ID instead of the unique name or the texture itself for performance reasons.

Parameters:

name - the name of the texture

Returns:

the ID of this texture or TEXTURE_NOTFOUND

getTextureByID

public Texture getTextureByID(int id)

Returns the texture with the ID or null if no such texture can be found.

Parameters:

id - int the ID

Returns:

Texture the texture having this ID

getTexture

public Texture getTexture(java.lang.String name)

Returns the texture being named 'name'.

Parameters:

name - the name of the texture that should be retrieved

Returns:

the texture with this name (or null in case of error)

getNames

public java.util.Enumeration getNames()

Gets all the names of the textures that have been added to the manager.

Returns:

the names

getNameByID

public java.lang.String getNameByID(int id)

Gets the name with which the texture with the given ID has been added to the manager.

Parameters:

id - the texture's ID

Returns:

String the name, or null if no such texture exists

getNameByTexture

public java.lang.String getNameByTexture(Texture texture)

Returns the name with which the texture has been added to the manager. If the texture has been added multiple times but with different names, some name will be returned.

Parameters:

texture -

Returns:

the name or null, if the texture can't be found

isForgiving

public boolean isForgiving()

Returns if the TextureManager is in "forgiving" mode or not (default).

Returns:

is it?

setForgiving

public void setForgiving(boolean forgiving)

Sets "forgiving" mode. A TextureManager in forgiving mode allows you to add a texture with an existing name. It will simply replace that texture instead. If forgiving is false, it will raise an error.

Parameters:

forgiving - the mode