iTextureHandle Struct Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions
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 bool | GetKeyColor () const =0
| Get the key color status (false if disabled, true if enabled).
virtual void | GetKeyColor (uint8 &red, uint8 &green, uint8 &blue) const =0
| Get the key color.
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)=0
| Return the original dimensions of the image used to create 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 bool | GetRendererDimensions (int &mw, int &mh)=0
| Get the dimensions the renderer uses for this texture.
virtual bool | GetRendererDimensions (int &mw, int &mh, int &md)=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< iDataBuffer > | Readback (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 (bool Enable)=0
| Enable key color.
virtual void | SetKeyColor (uint8 red, uint8 green, uint8 blue)=0
| Set the 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:

- iTextureManager::RegisterTexture()

Main ways to get pointers to this interface:

- iTextureWrapper::GetTextureHandle()

Main users of this interface:

- 3D renderer implementations (iGraphics3D).

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.

enum iTextureHandle::BlitBufferNature

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.

enum iTextureHandle::TextureBlitDataFormat

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.

enum iTextureHandle::TextureType

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 bool iTextureHandle::GetKeyColor | ( |  | ) | const`[pure virtual]`

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

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

Get the key color.

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
| ) |  | `[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 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 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 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 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 | ( | bool | Enable | ) | `[pure virtual]`

Enable key color.

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

Set the 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:

- ivideo/texture.h