This reference page is linked to from the following overview topics: Textures, Sampling Texture Values, Images, Stamps and Stencils.

Detailed Description

This is the base image type defining the interface to images.

There are three differend kinds of images;

Physically contiguous
Striped
Tiled/Virtual/Versioned

The first kind is the fastest, but least memory efficient. If the system is not able to allocate the required memory in one piece, a striped image will be created. A striped image consists of several stripes of 1 or more rows of pixels.

The third type of image is the most versatile -- It is stored as 128 pixel square tiles -- tiles are copy-on-write, versioned, and have their own virtual memory system optimized for images. Texture layers are typically stored in this third type of image so that paint operations on them are easily undoable.

Note:: In Mudbox (starting in Version 2012) Mudbox images are lower left origin. This in vertically flipped compared to QImages which are upper left origin. This was done so that GL textures and images have the same orientation, eliminating the need to perform a vertical flip when loading and unloading textures from the GPU.

Definition at line 1301 of file image.h.

#include <image.h>

Inheritance diagram for Image:

[legend]

List of all members.

Public Types
enum	ImageType { Type_Invalid = 0, Type_Memory, Type_Virtual }
	used to identify what type of image any particular instance is. More...
enum	Format { e8integer = 0, e16integer, e32integer, e16float, e32float, e16depth, e24depth, e32depth, eUnknown, eInvalid }
	Image channel datatype type. More...
Public Member Functions
virtual	~Image (void)
virtual void	GenerateProxy (Image *targetImg, int factor)
	Generate a downsampled proxy of this image.
void	UnitTest (int iterations)
	cause the image storage mechanisms to be tested randomly for the specified number of iterations.
virtual bool	isAllocated () const
ImageType	getType () const
	return the image type.
const ImageDescriptor &	getDescriptor () const
	get the full descriptor for the image
unsigned char	getProxyLevel () const
	get the Proxy level of the image -- 0 = no proxying.
bool	setProxyLevel (unsigned char newLevel)
	set the current proxy level
Image *	getProxyImage ()
	get the proxy image.
int	xSize () const
	Get the x size of the image.
int	ySize () const
	Get the y size of the image.
int	cSize () const
	Get the channel count of the image.
int	curWidth () const
	get the width of the current proxy level of the image
int	curHeight () const
	get the height of the current proxy level of the image
ImageDescriptor::MemoryChannelOrder	channelOrder () const
	Get the channel ordering of the image.
const ImgTile &	getBounds () const
	returns the bounds of the image -- the origin of this rect may not be at 0,0
void	getFillColor (void fillPixel, const PixelDescriptor pd=0) const
	Reads the fill color into the provided buffer, in the specified format -- if no format is provided, it uses the pixel format of this image.
void	setFillColor (const void fillPixel, const PixelDescriptor pd=0)
	Sets the fill color into the provided buffer, in the specified format -- if no format is provided, it uses the pixel format of this image.
void	getTile (int x, int y, int nx, int ny, void data, const PixelDescriptor pd=0)
	Reads a rectangular region of pixels from the image into a buffer.
void	getSubTile (int x, int y, int nx, int ny, void data, int dx, int dy, int dnx, int dny, const PixelDescriptor pd=0)
	Reads a rectangular region of pixels from the image into a buffer.
void	getTile (const ImgTile &srcTile, void data, const PixelDescriptor pd=0)
	Reads a rectangular region of pixels from the image into a buffer.
virtual void	getSubTile (const ImgTile &srcTile, void data, const ImgTile &targetBounds, const PixelDescriptor pd=0)
	Reads a rectangular region of pixels from the image into a buffer.
void	setTile (int x, int y, int nx, int ny, void data, const PixelDescriptor pd=0)
	Writes a rectangular region of pixels to the image from a buffer.
void	setSubTile (int x, int y, int nx, int ny, const void data, int dx, int dy, int dnx, int dny, const PixelDescriptor pd=0)
	Writes a rectangular region of pixels from the image into a buffer.
void	setTile (const ImgTile &dstTile, const void data, const PixelDescriptor pd=0)
	Writes a rectangular region of pixels to the image from a buffer.
virtual void	setSubTile (const ImgTile &dstTile, const void data, const ImgTile &sourceBounds, const PixelDescriptor pd=0)
	Writes a rectangular region of pixels from the image into a buffer.
void	copyTile (int x, int y, int nx, int ny, Image &fromImg, int ox, int oy)
	Copies a rectangular region of pixels from a source image to this image.
virtual void	copyTile (const ImgTile &dstTile, Image &fromImg, int ox, int oy)
	Copies a rectangular region of pixels from a source image to this image.
virtual void	Clear ()
	Clear all the pixels of the image to 0 in all channels.
void	fillTile (int x, int y, int nx, int ny, void pixelData, const PixelDescriptor pd=0, const ImgTile *maskTile=0)
	Fills a rectangular region of pixels in the image with a constant color.
void	fillTile (const ImgTile &dstTile, const void pixelData, const PixelDescriptor pd, const ImgTile *maskTile)
	Fills a rectangular region of pixels in the image with a constant color.
virtual void	fillTile (const ImgTile &dstTile, const void pixelData, const PixelDescriptor pd=0)
	Fills a rectangular region of pixels in the image with a constant color.
virtual void	getPageSize (int &nx, int &ny)
	Returns the size of an image page.
ImgPageIterator *	getPageIterator (int x, int y, int nx, int ny)
	Returns a tile iterator that will iterate over the pages of this image in an optimal order.
virtual ImgPageIterator *	getPageIterator (const ImgTile &srcTile)
	Returns a tile iterator that will iterate over the pages of this image in an optimal order.
ImgLockPageIterator *	lockPageSet (int x, int y, int nx, int ny, ImgLockPageIterator::AccessMode mode)
	Returns a tile iterator that will iterate over the pages of this image in an optimal order.
virtual ImgLockPageIterator *	lockPageSet (const ImgTile &srcTile, ImgLockPageIterator::AccessMode mode)
	Returns a tile iterator that will iterate over the pages of this image in an optimal order.
void	CopyInverseLuminance (const Image &srcImage)
	copies 1-luminance from the source image into this image
void	CopyLuminance (const Image &srcImage)
	copies the luminance of the source image into this image
virtual QString	SupportedExtensions (bool bRGBAOnly=false, bool bRead=true, bool bDesc=false, bool bPSD=true, QString sDelimiter=";") const
	Returns the supported file extensions, separated by ';'.
virtual void	Create (unsigned int iWidth, unsigned int iHeight, unsigned int iChannelCount, Format eFormat=e8integer, bool Tiled=false, ImageDescriptor::MemoryChannelOrder eOrder=ImageDescriptor::orderRGBA)
	Create a new image.
virtual void	Load (const QString &sFileName, int iLayerIndex=0)
	Load a whole image from an external file.
virtual void	LoadChannel (const QString &sFileName, unsigned int iChannelIndex, int iLayerIndex=0)
	Load a single channel from an external file.
virtual bool	GetPSDLayerMeta (void *pPSDFile, int iLayerIndex, QString &layerName, int &blendMode, float &opacity, bool &locked, bool &visible, bool &transLocked)
virtual bool	LoadPSDLayer (void *pPSDFile, int iLayerIndex, bool Tiled=false, bool premult=true)
	Load this image from a layer in a Photoshop file.
virtual Image *	ComputeDifferenceMask (Image *otherImg, int expansionRadius, int AARadius, bool &anyDiffs)
virtual bool	SavePSDLayerMeta (void *pPSDFile, int iLayerIndex, const QString &pLayerName, float opacity=1.0f, bool visible=true, bool locked=false, int xOff=0, int yOff=0, int blendMode=-1)
	Save this image metadata to the layer metadata in a Photoshop file.
virtual bool	SavePSDLayer (void *pPSDFile, int iLayerIndex, const QString &pLayerName, float opacity=1.0f, bool visible=true, bool locked=false, bool needs_unpremult=true, int xOff=0, int yOff=0)
	Save this image to a layer in a Photoshop file.
virtual void *	OpenPSDFile (const QString &pFileName, bool writing=false)
	Open a PSD file for reading or writing -- returns a pointer to blind data representing the open file, or NULL if it was unable to open the file.
virtual bool	GetPSDFileInfo (void psdFile, int width, int height, int numChannels, int bitDepth, int numLayers, int *curLayer)
	Returns the basic file scope metadata for a PSD file.
virtual bool	SetPSDFileInfo (void *psdFile, int width, int height, int numChannels, int bitDepth, int numLayers, int curLayer)
	Sets the file scope metadata for a writable PSD file.
virtual bool	ClosePSDFile (void *psdFile)
	Close a PSD file.
virtual void	Save (const QString &sFileName, bool bForce=true, Material *pMaterial=NULL, float uStart=0.0f, float vStart=0.0f, bool force_1_Channel_To_4_Channel=false)
	Save the image to an external file.
virtual unsigned int	Width (void) const
	Return the width of the image in pixels.
virtual unsigned int	Height (void) const
	Return the height of the image in pixels.
virtual Format	Format (void) const
	Return the format of the image.
virtual unsigned int	ChannelCount (void) const
	Return the number of channels in the image.
virtual unsigned int	BytesPerPixel (void) const
	Return the number of bytes used by a pixel.
unsigned int	curBytesPerPixel () const
	Return the number of bytes used by a pixel at the current proxy level.
virtual unsigned int	TotalBytes (void) const
	Return the number of bytes used by the whole image.
unsigned int	curTotalBytes (void) const
	Return the number of bytes used by the whole image (current proxy level)
virtual void	SetValueAt (unsigned int iXPos, unsigned int iYPos, unsigned int iChannel, float fValue)
	Set value for a specified texel.
virtual float	ValueAt (unsigned int iXPos, unsigned int iYPos, unsigned int iChannel) const
	Get the value at a given coordinate.
virtual float	ValueAt (float fXPos, float fYPos, unsigned int iChannel) const
	Get interpolated value at a given coordinate.
virtual void	SetColorAt (unsigned int iXPos, unsigned int iYPos, const Color &cColor)
	Set value for a specified texel.
virtual Color	ColorAt (unsigned int iXPos, unsigned int iYPos) const
	Get the value at a given coordinate.
virtual Color	ColorAt (float fXPos, float fYPos) const
	Get interpolated value at a given coordinate.
virtual QImage *	ConvertToQImage ()
	Create a QImage object from the image data for display purposes.
virtual void	ConvertFromQImage (QImage &qImg)
	Creates the image from a QImage.
virtual bool	Fragmented () const
	returns true if the image is not stored in one physically contiguous piece of CPU visible memory -- If so, you must use lockPageSet to get at portions of the image data...
virtual bool	Tiled () const
	returns true if this is a tiled and versioned image
bool	Versioned () const
	returns true if this is a tiled and versioned image
virtual bool	NewVersion ()
	checkpoint and create a new version of this image.
virtual bool	PrevVersion ()
	makes the previous version current -- used for undo returns true if it worked, false otherwise marks the proxy dirty
virtual bool	NextVersion ()
	makes the next version current -- used for redo returns true if it worked, false otherwise marks the proxy dirty
virtual int	NumVersions ()
	returns the number of versions. returns 1 for unversioned images
virtual bool	MergeOldestVersions ()
	merges the oldest two versions -- used to limit the number of items on the undo queue.
virtual bool	PurgeNewerVersions ()
	Creating a new version will implicitly purge nerer versions, but if another operation takes place that puts a new item on the undo queue, this should be called to purge newer versions of this image returns true if it worked, false otherwise.
virtual bool	PurgeAllButCurrentVersion ()
	Releases all but the current version -- used to flush the undo queue.
virtual void *	Data (int iRow=-1, bool writing=true)
	Get a pointer to the raw data of a row of the image.
virtual const void *	Data (int iRow=-1, bool writing=false) const
virtual void	DrawUVs (Material *pMaterial, float uStart=0.0f, float vStart=0.0f, bool baseLevel=true)
	Draw the uv mesh for a given material into this image -- either the base or active level.
virtual void	scaleTileBilinear_4Chan_uchar (float x, float y, float nx, float ny, unsigned int *data, int dx, int dy, int dnx, int dny, float xScale, float yScale) const
	Fast, thread safe image scaler.
virtual void	GenerateUpscaled (Image *targetImg, int factor)
	This upscales an image with good filtering (bilinear to Lanczos as needed based on the scale factor.
virtual bool	isDirty () const
	Query if the contents of this image have changed since the last call to setClean.
virtual void	setDirty ()
	Explicitly set the image state to dirty.
virtual void	setClean ()
	explicitly set the image state to clean.
virtual void	VerticalFlip ()
	vertically flip the image (make it upside down)
Static Public Member Functions
static QString	AllSupportedExtensions (bool bRGBAOnly=false, bool bRead=true, bool bDesc=false, bool bPSD=true, QString sDelimiter=";")
static ImageDescriptor::MemoryChannelOrder	optimizedChannelOrder ()
static void	ConvertPixels (void dst, const void src, int numPix, const PixelDescriptor &dstDesc, const PixelDescriptor *srcDesc=0)
static void	MultiplyRGBByAlpha_uc4 (unsigned char *buffer, int numPixels)
	multiply alpha into RGB for the specified number of pixels.
Protected Member Functions
	Image (void)
void	markProxyDirty ()
virtual void	regenerateProxy ()
bool	isProxyDirty () const
Protected Attributes
unsigned char	m_FillPixel [16]
ImageDescriptor	m_Descriptor
ImageType	m_ImageType
bool	m_ProxyDirty
unsigned char	m_ProxyLevel
Image *	m_pProxyImage
Friends
class	ImgPageIterator
class	ImgLockPageIterator

Type_Invalid	Search for all occurrences
Type_Memory	physically contiguous image or striped Search for all occurrences
Type_Virtual	Tiled & versioned, not contiguous. Search for all occurrences

e8integer	Search for all occurrences
e16integer	Search for all occurrences
e32integer	Search for all occurrences
e16float	Search for all occurrences
e32float	Search for all occurrences
e16depth	Search for all occurrences
e24depth	Search for all occurrences
e32depth	Search for all occurrences
eUnknown	Search for all occurrences
eInvalid	Search for all occurrences

virtual void GenerateProxy	(	Image *	targetImg,
		int	factor
	)		`[virtual]`

static QString AllSupportedExtensions	(	bool	bRGBAOnly = `false`,
		bool	bRead = `true`,
		bool	bDesc = `false`,
		bool	bPSD = `true`,
		QString	sDelimiter = `";"`
	)		`[static]`

void getFillColor	(	void *	fillPixel,
		const PixelDescriptor *	pd = `0`
	)		const

fillPixel	Pointer to the target where the fill color will be written
pd	Desired pixelformat for the fill color -- if 0, it uses the pixel format of this image

void setFillColor	(	const void *	fillPixel,
		const PixelDescriptor *	pd = `0`
	)

fillPixel	Pointer to the source where the fill color will be read from
pd	Desired pixelformat for the fill color -- if 0, it uses the pixel format of this image

void getTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		void *	data,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

x	x coord of the lower left corner of the region to be read.
y	y coord of the lower left corner of the region to be read.
nx	width of the region to be read.
ny	height of the region to be read.
data	Pointer to the target buffer.
pd	Desired pixelformat for the buffer color -- if 0, it uses the pixel format of this image

void getSubTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		void *	data,
		int	dx,
		int	dy,
		int	dnx,
		int	dny,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

void getTile	(	const ImgTile &	srcTile,
		void *	data,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

srcTile	the rectangle of the image to be read into the buffer.
data	Pointer to the target buffer.
pd	Desired pixelformat for the buffer color -- if 0, it uses the pixel format of this image

virtual void getSubTile	(	const ImgTile &	srcTile,
		void *	data,
		const ImgTile &	targetBounds,
		const PixelDescriptor *	pd = `0`
	)		`[virtual]`

void setTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		void *	data,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

x	x coord of the lower left corner of the region to be written.
y	y coord of the lower left corner of the region to be written.
nx	width of the region to be written.
ny	height of the region to be written.
data	Pointer to the source buffer.
pd	Pixelformat for the buffer color -- if 0, it uses the pixel format of this image

void setSubTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		const void *	data,
		int	dx,
		int	dy,
		int	dnx,
		int	dny,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

void setTile	(	const ImgTile &	dstTile,
		const void *	data,
		const PixelDescriptor *	pd = `0`
	)		`[inline]`

dstTile	rectangle of the image to be written.
data	Pointer to the source buffer.
pd	Desired pixelformat for the buffer color -- if 0, it uses the pixel format of this image

virtual void setSubTile	(	const ImgTile &	dstTile,
		const void *	data,
		const ImgTile &	sourceBounds,
		const PixelDescriptor *	pd = `0`
	)		`[virtual]`

Image Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

void copyTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		Image &	fromImg,
		int	ox,
		int	oy
	)		`[inline]`

x	x target coord of the lower left corner of the region to be copied.
y	y target coord of the lower left corner of the region to be copied.
nx	width of the region to be copied.
ny	height of the region to be copied.
fromImg	The source image.
ox	x source coord of the lower left corner of the region to be copied (in souce image coordinates).
oy	y source coord of the lower left corner of the region to be copied (in souce image coordinates). .

virtual void copyTile	(	const ImgTile &	dstTile,
		Image &	fromImg,
		int	ox,
		int	oy
	)		`[virtual]`

dstTile	target rectangle to be copied.
fromImage	The source image.
ox	x source coord of the lower left corner of the region to be copied (in souce image coordinates).
oy	y source coord of the lower left corner of the region to be copied (in souce image coordinates). .

void fillTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		void *	pixelData,
		const PixelDescriptor *	pd = `0`,
		const ImgTile *	maskTile = `0`
	)		`[inline]`

x	x target coord of the lower left corner of the region to be filled.
y	y target coord of the lower left corner of the region to be filled.
nx	width of the region to be filled.
ny	height of the region to be filled.
pixelData	Pointer to the source pixel data. If 0, all 0s are used instead.
pd	Pixelformat for the source pixel color -- if 0, it uses the pixel format of this image
masktTile	an optional pointer to a mask rectangle. If present, the contents of this rectangle of the image will remain unchanged by this operation.

virtual void fillTile	(	const ImgTile &	dstTile,
		const void *	pixelData,
		const PixelDescriptor *	pd = `0`
	)		`[virtual]`

ImgPageIterator* getPageIterator	(	int	x,
		int	y,
		int	nx,
		int	ny
	)		`[inline]`

x	x origin of the region to iterate over
y	yorigin of the region to iterate over
nx	width of the region to iterate over
ny	height of the region to iterate over

ImgLockPageIterator* lockPageSet	(	int	x,
		int	y,
		int	nx,
		int	ny,
		ImgLockPageIterator::AccessMode	mode
	)		`[inline]`