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.

BLContextOpType : uint32_tenum

Describes a rendering operation type - fill or stroke.

The rendering context allows to get and set fill & stroke options directly or via "style" functions that take the rendering operation type (opType) and dispatch the call to the right function.

ConstantDescription
BL_CONTEXT_OP_TYPE_FILL 

Fill operation type.

BL_CONTEXT_OP_TYPE_STROKE 

Stroke operation type.

BL_CONTEXT_OP_TYPE_MAX_VALUE 

Maximum value of BLContextOpType

BLContextFlushFlags : uint32_tenum

Rendering context flush-flags, use with BLContext::flush().

ConstantDescription
BL_CONTEXT_FLUSH_SYNC 

Flush the command queue and wait for its completion (will block).

BLContextCreateFlags : uint32_tenum

Rendering context create-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.

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.

BLGradientQuality : uint32_tenum

Gradient rendering quality.

ConstantDescription
BL_GRADIENT_QUALITY_NEAREST 

Nearest neighbor.

BL_GRADIENT_QUALITY_MAX_VALUE 

Maximum value of BLGradientQuality.

BLPatternQuality : uint32_tenum

Pattern quality.

ConstantDescription
BL_PATTERN_QUALITY_NEAREST 

Nearest neighbor.

BL_PATTERN_QUALITY_BILINEAR 

Bilinear.

BL_PATTERN_QUALITY_MAX_VALUE 

Maximum value of BLPatternQuality.

BLRenderingQuality : uint32_tenum

Rendering quality.

ConstantDescription
BL_RENDERING_QUALITY_ANTIALIAS 

Render using anti-aliasing.

BL_RENDERING_QUALITY_MAX_VALUE 

Maximum value of BLRenderingQuality.