The shader library

Ollin splices its shader library into every user-supplied shader at compile time, so you can call these helpers from inside shade(uv, info) with no #include. They are the same helpers Ollin's own shaders use, so there is one source of truth. Each one is written from the published technique and credited in the Techniques list.

Compute kernels get the same library in full, so a helper you learn here works the same way in a kernel. The using: option is a fragment-Shader option only, because a kernel always sees everything.

By default the whole library is available. Unused helpers are removed as dead code, so on the GPU the choice costs nothing either way. Restrict the library with the using: option to cut compile time:

let s = Shader(source, using: [.noise, .sdf])   // only these sections splice

Contents

• Color (base)
• Palettes & perceptual color
• Hashing
• Noise
• Signed-distance functions
• Domain operators
• Complex numbers
• Visual-chain operations
• Chaotic systems (compute only)

Color (base)

These are always available. The render pipeline composites in linear light, so they convert between the sRGB values you author and the linear values that blend correctly.

A shade function returns straight sRGB and Ollin handles the linear conversion, so you only need these functions for your own color math.

Palettes & perceptual color

using: .color. OKLab math assumes non-negative linear RGB.

To mix in OKLab or OKLCH, interpolate there and then convert back. That gives you even lightness and clean hue sweeps, which linear-RGB mixing cannot.

thinFilm returns a reflectance, not a finished color, so multiply it by whatever the surface is reflecting. The color moves with cosTheta, which is what produces the effect. If your sketch wants bands across a shape, feed cosTheta a coordinate rather than a constant. The 3D material is the same model wired into the physically based finish.

Hashing

using: .hash. These give pseudo-random values from a coordinate, in [0, 1), with no texture lookup. The name is hashNM, where N is the number of output channels and M is the number of seed components.

Noise

using: .noise, which pulls in .hash. Value noise reads in about [0, 1], and gradient noise in about [-1, 1].

Signed-distance functions

using: .sdf. Each function returns the signed distance to a shape's outline in local units, negative inside and positive outside. The open shapes sdSegment, sdArc, and sdBezier return an unsigned distance instead. Combine the shapes with smin and the domain operators. To turn a distance into an anti-aliased edge, use fwidth (smoothstep(fw, -fw, d)). These are the canonical 2D distance functions. A few of them take precomputed (sin, cos) angle vectors, which is the form the originals use.

Domain operators

using: .domain. These transform the point a field is evaluated at. The tiling operators change the point in place and return the cell or side index. A shape evaluated at the transformed point then tiles or reflects across space, so you never evaluate it once per copy. Rotation works differently, because it takes a point and returns another one.

This example draws a ring of one shape:

float4 shade(float2 uv, ShaderInfo info) {
    float2 p = (uv - 0.5) * 8.0;
    pmodPolar(p, 8.0);              // 8-fold radial fold
    p.x -= 2.5;                     // push the cell out to a radius
    float d = sdHeart(p * 1.5) / 1.5;
    float e = fwidth(d);
    float cov = smoothstep(e, -e, d);
    return float4(palette(0.6, float3(0.5), float3(0.5),
                          float3(1.0), float3(0.0, 0.1, 0.2)) * cov, 1.0);
}

Complex numbers

using: .complex (pulls in .color for the wheel). A float2 read as a complex number, x the real part and y the imaginary part. A point of the plane is then a number, and the functions below are what a plain * cannot do: multiplying multiplies the lengths and adds the angles. The names follow C's own complex library, with cmul and cdiv for the two operators C never had to name. Every multi-valued function takes the principal branch, the argument in (-pi, pi], so the seam along the negative real axis is real and shown. Each mirrors the CPU Complex value of the same meaning. A curve worked out in draw() lands on the pixels a shader paints.

The transcendentals clamp their exponent, so a far-out pixel saturates instead of returning an infinity that atan2 cannot take a direction from.

float4 shade(float2 uv, ShaderInfo info) {
    float2 z = complexPlane(uv, info.resolution, float2(0.0), 3.0);
    float2 p = cpolar(0.8, info.time), q = cpolar(0.8, info.time + 2.3);
    float2 f = cdiv(z - p, z - q);              // a zero at p, a pole at q
    return float4(domainColor(f, 2, 0.7), 1.0);
}

Visual-chain operations

using: .visual, which pulls in .hash and .noise. These are the per-pixel sources, coordinate warps, HSV color adjustments, and two-input blends behind Visual chains. You can call them from a hand-written shader too. Colors are straight sRGB. An operation that would distort on a non-square canvas takes an aspect (width / height) and corrects for it.

Spatial-hash neighbor search (compute only)

These are always available in a compute kernel. They take bound buffers, so they are not part of the using: fragment-shader subset. They are the primitives behind SpatialHash and the artificial-life sims, and OllinSpatialGrid is the shared grid struct.

Chaotic systems (compute only)

These are always available in a compute kernel. Like the neighbor search, they sit outside the using: fragment-shader subset. They are the velocity fields behind AttractorFlow and the classic iterated maps, written from their published equations. A kernel of your own can use them to run a chaotic system directly.

A flow returns the derivative at a phase-space point, and you advance it with OLLIN_RK4_STEP. A map returns the next point directly and needs no integration.

derivative is an expression in the sample point _p, which is how a system's constants reach it. Metal has no function pointers here, so this is a macro, like the neighbor iteration:

OLLIN_RK4_STEP(state, 0.01, ollin_lorenz(_p, 10.0, 28.0, 8.0 / 3.0));

Keep the step near the one the system was published with. A step much larger than the system's own scale integrates a different system, so take several small steps rather than one big one.

See also

• Shaders: the Shader type, the shade(uv, info) contract, and running a shader as a generator/filter/combine
• Visuals: the fluent Visual chains these operations render
• SDF combinators: compose signed-distance fields into merged shapes without writing shader code
• Color: the CPU-side Color, Palette, and OKLab family
• Strange attractors: the CPU orbits and the AttractorFlow these fields drive