Getting started

Kaustics draws the light that polished metal, glass and water throw on to the surfaces around them: the cardioid inside a ring on a table, the bright spot in a glass ball’s shadow, the moving net of light on the floor of a pool. It runs every frame on the GPU, so the light, the objects and the meshes themselves can all move.

#Requirements

iOS 17 or later
Xcode 16 or later (Swift 6)

#Install

Add the package in Xcode (File, Add Package Dependencies) or in Package.swift:

Swift

.package(url: "https://github.com/dovas-net/kaustics-ios.git", from: "0.1.0")

and add Kaustics to your target’s dependencies.

#Your first scene

A KausticsScene holds a light, the casters that throw caustics, the surfaces the light lands on, and a camera. A KausticsView draws it.

Swift

import Kaustics
import SwiftUI

struct RingView: View {
    @State private var scene = KausticsScene(
        light: KausticsLight(
            position: [1.6, 0.7, 1.4], intensity: 12, radius: 0.025),
        casters: [
            KausticsCaster(
                mesh: try! .ring(),
                material: .metal(.gold, roughness: 0.04))
        ],
        surfaces: [
            .init(.floor(size: [2, 2]), color: [0.75, 0.73, 0.7])
        ],
        camera: .init(
            position: [0, 1.15, 1.45],
            target: [0, 0, 0],
            fieldOfView: 0.95))

    var body: some View {
        KausticsView(scene: scene).ignoresSafeArea()
    }
}

That is a gold ring standing on a floor. Lit from low down, the inside of its wall gathers light into a cardioid on the floor.

Drag across the view to move the light around scene.lightPivot. Everything in the scene can be changed from the main actor while it runs, and scene.onFrame is called before every frame for animation.

#Two levels of API

	Use it when
The SwiftUI view	You want a whole scene drawn for you: the surfaces lit by the light, its soft shadow and the caustics, metal reflecting a small studio, glass and water showing what is behind them. See Scenes and the view.
The renderer	You have your own Metal renderer and want the caustics as textures to add to your own lighting. See Your own Metal pipeline.

KausticsView is there to make the easy case easy, not to be a general renderer.

#Where to next

Materials covers metal, water and glass.
Meshes covers what throws the light, and why it needs smooth normals.
How it works explains the five passes behind every frame.
Limits of v0.1.0 lists what Kaustics does not do yet.