Canvas
A canvas is an immediate drawing surface. It has no meaningful children and no CSS-painted content of its own; the host gives your callback a GPU context or a recorder scoped to the element's box on every frame.
Why it is special
| Concern | How Donkeh handles it |
|---|---|
| Layout | Replaced content with a default 300 × 150 box, or the width/height attributes. CSS positions and sizes the box like any other element. |
| Clipping | The host clips drawing to the canvas border box and establishes a canvas-local coordinate system before invoking the callback. |
| Batching | OnDraw records rectangles, ellipses, paths, text and images into the same indirect GPU batch as the rest of the UI. |
| Raw access | OnContext hands you Silk.NET's GL after the batch is submitted, for effects the recorder does not model. |
| Browser | Not wired yet. The DOM host mirrors a native canvas element, but the OpenGL/WebGL interop needed to run these callbacks has not been built. |
Outside a browser, canvas drawing runs through Silk.NET against the same OpenGL 3.3 context as the window on desktop, and the matching GLES context on Android. That is why it is a real drawing primitive on those hosts rather than a styled rectangle.
Batched drawing
Prefer OnDraw. It records into the frame's indirect batch, so a
canvas does not force a viewport switch, a separate upload or one draw call
per shape.
using Donkeh.LayoutLab;
using Donkeh.UILab;
using Donkeh.Windowing;
using static Donkeh.UILab.HtmlHelper;
using static Donkeh.UILab._;
public sealed class Sparkline : Component
{
public override Node Render() =>
H("canvas", new CanvasProps
{
Attributes = new Dictionary<string, string>
{
["width"] = "320",
["height"] = "120"
},
OnDraw = context =>
{
context.Clear(0xFF111827);
var bar = new Rect(16, 48, 28, 56);
context.FillRoundedRect(bar, 0xFF5957D9, new CornerRadius(6, 6, 6, 6));
context.FillRect(bar.X + 44, 24, 28, 80, 0xFF43D3E8);
context.FillEllipse(new Rect(120, 20, 64, 64), 0xFF86EFAC);
context.StrokeRect(new Rect(200, 28, 96, 64), 0xFFE5E7EB, 2);
}
});
CanvasContext API
| Member | Purpose |
|---|---|
Clear(uint color) | Fill the whole canvas with a packed 0xAARRGGBB colour. |
FillRect, FillRoundedRect | Axis-aligned fills with optional per-corner radii. |
FillEllipse, StrokeRect | Ellipse fill and a rectangular outline. |
DrawText | Draw a text run with a resolved TextStyle. |
DrawImage | Draw a cached image with object-fit, tint and opacity. |
PushClip / PopClip | Rectangular canvas-local clipping. |
PushTransform / PopTransform | Nested Matrix3x2 transforms. |
PushOpacity / PopOpacity | Opacity multiplier for subsequent primitives. |
Coordinates are canvas-local CSS pixels with the origin at the top-left of the
element's border box. The same CanvasContext instance is reused
between frames and is only valid inside the callback; storing it and drawing
later throws.
Pop* calls keep sibling drawing deterministic.
Raw OpenGL
OnContext receives a Silk.NET GL instance bound to the
window context. The host has already set the viewport and scissor to the canvas
bounds, so draw inside the element's box. These commands are immediate-mode and
paint after batched OnDraw content.
using Silk.NET.OpenGL;
H("canvas", new CanvasProps
{
OnDraw = context => context.Clear(0xFF0B1018),
OnContext = gl =>
{
gl.Enable(EnableCap.ScissorTest);
gl.ClearColor(0.05f, 0.08f, 0.12f, 1f);
gl.Clear(ClearBufferMask.ColorBufferBit);
gl.Disable(EnableCap.ScissorTest);
}
});
Use this sparingly. State changes made here are yours to restore, and raw commands are not batched with the rest of the frame.
Browser limitation
OnDraw and OnContext are not invoked on
net10.0-browser. Wiring a GL context through browser WebGL is a
large, complex piece of interop work, so it is not enabled rather than
emulated badly. The element exists in the DOM, but drawing from C# is a
desktop and Android feature.
For browser-only graphics today, use ordinary HTML, CSS, images and DOM
effects. If a canvas is optional, gate the drawing callback on
OperatingSystem.IsBrowser() or provide a CSS/DOM fallback so the
page still communicates the same information.