Blend2D
2D Vector Graphics Engine
About
Roadmap
Performance
Docs
Blog
Research
Support
Download
{Fiddle}
Index ⭢ Imaging ⭢ BLImage

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
Overloaded Operators
Common Functionality
Create Functionality
Accessors
Image Utilities
Image IO

Static Functions

Additional Inherited Members

Public Attributes inherited from BLObjectCore

BLImage::BLImage()noexcept[1/4][¶]

Creates a default constructed image, which is an empty image having pixel format equal to BL_FORMAT_NONE.

BLImage::BLImage(
BLImage&& other
)noexcept[2/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(
const BLImage& other
)noexcept[3/4][¶]

Copy constructor creates a weak copy of other image by incrementing the reference count of the underlying representation.

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 is_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
) constnodiscardnoexcept[¶]

Tests whether this image is equal with other image , see equals() for more details about image equality.

bool BLImage::operator!=(
const BLImage& other
) constnodiscardnoexcept[¶]

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 is_empty() and holds no data that could be used by the rendering context or as a pattern.

void BLImage::swap(
BLImage& other
)noexcept[¶]

Swaps the underlying data with the other image.

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::assign_deep(
const BLImage& other
)noexcept[¶]

Create a deep copy of the other image.

bool BLImage::is_empty() constnodiscardnoexcept[¶]

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 is_empty() - it checks whether the image is actually holding pixel data.

bool BLImage::equals(
const BLImage& other
) constnodiscardnoexcept[¶]

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::create_from_data(
int w,
int h,
BLFormat format,
void* pixel_data,
intptr_t stride,
BLDataAccessFlags access_flags = BL_DATA_ACCESS_RW,
BLDestroyExternalDataFunc destroy_func = nullptr,
void* user_data = nullptr
)noexcept[¶]

Creates a new image from external data passed in pixel_data.

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 access_flags, 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 pixel_data anymore, pass your own function in destroy_func parameter with an optional user_data).

int BLImage::width() constnodiscardnoexcept[¶]

Returns image width (in pixels).

int BLImage::height() constnodiscardnoexcept[¶]

Returns image height (in pixels).

BLSizeI BLImage::size() constnodiscardnoexcept[¶]

Returns image size (in pixels).

BLFormat BLImage::format() constnodiscardnoexcept[¶]

Returns image format, see BLFormat.

Note

When an image is is_empty(), the pixel format returned is always BL_FORMAT_NONE.

uint32_t BLImage::depth() constnodiscardnoexcept[¶]

Returns image depth (in bits).

BLResult BLImage::get_data(
BLImageData* data_out
) constnoexcept[¶]

Returns immutable in data_out, 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 pixel_data pointer, the data is immutable. If you intend to modify the data, use make_mutable() function instead, which would copy the image data if it's shared with another BLImage instance.

BLResult BLImage::make_mutable(
BLImageData* data_out
)noexcept[¶]

Makes the image data mutable and returns it in data_out.

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 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::read_from_file(
const char* file_name
)noexcept[1/2][¶]

Reads an image from a file specified by file_name.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by BLImageCodec::built_in_codecs().

BLResult BLImage::read_from_file(
const char* file_name,
const BLArray<BLImageCodec>& codecs
)noexcept[2/2][¶]

Reads an image from a file specified by file_name 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::read_from_data(
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::built_in_codecs().

BLResult BLImage::read_from_data(
const void* data,
size_t size,
const BLArray<BLImageCodec>& codecs
)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::read_from_data(
const BLArray<uint8_t>& array
)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::built_in_codecs().

BLResult BLImage::read_from_data(
const BLArray<uint8_t>& array,
const BLArray<BLImageCodec>& codecs
)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::read_from_data(
const BLArrayView<uint8_t>& view
)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::built_in_codecs().

BLResult BLImage::read_from_data(
const BLArrayView<uint8_t>& view,
const BLArray<BLImageCodec>& codecs
)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::write_to_file(
const char* file_name
) constnoexcept[1/2][¶]

Writes an encoded image to a file specified by file_name.

Image writer detects the image codec by inspecting the extension of a file passed via file_name.

BLResult BLImage::write_to_file(
const char* file_name,
const BLImageCodec& codec
) constnoexcept[2/2][¶]

Writes an encoded image to a file specified by file_name using the specified image codec to encode the image.

BLResult BLImage::write_to_data(
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.

© 2017-2025 Blend2D Team | GitHub | Chat | Support | Download
Blend2D library and its dependencies are open source software released under the Zlib license and can be used safely in any open-source or commercial product, statically or dynamically linked, and without advertising the use of Blend2D. Code snippets and examples are released into public domain, see Unlicense for more details.