C API

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 and Reset functions. These functions 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 Reset works:

blImageInit(&img);
blImageCreate(&img, 128, 128, BL_FORMAT_PRGB32);
blImageReset(&img);

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

blImageInitAs(&img, 128, 128, BL_FORMAT_PRGB32);
blImageReset(&img);

It's worth nothing 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 reset as they don't hold any data (however never do that in practice). Resetting always resets the object into its default initialized form, so you can reuse such object afterwards (after reset it's still properly initialized) or consider it destroyed.

The following example should explain how init/reset works:

// 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 (result != BL_SUCCESS) {
// 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 reset it explicitly although the C++ API would do it in
// image destructor.
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 as the data it holds
// is still valid, but the image is of course empty.
printf("%d", blImageEquals(&img, &img));

BLArray

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.

BLContext

BLFile

BLFileSystem

BLFont

BLFontData

BLFontFace

BLFontLoader

BLFormat

BLGlyphBuffer

BLGradient

BLImage

BLImageCodec

BLImageDecoder

BLImageEncoder

BLMatrix2D

BLPath

BLPattern

BLPixelConverter

BLRandom

BLRegion

BLRuntime

BLString

BLStrokeOptions

BLVariant