Package limn.graphics

Interface Canvas

All Known Implementing Classes:
NoopCanvas
public interface Canvas
Immediate-mode 2D drawing API: what every widget paints through. All coordinates are logical points; the backend multiplies by the monitor content scale (a float: 1.0, 1.25, 1.5, 2.0…) into physical pixels, applies analytic antialiasing, and batches geometry into as few GPU draw calls as possible.

Pixel snapping: 1-logical-pixel strokes and axis-aligned lines are automatically aligned to the physical pixel grid (odd device widths center on half-pixels, even on integers) so hairlines stay crisp at fractional scales like 125%/150%. Snapping is skipped under rotation.

State (save()/restore()) covers the transform, the opacity and the clip. Clips only intersect (never expand) and are restored by restore(); an opacity multiplies the one in force. A layer is a save whose drawing is composited as one picture by its restore().

A Canvas is only valid during a frame callback and is single-threaded (UI thread).

  • Method Summary

    Modifier and Type
    Method
    Description
    default BlendMode
    blendMode()
     
    void
    clear(Color color)
    Clears the whole framebuffer (ignores transform/clip/opacity).
    default void
    clearRect(float x, float y, float width, float height, Color color)
    Replaces one rectangle with color: clear(limn.graphics.Color) semantics confined to a rect, in untransformed logical frame coordinates, ignoring transform/clip/opacity.
    default @Nullable Rect
    clipBounds()
    The current clip as a rectangle in current coordinates, or null when this canvas cannot say: it does not track clips, or the transform is rotated and the clip's device-space box has no rectangular pre-image.
    void
    clipRect(float x, float y, float width, float height)
    Intersects the clip with an axis-aligned rectangle (in current coordinates).
    default void
    clipRect(Rect rect)
    Intersects the clip with an axis-aligned rectangle (see clipRect(float, float, float, float)).
    void
    clipRoundRect(RoundRect roundRect)
    Intersects the clip with a rounded rectangle.
    default void
    clipRoundRectInsideBorder(float x, float y, float width, float height, float radius, float borderWidth)
    Intersects the clip with the shape fillRoundRectInsideBorder(float, float, float, float, float, float, limn.graphics.Paint) fills, for a surface whose fill is a gradient, an image or several shapes: clip, paint them over the whole box, restore, then draw the border.
    float
    contentScale()
     
    default void
    damageScissorHint(float x, float y, float width, float height)
    Backend hint from partial rendering: every draw for the rest of this frame lies inside this rect, in untransformed logical frame coordinates.
    void
    drawCircle(float cx, float cy, float radius, float strokeWidth, Paint paint)
     
    void
    drawEllipse(float cx, float cy, float radiusX, float radiusY, float strokeWidth, Paint paint)
     
    default void
    drawImage(Image image, float x, float y)
    Draws image at its natural pixel size (1 pixel = 1 logical point).
    void
    drawImage(Image image, float x, float y, float w, float h)
    Draws image into the rectangle (x, y, w, h) in logical points, scaled with linear filtering, modulated by the current opacity().
    void
    drawImage(Image image, float srcX, float srcY, float srcW, float srcH, float dstX, float dstY, float dstW, float dstH)
    Draws the source rectangle (srcX, srcY, srcW, srcH), in image pixels, into the destination rectangle (dstX, dstY, dstW, dstH) in logical points.
    void
    drawImage(Image image, float srcX, float srcY, float srcW, float srcH, float dstX, float dstY, float dstW, float dstH, Color tint)
    The sprite primitive and the tint, together: one cell of a sheet, modulated by tint exactly as drawImage(Image, float, float, float, float, Color) modulates a whole image.
    void
    drawImage(Image image, float x, float y, float w, float h, Color tint)
    Draws image tinted by tint (its RGB and alpha are multiplied by the tint's), the path for modulating a picture (e.g.
    default void
    drawImageMask(Image image, float x, float y, float w, float h, Color tint)
    Draws image as a single-color mask: the image's alpha is used as coverage and painted in tint's color; the image's own RGB is ignored.
    void
    drawLine(float x1, float y1, float x2, float y2, float strokeWidth, Paint paint)
    Line segment with round caps.
    void
    drawPath(Path2D path, float strokeWidth, Paint paint)
    Strokes a path with round caps and joins.
    void
    drawRect(float x, float y, float width, float height, float strokeWidth, Paint paint)
    Strokes the rectangle outline, centered on its boundary.
    default void
    drawRoundRect(float x, float y, float width, float height, float radius, float strokeWidth, Paint paint)
    Strokes the rounded-rect outline, centered on its boundary.
    void
    drawRoundRect(RoundRect roundRect, float strokeWidth, Paint paint)
    Strokes the rounded-rect outline, centered on its boundary.
    default void
    drawRoundRectBorder(float x, float y, float width, float height, float radius, float borderWidth, Paint paint)
    Strokes a border borderWidth wide lying wholly inside the rounded box, its outer edge exactly the box's outline.
    default void
    drawShadow(RoundRect shape, Shadow shadow)
    Draws one layer of the shadow a rounded rectangle casts: the shape moved by the layer's offset, its edge softened over the layer's blur, in the layer's colour.
    void
    drawSurface(GpuSurface surface, float x, float y, float w, float h)
    Composites a GpuSurface (e.g.
    void
    drawText(String text, float x, float y, Font font, Paint paint)
    Draws a single line of text with (x, y) at the baseline origin.
    default void
    drawText(ShapedText text, float x, float y, Paint paint)
    Draws an already-shaped line with (x, y) at the baseline origin of its left edge — for either base direction: right-to-left text fills the same box from the other end rather than growing leftwards from x, so the run covers [x, x + text.metrics().width()] and right-aligning a right-to-left paragraph is a matter of choosing x.
    default void
    fillBackdropRoundRect(float x, float y, float width, float height, float radius, BackdropEffect effect)
    fillBackdropRoundRect(RoundRect, BackdropEffect) with one radius on every corner.
    default void
    fillBackdropRoundRect(RoundRect roundRect, BackdropEffect effect)
    Fills roundRect with what this frame has already drawn underneath it, put through effect: a glass panel, a wash over video, a redacted field.
    void
    fillCircle(float cx, float cy, float radius, Paint paint)
     
    void
    fillEllipse(float cx, float cy, float radiusX, float radiusY, Paint paint)
     
    void
    fillPath(Path2D path, Paint paint)
    Fills a path.
    void
    fillRect(float x, float y, float width, float height, Paint paint)
     
    default void
    fillRect(Rect rect, Paint paint)
     
    default void
    fillRoundRect(float x, float y, float width, float height, float radius, Paint paint)
     
    void
    fillRoundRect(RoundRect roundRect, Paint paint)
     
    default void
    fillRoundRectInsideBorder(float x, float y, float width, float height, float radius, float borderWidth, Paint paint)
    Fills the box inside the border drawRoundRectBorder(float, float, float, float, float, float, limn.graphics.Paint) draws with the same arguments, as far as the border's centre line: the box inset by half the border, with the radius reduced by as much.
    default void
    fillRoundRectWithBorder(float x, float y, float width, float height, float radius, Paint fill, float borderWidth, Paint border)
    Paints a bordered surface: fill over the rounded box, and a border borderWidth wide in border lying wholly inside the box, its outer edge exactly the box's outline.
    float
    height()
     
    TextMetrics
    measureText(String text, Font font)
    Measures a single line of text in logical points (baseline-relative, unquantized and therefore independent of the monitor scale).
    float
    opacity()
     
    default boolean
    pixelSnap()
     
    default @Nullable Image
    readBack(float x, float y, float width, float height)
    Reads back, now, a part of what has been drawn on this canvas in this frame, with its transparency: what was cleared to nothing and not painted over is transparent in the image.
    void
    restore()
    Pops back to the previously saved state.
    void
    restoreToCount(int count)
    Pops saves until saveCount() equals count.
    void
    rotate(float angleRadians)
    Rotates by angleRadians (positive = clockwise, y grows down).
    default Sampling
    sampling()
     
    void
    save()
    Pushes a copy of the current state (transform, opacity, clip, blend mode, sampling, pixel snap).
    int
    saveCount()
    How many save()s are outstanding, the depth of the state stack.
    default void
    saveLayer(float x, float y, float width, float height, float opacity)
    Opens a layer: until the matching restore(), everything drawn goes into an offscreen picture, and the restore composites that picture over what is beneath it with opacity, once.
    default void
    saveLayer(float x, float y, float width, float height, float opacity, Mat4 transform)
    Opens a layer drawn in a space of its own and composited through transform: until the matching restore(), current coordinates are the layer's, upright, and its picture is laid where the canvas as it stood draws transform times each of its points.
    void
    scale(float sx, float sy)
     
    default void
    setBlendMode(BlendMode mode)
    Sets the current state's BlendMode: how every subsequent primitive (shape, text, image) combines with the destination.
    void
    setOpacity(float opacity)
    Multiplies the current state's opacity by opacity, clamped to [0..1]; every subsequent paint's alpha is multiplied by the result.
    default void
    setPixelSnap(boolean snap)
    Enables/disables the automatic pixel-grid snapping of image quads under axis-aligned transforms.
    default void
    setSampling(Sampling sampling)
    Sets the current state's image Sampling: how subsequent drawImage calls filter texels (Sampling.PIXELATED keeps pixel art crisp when scaled).
    void
    translate(float dx, float dy)
     
    float
    width()
     

  • Method Details

    • width

      float width()
      Returns:
      frame width in logical points

    • height

      float height()
      Returns:
      frame height in logical points

    • contentScale

      float contentScale()
      Returns:
      physical pixels per logical point for this frame

    • clear

      void clear(Color color)
      Clears the whole framebuffer (ignores transform/clip/opacity).

    • readBack

      default @Nullable Image readBack(float x, float y, float width, float height)
      Reads back, now, a part of what has been drawn on this canvas in this frame, with its transparency: what was cleared to nothing and not painted over is transparent in the image. It is how a picture of one thing is made, painted alone on a cleared corner of a frame before the frame itself is painted over it; a drag's picture is.

      On the canvas, and not on the renderer behind it, because whoever paints a scene has the canvas and may have nothing else: an application that renders its scene from a frame callback of its own hands the scene a canvas and no renderer.

      Parameters:
      x - the part's left edge, in logical points
      y - the part's top edge, in logical points
      width - its width, in logical points
      height - its height, in logical points
      Returns:
      the pixels, straight alpha, rows top-down, at the canvas's own resolution; null where the canvas keeps no transparency or cannot be read

    • clearRect

      default void clearRect(float x, float y, float width, float height, Color color)
      Replaces one rectangle with color: clear(limn.graphics.Color) semantics confined to a rect, in untransformed logical frame coordinates, ignoring transform/clip/opacity. Partial rendering resets each repaint pass with this. The default falls back to fillRect(float, float, float, float, limn.graphics.Paint), which is equivalent only for opaque colors: backends that support translucent framebuffers (popup windows) must override it with a true replace (a blend cannot write alpha back to 0).

    • damageScissorHint

      default void damageScissorHint(float x, float y, float width, float height)
      Backend hint from partial rendering: every draw for the rest of this frame lies inside this rect, in untransformed logical frame coordinates. Backends may confine rasterization to it (e.g. glScissor) so fragments outside are never shaded. Purely an optimization: pixels outside simply keep their previous content, so honoring it must not change what a correct frame produces. Reset at the start of each frame; a non-positive width or height disables it. Default: ignored.

    • save

      void save()
      Pushes a copy of the current state (transform, opacity, clip, blend mode, sampling, pixel snap).

    • restore

      void restore()
      Pops back to the previously saved state.

    • saveCount

      int saveCount()
      How many save()s are outstanding, the depth of the state stack.

      It exists so that a caller can put the canvas back where it found it without knowing how many saves happened in between, which is the only way to be safe against code it does not control: a widget's paint may push clips, may push more of them down a branch, and may stop halfway by throwing. Widget.paintWidget reads this before painting a widget and trims back to it afterwards, so one widget's leak cannot become every ancestor's.

      Returns:
      the number of outstanding saves; 0 on a canvas nobody has saved on

    • restoreToCount

      void restoreToCount(int count)
      Pops saves until saveCount() equals count.

      Does nothing when the depth is already at or below count: it is a trim, not an assertion, and a caller using it to recover from someone else's mistake must not be given a second mistake to handle. Never pops past zero.

      Parameters:
      count - the depth to return to, normally one taken from saveCount() earlier

    • translate

      void translate(float dx, float dy)

    • scale

      void scale(float sx, float sy)

    • rotate

      void rotate(float angleRadians)
      Rotates by angleRadians (positive = clockwise, y grows down).

    • setOpacity

      void setOpacity(float opacity)
      Multiplies the current state's opacity by opacity, clamped to [0..1]; every subsequent paint's alpha is multiplied by the result. Restored by restore().

      It multiplies rather than replaces so that an opacity set inside a fading surface, or inside a layer, combines with the one around it instead of undoing it: a widget at one half inside a panel fading at one half draws at a quarter. On a fresh save() the current opacity is whatever the enclosing state carries, which is 1 at the top of a frame and inside a layer, so a caller that saves and sets once gets the number it asked for. A caller that wants an absolute value has to know what it is multiplying.

      This is a per-draw alpha: each draw is translucent on its own, so where one draw covers another the one beneath shows through it. To fade overlapping draws as one picture, open a layer instead.

      Parameters:
      opacity - the factor, clamped to [0..1]

    • opacity

      float opacity()
      Returns:
      the current state's opacity, the product of every setOpacity(float) still in force

    • saveLayer

      default void saveLayer(float x, float y, float width, float height, float opacity)
      Opens a layer: until the matching restore(), everything drawn goes into an offscreen picture, and the restore composites that picture over what is beneath it with opacity, once. Overlapping draws inside it therefore fade as one picture: a row's highlight does not show through the row's icon, and a panel's shadow does not darken the panel. This is what an Opacity container draws through, and what a widget that paints overlapping parts of its own uses to fade them together.

      The rectangle, in current coordinates, is what the picture keeps: whatever is drawn outside it is lost. A canvas sizes the picture to the rectangle as far as its current clip lets it be seen, on whole device pixels, so a layer is never larger than what can show. Like save() it pushes the state (transform, clip, blend mode, sampling, pixel snap), and inside it the opacity starts again from 1, since the composite carries it; the blend mode in force when it is opened is the one the composite uses, and drawing inside starts from BlendMode.NORMAL.

      A blend mode inside a layer blends with the layer, which starts transparent, and not with what is beneath it, as an isolated group of a web page does: a draw in BlendMode.MULTIPLY or BlendMode.ADDITIVE combines with what was drawn before it inside the layer, and where nothing was, it is drawn as itself, as a draw in BlendMode.NORMAL would be. An opacity of 1 under BlendMode.NORMAL opens no layer, so there the same draw combines with what is beneath: a tint that multiplies inside a group fading in shows over the page as itself during the fade and multiplies it once the fade arrives at 1, which a page's own fade does too. Draw what should blend with what is beneath outside the group, or keep the group below 1. Inside a layer BlendMode.MULTIPLY is drawn in two passes: draws in it that cannot cover a pixel in common share them, shapes a pixel or more apart included, and each that can, shapes that touch included, costs two draw calls of its own, a line of text about one pair for every eight to ten glyphs (BlendMode has the measured numbers).

      What it costs, measured on the renderer this toolkit ships: two batch breaks and one composited quad per layer, about 0.03 to 0.1 ms of GPU for a popup-sized layer on a GPU and a percent or two of the frame on a software renderer; a window-sized one costs 0.1 to 0.15 ms of GPU, and about 10% of a frame on a software renderer. A canvas keeps the layer's memory, four bytes a device pixel, only while consecutive frames open layers. An opacity of 1 under BlendMode.NORMAL needs none, and a canvas opens none for it; under another mode it does, since the rule above holds at every opacity: drawing at 1 blend by blend would not be the picture blended once, and a fade arriving at 1 would jump.

      A canvas that cannot make layers (a recording or measuring one) falls back to what the default does: a save() and a per-draw setOpacity(float), which draws the same things in the same places and lets overlapping draws show through each other, each in the blend mode in force, at every opacity alike.

      Parameters:
      x - the left edge of what the layer keeps, in current coordinates
      y - its top edge
      width - its width
      height - its height
      opacity - the opacity the picture is composited with, clamped to [0..1]

    • saveLayer

      default void saveLayer(float x, float y, float width, float height, float opacity, Mat4 transform)
      Opens a layer drawn in a space of its own and composited through transform: until the matching restore(), current coordinates are the layer's, upright, and its picture is laid where the canvas as it stood draws transform times each of its points. The layer's space is the plane z = 0: a point (x, y) of it is drawn at the matrix's x and y of (x, y, 0, 1), each divided by its w, and a point whose w is not above 0 lies behind the eye and is not drawn. This is how a rotated, skewed or turned subtree keeps every clip inside it an exact rectangle (a scroll view turned a few degrees shows nothing in its corners), and clipBounds() answering inside it, so that what scrolled away is still skipped.

      The rectangle, in the layer's own coordinates, is what the picture keeps. A canvas sizes the picture to the part of the rectangle that the clip in force lets be seen once it is turned, in front of the eye, at the largest magnification the transform gives any point of it, the nearest under a perspective, so text and shapes are drawn into it at the size they are seen at; past the window's size the picture is drawn smaller and composited softer. Seen in perspective, the picture is laid perspective-correctly, and a glass drawn inside reads only what the subtree drew beneath it. Its edges are antialiased by a clear ring of one pixel round what is drawn, which the composite's filtering ramps over about a pixel. The clip in force when it is opened, rounded or not, cuts the composite. Otherwise as saveLayer(float, float, float, float, float): the opacity and the blend mode in force are the composite's, and drawing inside starts again from an opacity of 1 and BlendMode.NORMAL.

      What it costs: what a layer of the same size costs, since it is one picture and one quad, and the frame after the last one that opens it frees the picture. A transform that only moves and scales along the axes needs no picture, and a canvas draws through it straight, as translate(float, float) and scale(float, float) would.

      A canvas that cannot make layers applies the transform's flat part, its x, y and w rows and columns without the w row's tilt, straight to its own transform, through translate(float, float), rotate(float) and scale(float, float), and the opacity per draw: the same commands in nearly the same places, which is what counting them needs.

      Parameters:
      x - the left edge of what the layer keeps, in the layer's own coordinates
      y - its top edge
      width - its width
      height - its height
      opacity - the opacity the picture is composited with, clamped to [0..1]
      transform - where the layer's space is drawn, applied after the canvas's own transform

    • setBlendMode

      default void setBlendMode(BlendMode mode)
      Sets the current state's BlendMode: how every subsequent primitive (shape, text, image) combines with the destination. Restored by restore(). Backends without blend-mode support paint BlendMode.NORMAL (the no-op default).

      Inside a layer the destination is the layer's own picture, which starts transparent: a draw in another mode combines with what the layer drew before it, and where it drew nothing is drawn as itself.

    • blendMode

      default BlendMode blendMode()
      Returns:
      the current BlendMode (default BlendMode.NORMAL)

    • setSampling

      default void setSampling(Sampling sampling)
      Sets the current state's image Sampling: how subsequent drawImage calls filter texels (Sampling.PIXELATED keeps pixel art crisp when scaled). Restored by restore(). Shapes and text are unaffected.

    • sampling

      default Sampling sampling()
      Returns:
      the current image Sampling (default Sampling.SMOOTH)

    • setPixelSnap

      default void setPixelSnap(boolean snap)
      Enables/disables the automatic pixel-grid snapping of image quads under axis-aligned transforms. Snapping (the default) keeps icons and stills crisp; disable it for sprites that move sub-pixel per frame. A slow smooth scroll snaps into a visible stutter otherwise. Text and stroke snapping are unaffected. Restored by restore().

    • pixelSnap

      default boolean pixelSnap()
      Returns:
      whether image quads snap to the pixel grid (default true)

    • clipRect

      void clipRect(float x, float y, float width, float height)
      Intersects the clip with an axis-aligned rectangle (in current coordinates). V1 limitation: under a rotated transform the clip degrades to the device-space AABB of the transformed corners, a superset of the requested region (content may show in the AABB's corners). Axis-aligned transforms clip exactly.

    • clipRect

      default void clipRect(Rect rect)
      Intersects the clip with an axis-aligned rectangle (see clipRect(float, float, float, float)).

    • clipBounds

      default @Nullable Rect clipBounds()
      The current clip as a rectangle in current coordinates, or null when this canvas cannot say: it does not track clips, or the transform is rotated and the clip's device-space box has no rectangular pre-image. A caller may use a non-null answer only to skip work whose every pixel would be clipped away, which is what Widget does for a subtree scrolled entirely out of a viewport; nothing may draw more because of it. The default is the null answer, so a canvas that inherits it simply paints everything.

    • clipRoundRect

      void clipRoundRect(RoundRect roundRect)
      Intersects the clip with a rounded rectangle. The corners are this rectangle's own: a clipRect(float, float, float, float) made before or after it cuts the region straight and never rounds where it cuts, so a repaint confined to part of a rounded surface draws that part exactly as a whole frame does.

      V1 limitations: the clip state tracks one rounded rect, so nested rounded clips intersect their rectangles exactly and the region they leave is rounded by the most recent corner radius alone, as a single uniform radius (the max of the four corners, clamped to that region's half extents). That is exact when the inner rounded rect lies inside the outer one; where the two only overlap, every corner of the region they leave is rounded by the inner radius, whichever rectangle it came from. A rounded rect whose corners are all square clips like clipRect and leaves an earlier one's corners as they were. Rotation degrades to the AABB like clipRect.

    • fillRect

      void fillRect(float x, float y, float width, float height, Paint paint)

    • fillRect

      default void fillRect(Rect rect, Paint paint)

    • drawRect

      void drawRect(float x, float y, float width, float height, float strokeWidth, Paint paint)
      Strokes the rectangle outline, centered on its boundary.

    • fillRoundRect

      void fillRoundRect(RoundRect roundRect, Paint paint)

    • fillRoundRect

      default void fillRoundRect(float x, float y, float width, float height, float radius, Paint paint)

    • drawShadow

      default void drawShadow(RoundRect shape, Shadow shadow)
      Draws one layer of the shadow a rounded rectangle casts: the shape moved by the layer's offset, its edge softened over the layer's blur, in the layer's colour. Drawn whole, under where the shape will be: paint the shape after it. Ink reaches Shadow.reach() past the shape's box.

      The default draws nothing: a shadow is decoration a canvas may go without, and a recording or counting canvas has nothing to say about it.

      Parameters:
      shape - the shape that casts it
      shadow - the layer
      Throws:
      NullPointerException - if either argument is null

    • fillBackdropRoundRect

      default void fillBackdropRoundRect(RoundRect roundRect, BackdropEffect effect)
      Fills roundRect with what this frame has already drawn underneath it, put through effect: a glass panel, a wash over video, a redacted field. The shape is opaque within its coverage: the effect replaces the pixels behind it with a transformed copy of them, so a BackdropEffect.tint() with alpha 0 and no displacement is exactly identity.

      It samples the frame at the moment it is called. Anything drawn after it is not in the backdrop and will simply paint on top; anything drawn before it is. That makes paint order load-bearing in a way it is not anywhere else in this interface: a panel must be painted after the content it is meant to sit over, which for a widget means the ordinary child order and for a scene means the ordinary z order.

      Cost. A renderer that batches (this one does) must flush pending geometry and copy a region of the framebuffer before it can sample it, so every call is a batch break plus a copy of the shape's bounds. That is cheap for a control bar and wasteful for a hundred small shapes; it is the reason this is a separate entry point rather than a Paint.

      Where it goes wrong, and it is one place: with partial rendering enabled (Scene.setPartialRendering), a frame repaints only what was invalidated. A shape filled this way depends on pixels that are not its own, so if content behind it changes while it does not itself invalidate, it keeps showing the older backdrop. Over content that repaints anyway (video, an animation, a viewport), the question does not arise. Over static content the effect is correct because nothing moved.

      Rounded rectangles only, which covers rectangles, circles and capsules through the same shape. There is no path-shaped form: the effect needs the shape's signed distance to find its own rim, and a filled path has no analytic distance field.

      Renderers need not implement it. The default fills the shape with BackdropEffect.tint(): a flat translucent panel, the right size in the right place, which is what this toolkit drew before any of this existed. A backdrop effect degrades; it does not fail.

      Throws:
      NullPointerException - if either argument is null

    • fillBackdropRoundRect

      default void fillBackdropRoundRect(float x, float y, float width, float height, float radius, BackdropEffect effect)
      fillBackdropRoundRect(RoundRect, BackdropEffect) with one radius on every corner.

    • drawRoundRect

      void drawRoundRect(RoundRect roundRect, float strokeWidth, Paint paint)
      Strokes the rounded-rect outline, centered on its boundary.

    • drawRoundRect

      default void drawRoundRect(float x, float y, float width, float height, float radius, float strokeWidth, Paint paint)
      Strokes the rounded-rect outline, centered on its boundary.

      A degenerate size (zero or negative width/height) draws nothing rather than throwing, which is the convention every 2D API follows, and a practical necessity: a border drawn inside its box (drawRoundRectBorder(float, float, float, float, float, float, limn.graphics.Paint), a stroke on the box inset by half the border) produces a negative size the moment a widget is laid out narrower than its border, which happens routinely while a window is being resized small. Explicitly building a RoundRect still validates, so genuinely malformed geometry (say, swapped corners) is still caught at construction.

    • fillRoundRectWithBorder

      default void fillRoundRectWithBorder(float x, float y, float width, float height, float radius, Paint fill, float borderWidth, Paint border)
      Paints a bordered surface: fill over the rounded box, and a border borderWidth wide in border lying wholly inside the box, its outer edge exactly the box's outline. The one call for a field, a card, a panel or a swatch; drawRoundRectBorder(float, float, float, float, float, float, limn.graphics.Paint) explains the geometry, and fillRoundRectInsideBorder(float, float, float, float, float, float, limn.graphics.Paint) and clipRoundRectInsideBorder(float, float, float, float, float, float) are its two halves, for a surface that paints something between its fill and its border or whose fill is not one paint.

      The defaults here build on the scalar fillRoundRect and drawRoundRect, so they allocate nothing. A renderer may draw the pair in one pass instead, as long as it keeps the geometry the defaults define, moved onto its pixel grid as the two halves say.

    • drawRoundRectBorder

      default void drawRoundRectBorder(float x, float y, float width, float height, float radius, float borderWidth, Paint paint)
      Strokes a border borderWidth wide lying wholly inside the rounded box, its outer edge exactly the box's outline.

      The geometry. A stroke is centred on its path, so a border inside a box is a stroke on the box inset by half the border. The inset path's corner radius has to shrink by the same half border, and that is what makes it concentric with the box: every point of an arc of radius radius - borderWidth / 2 is half a border from the box's own arc, so the stroke's outer edge follows the box's outline all the way round. Insetting the rectangle but keeping the box's radius, the obvious drawRoundRect(0.5f, 0.5f, w - 1, h - 1, radius, 1, …), draws a corner whose outer edge is an arc of radius radius + 0.5 about a centre half a point further in: on the diagonal it falls 0.5 × (√2 − 1), about 0.2 pt, short of the box's corner, and whatever fills the box shows outside the border there.

      A radius under half the border leaves the path square, and the stroke's outer corner is then rounded by half the border, which is as tight as a centred stroke can draw. A box no wider or taller than its border draws nothing.

    • fillRoundRectInsideBorder

      default void fillRoundRectInsideBorder(float x, float y, float width, float height, float radius, float borderWidth, Paint paint)
      Fills the box inside the border drawRoundRectBorder(float, float, float, float, float, float, limn.graphics.Paint) draws with the same arguments, as far as the border's centre line: the box inset by half the border, with the radius reduced by as much. Reaching exactly that far is what hides the fill's antialiased edge under the border's opaque middle: a fill of the whole box puts that edge on the border's own outer edge, and the partly covered pixels there mix the fill into the border's fringe, which a strong fill under a grey border shows as a coloured rim. Draw the border after it.

      A renderer that moves a stroke's centre line onto its pixel grid (see the class notes) moves this fill's edge with it, to where the border's centre line is drawn rather than where it was asked for: left behind, the fill's corner arc no longer shares a centre with the border's: wherever the border moved inward the fill shows past it on the diagonal, and wherever it moved outward the background shows between the two.

      A border that fades out, leaving the fill to stand alone, is the one case this is wrong for: the fill has to reach the box then, and is a plain fillRoundRect(float, float, float, float, float, Paint) of it.

    • clipRoundRectInsideBorder

      default void clipRoundRectInsideBorder(float x, float y, float width, float height, float radius, float borderWidth)
      Intersects the clip with the shape fillRoundRectInsideBorder(float, float, float, float, float, float, limn.graphics.Paint) fills, for a surface whose fill is a gradient, an image or several shapes: clip, paint them over the whole box, restore, then draw the border. Builds one RoundRect, as clipRoundRect(limn.graphics.RoundRect) needs. A renderer that moves strokes onto its pixel grid moves this clip's edge with the border's centre line, as fillRoundRectInsideBorder(float, float, float, float, float, float, limn.graphics.Paint) explains.

    • fillCircle

      void fillCircle(float cx, float cy, float radius, Paint paint)

    • drawCircle

      void drawCircle(float cx, float cy, float radius, float strokeWidth, Paint paint)

    • fillEllipse

      void fillEllipse(float cx, float cy, float radiusX, float radiusY, Paint paint)

    • drawEllipse

      void drawEllipse(float cx, float cy, float radiusX, float radiusY, float strokeWidth, Paint paint)

    • drawLine

      void drawLine(float x1, float y1, float x2, float y2, float strokeWidth, Paint paint)
      Line segment with round caps. Axis-aligned lines are pixel-snapped.

    • fillPath

      void fillPath(Path2D path, Paint paint)
      Fills a path. Each closed subpath is filled independently (see Path2D for the v1 winding limitations).

    • drawPath

      void drawPath(Path2D path, float strokeWidth, Paint paint)
      Strokes a path with round caps and joins. V1 limitation: joins are overlapping round caps, so translucent paints double-blend slightly at each vertex.

    • drawText

      void drawText(String text, float x, float y, Font font, Paint paint)
      Draws a single line of text with (x, y) at the baseline origin. Glyphs are rasterized at font.size() × the effective device scale (content scale × canvas transform) and cached in a glyph atlas keyed by physical pixel size: bitmaps are never scaled, so text stays sharp at 1.0/1.25/1.5/2.0. Under axis-aligned uniform transforms, glyphs are snapped to the physical pixel grid.

      Full code-point support, surrogate pairs included. A code point the font lacks is resolved against the registered fallback faces, so mixed-script text draws; a code point no face has renders as .notdef.

      This is the shaped path with the shaping done for you. A canvas that has a shaper hands the string to the installed TextRuler and draws the ShapedText it gets back, so contextual forms, ligatures, mark attachment and bidirectional ordering are what any caption gets, not only the widgets that hold a value of their own. What that costs is one memo lookup per call on the ruler's side; what it buys is that the string measured by measureText(java.lang.String, limn.graphics.Font) and the string drawn here are the same arithmetic. A caller that draws the same text every frame should still hold a ShapedText and use the overload below — that is the form that pays nothing at all, and the only one that carries a base direction: this one resolves the paragraph from the string alone, left to right where no character is strong, which is wrong exactly for the all-neutral captions a widget could have decided (Widget.shapeText).

      Control characters, \n included, are skipped: multi-line layout belongs to the widget layer. Under anisotropic scale glyphs rasterize at the larger axis and filter on the smaller one.

    • drawText

      default void drawText(ShapedText text, float x, float y, Paint paint)
      Draws an already-shaped line with (x, y) at the baseline origin of its left edge — for either base direction: right-to-left text fills the same box from the other end rather than growing leftwards from x, so the run covers [x, x + text.metrics().width()] and right-aligning a right-to-left paragraph is a matter of choosing x. Rasterization, atlas keying and pixel snapping are exactly as drawText(String, float, float, Font, Paint) describes.

      This is the form that costs nothing per frame: the shaping was already paid for, and this walks runs, resolving a face once each, then glyphs. The String overload above draws the same scripts equally correctly and pays a memo lookup to do it; the difference is only who holds the value. There is no Font parameter because the font is the one the glyphs were chosen for; a font passed here could disagree with it, and the text would then be measured by one face and drawn by another.

      A cluster reported as ShapedText.NO_GLYPH is drawn from the shaped text's own characters instead, which is how a colour-emoji strike keeps working and how a ruler that cannot shape still paints. So does a run whose face this canvas no longer recognizes, which is what a value shaped before an eviction becomes: a stale value draws the right characters by the slower route rather than the wrong glyphs from whichever face inherited the id.

      The whole run draws in one Paint. Text that changes colour partway is two runs today, and two runs shape independently.

      Default, not abstract, for two reasons that point the same way. Canvas is a published interface, and an abstract method added to one breaks every implementation that exists outside this repository as well as every recording and counting canvas inside it. And the honest fallback for a canvas that cannot place glyphs itself is the string the run was shaped from, which is what the default draws.

    • measureText

      TextMetrics measureText(String text, Font font)
      Measures a single line of text in logical points (baseline-relative, unquantized and therefore independent of the monitor scale). Same code-point rules as drawText(java.lang.String, float, float, limn.graphics.Font, limn.graphics.Paint), and the same shaping: a canvas that shapes when it draws measures what it will draw, so a caption is never laid out to one width and painted at another.

    • drawImage

      void drawImage(Image image, float x, float y, float w, float h)
      Draws image into the rectangle (x, y, w, h) in logical points, scaled with linear filtering, modulated by the current opacity(). The GPU texture is created lazily on first use and cached per window, within Images.textureBudget() as Images.setTextureBudget(long) describes: a texture dropped at a frame boundary is made again when its image is next drawn, and none that the frame just ended drew is dropped.

    • drawImage

      default void drawImage(Image image, float x, float y)
      Draws image at its natural pixel size (1 pixel = 1 logical point).

    • drawImage

      void drawImage(Image image, float srcX, float srcY, float srcW, float srcH, float dstX, float dstY, float dstW, float dstH)
      Draws the source rectangle (srcX, srcY, srcW, srcH), in image pixels, into the destination rectangle (dstX, dstY, dstW, dstH) in logical points. This is the sprite primitive: frames of a sprite sheet, tiles of a tileset and regions of a texture atlas all draw from one shared Image (one GPU texture, so batching stays unbroken across sprites of the same sheet).

      The source rectangle is not clamped: coordinates outside the image sample the edge texels (CLAMP_TO_EDGE). With Sampling.SMOOTH, half a texel of bleed from neighboring atlas cells is possible at the edges; pack sheets with 1px gutters or use Sampling.PIXELATED for exact cells. Gutters only protect mip level 0: SMOOTH minification (drawing a cell well below its pixel size) selects coarser mips where whole cells average together; for atlases that will be minified, use PIXELATED or pad cells generously.

    • drawImage

      void drawImage(Image image, float srcX, float srcY, float srcW, float srcH, float dstX, float dstY, float dstW, float dstH, Color tint)
      The sprite primitive and the tint, together: one cell of a sheet, modulated by tint exactly as drawImage(Image, float, float, float, float, Color) modulates a whole image.

      Both halves already existed and could not be used at once, which left an ordinary thing (a tinted sprite from a sheet) reachable only by splitting the sheet into one Image per cell and losing the batching that is the point of a sheet. Everything the source-rectangle overload says about clamping, bleed and mips applies here unchanged.

    • drawImage

      void drawImage(Image image, float x, float y, float w, float h, Color tint)
      Draws image tinted by tint (its RGB and alpha are multiplied by the tint's), the path for modulating a picture (e.g. ImageView.setTint). A white opaque tint draws it unchanged. A black source stays black: to recolor a mask, use drawImageMask(limn.graphics.Image, float, float, float, float, limn.graphics.Color).

    • drawImageMask

      default void drawImageMask(Image image, float x, float y, float w, float h, Color tint)
      Draws image as a single-color mask: the image's alpha is used as coverage and painted in tint's color; the image's own RGB is ignored. This is the icon-recolor path: a mask authored in any color (black, white, colored) recolors cleanly to the theme, unlike drawImage(Image, float, float, float, float, Color) which multiplies (so a black mask would stay black). The default falls back to that multiply; backends override for a true coverage tint.

    • drawSurface

      void drawSurface(GpuSurface surface, float x, float y, float w, float h)
      Composites a GpuSurface (e.g. an offscreen 3D viewport) into the rectangle (x, y, w, h) in logical points, as one quad in the 2D paint order, so overlays, dialogs, tooltips and clipping apply to it like any other content. The surface must already have been rendered this frame.

      No default: it was a no-op, so a backend that did not implement it drew every 3D viewport and video blank without an error. A canvas that cannot composite a GPU surface (a recording or measuring canvas) implements it as a no-op, on purpose and in writing.