2D Vector Graphics Engine
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
Some init functions may provide shortcuts for the most used scenarios that merge initialization and resource allocation into a single function:
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: