Blend2D
2D Vector Graphics Engine
BLImage Class Referencefinal
2D raster image [C++ API].
Raster image holds pixel data and additional information such as pixel format. The underlying image data can be shared between multiple instances of BLImage, which can be used by multiple threads. Atomic reference counting is used to safely manage the internal reference count of the underlying image data.
When an image is copied to another BLImage instance its called a weak-copy as the underlying data is not copied, but the reference count is increased instead (atomically). Since atomic operations involve a minor overhead Blend2D implements also move operations, which are the most efficient operations that can be used to move one instance to another.
Member Functions
Construction & Destruction
BLImage() noexcept
~BLImage()
Overloaded Operators
Common Functionality
Create Functionality
BLResult createFromData(int w, int h, BLFormat format, void* pixelData, intptr_t stride, BLDataAccessFlags accessFlags = BL_DATA_ACCESS_RW, BLDestroyExternalDataFunc destroyFunc = nullptr, void* userData = nullptr) noexcept
Accessors
Image Utilities
Image IO
BLResult readFromData(const BLArrayView<uint8_t>& view, const BLArray<BLImageCodec>& codecs) noexcept
Static Functions
Additional Inherited Members
Public Attributes inherited from BLObjectCoreBLImage::BLImage()noexcept[1/4][¶]
Creates a default constructed image, which is an empty image having pixel format equal to BL_FORMAT_NONE.
BLImage::BLImage(const BLImage& other)noexcept[2/4][¶]
Copy constructor creates a weak copy of other image by incrementing the reference count of the underlying representation.
BLImage::BLImage(BLImage&& other)noexcept[3/4][¶]
Move constructor moves other image this this image and sets other image to a default constructed state.
This is the most efficient operation as the reference count of the underlying image is not touched by a move operation.
BLImage::BLImage(int w, int h, BLFormat format)noexcept[4/4][¶]
Creates a new image data of [w, h] size (specified in pixels) having the given pixel format.
To create a valid image, both w and h must be greater than zero and the pixel format cannot be BL_FORMAT_NONE.
- Note
- Since C++ cannot return values via constructors you should verify that the image was created by using either explicit
operator bool()or verifying the image is not empty().
BLImage::~BLImage()[¶]
Destroys the image data held by the instance.
The pixel data held by the image will only be deallocated if the reference count of the underlying representation gets decremented to zero.
BLImage::operator bool() constexplicitnoexcept[¶]
Returns whether the image holds any data, which means that both width and height are greater than zero and that the pixel format is not BL_FORMAT_NONE (which would never be true if the size is non-zero).
BLImage& BLImage::operator=(const BLImage& other)noexcept[1/2][¶]
Copy assignment replaces the underlying data of this image with a weak-copy of the other image.
BLImage& BLImage::operator=(BLImage&& other)noexcept[2/2][¶]
Move assignment replaces the underlying data of this image with the other image and resets other image to a default constructed image. This operation is the fastest operation to change the underlying data of an image as moving doesn't involve reference counting in most cases.
bool BLImage::operator==(const BLImage& other) constnoexcept[¶]
Tests whether this image is equal with other image , see equals() for more details about image equality.
bool BLImage::operator!=(const BLImage& other) constnoexcept[¶]
Tests whether this image is not equal with other image , see equals() for more details about image equality.
BLResult BLImage::reset()noexcept[¶]
Resets the image to a default constructed image.
A default constructed image has zero size and a pixel format equal to BL_FORMAT_NONE. Such image is considered empty() and holds no data that could be used by the rendering context or as a pattern.
BLResult BLImage::assign(const BLImage& other)noexcept[1/2][¶]
Copy assignment replaces the underlying data of this image with other, see operator=() for more details.
BLResult BLImage::assign(BLImage&& other)noexcept[2/2][¶]
Move assignment replaces the underlying data of this image with other and resets other image to a default constructed state, see operator=() for more details.
BLResult BLImage::assignDeep(const BLImage& other)noexcept[¶]
Create a deep copy of the other image.
bool BLImage::empty() constnoexcept[¶]
Tests whether the image is empty (such image has no size and a pixel format is equal to BL_FORMAT_NONE).
- Note
- You can use
operator bool(), which does the reverse of empty() - it checks whether the image is actually holding pixel data.
bool BLImage::equals(const BLImage& other) constnoexcept[¶]
Tests whether the image is equal to other image.
Images are equal when the size, pixel format, and pixel data match. This means that this operation could be very expensive if the images are large.
BLResult BLImage::create(int w, int h, BLFormat format)noexcept[¶]
Creates a new image of a specified width w, height h, and format.
- Note
- It's important to always test whether the function succeeded as allocating pixel-data can fail. If invalid arguments (invalid size or format) were passed to the function BL_ERROR_INVALID_VALUE will be returned and no data will be allocated. It's also important to notice that create() would not change anything if the function fails (the previous image content would be kept as is in such case).
BLResult BLImage::createFromData(int w, int h, BLFormat format, void* pixelData, intptr_t stride, BLDataAccessFlags accessFlags = BL_DATA_ACCESS_RW, BLDestroyExternalDataFunc destroyFunc = nullptr, void* userData = nullptr)noexcept[¶]
Creates a new image from external data passed in pixelData.
Blend2D can use pixel-data allocated outside of Blend2D, which is useful for rendering into images that can be allocated by other libraries such as AGG, Cairo, Qt, Windows API (DIBSECTION), etc.. The only thing that the user should pay extra attention to is the passed pixel format and stride.
If the image data you are passing is read-only, pass BL_DATA_ACCESS_READ in accessFlags, in that case Blend2D would never attempt to modify the passed data and would create a copy instead if such image gets modified.
Additionally, if you would like to get notified about the destruction of the image (and thus Blend2D not holding the passed pixelData anymore, pass your own function in destroyFunc parameter with an optional userData).
int BLImage::width() constnoexcept[¶]
Returns image width (in pixels).
int BLImage::height() constnoexcept[¶]
Returns image height (in pixels).
BLFormat BLImage::format() constnoexcept[¶]
Returns image format, see BLFormat.
- Note
- When an image is empty(), the pixel format returned is always BL_FORMAT_NONE.
uint32_t BLImage::depth() constnoexcept[¶]
Returns image depth (in bits).
BLResult BLImage::getData(BLImageData* dataOut) constnoexcept[¶]
Returns immutable in dataOut, which contains pixel pointer, stride, and other image properties like size and pixel format.
- Note
- Although the data is filled in BLImageData, which holds a non-const
pixelDatapointer, the data is immutable. If you intend to modify the data, use makeMutable() function instead, which would copy the image data if it's shared with another BLImage instance.
BLResult BLImage::makeMutable(BLImageData* dataOut)noexcept[¶]
Makes the image data mutable and returns them in dataOut.
BLResult BLImage::convert(BLFormat format)noexcept[¶]
Converts the image to a different pixel format.
This operation could be lossy if the given pixel format has less channels than this image.
- Note
- If the image is empty() the image format would not be changed. It will stay BL_FORMAT_NONE and BL_ERROR_NOT_INITIALIZED will be returned.
BLResult BLImage::readFromFile(const char* fileName)noexcept[1/2][¶]
Reads an image from a file specified by fileName.
Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by BLImageCodec::builtInCodecs().
BLResult BLImage::readFromFile(const char* fileName, )noexcept[2/2][¶]
Reads an image from a file specified by fileName by using image codecs passed via codecs parameter.
Image reader will automatically detect the image format by checking whether it's supported by the passed image codecs - only codecs passed in will be considered.
BLResult BLImage::readFromData(const void* data, size_t size)noexcept[1/6][¶]
Reads an image from an existing byte-array starting at data and having size bytes.
Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by BLImageCodec::builtInCodecs().
BLResult BLImage::readFromData(const void* data, size_t size, )noexcept[2/6][¶]
Reads an image from an existing byte-array starting at data and having size bytes by using image codecs passed via codecs parameter.
Image reader will automatically detect the image format by checking whether it's supported by the passed image codecs - only codecs passed in will be considered.
BLResult BLImage::readFromData()noexcept[3/6][¶]
Reads an image from an existing byte-buffer passed via array.
Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by BLImageCodec::builtInCodecs().
BLResult BLImage::readFromData()noexcept[4/6][¶]
Reads an image from an existing byte-buffer passed via array by using image codecs passed via codecs parameter.
Image reader will automatically detect the image format by checking whether it's supported by the passed image codecs - only codecs passed in will be considered.
BLResult BLImage::readFromData()noexcept[5/6][¶]
Reads an image from an existing byte-view passed via view.
Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by BLImageCodec::builtInCodecs().
BLResult BLImage::readFromData()noexcept[6/6][¶]
Reads an image from an existing byte-view passed via view by using image codecs passed via codecs parameter.
Image reader will automatically detect the image format by checking whether it's supported by the passed image codecs - only codecs passed in will be considered.
BLResult BLImage::writeToFile(const char* fileName) constnoexcept[1/2][¶]
Writes an encoded image to a file specified by fileName.
Image writer detects the image codec by inspecting the extension of a file passed via fileName.
BLResult BLImage::writeToFile(const char* fileName, const BLImageCodec& codec) constnoexcept[2/2][¶]
Writes an encoded image to a file specified by fileName using the specified image codec to encode the image.
BLResult BLImage::writeToData(BLArray<uint8_t>& dst, const BLImageCodec& codec) constnoexcept[¶]
Writes an encoded image to a buffer dst using the specified image codec to encode the image.
BLResult BLImage::scale(BLImage& dst, const BLImage& src, const BLSizeI& size, BLImageScaleFilter filter)staticnoexcept[¶]
Scales the src image to the specified size by using filter and writes the scaled image to dst.
If the destination image dst doesn't match size and the source pixel format the underlying image data will be re-created.