Easy to Use API

Blend2D is written in C++ but it provides both C and C++ APIs. Public functionality is provided through C interface so that each feature of the library is accessible to both C and C++ users. The C API makes it possible to use Blend2D from many programming languages which are able to interface with C (either natively or through FFI). The primary goal of the C++ API is to make the library easy-to-use in C++ projects without the need of managing resources manually. It is built on top of the C API and turns all objects requiring initialization and finalization into smart objects that handle it in their constructors and destructors.

The snippets below provide an insight into the C and C++ APIs provided by Blend2D.

#include <blend2d.h>

// Each C API struct that requires a lifetime management
// ends with 'Core'. Such structs must be initialized by
// 'Init()' and finalized by 'Reset()' or by function
// that resets implicitly like 'blContextEnd()'.
void render(BLImageCore* img) {
  BLResult r;
  BLContextCore ctx;
  BLGradientCore gradient;

  r = blImageInitAs(img, 256, 256, BL_FORMAT_PRGB32);
  if (r != BL_SUCCESS) return;

  r = blContextInitAs(&ctx, img, NULL);
  if (r != BL_SUCCESS) return;

  BLLinearGradientValues values = { 0, 0, 256, 256 };
  blGradientInitAs(&gradient,
    BL_GRADIENT_TYPE_LINEAR, &values,
    BL_EXTEND_MODE_PAD, NULL, 0, NULL);

  blGradientAddStopRgba32(&gradient, 0.0, 0x00000000);
  blGradientAddStopRgba32(&gradient, 1.0, 0xFFFFFFFF);

  blContextSetCompOp(&ctx, BL_COMP_OP_SRC_COPY);
  blContextSetFillStyle(&ctx, &gradient);

  blContextFillAll(&ctx);
  blContextEnd(&ctx);

  // Manual cleanup is necessary in C.
  blGradientReset(&gradient);
}

#include <blend2d.h>

// C++ API is automatically provided in C++ mode. Each
// 'Core' struct has also its C++ counterpart that
// doesn't have the suffix (BLImageCore -> BLImage)
// and provides scope-bound resource management.
void render(BLImage& img) noexcept {
  BLResult r;
  BLContext ctx;
  BLGradient gradient;

  r = img.create(256, 256, BL_FORMAT_PRGB32);
  if (r != BL_SUCCESS) return;

  r = ctx.begin(img);
  if (r != BL_SUCCESS) return;

  // There are many overloads available in C++ API.
  gradient.create(
    BLLinearGradientValues(0, 0, 256, 256),
    BL_EXTEND_MODE_PAD);

  gradient.addStop(0.0, BLRgba32(0x00000000));
  gradient.addStop(1.0, BLRgba32(0xFFFFFFFF));

  ctx.setCompOp(BL_COMP_OP_SRC_COPY);
  ctx.setFillStyle(gradient);

  ctx.fillAll();
  ctx.end();

  // C++ smart objects take care of cleanup
  // automatically when they go out of scope.
}

Please note that both examples were written to be line-by-line comparable and to not use excessive error handling. More C++ examples and their corresponding outputs can be seen on Getting Started page.

Composition & Blending

Blend2D supports all Porter & Duff compositing operators and a wide range of blend modes defined by SVG, CSS, and PDF specifications. Composition and blending modes can be applied to any rendering operation including fills, strokes, and image blits.