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. More... | |
Image (const Image &) noexcept | |
Creates a shared reference to another image. More... | |
Image (Image &&) noexcept | |
Move constructor. More... | |
Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage) | |
Creates an image with a specified size and format. More... | |
Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage, const ImageType &type) | |
Creates an image with a specified size and format. More... | |
Image (ReferenceCountedObjectPtr< ImagePixelData >) noexcept | |
~Image () | |
Destructor. More... | |
void | clear (const Rectangle< int > &area, Colour colourToClearTo=Colour(0x00000000)) |
Clears a section of the image with a given colour. More... | |
Image | convertedToFormat (PixelFormat newFormat) const |
Returns a version of this image with a different image format. More... | |
Image | createCopy () const |
Creates a copy of this image. More... | |
std::unique_ptr< LowLevelGraphicsContext > | createLowLevelContext () const |
Creates a context suitable for drawing onto this image. More... | |
void | createSolidAreaMask (RectangleList< int > &result, float alphaThreshold) const |
Creates a RectangleList containing rectangles for all non-transparent pixels of the image. More... | |
void | desaturate () |
Changes all the colours to be shades of grey, based on their current luminosity. More... | |
void | duplicateIfShared () |
Makes sure that no other Image objects share the same underlying data as this one. More... | |
Rectangle< int > | getBounds () const noexcept |
Returns a rectangle with the same size as this image. More... | |
Image | getClippedImage (const Rectangle< int > &area) const |
Returns an image which refers to a subsection of this image. More... | |
PixelFormat | getFormat () const noexcept |
Returns the image's pixel format. More... | |
int | getHeight () const noexcept |
Returns the image's height (in pixels). More... | |
Colour | getPixelAt (int x, int y) const |
Returns the colour of one of the pixels in the image. More... | |
ImagePixelData * | getPixelData () const noexcept |
NamedValueSet * | getProperties () const |
Returns a NamedValueSet that is attached to the image and which can be used for associating custom values with it. More... | |
int | getReferenceCount () const noexcept |
Returns the number of Image objects which are currently referring to the same internal shared image data. More... | |
int | getWidth () const noexcept |
Returns the image's width (in pixels). More... | |
bool | hasAlphaChannel () const noexcept |
True if the image contains an alpha-channel. More... | |
bool | isARGB () const noexcept |
True if the image's format is ARGB. More... | |
bool | isNull () const noexcept |
Returns true if this image is not valid. More... | |
bool | isRGB () const noexcept |
True if the image's format is RGB. More... | |
bool | isSingleChannel () const noexcept |
True if the image's format is a single-channel alpha map. More... | |
bool | isValid () const noexcept |
Returns true if this image isn't null. More... | |
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. More... | |
void | multiplyAllAlphas (float amountToMultiplyBy) |
Changes the overall opacity of the image. More... | |
void | multiplyAlphaAt (int x, int y, float multiplier) |
Changes the opacity of a pixel. More... | |
bool | operator!= (const Image &other) const noexcept |
Returns true if the two images are not referring to the same internal, shared image. More... | |
Image & | operator= (const Image &) |
Makes this image refer to the same underlying image as another object. More... | |
Image & | operator= (Image &&) noexcept |
Move assignment operator. More... | |
bool | operator== (const Image &other) const noexcept |
Returns true if the two images are referring to the same internal, shared image. More... | |
Image | rescaled (int newWidth, int newHeight, Graphics::ResamplingQuality quality=Graphics::mediumResamplingQuality) const |
Returns a rescaled version of this image. More... | |
void | setPixelAt (int x, int y, Colour colour) |
Sets the colour of one of the image's pixels. More... | |
Private Attributes | |
ReferenceCountedObjectPtr< ImagePixelData > | image |
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.
Other useful ways to create an image are with the ImageCache class, or the ImageFileFormat, which provides a way to load common image files.
@tags{Graphics}
|
noexcept |
Creates a null image.
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.
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. |
juce::Image::Image | ( | PixelFormat | format, |
int | imageWidth, | ||
int | imageHeight, | ||
bool | clearImage, | ||
const ImageType & | type | ||
) |
Creates an image with a specified size and format.
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. |
|
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().
|
noexcept |
Move constructor.
juce::Image::~Image | ( | ) |
Destructor.
|
explicitnoexcept |
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).
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.
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.
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.
void juce::Image::createSolidAreaMask | ( | RectangleList< int > & | result, |
float | alphaThreshold | ||
) | const |
Creates a RectangleList containing rectangles for all non-transparent pixels of the image.
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 |
void juce::Image::desaturate | ( | ) |
Changes all the colours to be shades of grey, based on their current luminosity.
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.
Returns a rectangle with the same size as this image.
The rectangle's origin is always (0, 0).
Referenced by juce::RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::clipToImageAlpha(), and juce::RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::renderImage().
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.
|
noexcept |
Returns the image's pixel format.
|
noexcept |
Returns the image's height (in pixels).
Referenced by juce::RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::renderImage().
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.
|
inlinenoexcept |
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.
|
noexcept |
Returns the number of Image objects which are currently referring to the same internal shared image data.
|
noexcept |
Returns the image's width (in pixels).
Referenced by juce::RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::renderImage().
|
noexcept |
True if the image contains an alpha-channel.
Referenced by juce::RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::clipToImageAlpha().
|
noexcept |
True if the image's format is ARGB.
|
inlinenoexcept |
|
noexcept |
True if the image's format is RGB.
|
noexcept |
True if the image's format is a single-channel alpha map.
|
inlinenoexcept |
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.
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.
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.
Returns true if the two images are not referring to the same internal, shared image.
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().
Returns true if the two images are referring to the same internal, shared 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.
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.
|
private |