#include
<MImage.h>
List of all
members.
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).
-
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.
|
Public Types
|
enum |
MImageFilterFormat
{
kNoFormat,
kHeightFieldBumpFormat,
kNormalMapBumpFormat,
kUnknownFormat } |
|
Filter formats. More...
|
enum |
MPixelType
{
kUnknown,
kByte,
kFloat } |
|
Pixel formats. More...
|
Public Member Functions
|
|
MImage
() |
|
~MImage
() |
MStatus |
create
(unsigned int width, unsigned int height, unsigned int channels=4,
MPixelType
type=kByte) |
MStatus |
readFromFile
(MString pathname,
MPixelType
type=kByte) |
MStatus |
readFromTextureNode
(const MObject
&fileTextureObject, MPixelType
type=kByte) |
MStatus |
getSize
(unsigned int &width, unsigned int &height) const |
MPixelType |
pixelType
() const |
unsigned char * |
pixels ()
const |
float * |
floatPixels
() const |
void |
setPixels
(unsigned char *pixels, unsigned int width, unsigned int
height) |
void |
setFloatPixels
(float *pixels, unsigned int width, unsigned int height, unsigned
int channels=4) |
unsigned int |
depth ()
const |
MStatus |
getDepthMapSize
(unsigned int &width, unsigned int &height) const |
MStatus |
setDepthMap
(float *depth, unsigned width, unsigned height) |
MStatus |
setDepthMap
(const MFloatArray &depth, unsigned
width, unsigned height) |
float * |
depthMap
(MStatus
*ReturnStatus=NULL) const |
MStatus |
readDepthMap
(MString
pathname) |
MStatus |
resize
(int width, int height, bool preserveAspectRatio=true) |
MStatus |
filter
(MImageFilterFormat
sourceFormat, MImageFilterFormat
targetFormat, double scale=1.0, double offset=0.0) |
MStatus |
writeToFile
(MString pathname,
MString
outputFormat=MString("iff")) const |
MStatus |
writeToFileWithDepth
(MString pathname,
MString
outputFormat=MString("iff"), bool writeDepth=false)
const |
MStatus |
release
() |
void |
verticalFlip
() |
void |
setRGBA
(bool rgbaFormat) |
bool |
isRGBA ()
const |
bool |
haveDepth
() const |
MStatus |
convertPixelFormat
(MPixelType
type, double scale=1.0, double offset=0.0) |
Static Public Member Functions
|
static bool |
filterExists
(MImageFilterFormat
sourceFormat, MImageFilterFormat
targetFormat) |
Member Enumeration Documentation
Filter formats.
- Enumerator:
-
kNoFormat |
|
kHeightFieldBumpFormat |
|
kNormalMapBumpFormat |
|
kUnknownFormat |
|
Pixel formats.
- Enumerator:
-
kUnknown |
Format not known or invalid. |
kByte |
One byte per channel, ranging from 0 to 255. |
kFloat |
One float per channel, ranging from 0.0 to 1.0. |
Constructor & Destructor Documentation
The default class constructor. Initialize the image.
Class destructor. Automatically releases the associated image
array.
Member Function Documentation
MStatus MImage::create |
( |
unsigned int |
width, |
|
|
unsigned int |
height, |
|
|
unsigned int |
channels = 4 , |
|
|
MPixelType |
type = kByte |
|
|
) |
|
|
|
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:
-
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:
-
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:
-
MStatus MImage::getSize |
( |
unsigned int & |
width, |
|
|
unsigned int & |
height |
|
|
) |
|
|
const |
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:
-
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 * MImage::pixels |
( |
|
) |
const |
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
float * MImage::floatPixels |
( |
|
) |
const |
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
void MImage::setPixels |
( |
unsigned char * |
inPixelPtr, |
|
|
unsigned int |
width, |
|
|
unsigned int |
height |
|
|
) |
|
|
|
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. |
void MImage::setFloatPixels |
( |
float * |
inPixelPtr, |
|
|
unsigned int |
width, |
|
|
unsigned int |
height, |
|
|
unsigned int |
channels = 4 |
|
|
) |
|
|
|
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 MImage::depth |
( |
|
) |
const |
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 MImage::getDepthMapSize |
( |
unsigned int & |
width, |
|
|
unsigned int & |
height |
|
|
) |
|
|
const |
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:
-
MStatus MImage::setDepthMap |
( |
float * |
depth, |
|
|
unsigned |
width, |
|
|
unsigned |
height |
|
|
) |
|
|
|
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:
-
MStatus MImage::setDepthMap |
( |
const MFloatArray & |
depth, |
|
|
unsigned |
width, |
|
|
unsigned |
height |
|
|
) |
|
|
|
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:
float * MImage::depthMap |
( |
MStatus * |
ReturnStatus =
NULL |
) |
const |
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.
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 MImage::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.
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.
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.
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:
-
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.
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.
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.
void MImage::verticalFlip |
( |
|
) |
|
Flips the image vertically.
void MImage::setRGBA |
( |
bool |
rgbaFormat |
) |
|
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 |
bool MImage::isRGBA |
( |
|
) |
const |
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 MImage::haveDepth |
( |
|
) |
const |
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 MImage::convertPixelFormat |
( |
MPixelType |
format, |
|
|
double |
scale = 1.0 , |
|
|
double |
offset = 0.0 |
|
|
) |
|
|
|
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.