Skip to content

Extending Bink

Six extension points cover what applications actually need to change, and none of them touches the engine. This page uses three of them live: a brush of its own, an element type of its own, and a render target of its own. Draw with the dashed pen, add sticky notes and vote on them, then save and reload - with the extensions, and as an application that has never heard of them.

Drawing with 2 elements on 1 layer. Sticky note: Drag me with Select, 2 votes. Stroke, 41 points, demo-dashed brush, color #7c3aed.

A brush of your own

Derive from BinkBrush, give it a unique Kind, and build the stroke's geometry from its points: a filled outline, or a centerline stroked at the brush's width as here. Colour, width, opacity, blend mode, smoothing, spacing, taper and pressure curve are the base record's and are saved for it; settings of its own are saved once it names them in GetParameters, and come back through WithParameters, which clamps them because a file or a collaborator can say anything. BinkCalligraphyBrush is built exactly this way.

public sealed record DashedBrush : BinkBrush
{
    public override string Kind => "demo-dashed";
    public float DashLength { get; init; } = 12f;

    public override BinkStrokeGeometry BuildGeometry(BinkStrokePointsView points, BinkPathBuilder builder)
    {
        // walk points.PositionAt(i), MoveTo at the start of each dash and LineTo along it
        return new BinkStrokeGeometry(builder.ToGeometry(), BinkStrokeGeometryMode.Centerline, Width,
            BinkLineCap.Round, BinkLineJoin.Round, points.Bounds.Inflate(Width));
    }

    public override IReadOnlyDictionary<string, float> GetParameters() => new Dictionary<string, float> { ["dashLength"] = DashLength };
    public override BinkBrush WithParameters(IReadOnlyDictionary<string, float> p)
        => this with { DashLength = p.TryGetValue("dashLength", out float d) ? Math.Clamp(d, 2f, 80f) : DashLength };
}

BinkBrushRegistry.Default.Register<DashedBrush>();   // so documents that use it load back as this brush

The points view gives positions, pressure and time; tilt and twist are on the stroke's Points, for a brush that follows the pen's angle. Geometry is built once per stroke and brush and cached, so it costs nothing on later frames.

An element type of your own

BinkElement is an abstract record. A sticky note supplies its bounds, how it draws and how it is hit, in its own coordinates, and from then on it moves, resizes, rotates, groups, locks, duplicates and undoes like any built-in element - try it with Select. To save it, paste it and send it to collaborators, register a converter: the serializer writes the type and every shared field (id, version, transform, description, metadata, lock, groups) and the bounds itself, and the converter only the note's own fields. Whatever it reads is untrusted, so it checks every value and throws FormatException, which is reported as a malformed document.

public sealed record StickyNote(BinkRect Rect, string Text) : BinkElement
{
    public override BinkRect LocalBounds => Rect;
    public override string TypeName => "Sticky note";
    protected override void DrawCore(IBinkRenderContext context) { /* FillPath, StrokePath, DrawText */ }
    protected override bool HitTestCore(Vector2 point, float tolerance) => Rect.Inflate(tolerance).Contains(point);
}

public sealed class StickyNoteConverter : BinkElementConverter<StickyNote>
{
    public override string TypeName => "demo-sticky-note";
    public override void Write(Utf8JsonWriter writer, StickyNote note, BinkSerializerOptions options) { /* rect, text, votes */ }
    public override StickyNote Read(JsonElement json, BinkDeserializerOptions options) { /* validate, bound, build */ }
}

BinkElementRegistry.Default.Register(new StickyNoteConverter());

Read by an application that does not know them

Reload without the extensions reads the drawing the way another application, or an older build, would: with registries that have never heard of the brush or the note. The dashed strokes draw as plain pens in their own colour and width, and keep their kind and their dashLength; each note becomes a BinkUnknownElement, not drawn and not selectable, but kept in its place and written back exactly as it was read. Save and reload then brings everything back unchanged, because nothing was lost on the way through.

var write = new BinkSerializerOptions { BrushRegistry = _brushes, ElementRegistry = _elements };
var read = new BinkDeserializerOptions { BrushRegistry = _brushes, ElementRegistry = _elements };
string json = BinkSerializer.Serialize(document, write);

BinkDocument elsewhere = BinkSerializer.Deserialize(json);   // the default registries: neither extension

Most applications register once, in BinkBrushRegistry.Default and BinkElementRegistry.Default, which the canvas's clipboard and collaboration use too. This page keeps its extensions in registries of its own and passes them through the options instead - the way an application that keeps several sets apart does - so the site's other pages, and the MCP server it hosts, never see them. A custom element with no converter at all cannot be saved, deliberately: nothing could read it back.

A render target of your own

IBinkRenderContext is the only surface the engine knows: fill a path, stroke a path, draw an image, draw text, transform, clip and isolate a group. The browser canvas, SVG export and the built-in rasterizer each implement it, which is why an export always matches the screen; a PDF writer or a printer would be a fourth. Count draw calls renders the drawing into the smallest one possible, which counts. Two rules matter for a real one: PushGroup must genuinely isolate, because content inside it may erase, and fills must honour BinkFillRule.NonZero, which keeps a self-overlapping stroke solid.

var counter = new DrawCallCounter();
BinkDocumentRenderer.Render(_document, counter);

// Server-side PNG export has no font engine of its own; give it one to draw text:
var png = BinkPngExporter.Export(document, new BinkPngExportOptions { TextRasterizer = new SkiaTextRasterizer() });

IBinkTextRasterizer is the related extension point: two methods, draw a string into a surface and measure one, which is all BinkPngExporter needs to render text on a server.

Tools, transports, and what stays closed

The other two extension points have pages of their own. A custom tool implements IBinkTool, or derives from BinkToolBase: the diagram surface builds its node and connector tools that way, with their own overlay previews and snapping. A collaboration transport implements IBinkCollaborationTransport over SignalR, WebSockets or anything else; the collaboration page runs on an in-memory one.

What stays closed is the operation set. BinkDrawingOperation cannot be subclassed from outside the library, because undo, saving and synchronization all depend on knowing every operation's inverse and wire format. Everything above composes the existing operations - adding, replacing, removing - so it is undoable and synchronizable with no extra work.

An unhandled error has occurred. Reload 🗙