mudbox::Image Class Reference

#include <image.h>

Inheritance diagram for mudbox::Image:

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.


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 const mudbox::ClassDesc *	RuntimeClass (void) const
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
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.
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 char 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 char 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)
	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.
virtual unsigned int	TotalBytes (void) const
	Return the number of bytes used by the whole image.
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
virtual bool	NextVersion ()
	makes the next version current -- used for redo returns true if it worked, false otherwise
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)
	Get a pointer to the raw data of a row of the image.
virtual const void *	Data (int iRow=-1) 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.
Static Public Member Functions
const mudbox::ClassDesc *	StaticClass (void)
mudbox::Node *	CreateInstances (unsigned int iCount=1)
ImageDescriptor::MemoryChannelOrder	optimizedChannelOrder ()
void	ConvertPixels (void dst, const void src, int numPix, const PixelDescriptor &dstDesc, const PixelDescriptor *srcDesc=0)
Protected Member Functions
	Image (void)
Protected Attributes
unsigned char	m_FillPixel [16]
ImageDescriptor	m_Descriptor
ImageType	m_ImageType
Friends
class	ImgPageIterator
class	ImgLockPageIterator

Member Enumeration Documentation

enum mudbox::Image::ImageType

used to identify what type of image any particular instance is.

Enumeration values:

Type_Invalid
Type_Memory	physically contiguous image or striped
Type_Virtual	Tiled & versioned, not contiguous.

01352                  {
01353         Type_Invalid = 0,
01354         Type_Memory,       
01355         Type_Virtual       
01356     } ImageType;

enum mudbox::Image::Format

Image channel datatype type.

Enumeration values:

e8integer
e16integer
e32integer
e16float
e32float
e16depth
e24depth
e32depth
eUnknown
eInvalid

01360     {
01361         e8integer = 0,
01362         e16integer,
01363         e32integer,
01364         e16float,
01365         e32float,
01366         e16depth,
01367         e24depth,
01368         e32depth,
01369         eUnknown,
01370         eInvalid,
01371     };

Constructor & Destructor Documentation

mudbox::Image::Image ( void ) [protected]

Member Function Documentation

virtual const mudbox::ClassDesc* mudbox::Image::RuntimeClass ( void ) const [inline, virtual]

Reimplemented from mudbox::Node.

01350 :

const mudbox::ClassDesc* mudbox::Image::StaticClass ( void ) [static]

Reimplemented from mudbox::Node.

mudbox::Node* mudbox::Image::CreateInstances ( unsigned int iCount = 1 ) [static]

Reimplemented from mudbox::Node.

void mudbox::Image::UnitTest

(

int

iterations

)

cause the image storage mechanisms to be tested randomly for the specified number of iterations.

virtual bool mudbox::Image::isAllocated ( ) const [virtual]

ImageType mudbox::Image::getType ( ) const [inline]

return the image type.

01391 { return m_ImageType; }

const ImageDescriptor& mudbox::Image::getDescriptor ( ) const [inline]

get the full descriptor for the image

01394 { return m_Descriptor; }

int mudbox::Image::xSize ( ) const [inline]

Get the x size of the image.

01397 { return m_Descriptor.xSize(); }

int mudbox::Image::ySize ( ) const [inline]

Get the y size of the image.

01400 { return m_Descriptor.ySize(); }

int mudbox::Image::cSize ( ) const [inline]

Get the channel count of the image.

01403 { return m_Descriptor.cSize(); }

ImageDescriptor::MemoryChannelOrder mudbox::Image::channelOrder ( ) const [inline]

Get the channel ordering of the image.

01406 { return m_Descriptor.m_channelOrder; }

const ImgTile& mudbox::Image::getBounds ( ) const [inline]

returns the bounds of the image -- the origin of this rect may not be at 0,0

01409 { return m_Descriptor.getBounds(); }

void mudbox::Image::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.

Parameters:

	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 mudbox::Image::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.

Parameters:

	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 mudbox::Image::getTile	(	int	x,
		int	y,
		int	nx,
		int	ny,
		void *	data,
		const PixelDescriptor *	pd = `0`
	)	`[inline]`

Reads a rectangular region of pixels from the image into a buffer.

The buffer must be exactly the size of the region being read. If the region is outside or partly outside the bounds of the image, those areas of the target buffer will be filled with the image's FillColor

Note:: this operation is atomic -- no other threads can write to the image while this is being performed.

Parameters:

	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

01457        { getTile(ImgTile(x, y, nx, ny), data, pd); }

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

Reads a rectangular region of pixels from the image into a buffer.

The buffer may be be different than the size of the region being read. If the region is outside or partly outside the bounds of the image, those areas of the target buffer will be filled with the image's FillColor

Note:: this operation is atomic -- no other threads can write to the image while this is being performed.

Parameters:

	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.
	dx	x coord of the lower left corner of the buffer (in image coords).
	dy	y coord of the lower left corner of the buffer (in image coords).
	dnx	width of the target buffer.
	dny	height of the target buffer.
	pd	Desired pixelformat for the buffer color -- if 0, it uses the pixel format of this image

01487        { getSubTile(ImgTile(x, y, nx, ny), data, ImgTile(dx, dy, dnx, dny), pd); }

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

Reads a rectangular region of pixels from the image into a buffer.

Note:: this operation is atomic -- no other threads can write to the image while this is being performed.

Parameters:

	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

01508        { getSubTile(srcTile, data, srcTile, pd); }

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

Reads a rectangular region of pixels from the image into a buffer.

Note:: this operation is atomic -- no other threads can write to the image while this is being performed.
this is the only member of the getTile family that must be provided by subclasses of this Image class.

Parameters:

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

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

Writes a rectangular region of pixels to the image from a buffer.

The buffer must be exactly the size of the region being written. If the image has dynamic bounds, the image bounds will be expanded as required so that the entire operation can complete. Otherwise the region that is outside the bounds of the image will not be written.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.

Parameters:

	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

01557        { setTile(ImgTile(x, y, nx, ny), data, pd); }

void mudbox::Image::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]`

Writes a rectangular region of pixels from the image into a buffer.

The buffer may be be different than the size of the region being written. If the image has dynamic bounds, the image bounds will be expanded as required so that the entire operation can complete. Otherwise the region that is outside the bounds of the image will not be written.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.

Parameters:

	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.
	dx	x coord of the lower left corner of the buffer (in image coords).
	dy	y coord of the lower left corner of the buffer (in image coords).
	dnx	width of the target buffer.
	dny	height of the target buffer.
	pd	Pixelformat for the buffer color -- if 0, it uses the pixel format of this image

01589        { setSubTile(ImgTile(x, y, nx, ny), data, ImgTile(dx, dy, dnx, dny), pd); }

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

Writes a rectangular region of pixels to the image from a buffer.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.

Parameters:

	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

01609        { setSubTile(dstTile, data, dstTile, pd); }

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

Writes a rectangular region of pixels from the image into a buffer.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.
this is the only member of the setTile family that must be provided by subclasses of this Image class.

Parameters:

	dstTile	rectangle of the image to be written.
	data	Pointer to the source buffer.
	sourceBounds	bounds of the source buffer (in image coords).
	pd	Pixelformat for the buffer color -- if 0, it uses the pixel format of this image

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

Copies a rectangular region of pixels from a source image to this image.

If the image has dynamic bounds, the image bounds will be expanded as required so that the entire operation can complete. Otherwise the region that is outside the bounds of the image will not be written. Regions outsude the bounds of the source image will be filled with the FillColor of the source image.

Note:: this operation is atomic -- no other threads can read or write to the target image while this is being performed, and no other threads can write to the source image.
Format conversions are automatically performed as required.

Parameters:

	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). .

01661        { copyTile(ImgTile(x, y, nx, ny), fromImg, ox, oy); }

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

Copies a rectangular region of pixels from a source image to this image.

Note:

this operation is atomic -- no other threads can read or write to the target image while this is being performed, and no other threads can write to the source image.

Format conversions are automatically performed as required.

this is the only member of the copyTile family that must be provided by subclasses of this Image class.

Parameters:

	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). .

virtual void mudbox::Image::Clear ( ) [virtual]

Clear all the pixels of the image to 0 in all channels.

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

Fills a rectangular region of pixels in the image with a constant color.

Optionally a rectangular region can be "masked off" and not filled. If the image has dynamic bounds, the image bounds will be expanded as required so that the entire operation can complete. Otherwise the region that is outside the bounds of the image will not be written.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.

Parameters:

	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.

01720     { fillTile(ImgTile(x, y, nx, ny), pixelData, pd, maskTile); }

void mudbox::Image::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.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.

Parameters:

	dstTile	Rectangle of the image to be written.
	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 mudbox::Image::fillTile	(	const ImgTile &	dstTile,
		const void *	pixelData,
		const PixelDescriptor *	pd = `0`
	)	`[virtual]`

Fills a rectangular region of pixels in the image with a constant color.

Note:: this operation is atomic -- no other threads can read or write to the image while this is being performed.
this is the only member of the fillTile family that must be provided by subclasses of this Image class.

Parameters:

	dstTile	Rectangle of the image to be written.
	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

virtual void mudbox::Image::getPageSize	(	int &	nx,
		int &	ny
	)	`[virtual]`

Returns the size of an image page.

Some images may be carved up into 1 or more image pages -- this method returns the page size for this image. MemoryImages will be a single page that is the size of the entire images. virtualImages will have have a page size of 128 x 128 pixels.

Parameters:

	nx	width of a page
	ny	height of a page

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

Returns a tile iterator that will iterate over the pages of this image in an optimal order.

For MemoryImages and other non paged images this iterator will only produce one tile.

Parameters:

	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

Returns:: the tileIterator

Note:: this function allocates the iterator -- when the caller is finished with it, the caller must delete it.

01795     { return getPageIterator(ImgTile(x, y, nx, ny)); }

virtual ImgPageIterator* mudbox::Image::getPageIterator ( const ImgTile & srcTile ) [virtual]

Returns a tile iterator that will iterate over the pages of this image in an optimal order.

For MemoryImages and other non paged images this iterator will only produce one tile.

Parameters:

srcTile

the region to iterate over

Returns:: the tileIterator

Note:: this function allocates the iterator -- when the caller is finished with it, the caller must delete it.

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

Returns a tile iterator that will iterate over the pages of this image in an optimal order.

These pages are locked at the start of this operation, and unlocked 1 by one as they are iterated over. For MemoryImages and other non paged images this iterator will only produce one tile.

Parameters:

	x	x origin of the region to lock and iterate over
	y	yorigin of the region to lock and iterate over
	nx	width of the region to lock and iterate over
	ny	height of the region to lock and iterate over
	mode	the access mode -- read only, read/write or write only.

Returns:: the tileIterator

Note:: this function allocates the iterator -- when the caller is finished with it, the caller must delete it.

01827     { return lockPageSet(ImgTile(x, y, nx, ny), mode); }

virtual ImgLockPageIterator* mudbox::Image::lockPageSet	(	const ImgTile &	srcTile,
		ImgLockPageIterator::AccessMode	mode
	)	`[virtual]`

Returns a tile iterator that will iterate over the pages of this image in an optimal order.

These pages are locked at the start of this operation, and unlocked 1 by one as they are iterated over. For MemoryImages and other non paged images this iterator will only produce one tile.

Parameters:

	srcTile	the region to lock and iterate over
	mode	the access mode -- read only, read/write or write only.

Returns:: the tileIterator

Note:: this function allocates the iterator -- when the caller is finished with it, the caller must delete it.

ImageDescriptor::MemoryChannelOrder mudbox::Image::optimizedChannelOrder ( ) [static]

void mudbox::Image::ConvertPixels	(	void *	dst,
		const void *	src,
		int	numPix,
		const PixelDescriptor &	dstDesc,
		const PixelDescriptor *	srcDesc = `0`
	)	`[static]`

void mudbox::Image::CopyInverseLuminance

(

const Image &

srcImage

)

copies 1-luminance from the source image into this image

void mudbox::Image::CopyLuminance

(

const Image &

srcImage

)

copies the luminance of the source image into this image

virtual QString mudbox::Image::SupportedExtensions	(	bool	bRGBAOnly = `false`,
		bool	bRead = `true`,
		bool	bDesc = `false`,
		bool	bPSD = `true`,
		QString	sDelimiter = `";"`
	)	const `[virtual]`

Returns the supported file extensions, separated by ';'.

Parameters:

	bRGBAOnly	true to return a list of file formats that support 4 channels. false to return a list of all supported formats. Not all returned formats may support 4 channels (like JPEG).
	bRead	true to return list of readable formats, false for writable formats. Not all readable formats may be writable and vice versa.
	bDesc	true to prepend descriptive text to each extension. i.e "JPG [8 bit, RGB]"
	bPSD	true to support PSD files...

virtual void mudbox::Image::Create	(	unsigned int	iWidth,
		unsigned int	iHeight,
		unsigned int	iChannelCount,
		Format	eFormat = `e8integer`,
		bool	Tiled = `false`,
		ImageDescriptor::MemoryChannelOrder	eOrder = `ImageDescriptor::orderRGBA`
	)	`[virtual]`

Create a new image.

Data will be undefined. The Tiled argument creates a tiled versioned image. (the Data method will not work on these type of images, you must use get/set/copy tile or page locking to access them)

virtual void mudbox::Image::Load	(	const QString &	sFileName,
		int	iLayerIndex = `0`
	)	`[virtual]`

Load a whole image from an external file.

The extension in the filename must be included. If the file is a PSD file, the bottom bost image layer is loaded into this image.

virtual void mudbox::Image::LoadChannel	(	const QString &	sFileName,
		unsigned int	iChannelIndex,
		int	iLayerIndex = `0`
	)	`[virtual]`

Load a single channel from an external file.

virtual bool mudbox::Image::GetPSDLayerMeta	(	void *	pPSDFile,
		int	iLayerIndex,
		QString &	layerName,
		int &	blendMode,
		float &	opacity,
		bool &	locked,
		bool &	visible,
		bool &	transLocked
	)	`[virtual]`

virtual bool mudbox::Image::LoadPSDLayer	(	void *	pPSDFile,
		int	iLayerIndex,
		bool	Tiled = `false`,
		bool	premult = `true`
	)	`[virtual]`

Load this image from a layer in a Photoshop file.

The image will be created at the bit-depth and format of the PSD file (either 8 bit int, 16 bit int, or 32 bit float), and will be the size of the PSD file (not the size of the layer, which can be smaller). The image will be tiled as specified. The pPSDFile must have been created with OpenPSDFile. 0 is the bottom layer, and they increase as you go up in the layer stack.

virtual Image* mudbox::Image::ComputeDifferenceMask	(	Image *	otherImg,
		int	expansionRadius,
		int	AARadius,
		bool &	anyDiffs
	)	`[virtual]`

virtual bool mudbox::Image::SavePSDLayerMeta	(	void *	pPSDFile,
		int	iLayerIndex,
		const char *	pLayerName,
		float	opacity = `1.0f`,
		bool	visible = `true`,
		bool	locked = `false`,
		int	xOff = `0`,
		int	yOff = `0`,
		int	blendMode = `-1`
	)	`[virtual]`

Save this image metadata to the layer metadata in a Photoshop file.

The image must be the same size and bit-depth as the PSD file The pPSDFile must have been created with PSDOpen. 0 is the bottom layer, and they increase as you go up in the layer stack -1 for the layer index indicates that you want to save the RGB of this image into the composite image in the PSD file. In that case, the remaining parameters are ignored. All layer metadata must be set before any layer images are written

virtual bool mudbox::Image::SavePSDLayer	(	void *	pPSDFile,
		int	iLayerIndex,
		const char *	pLayerName,
		float	opacity = `1.0f`,
		bool	visible = `true`,
		bool	locked = `false`,
		bool	needs_unpremult = `true`,
		int	xOff = `0`,
		int	yOff = `0`
	)	`[virtual]`

Save this image to a layer in a Photoshop file.

The image must be the same size and bit-depth as the PSD file The pPSDFile must have been created with PSDOpen. 0 is the bottom layer, and they increase as you go up in the layer stack -1 for the layer index indicates that you want to save the RGB of this image into the composite image in the PSD file. In that case, the remaining parameters are ignored. The layer metata for this and all other layers must have been set before calling this function.

virtual void* mudbox::Image::OpenPSDFile	(	const QString &	pFileName,
		bool	writing = `false`
	)	`[virtual]`

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.

When creating a PSD file, first open it, then set the FileInfo, then save the layes from the bottom up (index 0 to n), and lastly save the composite layer (index -1.) Then close the file.

virtual bool mudbox::Image::GetPSDFileInfo	(	void *	psdFile,
		int *	width,
		int *	height,
		int *	numChannels,
		int *	bitDepth,
		int *	numLayers,
		int *	curLayer
	)	`[virtual]`

Returns the basic file scope metadata for a PSD file.

Returns true if successful. (if any of the pointers are NULL, the informaton is not retrieved)

virtual bool mudbox::Image::SetPSDFileInfo	(	void *	psdFile,
		int	width,
		int	height,
		int	numChannels,
		int	bitDepth,
		int	numLayers,
		int	curLayer
	)	`[virtual]`

Sets the file scope metadata for a writable PSD file.

Returns true if successful. This must be called before saving any layers.

virtual bool mudbox::Image::ClosePSDFile ( void * psdFile ) [virtual]

Close a PSD file.

virtual void mudbox::Image::Save	(	const QString &	sFileName,
		bool	bForce = `true`,
		Material *	pMaterial = `NULL`,
		float	uStart = `0.0f`,
		float	vStart = `0.0f`
	)	`[virtual]`

Save the image to an external file.

The extension of the file will determine the file type. If bForce is true the image should be saved even it means data loss. Otherwise an exception should drop. Optionally, when saving to PSD, if you specify a material and a uv offset for this texture, it can draw the base uv mesh on a layer above the image layer.

virtual unsigned int mudbox::Image::Width ( void ) const [virtual]

Return the width of the image in pixels.

virtual unsigned int mudbox::Image::Height ( void ) const [virtual]

Return the height of the image in pixels.

virtual Format mudbox::Image::Format ( void ) const [virtual]

Return the format of the image.

virtual unsigned int mudbox::Image::ChannelCount ( void ) const [virtual]

Return the number of channels in the image.

virtual unsigned int mudbox::Image::BytesPerPixel ( void ) const [virtual]

Return the number of bytes used by a pixel.

virtual unsigned int mudbox::Image::TotalBytes ( void ) const [virtual]

Return the number of bytes used by the whole image.

virtual void mudbox::Image::SetValueAt	(	unsigned int	iXPos,
		unsigned int	iYPos,
		unsigned int	iChannel,
		float	fValue
	)	`[virtual]`

Set value for a specified texel.

For integer maps 1 should be mapped for the maximum value (255 for 8 bit images and 65535 for 16 bit images) This fcn is very slow and deprecated. Use LockPageSet, or the fast templated pixel accessor classes.

virtual float mudbox::Image::ValueAt	(	unsigned int	iXPos,
		unsigned int	iYPos,
		unsigned int	iChannel
	)	const `[virtual]`

Get the value at a given coordinate.

This fcn is very slow and deprecated. Use LockPageSet, or the fast templated pixel accessor classes.

virtual float mudbox::Image::ValueAt	(	float	fXPos,
		float	fYPos,
		unsigned int	iChannel
	)	const `[virtual]`

Get interpolated value at a given coordinate.

This fcn is very slow and deprecated. Use LockPageSet, or the fast templated pixel accessor classes.

virtual void mudbox::Image::SetColorAt	(	unsigned int	iXPos,
		unsigned int	iYPos,
		const Color &	cColor
	)	`[virtual]`

Set value for a specified texel.

For integer maps 1 should be mapped for the maximum value (255 for 8 bit images and 65535 for 16 bit images)

virtual Color mudbox::Image::ColorAt	(	unsigned int	iXPos,
		unsigned int	iYPos
	)	const `[virtual]`

Get the value at a given coordinate.

virtual Color mudbox::Image::ColorAt	(	float	fXPos,
		float	fYPos
	)	const `[virtual]`

Get interpolated value at a given coordinate.

virtual QImage* mudbox::Image::ConvertToQImage ( ) [virtual]

Create a QImage object from the image data for display purposes.

This function allocates the QImage -- the caller will have to delete it when done with the image.

virtual void mudbox::Image::ConvertFromQImage ( QImage & qImg ) [virtual]

Creates the image from a QImage.

virtual bool mudbox::Image::Fragmented ( ) const [virtual]

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 mudbox::Image::Tiled ( ) const [virtual]

returns true if this is a tiled and versioned image

bool mudbox::Image::Versioned ( ) const [inline]

returns true if this is a tiled and versioned image

02052 { return Tiled(); }

virtual bool mudbox::Image::NewVersion ( ) [virtual]

checkpoint and create a new version of this image.

returns true if it worked, false otherwise

virtual bool mudbox::Image::PrevVersion ( ) [virtual]

makes the previous version current -- used for undo returns true if it worked, false otherwise

virtual bool mudbox::Image::NextVersion ( ) [virtual]

makes the next version current -- used for redo returns true if it worked, false otherwise

virtual int mudbox::Image::NumVersions ( ) [virtual]

returns the number of versions. returns 1 for unversioned images

virtual bool mudbox::Image::MergeOldestVersions ( ) [virtual]

merges the oldest two versions -- used to limit the number of items on the undo queue.

returns true if it worked, false otherwise

virtual bool mudbox::Image::PurgeNewerVersions ( ) [virtual]

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 mudbox::Image::PurgeAllButCurrentVersion ( ) [virtual]

Releases all but the current version -- used to flush the undo queue.

returns true if it worked, false otherwise

virtual void* mudbox::Image::Data ( int iRow = -1 ) [virtual]

Get a pointer to the raw data of a row of the image.

If the given row index is -1, then a pointer - if exists - to the whole data block is returned. These are deprecated and are going away shortly. DO NOT USE THEM IN NEW CODE. Use LockPageSet instead. These will not work on tiled images at all.

virtual const void* mudbox::Image::Data ( int iRow = -1 ) const [virtual]

virtual void mudbox::Image::DrawUVs	(	Material *	pMaterial,
		float	uStart = `0.0f`,
		float	vStart = `0.0f`,
		bool	baseLevel = `true`
	)	`[virtual]`

Draw the uv mesh for a given material into this image -- either the base or active level.

uv offset can be specified for tiled materials. These offsets should be 0.0, 1.0, 1.0 etc... The default is to draw from 0.0, 0.0 to 1.0, 1.0

virtual void mudbox::Image::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 `[virtual]`

Fast, thread safe image scaler.

Works only on 4 channel 8 bit/channel images Note: Not a permanent part of the API.

Friends And Related Function Documentation

friend class ImgPageIterator [friend]

friend class ImgLockPageIterator [friend]

Member Data Documentation

unsigned char mudbox::Image::m_FillPixel[16] [protected]

ImageDescriptor mudbox::Image::m_Descriptor [protected]

ImageType mudbox::Image::m_ImageType [protected]

mudbox::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