Rendering Context

2D rendering context API, structures, and constants.

Classes

BLContext - Constants

BLContext - C API

Enumeration Type Documentation

BLContextType : uint32_tenum◆ 

Rendering context type.

ConstantDescription
BL_CONTEXT_TYPE_NONE 

No rendering context.

BL_CONTEXT_TYPE_DUMMY 

Dummy rendering context.

BL_CONTEXT_TYPE_RASTER 

Software-accelerated rendering context.

BL_CONTEXT_TYPE_MAX_VALUE 

Maximum value of BLContextType.

BLContextHint : uint32_tenum◆ 

Rendering context hint.

ConstantDescription
BL_CONTEXT_HINT_RENDERING_QUALITY 

Rendering quality.

BL_CONTEXT_HINT_GRADIENT_QUALITY 

Gradient quality.

BL_CONTEXT_HINT_PATTERN_QUALITY 

Pattern quality.

BL_CONTEXT_HINT_MAX_VALUE 

Maximum value of BLContextHint.

BLContextStyleSlot : uint32_tenum◆ 

Describes a rendering context style slot - fill or stroke.

ConstantDescription
BL_CONTEXT_STYLE_SLOT_FILL 

Fill operation style slot.

BL_CONTEXT_STYLE_SLOT_STROKE 

Stroke operation style slot.

BL_CONTEXT_STYLE_SLOT_MAX_VALUE 

Maximum value of BLContextStyleSlot

BLContextRenderTextOp : uint32_tenum◆ 

The type of a text rendering operation.

This value specifies the type of the parameter passed to the text rendering API.

Note
In most cases this should not be required to use by Blend2D users. The C API provides functions that wrap all of the text operations and C++ API provides functions that use BLContextRenderTextOp internally.
ConstantDescription
BL_CONTEXT_RENDER_TEXT_OP_UTF8 

UTF-8 text rendering operation - UTF-8 string passed as BLStringView or BLArrayView<uint8_t>.

BL_CONTEXT_RENDER_TEXT_OP_UTF16 

UTF-16 text rendering operation - UTF-16 string passed as BLArrayView<uint16_t>.

BL_CONTEXT_RENDER_TEXT_OP_UTF32 

UTF-32 text rendering operation - UTF-32 string passed as BLArrayView<uint32_t>.

BL_CONTEXT_RENDER_TEXT_OP_LATIN1 

LATIN1 text rendering operation - LATIN1 string is passed as BLStringView or BLArrayView<uint8_t>.

BL_CONTEXT_RENDER_TEXT_OP_WCHAR 

wchar_t text rendering operation - wchar_t string is passed as BLArrayView<wchar_t>.

BL_CONTEXT_RENDER_TEXT_OP_GLYPH_RUN 

Glyph run text rendering operation - the BLGlyphRun parameter is passed.

BL_CONTEXT_RENDER_TEXT_OP_MAX_VALUE 

Maximum value of BLContextRenderTextInputType

BLContextFlushFlags : uint32_tenum◆ 

Rendering context flush flags, used by BLContext::flush().

ConstantDescription
BL_CONTEXT_FLUSH_SYNC 

Flushes the command queue and waits for its completion (will block until done).

BLContextCreateFlags : uint32_tenum◆ 

Rendering context creation flags.

ConstantDescription
BL_CONTEXT_CREATE_NO_FLAGS 

No flags.

BL_CONTEXT_CREATE_FLAG_DISABLE_JIT 

Disables JIT pipeline generator.

BL_CONTEXT_CREATE_FLAG_FALLBACK_TO_SYNC 

Fallbacks to a synchronous rendering in case that the rendering engine wasn't able to acquire threads. This flag only makes sense when the asynchronous mode was specified by having threadCount greater than 0. If the rendering context fails to acquire at least one thread it would fallback to synchronous mode with no worker threads.

Note
If this flag is specified with threadCount == 1 it means to immediately fallback to synchronous rendering. It's only practical to use this flag with 2 or more requested threads.
BL_CONTEXT_CREATE_FLAG_ISOLATED_THREAD_POOL 

If this flag is specified and asynchronous rendering is enabled then the context would create its own isolated thread-pool, which is useful for debugging purposes.

Do not use this flag in production as rendering contexts with isolated thread-pool have to create and destroy all threads they use. This flag is only useful for testing, debugging, and isolated benchmarking.

BL_CONTEXT_CREATE_FLAG_ISOLATED_JIT_RUNTIME 

If this flag is specified and JIT pipeline generation enabled then the rendering context would create its own isolated JIT runtime. which is useful for debugging purposes. This flag will be ignored if JIT pipeline compilation is either not supported or was disabled by other flags.

Do not use this flag in production as rendering contexts with isolated JIT runtime do not use global pipeline cache, that's it, after the rendering context is destroyed the JIT runtime is destroyed with it with all compiled pipelines. This flag is only useful for testing, debugging, and isolated benchmarking.

BL_CONTEXT_CREATE_FLAG_ISOLATED_JIT_LOGGING 

Enables logging to stderr of isolated runtime.

Note
Must be used with BL_CONTEXT_CREATE_FLAG_ISOLATED_JIT_RUNTIME otherwise it would have no effect.
BL_CONTEXT_CREATE_FLAG_OVERRIDE_CPU_FEATURES 

Override CPU features when creating isolated context.

BLContextErrorFlags : uint32_tenum◆ 

Error flags that are accumulated during the rendering context lifetime and that can be queried through BLContext::queryAccumulatedErrorFlags(). The reason why these flags exist is that errors can happen during asynchronous rendering, and there is no way the user can catch these errors.

ConstantDescription
BL_CONTEXT_ERROR_NO_FLAGS 

No flags.

BL_CONTEXT_ERROR_FLAG_INVALID_VALUE 

The rendering context returned or encountered BL_ERROR_INVALID_VALUE, which is mostly related to the function argument handling. It's very likely some argument was wrong when calling BLContext API.

BL_CONTEXT_ERROR_FLAG_INVALID_STATE 

Invalid state describes something wrong, for example a pipeline compilation error.

BL_CONTEXT_ERROR_FLAG_INVALID_GEOMETRY 

The rendering context has encountered invalid geometry.

BL_CONTEXT_ERROR_FLAG_INVALID_GLYPH 

The rendering context has encountered invalid glyph.

BL_CONTEXT_ERROR_FLAG_INVALID_FONT 

The rendering context has encountered invalid or uninitialized font.

BL_CONTEXT_ERROR_FLAG_THREAD_POOL_EXHAUSTED 

Thread pool was exhausted and couldn't acquire the requested number of threads.

BL_CONTEXT_ERROR_FLAG_OUT_OF_MEMORY 

Out of memory condition.

BL_CONTEXT_ERROR_FLAG_UNKNOWN_ERROR 

Unknown error, which we don't have flag for.

BLContextStyleSwapMode : uint32_tenum◆ 

Specifies the behavior of BLContext::swapStyles() operation.

ConstantDescription
BL_CONTEXT_STYLE_SWAP_MODE_STYLES 

Swap only fill and stroke styles without affecting fill and stroke alpha.

BL_CONTEXT_STYLE_SWAP_MODE_STYLES_WITH_ALPHA 

Swap both fill and stroke styles and their alpha values.

BL_CONTEXT_STYLE_SWAP_MODE_MAX_VALUE 

Maximum value of BLContextStyleSwapMode.

BLContextStyleTransformMode : uint32_tenum◆ 

Specifies how style transformation matrix is combined with the rendering context transformation matrix, used by BLContext::setStyle() function.

ConstantDescription
BL_CONTEXT_STYLE_TRANSFORM_MODE_USER 

Style transformation matrix should be transformed with the rendering context user and meta matrix (default).

Note
This transformation mode is identical to how user geometry is transformed and it's the default transformation and most likely the behavior expected in most cases.
BL_CONTEXT_STYLE_TRANSFORM_MODE_META 

Style transformation matrix should be transformed with the rendering context meta matrix.

BL_CONTEXT_STYLE_TRANSFORM_MODE_NONE 

Style transformation matrix is considered absolute, and is not combined with a rendering context transform.

BL_CONTEXT_STYLE_TRANSFORM_MODE_MAX_VALUE 

Maximum value of BLContextStyleTransformMode.

BLClipMode : uint32_tenum◆ 

Clip mode.

ConstantDescription
BL_CLIP_MODE_ALIGNED_RECT 

Clipping to a rectangle that is aligned to the pixel grid.

BL_CLIP_MODE_UNALIGNED_RECT 

Clipping to a rectangle that is not aligned to pixel grid.

BL_CLIP_MODE_MASK 

Clipping to a non-rectangular area that is defined by using mask.

BL_CLIP_MODE_COUNT 

Count of clip modes.

BLCompOp : uint32_tenum◆ 

Composition & blending operator.

ConstantDescription
BL_COMP_OP_SRC_OVER 

Source-over [default].

BL_COMP_OP_SRC_COPY 

Source-copy.

BL_COMP_OP_SRC_IN 

Source-in.

BL_COMP_OP_SRC_OUT 

Source-out.

BL_COMP_OP_SRC_ATOP 

Source-atop.

BL_COMP_OP_DST_OVER 

Destination-over.

BL_COMP_OP_DST_COPY 

Destination-copy [nop].

BL_COMP_OP_DST_IN 

Destination-in.

BL_COMP_OP_DST_OUT 

Destination-out.

BL_COMP_OP_DST_ATOP 

Destination-atop.

BL_COMP_OP_XOR 

Xor.

BL_COMP_OP_CLEAR 

Clear.

BL_COMP_OP_PLUS 

Plus.

BL_COMP_OP_MINUS 

Minus.

BL_COMP_OP_MODULATE 

Modulate.

BL_COMP_OP_MULTIPLY 

Multiply.

BL_COMP_OP_SCREEN 

Screen.

BL_COMP_OP_OVERLAY 

Overlay.

BL_COMP_OP_DARKEN 

Darken.

BL_COMP_OP_LIGHTEN 

Lighten.

BL_COMP_OP_COLOR_DODGE 

Color dodge.

BL_COMP_OP_COLOR_BURN 

Color burn.

BL_COMP_OP_LINEAR_BURN 

Linear burn.

BL_COMP_OP_LINEAR_LIGHT 

Linear light.

BL_COMP_OP_PIN_LIGHT 

Pin light.

BL_COMP_OP_HARD_LIGHT 

Hard-light.

BL_COMP_OP_SOFT_LIGHT 

Soft-light.

BL_COMP_OP_DIFFERENCE 

Difference.

BL_COMP_OP_EXCLUSION 

Exclusion.

BL_COMP_OP_MAX_VALUE 

Count of composition & blending operators.

BLRenderingQuality : uint32_tenum◆ 

Rendering quality.

ConstantDescription
BL_RENDERING_QUALITY_ANTIALIAS 

Render using anti-aliasing.

BL_RENDERING_QUALITY_MAX_VALUE 

Maximum value of BLRenderingQuality.