The context¶
RenderContext, in pollock/context, is the contract between pollock and its backends. It is a Nim concept: a backend is any type with these procs. Application code rarely calls them directly, since Drawing wraps them, but their semantics are what every backend has to match.
type RenderContext* = concept
proc clear(ctx: var Self, color: Color)
proc fillPath(ctx: var Self, path: BezPath, paint: Paint, rule: FillRule)
proc strokePath(ctx: var Self, path: BezPath, paint: Paint, style: StrokeStyle)
proc clipPath(ctx: var Self, path: BezPath, rule: FillRule)
proc save(ctx: var Self)
proc restore(ctx: var Self)
proc transform(ctx: var Self, affine: Affine)
proc currentTransform(ctx: Self): Affine
proc drawImage(ctx: var Self, image: ImageData, dst: Rect, interp: Interpolation)
proc drawGlyphs(ctx: var Self, run: GlyphRun, paint: Paint)
proc finish(ctx: var Self): RenderResult
The primitive names end in Path so they never collide with the shape-taking helpers in pollock/draw: fill(ctx, circle(...)) is the helper, fillPath(ctx, path, ...) the primitive it calls.
The primitives¶
clear(color)- Paints the whole target with
color, replacing what was there. Ignores the transform and the clip. fillPath(path, paint, rule)- Fills
pathunder the current transform and clip.frNonZerofills where the winding number is not zero,frEvenOddwhere it is odd. strokePath(path, paint, style)- Strokes
path. The width, dashes and caps are in user space, so they scale with the transform. clipPath(path, rule)- Intersects the clip with the inside of
path, under the current transform. Onlyrestorecan widen the clip again. saveandrestore- Push and pop the transform and the clip. Nothing else is saved; paints are passed per call. A
restorewith nothing saved does nothing. transform(affine)- Multiplies the current transform by
affine, so later coordinates are mapped byaffinefirst. currentTransform- The transform in effect.
drawImage(image, dst, interp)- Draws
imagestretched intodst, under the transform and clip, with nearest or bilinear sampling. drawGlyphs(run, paint)- Draws a glyph run (one font at one size, glyph ids with positions in user space) in
paint, under the transform and clip. The paint is passed explicitly, like every other paint, so a run can be drawn in a paint other than its own (a shadow, a highlight);drawTextinpollock/drawpasses each run's own. A backend that can make a native font from the run's bytes draws natively; otherwise it callsdrawGlyphsAsPaths(ctx, engine, run, paint), which fills the engine's outlines and color layers withfillPathand its bitmaps withdrawImage. finish- Ends a frame. Returns a
RenderResultwithokfalse and amessageif any call failed since the lastfinish, and clears that state. Backends that draw to a window present the frame here.
The rules¶
These are the agreements every backend keeps, so that one drawing looks the same everywhere.
- Coordinates have their origin at the top left with y pointing down, in logical units. A positive rotation is clockwise on the screen. Backends whose native API disagrees (Core Graphics puts the origin at the bottom left) apply the correction once, when the context is made.
- Colors are sRGB.
Colorhas straight alpha; images declare their format and backends convert. Gradients interpolate in sRGB with straight alpha, as the native renderers do. - Paints are values.
Paintcarries no backend state. A backend may build a device resource (a Direct2D brush, a WebGL texture) from one and cache it. - Drawing calls never raise. A backend records the first failure and reports it from
finish. Losing the device is one of those failures; the caller makes a new context. - State is small.
saveandrestorecover the transform and the clip, nothing else. clearis absolute. It ignores the transform and the clip, so it is safe to call at the top of every frame.- Text is glyph runs. Glyph positions are in user space, so the transform applies to them like to a path. A font is its bytes, face index and variation coordinates, never a platform handle, so any backend can build its own native font from it. Font lookup and fallback belong to the engine, not the backend. Glyphs are drawn unhinted with grayscale antialiasing, so every engine and backend pairing can be compared with the reference, the CPU backend with the pure Nim engine.
Types¶
FillRule:frNonZero,frEvenOdd.Interpolation:ipNearest,ipBilinear.RenderResult:ok: bool,message: string.success()andfailure(message)make them.GlyphRun,Glyph,GlyphId,Font,GlyphDrawingand theTextEngineconcept come frompollock/text, which the context re-exports; see Text.