JUCE

    // create a transparent 500x500 image..
    Image myImage (Image::RGB, 500, 500, true);

    Graphics g (myImage);
    g.setColour (Colours::red);
    g.fillEllipse (20, 20, 300, 200);  // draws a red ellipse in our image.

Other useful ways to create an image are with the ImageCache class, or the ImageFileFormat, which provides a way to load common image files.


Public Types
enum	PixelFormat { RGB, ARGB, SingleChannel }
Public Member Functions
	Image (const PixelFormat format, const int imageWidth, const int imageHeight, const bool clearImage)
	Creates an in-memory image with a specified size and format.
	Image (const Image &other)
	Creates a copy of another image.
virtual	~Image ()
	Destructor.
int	getWidth () const throw ()
	Returns the image's width (in pixels).
int	getHeight () const throw ()
	Returns the image's height (in pixels).
PixelFormat	getFormat () const throw ()
	Returns the image's pixel format.
bool	isARGB () const throw ()
	True if the image's format is ARGB.
bool	isRGB () const throw ()
	True if the image's format is RGB.
bool	hasAlphaChannel () const throw ()
	True if the image contains an alpha-channel.
virtual void	clear (int x, int y, int w, int h, const Colour &colourToClearTo=Colour(0x00000000))
	Clears a section of the image with a given colour.
virtual Image *	createCopy (int newWidth=-1, int newHeight=-1, const Graphics::ResamplingQuality quality=Graphics::mediumResamplingQuality) const
	Returns a new image that's a copy of this one.
virtual const Colour	getPixelAt (const int x, const int y) const
	Returns the colour of one of the pixels in the image.
virtual void	setPixelAt (const int x, const int y, const Colour &colour)
	Sets the colour of one of the image's pixels.
virtual void	multiplyAlphaAt (const int x, const int y, const float multiplier)
	Changes the opacity of a pixel.
virtual void	multiplyAllAlphas (const float amountToMultiplyBy)
	Changes the overall opacity of the image.
virtual void	desaturate ()
	Changes all the colours to be shades of grey, based on their current luminosity.
virtual uint8 *	lockPixelDataReadWrite (int x, int y, int w, int h, int &lineStride, int &pixelStride)
	Locks some of the pixels in the image so they can be read and written to.
virtual void	releasePixelDataReadWrite (void *sourceData)
	Releases a block of memory that was locked with lockPixelDataReadWrite().
virtual const uint8 *	lockPixelDataReadOnly (int x, int y, int w, int h, int &lineStride, int &pixelStride) const
	Locks some of the pixels in the image so they can be read.
virtual void	releasePixelDataReadOnly (const void *sourceData) const
	Releases a block of memory that was locked with lockPixelDataReadOnly().
virtual void	setPixelData (int destX, int destY, int destW, int destH, const uint8 *sourcePixelData, int sourceLineStride)
	Copies some pixel values to a rectangle of the image.
virtual void	moveImageSection (int destX, int destY, int sourceX, int sourceY, int width, int height)
	Copies a section of the image to somewhere else within itself.
void	createSolidAreaMask (RectangleList &result, const float alphaThreshold=0.5f) const
	Creates a RectangleList containing rectangles for all non-transparent pixels of the image.
virtual juce_UseDebuggingNewOperator LowLevelGraphicsContext *	createLowLevelContext ()
	Creates a context suitable for drawing onto this image.
Protected Member Functions
	Image (const PixelFormat format, const int imageWidth, const int imageHeight)
	Used internally so that subclasses can call a constructor that doesn't allocate memory.
Protected Attributes
const PixelFormat	format
const int	imageWidth
const int	imageHeight
int	pixelStride
int	lineStride
uint8 *	imageData

Member Enumeration Documentation

enum Image::PixelFormat

Enumerator:

RGB	< each pixel is a 3-byte packed RGB colour value. For byte order, see the PixelRGB class.
ARGB	< each pixel is a 4-byte ARGB premultiplied colour value. For byte order, see the PixelARGB class.
SingleChannel	< each pixel is a 1-byte alpha channel value.

Constructor & Destructor Documentation

Image::Image	(	const PixelFormat	format,
		const int	imageWidth,
		const int	imageHeight,
		const bool	clearImage
	)

Creates an in-memory image with a specified size and format.

Parameters:

	format	the number of colour channels in the image
	imageWidth	the desired width of the image, in pixels - this value must be greater than zero (otherwise a width of 1 will be used)
	imageHeight	the desired width of the image, in pixels - this value must be greater than zero (otherwise a height of 1 will be used)
	clearImage	if true, the image will initially be cleared to black or transparent black. If false, the image may contain random data, and the user will have to deal with this

Image::Image

(

const Image &

other

)

Creates a copy of another image.

See also:: createCopy

Image::Image	(	const PixelFormat	format,
		const int	imageWidth,
		const int	imageHeight
	)	`[protected]`

Used internally so that subclasses can call a constructor that doesn't allocate memory.

Member Function Documentation

int Image::getHeight

(

)

const throw ()

Returns the image's height (in pixels).

PixelFormat Image::getFormat

(

)

const throw ()

Returns the image's pixel format.

bool Image::hasAlphaChannel

(

)

const throw ()

True if the image contains an alpha-channel.

virtual void Image::clear	(	int	x,
		int	y,
		int	w,
		int	h,
		const Colour &	colourToClearTo = `Colour(0x00000000)`
	)	`[virtual]`

Clears a section of the image with a given colour.

This won't do any alpha-blending - it just sets all pixels in the image to the given colour (which may be non-opaque if the image has an alpha channel).

virtual Image* Image::createCopy	(	int	newWidth = `-1`,
		int	newHeight = `-1`,
		const Graphics::ResamplingQuality	quality = `Graphics::mediumResamplingQuality`
	)	const `[virtual]`

Returns a new image that's a copy of this one.

A new size for the copied image can be specified, or values less than zero can be passed-in to use the image's existing dimensions.

It's up to the caller to delete the image when no longer needed.

virtual const Colour Image::getPixelAt	(	const int	x,
		const int	y
	)	const `[virtual]`

Returns the colour of one of the pixels in the image.

If the co-ordinates given are beyond the image's boundaries, this will return Colours::transparentBlack.

(0, 0) is the image's top-left corner.

See also:: getAlphaAt, setPixelAt, blendPixelAt

virtual void Image::setPixelAt	(	const int	x,
		const int	y,
		const Colour &	colour
	)	`[virtual]`

Sets the colour of one of the image's pixels.

If the co-ordinates are beyond the image's boundaries, then nothing will happen.

Note that unlike blendPixelAt(), this won't do any alpha-blending, it'll just replace the existing pixel with the given one. The colour's opacity will be ignored if this image doesn't have an alpha-channel.

(0, 0) is the image's top-left corner.

See also:: blendPixelAt

virtual void Image::multiplyAlphaAt	(	const int	x,
		const int	y,
		const float	multiplier
	)	`[virtual]`

Changes the opacity of a pixel.

This only has an effect if the image has an alpha channel and if the given co-ordinates are inside the image's boundary.

The multiplier must be in the range 0 to 1.0, and the current alpha at the given co-ordinates will be multiplied by this value.

See also:: getAlphaAt, setPixelAt

virtual void Image::multiplyAllAlphas ( const float amountToMultiplyBy ) [virtual]

Changes the overall opacity of the image.

This will multiply the alpha value of each pixel in the image by the given amount (limiting the resulting alpha values between 0 and 255). This allows you to make an image more or less transparent.

If the image doesn't have an alpha channel, this won't have any effect.

virtual void Image::desaturate ( ) [virtual]

Changes all the colours to be shades of grey, based on their current luminosity.

virtual uint8* Image::lockPixelDataReadWrite	(	int	x,
		int	y,
		int	w,
		int	h,
		int &	lineStride,
		int &	pixelStride
	)	`[virtual]`

Locks some of the pixels in the image so they can be read and written to.

This returns a pointer to some memory containing the pixels in the given rectangle. It also returns values for the line and pixel stride used within the data. The format of the pixel data is the same as that of this image.

When you've finished reading and changing the data, you must call releasePixelDataReadWrite() to give the pixels back to the image.

For images that are stored in memory, this method may just return a direct pointer to the image's data, but other types of image may be stored elsewhere, e.g. in video memory, and if so, this lockPixelDataReadWrite() and releasePixelDataReadWrite() may need to create a temporary copy in main memory.

If you only need read-access to the pixel data, use lockPixelDataReadOnly() instead.

See also:: releasePixelDataReadWrite, lockPixelDataReadOnly

virtual void Image::releasePixelDataReadWrite ( void * sourceData ) [virtual]

Releases a block of memory that was locked with lockPixelDataReadWrite().

virtual const uint8* Image::lockPixelDataReadOnly	(	int	x,
		int	y,
		int	w,
		int	h,
		int &	lineStride,
		int &	pixelStride
	)	const `[virtual]`

Locks some of the pixels in the image so they can be read.

When you've finished reading the data, you must call releasePixelDataReadOnly() to let the image free the memory if necessary.

If you only need to read and write the pixel data, use lockPixelDataReadWrite() instead.

See also:: releasePixelDataReadOnly, lockPixelDataReadWrite

virtual void Image::releasePixelDataReadOnly ( const void * sourceData ) const [virtual]

Releases a block of memory that was locked with lockPixelDataReadOnly().

virtual void Image::setPixelData	(	int	destX,
		int	destY,
		int	destW,
		int	destH,
		const uint8 *	sourcePixelData,
		int	sourceLineStride
	)	`[virtual]`

Copies some pixel values to a rectangle of the image.

The format of the pixel data must match that of the image itself, and the rectangle supplied must be within the image's bounds.

virtual void Image::moveImageSection	(	int	destX,
		int	destY,
		int	sourceX,
		int	sourceY,
		int	width,
		int	height
	)	`[virtual]`

Copies a section of the image to somewhere else within itself.

void Image::createSolidAreaMask	(	RectangleList &	result,
		const float	alphaThreshold = `0.5f`
	)	const

Creates a RectangleList containing rectangles for all non-transparent pixels of the image.

Parameters:

	result	the list that will have the area added to it
	alphaThreshold	for a semi-transparent image, any pixels whose alpha is above this level will be considered opaque

virtual juce_UseDebuggingNewOperator LowLevelGraphicsContext* Image::createLowLevelContext ( ) [virtual]

Creates a context suitable for drawing onto this image.

Don't call this method directly! It's used internally by the Graphics class.

Image Class Reference

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation