Global API

Global functions, constants, and classes used universally across the library.

Classes

Typedefs

Enumerations

BLBitSet - Constants

BLBitSet - C++ API

Debugging Functionality

Explicit Construction & Destruction.

These should be only necessary when extending Blend2D.

Global C++ Functions

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

BLRandom - C API

BLString - C API

BLVar - C API

Typedef Documentation

typedef uint32_t BLResult◆ 

Result code used by most Blend2D functions (32-bit unsigned integer).

The BLResultCode enumeration contains Blend2D result codes that contain Blend2D specific set of errors and an extended set of errors that can come from WIN32 or POSIX APIs. Since the success result code is zero it's recommended to use the following check to determine whether a call failed or not:

BLResult result = doSomething();
if (result != BL_SUCCESS) {
// `doSomething()` failed...
}

typedef uint32_t BLTag◆ 

Tag is a 32-bit integer consisting of 4 characters in the following format:

tag = ((a << 24) | (b << 16) | (c << 8) | d)

Tags are used extensively by OpenType fonts and other binary formats like PNG. In most cases TAGs should only contain ASCII letters, digits, and spaces.

Blend2D uses BLTag in public and internal APIs to distinguish between a regular uint32_t and tag.

typedef uint64_t BLUniqueId◆ 

Unique identifier that can be used for caching purposes.

Some objects such as BLImage and BLFontFace have assigned an unique identifier that can be used to identify such objects for caching purposes. This identifier is never zero, so zero can be safely used as "uncached".

Note
Unique identifier is per-process. It's implemented as an increasing global or thread-local counter in a way that identifiers would not collide.

typedef void BLUnknown◆ 

BLUnknown is void - it's used in places that accept pointer to BLVarCore or any BLObjectCore compatible object.

typedef void(* BLDebugMessageSinkFunc)(const char* message, size_t size, void* userData)◆ 

A sink that can be used to debug various parts of Blend2D.

typedef BLArrayView<char> BLStringView◆ 

View of char[] data used by String.

typedef BLArrayView<uint8_t> BLDataView◆ 

View of untyped data.

using BLBitSetBuilder = BLBitSetBuilderT<512>◆ 

BitSet builder [C++ API] that is configured to have a temporary storage of 512 bits.

Enumeration Type Documentation

BLResultCode : uint32_tenum◆ 

Blend2D result code.

ConstantDescription
BL_SUCCESS 

Successful result code.

BL_ERROR_OUT_OF_MEMORY 

Out of memory [ENOMEM].

BL_ERROR_INVALID_VALUE 

Invalid value/argument [EINVAL].

BL_ERROR_INVALID_STATE 

Invalid state [EFAULT].

BL_ERROR_INVALID_HANDLE 

Invalid handle or file. [EBADF].

BL_ERROR_INVALID_CONVERSION 

Invalid conversion.

BL_ERROR_OVERFLOW 

Overflow or value too large [EOVERFLOW].

BL_ERROR_NOT_INITIALIZED 

Object not initialized.

BL_ERROR_NOT_IMPLEMENTED 

Not implemented [ENOSYS].

BL_ERROR_NOT_PERMITTED 

Operation not permitted [EPERM].

BL_ERROR_IO 

IO error [EIO].

BL_ERROR_BUSY 

Device or resource busy [EBUSY].

BL_ERROR_INTERRUPTED 

Operation interrupted [EINTR].

BL_ERROR_TRY_AGAIN 

Try again [EAGAIN].

BL_ERROR_TIMED_OUT 

Timed out [ETIMEDOUT].

BL_ERROR_BROKEN_PIPE 

Broken pipe [EPIPE].

BL_ERROR_INVALID_SEEK 

File is not seekable [ESPIPE].

BL_ERROR_SYMLINK_LOOP 

Too many levels of symlinks [ELOOP].

BL_ERROR_FILE_TOO_LARGE 

File is too large [EFBIG].

BL_ERROR_ALREADY_EXISTS 

File/directory already exists [EEXIST].

BL_ERROR_ACCESS_DENIED 

Access denied [EACCES].

BL_ERROR_MEDIA_CHANGED 

Media changed [Windows::ERROR_MEDIA_CHANGED].

BL_ERROR_READ_ONLY_FS 

The file/FS is read-only [EROFS].

BL_ERROR_NO_DEVICE 

Device doesn't exist [ENXIO].

BL_ERROR_NO_ENTRY 

Not found, no entry (fs) [ENOENT].

BL_ERROR_NO_MEDIA 

No media in drive/device [ENOMEDIUM].

BL_ERROR_NO_MORE_DATA 

No more data / end of file [ENODATA].

BL_ERROR_NO_MORE_FILES 

No more files [ENMFILE].

BL_ERROR_NO_SPACE_LEFT 

No space left on device [ENOSPC].

BL_ERROR_NOT_EMPTY 

Directory is not empty [ENOTEMPTY].

BL_ERROR_NOT_FILE 

Not a file [EISDIR].

BL_ERROR_NOT_DIRECTORY 

Not a directory [ENOTDIR].

BL_ERROR_NOT_SAME_DEVICE 

Not same device [EXDEV].

BL_ERROR_NOT_BLOCK_DEVICE 

Not a block device [ENOTBLK].

BL_ERROR_INVALID_FILE_NAME 

File/path name is invalid [n/a].

BL_ERROR_FILE_NAME_TOO_LONG 

File/path name is too long [ENAMETOOLONG].

BL_ERROR_TOO_MANY_OPEN_FILES 

Too many open files [EMFILE].

BL_ERROR_TOO_MANY_OPEN_FILES_BY_OS 

Too many open files by OS [ENFILE].

BL_ERROR_TOO_MANY_LINKS 

Too many symbolic links on FS [EMLINK].

BL_ERROR_TOO_MANY_THREADS 

Too many threads [EAGAIN].

BL_ERROR_THREAD_POOL_EXHAUSTED 

Thread pool is exhausted and couldn't acquire the requested thread count.

BL_ERROR_FILE_EMPTY 

File is empty (not specific to any OS error).

BL_ERROR_OPEN_FAILED 

File open failed [Windows::ERROR_OPEN_FAILED].

BL_ERROR_NOT_ROOT_DEVICE 

Not a root device/directory [Windows::ERROR_DIR_NOT_ROOT].

BL_ERROR_UNKNOWN_SYSTEM_ERROR 

Unknown system error that failed to translate to Blend2D result code.

BL_ERROR_INVALID_ALIGNMENT 

Invalid data alignment.

BL_ERROR_INVALID_SIGNATURE 

Invalid data signature or header.

BL_ERROR_INVALID_DATA 

Invalid or corrupted data.

BL_ERROR_INVALID_STRING 

Invalid string (invalid data of either UTF8, UTF16, or UTF32).

BL_ERROR_INVALID_KEY 

Invalid key or property.

BL_ERROR_DATA_TRUNCATED 

Truncated data (more data required than memory/stream provides).

BL_ERROR_DATA_TOO_LARGE 

Input data too large to be processed.

BL_ERROR_DECOMPRESSION_FAILED 

Decompression failed due to invalid data (RLE, Huffman, etc).

BL_ERROR_INVALID_GEOMETRY 

Invalid geometry (invalid path data or shape).

BL_ERROR_NO_MATCHING_VERTEX 

Returned when there is no matching vertex in path data.

BL_ERROR_INVALID_CREATE_FLAGS 

Invalid create flags (BLContext).

BL_ERROR_NO_MATCHING_COOKIE 

No matching cookie (BLContext).

BL_ERROR_NO_STATES_TO_RESTORE 

No states to restore (BLContext).

BL_ERROR_TOO_MANY_SAVED_STATES 

Cannot save state as the number of saved states reached the limit (BLContext).

BL_ERROR_IMAGE_TOO_LARGE 

The size of the image is too large.

BL_ERROR_IMAGE_NO_MATCHING_CODEC 

Image codec for a required format doesn't exist.

BL_ERROR_IMAGE_UNKNOWN_FILE_FORMAT 

Unknown or invalid file format that cannot be read.

BL_ERROR_IMAGE_DECODER_NOT_PROVIDED 

Image codec doesn't support reading the file format.

BL_ERROR_IMAGE_ENCODER_NOT_PROVIDED 

Image codec doesn't support writing the file format.

BL_ERROR_PNG_MULTIPLE_IHDR 

Multiple IHDR chunks are not allowed (PNG).

BL_ERROR_PNG_INVALID_IDAT 

Invalid IDAT chunk (PNG).

BL_ERROR_PNG_INVALID_IEND 

Invalid IEND chunk (PNG).

BL_ERROR_PNG_INVALID_PLTE 

Invalid PLTE chunk (PNG).

BL_ERROR_PNG_INVALID_TRNS 

Invalid tRNS chunk (PNG).

BL_ERROR_PNG_INVALID_FILTER 

Invalid filter type (PNG).

BL_ERROR_JPEG_UNSUPPORTED_FEATURE 

Unsupported feature (JPEG).

BL_ERROR_JPEG_INVALID_SOS 

Invalid SOS marker or header (JPEG).

BL_ERROR_JPEG_INVALID_SOF 

Invalid SOF marker (JPEG).

BL_ERROR_JPEG_MULTIPLE_SOF 

Multiple SOF markers (JPEG).

BL_ERROR_JPEG_UNSUPPORTED_SOF 

Unsupported SOF marker (JPEG).

BL_ERROR_FONT_NOT_INITIALIZED 

Font doesn't have any data as it's not initialized.

BL_ERROR_FONT_NO_MATCH 

Font or font face was not matched (BLFontManager).

BL_ERROR_FONT_NO_CHARACTER_MAPPING 

Font has no character to glyph mapping data.

BL_ERROR_FONT_MISSING_IMPORTANT_TABLE 

Font has missing an important table.

BL_ERROR_FONT_FEATURE_NOT_AVAILABLE 

Font feature is not available.

BL_ERROR_FONT_CFF_INVALID_DATA 

Font has an invalid CFF data.

BL_ERROR_FONT_PROGRAM_TERMINATED 

Font program terminated because the execution reached the limit.

BL_ERROR_GLYPH_SUBSTITUTION_TOO_LARGE 

Glyph substitution requires too much space and was terminated.

BL_ERROR_INVALID_GLYPH 

Invalid glyph identifier.

BLByteOrder : uint32_tenum◆ 

Byte order.

ConstantDescription
BL_BYTE_ORDER_LE 

Little endian byte-order.

BL_BYTE_ORDER_BE 

Big endian byte-order.

BL_BYTE_ORDER_NATIVE 

Native (host) byte-order.

BL_BYTE_ORDER_SWAPPED 

Swapped byte-order (BE if host is LE and vice versa).

BLDataAccessFlags : uint32_tenum◆ 

Data access flags.

ConstantDescription
BL_DATA_ACCESS_NO_FLAGS 

No data access flags.

BL_DATA_ACCESS_READ 

Read access.

BL_DATA_ACCESS_WRITE 

Write access.

BL_DATA_ACCESS_RW 

Read and write access.

BLDataSourceType : uint32_tenum◆ 

Data source type.

ConstantDescription
BL_DATA_SOURCE_TYPE_NONE 

No data source.

BL_DATA_SOURCE_TYPE_MEMORY 

Memory data source.

BL_DATA_SOURCE_TYPE_FILE 

File data source.

BL_DATA_SOURCE_TYPE_CUSTOM 

Custom data source.

BL_DATA_SOURCE_TYPE_MAX_VALUE 

Maximum value BLDataSourceType.

BLModifyOp : uint32_tenum◆ 

Modification operation applied to Blend2D containers.

ConstantDescription
BL_MODIFY_OP_ASSIGN_FIT 

Assign operation, which reserves space only to fit the requested input.

BL_MODIFY_OP_ASSIGN_GROW 

Assign operation, which takes into consideration successive appends.

BL_MODIFY_OP_APPEND_FIT 

Append operation, which reserves space only to fit the current and appended content.

BL_MODIFY_OP_APPEND_GROW 

Append operation, which takes into consideration successive appends.

BL_MODIFY_OP_MAX_VALUE 

Maximum value of BLModifyOp.

BLBooleanOp : uint32_tenum◆ 

Boolean operator.

ConstantDescription
BL_BOOLEAN_OP_COPY 

Result = B.

BL_BOOLEAN_OP_AND 

Result = A & B.

BL_BOOLEAN_OP_OR 

Result = A | B.

BL_BOOLEAN_OP_XOR 

Result = A ^ B.

BL_BOOLEAN_OP_AND_NOT 

Result = A & ~B.

BL_BOOLEAN_OP_NOT_AND 

Result = ~A & B.

BL_BOOLEAN_OP_MAX_VALUE 

Maximum value of BLBooleanOp.

BLBitSetConstants : uint32_tenum◆ 

ConstantDescription
BL_BIT_SET_INVALID_INDEX 

Invalid bit-index.

This is the only index that cannot be stored in BLBitSet.

BL_BIT_SET_RANGE_MASK 

Range mask used by BLBitsetSegment::start value - if set the segment is a range of all ones.

BL_BIT_SET_SEGMENT_WORD_COUNT 

Number of words in a BLBitSetSegment.

Function Documentation

BLResult blTraceError(BLResult result)static◆ 

Returns the result passed.

Provided for debugging purposes. Putting a breakpoint inside blTraceError() can help with tracing an origin of errors reported / returned by Blend2D as each error goes through this function.

It's a zero-cost solution that doesn't affect release builds in any way.

template<typename T, typename... Args>
void blCallCtor(T& instance, Args&&... args)static◆ 

Constructs an instance in place (calls its constructor) with optional args.

template<typename T>
void blCallDtor(T& instance)static◆ 

Destroys an instance in place (calls its destructor).

template<typename Out, typename In>
Out blBitCast(const In& x)static◆ 

Bit-cast x of In type to the given Out type.

Useful to bit-cast between integers and floating points. The size of Out and In must be the same otherwise the compilation would fail. Bit casting is used by blEquals to implement bit equality for floating point types.

template<typename T>
T blAbs(const T& a)constexprconstexpr◆ 

Returns an absolute value of a.

template<typename T>
T blMin(const T& a, const T& b)constexprconstexpr[1/2]◆ 

Returns a minimum value of a and b.

template<typename T>
T blMax(const T& a, const T& b)constexprconstexpr[1/2]◆ 

Returns a maximum value of a and b.

template<typename T>
T blClamp(const T& a, const T& b, const T& c)constexprconstexpr◆ 

Clamps a to a range defined as [b, c].

template<typename T, typename... Args>
T blMin(const T& a, const T& b, Args&&... args)constexprconstexpr[2/2]◆ 

Returns a minimum value of all arguments passed.

template<typename T, typename... Args>
T blMax(const T& a, const T& b, Args&&... args)constexprconstexpr[2/2]◆ 

Returns a maximum value of all arguments passed.

template<typename T>
bool blEquals(const T& a, const T& b)◆ 

Returns true if a and b equals at binary level.

For example blEquals(NaN, NaN) == true.