Table of Contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
API Reference
Every exported symbol of the package cl-sdf, which the examples call sdf through a local nickname (see Getting Started). Each function's docstring says the same: (describe 'sdf:generate-mtsdf). Every exported function has a declaimed ftype, which gives each argument's full type, such as (integer 1), fill-rule or (or null rectangle): SBCL checks it when the function is entered. See Errors for the types and what a wrong argument signals.
Thread rules for everything here: cl-sdf has no global state, so every function may be called from any number of threads at once. Shapes and colored edges are immutable. A field may be read from many threads; writing its samples while others read them needs your own lock.
Types
segment (type)
One outline segment: (:line x0 y0 x1 y1), (:quadratic x0 y0 cx cy x1 y1) or (:cubic x0 y0 c1x c1y c2x c2y x1 y1), all coordinates coordinates. See Contours and Fill Rules.
coordinate (type)
A real within ±1e36: a coordinate, bound, padding or query point in shape units. Within it, every distance fits the single-floats a field stores. Spreads and tolerances are positive reals up to 1e36. See Errors.
rectangle (type)
A list (xmin ymin xmax ymax) of four coordinates, in shape units: the form of :bounds, bounds, contour-bounds and shape-bounds, and of field-bounds unless padding took it beyond ±1e36.
fill-rule (type)
:nonzero or :even-odd.
y-axis (type)
:up, row zero at the bottom of a field's bounds, or :down, row zero at the top.
edge-color (type)
:red, :green, :blue, :cyan, :magenta, :yellow or :white: the channels an MSDF edge feeds. See Edge Coloring.
Conditions
See Errors for every message.
sdf-error (condition)
The base of every error cl-sdf signals itself. A subclass of error. Its report says what went wrong and what to change. Wrong argument types signal cl:type-error, except malformed contours, which signal invalid-contours-error, both.
invalid-contours-error (condition)
Contours, a contour or a segment are malformed. A subclass of both sdf-error and type-error: type-error-datum is the offending object, type-error-expected-type what was expected.
| Reader | Returns |
|---|---|
(invalid-contours-error-contour-index condition) |
The position of the bad contour, or nil if the whole argument is malformed. |
(invalid-contours-error-segment-index condition) |
The position of the bad segment in its contour, or nil if the contour itself is malformed. |
open-contour-error (condition)
A signed query, make-shape or a generator was given a contour that does not close. A subclass of sdf-error.
| Reader | Returns |
|---|---|
(open-contour-error-contour-index condition) |
The position of the open contour. |
(open-contour-error-gap condition) |
(x0 y0 x1 y1): one segment ends at x0, y0 and the next starts at x1, y1. |
Geometry
bounds
(bounds contours) => (xmin ymin xmax ymax)
The box around every point of contours, control points included, as double-floats; all zeros if there are no points.
contour-bounds
(contour-bounds contour) => (xmin ymin xmax ymax)
The same for one contour.
flatten-contours
(flatten-contours contours &key (tolerance 0.01d0)) => list of contours of (x0 y0 x1 y1)
contours as polylines, each line a list of four double-floats, with the same nesting. Curves are halved until their control points are within tolerance of the chord. Signals sdf-error if 24 halvings are not enough.
Prepared shapes
shape (structure)
Contours prepared once for many point queries: flattened, with the filled region's boundary resolved, both indexed. Made by make-shape. Immutable. Prints as #<CL-SDF:SHAPE 32 lines, :NONZERO {…}>.
| Reader | Returns |
|---|---|
(shape-fill-rule shape) |
The fill rule it was made with. |
(shape-bounds shape) |
The contours' control-point box, a rectangle. |
shape-p
(shape-p object) => boolean
True if object is a shape.
make-shape
(make-shape contours &key (fill-rule :nonzero) (flatten-tolerance 0.01d0)) => shape
Prepares contours, which must be closed. Signals open-contour-error otherwise. See Distance Queries.
Distance queries
shape is a shape or a list of contours. With contours, :fill-rule and :flatten-tolerance apply to the one call; with a shape, passing either signals sdf-error. x and y are coordinates.
inside-p
(inside-p shape x y &key fill-rule flatten-tolerance) => boolean
True if the point is inside, by the fill rule over every input segment. Contours must be closed; an open one signals open-contour-error.
signed-distance
(signed-distance shape x y &key fill-rule flatten-tolerance) => double-float
The distance to the filled region's boundary, positive inside. Ignores edges with fill on both sides. With contours, makes a shape on every call. Empty input: -3.4028234663852886d38.
unsigned-distance
(unsigned-distance shape x y &key flatten-tolerance) => double-float
The distance to the nearest input segment, internal ones included. Accepts open contours and isolated points. Empty input: 3.4028234663852886d38.
encode-distance
(encode-distance distance spread &key (clamp t)) => single-float
0.5 + distance / (2 × spread), clamped to 0..1 unless clamp is false. distance is any real within the double-float range, spread a positive one. Unclamped, a sample beyond the single-float range signals sdf-error.
decode-distance
(decode-distance value spread) => double-float
The inverse of encode-distance: (value − 0.5) × 2 × spread. Arguments within the double-float range; a result beyond it signals sdf-error.
Edge coloring
colored-edge (structure)
A segment and the color that says which MSDF channels it feeds. Immutable.
| Reader | Returns |
|---|---|
(colored-edge-segment edge) |
The segment. |
(colored-edge-color edge) |
The edge-color. |
make-colored-edge
(make-colored-edge segment color) => colored-edge
Signals type-error for a segment that is not a segment and for an unknown color. Fields accept only :cyan, :magenta, :yellow and :white edges.
edge-color-channels
(edge-color-channels color) => list of :red, :green, :blue
The channels color feeds: :magenta gives (:red :blue).
color-edges
(color-edges contours &key (colors '(:cyan :magenta :yellow)) (angle-threshold 3d0))
=> list of contours of colored-edge
The automatic coloring the generators use; its result can be passed to them in place of the contours. colors is a palette of at least two distinct colors from cyan, magenta and yellow; three are needed for contours with an odd number of corners. A joint is a corner if the angle between its edges is less than angle-threshold, in radians from 0 to π. Smooth contours are white; contours with one corner are split into thirds; point segments are left out. See Edge Coloring.
Fields
field (structure)
A generated distance field and the mapping it was made with. Prints as #<CL-SDF:FIELD 64 by 64, 4 channels {…}>. See Reading Fields.
| Reader | Returns |
|---|---|
(field-width field) |
Columns. |
(field-height field) |
Rows. |
(field-channels field) |
1, 3 or 4. |
(field-data field) |
The samples, a (simple-array single-float (*)), row-major, channels interleaved. |
(field-bounds field) |
The list (xmin ymin xmax ymax) of double-floats the texels cover, after padding: a rectangle, unless padding took it beyond ±1e36. Do not modify it. |
(field-spread field) |
The distance, in shape units, that maps to 0 and 1. A double-float. |
(field-y-axis field) |
:up or :down. |
(field-normalized-p field) |
True if samples are 0..1, false if they are raw distances. |
field-ref
(field-ref field column row &optional (channel 0)) => single-float
(setf (field-ref field column row &optional (channel 0)) value)
The stored sample. Out-of-range indexes signal sdf-error. setf stores any real within the single-float range, as a single-float.
field-distance
(field-distance field column row &optional (channel 0)) => double-float
The sample as a distance in shape units: decoded with the spread for a normalized field, as stored for a raw one.
field-octets
(field-octets field) => (simple-array (unsigned-byte 8) (*))
A fresh vector of bytes in field-data's layout, each sample clamped and mapped to the nearest of 0..255; the edge is 128. Signals sdf-error for a raw field.
Generation
generate-sdf
(generate-sdf contours width height
&key bounds (padding 0d0) spread (px-spread 4d0) (fill-rule :nonzero)
flatten-tolerance (y-axis :up) (normalize t))
=> field
A one-channel signed distance field of closed contours, width by height texels. contours may also be colored contours, as for generate-msdf; the colors are ignored. Every option is explained in Generating Fields.
generate-msdf
(generate-msdf contours width height
&key bounds (padding 0d0) spread (px-spread 4d0) (fill-rule :nonzero)
flatten-tolerance (y-axis :up) (normalize t) (error-correction t))
=> field
A three-channel multi-channel signed distance field. contours are contours of segments, colored automatically, or contours of colored-edges, as color-edges returns, to choose the colors: every edge colored or none, each cyan, magenta, yellow or white. error-correction false skips the artifact pass.
generate-mtsdf
(generate-mtsdf contours width height &key ...) => field
The same arguments as generate-msdf. Four channels: the MSDF in the first three, and the true distance, exactly generate-sdf's, in the fourth.