Holds a fixed-size bitmap. More...

#include "juce_Image.h"

Classes
class	BitmapData
	Retrieves a section of an image as raw pixel data, so it can be read or written to. More...

Public Types
enum	PixelFormat { UnknownFormat , RGB , ARGB , SingleChannel }

Public Member Functions
	Image () noexcept
	Creates a null image.

	Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage)
	Creates an image with a specified size and format.

	Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage, const ImageType &type)
	Creates an image with a specified size and format.

	Image (const Image &) noexcept
	Creates a shared reference to another image.

Image &	operator= (const Image &)
	Makes this image refer to the same underlying image as another object.

	Image (Image &&) noexcept
	Move constructor.

Image &	operator= (Image &&) noexcept
	Move assignment operator.

	~Image ()
	Destructor.

bool	operator== (const Image &other) const noexcept
	Returns true if the two images are referring to the same internal, shared image.

bool	operator!= (const Image &other) const noexcept
	Returns true if the two images are not referring to the same internal, shared image.

bool	isValid () const noexcept
	Returns true if this image isn't null.

bool	isNull () const noexcept
	Returns true if this image is not valid.

int	getWidth () const noexcept
	Returns the image's width (in pixels).

int	getHeight () const noexcept
	Returns the image's height (in pixels).

Rectangle< int >	getBounds () const noexcept
	Returns a rectangle with the same size as this image.

PixelFormat	getFormat () const noexcept
	Returns the image's pixel format.

bool	isARGB () const noexcept
	True if the image's format is ARGB.

bool	isRGB () const noexcept
	True if the image's format is RGB.

bool	isSingleChannel () const noexcept
	True if the image's format is a single-channel alpha map.

bool	hasAlphaChannel () const noexcept
	True if the image contains an alpha-channel.

void	clear (const Rectangle< int > &area, Colour colourToClearTo=Colour(0x00000000))
	Clears a section of the image with a given colour.

Image	rescaled (int newWidth, int newHeight, Graphics::ResamplingQuality quality=Graphics::mediumResamplingQuality) const
	Returns a rescaled version of this image.

Image	createCopy () const
	Creates a copy of this image.

Image	convertedToFormat (PixelFormat newFormat) const
	Returns a version of this image with a different image format.

void	duplicateIfShared ()
	Makes sure that no other Image objects share the same underlying data as this one.

Image	getClippedImage (const Rectangle< int > &area) const
	Returns an image which refers to a subsection of this image.

Colour	getPixelAt (int x, int y) const
	Returns the colour of one of the pixels in the image.

void	setPixelAt (int x, int y, Colour colour)
	Sets the colour of one of the image's pixels.

void	multiplyAlphaAt (int x, int y, float multiplier)
	Changes the opacity of a pixel.

void	multiplyAllAlphas (float amountToMultiplyBy)
	Changes the overall opacity of the image.

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

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< int > &result, float alphaThreshold) const
	Creates a RectangleList containing rectangles for all non-transparent pixels of the image.

NamedValueSet *	getProperties () const
	Returns a NamedValueSet that is attached to the image and which can be used for associating custom values with it.

std::unique_ptr< LowLevelGraphicsContext >	createLowLevelContext () const
	Creates a context suitable for drawing onto this image.

int	getReferenceCount () const noexcept
	Returns the number of Image objects which are currently referring to the same internal shared image data.

ImagePixelData *	getPixelData () const noexcept

	Image (ReferenceCountedObjectPtr< ImagePixelData >) noexcept

Detailed Description

Holds a fixed-size bitmap.

The image is stored in either 24-bit RGB or 32-bit premultiplied-ARGB format.

To draw into an image, create a Graphics object for it. e.g.

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

See also: Graphics, ImageFileFormat, ImageCache, ImageConvolutionKernel

@tags{Graphics}

Definition at line 57 of file juce_Image.h.

Member Enumeration Documentation

◆ PixelFormat

enum juce::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.

Definition at line 63 of file juce_Image.h.

Constructor & Destructor Documentation

◆ Image() [1/6]

juce::Image::Image ( )

noexcept

Creates a null image.

Definition at line 225 of file juce_Image.cpp.

◆ Image() [2/6]

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

Creates an image with a specified size and format.

The image's internal type will be of the NativeImageType class - to specify a different type, use the other constructor, which takes an ImageType to use.

Parameters

format	the preferred pixel format. Note that this is only a hint which is passed to the ImageType class - different ImageTypes may not support all formats, so may substitute e.g. ARGB for RGB.
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 (if it's RGB) or transparent black (if it's ARGB). If false, the image may contain junk initially, so you need to make sure you overwrite it thoroughly.

Definition at line 234 of file juce_Image.cpp.

◆ Image() [3/6]

juce::Image::Image	(	PixelFormat	format,
		int	imageWidth,
		int	imageHeight,
		bool	clearImage,
		const ImageType &	type
	)

Creates an image with a specified size and format.

Parameters

format	the preferred pixel format. Note that this is only a hint which is passed to the ImageType class - different ImageTypes may not support all formats, so may substitute e.g. ARGB for RGB.
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 (if it's RGB) or transparent black (if it's ARGB). If false, the image may contain junk initially, so you need to make sure you overwrite it thoroughly.
type	the type of image - this lets you specify the internal format that will be used to allocate and manage the image data.

Definition at line 239 of file juce_Image.cpp.

◆ Image() [4/6]

juce::Image::Image ( const Image & other )

noexcept

Creates a shared reference to another image.

This won't create a duplicate of the image - when Image objects are copied, they simply point to the same shared image data. To make sure that an Image object has its own unique, unshared internal data, call duplicateIfShared().

Definition at line 244 of file juce_Image.cpp.

◆ Image() [5/6]

juce::Image::Image ( Image && other )

noexcept

Move constructor.

Definition at line 255 of file juce_Image.cpp.

◆ ~Image()

juce::Image::~Image ( )

Destructor.

Definition at line 266 of file juce_Image.cpp.

◆ Image() [6/6]

juce::Image::Image ( ReferenceCountedObjectPtr< ImagePixelData > instance )

explicitnoexcept

Definition at line 229 of file juce_Image.cpp.

Member Function Documentation

◆ clear()

void juce::Image::clear	(	const Rectangle< int > &	area,
		Colour	colourToClearTo = `Colour (0x00000000)`
	)

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

Definition at line 453 of file juce_Image.cpp.

◆ convertedToFormat()

Image juce::Image::convertedToFormat ( PixelFormat newFormat ) const

Returns a version of this image with a different image format.

A new image is returned which has been converted to the specified format.

Note that if the new format is no different to the current one, this will just return a reference to the original image, and won't actually create a copy.

Definition at line 317 of file juce_Image.cpp.

◆ createCopy()

Image juce::Image::createCopy ( ) const

Creates a copy of this image.

Note that it's usually more efficient to use duplicateIfShared(), because it may not be necessary to copy an image if nothing else is using it.

See also: getReferenceCount

Definition at line 294 of file juce_Image.cpp.

◆ createLowLevelContext()

std::unique_ptr< LowLevelGraphicsContext > juce::Image::createLowLevelContext ( ) const

Creates a context suitable for drawing onto this image.

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

Definition at line 280 of file juce_Image.cpp.

◆ createSolidAreaMask()

void juce::Image::createSolidAreaMask	(	RectangleList< int > &	result,
		float	alphaThreshold
	)		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

Definition at line 567 of file juce_Image.cpp.

◆ desaturate()

void juce::Image::desaturate ( )

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

Definition at line 558 of file juce_Image.cpp.

◆ duplicateIfShared()

void juce::Image::duplicateIfShared ( )

Makes sure that no other Image objects share the same underlying data as this one.

If no other Image objects refer to the same shared data as this one, this method has no effect. But if there are other references to the data, this will create a new copy of the data internally.

Call this if you want to draw onto the image, but want to make sure that this doesn't affect any other code that may be sharing the same data.

See also: getReferenceCount

Definition at line 288 of file juce_Image.cpp.

◆ getBounds()

Rectangle< int > juce::Image::getBounds ( ) const

noexcept

Returns a rectangle with the same size as this image.

The rectangle's origin is always (0, 0).

Definition at line 273 of file juce_Image.cpp.

◆ getClippedImage()

Image juce::Image::getClippedImage ( const Rectangle< int > & area ) const

Returns an image which refers to a subsection of this image.

This will not make a copy of the original - the new image will keep a reference to it, so that if the original image is changed, the contents of the subsection will also change. Likewise if you draw into the subimage, you'll also be drawing onto that area of the original image. Note that if you use operator= to make the original Image object refer to something else, the subsection image won't pick up this change, it'll remain pointing at the original.

The area passed-in will be clipped to the bounds of this image, so this may return a smaller image than the area you asked for, or even a null image if the area was out-of-bounds.

Definition at line 210 of file juce_Image.cpp.

◆ getFormat()

Image::PixelFormat juce::Image::getFormat ( ) const

noexcept

Returns the image's pixel format.

Definition at line 274 of file juce_Image.cpp.

◆ getHeight()

int juce::Image::getHeight ( ) const

noexcept

Returns the image's height (in pixels).

Definition at line 272 of file juce_Image.cpp.

◆ getPixelAt()

Colour juce::Image::getPixelAt	(	int	x,
		int	y
	)		const

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

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

See also: setPixelAt, Image::BitmapData::getPixelColour

Definition at line 464 of file juce_Image.cpp.

◆ getPixelData()

ImagePixelData * juce::Image::getPixelData ( ) const

noexcept

Definition at line 412 of file juce_Image.h.

◆ getProperties()

NamedValueSet * juce::Image::getProperties ( ) const

Returns a NamedValueSet that is attached to the image and which can be used for associating custom values with it.

If this is a null image, this will return a null pointer.

Definition at line 374 of file juce_Image.cpp.

◆ getReferenceCount()

int juce::Image::getReferenceCount ( ) const

noexcept

Returns the number of Image objects which are currently referring to the same internal shared image data.

See also: duplicateIfShared

Definition at line 270 of file juce_Image.cpp.

◆ getWidth()

int juce::Image::getWidth ( ) const

noexcept

Returns the image's width (in pixels).

Definition at line 271 of file juce_Image.cpp.

◆ hasAlphaChannel()

bool juce::Image::hasAlphaChannel ( ) const

noexcept

True if the image contains an alpha-channel.

Definition at line 278 of file juce_Image.cpp.

◆ isARGB()

bool juce::Image::isARGB ( ) const

noexcept

True if the image's format is ARGB.

Definition at line 275 of file juce_Image.cpp.

◆ isNull()

bool juce::Image::isNull ( ) const

noexcept

Returns true if this image is not valid.

If you create an Image with the default constructor, it has no size or content, and is null until you reassign it to an Image which contains some actual data. The isNull() method is the opposite of isValid().

See also: isValid

Definition at line 155 of file juce_Image.h.

◆ isRGB()

bool juce::Image::isRGB ( ) const

noexcept

True if the image's format is RGB.

Definition at line 276 of file juce_Image.cpp.

◆ isSingleChannel()

bool juce::Image::isSingleChannel ( ) const

noexcept

True if the image's format is a single-channel alpha map.

Definition at line 277 of file juce_Image.cpp.

◆ isValid()

bool juce::Image::isValid ( ) const

noexcept

Returns true if this image isn't null.

If you create an Image with the default constructor, it has no size or content, and is null until you reassign it to an Image which contains some actual data. The isNull() method is the opposite of isValid().

See also: isNull

Definition at line 147 of file juce_Image.h.

◆ moveImageSection()

void juce::Image::moveImageSection	(	int	destX,
		int	destY,
		int	sourceX,
		int	sourceY,
		int	width,
		int	height
	)

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

Definition at line 617 of file juce_Image.cpp.

◆ multiplyAllAlphas()

void juce::Image::multiplyAllAlphas ( float amountToMultiplyBy )

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.

Definition at line 541 of file juce_Image.cpp.

◆ multiplyAlphaAt()

void juce::Image::multiplyAlphaAt	(	int	x,
		int	y,
		float	multiplier
	)

Changes the opacity of a pixel.

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

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

See also: setPixelAt

Definition at line 484 of file juce_Image.cpp.

◆ operator!=()

bool juce::Image::operator!= ( const Image & other ) const

noexcept

Returns true if the two images are not referring to the same internal, shared image.

Definition at line 139 of file juce_Image.h.

◆ operator=() [1/2]

Image & juce::Image::operator= ( const Image & other )

Makes this image refer to the same underlying image as another object.

This won't create a duplicate of the image - when Image objects are copied, they simply point to the same shared image data. To make sure that an Image object has its own unique, unshared internal data, call duplicateIfShared().

Definition at line 249 of file juce_Image.cpp.

◆ operator=() [2/2]

Image & juce::Image::operator= ( Image && other )

noexcept

Move assignment operator.

Definition at line 260 of file juce_Image.cpp.

◆ operator==()

bool juce::Image::operator== ( const Image & other ) const

noexcept

Returns true if the two images are referring to the same internal, shared image.

Definition at line 136 of file juce_Image.h.

◆ rescaled()

Image juce::Image::rescaled	(	int	newWidth,
		int	newHeight,
		Graphics::ResamplingQuality	quality = `Graphics::mediumResamplingQuality`
	)		const

Returns a rescaled version of this image.

A new image is returned which is a copy of this one, rescaled to the given size.

Note that if the new size is identical to the existing image, this will just return a reference to the original image, and won't actually create a duplicate.

Definition at line 302 of file juce_Image.cpp.

◆ setPixelAt()

void juce::Image::setPixelAt	(	int	x,
		int	y,
		Colour	colour
	)

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

If the coordinates are beyond the image's boundaries, then nothing will happen.

Note that 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.

See also: getPixelAt, Image::BitmapData::setPixelColour

Definition at line 475 of file juce_Image.cpp.

The documentation for this class was generated from the following files:

juce_graphics/images/juce_Image.h
juce_graphics/images/juce_Image.cpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ PixelFormat

Constructor & Destructor Documentation

◆ Image() [1/6]

◆ Image() [2/6]

◆ Image() [3/6]

◆ Image() [4/6]

◆ Image() [5/6]

◆ ~Image()

◆ Image() [6/6]

Member Function Documentation

◆ clear()

◆ convertedToFormat()

◆ createCopy()

◆ createLowLevelContext()

◆ createSolidAreaMask()

◆ desaturate()

◆ duplicateIfShared()

◆ getBounds()

◆ getClippedImage()

◆ getFormat()

◆ getHeight()

◆ getPixelAt()

◆ getPixelData()

◆ getProperties()

◆ getReferenceCount()

◆ getWidth()

◆ hasAlphaChannel()

◆ isARGB()

◆ isNull()

◆ isRGB()

◆ isSingleChannel()

◆ isValid()

◆ moveImageSection()

◆ multiplyAllAlphas()

◆ multiplyAlphaAt()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ rescaled()

◆ setPixelAt()