com.threed.jpct
Class Texture

java.lang.Object
  extended by com.threed.jpct.Texture
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
NPOTTexture

public class Texture
extends java.lang.Object
implements java.io.Serializable

A Texture in jPCT-AE is a bitmap with a width/height of 2^x and a color-depth of 24 bpp with 8 bit alpha. You can enable 4bpp per texture, if you want to convert it to a 16 bit texture instead. This might be faster on some hardware.
If a texture with a different width/height is used, an error will be raised Textures are managed by the TextureManager.

See Also:
TextureManager, Serialized Form

Field Summary
static int DEFAULT_HEIGHT
          The default height of a texture (16 pixels).
static int DEFAULT_WIDTH
          The default width of a texture (16 pixels).
 
Constructor Summary
Texture(Bitmap image)
          Creates a texture using a Bitmap. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.
Texture(Bitmap image, boolean useAlpha)
          Creates a texture using a Bitmap. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.
Texture(Drawable image)
          Creates a texture using a Drawble. jPCT supports every format that JAVA supports for creating images from files as long as the result is a 24bpp image.
Texture(Drawable image, boolean useAlpha)
          Creates a texture using a Drawable. 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(int width, int height)
          Creates a black 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(int width, int height, RGBColor col)
          Creates a colored texture with no alpha in the given dimensions.
 
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 compress()
          Compresses the texture so that is uses less main memory.
static void defaultTo4bpp(boolean doit)
          Static method to set the textures' default depth to 4bpp (respectively 5bpp without a dedicated alpha channel).
static void defaultToKeepPixels(boolean doit)
          Static method to set the textures' default behaviour for keeping the pixel data after uploading to the gpu.
static void defaultToMipmapping(boolean doit)
          Static method to make all textures use mipmaps by default.
 void enable4bpp(boolean doit)
          Makes jPCT converting this texture to use 4 bits per pixel/alpha (respectively 5/1 without a dedicated alpha channel) instead of 8, i.e.
 void enableClamping()
          Deprecated.  
 int getArraySize()
          Returns the size of the texture array.
 DepthBuffer getDepthBuffer()
          Returns the depth buffer if one has been set or null otherwise.
 int getExternalId()
          Returns the external id if one has been set or -1 otherwise.
 int getHeight()
          Returns the height of the texture in pixels.
 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.
 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 setAsShadowMap(boolean isShadowMap)
          Marks this texture as a shadow map.
 void setClamping(boolean clamping)
          Set texture coordinate to clamping or wrapping/repeating.
 void setDepthBuffer(DepthBuffer depthBuffer)
          When used as a render target, jPCT-AE creates an internal depth buffer for this texture so that rendering into it works as expected.
 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 glTarget)
          Sets an external id.
 void setFiltering(boolean filter)
          Sets the bilinear filtering state on textures.
 void setMipmap(boolean mipmap)
          Enabled/Disables mip map setting for a texture.
 void setMipmapMode(int mode)
          Experimental, doesn't do much ATM.
 void setTextureCompression(boolean enabled)
          Enables ETC1-texture compression if available on the platform.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_WIDTH

public static final int DEFAULT_WIDTH
The default width of a texture (16 pixels).

See Also:
Constant Field Values

DEFAULT_HEIGHT

public static final int DEFAULT_HEIGHT
The default height of a texture (16 pixels).

See Also:
Constant Field Values
Constructor Detail

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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error. 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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error. 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.

Parameters:
is - the InputStream containing the data
useAlpha - use alpha information from texture?
See Also:
TextureManager

Texture

public Texture(Bitmap image)
Creates a texture using a Bitmap. 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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error.

Parameters:
image - the Bitmap
See Also:
TextureManager

Texture

public Texture(Bitmap image,
               boolean useAlpha)
Creates a texture using a Bitmap. 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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error. This method can be used to load a texture that provides an additional alpha channel.

Parameters:
image - the Bitmap
useAlpha - use alpha information from texture?
See Also:
TextureManager

Texture

public Texture(Drawable image)
Creates a texture using a Drawble. 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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error.

Parameters:
image - the Drawable
See Also:
TextureManager

Texture

public Texture(Drawable image,
               boolean useAlpha)
Creates a texture using a Drawable. 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. Supported texture sizes are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 and 8192 pixels in width and height. Any texture using other dimensions will raise an error. This method can be used to load a texture that provides an additional alpha channel.

Parameters:
image - the Drawable
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.
height - the height of the texture. Has to be a power of 2.

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,
               RGBColor 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.
height - the height of the texture. Has to be a power of 2.
col - the color. Can be null for render targets.
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.

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, no etc texture compression and the texture is 32bit 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.

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

enable4bpp

public void enable4bpp(boolean doit)
Makes jPCT converting this texture to use 4 bits per pixel/alpha (respectively 5/1 without a dedicated alpha channel) instead of 8, i.e. use 16 bit textures. Default is false unless you call Texture.defaultTo4bpp(true);

Parameters:
doit - should we?

defaultTo4bpp

public static void defaultTo4bpp(boolean doit)
Static method to set the textures' default depth to 4bpp (respectively 5bpp without a dedicated alpha channel). This doesn't affect the Texture instances themselves but the data uploaded to the graphics card.

Parameters:
doit - should 4bpp be the default?

defaultToKeepPixels

public static void defaultToKeepPixels(boolean doit)
Static method to set the textures' default behaviour for keeping the pixel data after uploading to the gpu. Default is true.

Parameters:
doit -

defaultToMipmapping

public static void defaultToMipmapping(boolean doit)
Static method to make all textures use mipmaps by default. Default setting is false.

Parameters:
doit - should mipmapping be the default?

setTextureCompression

public void setTextureCompression(boolean enabled)
Enables ETC1-texture compression if available on the platform. If not, jPCT-AE will fall back to normal textures. The usual restrictions for ETC1 apply.

Parameters:
enabled - enable ETC1 texture compression

compress

public void compress()
Compresses the texture so that is uses less main memory. This doesn't effect the memory used inside the gpu.
Compressed textures require some more time to upload. If the saved space is less than 5% of the original size, the texture won't be compressed.


getArraySize

public int getArraySize()
Returns the size of the texture array.

Returns:
the array size or 0, if no texel array is present

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

enableClamping

public void enableClamping()
Deprecated. 

Enables texture coordinate clamping instead of wrapping/repeating. 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. Calling this on an already uploaded texture forces a new texture upload to the graphics card.


setFiltering

public void setFiltering(boolean filter)
Sets the bilinear filtering state on textures. 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

setMipmap

public void setMipmap(boolean mipmap)
Enabled/Disables mip map setting for a texture. Default is true.

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

setMipmapMode

public void setMipmapMode(int mode)
Experimental, doesn't do much ATM. Ignore it for now.

Parameters:
mode - the mode, default is 0.

removeAlpha

public void removeAlpha()
Removes any alpha information from a texture.


removePixels

public void removePixels()
Removes the backing int-array from this texture. Only use this, if you know what you are doing...


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 true. Setting this to false will cause the texture to be corrupted on a context change.

Parameters:
keepData - should they?

setAsShadowMap

public void setAsShadowMap(boolean isShadowMap)
Marks this texture as a shadow map. This only affects the OpenGL ES 2.0 mode.

Parameters:
isShadowMap - is it a shadow map or not?

setDepthBuffer

public void setDepthBuffer(DepthBuffer depthBuffer)
When used as a render target, jPCT-AE creates an internal depth buffer for this texture so that rendering into it works as expected. If you want to share depth buffers between textures, because one rendering needs the buffer of the former, you can assign a DepthBuffer instance instead.
DepthBuffer and Texture have to have the same dimensions.
This will have no effect in OpenGL ES 1.x, it's a 2.0 feature only.

Parameters:
depthBuffer - the depth buffer

getDepthBuffer

public DepthBuffer getDepthBuffer()
Returns the depth buffer if one has been set or null otherwise.

Returns:
the depth buffer

setExternalId

public void setExternalId(int glId,
                          int glTarget)
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.

Parameters:
glId - the id
glTarget - the target, in most cases this will be GL10.GL_TEXTURE_2D.

getExternalId

public int getExternalId()
Returns the external id if one has been set or -1 otherwise.

Returns:
the id or -1