CrystalSpace

Public API Reference

iTextureHandle Struct Reference
[3D]

A texture handle as returned by iTextureManager. More...

#include <ivideo/texture.h>

Inheritance diagram for iTextureHandle:

List of all members.

Public Types

enum  
 

Texture Depth Indices are used for Cubemap interface.

More...
enum  { blitbufReadable = 1, blitbufRetainArea = 2 }
enum  BlitBufferNature { natureIndirect = 0, natureDirect = 1 }
 

Characteristics of a blit buffer.

More...
enum  TextureBlitDataFormat { RGBA8888 = 0, BGRA8888 }
 

Format of the pixel data that is passed to iTextureHandle->Blit().

More...
enum  TextureType {
  texType1D = 0, texType2D, texType3D, texTypeCube,
  texTypeRect
}
 

Possible texture types.

More...

Public Member Functions

virtual void ApplyBlitBuffer (uint8 *buf)=0
 Apply the given blitting buffer.
virtual void Blit (int x, int y, int width, int height, unsigned char const *data, TextureBlitDataFormat format=RGBA8888)=0
 Blit a memory block to this texture.
virtual csAlphaMode::AlphaType GetAlphaType () const =0
 Get the type of alpha associated with the texture.
virtual int GetFlags () const =0
 Retrieve the flags set for this texture.
virtual const char * GetImageName () const =0
 Get the original image name.
virtual void GetKeyColor (uint8 &red, uint8 &green, uint8 &blue) const =0
 Get the key color.
virtual bool GetKeyColor () const =0
 Get the key color status (false if disabled, true if enabled).
virtual void GetMipmapLimits (int &maxMip, int &minMip)=0
 Get the highest and lowest used mipmap for this texture.
virtual void GetOriginalDimensions (int &mw, int &mh, int &md)=0
 Return the original dimensions of the image used to create this texture.
virtual void GetOriginalDimensions (int &mw, int &mh)=0
 Return the original dimensions of the image used to create this texture.
virtual bool GetRendererDimensions (int &mw, int &mh, int &md)=0
 Get the dimensions the renderer uses for this texture.
virtual bool GetRendererDimensions (int &mw, int &mh)=0
 Get the dimensions the renderer uses for this texture.
virtual const char * GetTextureClass ()=0
 Get the "class" of a texture.
virtual TextureType GetTextureType () const =0
 Get the texture type (2D, 3D, cube map, RECT texture .
virtual bool IsPrecached ()=0
 Check if this texture has already been precached.
virtual void Precache ()=0
 Precache this texture.
virtual uint8 * QueryBlitBuffer (int x, int y, int width, int height, size_t &pitch, TextureBlitDataFormat format=RGBA8888, uint bufFlags=0)=0
 Query a buffer for blitting.
virtual csPtr< iDataBufferReadback (const CS::StructuredTextureFormat &format, int mip=0)=0
 Read back the data of the texture in the given format.
virtual void SetAlphaType (csAlphaMode::AlphaType alphaType)=0
 Set the type of alpha associated with the texture.
virtual void SetKeyColor (uint8 red, uint8 green, uint8 blue)=0
 Set the key color.
virtual void SetKeyColor (bool Enable)=0
 Enable key color.
virtual void SetMipmapLimits (int maxMip, int minMip=0)=0
 Set the highest and lowest used mipmap for this texture.
virtual void SetTextureClass (const char *className)=0
 Set the "class" of this texture.

Detailed Description

A texture handle as returned by iTextureManager.

Main creators of instances implementing this interface:

Main ways to get pointers to this interface:

Main users of this interface:

Definition at line 53 of file texture.h.


Member Enumeration Documentation

anonymous enum

Texture Depth Indices are used for Cubemap interface.

Definition at line 94 of file texture.h.

anonymous enum
Enumerator:
blitbufReadable 

The buffer will also be read from, so make sure it's readable.

blitbufRetainArea 

The returned buffer should mirror the current contents of the requested area on the texture.

If this flag is not present the buffer contents will be undefined and should thus be reset entirely. However, setting this flag may incur a performance penalty.

Definition at line 204 of file texture.h.

Characteristics of a blit buffer.

Enumerator:
natureIndirect 

The returned buffer is an intermediate buffer which is applied only indirectly, possibly with a call to a foreign module.

This information is mostly useful in cases where some state has to be set before a foreign call could possibly occur. An examples for such action is code that utilizes MMX which should execute the 'emms' instruction before foreign code is called.

natureDirect 

The returned buffer is actually a direct pointer to the texture storage.

Definition at line 243 of file texture.h.

Format of the pixel data that is passed to iTextureHandle->Blit().

Enumerator:
RGBA8888 

RGBA, 8 bits per pixel.

BGRA8888 

BGRA, 8 bits per pixel.

Definition at line 120 of file texture.h.

Possible texture types.

Enumerator:
texType1D 

1D texture

texType2D 

2D texture

texType3D 

3D texture

texTypeCube 

Cube map.

texTypeRect 

Rectangle texture.

Definition at line 183 of file texture.h.


Member Function Documentation

virtual void iTextureHandle::ApplyBlitBuffer ( uint8 *  buf  )  [pure virtual]

Apply the given blitting buffer.

virtual void iTextureHandle::Blit ( int  x,
int  y,
int  width,
int  height,
unsigned char const *  data,
TextureBlitDataFormat  format = RGBA8888 
) [pure virtual]

Blit a memory block to this texture.

Format of the image is determined by the format parameter. Row by row.

Remarks:
If the specified target rectangle exceeds the texture dimensions the Blit() call may have no effect. It's the responsibility of the caller to ensure that the rectangle lies completely inside the texture.
virtual csAlphaMode::AlphaType iTextureHandle::GetAlphaType (  )  const [pure virtual]

Get the type of alpha associated with the texture.

virtual int iTextureHandle::GetFlags (  )  const [pure virtual]

Retrieve the flags set for this texture.

virtual const char* iTextureHandle::GetImageName (  )  const [pure virtual]

Get the original image name.

virtual void iTextureHandle::GetKeyColor ( uint8 &  red,
uint8 &  green,
uint8 &  blue 
) const [pure virtual]

Get the key color.

virtual bool iTextureHandle::GetKeyColor (  )  const [pure virtual]

Get the key color status (false if disabled, true if enabled).

virtual void iTextureHandle::GetMipmapLimits ( int &  maxMip,
int &  minMip 
) [pure virtual]

Get the highest and lowest used mipmap for this texture.

virtual void iTextureHandle::GetOriginalDimensions ( int &  mw,
int &  mh,
int &  md 
) [pure virtual]

Return the original dimensions of the image used to create this texture.

This is most often equal to GetMipMapDimensions (0, mw, mh, md) but in some cases the texture will have been resized in order to accomodate hardware restrictions (like power of two and maximum texture size). This function returns the uncorrected coordinates.

virtual void iTextureHandle::GetOriginalDimensions ( int &  mw,
int &  mh 
) [pure virtual]

Return the original dimensions of the image used to create this texture.

This is most often equal to GetMipMapDimensions (0, mw, mh) but in some cases the texture will have been resized in order to accomodate hardware restrictions (like power of two and maximum texture size). This function returns the uncorrected coordinates.

virtual bool iTextureHandle::GetRendererDimensions ( int &  mw,
int &  mh,
int &  md 
) [pure virtual]

Get the dimensions the renderer uses for this texture.

In most cases this corresponds to the size that was used to create this texture, but some renderers have texture size limitations (like power of two) and in that case the size returned here will be the corrected size. You can get the original image size with GetOriginalDimensions().

Returns:
Whether the renderer-used dimensions could be determined.
virtual bool iTextureHandle::GetRendererDimensions ( int &  mw,
int &  mh 
) [pure virtual]

Get the dimensions the renderer uses for this texture.

In most cases this corresponds to the size that was used to create this texture, but some renderers have texture size limitations (like power of two) and in that case the size returned here will be the corrected size. You can get the original image size with GetOriginalDimensions().

Returns:
Whether the renderer-used dimensions could be determined.
virtual const char* iTextureHandle::GetTextureClass (  )  [pure virtual]

Get the "class" of a texture.

See also:
SetTextureClass
virtual TextureType iTextureHandle::GetTextureType (  )  const [pure virtual]

Get the texture type (2D, 3D, cube map, RECT texture .

..). Note that the texture type is determined by the image from which the texture was created and possibly the texture flags.

virtual bool iTextureHandle::IsPrecached (  )  [pure virtual]

Check if this texture has already been precached.

virtual void iTextureHandle::Precache (  )  [pure virtual]

Precache this texture.

This might free up temporary memory and makes later usage of the texture faster.

virtual uint8* iTextureHandle::QueryBlitBuffer ( int  x,
int  y,
int  width,
int  height,
size_t &  pitch,
TextureBlitDataFormat  format = RGBA8888,
uint  bufFlags = 0 
) [pure virtual]

Query a buffer for blitting.

Multiple areas
If multiple areas of the texture are to be updated, call QueryBlitBuffer () for a new area before you call ApplyBlitBuffer () for the prior one. That is, the order of calls should be like:
   uint8* buf1 = texture->QueryBlitBuffer (...);
   // ... Change buf1 ...
   uint8* buf2 = texture->QueryBlitBuffer (...);
   texture->ApplyBlitBuffer (buf1);
   // ... Change buf1 ...
   // And so on
This "interleaving" will result in greater runtime performance as some resources can be re-used.

When multiple queried areas overlap the overlapping areas will contain undefined data on the texture.

virtual csPtr<iDataBuffer> iTextureHandle::Readback ( const CS::StructuredTextureFormat format,
int  mip = 0 
) [pure virtual]

Read back the data of the texture in the given format.

Remarks:
To obtain the fastest possible readbacks:
  • If you read back the data frequently (e.g. from a render target used to render the scene) use the CSDRAW_READBACK draw flag when drawing the scene.
  • Access the actual data in a delayed fashion (e.g. the next frame) to facilitate asynchronous transfers.
  • Read back in the format the texture was created with.
  • Certain formats are faster than others. (This is hardware-dependent, but usually choosing one of argb8, abgr16_f or abgr32_f gives good results. Again, texture and readback format should match.)
virtual void iTextureHandle::SetAlphaType ( csAlphaMode::AlphaType  alphaType  )  [pure virtual]

Set the type of alpha associated with the texture.

Usually, the alpha mode is auto-detected (alphaSmooth on images with alpha channels, alphaBinary on keycolored images, alphaNone otherwise), but can be overridden with this method.

virtual void iTextureHandle::SetKeyColor ( uint8  red,
uint8  green,
uint8  blue 
) [pure virtual]

Set the key color.

virtual void iTextureHandle::SetKeyColor ( bool  Enable  )  [pure virtual]

Enable key color.

virtual void iTextureHandle::SetMipmapLimits ( int  maxMip,
int  minMip = 0 
) [pure virtual]

Set the highest and lowest used mipmap for this texture.

virtual void iTextureHandle::SetTextureClass ( const char *  className  )  [pure virtual]

Set the "class" of this texture.

A texture class is used to set some characteristics on how a texture is handled at runtime. For example, graphics hardware usually offers texture compression, but it can cause a loss of quality and precision and thus may not be desireable for all data. In this case, a class can be set on the texture that instructs the renderer to not apply texture compression.

Remarks:
Not all renderers may support texture classes.
See also:
GetTextureClass

The documentation for this struct was generated from the following file:

Generated for Crystal Space 2.0 by doxygen 1.6.1