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

Fields

Modifier and Type	Field and Description
static int	TEXTURE_NOTFOUND The id of a none-existent texture

Method Summary

Modifier and Type	Method and Description
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.
void	compress() Compresses all texture known to the TextureManager so that they use less main memory.
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	deVirtualize(Texture tex) Removes a texture from the virtualized set by recreating a state as if this texture has never been virtualized, i.e. pixel data will be stored in memory again the file which has been stored on disk has been removed.
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() Returns the VM memory used to store the texture data.
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.HashSet<java.lang.String>	getNames() Gets all the names of the textures that have been added to the manager.
java.util.List<?>	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.
Virtualizer	getVirtualizer() Returns the current Virtualizer.
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 like uploading all known textures if needed before the renderer is going to use them anyway.
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(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.List<?> dump) Sets the state of the TextureManager.
void	setVirtualizer(Virtualizer textureVirtualizer) Sets a new Virtualizer.
void	unloadTexture(FrameBuffer from, Texture texture) Unloads a texture from the contexts of the renderers of the given frame buffer.
void	virtualize(Texture tex) Virtualizes a textures if a Virtualizer has been set.

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.List<?> 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.List<?> 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

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

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

getMemoryUsage

public long getMemoryUsage()

Returns the VM memory used to store the texture data. Doesn't take the GPU memory into account.

Returns:

the memory in bytes

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.

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. 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(java.lang.String, 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)

flush

public void flush()

Flushes the textures in the manager. In other words: The manager doesn't contain any textures after calling flush(). Keep in mind that this method doesn't free any native memory usd to store the texture for the gpu. To free that, have a look at FrameBuffer.freeMemory();

See Also:

FrameBuffer.freeMemory()

compress

public void compress()

Compresses all texture known to the TextureManager so that they use less main memory. This doesn't effect the memory used inside the gpu.
Compressed textures require some more time to upload.

preWarm

public void preWarm(FrameBuffer buffer)

Does some work that may otherwise happen during runtime and can cause hick-ups like uploading all known textures if needed before the renderer is going to use them anyway.
This only affects the textures that the TextureManager currently knows. It has to be called within the render thread, i.e. within onDraw() for example.

Parameters:

buffer - the current frame buffer.

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.HashSet<java.lang.String> 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

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

setVirtualizer

public void setVirtualizer(Virtualizer textureVirtualizer)

Sets a new Virtualizer.

Parameters:

textureVirtualizer - The Virtualizer

getVirtualizer

public Virtualizer getVirtualizer()

Returns the current Virtualizer. By default, none is set.

Returns:

the virtualizer or null

virtualize

public void virtualize(Texture tex)

Virtualizes a textures if a Virtualizer has been set. This means that the texture might (and most likely will) be swapped to disk instead of being kept in memory. This doesn't affect the texture data uploaded to the GPU of course.
Note that you can't use an ITextureEffect on a virtualized texture.

Parameters:

tex - the Texture to virtualize. If it is virtual already, no actions will be taken.

deVirtualize

public void deVirtualize(Texture tex)

Removes a texture from the virtualized set by recreating a state as if this texture has never been virtualized, i.e. pixel data will be stored in memory again the file which has been stored on disk has been removed.

Parameters:

tex - the Texture to de-virtualize. If it's not virtual anyway, no actions will be taken.

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 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