IndexC API
C API

Blend2D C API structs and functions exported as extern "C" (C API).

We do not document most C API 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 instances is managed.

Each type that requires initialization provides bl[...]Init, 'bl[...]Destroy', and bl[...]Reset C API 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.
blImageInit(&img);
// 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.
blImageDestroy(&img);

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.
blImageDestroy(&img);

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. On 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 constructed 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:

// 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 explicitly destroyed when it's no longer needed to release the associated data it holds.
BLResult result = blImageCreate(&img, 128, 128, BL_FORMAT_PRGB32);
// If `blImageCreate()` failed it leaves the object in the state it was prior to the call. Most of API calls
// in Blend2D behave like this (it's transactional). This means that if the call failed the `img` would still
// be default constructed and the function can simply return without leaking any resources. In C++ API the
// compiler would emit a call to `blImageDestroy()` implicitly, but that's just how RAII works.
if (result != BL_SUCCESS)
return result;
// Resetting image would destroy its data and make it default constructed.
blImageReset(&img);
// The instance is valid after `reset()` - it's now a default constructed instance as created by `blImageInit()`.
printf("%p", img.impl);
// Calling `blImageDestroy()` would make the instance invalid.
blImageDestroy(&img);
// Calling any method except initialization such as `blImageInit()` on invalid instance is UNDEFINED BEHAVIOR!
blImageCreate(&img, 128, 128, BL_FORMAT_PRGB32); // Can crash, can corrupt memory, can succeed, never do that!

BLArray - C API

Array functionality is provided by BLArrayCore in C API and wrapped by BLArray<T> 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 an implementation perspective.

BLBitArray - C API

BLBitSet - C API

BLContext - C API

BLFile C API Functions

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

BLFileSystem C API Functions

BLFont - C API

BLFontData - C API

BLFontFace - C API

BLFontFeatureSettings - C API

BLFontManager - C API

BLFontVariationSettings - C API

BLFormat - C API

BLGlyphBuffer - C API

BLGradient - C API

BLImage - C API

BLImageCodec - C API

BLImageDecoder - C API

BLImageEncoder - C API

BLMatrix2D - C API

Functions that initialize and manipulate BLMatrix2D content.

BLObject - C API

BLPath - C API

BLPattern - C API

BLPixelConverter - C API

BLRandom - C API

BLRuntime - C API

BLString - C API

BLVar - C API

BLResult blRuntimeInit()noexcept[¶]

Initialized Blend2D runtime.

BLResult blRuntimeShutdown()noexcept[¶]

Shuts down Blend2D runtime.