MTexture Class Reference

#include <MTextureManager.h>

Class Description

Public Member Functions

void * resourceHandle () const
 This method allows access to the draw API dependent handle for a texture. More...
 
const MStringname () const
 Get the name of the texture. More...
 
void textureDescription (MTextureDescription &desc) const
 Get texture description. More...
 
bool hasAlpha () const
 Get whether the texture has an alpha channel. More...
 
MStatus setHasAlpha (bool value)
 Specify that the texture has an alpha channel. More...
 
bool hasZeroAlpha () const
 Get whether the texture has any texels with an alpha value of 0.0. More...
 
MStatus setHasZeroAlpha (bool value)
 Specify that the texture has texels with an alpha value of 0.0. More...
 
bool hasTransparentAlpha () const
 Get whether the texture has semi-transparent texels. More...
 
MStatus setHasTransparentAlpha (bool value)
 Specify that the texture has texels with an alpha value greater than or equal to 0.0 and less than 1.0. More...
 
unsigned int bytesPerPixel () const
 Get the number of bytes per pixel in the texture. More...
 
void * rawData (int &rowPitch, int &slicePitch) const
 Get a copy of the raw data mapped to the texture. More...
 
MStatus update (const void *pixelData, bool generateMipMaps, unsigned int rowPitch=0, MHWRender::MTextureUpdateRegion *region=NULL)
 Update the contents of an image with new data. More...
 
MStatus update (const MImage &image, bool generateMipMaps)
 Update the contents of an image with new data. More...
 
MStatus update (const MObject &textureNode)
 Attempt to update the texture given a file texture node. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 
static void freeRawData (void *)
 Convenience method that simply deletes the data that is allocated in the MTexture::rawData() method. More...
 

Member Function Documentation

void * resourceHandle ( ) const

This method allows access to the draw API dependent handle for a texture.

This handle is owned by the renderer and is provided to allow access to use a texture as a read-only object.

Modifications should never be performed on this texture.

Any modifications to the texture may result in unpredictable stability as the renderer no longer has knowledge of the texture contents.

For OpenGL, a pointer to an OpenGL texture identifier is returned.

For DirectX 10 and higher a pointer to a shader resource view is returned.

Returns
A pointer (handle) to the texture if successful, otherwise NULL.
+ Examples:
const MString & name ( ) const

Get the name of the texture.

Returns
The name of the texture
bool hasAlpha ( ) const

Get whether the texture has an alpha channel.

Returns
true if the channel exists
MStatus setHasAlpha ( bool  value)

Specify that the texture has an alpha channel.

This will only set a flag indicating this property but will not change the contents of the texture.

Care should be taken as the texture is only tested for this property when it is first loaded in and will not be checked again after this method is called.

Parameters
[in]valueValue to set property to
Returns
Status code
Status Codes:
bool hasZeroAlpha ( ) const

Get whether the texture has any texels with an alpha value of 0.0.

Returns
true if such texels exist
MStatus setHasZeroAlpha ( bool  value)

Specify that the texture has texels with an alpha value of 0.0.

This will only set a flag indicating this property but will not change the contents of the texture.

Care should be taken as the texture is only tested for this property when it is first loaded in and will not be checked again after this method is called.

Parameters
[in]valueValue to set property to
Returns
Status code
Status Codes:
bool hasTransparentAlpha ( ) const

Get whether the texture has semi-transparent texels.

Such texels have an alpha value less than 1.0 and greater than or equal to 0.0.

Returns
true if such texels exist
MStatus setHasTransparentAlpha ( bool  value)

Specify that the texture has texels with an alpha value greater than or equal to 0.0 and less than 1.0.

This will only set a flag indicating this property but will not change the contents of the texture.

Care should be taken as the texture is only tested for this property when it is first loaded in and will not be checked again after this method is called.

Parameters
[in]valueValue to set property to
Returns
Status code
Status Codes:
unsigned int bytesPerPixel ( ) const

Get the number of bytes per pixel in the texture.

Returns
Byte count
+ Examples:
void * rawData ( int &  rowPitch,
int &  slicePitch 
) const

Get a copy of the raw data mapped to the texture.

The caller must deallocate the system memory as the texture itself does not keep any references to it. The convenience method MTexture::freeRawData() can be used to deallocate memory.

Texture arrays and compressed textures cannot currently be accessed with this method.

Parameters
[out]rowPitchThe row pitch of the data. It represents the number of bytes of one line of the texture data.
[out]slicePitchThe slice pitch of the data. It represents the number of bytes of the whole texture data.
Returns
A pointer to the data, or NULL on failure
+ Examples:
MStatus update ( const void *  pixelData,
bool  generateMipMaps,
unsigned int  rowPitch = 0,
MHWRender::MTextureUpdateRegion region = NULL 
)

Update the contents of an image with new data.

It is the responsibility of the caller to provide data which matches the description of the texture (MTextureDescription).

Texture arrays and compressed textures cannot currently be updated with this method.

Parameters
[in]pixelDataData to update the texture with
[in]generateMipMapsIndicate if mip-maps levels for the texture be rebuilt. If the texture already contains mip-maps then new mip-maps will be created by default.
[in]rowPitchThe row pitch of the incoming data. It represents the number of bytes of one line of data to update the texture. The default value of this argument is 0. This means to use the texture's width * the number of bytes per pixel.
[in]regionTexture sub-region to update. If a NULL is passed in then the input data is assumed to be updating the entire texture.
Returns
Status code
Status Codes:
+ Examples:
MStatus update ( const MImage image,
bool  generateMipMaps 
)

Update the contents of an image with new data.

It is the responsibility of the caller to provide data which matches the description of the texture (MTextureDescription). Only MImages with pixel type MPixelType::kByte are currently supported.

Texture arrays and compressed textures cannot currently be updated with this method.

Parameters
[in]imageImage containing data to update the texture with
[in]generateMipMapsIndicate if mip-maps levels for the texture be rebuilt. If the texture already contains mip-maps then new mip-maps will be created by default.
Returns
Status code
Status Codes:
MStatus update ( const MObject textureNode)

Attempt to update the texture given a file texture node.

If the texture is using uv tiles, then only the first tile will be returned.

Parameters
[in]textureNodeFile texture node
Returns
Status code
Status Codes:
const char * className ( )
static

Returns the name of this class.

Returns
Name of this class.
void freeRawData ( void *  data)
static

Convenience method that simply deletes the data that is allocated in the MTexture::rawData() method.

This method can be used to safely free data within a plug-in which is compiled in debug mode.

Parameters
[in]dataRaw data. After deletion the pointer no longer points to a valid memory location.

The documentation for this class was generated from the following files:
  • MTextureManager.h
  • MTextureManager.cpp