Docs menu: Signed distance fields Documentation home
On this page The sdf element Primitives Operations Choosing k Where it renders

Signed distance fields

Shape trees built from primitives and boolean operations, evaluated per pixel.

An sdf element draws a shape described by a distance function instead of an outline. For every pixel, the function returns the signed distance to the shape's edge: negative inside, positive outside, zero on the edge. Pixels with a negative distance are filled.

The distance form makes operations possible that outlines handle poorly. Two shapes can be merged with a smooth join, one shape can be carved out of another, and a shape can be grown or shrunk by a fixed amount. The renderers evaluate the field per pixel, so edges stay exact at any size.

sdf_shapes rendered
examples/sdf_shapes.msx · 64 lines · open in playground · all samples

The sdf element

{ type = "sdf", fill = #4a9eff,
  transform = { type = "translate", x = 75, y = 100 },
  tree = { type = "circle", cx = 0, cy = 0, r = 55 } }
Field Meaning Default
tree The shape tree required
fill Paint for the inside none
stroke Paint for the edge none
stroke_width Edge width. Read only when stroke is set
id, transform As for every element

A node with neither a fill nor a stroke draws nothing. The usual pattern is to build each shape around the origin and position it with transform, as the example above does.

Primitives

Type Fields Defaults
circle cx, cy, r cx and cy 0, r required
box x, y, width, height, corner_radius x and y 0, size required, radius 0
line x1, y1, x2, y2, thickness coordinates 0, thickness 1
ring cx, cy, r, thickness center 0, r required, thickness 1
arc cx, cy, r, angle_start, angle_end, thickness center 0, r required, angles 0 and 2π, thickness 1

box is positioned by its top left corner, like a rect. A box with x = -55, y = -45, width = 110 and height = 90 is centered on the origin. thickness is the full width of the band, so a ring with r = 48 and thickness = 16 covers the radii from 40 to 56. Angles of an arc are in radians, measured from the positive x axis and increasing clockwise on screen. The arc runs from angle_start up to angle_end, and its ends are rounded.

Warning Set both angles of an arc. The defaults, 0 and 2π, name the same direction, so the arc covers almost nothing and draws only a dot at its start. Use a ring for a full circle.

Operations

An operation combines other trees. Its children are written as nested objects.

Type Fields Result
union children Everything covered by any child
smooth_union children, k A union with a rounded join
subtract a, b a with b carved out
smooth_subtract a, b, k A subtraction with a rounded edge
intersect a, b Only the area both cover
smooth_intersect a, b, k An intersection with rounded corners
offset child, amount The child grown by amount, or shrunk when negative

union and smooth_union take any number of children in an array. The other binary operations take exactly two trees named a and b. offset takes one tree named child. The default k of a smooth union is 0.1, and amount defaults to 0.

{ type = "sdf", fill = #ff6b6b,
  transform = { type = "translate", x = 225, y = 280 },
  tree = { type = "smooth_union", k = 14,
    children = [ { type = "circle", cx = -22, cy = 0, r = 38 },
                 { type = "circle", cx =  22, cy = 0, r = 38 } ] } }

Choosing k

k is the width of the blend zone, in the same units as the distances, which are pixels in the node's own coordinate space. The smooth join moves the edge by at most a quarter of k. A k below about 4 is therefore hard to see on shapes a few dozen pixels across, and values between 10 and 30 give a clear fillet. A k of 0 or less gives the hard operation.

Where it renders

The CPU and GPU renderers evaluate the tree per pixel. The SVG renderer has no way to express the shape and writes a comment in its place, so an sdf element is missing from SVG output. Shapes in this form can also take a shader fill on the GPU, as in the sdf_shader_fill example.

For animation, an sdf node responds to transform tracks only. Its opacity is not a channel.