Global C API functions exported as extern "C" (C API).

We do not document these functions as they are called from C++ wrappers, which are documented and should be used as a reference. The most important thing in using C API is to understand how lifetime of objects is managed.

Each type that requires initialization provides Init, 'Destroy', and Reset functions. Init/Destroy are called by C++ constructors and destructors on C++ side and must be used the same way by C users. Although these functions return BLResult it's guaranteed the result is always BL_SUCCESS - the return value is only provided for consistency and possible tail calling.

The following example should illustrate how Init and Destroy works:

// Initializes the BLImage object, always succeeds.
// Creates image data, note how it's called on an already initialized object.
blImageCreate(&img, 128, 128, BL_FORMAT_PRGB32);
// Destroys the BLImage object, always succeeds.

Some init functions may provide shortcuts for the most used scenarios that merge initialization and resource allocation into a single function:

// Combines blImageInit() with blImageCreate().
blImageInitAs(&img, 128, 128, BL_FORMAT_PRGB32);
// Destroys the data, doesn't have to be called if blImageInitAs() failed.

It's worth knowing that default initialization in Blend2D costs nothing and no resources are allocated, thus initialization never fails and in theory default initialized objects don't have to be destroyed as they don't hold any data that would have to be deallocated (however never do that in practice).

There is a distinction between 'Destroy' and 'Reset' functionality. Destroy would destroy the object and put it into a non-reusable state. Thus if the object is used by accident it should crash on null-pointer access. In the contrary resetting the object with 'Reset' explicitly states that the instance will be reused so 'Reset' basically destroys the object and puts it into its default initialized state for further use. This means that it's not needed to explicitly call 'Destroy' on instance that was reset, and it also is not needed for a default constructed instance. However, we recommend to not count on this behavior and to always properly initialize and destroy Blend2D objects.

The following example should explain how init/reset can avoid destroy:

``` BLImageCore img;

// Now image is default constructed/initialized. if you did just this and // abandon it then no resources will be leaked as default construction is // not allocating any resources nor increasing any reference counters. blImageInit(&img);

// Now image will have to dynamically allocate some memory to store pixel // data. If this succeeds the image will have to be reset to destroy the // data it holds. BLResult result = blImageCreate(&img, 128, 128, BL_FORMAT_PRGB32);

// If function fails it should behave like it was never called, so img // would still be default initialized in this case. this means that you // don't have to destroy it explicitly although the C++ API would do it in // BLImage destructor. if (result != BL_SUCCESS) return result;

// Resetting image would destroy its data and make it default constructed. blImageReset(&img);

// You can still use the image after it has been reset, however, since the // image is default initialized it's empty. printf("%p", img.impl);

// The instance is still valid, to make it invalid we can destroy it for good. blImageDestroy(&img);

// At the moment null will be printed, but that's implementation dependent // and such behavior can change at any time. printf("%p", img.impl); ```


Array functionality is provided by BLArrayCore in C-API and wrapped by BLArray template in C++ API.

C API users must call either generic functions with Item suffix or correct specialized functions in case of typed arrays. For example if you create a BLArray<uint32_t> in C then you can only modify it through functions that have either U32 or Item suffix. Arrays of signed types are treated as arrays of unsigned types at API level as there is no difference between them from implementation perspective.


Rendering functionality is provided by BLContextCore in C-API and wrapped by BLContext in C++ API.


File read/write functionality is provided by BLFileCore in C-API and wrapped by BLFile in C++ API.


Filesystem API is provided by functions prefixed with blFileSystem and wrapped by BLFileSystem namespace in C++ API.


Font functionality is provided by BLFontCore in C-API and wrapped by BLFont in C++ API.


Font-data functionality is provided by BLFontDataCore in C-API and wrapped by BLFontData in C++ API.


Font-face functionality is provided by BLFontFaceCore in C-API and wrapped by BLFontFace in C++ API.


Font management functionality is provided by BLFontManagerCore in C-API and wrapped by BLFontManager in C++ API.



Glyph-buffer functionality is provided by BLGlyphBufferCore in C-API and wrapped by BLGlyphBuffer in C++ API.


Gradient container is provided by BLGradientCore in C-API and wrapped by BLGradient in C++ API.


Image container is provided by BLImageCore in C-API and wrapped by BLImage in C++ API.


Image codec functionality is provided by BLImageCodecCore in C-API and wrapped by BLImageCodec in C++ API.


Image decoder functionality is provided by BLImageDecoderCore in C-API and wrapped by BLImageDecoder in C++ API.


Image encoder functionality is provided by BLImageEncoderCore in C-API and wrapped by BLImageEncoder in C++ API.


Matrix functionality is provided by BLMatrix2D, C++ API adds methods to the struct when compiling in C++ mode.


2D path functionality is provided by BLPathCore in C-API and wrapped by BLPath in C++ API.


Pattern functionality is provided by BLPatternCore in C-API and wrapped by BLPattern in C++ API.


Pixel conversion functionality is provided by BLPixelConverterCore in C-API and wrapped by BLPixelConverter in C++ API.



2D region functionality is provided by BLRegionCore in C-API and wrapped by BLRegion in C++ API.


Blend2D runtime functions are provided either as a C-API or wrapped by BLRuntime namespace in C++ API.


String contanter is provided by BLStringCore in C-API and wrapped by BLString in C++ API.


Stroke options are provided by BLStrokeOptionsCore in C-API and wrapped by BLStrokeOptions in C++ API.



Variant C-API can be used on any object compatible with Blend2D Impl, at the moment only BLStrokeOptionsCore and BLGlyphBufferCore are not compatible, all others are.