com.threed.jpct
Class Texture

java.lang.Object
  com.threed.jpct.Texture

All Implemented Interfaces:

java.io.Serializable

public class Texture

extends java.lang.Object

implements java.io.Serializable

A Texture in jPCT is a bitmap with a width/height of 2^x and a color-depth of 24 bpp. If a texture with a different width/height is used, it will be scaled to a width/height of 256 automatically, but a warning will be printed out because this shouldn't be the normal way to scale the textures... Textures are used to give objects a realistic looking surface as well as for some special effects. Textures are managed by the TextureManager class.
When using OpenGL support, the textures will be converted into an OpenGL-compatible format at runtime, so accessing a texture for the first time may result in little 'hickup' while the texture gets converted, but usually this shouldn't be noticeable.

See Also:

TextureManager, Serialized Form

Field Summary

static int	DEFAULT_BPP The default color-depth of 24 bpp.
static int	DEFAULT_HEIGHT The default height of a texture (256 pixels).
static int	DEFAULT_WIDTH The default width of a texture (256 pixels).

Constructor Summary

Texture(java.awt.Image image)
Creates a texture using a java.awt.Image. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.awt.Image image, boolean useAlpha)
Creates a texture using a java.awt.Imagem. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.io.InputStream is)
Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.io.InputStream is, boolean useAlpha)
Creates a texture using an image from file (usually in jpeg format). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.io.InputStream is, boolean useAlpha, boolean closeStream)
Creates a texture using an image from file (usually in jpeg format). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(int width, int height)
Creates a black texture with no alpha in the given dimensions.

Texture(int width, int height, java.awt.Color col)
Creates a colored texture with no alpha in the given dimensions.

Texture(int width, int height, int alpha)
Creates a black texture with alpha in the given dimensions.

Texture(java.lang.String filename)
Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.lang.String filename, boolean useAlpha)
Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.net.URL docBase, java.lang.String filename)
Creates a texture using an image from an URL (intended to be used in applets). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Texture(java.net.URL docBase, java.lang.String filename, boolean useAlpha)
Creates a texture using an image from an URL (intended to be used in applets). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.

Method Summary

void	add(Texture ta, float weight) Adds a textures color (and alpha) information to this one.
void	applyEffect() Applies the effect to the texture.
void	enableGLClamping() Deprecated.
int	getArraySize() Returns the size of the texture array. jPCT stores a little more for every texture than the actual texture data would need.
int	getByteSize() Deprecated.
int	getExternalId() Returns the external id if one has been set or -1 otherwise.
int	getHeight() Returns the height of the texture in pixels.
long	getLastFrame() Returns the number of the last frame the texture was used in.
int	getMemoryUsage() Returns the actual memory usage in VM memory.
int	getWidth() Returns the width of the texture in pixels.
boolean	isEnabled() Returns if the texture is enabled or not.
boolean	isShadowMap() Returns if this texture is used as a shadow map or not.
void	keepPixelData(boolean keepData) Should a texture's pixels be kept even when the texture has been uploaded to the GPU?
void	overrideTexelData(java.nio.ByteBuffer texels) This will override the actual texel data with the data from the buffer.
void	removeAlpha() Removes any alpha information from a texture.
void	removeEffect() Removes an ITextureEffect from the Texture
void	removePixels() Removes the backing int-array from this texture.
void	setAlpha(int al) Sets an alpha value for the whole texture
void	setAsShadowMap(boolean isShadowMap) Marks this texture as a shadow map.
void	setClamping(boolean clamping) Set texture coordinate to clamping or wrapping/repeating.
void	setEffect(ITextureEffect effect) Sets an effect for this texture.
void	setEnabled(boolean isEnabled) Sets the texture to enable/disabled.
void	setExternalId(int glId, int dontCare) Sets an external id.
void	setGLFiltering(boolean filter) Sets the bilinear filtering state on textures when using a GL renderer.
void	setGLMipmap(boolean mipmap) Deprecated.
void	setMipmap(boolean mipmap) Overrides a global mip map setting in Config for this particular texture.
void	setMipmapMode(int mode) Exists solely for compatibility with jPCT-AE.
void	setProjector(Projector proj, boolean reload) Sets a projector, i.e. this texture will be treated as if it would be projected onto the scene from the projector's position (and into its direction).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BPP

public static final int DEFAULT_BPP

The default color-depth of 24 bpp.

See Also:

Constant Field Values

DEFAULT_WIDTH

public static final int DEFAULT_WIDTH

The default width of a texture (256 pixels).

See Also:

Constant Field Values

DEFAULT_HEIGHT

public static final int DEFAULT_HEIGHT

The default height of a texture (256 pixels).

See Also:

Constant Field Values

Constructor Detail

Texture

public Texture(java.lang.String filename)

Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.

Parameters:

filename - the name of the texture

See Also:

TextureManager

Texture

public Texture(java.lang.String filename,
               boolean useAlpha)

Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This method can be used to load a texture that provides an additional alpha channel. jPCT will then use this channel when doing transparency in the OpenGL and the SoftGL renderers.

Parameters:

filename - the name of the texture

useAlpha - use alpha information from texture?

See Also:

TextureManager

Texture

public Texture(java.net.URL docBase,
               java.lang.String filename)

Creates a texture using an image from an URL (intended to be used in applets). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.

Parameters:

docBase - the document base

filename - the name of the texture

See Also:

TextureManager

Texture

public Texture(java.net.URL docBase,
               java.lang.String filename,
               boolean useAlpha)

Creates a texture using an image from an URL (intended to be used in applets). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This method can be used to load a texture that provides an additional alpha channel. jPCT will then use this channel when doing transparency in the OpenGL and the SoftGL renderers.

Parameters:

docBase - the document base

filename - the name of the texture

useAlpha - use alpha information from texture?

See Also:

TextureManager

Texture

public Texture(java.io.InputStream is)

Creates a texture using an image from file. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This variant can be used to get the data from an InputStream (for accessing files via getResourceAsStream() for example)

Parameters:

is - the InputStream for the data

See Also:

TextureManager

Texture

public Texture(java.io.InputStream is,
               boolean useAlpha)

Creates a texture using an image from file (usually in jpeg format). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This variant can be used to get the data from an InputStream (for accessing files via getResourceAsStream() for example)
This method can be used to load a texture that provides an additional alpha channel. jPCT will then use this channel when doing transparency in the OpenGL and the SoftGL renderers.

Parameters:

is - the InputStream containing the data

useAlpha - use alpha information from texture?

See Also:

TextureManager

Texture

public Texture(java.io.InputStream is,
               boolean useAlpha,
               boolean closeStream)

Creates a texture using an image from file (usually in jpeg format). jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This variant can be used to get the data from an InputStream (for accessing files via getResourceAsStream() for example)
This method can be used to load a texture that provides an additional alpha channel. jPCT will then use this channel when doing transparency in the OpenGL and the SoftGL renderers.

Parameters:

is - the InputStream containing the data

useAlpha - use alpha information from texture?

closeStream - should the stream be closed (true) or left open (false)

See Also:

TextureManager

Texture

public Texture(java.awt.Image image)

Creates a texture using a java.awt.Image. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.

Parameters:

image - an Image

See Also:

TextureManager

Texture

public Texture(java.awt.Image image,
               boolean useAlpha)

Creates a texture using a java.awt.Imagem. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image. A texture has to be added to a TextureManager to be of any use for the engine. Texture size has to be a power of 2. Any texture using another width and/or height will automatically be scaled to a width of 256 pixels. jPCT will print out a warning in this case.
This method can be used to load a texture that provides an additional alpha channel. jPCT will then use this channel when doing transparency in the OpenGL and the SoftGL renderers.

Parameters:

image - an Image

useAlpha - use alpha information from texture?

See Also:

TextureManager

Texture

public Texture(int width,
               int height)

Creates a black texture with no alpha in the given dimensions.

Parameters:

width - the width of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

height - the height of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

Texture

public Texture(int width,
               int height,
               int alpha)

Creates a black texture with alpha in the given dimensions.

Parameters:

width - the width of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

height - the height of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

alpha - the alpha value (0..255)

Texture

public Texture(int width,
               int height,
               java.awt.Color col)

Creates a colored texture with no alpha in the given dimensions.

Parameters:

width - the width of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

height - the height of the texture. Has to be a power of 2. If its not, it will be adjusted accordingly.

col - the color. If color is null, no int[]-array for texture data will be created in main memory.

Method Detail

add

public void add(Texture ta,
                float weight)

Adds a textures color (and alpha) information to this one.

Parameters:

ta - the texture whose color should be added

weight - the weight of the second texture's data. May be even negative.

setProjector

public void setProjector(Projector proj,
                         boolean reload)

Sets a projector, i.e. this texture will be treated as if it would be projected onto the scene from the projector's position (and into its direction). Any texture coordinates given to polygons which are using this texture will be ignored until the projector is set back to null again.
The software renderer will ignore this setting because it doesn't support projective texturing.
Using more projected textures in a scene than the hardware supports texture stages may result in a severe performance drop.

Parameters:

proj - the projector from which the texture is projected onto the scene. Set it to null to stop projection.

reload - if true, the texture will be uploaded again. This can be necessary if the texture has already been uploaded to the graphics card before the projector has been set. Remember that uploading textures is costly. Don't do this every frame.

setAsShadowMap

public void setAsShadowMap(boolean isShadowMap)

Marks this texture as a shadow map. As long as you are using the ShadowHelper to do shadows, this is not needed.

Parameters:

isShadowMap - is it a shadow map or not?

See Also:

ShadowHelper

isShadowMap

public boolean isShadowMap()

Returns if this texture is used as a shadow map or not.

Returns:

is it?

setEffect

public void setEffect(ITextureEffect effect)

Sets an effect for this texture. The effect is an implementation of ITextureEffect.

Parameters:

effect - the effect

See Also:

ITextureEffect

removeEffect

public void removeEffect()

Removes an ITextureEffect from the Texture

applyEffect

public void applyEffect()

Applies the effect to the texture. Depending on the implementation of the effect, this can be slow.

overrideTexelData

public void overrideTexelData(java.nio.ByteBuffer texels)

This will override the actual texel data with the data from the buffer. This will work only if no mip mapping is being used and the buffer has the correct size. All other cases will cause an error. The data won't survive a context change. Instead, the orginal texel data of that texture will be used instead.
This method provides a fast way of uploading texel data from other sources without the need for an ITextureEffect implementation.
This is limited to the OpenGL renderers. It has no effect when using the software renderer.

Parameters:

texels - the buffer with the texel data in RGBA-format.

setEnabled

public void setEnabled(boolean isEnabled)

Sets the texture to enable/disabled. A disabled texture won't show up when used on any texture stage except the first one. This setting has no influence on the software renderer, because it doesn't support stages higher than 0. Default it true.

Parameters:

isEnabled - is it enabled?

isEnabled

public boolean isEnabled()

Returns if the texture is enabled or not. A disabled texture won't show up when used on any texture stage except the first one.

Returns:

boolean is it?

getByteSize

public int getByteSize()

Deprecated.

Returns the size of the texture in bytes. jPCT stores a little more bytes for every texture than the actual texture data would need.
This method is deprecated, because it doesn't really return the size in bytes...it returns it in ints. I just don't want to fix this, because somebody may rely on this value. Use getArraySize() instead, which will return the same value.

Returns:

the size in bytes

getArraySize

public int getArraySize()

Returns the size of the texture array. jPCT stores a little more for every texture than the actual texture data would need.

Returns:

the array size

getMemoryUsage

public int getMemoryUsage()

Returns the actual memory usage in VM memory. This doesn't take GPU memory into account.

Returns:

the memory usage

getWidth

public int getWidth()

Returns the width of the texture in pixels.

Returns:

the width

getHeight

public int getHeight()

Returns the height of the texture in pixels.

Returns:

the height

getLastFrame

public long getLastFrame()

Returns the number of the last frame the texture was used in. This can help to optimize the usage of texture effects. This value is only valid when using a software renderer.

Returns:

the number of the frame

See Also:

World.getFrameCounter()

enableGLClamping

public void enableGLClamping()

Deprecated.

Enables texture coordinate clamping instead of wrapping/repeating for the OpenGL renderers. This doesn't affect the software renderers, which are always clamping/repeating depending on the renderer. Calling this on an already uploaded texture forces a new texture upload to the graphics card. This method is deprecated, use setClamping() instead.

setClamping

public void setClamping(boolean clamping)

Set texture coordinate to clamping or wrapping/repeating. This doesn't affect the software renderers, which are always clamping/repeating depending on the renderer. Calling this on an already uploaded texture forces a new texture upload to the graphics card.

setGLFiltering

public void setGLFiltering(boolean filter)

Sets the bilinear filtering state on textures when using a GL renderer. Setting this to false forces jPCT to use a pick nearest on the textures. This may also affect mip mapping.

Parameters:

filter - the mode, true for bilinear, false for pick nearest

setGLMipmap

public void setGLMipmap(boolean mipmap)

Deprecated.

Overrides a global mip map setting in Config for this particular texture.
This method is decprecated. use setMipMap(boolean) instead.

Parameters:

mipmap - true, if there's no override. false means no mip mapping/trilinear for this texture

See Also:

setMipmap(boolean)

setMipmap

public void setMipmap(boolean mipmap)

Overrides a global mip map setting in Config for this particular texture. Depending on the renderer, this setting overrides Config.glMipmap or Config.mipmap.

Parameters:

mipmap - true, if there's no override. false means no mip mapping/trilinear for this texture

setMipmapMode

public void setMipmapMode(int mode)

Exists solely for compatibility with jPCT-AE. Setting this value does nothing in desktop jPCT.

Parameters:

mode - some int, which doesn't matter

removeAlpha

public void removeAlpha()

Removes any alpha information from a texture. This is useful when using a texture with autogenerated alpha-channel in combination with shadow-mapping.

removePixels

public void removePixels()

Removes the backing int-array from this texture. Only use this, if you know what you are doing...

setAlpha

public void setAlpha(int al)

Sets an alpha value for the whole texture

Parameters:

al - the alpha value

keepPixelData

public void keepPixelData(boolean keepData)

Should a texture's pixels be kept even when the texture has been uploaded to the GPU? Default is false. The main purpose of this method is to stay compatible with jPCT-AE, which offers this method too. Here in jPCT, it's effect depends on the setting of Config.glAvoidTextureCopies. This method only has an effect, if that setting is true.

Parameters:

keepData - should they?

setExternalId

public void setExternalId(int glId,
                          int dontCare)

Sets an external id. This id can be obtained directly by OpenGL. This is a special method that allows to redirect a texture to some other that has been created outside of the engine's scope.
For normal use, this method isn't needed and can be ignored. The software renderer will ignore this setting.

Parameters:

glId - the id

dontCare - has no meaning in desktop jPCT. It's here to make the method signature equal to that of jPCT-AE

getExternalId

public int getExternalId()

Returns the external id if one has been set or -1 otherwise.

Returns:

the id or -1