- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MImage Class Reference

# OpenMaya - API module for common classes

This reference page is linked to from the following overview topics: A hardware shading node plug-in example.

Search for all occurrences

## Detailed Description

Image manipulation.

This class provides methods for reading file images stored on disk.

MImage is a class which provides access to some of Maya's image manipulation functionality. It has methods for loading and resizing image files in any Maya-supported raster format, including IFF, SGI, Softimage (pic), TIFF (tif), Alias PIX (als), GIF, RLA, JPEG (jpg). The image is stored as an uncompressed array of pixels, that can be read and manipulated directly. For simplicity, the pixels are stored in a RGBA format (4 bytes per pixel).

Examples:

  cgfxAttrDef.cpp, cgfxAttrDef.h, cgfxShaderNode.cpp, cgfxShaderNode.h, convertBumpCmd.cpp, customImagePlane.cpp, D3DViewportRenderer.h, ddsFloatReader.cpp, GLSLShaderNode.cpp, GLSLShaderNode.h, hlslShader.cpp, hlslShader.h, hwAnisotropicShader_NV20.cpp, hwColorPerVertexShader.cpp, hwManagedTextureShader.cpp, hwPhongShader.cpp, hwPhongShader.h, hwReflectBumpShader_NV20.h, hwRefractReflectShader_NV20.h, MTexture.cpp, MTexture.h, OpenEXR.cpp, simpleImageFile.cpp, tiffFloatReader.cpp, and viewCallbackTest.cpp.

`#include <MImage.h>`

List of all members.

## Public Types
enum | MImageFilterFormat { kNoFormat, kHeightFieldBumpFormat, kNormalMapBumpFormat, kUnknownFormat }
| Filter formats. More...
enum | MPixelType { kUnknown, kByte, kFloat }
| Pixel formats. More...
## Public Member Functions
| MImage ()
| The default class constructor.
| ~MImage ()
| Class destructor.
MStatus | create (unsigned int width, unsigned int height, unsigned int channels=4, MPixelType type=kByte)
| Create a new MImage object.
MStatus | readFromFile (MString pathname, MPixelType type=kByte)
| Attempt to identify and open the specified image file.
MStatus | readFromTextureNode (const MObject &fileTextureObject, MPixelType type=kByte)
| Attempt to read the content of the given file texture node.
MStatus | getSize (unsigned int &width, unsigned int &height) const
| Get the width and height of the currently opened image.
MPixelType | pixelType () const
| Get the current pixel format of the image.
unsigned char * | pixels () const
| Returns a pointer to the first pixel of the uncompressed pixels array.
float * | floatPixels () const
| Returns a pointer to the first pixel of the uncompressed pixels array.
void | setPixels (unsigned char *pixels, unsigned int width, unsigned int height)
| Set the pointer to the first pixel of the uncompressed pixels array.
void | setFloatPixels (float *pixels, unsigned int width, unsigned int height, unsigned int channels=4)
| Set the pointer to the first pixel of the uncompressed pixels array.
unsigned int | depth () const
| Get the color depth (in bytes) of the currently opened image.
MStatus | getDepthMapSize (unsigned int &width, unsigned int &height) const
| Returns the size of the depth map buffer.
MStatus | setDepthMap (float *depth, unsigned width, unsigned height)
| Specifies the depth map resolution and data.
MStatus | setDepthMap (const MFloatArray &depth, unsigned width, unsigned height)
| Specifies the depth map resolution and data.
float * | depthMap (MStatus *ReturnStatus=NULL) const
| Returns a pointer to the depth data.
MStatus | readDepthMap (MString pathname)
| Reads the depth map from the specified file and place the result into the depth map array of this MImage instance.
MStatus | resize (int width, int height, bool preserveAspectRatio=true)
| Resize the currently opened image to the specified dimension, or to the closest width/height that is preserves the original aspect ratio.
MStatus | filter (MImageFilterFormat sourceFormat, MImageFilterFormat targetFormat, double scale=1.0, double offset=0.0)
| Modify the content of the image by applying a filter.
MStatus | writeToFile (MString pathname, MString outputFormat=kIffStringDefault) const
| Save the content of this image in a file.
MStatus | writeToFileWithDepth (MString pathname, MString outputFormat=kIffStringDefault, bool writeDepth=false) const
| Save the content of this image in a file.
MStatus | release ()
| Release the current image.
void | verticalFlip ()
| Flips the image vertically.
void | setRGBA (bool rgbaFormat)
| Sets a flag to indicate that pixel information is in RGBA sequence or BGRA sequence.
bool | isRGBA () const
| Query flag which indicates whether the pixel information is in RGBA sequence or BGRA sequence.
bool | haveDepth () const
| Returns true if this instance of MImage contains a depth map.
MStatus | convertPixelFormat (MPixelType type, double scale=1.0, double offset=0.0)
| Convert the pixel format used by this image using the specified parameters.
## Static Public Member Functions
static bool | filterExists (MImageFilterFormat sourceFormat, MImageFilterFormat targetFormat)
| Return whether or not a given source format can be directly converted to a given target format.
static const char * | className ()
| Returns the name of this class. Search for all occurrences

## Member Enumeration Documentation

enum MImageFilterFormat

Search for all occurrences

Filter formats.

Enumerator:

  kNoFormat | Search for all occurrences
  kHeightFieldBumpFormat | Search for all occurrences
  kNormalMapBumpFormat | Search for all occurrences
  kUnknownFormat | Search for all occurrences

enum MPixelType

Search for all occurrences

Pixel formats.

Enumerator:

  kUnknown | Format not known or invalid. Search for all occurrences
  kByte | One byte per channel, ranging from 0 to 255. Search for all occurrences
  kFloat | One float per channel, ranging from 0.0 to 1.0. Search for all occurrences

## Constructor & Destructor Documentation

MImage | ( |  | ) |

The default class constructor.

Initialize the image.

~MImage | ( |  | ) |

Class destructor.

Automatically releases the associated image array.

## Member Function Documentation

MStatus create | ( | unsigned int | width,
|  | unsigned int | height,
|  | unsigned int | channels = `4`,
|  | MPixelType | type = `kByte`
| ) |  |

Search for all occurrences

Create a new MImage object.

Allocates memory for an RGBA array of pixels of the given size. If an object was already in memory, it is released first.

Parameters:

  [in] | width | the desired image's width in pixels.
  [in] | height | the desired image's height in pixels.
  [in] | channels | the desired number of channels per pixel. For byte typed images, 4 channels is the only value currently supported.
  [in] | type | the desired pixel format.

Returns:
  - MS::kFailure if there is not enough memory to allocate the array.
  - MS::kSuccess otherwise.

Examples:
  ddsFloatReader.cpp, hwAnisotropicShader_NV20.cpp, OpenEXR.cpp, simpleImageFile.cpp, tiffFloatReader.cpp, and viewCallbackTest.cpp.

MStatus readFromFile | ( | MString | pathname,
|  | MPixelType | type = `kByte`
| ) |  |

Search for all occurrences

Attempt to identify and open the specified image file.

Please note that IFF and SGI are the fastest image file formats for reading.

Parameters:

  [in] | pathname | the full path of the image file that should be opened.
  [in] | type | the desired pixel format. kUnknown attempts to load the native pixel type.

Returns:
  - MS::kSuccess if the image file was succesfully identified and opened.
  - MS::kFailure otherwise.

Examples:
  convertBumpCmd.cpp, customImagePlane.cpp, hwManagedTextureShader.cpp, and MTexture.cpp.

MStatus readFromTextureNode | ( | const MObject & | fileTextureObject,
|  | MPixelType | type = `kByte`
| ) |  |

Search for all occurrences

Attempt to read the content of the given file texture node.

Please note that IFF and SGI are the fastest image file formats for reading.

Parameters:

  [in] | fileTextureObject | an object that refers to the file texture node that should be read.
  [in] | type | the desired pixel format. kUnknown attempts to load the native image pixel type.

Returns:
  - MS::kSuccess if the content of the file texture was read succesfully.
  - MS::kFailure otherwise.

Examples:
  cgfxAttrDef.cpp, cgfxShaderNode.cpp, and GLSLShaderNode.cpp.

MStatus getSize | ( | unsigned int & | width,
|  | unsigned int & | height
| ) |  | const

Search for all occurrences

Get the width and height of the currently opened image.

Parameters:

  [out] | width | the variable that will be set to the image's width in pixels.
  [out] | height | the variable that will be set to the image's height in pixels.

Returns:
  - MS::kFailure if there is no currently opened image.
  - MS::kSuccess otherwise.

Examples:
  cgfxShaderNode.cpp, convertBumpCmd.cpp, customImagePlane.cpp, GLSLShaderNode.cpp, hlslShader.cpp, hwColorPerVertexShader.cpp, hwManagedTextureShader.cpp, hwPhongShader.cpp, MTexture.cpp, and viewCallbackTest.cpp.

MImage::MPixelType pixelType | ( |  | ) | const

Search for all occurrences

Get the current pixel format of the image.

Returns:
  - The current pixel format of the image.
  - kUnknown if there is no currently opened image.

unsigned char * pixels | ( |  | ) | const

Search for all occurrences

Returns a pointer to the first pixel of the uncompressed pixels array.

This array is tightly packed, of size (width * height * depth) bytes. For the moment, pixels are always stored in a RGBA (depth=4 bytes) pixel format.

Returns:
  - Pointer to the first pixel of the array.
  - NULL if no image is currently opened, or the current image has a pixel type other than kByte

Examples:
  cgfxShaderNode.cpp, customImagePlane.cpp, GLSLShaderNode.cpp, hwAnisotropicShader_NV20.cpp, hwManagedTextureShader.cpp, MTexture.cpp, and viewCallbackTest.cpp.

float * floatPixels | ( |  | ) | const

Search for all occurrences

Returns a pointer to the first pixel of the uncompressed pixels array.

This array is tightly packed, of size (width * height * depth * sizeof( float)) bytes.

Returns:
  - Pointer to the first pixel of the array.
  - NULL if no image is currently opened, or the current image has a pixel type other than kFloat

Examples:
  ddsFloatReader.cpp, OpenEXR.cpp, simpleImageFile.cpp, and tiffFloatReader.cpp.

void setPixels | ( | unsigned char * | inPixelPtr,
|  | unsigned int | width,
|  | unsigned int | height
| ) |  |

Search for all occurrences

Set the pointer to the first pixel of the uncompressed pixels array.

This array is tightly packed, of size (width * height * depth) bytes. For the moment, pixels are always stored in a RGBA (depth=4 bytes) pixel format.

Parameters:

  [in] | inPixelPtr | the variable containing a block of pixels.
  [in] | width | the variable that will be set to the image's width in pixels.
  [in] | height | the variable that will be set to the image's height in pixels.

Examples:
  viewCallbackTest.cpp.

void setFloatPixels | ( | float * | inPixelPtr,
|  | unsigned int | width,
|  | unsigned int | height,
|  | unsigned int | channels = `4`
| ) |  |

Search for all occurrences

Set the pointer to the first pixel of the uncompressed pixels array.

This array is tightly packed, of size (width * height * depth) bytes. For the moment, pixels are always stored in a RGBA (depth=4 bytes) pixel format.

Parameters:

  [in] | inPixelPtr | the variable containing a block of pixels.
  [in] | width | the variable that will be set to the image's width in pixels.
  [in] | height | the variable that will be set to the image's height in pixels.
  [in] | channels | the number of channels per pixel.

unsigned int depth | ( |  | ) | const

Search for all occurrences

Get the color depth (in bytes) of the currently opened image.

Returns:
  - The number of bytes used for each pixel.
  - 0 if there is no currently opened image.

MStatus getDepthMapSize | ( | unsigned int & | width,
|  | unsigned int & | height
| ) |  | const

Search for all occurrences

Returns the size of the depth map buffer.

Note, depth maps can differ in resolution from the color map. This is mainly for oversampling support in image planes. In all other cases, you should insure that depth size matches the color buffer size. You cannot write out an image where the depth map and image map has different resolutions.

Note, depth maps are not support with HDR, or floating point, images.

Parameters:

  [out] | width | - width of the depth map
  [out] | height | - height of the depth map

Returns:
  - MS::kSuccess - height / width successfully returned.
  - MS::kFailure - invalid depth map data.

MStatus setDepthMap | ( | float * | depth,
|  | unsigned | width,
|  | unsigned | height
| ) |  |

Search for all occurrences

Specifies the depth map resolution and data.

Note, it is possible for the depth map to be a different resolution from the color map. This is to support oversampling with image planes. You cannot save image data to a file if the color map and image maps are different resolutions.

Parameters:

  [in] | depth | - float buffer that contains depth values. The depth values should be stored as -1.0/eyeDistance, where eyeDistance == 0.0 implies no depth is at that location.
  [in] | width | - the width of the depth buffer
  [in] | height | - the height of the depth buffer.

Returns:
  - MS::kSuccess - depth values successfully loaded.
  - MS::kFailure - invalid object.
  - MS::kInvalidParameter - invalid parameter values.

Examples:
  customImagePlane.cpp.

MStatus setDepthMap | ( | const MFloatArray & | depth,
|  | unsigned | width,
|  | unsigned | height
| ) |  |

Search for all occurrences

Specifies the depth map resolution and data.

Note, it is possible for the depth map to be a different resolution from the color map. This is to support oversampling with image planes. You cannot save image data to a file if the color map and image maps are different resolutions.

Parameters:

  [in] | depth | - float array that contains depth values. The depth values should be stored as -1.0/eyeDistance, where eyeDistance == 0.0 implies no depth is at that location.
  [in] | width | - the width of the depth buffer
  [in] | height | - the height of the depth buffer.

Returns:

- MS::kSuccess - depth values successfully loaded.
- MS::kFailure - invalid object.
- MS::kInvalidParameter - invalid parameter values.

float * depthMap | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns a pointer to the depth data.

Parameters:

  [in] | ReturnStatus | - return code.

Returns:
  - MS::kFailure - invalid object, or no depth data exists for this image instance.
  - MS::kSuccess - depth buffer successfully returned.

MStatus readDepthMap | ( | MString | pathname | ) |

Search for all occurrences

Reads the depth map from the specified file and place the result into the depth map array of this MImage instance.

Parameters:

  [in] | pathname | - the path to the depth file.

Returns:
  - MS::kFailure - invalid object, or a depth buffer does not exist in the specified file.
  - MS::kSuccess - depth map successfully read.

MStatus resize | ( | int | width,
|  | int | height,
|  | bool | preserveAspectRatio = `true`
| ) |  |

Search for all occurrences

Resize the currently opened image to the specified dimension, or to the closest width/height that is preserves the original aspect ratio.

Resizing the image doesn't affect the file it was loaded from; it only affects the pixels in memory. The pixels are automatically filtered and antialiased to avoid a pixelated look.

Parameters:

  [in] | width | the desired width in pixels.
  [in] | height | the desired height in pixels.
  [in] | preserveAspectRatio | a boolean specifying whether the aspect ratio should be preserved or not. If this flag is set, the given width and height are interpreted as the maximum dimensions allowable.

Returns:
  - MS::kSuccess if the operation was succesful.
  - MS::kFailure if there is no currently opened image, the image has a pixel type other than kByte, there is not enough memory to allocate the new pixels array, or in case of any other error.

Examples:
  cgfxShaderNode.cpp, GLSLShaderNode.cpp, and MTexture.cpp.

bool filterExists | ( | MImageFilterFormat | sourceFormat,
|  | MImageFilterFormat | targetFormat
| ) |  | `[static]`

Search for all occurrences

Return whether or not a given source format can be directly converted to a given target format.

See MImage::filter() for more information.

Parameters:

  [in] | targetFormat | the format of the resulting image.
  [in] | sourceFormat | the format of the source image.

Returns:
  - true if the filter exists.
  - false otherwise.

Examples:
  convertBumpCmd.cpp.

MStatus filter | ( | MImageFilterFormat | sourceFormat,
|  | MImageFilterFormat | targetFormat,
|  | double | scale = `1.0`,
|  | double | offset = `0.0`
| ) |  |

Search for all occurrences

Modify the content of the image by applying a filter.

The dimension of the image remains the same; only the RGBA components get affected.

Currently, only one filter is supported:

sourceFormat = kHeightFieldBumpFormat, targetFormat = kNormalMapBumpFormat: this filter performs a conversion from the height-field bump format (generally used by Maya) to a normal map bump format suitable for interactive display. This filter is typically most useful to support bump mapping in a MPxHwShaderNode-derived hardware shader plug-in, since most high-end graphics adapter support it. For more information regarding this filter, see "A Practical and Robust Bump-mapping Technique for Today's GPUs", by Mark J. Kilgard, NVIDIA Corporation.

The scale argument for this filter can vary from -256.0 to 256.0, although typical values range from 1.0 to 10.0. The offset argument is currently ignored and should be left to the default value of 0.0.

Parameters:

  [in] | sourceFormat | the source format.
  [in] | targetFormat | desired target format.
  [in] | scale | vary depending on the source/target format.
  [in] | offset | vary depending on the source/target format.

Returns:
  - MS::kSuccess if the operation was succesful.
  - MS::kFailure if this image is empty or uses a format other than kByte.

Examples:
  convertBumpCmd.cpp.

MStatus writeToFile | ( | MString | pathname,
|  | MString | outputFormat = `kIffStringDefault`
| ) |  | const

Search for all occurrences

Save the content of this image in a file.

By default, the file is saved in IFF format. Optionally, the file can also be converted in a variety of image formats.

Parameters:

  [in] | pathname | a path to the desired file. This path can be absolute (eg: "C:/temp/bump.iff") or relative (eg: "temp/bump.iff").
  [in] | outputFormat | the desired image format to save into. This follows the same convention found in the Render Globals window. Examples of valid formats include: als, bmp, cin, gif, jpg, rla, sgi, tga, tif. "iff" is the default, and is the fastest format to save into since it doesn't need any internal conversion.

Returns:
  - MS::kFailure if an error occured. Common potential errors include: empty image, invalid output format, invalid pathname, not enough disk space or read-only file.
  - MS::kSuccess otherwise.

Examples:
  convertBumpCmd.cpp, and hwAnisotropicShader_NV20.cpp.

MStatus writeToFileWithDepth | ( | MString | pathname,
|  | MString | outputFormat = `kIffStringDefault`,
|  | bool | writeDepth = `false`
| ) |  | const

Search for all occurrences

Save the content of this image in a file.

By default, the file is saved in IFF format. Optionally, the file can also be converted in a variety of image formats. If the writeDepth parameter is true then any depth information stored in MImage will be written to file.

IMPORTANT: Depth map is only supported if the outputFormat is 'iff'. If the depth map and color map size differ in resolution then the file cannot be written.

Parameters:

  [in] | pathname | a path to the desired file. This path can be absolute (eg: "C:/temp/bump.iff") or relative (eg: "temp/bump.iff").
  [in] | outputFormat | the desired image format to save into. This follows the same convention found in the Render Globals window. Examples of valid formats include: als, bmp, cin, gif, jpg, rla, sgi, tga, tif. "iff" is the default, and is the fastest format to save into since it doesn't need any internal conversion.
  [in] | writeDepth | writes the depth channel information if it stored in the class data.

Returns:
  - MS::kFailure if an error occured. Common potential errors include: empty image, invalid output format, invalid pathname, not enough disk space, read-only file, or depth map resolution does not match color map resolution.
  - MS::kSuccess otherwise.

MStatus release | ( |  | ) |

Search for all occurrences

Release the current image.

If there is no current image, the call is ignored. An image is always released automatically during destruction, so generally there is no need to call this function manually.

Returns:
  MS::kSuccess always.

Examples:
  cgfxAttrDef.cpp.

void setRGBA | ( | bool | rgbaFormat | ) |

Search for all occurrences

Sets a flag to indicate that pixel information is in RGBA sequence or BGRA sequence.

Pixel data must have been allocated before this call is made.

Parameters:

  [in] | rgbaFormat | true value indicates RGBA format

Examples:
  hlslShader.cpp.

bool isRGBA | ( |  | ) | const

Search for all occurrences

Query flag which indicates whether the pixel information is in RGBA sequence or BGRA sequence.

If no pixel data exists, then false will be returned.

Returns:
  - true if in RGBA format.
  - false if in BGRA format.

bool haveDepth | ( |  | ) | const

Search for all occurrences

Returns true if this instance of MImage contains a depth map.

Returns:
  - true - depth map exists for this class instance.
  - false - depth map does not exist for this class instance.

MStatus convertPixelFormat | ( | MPixelType | format,
|  | double | scale = `1.0`,
|  | double | offset = `0.0`
| ) |  |

Search for all occurrences

Convert the pixel format used by this image using the specified parameters.

Parameters:

  [in] | format | the desired pixel format. If this matches the current format, this method will do nothing.
  [in] | scale | if conversion is required, this specifies the scaling applied to every channel of every pixel. A scale of 0 will automatically rescale based on the minimum and maximum values in the image.
  [in] | offset | if conversion is required, this specifies the offset applied to every channel of every pixel.

Returns:
  - MS::kFailure if the image is empty, or not in the requested format.
  - MS::kSuccess if the image is in the requested format.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

MImage MImage MImage MImage MImage MImage MImage MImage MImage MImage
MImage MImage MImage MImage MImage MImage MImage MImage MImage MImage