Rendering API

2D rendering context, helper structures, and constants.

Classes

Enumerations

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_COUNT 

Count of rendering context types.

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_COUNT 

Count of rendering context hints.

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_COUNT 

Count of rendering operations.

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_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 generation 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.

BLContextProperty : uint32_tenum

Specifies a rendering context property that can be specific to the rendering context implementation and that doesn't have its own C and C++ API. Different rendering context implementations may expose various properties that users can query to get more details about the rendering context itself, rendering details (like optimizations or possibly limitations), memory details, and other information that was collected during the rendering.

Properties are never part of the rendering context state - they are stateless and are not subject to save() and restore(). Many properties are purely informative, but some not, e.g. BL_CONTEXT_PROPERTY_ACCUMULATED_ERROR_FLAGS.

ConstantDescription
BL_CONTEXT_PROPERTY_THREAD_COUNT 

Number of threads that the rendering context uses for rendering.

BL_CONTEXT_PROPERTY_ACCUMULATED_ERROR_FLAGS 

Accumulated errors collected during the lifetime of the rendering 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_FLAG_INVALID_VALUE 

The rendering context returned or encountered BL_ERROR_INVALID_VALUE, which is mostly related to 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_COUNT 

Count of composition & blending operators.

BLGradientQuality : uint32_tenum

Gradient rendering quality.

ConstantDescription
BL_GRADIENT_QUALITY_NEAREST 

Nearest neighbor.

BL_GRADIENT_QUALITY_COUNT 

Count of gradient quality options.

BLPatternQuality : uint32_tenum

Pattern quality.

ConstantDescription
BL_PATTERN_QUALITY_NEAREST 

Nearest neighbor.

BL_PATTERN_QUALITY_BILINEAR 

Bilinear.

BL_PATTERN_QUALITY_COUNT 

Count of pattern quality options.

BLRenderingQuality : uint32_tenum

Rendering quality.

ConstantDescription
BL_RENDERING_QUALITY_ANTIALIAS 

Render using anti-aliasing.

BL_RENDERING_QUALITY_COUNT 

Count of rendering quality options.