This file contains ambiguous Unicode characters

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. cl-slug has the band builder, cl-slug/clsl the shader. Each function's docstring says the same: (describe 'cl-slug:store-add).

Thread rules for everything in cl-slug: a store and its shapes may be used from any number of threads at once.

Conditions

slug-error (condition)

The base of every error cl-slug signals. A subclass of error.

Reader	Returns
(slug-error-message condition)	What went wrong, and what to do about it.

See Errors and Limits.

Stores

+texture-width+ (constant)

4096: the width in texels of the curve and band textures.

store (class)

Shapes placed in a curve texture and a band texture. Make one with make-store.

Reader	Returns
(store-epsilon store)	How far bands overlap, in ems.
(store-max-rows store)	The most rows either texture may have.

make-store

(make-store &key (epsilon 1/1024) (max-rows 4096)) => store

A new, empty store. epsilon is a non-negative real, in ems; max-rows an integer from 1 to 65536. See Stores.

store-add

(store-add store curves &key (fill-rule :nonzero)) => shape

Adds the shape made of curves and returns it. Signals slug-error for bad curves or a full store. See Shapes and Curves.

store-find-or-add

(store-find-or-add store key function) => shape

The shape for key, compared with equal. The first time, calls function with no arguments for the curves, and optionally the fill rule as a second value, outside the store's lock, and adds them.

store-find

(store-find store key) => shape or nil

The shape store-find-or-add added for key, or nil.

store-shape-count

(store-shape-count store) => integer

How many shapes have been added.

store-curve-rows, store-band-rows

(store-curve-rows store) => integer
(store-band-rows store) => integer

How many rows of the curve or band texture hold data: how tall the texture must be, at most the store's max-rows.

take-curve-changes, take-band-changes

(take-curve-changes store) => first-row, row-count   or nil
(take-band-changes store) => first-row, row-count    or nil

The rows written since the function was last called, which are forgotten, or nil. Allocates nothing.

copy-curve-rows, copy-band-rows

(copy-curve-rows store row count) => (simple-array (unsigned-byte 16) (*))
(copy-band-rows store row count) => (simple-array (unsigned-byte 16) (*))

A fresh copy of count rows from row: four 16-bit integers a texel for the curve texture, the bits of half floats, and two for the band texture. Rows below the data are zeros. row is from 0 to 65535 and count from 0 to 65536, since no texture of a store has more rows than 65536.

Shapes

curves (type)

A shape's curves: a vector of reals, six per quadratic curve, X0 Y0 CX CY X1 Y1, in ems with y up, in closed contours. See Shapes and Curves.

fill-rule (type)

(member :nonzero :even-odd). See Shapes and Curves.

shape (structure)

A shape in a store, as store-add returns it. Immutable, and may be read from any thread. It prints with its curve and band counts: #<CL-SLUG:SHAPE 11 curves, 7 by 3 bands {...}>.

Reader	Returns
(shape-xmin shape), (shape-ymin shape), (shape-xmax shape), (shape-ymax shape)	Its bounds in ems, single-floats, rounded to half floats. All 0.0 for an empty shape.
(shape-fill-rule shape)	:nonzero or :even-odd.
(shape-curve-count shape)	How many curves it has, after curves of no length are left out.

What the pixel shader needs is written by write-shape-data. One by one, for a renderer that packs them its own way:

Reader	Returns
(shape-data-x shape), (shape-data-y shape)	Where its data starts in the band texture.
(shape-vertical-band-count shape)	How many vertical bands its bounds are cut into, across x: 1 to 32, or 0 for an empty shape.
(shape-horizontal-band-count shape)	How many horizontal bands, up y: 1 to 32, or 0 for an empty shape.
(shape-band-scale-x shape), (shape-band-scale-y shape)	Bands per em, across and up.
(shape-band-offset-x shape), (shape-band-offset-y shape)	With the scales, map an em coordinate to a band index: coordinate × scale + offset.

write-shape-data

(write-shape-data shape vector start) => (no values)

Writes the eight single-floats slug-coverage needs for shape into vector, a (simple-array single-float (*)), from start:

Index	Value	Passed to the shader as
start … start+3	band scale x, scale y, offset x, offset y	banding, a vec4
start+4, start+5	shape-data-x, shape-data-y	data, an ivec4
start+6	index of the last vertical band
start+7	index of the last horizontal band, plus 4096 for :even-odd

Allocates nothing, so it suits filling an instance buffer each frame. Signals slug-error if the eight do not fit in vector. An empty shape writes zeros for its data; it draws nothing, so skip it.

+shape-data-floats+ (constant)

8: how many floats write-shape-data writes.

shape-empty-p

(shape-empty-p shape) => boolean

True if the shape has no curves, as a space has none. It draws nothing.

shape-glyph-words

(shape-glyph-words shape) => tex-z, tex-w

The shape's data as the reference vertex shader's tex.z and tex.w, two 32-bit words, for renderers using the reference HLSL shaders. See Data Format.

Half floats

half-float-bits

(half-float-bits real) => (unsigned-byte 16)

The bits of the half-precision float nearest real, rounded to nearest with ties to even. real is one that rounds to a finite half: of magnitude less than 65520, halfway from the largest half, 65504, to the next step. Another, an infinity included, signals a type-error.

half-float-value

(half-float-value bits) => single-float

The value of the half-precision float whose bits are bits. Negative zero keeps its sign. bits are those of a finite half, from #x0000 to #x7BFF or from #x8000 to #xFBFF: an infinity's or a NaN's signal a type-error.

cl-slug/clsl

slug-coverage (clsl shader function)

(slug-coverage curves bands render banding data) => :float

In a clsl fragment shader: how much of the pixel at render, in the shape's ems, the shape covers, from 0 to 1. curves is a :sampler2d of the curve texture and bands a :usampler2d of the band texture. banding, a :vec4, and data, an :ivec4, are the eight numbers write-shape-data writes. See Shaders.

The package's other functions, such as root-code and solve-horizontal, are internal steps of slug-coverage, named as in the reference shader.