SOFTrobots OS · App-API

As of 14 November 2026 · App-API 1 · Draft until release 1.0.0 – declarations may still change; programs are then rebuilt, not kept compatible · reorganised by module (rights · system calls · Swift), with App-API, System-API and libraries apart · 1078 declarations in docs/api/app-api-1.txt, 874 in docs/api/libraries.txt

Overview

Three levels

Rights in the signed manifest (capabilities = …, 32 names) · system calls in shapes/*.shape (138 calls in 24 modules, plus 14 primitive ones) · Swift for programs (SOFTrobotsKit). The kernel checks every system call against the rights; Swift makes the system calls.

One module, one name

Every area has the same name on all three levels: the prefix of its rights, its system-call module and its Swift namespace (network.outgoing · network.connect · Network.Connection). Swift is always shown with its full name (Database.Query.where(_:), never just where(_:)).

App-API · System-API · libraries

App-API: what every program may use – calls without a right or with one of the 9 rights a normal program can have (Capability.fromDevelop). System-API (marked grey): everything that needs one of the other 23 rights – for system programs only. Libraries: tools such as web, pictures, SVG that a program builds in through a uses-… file.

How to read an entry

Three parts per module: rights, system calls (with the right each needs) and Swift by task. A Swift row: full name and signature, a one-line explanation, on the right the system call behind it with its ≤ 2 ms time budget (the longest running time the kernel promises) and ID. Below it a collapsed example, usually from real programs (apps/…), otherwise marked as a “pattern”. new = since 10 or 11 Nov.

What is frozen at 1.0

Only the App-API: from release 1.0.0 its names, argument labels and types stay, new things are only added (make api-check against docs/api/app-api-1.txt, 1078 declarations). Until then everything is a draft: programs are rebuilt, not kept compatible. The System-API and the libraries (docs/api/libraries.txt, 874 declarations) may keep changing.

Renamed on 11 Nov

LevelOldNew
Rightapps.launchprograms.launch
Rightdevelop.buildprograms.build
Rightdevice.cameracamera.use
Rightdevice.microphonesound.microphone
Rightmicrophone.providesound.microphone.provide
Rightinput.receiveui.input
Rightinput.provideui.input.provide
Rightdisplay.ownui.display
Rightipcchannels.ipc
System-call modulenet.* (net.receive, net.connect …)network.* (network.receive, network.connect …)
System-call moduledb.* (db.open, db.query …)database.* (database.open, database.query …)
SwiftAppsPrograms
SwiftFileFiles.Handle
SwiftWriteSetDatabase.Write
SwiftQueryDatabase.Query
SwiftQueryPageDatabase.Page
SwiftNetConnectionNetwork.Connection
SwiftNetPeerNetwork.Peer
SwiftNetListenerNetwork.Listener
SwiftDatagramSocketNetwork.Datagram
SwiftSoundOutputSound.Output
SwiftMicrophoneSound.Microphone
SwiftMicrophoneInfoSound.MicrophoneInfo
SwiftMicrophoneRingSound.MicrophoneRing

Other names stayed (e.g. Surface, Canvas, Camera, ArmModel, Channel); the module IDs are unchanged. This table names the old names on purpose; otherwise they no longer appear on this page.

45 sections · App-API: 15 modules, 9 rights, 82 system calls, 942 Swift declarations · System-API: 23 rights, 56 system calls, 136 declarations · libraries: 10, 874 declarations · 515 explained entries · 243 examples

Manifest & profiles

A program gets rights only through its manifest (the file manifest in the program folder, signed at build time). The line capabilities = … names the rights; the kernel checks every call against them. An unknown right makes the manifest invalid – a program never gets a right the kernel does not understand. A call without a note on rights in this overview is open to every program.

On top of that come the profile files uses-… in the program folder: they decide which libraries are built in (heap, interface, images, TLS …). Without uses-heap a program is in the real-time profile (-no-allocations).

The rights themselves are now listed with their modules: the 9 for every program in the App-API, the other 23 in the System-API (overview there).

ManifestManifest lines

CallWhat it doesShape call · time budget
Identity
name = helloProgram name (required).
id = de.softrobots.helloIdentity as a reverse domain (required since 8 Nov); the data folder is /data/<id>.
version = 1.0.3Version (required); a program is only replaced by a higher one.
api = 1App-API version the program was built for; a system that offers less does not start it.
Rights & documents
capabilities = system.log, ui.surfaceThe program's rights (table below).
opens = txt, mdDocument types the program opens (up to 16); required for double-click in Files and Files.Handle.openDocument.
takes = png, jpgDocument types the program accepts only when dragged onto its window; Files never offers it for a double click (Ask, 14 Nov 2026).
Start & display
dock = no newNever show in the Dock, not even while running (the file dialog chooser).
start = demand | updateDo not start at boot, only on request (or at the first start of a new system copy).
helper = videoServes only another program; not offered in lists.
title / category / iconDisplay name, group (system, productivity, media, robot, tools) and SVG symbol 24 × 24.
Memory
memory = 512Heap limit in MiB (16 … 2048, default 256); the line also makes it a guarantee.
stack = 4096Stack size in KiB (64 … 8192).
Real time & data
realtime = 1000 200 stopReal-time contract: period and budget in µs, behaviour on a missed deadline (log, stop, restart, stop-actuators).
record = samples 64 5 3600 [flight]A measurement series without system calls (Recorder); flight = flight recorder.
publish = detectionsA publication that others read without system calls (detection or arm ring).
subscribe = camera.detectionsUp to two publications of other programs, mapped read-only at start.
Network
connects = api.anthropic.comThe only hosts the program may reach.
listens = 443, 80TCP ports to listen on (with network.incoming, up to 8).

Profilesuses-…Profiles: which libraries are built in

CallWhat it doesShape call · time budget
Profiles (uses-… files)
(no file)System, Files, Channel, Net, Apps, Settings, TextLine, WallClock, FileType, Maths – real-time capable, without a heap.
uses-heapArrays, strings, classes; plus the sound library (WAV, FLAC, level, voice detection).
uses-uiSurface, Canvas, Views, Keyboard, InputField, UITheme, Chart, ScrollBar.
uses-imagePicture, PNG, JPEG, GIF, WebP, BMP, TIFF, PDF writing/reading, Matroska (needs uses-heap).
uses-archiveZIP reading/writing with WinZip AES-256, Deflate (needs uses-heap).
uses-tlsTLS 1.3 (SecureConnection), DNS over HTTPS, crypto, trust anchors.
uses-aiA cloud AI through its API (type Claude; key in Settings › Privacy) – needs uses-tls and uses-heap.
uses-video / uses-opusVP9 decoder / Opus decoder (needs uses-heap and uses-image).
uses-svg / uses-web / uses-sqlSVG renderer; browser code; SQL translator for databases (read-only).
uses-vision / uses-inferAprilTag, colour blobs, motion / int8 inference (detectors).
uses-qr / uses-httpserverQR code encoder / HTTP/1.1 server building blocks.
uses-reflex / uses-reflexrtReflex compiler and machine (Develop) / real-time runtime.
Example: manifest of a program with a window, its own files and the file dialog (apps/reader, apps/dialogcheck)
# Reader: shows PDF documents.
name = reader
id = de.softrobots.reader
title = Reader
category = productivity
icon = icon.svg
capabilities = system.log, ui.surface
kind = system
opens = pdf
start = demand
memory = 768
# Next to it in the program folder: uses-heap, uses-image, uses-svg, uses-ui

system · Information, time, log, real time, text

Information about the system, time and randomness are open to every program; the log needs system.log, processors and usage system.status. Power, setting the clock, reading the log and setting secrets are rights of system programs.

A real-time program writes realtime = <period µs> <budget µs> [log|stop|restart|stop-actuators] into its manifest. The kernel admits it only if the budget fits on the real-time core, and starts every period on time. Real-time programs have no heap, no files and no Settings (no uses-heap file); they call System.waitForNextPeriod() once per period. They exchange data without system calls: subscriptions (subscribe =), the arm ring, channels with receivePolling and measurement series (Recorder, record = …).

Without a heap you need fixed building blocks: TextLine is a line of fixed size (160 bytes), WallClock computes calendar times (Berlin), Maths (the maths library for every profile) is now under Libraries › maths.

Parts for system programs only: System-API › system.

Rights

RightMeaningShape call · time budget
system.logWrite lines to the system log.≤ 5 µssystem.log0x0002_0003
system.statusRead the system state: utilisation, processors, consumption of all programs.≤ 100 µsprograms.usage0x0006_000E

System callssystemModule 0x0002 · The robot itself: info, time, log, power, randomness, processors, worker threads; events start/stop.

CallRequest → answerRightTime budget · ID
system.infoInfoRequest → SystemInfonone≤ 5 µs0x0002_0001
system.nowNowRequest → Nownone≤ 1 µs0x0002_0002
system.logLogLine → Donesystem.log≤ 5 µs0x0002_0003
system.processorTimesInfoRequest → ProcessorTimessystem.status≤ 5 µs0x0002_0006
system.randomRandomRequest → RandomBytesnone≤ 5 µs0x0002_0009
system.processorProcessorQuery → Processorsystem.status≤ 5 µs0x0002_000B
system.bootTimesInfoRequest → BootTimessystem.status≤ 5 µs0x0002_000C
system.realtimeRealtimeQuery → RealtimeStatsnone≤ 2 µs0x0002_000D
system.startWorkerWorkerStart → WorkerStartednone≤ 1 ms0x0002_000E
system.start eventStartedReflex eventevent0x0002_0007
system.stop eventStoppingReflex eventevent0x0002_0008

System callsSystemCallprimitive system calls (enum SystemCall)

NameWhat it doesRightNumber
exitExit the programnone0
yieldGive up processor timenone1
sleepSleep (ns)none2
waitWait for window/servicenone3
periodWaitReal time: next periodnone4
memoryGrowGrow the heapnone5
workerWakeWake a worker threadnone6
workerExitEnd a worker threadnone7
channelNotifyChannel: wake the other sidechannels.ipc8
channelWaitChannel: waitchannels.ipc9
surfaceNotifyWindow: wake the servicenone11
shapeCallShape call: all modules belownone13

System callscoreModule 0x0001 · Shapes shared by all modules: problem, point, rotation, pose, pixel rectangle.

No calls – only shared shapes.

SwiftSystemInformation, log, time, flow, randomness

CallWhat it doesShape call · time budget
Information
System.info() -> SystemStatus?apiVersion, version, deviceName, uptime, wallClock, cpus, realtimeCPU, memoryTotal/Free, screenWidth/Height, emergencyStopped, dataAvailable, dataProtected, memoryLow, deviceKey, arm, address, hasAES new (AES/PMULL instructions), versionShown new (“0.15.0 · Build N”; version is “0.15.0+N”) …≤ 5 µssystem.info0x0002_0001
Example
if let info = System.info() { info.arm.forEachByte { if count < 16 { id[count] = $0; count += 1 } } }
from apps/actuators (shortened)
System.processor(_ index: Int) -> ProcessorInfo?Core, clock rate, temperature, name (system.status).≤ 5 µssystem.processor0x0002_000B
Example
var index = 0
while let cpu = System.processor(index) { var name = TextLine(); cpu.appendName(to: &name); index += 1 }
Pattern (short, not copied from a program)
System.cpuStatus() -> (cpus: Int, now: UInt64, idle: InlineArray<8, UInt64>)?Idle time per CPU (system.status).≤ 5 µssystem.processorTimes0x0002_0006
Example
if let status = System.cpuStatus() { /* status.idle[cpu], status.now */ }
from apps/activity (shortened)
System.bootMeasurements() -> InlineArray<20, UInt64?>?The kernel's measurements from this boot (Benchmark).≤ 5 µssystem.bootTimes0x0002_000C
Log
System.log(_ text: StaticString) -> Bool / .log(_ line: TextLine) -> BoolOne line into the system log (at most 160 bytes; system.log).≤ 5 µssystem.log0x0002_0003
Example
System.log("reader: no window")
from apps/reader (shortened)
System.log(_ text: UnsafeRawBufferPointer, level: LogLevel) -> BoolWith level .debug/.info/.warning/.error (Activity › Log).≤ 5 µssystem.log0x0002_0003
Time
System.time: UInt64 / System.now() -> Nowns since start / wall clock (ns since 1970), since start, time zone.≤ 1 µssystem.now0x0002_0002
Example
static var wall: Int64 { System.now().wall }
from apps/develop (shortened)
System.wallClock: UInt64Milliseconds since 1970 (0 while unknown).≤ 1 µssystem.now0x0002_0002
Flow
System.sleep(nanoseconds: UInt64)Sleep.sleep (system call 2)
Example
System.sleep(nanoseconds: 10_000_000)
from apps/dialogcheck (shortened)
System.yield()Give up processor time.yield (system call 1)
System.exit(_ code: UInt64) -> NeverExit the program.exit (system call 0)
Example
case .close: System.exit(0)
from sdk-apps/greeter (shortened)
Randomness
System.random<let n: Int>(_ buffer: inout InlineArray<n, UInt8>) -> BoolRandom bytes from the kernel's generator (keys, nonces).≤ 5 µssystem.random0x0002_0009
Example
var key = InlineArray<32, UInt8>(repeating: 0)
guard System.random(&key) else { return }
Pattern (short, not copied from a program)

SwiftSystemReal time

CallWhat it doesShape call · time budget
Period
System.waitForNextPeriod()The work of this period is done; returns at the start of the next one.periodWait (system call 4)
Example
System.waitForNextPeriod()   // at the end of every period
from apps/control (shortened)
System.time: UInt64Nanoseconds since the start.≤ 1 µssystem.now0x0002_0002
Statistics
System.realtimeStats(restartWorst: Bool = false) -> RealtimeStats?Periods, missed deadlines, worst and mean start latency (seconds), period; nil for normal programs.≤ 2 µssystem.realtime0x0002_000D
Example
if System.time >= nextReport, let stats = System.realtimeStats(restartWorst: true) { /* stats.missed, stats.worstLatency */ }
from apps/control (shortened)

SwiftRecorderMeasurement series without a system call

CallWhat it doesShape call · time budget
Recording
Recorder.attach() -> Recorder?staticThe program's recording; nil without a record = line.
Example
guard let recorder = Recorder.attach() else { return }   // needs record = … in the manifest
Pattern (short, not copied from a program)
Recorder.push(time: UInt64, _ data: Span<UInt8>) -> BoolAppend a record (time + up to recordSize − 8 bytes); false if the ring was full (counted).
Example
recorder.push(time: System.time, sample.span)
from apps/rtrecord (shortened)
State
Recorder.dropped / .recordSize / .flightDropped records, record size, flight recorder (overwrites the oldest; saved only on an emergency stop or a crash).

SwiftTextLineA line of fixed size

CallWhat it doesShape call · time budget
Creating
TextLine() / TextLine(_ text: StaticString)Empty or pre-filled line.
Appending
TextLine.append(_ text: StaticString) / .append(_ other: TextLine) / .append(byte: UInt8)Append.
TextLine.append(decimal value: UInt64) / .append(hex value: UInt64, minimumDigits: Int = 1)Append numbers.
Example
var line = TextLine("ipcping: ")
line.append(decimal: rounds)
line.append(" round trips")
from apps/ipcping (shortened)
Read
TextLine.count / .subscript(index:) / .forEachByte(_:) / .capacityRead.

SwiftWallClock · CivilTimeCalendar time

CallWhat it doesShape call · time budget
Converting
WallClock.civil(unixMilliseconds: Int64) -> CivilTimems since 1970 → year, month, day, hour, minute, second, millisecond.
Example
let local = WallClock.civil(unixMilliseconds: milliseconds + WallClock.berlinOffset(unixSeconds: milliseconds / 1000) * 1000)
from apps/files (shortened)
WallClock.berlinOffset(unixSeconds: Int64) -> Int64Offset of Berlin time (with daylight saving time).
WallClock.unixSeconds(_ time: CivilTime) -> Int64 / .days(year:month:day:)Reverse conversion.
Output
WallClock.appendDate(_ time: CivilTime, to line: inout TextLine) / .appendTime(_:to:)Append "2026-11-10" / "14:23:05".
Example
WallClock.appendDate(local, to: &line)
from apps/files (shortened)
Example: system information, settings, starting a program (apps/apicheck)
guard let info = System.info() else { fail("no system information"); return }
guard info.apiVersion == 1, info.version.count > 0, info.cpus >= 1 else { fail("system information looks wrong"); return }

let callcost: StaticString = "callcost"
_ = callcost.withUTF8Buffer { Programs.launch(Span(_unsafeElements: $0)) }
Example: 1 kHz control loop with a real-time contract (apps/control)
// manifest: realtime = 1000 100      (period 1000 µs, budget 100 µs; no uses-heap file)
@c(app_main)
func appMain() {
    var position: Int64 = 0, target: Int64 = 10_000, integral: Int64 = 0, previousError: Int64 = 0
    var nextReport = System.time + 5_000_000_000
    while true {
        let error = target - position
        integral += error
        let derivative = error - previousError
        previousError = error
        position += (error * 8 + integral / 64 + derivative * 2) / 256
        if System.time >= nextReport, let stats = System.realtimeStats(restartWorst: true) {
            nextReport += 5_000_000_000
            var line = TextLine("control: ")
            line.append(decimal: stats.missed)
            line.append(" missed, worst ")
            line.append(decimal: UInt64(stats.worstLatency * 1e9))
            line.append(" ns")
            System.log(line)
        }
        System.waitForNextPeriod()
    }
}
Example: recording measurements
// manifest: record = samples 64 5 3600     (name, record size, seconds in the ring, seconds on disk)
guard let recorder = Recorder.attach() else { return }
var record = InlineArray<56, UInt8>(repeating: 0)
// ... fill record
_ = recorder.push(time: System.time, record.span)
Example: building a line with a date
var line = TextLine("As of ")
let time = WallClock.civil(unixMilliseconds: Int64(System.wallClock))
WallClock.appendDate(time, to: &line)
line.append(" ")
WallClock.appendTime(time, to: &line)
line.append(", angle ")
line.append(decimal: UInt64(Maths.degrees(Maths.atan2(1, 1))))
System.log(line)
All 97 declarations of this part (from docs/api/app-api-1.txt)
CivilTime.var hour: Int, minute: Int, second: Int
CivilTime.var millisecond
CivilTime.var year: Int, month: Int, day: Int
ProcessorInfo.func appendName(to line: inout TextLine)
ProcessorInfo.var isEfficiency: Bool
ProcessorInfo.var isPerformance: Bool
ProcessorInfo.var kind
ProcessorInfo.var megahertz
ProcessorInfo.var midr: UInt64
ProcessorInfo.var temperature
Recorder.func push(time: UInt64, _ data: Span<UInt8>) -> Bool
Recorder.let flight: Bool
Recorder.let recordSize: Int
Recorder.static func attach() -> Recorder?
Recorder.var dropped: UInt32
ShapeCall.func element<E: ShapeValue>(_ list: ShapeSlice, _ index: Int, as: E.Type) -> E
ShapeCall.func resultBytes(_ slice: ShapeSlice, _ body: (UnsafeRawBufferPointer) -> Void)
ShapeCall.func resultEquals(_ slice: ShapeSlice, _ text: StaticString) -> Bool
ShapeCall.init()
ShapeCall.mutating func bytes(_ source: UnsafeRawBufferPointer) -> ShapeSlice
ShapeCall.mutating func send<Q: ShapeValue, R: ShapeValue>(_ id: UInt32, _ value: Q, as: R.Type) -> ShapeOutcome<R>
ShapeCall.mutating func send<Q: ShapeValue, R: ShapeValue>(_ id: UInt32, _ value: Q, as: R.Type,
ShapeCall.mutating func sendPatched<Q: ShapeValue, R: ShapeValue>(_ id: UInt32, _ value: Q, patchOffset: Int, byte: UInt8,
ShapeCall.mutating func text(_ bytes: StaticString) -> ShapeSlice
System.static func bootMeasurements() -> InlineArray<20, UInt64?>?
System.static func cpuStatus() -> (cpus: Int, now: UInt64, idle: InlineArray<8, UInt64>)?
System.static func exit(_ code: UInt64) -> Never
System.static func info() -> SystemStatus?
System.static func log(_ line: TextLine) -> Bool
System.static func log(_ text: StaticString) -> Bool
System.static func log(_ text: UnsafeRawBufferPointer, level: LogLevel) -> Bool
System.static func now() -> Now
System.static func processor(_ index: Int) -> ProcessorInfo?
System.static func random<let n: Int>(_ buffer: inout InlineArray<n, UInt8>) -> Bool
System.static func realtimeStats(restartWorst: Bool = false) -> RealtimeStats?
System.static func sleep(nanoseconds: UInt64)
System.static func waitForNextPeriod()
System.static func yield()
System.static var time: UInt64
System.static var wallClock: UInt64
SystemStatus.var address: UInt32
SystemStatus.var afterUpdate
SystemStatus.var apiVersion
SystemStatus.var arm
SystemStatus.var bootAnimation
SystemStatus.var connectsRestricted
SystemStatus.var cpus
SystemStatus.var dataAvailable
SystemStatus.var dataProtected
SystemStatus.var deviceKey
SystemStatus.var deviceName
SystemStatus.var emergencyStopped
SystemStatus.var hasAES
SystemStatus.var hasDotProduct
SystemStatus.var hasMatrixMultiply
SystemStatus.var heapPeak: UInt64
SystemStatus.var memoryFree: UInt64
SystemStatus.var memoryGuarantee: UInt64
SystemStatus.var memoryLow
SystemStatus.var memoryTotal: UInt64
SystemStatus.var publishing
SystemStatus.var realtimeCPU
SystemStatus.var recording
SystemStatus.var screenHeight
SystemStatus.var screenWidth
SystemStatus.var subscriptions
SystemStatus.var uptime: UInt64
SystemStatus.var version
SystemStatus.var versionShown: TextLine
SystemStatus.var wallClock: UInt64
TextLine.func forEachByte(_ body: (UInt8) -> Void)
TextLine.init()
TextLine.init(_ text: StaticString)
TextLine.mutating func append(_ other: TextLine)
TextLine.mutating func append(_ text: StaticString)
TextLine.mutating func append(byte: UInt8)
TextLine.mutating func append(decimal value: UInt64)
TextLine.mutating func append(hex value: UInt64, minimumDigits: Int = 1)
TextLine.private(set) var count
TextLine.static let capacity
TextLine.subscript(index: Int) -> UInt8
WallClock.static func appendDate(_ time: CivilTime, to line: inout TextLine)
WallClock.static func appendTime(_ time: CivilTime, to line: inout TextLine)
WallClock.static func berlinOffset(unixSeconds: Int64) -> Int64
WallClock.static func civil(unixMilliseconds: Int64) -> CivilTime
WallClock.static func days(year: Int, month: Int, day: Int) -> Int
WallClock.static func unixSeconds(_ time: CivilTime) -> Int64
enum ShapeOutcome<R: ShapeValue>
enum System
enum SystemCall: UInt64
enum WallClock
struct CivilTime: Equatable
struct ProcessorInfo
struct Recorder
struct ShapeCall
struct SystemStatus
struct TextLine

programs · The program itself, settings, other programs

The program itself: the document handed to it, its own settings, its own usage (with system.status). Starting, stopping and listing other programs, reading their crashes or building programs is for system programs only (programs.launch, programs.build).

Settings are small, private settings per program (key = value, at most 4 KiB), kept by the system in DATA – no file right needed.

Parts for system programs only: System-API › programs.

Rights

No right needed: the own document and the own settings are open to every program; usage needs system.status (module system).

System callsprogramsModule 0x0006 · The program itself and the others: document, Settings, secret, start/stop, lists, crashes, building.

CallRequest → answerRightTime budget · ID
programs.documentDocumentRequest → HandedDocumentnone≤ 5 µs0x0006_0001
programs.settingsSettingsRequest → SettingsDatanone≤ 200 µs0x0006_0002
programs.saveSettingsSettingsData → Donenone≤ 2 ms0x0006_0003
programs.ownSecretSettingsRequest → SecretDatanone≤ 2 ms0x0006_0006
programs.usageProgramListQuery → UsageListsystem.status≤ 100 µs0x0006_000E

SwiftProgramsThe handed-over document, usage

CallWhat it doesShape call · time budget
Document
Programs.document() -> (name: InlineArray<80, UInt8>, length: Int, generation: UInt64)?The document handed to this program; generation changes with every new one.≤ 5 µsprograms.document0x0006_0001
Example
guard let document = Programs.document(), document.generation != generation else { return false }
from apps/reader (shortened)
Lists
Programs.usage(at index: Int) -> Usage?Consumption: CPU time, memory, heap, windows, file and network traffic … (system.status).≤ 100 µsprograms.usage0x0006_000E
Example
while let usage = Programs.usage(at: index) { /* usage.cpuTime, usage.memory, usage.total */ index += 1 }
from apps/activity (shortened)
Programs.Usage.buddyStage: IntBuddy's memory stage of a program without a memory = line: 0 calm, 1 sniff, 2 growl, 3 bark (1/4, 1/2, 3/4 of its limit).programs.usage

SwiftSettingsOwn settings (without a file right)

CallWhat it doesShape call · time budget
Loading
Settings.load() -> Settings?staticThe settings saved last (empty the first time); nil while DATA is locked, and for real-time programs.≤ 200 µsprograms.settings0x0006_0002
Example
guard var settings = Settings.load() else { fail("settings could not be loaded"); return }
from apps/apicheck (shortened)
Read
Settings.value(_ key: StaticString) -> TextLine?Value of a key.
Example
let greeting = settings.value("greeting")   // TextLine?
from apps/apicheck (shortened)
Settings.number(_ key: StaticString) -> Int?Value as an integer.
Example
let runs = (settings.number("runs") ?? 0) + 1
from apps/apicheck (shortened)
Set
Settings.set(_ key: StaticString, _ value: TextLine) -> BoolSets a text; false if 4 KiB would be exceeded.
Example
settings.set("greeting", TextLine("hello robot"))
from apps/apicheck (shortened)
Settings.set(_ key: StaticString, number: Int) -> BoolSets a number.
Example
settings.set("runs", number: runs)
from apps/apicheck (shortened)
Save
Settings.save() -> BoolWrites the settings.≤ 2 msprograms.saveSettings0x0006_0003
Example
guard settings.save() else { fail("settings were not kept"); return }
from apps/apicheck (shortened)
Example: remembering settings (docs/api/README.md)
if var settings = Settings.load() {
    let starts = (settings.number("starts") ?? 0) + 1
    settings.set("starts", number: starts)
    settings.set("greeting", TextLine("hello robot"))
    _ = settings.save()
}
All 39 declarations of this part (from docs/api/app-api-1.txt)
Programs.Usage.var buddyStage: Int
Programs.Usage.var capabilities: UInt64
Programs.Usage.var channelWakeUps: UInt64
Programs.Usage.var cpu
Programs.Usage.var cpuTime: UInt64
Programs.Usage.var cushion: UInt64
Programs.Usage.var fileRead: UInt64
Programs.Usage.var fileWritten: UInt64
Programs.Usage.var guarantee: UInt64
Programs.Usage.var heap: UInt64
Programs.Usage.var heapLimit: UInt64
Programs.Usage.var heapPeak: UInt64
Programs.Usage.var kind
Programs.Usage.var memory: UInt64
Programs.Usage.var missed: UInt64
Programs.Usage.var name
Programs.Usage.var nameLength
Programs.Usage.var networkReceived: UInt64
Programs.Usage.var networkSent: UInt64
Programs.Usage.var pagedOut: UInt64
Programs.Usage.var period: UInt64
Programs.Usage.var realtime
Programs.Usage.var slot
Programs.Usage.var started: UInt64
Programs.Usage.var state
Programs.Usage.var systemCalls: UInt64
Programs.Usage.var total: UInt64
Programs.Usage.var windows: UInt64
Programs.static func document() -> (name: InlineArray<80, UInt8>, length: Int, generation: UInt64)?
Programs.static func usage(at index: Int) -> Usage?
Programs.struct Usage
Settings.func number(_ key: StaticString) -> Int?
Settings.func save() -> Bool
Settings.func value(_ key: StaticString) -> TextLine?
Settings.mutating func set(_ key: StaticString, _ value: TextLine) -> Bool
Settings.mutating func set(_ key: StaticString, number: Int) -> Bool
Settings.static func load() -> Settings?
enum Programs
struct Settings

files · Files and folders

With files.own every path starts in the program's own folder /data/<id> – nothing else exists. files.system sees the whole volume (/apps read-only, system/…, in the VM mac/…); files.mac adds the Mac folder to the program's own folder. Paths with “/”, “.” and “..” are rejected. Changes take effect when the file is closed; at most 16 KiB per system call. A program with opens = … gets its handed-over document with Files.Handle.openDocument without a file right, and a file chosen in the dialog with Files.Handle.open(grant, mode:).

Since 11 Nov the open file is called Files.Handle (renamings: Overview); Files, Files.Handle and FileError are in app-api-1.txt. Snapshots and “show in Files” need rights of system programs.

Parts for system programs only: System-API › files.

Rights

RightMeaningShape call · time budget
files.ownFiles in its own folder /data/<id>; nothing else exists.≤ 2 msfiles.open0x0003_0001

System callsfilesModule 0x0003 · The program's files, folders, volume and snapshots.

CallRequest → answerRightTime budget · ID
files.openOpenFile → FileOpenedfiles.own or files.system (+ files.mac for mac/, + system.log.read for crashes/, logs/)≤ 2 ms0x0003_0001
files.readFileRead → FileDatanone≤ 2 ms0x0003_0002
files.writeFileWrite → FileWrittennone≤ 2 ms0x0003_0003
files.closeFileRequest → Donenone≤ 5 ms0x0003_0004
files.listListFolder → FolderEntriesfiles.own or files.system (+ files.system for a snapshot)≤ 2 ms0x0003_0005
files.infoFileQuery → FileInfofiles.own or files.system (+ files.system for a snapshot)≤ 200 µs0x0003_0006
files.makeFolderFileQuery → Donefiles.own or files.system≤ 2 ms0x0003_0007
files.removeFileQuery → Donefiles.own or files.system≤ 2 ms0x0003_0008
files.renameRename → Donefiles.own or files.system≤ 2 ms0x0003_0009
files.volumeVolumeQuery → VolumeInfosystem.status or files.system or files.own≤ 50 µs0x0003_000B

SwiftFiles.HandleAn open file

CallWhat it doesShape call · time budget
Open
Files.Handle.open(_ path: Span<UInt8> | StaticString, mode: Mode) -> Result<Files.Handle, FileError>staticOpens a file; mode .read, .replace (create/truncate), .append, .update (read and write at any position).≤ 2 msfiles.open0x0003_0001
Example
guard case .success(let file) = Files.Handle.open("notes.txt", mode: .read) else { return }
from sdk-apps/notes (shortened)
Files.Handle.openDocument(mode: Mode) -> Result<Files.Handle, FileError>staticOpens the document handed over by Files (see Programs.document).≤ 2 msfiles.open0x0003_0001
Example
switch Files.Handle.openDocument(mode: .read) {
case .failure(let error): message = TextLine(error.text)
case .success(let file): read(file)
}
from apps/reader (shortened)
Files.Handle.open(_ grant: FileGrant, mode: Mode) -> Result<Files.Handle, FileError>static newOpens a file chosen in the file dialog.≤ 2 msfiles.open0x0003_0001
Read
Files.Handle.read(into buffer: inout MutableSpan<UInt8>) -> Result<Int, FileError>Reads the next bytes (at most 16 KiB); 0 at the end.≤ 2 msfiles.read0x0003_0002
Example
var chunk = InlineArray<1024, UInt8>(repeating: 0)
var span = chunk.mutableSpan
guard case .success(let count) = file.read(into: &span), count > 0 else { break }
from sdk-apps/notes (shortened)
Files.Handle.read(into buffer: inout MutableSpan<UInt8>, at offset: UInt64) -> Result<Int, FileError>Reads from any position.≤ 2 msfiles.read0x0003_0002
Example
guard case .success(let got) = file.read(into: &span, at: 0), got >= 44 else { return }   // WAV header
from apps/sound (shortened)
Write
Files.Handle.write(_ data: Span<UInt8>) -> FileError?Appends all bytes (in pieces of 16 KiB).≤ 2 msfiles.write0x0003_0003
Example
bytes.withUnsafeBufferPointer { buffer in _ = file.write(Span(_unsafeElements: buffer)) }
from sdk-apps/notes (shortened)
Files.Handle.write(_ data: Span<UInt8>, at offset: UInt64) -> FileError?Writes at a position (at most up to the size: no holes).≤ 2 msfiles.write0x0003_0003
Example
_ = pending.withUnsafeBufferPointer { handle.write(Span(_unsafeElements: $0), at: bytes) }
from apps/sound (shortened)
Close
Files.Handle.close() -> FileError?Closes and commits the changes.≤ 5 msfiles.close0x0003_0004
Example
_ = file.close()   // only now are the changes committed
from sdk-apps/about (shortened)
Constants
Files.Handle.chunk = 16384 / .handle: UInt64staticBytes per system call / number of the file.

SwiftFilesFolders, info and changes by path

CallWhat it doesShape call · time budget
Folders
Files.entry(in path: Span<UInt8>, at index: Int, snapshot: UInt64? = nil) -> Result<Entry?, FileError>staticThe index-th entry of a folder (optionally as in a snapshot); nil after the last one. Index 0 reads afresh.≤ 2 msfiles.list0x0003_0005
Example
var index = 0
while case .success(let entry?) = folder.withUnsafeBufferPointer({ Files.entry(in: Span(_unsafeElements: $0), at: index) }) {
    index += 1
}
from apps/testcamera (shortened)
Files.makeDirectory(_ path: Span<UInt8>) -> FileError?staticCreate a folder (empty path: the program's own folder).≤ 2 msfiles.makeFolder0x0003_0007
Example
_ = folder.withUTF8Buffer { Files.makeDirectory(Span(_unsafeElements: $0)) }
from apps/sound (shortened)
Files.Entry: isDirectory, size, modified, name, nameLengthA folder entry.
Info
Files.info(_ path: Span<UInt8> | StaticString, snapshot: UInt64? = nil) -> Result<(isDirectory: Bool, size: UInt64, modified: UInt64), FileError>staticFolder?, size (folder: total size), last change.≤ 200 µsfiles.info0x0003_0006
Example
guard case .success(let runs) = Files.info("runs.log") else { return fail("runs.log has no size") }
from apps/shapecheck (shortened)
Files.volume(system: Bool = false) -> InlineArray<5, UInt64>?staticDATA or system volume: block size, blocks, used, snapshots, generation.≤ 50 µsfiles.volume0x0003_000B
Example
if let data = Files.volume() { dataUsed = data[2] * data[0]; dataTotal = data[1] * data[0]; snapshots = data[3] }
from apps/activity (shortened)
Changing
Files.remove(_ path: Span<UInt8> | StaticString) -> FileError?staticDelete a file or an empty folder.≤ 2 msfiles.remove0x0003_0008
Example
if Files.remove("shapecheck-moved.txt") != nil { failed("remove") }
from apps/shapecheck (shortened)
Files.rename(_ path: Span<UInt8>, to newPath: Span<UInt8>, replacing: Bool) -> FileError?staticMove/rename; with replacing atomically over an existing file.≤ 2 msfiles.rename0x0003_0009
Example
let renamed = old.withUTF8Buffer { o in new.withUTF8Buffer { n in Files.rename(Span(_unsafeElements: o), to: Span(_unsafeElements: n)) } }
from apps/sharecheck (shortened)
Files.replace(_ path: Span<UInt8>, with data: Span<UInt8>) -> FileError?staticReplace the whole content atomically (first .new, then rename).≤ 2 msfiles.open + files.rename0x0003_0001
Example
_ = path.withUnsafeBufferPointer { p in bytes.withUnsafeBufferPointer { b in Files.replace(Span(_unsafeElements: p), with: Span(_unsafeElements: b)) } }
from apps/settings (shortened)

SwiftFileErrorErrors

CallWhat it doesShape call · time budget
FileError
FileError: refused, badArgument, notFound, exists, notADirectory, notEmpty, noSpace, ioError, isADirectory, tooManyOpen, …Why a file operation failed; locked = DATA still sealed, wrongContent = content does not match the extension.
FileError.text: StaticString / FileError.from(_ result: UInt64) -> FileError?Short English sentence for messages / error from a return value.

SwiftFileTypeDocument types

CallWhat it doesShape call · time budget
Document types
FileType.of(_ name: Span<UInt8>) -> FileTypestaticType by extension.
FileType.label: StaticString / .isText / .isDatabaseDisplay name and kind.
FileType.accepts(_ prefix: Span<UInt8>, complete: Bool) -> BoolDoes the start of the content match the type?
FileType.extensionRange / .validUTF8 / .namesSVGElement / .equal / .maxExtensionstaticHelpers for extensions and content.
Example: reading and writing an own file (sdk-apps/notes)
// manifest: capabilities = system.log, ui.surface, files.own   (+ uses-heap)
guard case .success(let file) = Files.Handle.open("notes.txt", mode: .read) else { return }
var bytes: [UInt8] = []
var chunk = InlineArray<1024, UInt8>(repeating: 0)
while true {
    var span = chunk.mutableSpan
    guard case .success(let count) = file.read(into: &span), count > 0 else { break }
    for index in 0..<count { bytes.append(chunk[index]) }
}
file.close()

guard case .success(let out) = Files.Handle.open("notes.txt", mode: .replace) else { return }
bytes.withUnsafeBufferPointer { buffer in _ = out.write(Span(_unsafeElements: buffer)) }
out.close()
Example: listing a folder (apps/testcamera)
var index = 0
while case .success(let entry?) = folder.withUnsafeBufferPointer({ Files.entry(in: Span(_unsafeElements: $0), at: index) }) {
    // entry.name[0..<entry.nameLength], entry.isDirectory, entry.size, entry.modified
    index += 1
}
Example: opening the handed-over document (apps/reader)
// manifest: opens = pdf   – no files right needed
guard let document = Programs.document(), document.generation != generation else { return false }
generation = document.generation
switch Files.Handle.openDocument(mode: .read) {
case .failure(let error): message = TextLine(error.text)
case .success(let file):  // ... read, file.close()
}
All 44 declarations of this part (from docs/api/app-api-1.txt)
FileError.static func from(_ result: UInt64) -> FileError?
FileError.var text: StaticString
FileType.func accepts(_ prefix: Span<UInt8>, complete: Bool) -> Bool
FileType.static func equal(_ name: Span<UInt8>, _ start: Int, _ end: Int, _ word: StaticString) -> Bool
FileType.static func extensionRange(_ name: Span<UInt8>) -> (start: Int, end: Int)?
FileType.static func namesSVGElement(_ bytes: Span<UInt8>) -> Bool
FileType.static func of(_ name: Span<UInt8>) -> FileType
FileType.static func validUTF8(_ bytes: Span<UInt8>, complete: Bool) -> Bool
FileType.static let maxExtension
FileType.var isDatabase: Bool
FileType.var isText: Bool
FileType.var label: StaticString
Files.Entry.var isDirectory
Files.Entry.var modified: UInt64
Files.Entry.var name
Files.Entry.var nameLength
Files.Entry.var size: UInt64
Files.Handle.enum Mode: UInt64
Files.Handle.func close() -> FileError?
Files.Handle.func read(into buffer: inout MutableSpan<UInt8>) -> Result<Int, FileError>
Files.Handle.func read(into buffer: inout MutableSpan<UInt8>, at offset: UInt64) -> Result<Int, FileError>
Files.Handle.func write(_ data: Span<UInt8>) -> FileError?
Files.Handle.func write(_ data: Span<UInt8>, at offset: UInt64) -> FileError?
Files.Handle.let handle: UInt64
Files.Handle.static func open(_ grant: FileGrant, mode: Mode) -> Result<Files.Handle, FileError>
Files.Handle.static func open(_ path: Span<UInt8>, mode: Mode) -> Result<Files.Handle, FileError>
Files.Handle.static func open(_ path: StaticString, mode: Mode) -> Result<Files.Handle, FileError>
Files.Handle.static func openDocument(mode: Mode) -> Result<Files.Handle, FileError>
Files.Handle.static let chunk
Files.static func entry(in path: Span<UInt8>, at index: Int, snapshot: UInt64? = nil) -> Result<Entry?, FileError>
Files.static func info(_ path: Span<UInt8>, snapshot: UInt64? = nil) -> Result<(isDirectory: Bool, size: UInt64, modified: UInt64), FileError>
Files.static func info(_ path: StaticString) -> Result<(isDirectory: Bool, size: UInt64, modified: UInt64), FileError>
Files.static func makeDirectory(_ path: Span<UInt8>) -> FileError?
Files.static func remove(_ path: Span<UInt8>) -> FileError?
Files.static func remove(_ path: StaticString) -> FileError?
Files.static func rename(_ path: Span<UInt8>, to newPath: Span<UInt8>) -> FileError?
Files.static func rename(_ path: Span<UInt8>, to newPath: Span<UInt8>, replacing: Bool) -> FileError?
Files.static func replace(_ path: Span<UInt8>, with data: Span<UInt8>) -> FileError?
Files.static func volume(system: Bool = false) -> InlineArray<5, UInt64>?
Files.struct Entry
Files.struct Handle
enum FileError: UInt64, Error
enum FileType: UInt8
enum Files

database · SOFTrobotsDB

Tables with typed fields, kept and checked by the kernel (module database). A program describes its tables as stored Shapes in data.shape; shapec --database generates Swift code from them (openDatabase, one type per table with insert, update, delete, set…, row and the fields). The kernel checks rules such as unique, ranges and references on every write; a write set applies completely or not at all. No heap: write sets, queries and pages keep their bytes inline (create them as global variables). The program's own databases live in its own folder (files.own); other databases can be written only with database.edit.

Since 11 Nov Database, Database.Write, Database.Query and Database.Page are in app-api-1.txt (renamings: Overview). The code generated from data.shape belongs to the program (own section below).

Parts for system programs only: System-API › database.

Rights

No right of its own: the own databases are in the own folder and need files.own (module files).

System callsdatabaseModule 0x0004 · SOFTrobotsDB: opening, writing and querying databases, reading measurement series.

CallRequest → answerRightTime budget · ID
database.openOpenDatabase → DatabaseOpenedfiles.own or files.system (+ database.edit to write foreign ones)≤ 2 ms0x0004_0001
database.writeTableWrite → Writtenfiles.own or files.system≤ 1 ms0x0004_0002
database.queryTableQuery → TablePagefiles.own or files.system≤ 5 ms0x0004_0003
database.describeDatabaseRequest → Descriptionfiles.own or files.system≤ 1 ms0x0004_0004
database.closeDatabaseRequest → Donefiles.own or files.system≤ 50 µs0x0004_0005
database.readSeriesSeriesRead → SeriesRecordsfiles.own or files.system≤ 5 ms0x0004_0006

SwiftDatabaseopening & closing

CallWhat it doesShape call · time budget
Opening & closing
Database.open(_ path: StaticString, schema: Span<UInt8>) -> Result<Database, DatabaseError>staticThe same with a compiled schema.≤ 2 msdatabase.open0x0004_0001
Database.open(_ path: Span<UInt8>) -> Result<Database, DatabaseError>staticOpens it as it is (tools such as Console and Database).≤ 2 msdatabase.open0x0004_0001
Example
guard case .success(let database) = path.withSpan({ Database.open($0) }) else { return false }
from apps/database (shortened)
Database.close()Close.≤ 50 µsdatabase.close0x0004_0005
Example
robot.close()
from apps/dbcheck (shortened)

SwiftDatabase · Database.Writewriting: a write set, all or nothing

CallWhat it doesShape call · time budget
Write
Database.write<let capacity: Int>(_ set: inout Database.Write<capacity>, soon: Bool = false) -> Result<Int, DatabaseError>Applies a write set (all or nothing); returns the number of inserted rows. soon: returns immediately, on disk within 10 ms.≤ 1 msdatabase.write0x0004_0002
Example
Joints.update(&set, id: 7)
Joints.setAngle(&set, 12_345)
guard case .success = robot.write(&set) else { return fail("updating joint 7 failed") }
from apps/dbcheck (shortened)
Creating a set
Database.Write.init() / .clear() / .isEmptyEmpty set.
Operations
Database.Write.insert(_ table: StaticString, id: UInt64 = 0) / .update(_:id:) / .delete(_:id:)Begin an operation (the generated code calls this for you).
Database.Write.set(_ field: Int, bytes: | bool: | int:size: | unsigned:size: | float: | double: | text:) / .setNull(_:)Field values of the current operation.
Result
Database.Write.insertedIDs / .insertedCountids of the inserted rows.

SwiftDatabase.Query · Database.Pagequerying: query, conditions, result page

CallWhat it doesShape call · time budget
Queries
Database.next(_ query: inout Database.Query<q>, into page: inout Database.Page<output, cursor>) -> BoolRuns a query or fetches the next page; false when finished or on error (page.error).≤ 5 msdatabase.query0x0004_0003
Example
page.reset()
while robot.next(&query, into: &page) || page.rowCount > 0 {
    for row in 0..<page.rowCount { let joint = Joints.row(&page, row); _ = joint.angle }
    if page.rowCount == 0 { break }
}
from apps/dbcheck (shortened)
Database.next(query: Span<UInt8>, aggregate: Bool, grouped: Bool, into page: …) -> BoolThe same for a query from SQL.translate (uses-sql).≤ 5 msdatabase.query0x0004_0003
Database.firstValue<R>(query: Span<UInt8>, _ body: (Span<UInt8>?) -> R) -> RFirst value of a translated query.≤ 5 msdatabase.query0x0004_0003
Table
Database.Query.init(_ table: StaticString)Query on a table.
Example
query = Database.Query(Joints.table)
from apps/dbcheck (shortened)
Filtering
Database.Query.where(_ condition: Condition) / .whereAny(_:_:_:_:)Condition (AND) / up to four OR conditions.
Example
query.where(Joints.angle >= -10_000)
query.where(Joints.angle < 10_000)
from apps/dbcheck (shortened)
Sorting & limiting
Database.Query.sorted(by field: Int, descending: Bool = false) / .sorted(by:via:descending:)Sort (also across a reference, join).
Example
query.sorted(by: Joints.angle.index, descending: true)
from apps/dbcheck (shortened)
Database.Query.limit(_ rows: Int) / .select(_ field: Int)At most n rows / only certain fields.
Example
query.limit(10)
from apps/dbcheck (shortened)
Aggregates
Database.Query.count(groupedBy:) / .sum / .minimum / .maximum / .average (_ field: Int, groupedBy: Int? = nil)Aggregates, optionally grouped.
Example
query.count(groupedBy: Joints.status.index)
// per group: page.aggregate(row).rows
from apps/dbcheck (shortened)
Fields & conditions
NumberField: == != < <= > >= Int64, .isNull, .isNotNull, .via(_ ref:)Conditions on number fields; via = field of the referenced table (join, at most two references).
Example
query.where(Joints.status.via(Moves.joint) == 1)   // Join across the reference
from apps/dbcheck (shortened)
FloatField: == != < <= > >= DoubleConditions on floating-point fields.
TextField: == StaticString, equals, startsWith, contains, before, afterConditions on text fields.
Page
Database.Page.init() / .reset()Create a page / clear it for a new query.
Database.Page.rowCount, .error, .plan, .indexRows, errors, chosen plan (index, range …).
Reading values
Database.Page.id(_ row: Int) / .number(_:_:signed:) / .float / .double / .text / .withBytes / .isNull / .valueRead the values of a row.
Database.Page.aggregate(_ row: Int) -> (rows: UInt64, value: Int64?) / .groupNumber / .withGroupBytesResult of an aggregate or of a group.
Example
for row in 0..<page.rowCount { total += page.aggregate(row).rows }
from apps/dbcheck (shortened)

SwiftDatabase · Series · DatabaseErrordescribing, series, errors

CallWhat it doesShape call · time budget
Description
Database.describe(into buffer: inout MutableSpan<UInt8>) -> Result<Int, DatabaseError>Tables, fields and indexes.≤ 1 msdatabase.describe0x0004_0004
Measurement series
Series.info(_ path: Span<UInt8>) -> Result<Info, FileError>What a measurement series holds: record size, records, first/last time.≤ 5 msdatabase.readSeries0x0004_0006
Series.read(_ path: Span<UInt8>, from: UInt64, to: UInt64, …)Records of a time range (flight recorder, Recorder).≤ 5 msdatabase.readSeries0x0004_0006
Errors
DatabaseError: .system(FileError), .rule(DatabaseRule, operation:, field:)System error or violated rule (duplicate, outOfRange, badReference …).
Example
guard case .failure(.rule(.duplicate, operation: 0, field: 1)) = robot.write(&set) else { return fail("a duplicate name was accepted") }
from apps/dbcheck (shortened)

SwiftTables from your data.shapegenerated per program by the tool, not in app-api-1.txt

A program describes its tables as stored shapes in data.shape. At build time shapec --database turns them into Swift code that exists only in this program: the compiled schema, openDatabase(_:) and per table a type <Table> with typed fields. This code only calls the declarations above (Database.open(_:schema:), Database.Write, Database.Page); it belongs to the program, not to the App-API, and is therefore in neither list. The names in angle brackets below depend on your data.shape (example apps/dbcheck: tables Joints and Moves).

CallWhat it doesShape call · time budget
Opening
openDatabase(_ path: StaticString) -> Result<Database, DatabaseError>Generated by the generator: opens/creates and aligns the tables with the schema (fields added, renamed, removed – without rewriting rows).≤ 2 msdatabase.open0x0004_0001
Example
guard case .success(let robot) = openDatabase("robot.db") else { return fail("cannot open robot.db") }
from apps/dbcheck (shortened)
Per table
dataSchema: InlineArray<n, UInt8>The compiled schema of your tables; openDatabase passes it to Database.open(_:schema:).
<Table>.table: StaticStringThe table name for Database.Query(<Table>.table). <Table> is the name from stored as … with a capital (joints → Joints).
<Table>.<field>: NumberField | FloatField | TextFieldOne constant per field for conditions and sorting: Joints.angle > 90_000, Joints.angle.index.
<Table>.insert(_ set: inout Database.Write<n>, <required fields>)A new row with every required field (no default) as a parameter; set the others right after with set….
<Table>.update(_ set: inout Database.Write<n>, id: UInt64) / <Table>.delete(_:id:)Change row id (fields right after with set…) or delete it.
<Table>.set<Field>(_ set: inout Database.Write<n>, _ value:) / <Table>.clear<Field>(_:)Sets one field of the current operation; clear… only for optional fields (sets null).
<Table>.Row / <Table>.row(_ page: inout Database.Page<o, c>, _ row: Int) -> RowA row of a result page with typed fields (queries without select); enumerations come as their own type.
Example: describing tables (apps/dbcheck/data.shape)
enum JointStatus { ok @0, warning @1, fault @2 }

shape Joint stored as joints {
    name: Text(32) unique
    angle: Int32 in -180000 ... 180000
    current: Float32?
    status: JointStatus = .ok
    index status, angle
    index angle
}

shape Move stored as moves {
    joint: Joint
    at: Time
    target: Int32
}
Example: writing, rules, query via index, groups (apps/dbcheck)
nonisolated(unsafe) var set = Database.Write<65536>()
nonisolated(unsafe) var query = Database.Query<512>(Joints.table)
nonisolated(unsafe) var page = Database.Page<16384, 1024>()

guard case .success(let robot) = openDatabase("robot.db") else { return fail("cannot open robot.db") }

Joints.insert(&set, name: name.span.extracting(0..<length), angle: 45_000)
Joints.setStatus(&set, .warning)
guard case .success(1) = robot.write(&set) else { return fail("insert failed") }

// The kernel checks the rules:
guard case .failure(.rule(.duplicate, operation: 0, field: 1)) = robot.write(&set) else { ... }

// The ten largest angles above 90°, backwards via the index
query = Database.Query(Joints.table)
query.where(Joints.angle > 90_000)
query.sorted(by: Joints.angle.index, descending: true)
query.limit(10)
page.reset()
while robot.next(&query, into: &page) || page.rowCount > 0 {
    for row in 0..<page.rowCount { let joint = Joints.row(&page, row); _ = joint.angle }
    if page.rowCount == 0 { break }
}

// Join: movements whose joint has the status warning
query = Database.Query(Moves.table)
query.where(Joints.status.via(Moves.joint) == 1)
query.count()
All 134 declarations of this part (from docs/api/app-api-1.txt)
Database.Page.init()
Database.Page.internal(set) var error: DatabaseError?
Database.Page.internal(set) var index: UInt8
Database.Page.internal(set) var plan: UInt8
Database.Page.internal(set) var rowCount
Database.Page.mutating func aggregate(_ row: Int) -> (rows: UInt64, value: Int64?)
Database.Page.mutating func double(_ row: Int, _ field: Int) -> Double
Database.Page.mutating func float(_ row: Int, _ field: Int) -> Float
Database.Page.mutating func groupNumber(_ row: Int) -> Int64
Database.Page.mutating func id(_ row: Int) -> UInt64
Database.Page.mutating func isNull(_ row: Int, _ field: Int) -> Bool
Database.Page.mutating func number(_ row: Int, _ field: Int, signed: Bool = true) -> Int64
Database.Page.mutating func reset()
Database.Page.mutating func text(_ row: Int, _ field: Int) -> TextLine
Database.Page.mutating func value(_ row: Int, _ field: Int) -> (start: Int, length: Int)?
Database.Page.mutating func withBytes<R>(_ row: Int, _ field: Int, _ body: (Span<UInt8>) -> R) -> R?
Database.Page.mutating func withGroupBytes<R>(_ row: Int, _ body: (Span<UInt8>) -> R) -> R?
Database.Query.init(_ table: StaticString)
Database.Query.mutating func `where`(_ condition: Condition)
Database.Query.mutating func average(_ field: Int, groupedBy group: Int? = nil)
Database.Query.mutating func count(groupedBy field: Int? = nil)
Database.Query.mutating func limit(_ rows: Int)
Database.Query.mutating func maximum(_ field: Int, groupedBy group: Int? = nil)
Database.Query.mutating func minimum(_ field: Int, groupedBy group: Int? = nil)
Database.Query.mutating func select(_ field: Int)
Database.Query.mutating func sorted(by field: Int, descending: Bool = false)
Database.Query.mutating func sorted(by field: Int, via ref: NumberField, descending: Bool = false)
Database.Query.mutating func sum(_ field: Int, groupedBy group: Int? = nil)
Database.Query.mutating func whereAny(_ first: Condition, _ second: Condition, _ third: Condition? = nil, _ fourth: Condition? = nil)
Database.Write.init()
Database.Write.internal(set) var insertedCount
Database.Write.internal(set) var insertedIDs
Database.Write.mutating func clear()
Database.Write.mutating func delete(_ table: StaticString, id: UInt64)
Database.Write.mutating func delete(table name: Span<UInt8>, id: UInt64)
Database.Write.mutating func insert(_ table: StaticString, id: UInt64 = 0)
Database.Write.mutating func insert(table name: Span<UInt8>, id: UInt64 = 0)
Database.Write.mutating func set(_ field: Int, bool value: Bool)
Database.Write.mutating func set(_ field: Int, bytes value: Span<UInt8>)
Database.Write.mutating func set(_ field: Int, double value: Double)
Database.Write.mutating func set(_ field: Int, float value: Float)
Database.Write.mutating func set(_ field: Int, int value: Int64, size: Int)
Database.Write.mutating func set(_ field: Int, text line: TextLine)
Database.Write.mutating func set(_ field: Int, text value: StaticString)
Database.Write.mutating func set(_ field: Int, unsigned value: UInt64, size: Int)
Database.Write.mutating func setNull(_ field: Int)
Database.Write.mutating func update(_ table: StaticString, id: UInt64)
Database.Write.mutating func update(table name: Span<UInt8>, id: UInt64)
Database.Write.var isEmpty: Bool
Database.func close()
Database.func describe(into buffer: inout MutableSpan<UInt8>) -> Result<Int, DatabaseError>
Database.func firstValue<R>(query: Span<UInt8>, _ body: (Span<UInt8>?) -> R) -> R
Database.func next<let output: Int, let cursor: Int>(query queryBytes: Span<UInt8>, aggregate: Bool, grouped: Bool,
Database.func next<let q: Int, let output: Int, let cursor: Int>(_ query: inout Database.Query<q>, into page: inout Database.Page<output, cursor>) -> Bool
Database.func write<let capacity: Int>(_ set: inout Database.Write<capacity>, soon: Bool
Database.let handle: DatabaseHandle
Database.static func open(_ path: Span<UInt8>) -> Result<Database, DatabaseError>
Database.static func open(_ path: StaticString, schema: Span<UInt8>) -> Result<Database, DatabaseError>
Database.struct Page<let output: Int, let cursor: Int>
Database.struct Query<let capacity: Int>
Database.struct Write<let capacity: Int>
DatabaseBuffer.init()
DatabaseBuffer.mutating func withBytes<R>(_ body: (Span<UInt8>) -> R) -> R
DatabaseBuffer.mutating func withRoom<R>(_ body: (inout MutableSpan<UInt8>) -> R) -> R
DatabaseBuffer.subscript(index: Int) -> UInt8
DatabaseBuffer.var count
DatabaseRule.var text: StaticString
FieldRef.func via(_ ref: NumberField) -> FieldRef
FieldRef.init(_ index: Int)
FieldRef.internal(set) var joinedThrough
FieldRef.let index: Int
FieldRef.var isNotNull: Condition
FieldRef.var isNull: Condition
FloatField.func via(_ ref: NumberField) -> FloatField
FloatField.init(_ index: Int, double: Bool)
FloatField.internal(set) var joinedThrough
FloatField.let double: Bool
FloatField.let index: Int
FloatField.static func != (field: FloatField, value: Double) -> Condition
FloatField.static func < (field: FloatField, value: Double) -> Condition
FloatField.static func <= (field: FloatField, value: Double) -> Condition
FloatField.static func == (field: FloatField, value: Double) -> Condition
FloatField.static func > (field: FloatField, value: Double) -> Condition
FloatField.static func >= (field: FloatField, value: Double) -> Condition
FloatField.var isNotNull: Condition
FloatField.var isNull: Condition
FloatField.var ref: FieldRef
NumberField.func via(_ ref: NumberField) -> NumberField
NumberField.init(_ index: Int, size: Int, signed: Bool)
NumberField.internal(set) var joinedThrough
NumberField.let index: Int
NumberField.let signed: Bool
NumberField.let size: Int
NumberField.static func != (field: NumberField, value: Int64) -> Condition
NumberField.static func < (field: NumberField, value: Int64) -> Condition
NumberField.static func <= (field: NumberField, value: Int64) -> Condition
NumberField.static func == (field: NumberField, value: Int64) -> Condition
NumberField.static func > (field: NumberField, value: Int64) -> Condition
NumberField.static func >= (field: NumberField, value: Int64) -> Condition
NumberField.var isNotNull: Condition
NumberField.var isNull: Condition
NumberField.var ref: FieldRef
Series.Info.var first: UInt64
Series.Info.var last: UInt64
Series.Info.var recordSize
Series.Info.var records: UInt64
Series.static func info(_ path: Span<UInt8>) -> Result<Info, FileError>
Series.static func read(_ path: Span<UInt8>, from: UInt64, to: UInt64,
Series.struct Info
TextField.func after(_ value: StaticString) -> Condition
TextField.func before(_ value: StaticString) -> Condition
TextField.func contains(_ value: Span<UInt8>) -> Condition
TextField.func contains(_ value: StaticString) -> Condition
TextField.func equals(_ value: Span<UInt8>) -> Condition
TextField.func startsWith(_ value: Span<UInt8>) -> Condition
TextField.func startsWith(_ value: StaticString) -> Condition
TextField.func via(_ ref: NumberField) -> TextField
TextField.init(_ index: Int)
TextField.internal(set) var joinedThrough
TextField.let index: Int
TextField.static func == (field: TextField, value: StaticString) -> Condition
TextField.var isNotNull: Condition
TextField.var isNull: Condition
TextField.var ref: FieldRef
enum DatabaseError: Error, Equatable
enum DatabaseRule: UInt8, Sendable
enum Series
struct Condition
struct Database
struct DatabaseBuffer<let capacity: Int>
struct FieldRef: Sendable
struct FloatField: Sendable
struct NumberField: Sendable
struct TextField: Sendable

network · Network, TLS, cloud AI

Outgoing with network.outgoing: TCP (IPv4/IPv6) and UDP to exactly one server. A line connects = host, host limits the reachable hosts; names are then resolved by the kernel only. Incoming with network.incoming and listens = 443, 80 (only the program Server; never during an emergency stop) – there is no public web server; the gate is in the home network plus WireGuard.

TLS 1.3 comes with uses-tls as a library (SecureConnection: certificate chain checked against the system's trust anchors, DNS over HTTPS, up to 4 connections). Since 11 Nov 2026 TLS reads up to 8 KiB per system call, decrypts AES-128/256-GCM with the AES/PMULL instructions and ChaCha20 with NEON (checked against the software at the first connection). With uses-ai a program asks a cloud AI through its API (type Claude); the API key is the program's secret and is entered in Settings › Privacy.

Claude (uses-ai) is in app-api-1.txt; SecureConnection (uses-tls) is not declared public and is therefore in neither list.

Parts for system programs only: System-API › network.

Rights

RightMeaningShape call · time budget
network.outgoingOutgoing TCP connections and UDP; restricted by connects =.≤ 5 snetwork.connect0x0005_0004

System callsnetworkModule 0x0005 · Network: names, TCP, UDP, listening (get/post planned).

CallRequest → answerRightTime budget · ID
network.getGet → Responsenetwork.outgoing · not served by the kernel yet≤ 2 s0x0005_0001
network.postPost → Responsenetwork.outgoing · not served by the kernel yet≤ 2 s0x0005_0002
network.resolveResolve → Resolvednetwork.outgoing≤ 6 s0x0005_0003
network.connectConnect → Connectednetwork.outgoing≤ 5 s0x0005_0004
network.sendSocketSend → Sentnetwork.outgoing or network.incoming≤ 1 s0x0005_0005
network.receiveSocketReceive → SocketDatanetwork.outgoing or network.incoming≤ 10 s0x0005_0006
network.closeSocketRequest → Donenetwork.outgoing or network.incoming≤ 50 µs0x0005_0007
network.openDatagramDatagramOpen → DatagramOpenednetwork.outgoing≤ 5 s0x0005_0008
network.sendDatagramDatagramSend → Donenetwork.outgoing≤ 1 s0x0005_0009
network.receiveDatagramDatagramReceive → DatagramDatanetwork.outgoing≤ 10 s0x0005_000A
network.closeDatagramDatagramRequest → Donenetwork.outgoing≤ 50 µs0x0005_000B

System callsaskModule 0x0050 · Asking a cloud AI (Reflex scripts with the key from Settings).

CallRequest → answerRightTime budget · ID
ask.claudeQuestion → Answernone · not served by the kernel yetno budget0x0050_0001

SwiftNetwork.ConnectionA TCP connection

CallWhat it doesShape call · time budget
Resolving names
Network.Connection.resolve(_ name: StaticString | Span<UInt8>) -> UInt32?staticIPv4 address of a host name (the network's DNS).≤ 6 snetwork.resolve0x0005_0003
Example
guard let address = Network.Connection.resolve("example.com") else { return }
Pattern (short, not copied from a program)
Network.Connection.resolveIPv6(_ name: Span<UInt8>) -> InlineArray<16, UInt8>?staticIPv6 address (AAAA).≤ 6 snetwork.resolve0x0005_0003
Connecting
Network.Connection.init?(address: UInt32, port: UInt16)Open a connection (the handshake runs in the background).≤ 5 snetwork.connect0x0005_0004
Example
guard let connection = Network.Connection(address: address, port: 80) else { return }
Pattern (short, not copied from a program)
Network.Connection.init?(ipv6 address: InlineArray<16, UInt8>, port: UInt16)Over IPv6.≤ 5 snetwork.connect0x0005_0004
Sending & receiving
Network.Connection.send(_ data: Span<UInt8>) -> BoolSend all bytes (waits when the buffer is full).≤ 1 snetwork.send0x0005_0005
Network.Connection.receive(into buffer: inout InlineArray<1024, UInt8>, timeout: UInt64 = 1_000_000_000) -> Int?Receive up to 1 KiB; 0 = nothing yet, nil = the other side has closed.≤ 10 snetwork.receive0x0005_0006
Example
var buffer = InlineArray<1024, UInt8>(repeating: 0)
while let count = connection.receive(into: &buffer, timeout: 2_000_000_000), count > 0 { /* buffer[0..<count] */ }
Pattern (short, not copied from a program)
Close
Network.Connection.close()Close the sending direction; the system releases the connection when TCP is done.≤ 50 µsnetwork.close0x0005_0007
Sending & receiving
Network.Connection.receive(area: UnsafeMutableRawBufferPointer, timeout: UInt64 = 1_000_000_000) -> Range<Int>? newReceive up to 8 KiB straight into area (at least 8 KiB + 64 bytes; the bytes stay where the system put them). Result: where the bytes are in area (empty = nothing yet), nil = the other side has closed. Reads eight times less often than the 1 KiB version and copies nothing in the program.≤ 10 snetwork.receive0x0005_0006
Example
let area = UnsafeMutableRawBufferPointer.allocate(byteCount: 8192 + 64, alignment: 16)
while let range = connection.receive(area: area, timeout: 2_000_000_000), !range.isEmpty { /* area[range] */ }
Pattern (short, not copied from a program)

SwiftNetwork.DatagramUDP to a server

CallWhat it doesShape call · time budget
Open
Network.Datagram.init?(address: UInt32, port: UInt16)Connected UDP socket: datagrams from elsewhere never arrive.≤ 5 snetwork.openDatagram0x0005_0008
Sending & receiving
Network.Datagram.send(_ data: Span<UInt8>) -> BoolOne datagram (at most 1,472 bytes).≤ 1 snetwork.sendDatagram0x0005_0009
Network.Datagram.receive(into buffer: inout InlineArray<512, UInt8>, timeout: UInt64) -> Int?Wait for a datagram; 0 if none arrived.≤ 10 snetwork.receiveDatagram0x0005_000A
Close
Network.Datagram.close()Close.≤ 50 µsnetwork.closeDatagram0x0005_000B

SwiftSecureConnectionTLS 1.3 (uses-tls)

CallWhat it doesShape call · time budget
Connecting
SecureConnection.open(_ host: StaticString, port: UInt16 = 443, alpn: StaticString = "", timeout: UInt64 = 10_000_000_000) -> SecureConnection?staticResolve (DNS over HTTPS), connect, handshake with certificate check.≤ 5 snetwork.connect0x0005_0004
Example
guard let secure = SecureConnection.open("example.com") else { return }
from apps/https (shortened)
SecureConnection.open(host: Span<UInt8>, port: UInt16 = 443, timeout: UInt64 = 10_000_000_000) -> SecureConnection?staticFor a host known only at run time (browser).≤ 5 snetwork.connect0x0005_0004
SecureConnection.open(address: UInt32, serverName host: StaticString, port: UInt16 = 443, alpn: StaticString = "", timeout: UInt64 = 10_000_000_000, dns: Bool = false) -> SecureConnection?staticTo a known address.≤ 5 snetwork.connect0x0005_0004
Sending & receiving
SecureConnection.send(_ data: Span<UInt8>) -> BoolEncrypt and send.≤ 1 snetwork.send0x0005_0005
SecureConnection.receive(into out: inout InlineArray<1024, UInt8>, timeout: UInt64 = 5_000_000_000) -> Int?Decrypted bytes; 0 = nothing yet, nil = closed. Since 11 Nov it reads up to 8 KiB per system call internally.≤ 10 snetwork.receive0x0005_0006
Example
while let count = secure.receive(into: &buffer) { if count == 0 { break }; total += count }
from apps/https (shortened)
Close
SecureConnection.close()Send close_notify and close.≤ 50 µsnetwork.close0x0005_0007
Diagnostics
SecureConnection.lastError / .handshakeTime / .handshakes / .lastSlotstaticWhy open failed, duration of the last handshake.

SwiftClaudeOne question to a cloud AI through its API (uses-ai)

CallWhat it doesShape call · time budget
One question to a cloud AI
Claude.ask(_ question: String, jpeg: [UInt8]? = nil, model: String = defaultModel, maxTokens: Int = 700) -> AnswerAsks (optionally with an image) and waits for the whole answer (at most one minute). Camera images only if the owner has allowed it.≤ 5 snetwork.connect …0x0005_0004
Example
let result = Claude.ask(String(decoding: question, as: UTF8.self), jpeg: jpeg)
from apps/ask (shortened)
Claude.Answer: text, problem, milliseconds, incompleteAnswer text or reason, duration.
Example: HTTPS fetch with TLS 1.3 (apps/https)
// manifest: capabilities = system.log, network.outgoing   (+ uses-tls)
guard let secure = SecureConnection.open("example.com") else {
    var line = TextLine("https: ")
    line.append(SecureConnection.lastError)
    System.log(line)
    return
}
let request: StaticString = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"
let sent = request.withUTF8Buffer { bytes in secure.send(Span(_unsafeElements: bytes)) }
guard sent else { System.log("https: sending failed"); return }
var buffer = InlineArray<1024, UInt8>(repeating: 0)
while let count = secure.receive(into: &buffer) {
    if count == 0 { break }
    // ... buffer[0..<count]
}
secure.close()
Example: plain-text TCP (pattern after userland/Net.swift)
guard let address = Network.Connection.resolve("example.com"),
      let connection = Network.Connection(address: address, port: 80) else { return }
let request: StaticString = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"
_ = request.withUTF8Buffer { connection.send(Span(_unsafeElements: $0)) }
var buffer = InlineArray<1024, UInt8>(repeating: 0)
while let count = connection.receive(into: &buffer, timeout: 2_000_000_000), count > 0 {
    // ...
}
connection.close()
Example: asking the cloud AI (apps/ask)
// manifest: capabilities = …, network.outgoing, camera.use
//           connects = api.anthropic.com      (+ uses-ai, uses-tls, uses-heap)
let result = Claude.ask(String(decoding: question, as: UTF8.self), jpeg: jpeg)
if let problem = result.problem {
    // problem: why there is no answer (no key, no network …)
} else {
    answer = Array(result.text.utf8)
}
All 27 declarations of this part (from docs/api/app-api-1.txt)
Claude.Answer.var incomplete
Claude.Answer.var milliseconds: UInt64
Claude.Answer.var problem: String?
Claude.Answer.var text
Claude.static func ask(_ question: String, jpeg: [UInt8]? = nil, model: String = defaultModel, maxTokens: Int = 700) -> Answer
Claude.static let defaultModel
Claude.static let host
Claude.struct Answer
Network.Connection.func close()
Network.Connection.func receive(area: UnsafeMutableRawBufferPointer, timeout: UInt64 = 1_000_000_000) -> Range<Int>?
Network.Connection.func receive(into buffer: inout InlineArray<1024, UInt8>, timeout: UInt64 = 1_000_000_000) -> Int?
Network.Connection.func send(_ data: Span<UInt8>) -> Bool
Network.Connection.init?(address: UInt32, port: UInt16)
Network.Connection.init?(ipv6 address: InlineArray<16, UInt8>, port: UInt16)
Network.Connection.let handle: SocketHandle
Network.Connection.static func resolve(_ name: Span<UInt8>) -> UInt32?
Network.Connection.static func resolve(_ name: StaticString) -> UInt32?
Network.Connection.static func resolveIPv6(_ name: Span<UInt8>) -> InlineArray<16, UInt8>?
Network.Datagram.func close()
Network.Datagram.func receive(into buffer: inout InlineArray<512, UInt8>, timeout: UInt64) -> Int?
Network.Datagram.func send(_ data: Span<UInt8>) -> Bool
Network.Datagram.init?(address: UInt32, port: UInt16)
Network.Datagram.let handle: DatagramHandle
Network.struct Connection
Network.struct Datagram
enum Claude
enum Network

ui · Windows, drawing, views, input, menus, progress

A window is a Surface: pixel memory and a message ring that the kernel maps into the program and into the display service. The system draws the frame, title and menu bar; the program draws its content with Canvas or describes it with views (VStack, Text, Button …); colours come from UITheme. The event loop: nextEvent() until nil, draw, present, wait. Every switch over SurfaceEvent needs default: (new cases will be added).

The program describes its menus; the system draws them in the menu bar (index 0 … 5) and in the context menu (SurfaceMessage.contextMenuIndex). Chosen items arrive as .menu(id:). For File and Edit there are standard menus with fixed ids and shortcuts (⌘N ⌘O ⌘S ⇧⌘S ⌘E; ⌘Z ⌘X ⌘C ⌘V ⌘A).

New (10 Nov). A program says what it is doing and how far along it is (“how much of how much”); the system draws it the same way everywhere: a capsule in the window title with a bar, percentage and time remaining, and a thin bar on the Dock tile; a click shows details and – if allowed – Cancel. Buddy reports when a long task has finished while the window is not in front. At most 4 tasks per window; updates go out at most 10 times per second. No right of its own needed (the window is enough, ui.surface).

Parts for system programs only: System-API › ui.

Rights

RightMeaningShape call · time budget
ui.surfaceShow windows (up to three).≤ 5 msdisplay.createSurface0x0011_0004

System callsdisplayModule 0x0011 · Screen and window memory (ui.surface, ui.display).

CallRequest → answerRightTime budget · ID
display.createSurfaceDisplayQuery → SurfaceMemoryui.surface≤ 5 ms0x0011_0004

System callsscreenModule 0x0010 · Windows as a description of views (Reflex).

CallRequest → answerRightTime budget · ID
screen.showScreenView → Donenone · not served by the kernel yet≤ 200 µs0x0010_0001
screen.ScreenView effectReflex effecteffect0x0010_0002
screen.pressed eventPressedReflex eventevent0x0010_0003
screen.slid eventSlidReflex eventevent0x0010_0004
screen.key eventKeyPressReflex eventevent0x0010_0005

SwiftSurfaceThe program's windows

CallWhat it doesShape call · time budget
Creating a window
Surface.create(timeout: UInt64 = 10_000_000_000) -> Surface?staticRequests a window (up to three per program), waiting for the display service if necessary.≤ 5 msdisplay.createSurface0x0011_0004
Example
guard var surface = Surface.create() else { System.log("text: no window"); return }
from apps/text (shortened)
Surface.requestSize(width: Int, height: Int)Desired content size (the user can change it).
Example
surface.requestSize(width: 1120, height: 720)
from apps/sound (shortened)
Surface.setTitle(_ text: TextLine)Name above the window.
Example
window.setTitle(TextLine("Web"))
from apps/web (shortened)
Surface.destroy()Closes one of several windows (with only one: simply exit).
Example
guard var second = Surface.create() else { return }
// ... later, on .close of this window:
second.destroy()
Pattern (short, not copied from a program)
Fetching events
Surface.nextEvent() -> SurfaceEvent?Next message from the service, nil if none is waiting; .configure adjusts canvas.
Example
while let event = surface.nextEvent() {
    switch event {
    case .configure: dirty = true
    case .close: System.exit(0)
    default: break
    }
}
from sdk-apps/greeter (shortened)
Surface.wait(timeout: UInt64)Sleeps until the service sends something or timeout ns pass.wait (system call 3)
Example
surface.wait(timeout: 500_000_000)   // 0.5 s or until an event arrives
from apps/reader (shortened)
Drawing & showing
Surface.canvas: CanvasThe drawing surface the service has provided (empty until the first configure).
Surface.beginDrawing()Call before a frame: the service copies the window only after present (no tearing).
Example
surface.beginDrawing()
draw(surface.canvas)
surface.presentChanges()
from apps/reader (shortened)
Surface.present(_ rect: Rect) -> BoolShows the changed rectangle; false if the ring stayed full (show again later).
Example
surface.present(Rect(x: 0, y: 0, width: surface.canvas.width, height: surface.canvas.height))
from sdk-apps/greeter (shortened)
Surface.presentChanges()Shows all tiles changed since beginDrawing (DamageTracker).
Pointer, foreground, dragging
Surface.setPointer(_ shape: PointerShape)Pointer shape over the content (.hand, .text, .arrow, .resize…).
Example
surface.setPointer(ui.button(at: x, y) != 0 ? .hand : .arrow)
from sdk-apps/greeter (shortened)
Surface.raise()Brings the window to the front (e.g. after a handed-over document).
Example
if openHandedOver() { surface.raise(); dirty = true }   // Double-click in Files: to the front
from apps/database (shortened)
Surface.carry()Lets the user drag a document; the answer arrives as .dropped.
Example
case .pointer(let x, let y, let buttons):
    if buttons & 2 != 0 && overDocument(x, y) { surface.carry() }
case .dropped(let program, let length, _, _):
    if length > 0 { /* dropped over program[0..<length] */ }
Pattern (short, not copied from a program)
Internals
Surface.handle: UInt64Number of the window (for the system call surfaceNotify).
Surface.frameCounter / .frameShownstaticByte offsets in the ring page: frame counter (odd = being drawn) and last frame shown.

SwiftSurfaceEventWhat the service reports to the program

CallWhat it doesShape call · time budget
Window
SurfaceEvent.configure(width: Int, height: Int)caseSize changed / window ready: redraw.
SurfaceEvent.focus(Bool)caseWindow gains/loses focus.
SurfaceEvent.closecaseUser closed the window (⌘W): exit the program.
Input
SurfaceEvent.key(code: UInt8, down: Bool)caseKey (HID code); pass it through Keyboard.handle.
Example
case .key(let code, let down):
    let press = keyboard.handle(code: code, down: down)
from apps/reader (shortened)
SurfaceEvent.pointer(x: Int, y: Int, buttons: UInt32)casePointer moved / button; bit 1 (value 2) = primary button pressed.
SurfaceEvent.scroll(x: Int, y: Int, tenths: Int)caseMouse wheel in tenths of a notch, positive away from the user.
Example
case .scroll(let x, let y, let tenths):
    scrollY = max(0, scrollY - tenths * 6)
from apps/reader (shortened)
Menu & dragging
SurfaceEvent.menu(id: Int)caseA menu item (menu bar, context menu or shortcut) was chosen.
SurfaceEvent.dropped(program: InlineArray<32, UInt8>, length: Int, x: Int, y: Int)caseA carried document was dropped over a program.

SwiftSurfaceDescribing menus

CallWhat it doesShape call · time budget
Building menus
Surface.addMenu(_ index: Int, _ title: StaticString)Menu number index (0 … 5 menu bar, SurfaceMessage.contextMenu for right-click).
Example
surface.addMenu(2, "View")
from apps/reader (shortened)
Surface.addItem(_ index: Int, _ title: StaticString, id: Int, key: UInt8 = 0, enabled: Bool = true, icon: MenuIcon = .none, toggle: Bool? = nil)Menu item; key = letter of the ⌘ shortcut; with icon a large button at the top of the menu; toggle = toggle.
Example
surface.addItem(2, "Zoom In", id: Item.zoomIn, key: 0x2B, icon: .zoomIn)   // ⌘+
from apps/reader (shortened)
Surface.addSeparator(_ index: Int)Separator.
Example
surface.addSeparator(2)
from apps/reader (shortened)
Surface.publishMenus()Send the menus to the service (after all add… calls).
Example
surface.addMenu(0, "Counter")
surface.addItem(0, "Count", id: Buttons.count, key: 0x6E) // ⌘N
surface.publishMenus()
from sdk-apps/greeter (shortened)
Surface.clearMenus()Remove all menus, then send them again.
Switching items
Surface.setItem(_ id: Int, enabled: Bool)Item selectable or greyed out.
Example
surface.setItem(Buttons.delete, enabled: place != 2)
from apps/files (shortened)
Surface.setItem(_ id: Int, on: Bool)Toggle item on/off.
Example
surface.setItem(Item.pages, on: !showOutline)   // Keep the toggle item in step
Pattern (short, not copied from a program)
Standard menus
Surface.addFileMenu(_ index: Int = 0, new: StaticString = "", open: Bool = false, save: Bool = false, saveAs: Bool = false, export: Bool = false, showInFiles: Bool = false) newThe standard File menu: only the items the program supports, in system order with system shortcuts.
Example
surface.addFileMenu(new: "New Script", open: true, save: true, export: true)
from apps/develop (shortened)
Surface.addEditMenu(_ index: Int, contextMenu: Bool = true)The standard Edit menu (also in the context menu); pass the ids to the focused InputField.
Example
surface.addEditMenu(1)   // Menu 1 and context menu
from apps/reader (shortened)

SwiftFileMenu · EditMenu · MenuIconStandard menus

CallWhat it doesShape call · time budget
File menu
FileMenu.new / .open / .save / .saveAs / .export / .showInFiles (911 … 916) newids of the standard File menu.
FileMenu.contains(_ id: Int) -> Bool newDoes the id belong to the File menu?
Example
case .menu(let id):
    if FileMenu.contains(id) { fileCommand(id) }
    else if EditMenu.contains(id) { _ = field.command(id) }
Pattern (short, not copied from a program)
Edit menu
EditMenu.undo / .redo / .cut / .copy / .paste / .selectAll (901 … 906)ids of the Edit menu; on Paste the service releases the clipboard.
EditMenu.contains(_ id: Int) -> BoolDoes the id belong to the Edit menu?
Symbols
enum MenuIcon: none, folder, rename, delete, compress, extract, refresh, start, up, zoomIn, zoomOut, fit, actualSize, clear, list, log, copySymbols for menu items (drawn by the service).

SwiftSurfaceReporting progress

CallWhat it doesShape call · time budget
Starting a task
Surface.progress(_ title: TextLine, total: UInt64, unit: ProgressUnit = .none, cancellable: Bool = false) -> ProgressTask? newStarts a task in the title and in the Dock; total 0 = unknown (running stripe). Nil if there are already 4 tasks.surfaceNotify (system call 11)
Example
guard let task = surface.progress(TextLine("Export 1200 rows"), total: 1200, unit: .items, cancellable: true) else { return }
Pattern (short, not copied from a program)
Reporting progress
Surface.progress(_ task: ProgressTask, done: UInt64) newHow far the task has got (throttled to 10/s).
Example
surface?.progress(running, done: UInt64(response.body.count))
from apps/web (shortened)
Finishing
Surface.progress(_ task: ProgressTask, finished end: ProgressEnd, done: UInt64? = nil) newTask finished; stays green (or red) in the title for a moment.
Example
surface?.progress(running, finished: cancelled ? .cancelled : result.problem == nil ? .done : .failed)
from apps/web (shortened)
Detecting cancellation
Surface.isCancelled(_ task: ProgressTask) -> Bool newHas the person pressed Cancel? Ask at any time, even in the middle of a loop.
Example
if surface?.isCancelled(running) == true { cancelled = true; break }
from apps/web (shortened)
Surface.cancelRequestsstatic newByte offset of the cancel bits in the ring page (one bit per task).

SwiftProgressUnit · ProgressEnd · ProgressTaskProgress types

CallWhat it doesShape call · time budget
Types
enum ProgressUnit: UInt8 { none, bytes, items } newWhat done and total count.
enum ProgressEnd: UInt8 { done, failed, cancelled } newHow a task ended.
struct ProgressTask { let id: Int } newA running task of the window.
SurfaceMessage.progress newMessage kind 12 (program → service).

SwiftCanvasDrawing in pixels (logical points × scale)

CallWhat it doesShape call · time budget
Areas
Canvas.fill(_ rect: Rect, _ color: RGB)Fill a rectangle.
Example
canvas.fill(Rect(x: 0, y: 0, width: canvas.width, height: 40), UITheme.raised)
Pattern (short, not copied from a program)
Canvas.gradient(_ rect: Rect, from top: RGB, to bottom: RGB)Vertical gradient.
Canvas.blend(_ rect: Rect, _ color: RGB, alpha: UInt32)Overlay semi-transparently.
Example
canvas.blend(Rect(x: x - thick / 2, y: y - thick / 2, width: thick, height: thick), colour, alpha: alpha)
from apps/develop (shortened)
Canvas.smoothRect(_ rect: Rect, radius: Int, top: RGB, bottom: RGB)Rounded rectangle with gradient, anti-aliased.
Text
Canvas.text(_ line: TextLine, x: Int, y: Int, color: RGB, scale requested: Int = 1) -> IntText in the bitmap font; returns the width.
Canvas.text(_ text: TextLine, x: Int, baseline: Int, face: FontFace, color: RGB) -> IntText in a system font (.body, .heading …) on a baseline.
Example
canvas.text(TextLine("RECORDINGS"), x: area.x + 16, baseline: area.y + 26, face: .caption, color: UITheme.muted)
from apps/sound (shortened)
Canvas.width(_ text: TextLine, face: FontFace) -> IntstaticWidth of a text in a font.
Example
let plus = Rect(x: minus.right + 24 + Canvas.width(TextLine("100 %"), face: .body), y: soundY - 21, width: 32, height: 32)
from apps/sound (shortened)
Canvas.textWidth(_ line: TextLine, scale: Int = 1) -> IntstaticWidth in the bitmap font.
Pixels & colours
Canvas.pixel(_ x: Int, _ y: Int) -> UInt32 / .setPixel(_:_:_:)Read/set a single point (in the screen format).
Canvas.encode(_ color: RGB) -> UInt32 / .decode(_ value: UInt32) -> RGBColour ↔ pixel value.
Canvas.copy(from base: UInt64, stride sourceStride: Int, rect: Rect, to x: Int, _ y: Int, limit: Rect)Copy pixels from another memory (images, video).
Sub-areas
Canvas.region(_ rect: Rect) -> CanvasSub-area as its own Canvas (origin shifted, clipped).
Example
let sidebar = canvas.region(Rect(x: 0, y: 0, width: 210, height: canvas.height))
sidebar.fill(Rect(x: 0, y: 0, width: 210, height: canvas.height), UITheme.ground)
Pattern (short, not copied from a program)
Canvas.clip(_ rect: Rect) -> RectClip a rectangle to the surface.
Canvas.scaled(_ scale: Int) -> CanvasThe same surface at a different scale.
Drawing views
Canvas.render<V: View>(_ view: V, in rect: Rect, _ ui: inout UI, background: RGB = UITheme.background)Measure and draw views; buttons are registered in ui.
Example
canvas.render(view, in: Rect(x: 0, y: 0, width: canvas.width, height: canvas.height), &ui)
from sdk-apps/greeter (shortened)
Dimensions
Canvas.width, .height, .scale, .stride, .pixelWidth, .pixelHeight, .baseDimensions (logical and physical) and memory address.

SwiftViewsDescribing content instead of drawing it

CallWhat it doesShape call · time budget
Arranging
VStack(spacing: Int = 8, @ViewBuilder _ content: () -> Content)Arrange vertically.
Example
let view = Padded(20) {
    VStack(spacing: 14) {
        Text("greeter", face: .heading)
        Button("Count", id: Buttons.count)
        Spacer()
    }
}
from sdk-apps/greeter (shortened)
HStack(spacing: Int = 8, @ViewBuilder _ content: () -> Content)Arrange side by side.
Padded(_ amount: Int, @ViewBuilder _ content: () -> Content)Padding around a stack.
Spacer() / Divider()Flexible space / divider.
Contents
Text(_ text: StaticString | TextLine, face: FontFace = .body, color: RGB = UITheme.text)A text in the system font.
Button(_ title: StaticString | TextLine, id: Int, prominent: Bool = true, tint: RGB = UITheme.accent)Button; its id is returned by ui.button(at:).
ProgressBar (value, maximum, color)Progress bar in the content (for tasks in the title: Progress).
Custom views
protocol View: measure(_:) / draw(in:on:_:) / flexible / compressibleCustom views: measure and draw.

SwiftUIButtons, focus, keyboard navigation

CallWhat it doesShape call · time budget
Buttons
UI.init()Empty state (keep it global).
UI.button(at x: Int, _ y: Int) -> Intid of the button under the pointer (0: none).
Example
let under = ui.button(at: x, y)   // 0: no button
from sdk-apps/greeter (shortened)
UI.pressed / .focusedPressed or focused button.
UI.button(_ canvas: Canvas, _ rect: Rect, id: Int, _ title: TextLine, kind: ButtonKind = .secondary, size: ButtonSize = .regular, symbol: ButtonSymbol? = nil, enabled: Bool = true, background: RGB = UITheme.background)Draw and register a button directly (without views).
Example
ui.button(canvas, plus, id: Buttons.louder, louder, kind: .secondary)
from apps/settings (shortened)
UI.beginFrame() / .addButton(_ id: Int, _ rect: Rect)Begin a new frame / register a custom area as a button.
Keyboard navigation
UI.key(_ press: Keyboard.Result, shift: Bool) -> IntTab moves the focus, Enter/Space presses; returns the id of the pressed button.
Example
let press = keyboard.handle(code: code, down: down)
let pressed = ui.key(press, shift: keyboard.shift)
if pressed == Buttons.count { clicks += 1 }
Pattern (short, not copied from a program)

SwiftUITheme · ButtonLook · FileLookThe system's colours and button look

CallWhat it doesShape call · time budget
Colours
UITheme.background, .ground, .raised, .line, .text, .muted, .faint, .accent, .accentPressed, .onAccent, .good, .warning …staticSystem colours (dark or light, depending on the owner's setting).
UITheme.codeKeyword, .codeValue, .codeComment, .codeShapestaticColours for source code (Develop).
UITheme.use(light: Bool) / UITheme.isLight: BoolstaticChoose / query the light or dark palette.
Example
UITheme.use(light: true)   // light palette; redraw afterwards
Pattern (short, not copied from a program)
UIDesign.dark / UIDesign.lightstaticThe two palettes as UIDesign values.
Button look
ButtonLook.draw(_ canvas: Canvas, _ rect: Rect, _ kind: ButtonKind, _ size: ButtonSize, title: TextLine? = nil, symbol: ButtonSymbol? = nil, state: ButtonState = ButtonState(), background: RGB = UITheme.background)Draw a button in the system look (variants by ButtonKind, sizes by ButtonSize).
ButtonLook.width(_ title: TextLine, _ size: ButtonSize) -> IntWidth of a button.
ButtonLook.drawSymbol / .roundedFill / .coloursSymbol, rounded area, colours of a state.
File colours
FileLook.colour(_ name: Span<UInt8>) -> RGBColour with which Files shows a file type.

SwiftKeyboardInput: key codes to characters

CallWhat it doesShape call · time budget
Evaluating keys
Keyboard.init()State of the modifier keys.
Keyboard.handle(code: UInt8, down: Bool) -> ResultEvaluates a .key event: .character, .text, .special(…) or .none.
Example
let press = keyboard.handle(code: code, down: down)
switch press {
case .special(.down): scrollY += 40
case .character(0x20): scrollY += area.height - 40
default: break
}
from apps/reader (shortened)
Keyboard.utf8(_ code: UInt32, into out: inout InlineArray<4, UInt8>) -> IntstaticA character as UTF-8.
Modifier keys
Keyboard.shift, .control, .option, .command, .altGrPressed modifier keys.

SwiftInputFieldInput: a field with selection, undo and clipboard

CallWhat it doesShape call · time budget
Creating
InputField.init(maximumLength: Int = 512, secret: Bool = false)Create a field; secret shows dots (passwords).
Example
nonisolated(unsafe) var passwordInput = InputField(maximumLength: 127, secret: true)
passwordInput.placeholder = TextLine("Password")
from apps/reader (shortened)
Passing input on
InputField.key(_ press: Keyboard.Result, _ keyboard: Keyboard) -> ChangeKey while the field has the focus; result .none/.moved/.edited/.submit/.cancel.
Example
switch passwordInput.key(press, keyboard) {
case .submit: submitPassword()
case .none: return false
default: break
}
from apps/reader (shortened)
InputField.command(_ id: Int) -> ChangeExecute a command of the Edit menu (EditMenu ids).
Example
if searchFocused { let change = searchInput.command(id); if change == .edited { search() } }
from apps/reader (shortened)
InputField.pointer(_ x: Int, _ y: Int, down: Bool, pressed: Bool) -> BoolPointer event (click, drag); true if the field took it.
Example
if editing && queryInput.pointer(x, y, down: down, pressed: pressed) { surface.setPointer(.text); dirty = true }
from apps/database (shortened)
Drawing
InputField.draw(_ canvas: Canvas, _ rect: Rect, focused: Bool)Draw the field: frame, text, selection, cursor.
Example
searchInput.draw(canvas, field, focused: searchFocused)
from apps/reader (shortened)
InputField.contains(_ x: Int, _ y: Int) -> BoolIs the pointer over the field (for the text pointer)?
Setting & reading content
InputField.set(_ text: Span<UInt8> | TextLine) / .clear()Replace / clear the text.
InputField.select(from start: Int, to end: Int)Set cursor and selection.
InputField.withBytes<R>(_ body: (Span<UInt8>) -> R) -> R / .line: TextLineRead the content (bytes, or the first 160 bytes as a line).
Example
var password: [UInt8] = []
passwordInput.withBytes { for byte in $0 { password.append(byte) } }
from apps/reader (shortened)
Properties
InputField.placeholder, .bordered, .secret, .face, .textColour, .cursorColour, .maximumLengthAppearance and behaviour.
InputField.isEmpty, .hasSelection / .cursor, .anchor, .count, .frameState of the field.

SwiftRect · Size · RGBBasic types

CallWhat it doesShape call · time budget
Basic types
Rect(x: Int, y: Int, width: Int, height: Int) / .right / .bottomA rectangle in window points.
Size(width: Int, height: Int)A size (views measure with it).
RGB(_ red: UInt8, _ green: UInt8, _ blue: UInt8) / .mixed(with other: RGB, _ amount: UInt32) -> RGBA colour; mixing two colours.
Canvas.physicalPixel(_:_:) / .setPhysicalPixel(_:_:_:) / .shiftsPixels in the physical grid (without scale) and the screen's colour format.

SwiftScrollBar · ListBar · Chart · DamageTrackerBuilding blocks

CallWhat it doesShape call · time budget
Scroll bars
ScrollBar.draw(_ canvas: Canvas, _ rect: Rect, total: Int, visible: Int, offset: Int, active: Bool = false)Scroll bar in the system look (variant B).
Example
ScrollBar.draw(canvas, listBar, total: entryCount, visible: visibleRows, offset: scroll, active: listBarGrab != nil)
from apps/files (shortened)
ScrollBar.needed / .thumb / .part(at:…) / .offset(after:…) / .offset(dragTo:…)Is a bar needed, where is the thumb, evaluating clicks and dragging.
ListBar.place(_ area: Rect, total: Int, visible: Int) -> Int / .pointer(…) / .draw(_:offset:)Scroll bar for lists with its own state.
Charts
Chart.frame(_ canvas: Canvas, _ rect: Rect, low: Double, high: Double, lines: Int, labelWidth: Int, …, label: (Double) -> TextLine) -> PlotChart frame with grid and labels; returns the drawing area.
Example
let plot = Chart.frame(canvas, panel, low: 0, high: Double(top), lines: 5, labelWidth: 48, rightRoom: 58) { value in
    var line = TextLine(); line.append(decimal: UInt64(value)); return line
}
from apps/activity (shortened)
Chart.series(_ canvas: Canvas, _ plot: Plot, count: Int, slots: Int, colour: RGB, area: Bool, value: (Int) -> Double)A measurement series as a line or area.
Example
Chart.series(canvas, plot, count: values.count, slots: historyLength, colour: Chart.cpu, area: true) { index in
    values[index]
}
from apps/activity (shortened)
Chart.cursor / .endPoint / .dot / .niceTop / .roundedPanelCursor, end point with value, dot, rounded upper limit, panel.
Plot(area: Rect, low: Double, high: Double): x(of:count:slots:) / .y(_:) / .index(at:count:slots:)Conversion value ↔ pixel.
Changed tiles
DamageTracker.changes(_ canvas: Canvas, handle: UInt64, _ changed: (Rect) -> Void)Finds changed tiles (for presentChanges).
Example: a window with a menu, a button and an event loop (sdk-apps/greeter)
nonisolated(unsafe) var ui = UI()
nonisolated(unsafe) var clicks = 0

enum Buttons { static let count = 1 }

@c(app_main)
func appMain() {
    guard var surface = Surface.create() else { System.log("greeter: no window"); return }
    surface.requestSize(width: 360, height: 220)
    surface.addMenu(0, "Counter")
    surface.addItem(0, "Count", id: Buttons.count, key: 0x6E) // Cmd+N
    surface.publishMenus()
    var dirty = true
    while true {
        while let event = surface.nextEvent() {
            switch event {
            case .configure: dirty = true
            case .close: System.exit(0)
            case .menu(let id): if id == Buttons.count { clicks += 1; dirty = true }
            case .pointer(let x, let y, let buttons):
                let under = ui.button(at: x, y)
                surface.setPointer(under != 0 ? .hand : .arrow)
                if buttons & 2 != 0 {
                    if ui.pressed == 0 { ui.pressed = under; dirty = true }
                } else if ui.pressed != 0 {
                    if under == ui.pressed && under == Buttons.count { clicks += 1 }
                    ui.pressed = 0
                    dirty = true
                }
            default: break
            }
        }
        if dirty && surface.canvas.width > 0 {
            draw(surface.canvas)
            surface.present(Rect(x: 0, y: 0, width: surface.canvas.width, height: surface.canvas.height))
            dirty = false
        }
        surface.wait(timeout: 500_000_000)
    }
}
Example: describing content with views (sdk-apps/greeter)
private func draw(_ canvas: Canvas) {
    var text = TextLine("Clicked ")
    text.append(decimal: UInt64(clicks))
    text.append(clicks == 1 ? " time" : " times")
    let view = Padded(20) {
        VStack(spacing: 14) {
            Text("greeter", face: .heading)
            Text(text, face: .body, color: UITheme.muted)
            Button("Count", id: Buttons.count)
            Spacer()
        }
    }
    canvas.render(view, in: Rect(x: 0, y: 0, width: canvas.width, height: canvas.height), &ui)
}
Example: keyboard and search field (apps/reader)
nonisolated(unsafe) var keyboard = Keyboard()
nonisolated(unsafe) var searchInput = InputField(maximumLength: 120)

// at start
searchInput.placeholder = TextLine("Search")

// on case .key(let code, let down):
let press = keyboard.handle(code: code, down: down)
if searchFocused {
    switch searchInput.key(press, keyboard) {
    case .edited: search(); return true
    case .submit: return step(keyboard.shift ? -1 : 1, canvas)
    case .cancel: searchFocused = false; return true
    case .moved: return true
    case .none: break
    }
}

// when drawing
searchInput.draw(canvas, field, focused: searchFocused)
Example: showing only changed parts (apps/reader)
if dirty && surface.canvas.width > 0 {
    surface.beginDrawing()      // the service now does not copy in the middle of the frame
    draw(surface.canvas)
    surface.presentChanges()    // only the changed tiles
    dirty = false
}
surface.wait(timeout: 500_000_000)
Example: download with progress and cancel (apps/web, Fetch.swift, shortened)
// Long answers show their progress (the system draws it).
if task == nil {
    task = surface?.progress(TextLine("Download Big_Buck_Bunny.webm"),
                             total: UInt64(response.expectedLength ?? 0), unit: .bytes, cancellable: true)
}
if let running = task {
    surface?.progress(running, done: UInt64(response.body.count))
    if surface?.isCancelled(running) == true {
        cancelled = true
        break
    }
}

// at the end (defer):
if let running = task {
    surface?.progress(running, finished: cancelled ? .cancelled : result.problem == nil ? .done : .failed)
    task = nil
}
All 354 declarations of this part (from docs/api/app-api-1.txt)
Button.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
Button.func measure(_ proposal: Size) -> Size
Button.init(_ title: StaticString, id: Int, prominent: Bool = true, tint: RGB = UITheme.accent)
Button.init(_ title: TextLine, id: Int, prominent: Bool = true, tint: RGB = UITheme.accent)
Button.let id: Int
Button.let title: TextLine
Button.var prominent
Button.var tint
ButtonLook.static func colours(_ kind: ButtonKind, _ state: ButtonState, background: RGB) -> (fill: RGB?, text: RGB)
ButtonLook.static func draw(_ canvas: Canvas, _ rect: Rect, _ kind: ButtonKind, _ size: ButtonSize, title: TextLine? = nil,
ButtonLook.static func drawSymbol(_ canvas: Canvas, _ symbol: ButtonSymbol, x: Int, y: Int, size: Int, _ colour: RGB)
ButtonLook.static func roundedFill(_ canvas: Canvas, _ rect: Rect, radius: Int, _ colour: RGB)
ButtonLook.static func width(_ title: TextLine, _ size: ButtonSize) -> Int
ButtonSize.var height: Int
ButtonSize.var padding: Int
ButtonSize.var radius: Int
ButtonState.init(hovered: Bool = false, pressed: Bool = false, enabled: Bool = true, focused: Bool = false)
ButtonState.var enabled
ButtonState.var focused
ButtonState.var hovered
ButtonState.var pressed
Canvas.func blend(_ rect: Rect, _ color: RGB, alpha: UInt32)
Canvas.func clip(_ rect: Rect) -> Rect
Canvas.func copy(from base: UInt64, stride sourceStride: Int, rect: Rect, to x: Int, _ y: Int, limit: Rect)
Canvas.func decode(_ value: UInt32) -> RGB
Canvas.func encode(_ color: RGB) -> UInt32
Canvas.func fill(_ rect: Rect, _ color: RGB)
Canvas.func gradient(_ rect: Rect, from top: RGB, to bottom: RGB)
Canvas.func physicalPixel(_ x: Int, _ y: Int) -> UInt32
Canvas.func pixel(_ x: Int, _ y: Int) -> UInt32
Canvas.func region(_ rect: Rect) -> Canvas
Canvas.func render<V: View>(_ view: V, in rect: Rect, _ ui: inout UI, background: RGB = UITheme.background)
Canvas.func scaled(_ scale: Int) -> Canvas
Canvas.func setPhysicalPixel(_ x: Int, _ y: Int, _ value: UInt32)
Canvas.func setPixel(_ x: Int, _ y: Int, _ value: UInt32)
Canvas.func smoothRect(_ rect: Rect, radius: Int, top: RGB, bottom: RGB)
Canvas.func text(_ line: TextLine, x: Int, y: Int, color: RGB, scale requested: Int = 1) -> Int
Canvas.func text(_ text: TextLine, x: Int, baseline: Int, face: FontFace, color: RGB) -> Int
Canvas.init(base: UInt64, pixelWidth: Int, pixelHeight: Int, stride: Int, shifts: UInt64, scale: Int)
Canvas.init(base: UInt64, width: Int, height: Int, stride: Int, shifts: UInt64)
Canvas.let base: UInt64
Canvas.let height: Int
Canvas.let pixelHeight: Int
Canvas.let pixelWidth: Int
Canvas.let scale: Int
Canvas.let stride: Int
Canvas.let width: Int
Canvas.static func textWidth(_ line: TextLine, scale: Int = 1) -> Int
Canvas.static func width(_ text: TextLine, face: FontFace) -> Int
Canvas.var shifts: UInt64
Chart.Plot.func index(at x: Int, count: Int, slots: Int) -> Int?
Chart.Plot.func x(of index: Int, count: Int, slots: Int) -> Double
Chart.Plot.func y(_ value: Double) -> Double
Chart.Plot.init(area: Rect, low: Double, high: Double)
Chart.Plot.var area: Rect
Chart.Plot.var high: Double
Chart.Plot.var low: Double
Chart.static func cursor(_ canvas: Canvas, _ plot: Plot, index: Int, count: Int, slots: Int, value: Double, colour: RGB)
Chart.static func dot(_ canvas: Canvas, x: Double, y: Double, radius: Double, colour: RGB)
Chart.static func endPoint(_ canvas: Canvas, _ plot: Plot, count: Int, slots: Int, colour: RGB, value: Double,
Chart.static func frame(_ canvas: Canvas, _ rect: Rect, low: Double, high: Double, lines: Int, labelWidth: Int,
Chart.static func niceTop(_ value: Double) -> Double
Chart.static func roundedPanel(_ canvas: Canvas, _ rect: Rect)
Chart.static func series(_ canvas: Canvas, _ plot: Plot, count: Int, slots: Int, colour: RGB, area: Bool,
Chart.static var background: RGB
Chart.static var bad: RGB
Chart.static var bright: RGB
Chart.static var cpu: RGB
Chart.static var grid: RGB
Chart.static var label: RGB
Chart.static var memory: RGB
Chart.static var realtime: RGB
Chart.static var write: RGB
Chart.struct Plot
DamageTracker.init()
DamageTracker.mutating func changes(_ canvas: Canvas, handle: UInt64, _ changed: (Rect) -> Void)
DamageTracker.static let tile
Divider.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
Divider.func measure(_ proposal: Size) -> Size
Divider.init()
EditMenu.static func contains(_ id: Int) -> Bool
EditMenu.static let undo
FileLook.static func colour(_ name: Span<UInt8>) -> RGB
FileMenu.static func contains(_ id: Int) -> Bool
FileMenu.static let new
HStack.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
HStack.func measure(_ proposal: Size) -> Size
HStack.init(spacing: Int = 8, @ViewBuilder _ content: () -> Content)
HStack.let content: Content
HStack.let spacing: Int
InputField.enum Change: Equatable
InputField.func contains(_ x: Int, _ y: Int) -> Bool
InputField.func withBytes<R>(_ body: (Span<UInt8>) -> R) -> R
InputField.init(maximumLength: Int = 512, secret: Bool = false)
InputField.mutating func clear()
InputField.mutating func command(_ id: Int) -> Change
InputField.mutating func draw(_ canvas: Canvas, _ rect: Rect, focused: Bool)
InputField.mutating func key(_ press: Keyboard.Result, _ keyboard: Keyboard) -> Change
InputField.mutating func pointer(_ x: Int, _ y: Int, down: Bool, pressed: Bool) -> Bool
InputField.mutating func select(from start: Int, to end: Int)
InputField.mutating func set(_ text: Span<UInt8>)
InputField.mutating func set(_ text: TextLine)
InputField.private(set) var anchor
InputField.private(set) var count
InputField.private(set) var cursor
InputField.private(set) var frame
InputField.static let capacity
InputField.var bordered
InputField.var cursorColour: RGB?
InputField.var face
InputField.var hasSelection: Bool
InputField.var isEmpty: Bool
InputField.var line: TextLine
InputField.var maximumLength: Int
InputField.var placeholder
InputField.var secret: Bool
InputField.var textColour
Keyboard.enum Result: Equatable
Keyboard.enum Special
Keyboard.init()
Keyboard.mutating func handle(code: UInt8, down: Bool) -> Result
Keyboard.private(set) var altGr
Keyboard.private(set) var command
Keyboard.private(set) var control
Keyboard.private(set) var option
Keyboard.private(set) var shift
Keyboard.static func utf8(_ code: UInt32, into out: inout InlineArray<4, UInt8>) -> Int
ListAnd.func compressible(_ index: Int) -> Bool
ListAnd.func draw(_ index: Int, in rect: Rect, on canvas: Canvas, _ ui: inout UI)
ListAnd.func flexible(_ index: Int) -> Bool
ListAnd.func measure(_ index: Int, _ proposal: Size) -> Size
ListAnd.let head: Head
ListAnd.let last: Last
ListAnd.var count: Int
ListBar.func draw(_ canvas: Canvas, offset: Int)
ListBar.init()
ListBar.mutating func beginFrame()
ListBar.mutating func place(_ area: Rect, total: Int, visible: Int) -> Int
ListBar.mutating func pointer(_ x: Int, _ y: Int, down: Bool, pressed: Bool, offset: Int) -> Int?
ListBar.private(set) var rect: Rect?
ListOf1.func compressible(_ index: Int) -> Bool
ListOf1.func draw(_ index: Int, in rect: Rect, on canvas: Canvas, _ ui: inout UI)
ListOf1.func flexible(_ index: Int) -> Bool
ListOf1.func measure(_ index: Int, _ proposal: Size) -> Size
ListOf1.let a: A
ListOf1.var count: Int
Padded.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
Padded.func measure(_ proposal: Size) -> Size
Padded.init(_ amount: Int, @ViewBuilder _ content: () -> Content)
Padded.let amount: Int
Padded.let content: VStack<Content>
Padded.var flexible: Bool
ProgressBar.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
ProgressBar.func measure(_ proposal: Size) -> Size
ProgressBar.let maximum: Int
ProgressBar.let value: Int
ProgressBar.var color: RGB
ProgressTask.let id: Int
RGB.func mixed(with other: RGB, _ amount: UInt32) -> RGB
RGB.init(_ red: UInt8, _ green: UInt8, _ blue: UInt8)
RGB.var red: UInt8, green: UInt8, blue: UInt8
Rect.init(x: Int, y: Int, width: Int, height: Int)
Rect.var bottom: Int
Rect.var right: Int
Rect.var x: Int, y: Int, width: Int, height: Int
ScrollBar.enum Part: Equatable
ScrollBar.static func draw(_ canvas: Canvas, _ rect: Rect, total: Int, visible: Int, offset: Int, active: Bool = false)
ScrollBar.static func needed(total: Int, visible: Int) -> Bool
ScrollBar.static func offset(after part: Part, offset: Int, total: Int, visible: Int, step: Int) -> Int
ScrollBar.static func offset(dragTo y: Int, grab: Int, _ rect: Rect, total: Int, visible: Int) -> Int
ScrollBar.static func part(at y: Int, _ rect: Rect, total: Int, visible: Int, offset: Int) -> Part?
ScrollBar.static func thumb(_ rect: Rect, total: Int, visible: Int, offset: Int) -> Rect
ScrollBar.static let width
Size.init(width: Int, height: Int)
Size.var width: Int, height: Int
Spacer.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
Spacer.func measure(_ proposal: Size) -> Size
Spacer.init()
Spacer.var flexible: Bool
Surface.func addEditMenu(_ index: Int, contextMenu: Bool = true)
Surface.func addFileMenu(_ index: Int = 0, new: StaticString = "", open: Bool = false, save: Bool = false, saveAs: Bool = false,
Surface.func addItem(_ index: Int, _ title: StaticString, id: Int, key: UInt8 = 0, enabled: Bool = true, icon: MenuIcon = .none,
Surface.func addMenu(_ index: Int, _ title: StaticString)
Surface.func addSeparator(_ index: Int)
Surface.func beginDrawing()
Surface.func carry()
Surface.func clearMenus()
Surface.func destroy()
Surface.func isCancelled(_ task: ProgressTask) -> Bool
Surface.func present(_ rect: Rect) -> Bool
Surface.func presentChanges()
Surface.func progress(_ task: ProgressTask, done: UInt64)
Surface.func progress(_ task: ProgressTask, finished end: ProgressEnd, done: UInt64? = nil)
Surface.func progress(_ title: TextLine, total: UInt64, unit: ProgressUnit = .none, cancellable: Bool = false) -> ProgressTask?
Surface.func publishMenus()
Surface.func raise()
Surface.func requestSize(width: Int, height: Int)
Surface.func setItem(_ id: Int, enabled: Bool)
Surface.func setItem(_ id: Int, on: Bool)
Surface.func setTitle(_ text: TextLine)
Surface.func wait(timeout: UInt64)
Surface.let handle: UInt64
Surface.mutating func nextEvent() -> SurfaceEvent?
Surface.mutating func setPointer(_ shape: PointerShape)
Surface.private(set) var canvas: Canvas
Surface.static func create(timeout: UInt64 = 10_000_000_000) -> Surface?
Surface.static let cancelRequests
Surface.static let frameCounter
Surface.static let frameShown
SurfaceMessage.static func field(_ message: InlineArray<256, UInt8>, _ index: Int) -> UInt32
SurfaceMessage.static func make(_ kind: UInt8, _ fields: InlineArray<4, UInt32>, count: Int) -> (InlineArray<17, UInt8>, Int)
SurfaceMessage.static let carry: UInt8
SurfaceMessage.static let close: UInt8
SurfaceMessage.static let configure: UInt8
SurfaceMessage.static let contextMenu: UInt8
SurfaceMessage.static let contextMenuIndex
SurfaceMessage.static let disabled: UInt8
SurfaceMessage.static let dropped: UInt8
SurfaceMessage.static let focus: UInt8
SurfaceMessage.static let key: UInt8
SurfaceMessage.static let menu: UInt8
SurfaceMessage.static let menuChosen: UInt8
SurfaceMessage.static let menuEnabled: UInt8
SurfaceMessage.static let menuItem: UInt8
SurfaceMessage.static let menuReset: UInt8
SurfaceMessage.static let menuState: UInt8
SurfaceMessage.static let on: UInt8
SurfaceMessage.static let pointer: UInt8
SurfaceMessage.static let pointerShape: UInt8
SurfaceMessage.static let present: UInt8
SurfaceMessage.static let progress: UInt8
SurfaceMessage.static let raise: UInt8
SurfaceMessage.static let scroll: UInt8
SurfaceMessage.static let separator: UInt8
SurfaceMessage.static let size: UInt8
SurfaceMessage.static let title: UInt8
SurfaceMessage.static let toggle: UInt8
Text.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
Text.func measure(_ proposal: Size) -> Size
Text.init(_ text: StaticString, face: FontFace = .body, color: RGB = UITheme.text)
Text.init(_ text: TextLine, face: FontFace = .body, color: RGB = UITheme.text)
Text.let text: TextLine
Text.var color: RGB
Text.var compressible: Bool
Text.var face: FontFace
UI.func button(at x: Int, _ y: Int) -> Int
UI.init()
UI.mutating func addButton(_ id: Int, _ rect: Rect)
UI.mutating func beginFrame()
UI.mutating func button(_ canvas: Canvas, _ rect: Rect, id: Int, _ title: TextLine, kind: ButtonKind = .secondary,
UI.mutating func key(_ press: Keyboard.Result, shift: Bool) -> Int
UI.var focused
UI.var pressed
UIDesign.var accent: RGB
UIDesign.var accentPressed: RGB
UIDesign.var blue: RGB
UIDesign.var chart: RGB
UIDesign.var chartBright: RGB
UIDesign.var chartGrid: RGB
UIDesign.var chartLabel: RGB
UIDesign.var danger: RGB
UIDesign.var faint: RGB
UIDesign.var good: RGB
UIDesign.var ground: RGB
UIDesign.var light: Bool
UIDesign.var line: RGB
UIDesign.var muted: RGB
UIDesign.var onAccent: RGB
UIDesign.var raised: RGB
UIDesign.var selection: RGB
UIDesign.var selectionText: RGB
UIDesign.var surface: RGB
UIDesign.var text: RGB
UIDesign.var violet: RGB
UITheme.nonisolated(unsafe) private(set) static var palette
UITheme.static func use(light: Bool)
UITheme.static let dark
UITheme.static let light
UITheme.static var accent: RGB
UITheme.static var accentPressed: RGB
UITheme.static var background: RGB
UITheme.static var chart: RGB
UITheme.static var codeComment: RGB
UITheme.static var codeKeyword: RGB
UITheme.static var codeShape: RGB
UITheme.static var codeValue: RGB
UITheme.static var danger: RGB
UITheme.static var faint: RGB
UITheme.static var good: RGB
UITheme.static var ground: RGB
UITheme.static var isLight: Bool
UITheme.static var line: RGB
UITheme.static var muted: RGB
UITheme.static var onAccent: RGB
UITheme.static var raised: RGB
UITheme.static var selection: RGB
UITheme.static var selectionText: RGB
UITheme.static var text: RGB
UITheme.static var warning: RGB
VStack.func draw(in rect: Rect, on canvas: Canvas, _ ui: inout UI)
VStack.func measure(_ proposal: Size) -> Size
VStack.init(spacing: Int = 8, @ViewBuilder _ content: () -> Content)
VStack.init(spacing: Int, content: Content)
VStack.let content: Content
VStack.let spacing: Int
VStack.var flexible: Bool
View.var compressible: Bool
View.var flexible: Bool
ViewBuilder.static func buildExpression<V: View>(_ view: V) -> V
ViewBuilder.static func buildPartialBlock<A: View>(first: A) -> ListOf1<A>
ViewBuilder.static func buildPartialBlock<Head: ViewList, Last: View>(accumulated: Head, next: Last) -> ListAnd<Head, Last>
enum ButtonKind: Sendable
enum ButtonLook
enum ButtonSize: Sendable
enum ButtonSymbol: Sendable
enum Chart
enum EditMenu
enum FileLook
enum FileMenu
enum FontFace
enum MenuIcon: UInt8
enum PointerShape: UInt8
enum ProgressEnd: UInt8, Sendable
enum ProgressUnit: UInt8, Sendable
enum ScrollBar
enum SurfaceEvent
enum SurfaceMessage
enum UITheme
enum ViewBuilder
protocol View
protocol ViewList
struct Button: View
struct ButtonState: Sendable
struct Canvas
struct DamageTracker
struct Divider: View
struct HStack<Content: ViewList>: View
struct InputField
struct Keyboard
struct ListAnd<Head: ViewList, Last: View>: ViewList
struct ListBar
struct ListOf1<A: View>: ViewList
struct Padded<Content: ViewList>: View
struct ProgressBar: View
struct ProgressTask: Equatable, Sendable
struct RGB: Equatable, Sendable
struct Rect: Equatable
struct Size: Equatable, Sendable
struct Spacer: View
struct Surface
struct Text: View
struct UI
struct UIDesign: Sendable
struct VStack<Content: ViewList>: View

sound · Playing and listening

Playing (sound.play): every program gets a ring that the kernel's mixer plays (48 kHz, stereo, Int16). Listening (sound.microphone): the kernel writes what a microphone hears into one ring per microphone (48 kHz, 16 bit, mono/stereo, about 1.4 s), mapped read-only into every listening program; the level of each 10 ms period sits next to it. The microphone runs only while someone listens; the red MIC indicator names every program, and the owner can stop them all. The tools (level, auto level, noise gate, voice detection, editing) come with uses-heap and are under Libraries › sound.

Parts for system programs only: System-API › sound.

Rights

RightMeaningShape call · time budget
sound.playPlay sound: a ring that the kernel's mixer plays.≤ 1 mssound.open0x0030_0006
sound.microphoneListen to the microphone; the red MIC indicator names every program that listens.≤ 1 msmicrophone.open0x0031_0002

System callssoundModule 0x0030 · Sound through the system's mixer (sound.play; tone/play/stop planned).

CallRequest → answerRightTime budget · ID
sound.toneTone → Playednone · computed in the program by Reflex≤ 20 µs0x0030_0001
sound.playPlay → Playednone · not served by the kernel yet≤ 100 µs0x0030_0002
sound.stopStopSound → Donenone · not served by the kernel yet≤ 20 µs0x0030_0003
sound.Tone effectReflex effecteffect0x0030_0004
sound.Play effectReflex effecteffect0x0030_0005
sound.openSoundQuery → SoundRingsound.play≤ 1 ms0x0030_0006
sound.closeSoundQuery → Donenone≤ 5 µs0x0030_0007
sound.statusSoundQuery → SoundStatusnone≤ 5 µs0x0030_0008

System callsmicrophoneModule 0x0031 · The robot's microphones (sound.microphone, sound.microphone.provide).

CallRequest → answerRightTime budget · ID
microphone.listMicrophoneListRequest → MicrophoneListsound.microphone or sound.microphone.provide≤ 20 µs0x0031_0001
microphone.openMicrophoneQuery → MicrophoneMapsound.microphone≤ 1 ms0x0031_0002
microphone.closeMicrophoneQuery → Donesound.microphone≤ 1 ms0x0031_0003
microphone.loud eventLoudnessReflex eventevent0x0031_0008
microphone.voice eventVoiceChangeReflex eventevent0x0031_0009

System callssignalModule 0x0040 · Measurements over time: spectrum, filter, statistics.

CallRequest → answerRightTime budget · ID
signal.spectrumSpectrumRequest → Spectrumnone · computed in the program by Reflex≤ 500 µs0x0040_0001
signal.filterFilterRequest → Samplesnone · computed in the program by Reflex≤ 200 µs0x0040_0002
signal.statsSamples → Statsnone · computed in the program by Reflex≤ 50 µs0x0040_0003
signal.sineSineRequest → Samplesnone · computed in the program by Reflex≤ 2 ms0x0040_0004

SwiftSound.OutputPlaying

CallWhat it doesShape call · time budget
Open
Sound.Output.open() -> Sound.Output?staticThe program's ring (the same one on every call); nil without sound.play or a sound device.≤ 1 mssound.open0x0030_0006
Example
if output == nil { output = Sound.Output.open() }
from apps/sound (shortened)
Playing
Sound.Output.write(_ frames: UnsafePointer<Int16>, count: Int) -> IntWrites up to count frames (left, right); returns how many fitted.
Example
_ = chunk.withUnsafeBufferPointer { output.write($0.baseAddress!, count: count) }
from apps/sound (shortened)
Sound.Output.room / .queued / .withDevice: IntRoom now / written but not played / at the device, not yet heard.
Example
while output.room >= 480 && position < total { /* refill */ }
from apps/sound (shortened)
Sound.Output.flush()Discards what is waiting (stop).
Example
output?.flush()   // Stop: discard what is waiting
from apps/sound (shortened)
Volume
Sound.Output.volume: IntOwn volume 0 … 100 (on top of the master volume).
Sound.Output.status: (volume: Int, device: Bool, playing: Bool)staticMaster volume, device present, currently playing.≤ 5 µssound.status0x0030_0008
Example
let hasDevice = Sound.Output.status.device
from apps/settings (shortened)
Close
Sound.Output.close()The ring is no longer mixed.≤ 5 µssound.close0x0030_0007
Constants
Sound.Output.rate = 48_000 / .capacity: IntstaticSample rate / size of the ring.

SwiftSound.Microphone · Sound.MicrophoneRing · Sound.MicrophoneInfoListening

CallWhat it doesShape call · time budget
Choosing & opening a microphone
Sound.Microphone.info(at index: Int) -> Sound.MicrophoneInfo?The index-th microphone (name, rate, channels, listening, id).≤ 20 µsmicrophone.list0x0031_0001
Example
guard let info = Sound.Microphone.info(at: 0) else { problem = TextLine("There is no microphone."); return true }
from apps/sound (shortened)
Sound.Microphone.open(_ id: Int? = nil) -> Sound.MicrophoneRing?Start listening (nil: the first microphone); starts the microphone.≤ 1 msmicrophone.open0x0031_0002
Example
guard let opened = Sound.Microphone.open(info.id) else { return true }
ring = opened
ring?.skipToNow()
from apps/sound (shortened)
Sound.Microphone.close(_ id: Int? = nil) -> BoolStop listening; the microphone stops when nobody listens any more.≤ 1 msmicrophone.close0x0031_0003
Example
Sound.Microphone.close()
from apps/sound (shortened)
Reading samples
Sound.MicrophoneRing.read(into: UnsafeMutablePointer<Int16>, frames: Int) -> (frames: Int, lost: Int)Copy waiting frames; a reader more than a ring behind jumps to the newest second (lost).
Example
let got = raw.withUnsafeMutableBufferPointer { ring!.read(into: $0.baseAddress!, frames: 4800) }
from apps/sound (shortened)
Sound.MicrophoneRing.skipToNow()Skip what is waiting.
State & level
Sound.MicrophoneRing.state: State (running, idle, stoppedByOwner, failed)What the microphone is doing – e.g. stopped by the owner.
Example
if let state = ring?.state, state == .stoppedByOwner { problem = TextLine("You stopped the microphone (MIC in the menu bar).") }
from apps/sound (shortened)
Sound.MicrophoneRing.peakDecibels / .rmsDecibels / .periods / .available / .rate / .channels / .ringFramesLevel of the last 10 ms (dBFS), counter, waiting frames.
Example: opening and reading the microphone (apps/sound, Capture.swift)
// manifest: capabilities = …, sound.play, sound.microphone   (+ uses-heap)
guard let info = Sound.Microphone.info(at: 0) else {
    problem = TextLine("There is no microphone.")
    return true
}
guard let opened = Sound.Microphone.open(info.id) else { return true }
ring = opened
ring?.skipToNow()
autoLevel = AutoLevel(channels: channels, gain: Double(choices.gain))
gate = NoiseGate(channels: channels)
voice = VoiceDetector(channels: channels)

// in the loop:
if ring!.state == .stoppedByOwner { problem = TextLine("You stopped the microphone (MIC in the menu bar).") }
while true {
    let got = raw.withUnsafeMutableBufferPointer { ring!.read(into: $0.baseAddress!, frames: 4800) }
    guard got.frames > 0 else { break }
    // ... in 10 ms periods: autoLevel.process(&span), gate.process(&span),
    //     LevelMeter.measure(span), voice.detect(span)
}

// at the end:
Sound.Microphone.close()
Example: playing through the mixer (apps/sound, Player.swift, shortened)
if output == nil { output = Sound.Output.open() }
guard let output else { return }
while output.room >= 480 && position < total {
    let count = min(output.room, 4800, total - position)
    // fill chunk with count stereo frames (left, right)
    _ = chunk.withUnsafeBufferPointer { output.write($0.baseAddress!, count: count) }
    position += count
}
// Stop: output.flush()
All 38 declarations of this part (from docs/api/app-api-1.txt)
Sound.Microphone.static func close(_ id: Int? = nil) -> Bool
Sound.Microphone.static func info(at index: Int) -> Sound.MicrophoneInfo?
Sound.Microphone.static func open(_ id: Int? = nil) -> Sound.MicrophoneRing?
Sound.MicrophoneInfo.init()
Sound.MicrophoneInfo.var channels
Sound.MicrophoneInfo.var id
Sound.MicrophoneInfo.var listening
Sound.MicrophoneInfo.var name
Sound.MicrophoneInfo.var nameLength
Sound.MicrophoneInfo.var rate
Sound.MicrophoneRing.enum State
Sound.MicrophoneRing.mutating func read(into: UnsafeMutablePointer<Int16>, frames: Int) -> (frames: Int, lost: Int)
Sound.MicrophoneRing.mutating func skipToNow()
Sound.MicrophoneRing.private(set) var position: UInt32
Sound.MicrophoneRing.var available: Int
Sound.MicrophoneRing.var channels: Int
Sound.MicrophoneRing.var peakDecibels: Float
Sound.MicrophoneRing.var periods: UInt32
Sound.MicrophoneRing.var rate: Int
Sound.MicrophoneRing.var ringFrames: Int
Sound.MicrophoneRing.var rmsDecibels: Float
Sound.MicrophoneRing.var state: State
Sound.Output.func close()
Sound.Output.func flush()
Sound.Output.func write(_ frames: UnsafePointer<Int16>, count: Int) -> Int
Sound.Output.let capacity: Int
Sound.Output.static func open() -> Sound.Output?
Sound.Output.static let rate
Sound.Output.static var status: (volume: Int, device: Bool, playing: Bool)
Sound.Output.var queued: Int
Sound.Output.var room: Int
Sound.Output.var volume: Int
Sound.Output.var withDevice: Int
Sound.enum Microphone
Sound.struct MicrophoneInfo
Sound.struct MicrophoneRing
Sound.struct Output
enum Sound

camera · Cameras, vision and detections

Images come from the kernel's rings: with camera.use a camera's image ring is mapped read-only into the program (newest image without a system call); providers (camera.provide: test camera, USB driver) push JPEG images into it. The Mac camera records only while a program has the ring open.

Detection runs in the program Camera (local model, no network connection). It publishes its hits in the ring camera.detections (publish = detections); robot programs subscribe to it with subscribe = camera.detections and read without a system call and without waiting – even in a real-time loop. Images that are too old are discarded (“stale pictures must not steer a robot”).

Parts for system programs only: System-API › camera.

Rights

RightMeaningShape call · time budget
camera.useList cameras and map their image rings read-only.≤ 1 mscamera.ring0x0020_0006

System callscameraModule 0x0020 · The robot's cameras (camera.use, camera.provide).

CallRequest → answerRightTime budget · ID
camera.listCameraListRequest → CameraListcamera.use or camera.provide≤ 20 µs0x0020_0001
camera.frameFrameRequest → CameraFramecamera.use≤ 10 µs0x0020_0002
camera.toWorldPixelPoint → WorldPointcamera.use · computed in the program by Reflex≤ 2 µs0x0020_0003
camera.fromWorldWorldPoint → PixelPointcamera.use · computed in the program by Reflex≤ 2 µs0x0020_0004
camera.frame eventCameraFrameReflex eventevent0x0020_0005
camera.ringCameraRingQuery → CameraRingMapcamera.use≤ 1 ms0x0020_0006
camera.closeCameraRingQuery → Donecamera.use≤ 1 ms0x0020_0009

System callsvisionModule 0x0021 · What the cameras see: detections, colour masks, motion, markers.

CallRequest → answerRightTime budget · ID
vision.detectionsDetectionFilter → Detectionsnone · computed in the program by Reflex≤ 10 µs0x0021_0001
vision.maskColorMask → Masknone · computed in the program by Reflex≤ 2 ms0x0021_0002
vision.motionMotionRequest → Motion2Dnone · computed in the program by Reflex≤ 1 ms0x0021_0003
vision.markersMarkerRequest → Markersnone · computed in the program by Reflex≤ 3 ms0x0021_0004
vision.detections eventDetectionsReflex eventevent0x0021_0005

SwiftCamera · CameraInfo · CameraRingChoosing, opening a camera, reading pictures

CallWhat it doesShape call · time budget
Choosing & opening a camera
Camera.info(at index: Int) -> CameraInfo?The index-th camera (name, width, height, frames, running, id).≤ 20 µscamera.list0x0020_0001
Example
while let info = Camera.info(at: index) { list.append(info); index += 1 }
from apps/video (shortened)
Camera.open(_ id: Int) -> CameraRing?Map the image ring; starts recording.≤ 1 mscamera.ring0x0020_0006
Example
if ring == nil, let info = Camera.info(at: 0) { ring = Camera.open(info.id) }
from apps/server (shortened)
Camera.close(_ id: Int) -> BoolUnmap the ring; the Mac camera stops when nobody has it any more.≤ 1 mscamera.close0x0020_0009
Example
Camera.close(cameras[chosenCamera].id)
from apps/video (shortened)
Reading images
CameraRing.newest(after: UInt32, into buffer: UnsafeMutableRawBufferPointer) -> (frame: UInt32, count: Int, time: UInt64)?Copies the newest image (JPEG) if it is newer than after: number, size, capture time.
Example
let taken = jpeg.withUnsafeMutableBytes { ring.newest(after: frame.number, into: $0) }
from apps/video (shortened)
CameraRing.latest / .width / .height / .runningNewest complete image, dimensions, is the camera running?

SwiftDetectionReaderReading detections (subscriber)

CallWhat it doesShape call · time budget
Read
DetectionReader.newest(after: UInt32 = 0, now: UInt64, maximumAge: UInt64) -> DetectionBatch?Newest batch, unless it is older than maximumAge ns.
Example
if let batch = ring.newest(after: last, now: before, maximumAge: maximumAge) { last = batch.number }
from apps/rtvision (shortened)
Classes & model
DetectionReader.classIndex(of name: StaticString) -> Int? / .classByte(_:_:) / .classCountFind a class by name, read names.
Example
if let cup = ring.classIndex(of: "cup"), let best = batch.best(of: cup) { aim(best.centreX, best.centreY) }
Pattern (short, not copied from a program)
DetectionReader.latest / .modelGeneration / .modelNameNewest batch number; the generation rises when the model changes (look up classes again).

SwiftDetectionWriterPublishing detections (Video)

CallWhat it doesShape call · time budget
Classes & model
DetectionWriter.setClassName(_ index: Int, length: Int, _ byteAt: (Int) -> UInt8) / .classesDone(count: Int)Write class names once.
Example
publisher?.setClassName(classIndex, length: name.count) { name[$0] }
publisher?.classesDone(count: model.classNames.count)
from apps/video (shortened)
DetectionWriter.setModel(length: Int, _ byteAt: (Int) -> UInt8)Name of the active model (the generation rises).
Write
DetectionWriter.publish(_ batch: DetectionBatch) -> UInt32Write a batch as the next one; its number.
Example
publisher!.publish(batch)
from apps/video (shortened)
DetectionWriter.readers: IntHow many programs are reading right now.

SwiftDetectionBatch · Sighting · DetectionRingA batch of detections

CallWhat it doesShape call · time budget
Batch
DetectionBatch.number, .frame, .captured, .done, .width, .height, .count, .objects (up to 32)What an image showed.
DetectionBatch.best(of classIndex: Int) -> Sighting?Best hit of a class.
Object
Sighting(classIndex: Int, score: Double, x0: Double, y0: Double, x1: Double, y1: Double)An object: class, confidence, box as fractions of the image.
Example
batch.objects[batch.count] = Sighting(classIndex: detection.classIndex, score: Double(detection.score),
                                      x0: x0, y0: y0, x1: x1, y1: y1)
batch.count += 1
from apps/video (shortened)
Sighting.centreX / .centreYCentre of the box.
Ring format
DetectionRing.format(_:) / .magic / .version / .OffsetsLayout of the ring (one 16 KiB page).

For Reflex scriptsShape calls that Reflex scripts call directly by name

CallWhat it doesShape call · time budget
For Reflex and the kernel
vision.detectionsNewest detections (ring from Video).≤ 10 µsvision.detections0x0021_0001
vision.mask / vision.motion / vision.markersColour mask with blobs, motion between two images, AprilTag markers.≤ 2 msvision.mask0x0021_0002
camera.frame / camera.toWorld / camera.fromWorldNewest image; image ↔ world coordinates (calibration needed).≤ 2 µscamera.toWorld0x0020_0003
Example: fetching and decoding the newest camera image (apps/video, Pipeline.swift)
// manifest: capabilities = …, camera.use   publish = detections
var list: [CameraInfo] = []
var index = 0
while let info = Camera.info(at: index) { list.append(info); index += 1 }
ring = Camera.open(list[0].id)

func takeFrame() -> Bool {
    guard let ring else { return false }
    let taken = jpeg.withUnsafeMutableBytes { ring.newest(after: frame.number, into: $0) }
    guard let taken else { return false }
    guard case .success(let picture) = Picture.decode(Array(jpeg[0..<taken.count])) else { return false }
    // ... detect, draw
    return true
}
Example: publishing detections (apps/video)
nonisolated(unsafe) var publisher = Publications.detections()

var batch = DetectionBatch()
batch.frame = shown.number
batch.captured = shown.captured
batch.done = done
batch.width = width; batch.height = height
batch.objects[batch.count] = Sighting(classIndex: 3, score: 0.82, x0: 0.1, y0: 0.2, x1: 0.4, y1: 0.6)
batch.count += 1
publisher!.publish(batch)
Example: reading detections in a 1 kHz loop (apps/rtvision)
// manifest: realtime = 1000 200 log
//           subscribe = camera.detections
guard let ring = Publications.subscription(0) else {
    System.log("rtvision: no subscription (subscribe line missing)")
    return
}
var last: UInt32 = 0
while true {
    let now = System.time
    if let batch = ring.newest(after: last, now: now, maximumAge: 5_000_000_000) {
        last = batch.number
        // batch.objects[0..<batch.count], ring.classByte(classIndex, at) for the name
    }
    System.waitForNextPeriod()
}
All 67 declarations of this part (from docs/api/app-api-1.txt)
Camera.static func close(_ id: Int) -> Bool
Camera.static func info(at index: Int) -> CameraInfo?
Camera.static func open(_ id: Int) -> CameraRing?
CameraInfo.init()
CameraInfo.var frames: UInt32
CameraInfo.var id
CameraInfo.var name
CameraInfo.var nameLength
CameraInfo.var running
CameraInfo.var width
CameraRing.func newest(after: UInt32, into buffer: UnsafeMutableRawBufferPointer) -> (frame: UInt32, count: Int, time: UInt64)?
CameraRing.var height: Int
CameraRing.var latest: UInt32
CameraRing.var running: Bool
CameraRing.var width: Int
DetectionBatch.func best(of classIndex: Int) -> Sighting?
DetectionBatch.init()
DetectionBatch.static let most
DetectionBatch.var captured: UInt64
DetectionBatch.var count
DetectionBatch.var done: UInt64
DetectionBatch.var frame: UInt32
DetectionBatch.var number: UInt32
DetectionBatch.var objects
DetectionBatch.var width
DetectionReader.func classByte(_ index: Int, _ at: Int) -> UInt8
DetectionReader.func classIndex(of name: StaticString) -> Int?
DetectionReader.func newest(after: UInt32 = 0, now: UInt64, maximumAge: UInt64) -> DetectionBatch?
DetectionReader.init?(_ memory: M)
DetectionReader.let memory: M
DetectionReader.var classCount: Int
DetectionReader.var latest: UInt32
DetectionReader.var modelGeneration: UInt32
DetectionReader.var modelName: (bytes: InlineArray<24, UInt8>, length: Int)
DetectionRing.static func format<M: SharedWords>(_ memory: M)
DetectionRing.static let batchBytes
DetectionRing.static let batches
DetectionRing.static let batchesOffset
DetectionRing.static let bytes
DetectionRing.static let magic: UInt32
DetectionRing.static let modelGenerationOffset
DetectionRing.static let modelNameBytes
DetectionRing.static let modelNameOffset
DetectionRing.static let mostClasses
DetectionRing.static let nameBytes
DetectionRing.static let namesOffset
DetectionRing.static let readersOffset
DetectionRing.static let version: UInt32
DetectionWriter.func classesDone(count: Int)
DetectionWriter.func setClassName(_ index: Int, length: Int, _ byteAt: (Int) -> UInt8)
DetectionWriter.func setModel(length: Int, _ byteAt: (Int) -> UInt8)
DetectionWriter.init?(_ memory: M)
DetectionWriter.let memory: M
DetectionWriter.mutating func publish(_ batch: DetectionBatch) -> UInt32
DetectionWriter.var readers: Int
Sighting.init()
Sighting.init(classIndex: Int, score: Double, x0: Double, y0: Double, x1: Double, y1: Double)
Sighting.var centreX: Double
Sighting.var centreY: Double
enum Camera
enum DetectionRing
protocol SharedWords
struct CameraInfo
struct CameraRing
struct DetectionBatch
struct DetectionReader<M: SharedWords>
struct DetectionWriter<M: SharedWords>

robot · Arms, kinematics, actuator service, CAN

Movements are effects: programs never move motors themselves; they ask the actuator service (actuators, right safety.actuator) over the channel actuator (right channels.ipc). The service checks every movement against the safety limits (limits or refuses it) and talks to the motors over CAN. The emergency stop is held by the kernel itself: every program may read it; triggering and releasing it needs safety.stop. Programs see a generation that changes with every stop and every release (odd = stopped).

For arms there are models (SR-6, SO-101, UR5e, UR3e, FR3, xArm6, myCobot 280) with forward and inverse kinematics, a simulated gripper camera and simulated motors; the actuator service publishes the arm state (publish = arm).

Parts for system programs only: System-API › robot.

Rights

No right of its own: programs move the arm over the channel actuator to the actuator service (channels.ipc) and read its state as a publication (subscribe = …).

System callsrobotModule 0x0101 · Moving joints; safety limits and the emergency stop always apply.

CallRequest → answerRightTime budget · ID
robot.moveMove → Motionnone · computed in the program by Reflex≤ 20 µs0x0101_0001
robot.stateJointQuery → JointStatenone · computed in the program by Reflex≤ 5 µs0x0101_0002
robot.Move effectReflex effecteffect0x0101_0003
robot.moved eventMotionReflex eventevent0x0101_0004

System callsarmModule 0x0102 · The arm as a whole: forward/inverse kinematics, joints, torque.

CallRequest → answerRightTime budget · ID
arm.forwardAngles → ToolPosenone · computed in the program by Reflex≤ 2 µs0x0102_0001
arm.inverseReach → Anglesnone · computed in the program by Reflex≤ 20 µs0x0102_0002
arm.jointsJointsRequest → JointListnone · computed in the program by Reflex≤ 10 µs0x0102_0003
arm.torqueTorqueCommand → Donenone · not served by the kernel yet≤ 1 µs0x0102_0004
arm.TorqueCommand effectReflex effecteffect0x0102_0005

SwiftArmModelAn arm: joints, reach, tool

CallWhat it doesShape call · time budget
Choosing an arm
ArmModel.sr6 / .model(_ index: Int) -> ArmModelstaticThe simulated desk arm / model by index.
ArmModel.ids: InlineArray<7, StaticString>static"sr6", "so101", "ur5e", "ur3e", "fr3", "xarm6", "mycobot280".
ArmModel.chosen<let n: Int>(_ id: InlineArray<n, UInt8>, count: Int) -> ArmModel / .index(of:count:)staticArm from the bytes of arm = (Settings › Robot); SR-6 if empty.
Example
let model = ArmModel.chosen(state.id, count: state.idLength)
from apps/server (shortened)
Kinematics
ArmModel.forward(_ q: ArmAngles) -> ArmPoseJoint angles → points of the arm and tool pose.≤ 2 µsarm.forward0x0102_0001
Example
let pose = model.forward(q)   // pose.tip: ArmPoint in mm
Pattern (short, not copied from a program)
ArmModel.inverse(x: Double, y: Double, z: Double, pitch: Double, near: ArmAngles) -> ArmAngles?Tool tip to (x, y, z) with pitch, closest to near; nil if out of reach.≤ 20 µsarm.inverse0x0102_0002
Example
if let q = model.inverse(x: 300, y: 0, z: 120, pitch: -Maths.pi / 2, near: current) { goTo(q) }
Pattern (short, not copied from a program)
Joints & data
ArmModel.joint(_ index: Int) -> ArmJoint / .count / .jointsJoints (name, low, high, fastest, strongest, rest).≤ 10 µsarm.joints0x0102_0003
ArmModel.name, .maker, .id, .reach, .payload, .tool, .restAngles, .closedForm, .urdf …Description of the arm.

SwiftArmAngles · ArmPoint · ArmPose · ArmCameraAngles, points, poses, gripper camera

CallWhat it doesShape call · time budget
ArmAngles · ArmPoint · ArmPose · ArmCamera
ArmAngles() / .subscript(_ index: Int) -> DoubleJoint angles in radians (up to 7).
Example
var angles = ArmAngles()
angles[joint] = Double(state.positions[joint]) / 100 * Double.pi / 180
from apps/server (shortened)
ArmPoint(_ x: Double = 0, _ y: Double = 0, _ z: Double = 0)Point in world mm (x forward, y left, z up).
ArmPose.points, .pointCount, .tip, .approach, .pitchWhere the arm is.
ArmCamera(_ model: ArmModel, _ q: ArmAngles): toWorld(x:y:depth:) / .fromWorld(_:)Gripper camera 640 × 480: pixel ↔ world point.≤ 2 µscamera.toWorld0x0020_0003

SwiftSimulatedMotorsThe simulated motors (actuator service)

CallWhat it doesShape call · time budget
Creating
SimulatedMotors(_ model: ArmModel = .sr6)Arm in rest position.
Example
motors = SimulatedMotors(model)
from apps/actuators (shortened)
Controlling
SimulatedMotors.set(joint: Int, target value: Int32, speed limit: Int32)Target in 0.01° and speed.
Example
motors.set(joint: jointNumber - 1, target: grantedTarget, speed: grantedSpeed)
from apps/actuators (shortened)
SimulatedMotors.step(milliseconds: Int) / .emergencyStop(_ on: Bool)Simulate the movement / brake immediately.
State
SimulatedMotors.moving / .position / .velocity / .target / .speed / .stoppedState.

SwiftArmRing · ArmStateReading the arm state without a system call

CallWhat it doesShape call · time budget
Read
ArmRing.read<Ring: SharedWords>(_ ring: Ring) -> ArmState?Newest complete state (subscription subscribe = actuators.arm).
Example
guard let ring = Publications.subscriptionRing(0), let state = ArmRing.read(ring) else { return page }
from apps/server (shortened)
ArmState.positions, .moving, .stopped, .chosen, .id, .updatesJoint positions and flags.
Writing (service)
ArmRing.write(_:_:)Written by the actuator service.

SwiftCANFrameCAN and CAN FD frames over a channel

CallWhat it doesShape call · time budget
Building frames
CANFrame(identifier: UInt32, fd: Bool = true)Frames up to 64 data bytes.
Example
var setpoint = CANFrame(identifier: UInt32(0x100 + jointNumber))
setpoint.setInt32(grantedTarget, at: 0)
setpoint.setInt32(grantedSpeed, at: 4)
from apps/actuators (shortened)
CANFrame.int32(at offset: Int) -> Int32 / .setInt32(_:at:)Values in the frame (little-endian).
Sending & encoding
CANFrame.encode(into:) -> Int / .decode(_:count:) -> CANFrame?As a channel message.
Channel.send(_ frame: CANFrame) -> BoolSend a frame over a channel.
Example
_ = bus!.send(stop)   // stop: CANFrame(identifier: 0x000)
from apps/actuators (shortened)

For Reflex scriptsShape calls that Reflex scripts call directly by name

CallWhat it doesShape call · time budget
Moving
robot.moveStart a movement (effect; the actuator service carries it out).≤ 20 µsrobot.move0x0101_0001
robot.stateAngle, speed, current, temperature of a joint.≤ 5 µsrobot.state0x0101_0002
arm.torqueTorque for real-time control (real-time handlers only).≤ 1 µsarm.torque0x0102_0004
Example: moving joint 1 through the actuator service, emergency stop (apps/arm)
// manifest: capabilities = system.log, channels.ipc, ui.surface, safety.stop
guard var actuator = Channel("actuator") else { System.log("arm: no actuator channel"); return }

private func move(_ to: Int32, _ actuator: inout Channel) {
    var bytes = InlineArray<9, UInt8>(repeating: 0)
    bytes[0] = 1                                   // 1 = move
    let values: InlineArray<2, Int32> = [to, 3_000] // Target and speed in 0.01°
    for index in 0..<2 {
        let bits = UInt32(bitPattern: values[index])
        for byte in 0..<4 { bytes[1 + 4 * index + byte] = UInt8(truncatingIfNeeded: bits >> UInt32(8 * byte)) }
    }
    _ = actuator.send(bytes.span)
    actuator.notify()
}

// Answers: 2 = movement accepted/limited/refused, 3 = status of a joint
while let count = actuator.receive(into: &message), count >= 13 { /* ... */ }

// Emergency stop button:
System.emergencyStop(reason: 1)
// Release:
System.releaseEmergencyStop()
Example: reading the arm state and kinematics (apps/server, Live.swift)
// manifest: subscribe = actuators.arm
guard let ring = Publications.subscriptionRing(0), let state = ArmRing.read(ring) else { return }
let model = ArmModel.chosen(state.id, count: state.idLength)
var q = ArmAngles()
for joint in 0..<model.count {
    q[joint] = Double(state.positions[joint]) / 100 * Double.pi / 180   // 0.01° → radians
}
let pose = model.forward(q)                       // pose.tip, pose.points
if let reach = model.inverse(x: 300, y: 0, z: 120, pitch: -Maths.pi / 2, near: q) { _ = reach }
All 97 declarations of this part (from docs/api/app-api-1.txt)
ArmAngles.init()
ArmAngles.static func == (a: ArmAngles, b: ArmAngles) -> Bool
ArmAngles.subscript(_ index: Int) -> Double
ArmAngles.var values
ArmCamera.func fromWorld(_ p: ArmPoint) -> (x: Double, y: Double, depth: Double)?
ArmCamera.func toWorld(x: Double, y: Double, depth: Double?) -> ArmPoint?
ArmCamera.init(_ model: ArmModel, _ q: ArmAngles)
ArmCamera.static let focal
ArmCamera.static let width
ArmCamera.var position
ArmJoint.init(_ name: StaticString, _ low: Double, _ high: Double, fastest: Double, strongest: Double,
ArmJoint.var a
ArmJoint.var low: Double, high: Double, fastest: Double
ArmJoint.var name: StaticString
ArmJoint.var origin
ArmJoint.var rest
ArmJoint.var strongest: Double
ArmModel.func forward(_ q: ArmAngles) -> ArmPose
ArmModel.func inverse(x: Double, y: Double, z: Double, pitch: Double, near: ArmAngles) -> ArmAngles?
ArmModel.func joint(_ index: Int) -> ArmJoint
ArmModel.static func chosen<let n: Int>(_ id: InlineArray<n, UInt8>, count: Int) -> ArmModel
ArmModel.static func index<let n: Int>(of id: InlineArray<n, UInt8>, count: Int) -> Int?
ArmModel.static func model(_ index: Int) -> ArmModel
ArmModel.static let ids: InlineArray<7, StaticString>
ArmModel.static let maximumJoints
ArmModel.static let sr6
ArmModel.var base
ArmModel.var cameraBack
ArmModel.var closedForm: Bool
ArmModel.var count: Int
ArmModel.var id: StaticString
ArmModel.var index
ArmModel.var joints: InlineArray<7, ArmJoint>
ArmModel.var maker: StaticString
ArmModel.var modified: Bool
ArmModel.var name: StaticString
ArmModel.var payload
ArmModel.var reach
ArmModel.var restAngles: ArmAngles
ArmModel.var tool
ArmModel.var toolAxis
ArmModel.var toolOrigin
ArmModel.var urdf
ArmPoint.init(_ x: Double = 0, _ y: Double = 0, _ z: Double = 0)
ArmPoint.var x
ArmPose.var approach
ArmPose.var pitch
ArmPose.var pointCount
ArmPose.var points
ArmPose.var tip
ArmRing.static func read<Ring: SharedWords>(_ ring: Ring) -> ArmState?
ArmRing.static func write<Ring: SharedWords>(_ ring: Ring, _ state: ArmState)
ArmRing.static let magic: UInt32
ArmState.init()
ArmState.var chosen: Bool
ArmState.var count
ArmState.var flags: UInt32
ArmState.var id
ArmState.var idLength
ArmState.var moving: Bool
ArmState.var positions
ArmState.var stopped: Bool
ArmState.var updates: UInt32
CANFrame.func encode(into message: inout InlineArray<80, UInt8>) -> Int
CANFrame.func int32(at offset: Int) -> Int32
CANFrame.init()
CANFrame.init(identifier: UInt32, fd: Bool = true)
CANFrame.mutating func setInt32(_ value: Int32, at offset: Int)
CANFrame.static func decode(_ message: InlineArray<256, UInt8>, count: Int) -> CANFrame?
CANFrame.var data
CANFrame.var extended
CANFrame.var fd
CANFrame.var identifier: UInt32
CANFrame.var length
Channel.func send(_ frame: CANFrame) -> Bool
SimulatedMotors.init(_ model: ArmModel = .sr6)
SimulatedMotors.mutating func emergencyStop(_ on: Bool)
SimulatedMotors.mutating func set(joint: Int, target value: Int32, speed limit: Int32)
SimulatedMotors.mutating func step(milliseconds: Int)
SimulatedMotors.var count: Int
SimulatedMotors.var model: ArmModel
SimulatedMotors.var moving: Bool
SimulatedMotors.var position
SimulatedMotors.var speed
SimulatedMotors.var stopped
SimulatedMotors.var target
SimulatedMotors.var velocity
enum ArmRing
struct ArmAngles: Equatable, Sendable
struct ArmCamera
struct ArmJoint: Sendable
struct ArmModel: Sendable
struct ArmPoint: Sendable
struct ArmPose: Sendable
struct ArmState
struct CANFrame
struct SimulatedMotors

safety · The emergency stop

The kernel itself holds the emergency stop. Every program may read it (safety.state, no right); only programs with safety.stop may trigger and release it, and only the actuator service holds safety.actuator. Programs see a generation that changes with every stop and every release (odd = stopped).

Parts for system programs only: System-API › safety.

Rights

No right needed to read the emergency stop.

System callssafetyModule 0x0100 · The emergency stop (reading is free, stop/release with safety.stop).

CallRequest → answerRightTime budget · ID
safety.stateSafetyQuery → SafetyStatenone≤ 2 µs0x0100_0001

SwiftSystemReading the emergency stop

CallWhat it doesShape call · time budget
Reading the state
System.emergencyStopped: BoolIs the emergency stop in effect right now?≤ 2 µssafety.state0x0100_0001
Example
let stopped = System.emergencyStopped
from apps/arm (shortened)
System.safetyGeneration: UInt64Changes with every stop and every release; odd = stopped.≤ 2 µssafety.state0x0100_0001
Example
let now = System.safetyGeneration
if now != safety { safety = now; motors.emergencyStop(now & 1 == 1) }
from apps/actuators (shortened)
System.safetyState: SafetyStategeneration, stopped, sinceStop.≤ 2 µssafety.state0x0100_0001
System.microsecondsSinceStop: UInt64µs since the last stop.≤ 2 µssafety.state0x0100_0001

For Reflex scriptsShape calls that Reflex scripts call directly by name

CallWhat it doesShape call · time budget
Emergency stop
safety.state / stop / releaseRead, trigger, release the emergency stop.≤ 20 µssafety.stop0x0100_0002
All 4 declarations of this part (from docs/api/app-api-1.txt)
System.static var emergencyStopped: Bool
System.static var microsecondsSinceStop: UInt64
System.static var safetyGeneration: UInt64
System.static var safetyState: SafetyState

channels · Channels between programs, publications

With channels.ipc: two programs that open the same name share a page with a message ring in each direction (messages up to 256 bytes). Waking and waiting are primitive system calls (channelNotify, channelWait). If the other side runs on another CPU, receiveWaiting first polls the ring briefly – usually it answers within microseconds. This is also how robot programs talk to the actuator service (actuator) and drivers to each other (CAN frames).

Publications: a program with publish = … writes a ring that programs with subscribe = … read without a system call (Camera's detections, the actuator service's arm state).

Rights

RightMeaningShape call · time budget
channels.ipcOpen channels between programs.≤ 1 mschannels.open0x000A_0001

System callschannelsModule 0x000A · Message channels between programs (channels.ipc).

CallRequest → answerRightTime budget · ID
channels.openChannelName → ChannelOpenedchannels.ipc≤ 1 ms0x000A_0001

System callspeersModule 0x0110 · Robots nearby (reserved for later).

CallRequest → answerRightTime budget · ID
peers.listPeersRequest → PeerListnone · not served by the kernel yetno budget0x0110_0001
peers.sendEnvelope → Deliverednone · not served by the kernel yetno budget0x0110_0002
peers.received eventEnvelopeReflex eventevent0x0110_0003

SwiftChannelA channel

CallWhat it doesShape call · time budget
Open
Channel.init?(_ name: StaticString)Open or join a channel; nil without channels.ipc.≤ 1 mschannels.open0x000A_0001
Example
guard var channel = Channel("bench") else { System.log("ipcping: channel refused"); return }
from apps/ipcping (shortened)
Channel.handle: UInt64Number of the channel.
Sending
Channel.send(_ message: Span<UInt8>) -> BoolQueue a message (at most 256 bytes); false if the ring is full.
Example
while !channel.send(message.span) { System.yield() }
from apps/ipcping (shortened)
Channel.send(_ frame: CANFrame) -> BoolSend a CAN frame.
Channel.notify()Wake the other side.channelNotify (system call 8)
Example
_ = actuator.send(bytes.span)
actuator.notify()
from apps/arm (shortened)
Receiving
Channel.receive(into out: inout InlineArray<256, UInt8>) -> Int?Oldest received message or nil (does not wait).
Example
while let count = actuator.receive(into: &message), count >= 13 { /* evaluate the answer */ }
from apps/arm (shortened)
Channel.receiveWaiting(into out: inout InlineArray<256, UInt8>) -> IntBlocks until a message arrives (lost wake-ups are caught).channelWait (system call 9)
Example
let count = channel.receiveWaiting(into: &reply)
from apps/ipcping (shortened)
Channel.receivePolling(into out: inout InlineArray<256, UInt8>, microseconds: UInt64 = 30) -> Int?Next message if it arrives within µs (only when the other side is on another CPU).
Example
if open.receivePolling(into: &answer) != nil { return true }
from apps/benchmark (shortened)
Channel.peerOnSameCPU: BoolWhether the other side ran on this program's CPU at the last notify(); then polling for its answer only delays it, and a round trip takes 6-8 µs instead of 1.2-1.7 µs (F184).
Channel.wait(timeout: UInt64)Sleeps until a wake-up or timeout; may return earlier.channelWait (system call 9)
Example
channel!.wait(timeout: 50_000_000)
from apps/develop (shortened)

SwiftPublicationsPublishing and subscribing (publish =, subscribe =)

CallWhat it doesShape call · time budget
Publishing
Publications.detections() -> DetectionWriter<SharedRing>?staticThe program's own detection ring for writing; nil without publish =.
Example
nonisolated(unsafe) var publisher = Publications.detections()
from apps/video (shortened)
Subscribing
Publications.subscription(_ index: Int = 0) -> DetectionReader<SharedRing>?staticThe index-th subscription (0 or 1, order in the manifest).
Example
guard let ring = Publications.subscription(0) else { System.log("rtvision: no subscription (subscribe line missing)"); return }
from apps/rtvision (shortened)
Raw rings
Publications.ownRing() -> SharedRing? / Publications.subscriptionRing(_ index: Int) -> SharedRing?staticThe same rings as raw words (for other formats, e.g. the arm ring).

SwiftSharedPage · SharedRingRaw shared words

CallWhat it doesShape call · time budget
Raw shared words
SharedPage.load / .store / .loadAcquire / .storeReleaseThe channel page word by word (ordered accesses).
SharedRing.load32 / .store32 / .loadAcquire32 / .storeRelease32 / .barrierA publication word by word.
Example: there and back over the channel "bench" (apps/ipcping)
// manifest: capabilities = system.log, channels.ipc
guard var channel = Channel("bench") else {
    System.log("ipcping: channel refused")
    return
}
var reply = InlineArray<256, UInt8>(repeating: 0)
var message = InlineArray<64, UInt8>(repeating: 0x42)
for round in 0..<2_000 {
    message[0] = UInt8(truncatingIfNeeded: round)
    while !channel.send(message.span) { System.yield() }
    channel.notify()
    let count = channel.receiveWaiting(into: &reply)
    guard count == 64, reply[0] == message[0] else { System.log("ipcping: wrong reply"); return }
}
All 27 declarations of this part (from docs/api/app-api-1.txt)
Channel.func receive(into out: inout InlineArray<256, UInt8>) -> Int?
Channel.func receivePolling(into out: inout InlineArray<256, UInt8>, microseconds: UInt64 = 30) -> Int?
Channel.func receiveWaiting(into out: inout InlineArray<256, UInt8>) -> Int
Channel.func send(_ message: Span<UInt8>) -> Bool
Channel.func wait(timeout: UInt64)
Channel.init?(_ name: StaticString)
Channel.let handle: UInt64
Channel.mutating func notify()
Channel.private(set) var peerOnSameCPU
Publications.static func detections() -> DetectionWriter<SharedRing>?
Publications.static func ownRing() -> SharedRing?
Publications.static func subscription(_ index: Int = 0) -> DetectionReader<SharedRing>?
Publications.static func subscriptionRing(_ index: Int) -> SharedRing?
SharedPage.func load(_ offset: Int) -> UInt32
SharedPage.func loadAcquire(_ offset: Int) -> UInt32
SharedPage.func store(_ offset: Int, _ value: UInt32)
SharedPage.func storeRelease(_ offset: Int, _ value: UInt32)
SharedPage.let base: UInt64
SharedRing.func barrier()
SharedRing.func load32(_ offset: Int) -> UInt32
SharedRing.func loadAcquire32(_ offset: Int) -> UInt32
SharedRing.func store32(_ offset: Int, _ value: UInt32)
SharedRing.func storeRelease32(_ offset: Int, _ value: UInt32)
enum Publications
struct Channel
struct SharedPage: RingMemory
struct SharedRing: SharedWords

clipboard · Copy and paste

Text up to 64 KiB, one for the whole system. Every program with a window may copy; it may read only right after the owner has chosen “Paste” in that program (the display service grants one read access within two seconds). No program can watch the clipboard. The standard Edit menu (addEditMenu) and InputField take care of this on their own.

Parts for system programs only: System-API › clipboard.

Rights

No right of its own: copying needs a window (ui.surface); pasting only right after the owner's choice.

System callsclipboardModule 0x0012 · Copy and paste.

CallRequest → answerRightTime budget · ID
clipboard.copyClipText → Doneui.surface≤ 50 µs0x0012_0001
clipboard.pastePasteRequest → ClipTextnone≤ 50 µs0x0012_0002
clipboard.generationPasteRequest → ClipGenerationnone≤ 2 µs0x0012_0004

SwiftClipboardCopying, pasting

CallWhat it doesShape call · time budget
Copying
Clipboard.copy(_ text: Span<UInt8>) -> BoolstaticText (UTF-8, at most 64 KiB) to the clipboard.≤ 50 µsclipboard.copy0x0012_0001
Example
_ = Clipboard.copy(text.span.extracting(0..<length))
from apps/console (shortened)
Clipboard.generation: UInt64staticCounter that grows with every copy (the Mac bridge).≤ 2 µsclipboard.generation0x0012_0004
Pasting
Clipboard.paste(into buffer: inout MutableSpan<UInt8>) -> IntstaticReads into buffer; 0 if empty or not granted right now.≤ 50 µsclipboard.paste0x0012_0002
Example
var buffer = [UInt8](repeating: 0, count: 64 * 1024)
var span = buffer.mutableSpan
let length = Clipboard.paste(into: &span)
from apps/develop (shortened)
Example: copy and paste in the editor (apps/develop)
switch id {
case EditMenu.copy, EditMenu.cut:
    guard Editor.hasSelection else { return }
    let bytes = Editor.selectedBytes
    _ = bytes.withUnsafeBufferPointer { Clipboard.copy(Span(_unsafeElements: $0)) }
    if id == EditMenu.cut { Editor.insert([]) }
case EditMenu.paste:
    var buffer = [UInt8](repeating: 0, count: 64 * 1024)
    var span = buffer.mutableSpan
    let length = Clipboard.paste(into: &span)
    _ = span
    guard length > 0 else { return }
    Editor.insert(Array(buffer[0..<length]))
default: break
}
All 4 declarations of this part (from docs/api/app-api-1.txt)
Clipboard.static func copy(_ text: Span<UInt8>) -> Bool
Clipboard.static func paste(into buffer: inout MutableSpan<UInt8>) -> Int
Clipboard.static var generation: UInt64
enum Clipboard

dialog · Opening and saving through the system

File dialog (new, 10 Nov): “choosing is allowing”. The program asks with Dialog.open or Dialog.save; the system program chooser shows the dialog; what the person picks becomes a grant (FileGrant) for exactly that file – opened with Files.Handle.open(grant, mode:), with no file right at all in the manifest. The dialog shows the program's own folder, the shared documents and, in the VM, the Mac folder – never the folders of other programs. One question per program at a time; up to 16 grants while the program runs. Not for real-time programs.

Parts for system programs only: System-API › dialog.

Rights

No right of its own: asking needs a window (ui.surface); the chosen file opens without a file right.

System callsdialogModule 0x0013 · The system's open and save dialog (new, 10 Nov).

CallRequest → answerRightTime budget · ID
dialog.ask newDialogAsk → DialogTicketui.surface≤ 1 ms0x0013_0001
dialog.result newDialogTicket → DialogResultnone≤ 20 µs0x0013_0002

SwiftDialogAsking and fetching the answer

CallWhat it doesShape call · time budget
Open
Dialog.open(types: StaticString = "", action: StaticString = "") -> Boolstatic newAsks for a file to open; types = extensions separated by spaces ("wav flac"; empty: everything from opens). Returns immediately; false if a dialog is already open.≤ 1 msdialog.ask0x0013_0001
Example
_ = Dialog.open(types: "reflex srshare", action: "Import")
from apps/develop (shortened)
Save
Dialog.save(name: TextLine, formats: StaticString, action: StaticString = "") -> Boolstatic newAsks where to save; formats one line per format "Label=extension"; action = word on the button ("Export").≤ 1 msdialog.ask0x0013_0001
Example
if !Dialog.save(name: suggested, formats: "Script package=srshare", action: "Share") { Runner.note("A file dialog is open already.", .warning) }
from apps/develop (shortened)
Fetching the answer
Dialog.answer() -> Answer?static newThe answer as soon as there is one (cheap, ask on every loop pass): .chosen(FileGrant) or .cancelled; nil while open.≤ 20 µsdialog.result0x0013_0002
Example
if let answer = Dialog.answer() { Share.answered(answer); dirty = true }
from apps/develop (shortened)
enum Dialog.Answer { case chosen(FileGrant), cancelled } newResult of the question.
State
Dialog.isOpen: Boolstatic newIs a dialog of this program on the screen right now?
Example
if Dialog.isOpen { return }   // do not ask a second time
Pattern (short, not copied from a program)
Dialog.lastWasSavestatic newWas the last question a save (to tell answers apart)?
Example
if case .chosen(let grant)? = Dialog.answer() {
    if Dialog.lastWasSave { save(to: grant) } else { load(grant) }
}
Pattern (short, not copied from a program)

SwiftFileGrantA grant for exactly one file

CallWhat it doesShape call · time budget
Grant
FileGrant.number: Int newNumber of the grant (1 … 16).
FileGrant.name: TextLine newChosen file name.
FileGrant.place: DialogPlace newWhere it is: own folder, Documents or Mac folder.
FileGrant.format newWhen saving: index of the chosen format.
Opening a file
Files.Handle.open(_ grant: FileGrant, mode: Mode) -> Result<Files.Handle, FileError> newOpens the granted file (read or write) – without a file right.≤ 2 msfiles.open0x0003_0001
Example
guard case .success(let file) = Files.Handle.open(grant, mode: .replace) else { return false }
from apps/develop (shortened)
Example: File menu with “Open…” and the answer in the loop (apps/reader)
surface.addFileMenu(open: true)
surface.addEditMenu(1)
surface.addMenu(2, "View")
surface.addItem(2, "Zoom In", id: Item.zoomIn, key: 0x2B, icon: .zoomIn)   // +
surface.addItem(2, "Zoom Out", id: Item.zoomOut, key: 0x2D, icon: .zoomOut) // -
surface.publishMenus()

while true {
    while let event = surface.nextEvent() {
        switch event {
        case .menu(let id):
            if id == FileMenu.open { _ = Dialog.open(types: "pdf") }
            else if menu(id, surface.canvas) { dirty = true }
        default: break
        }
    }
    if case .chosen(let grant)? = Dialog.answer() {
        load(grant.name, grant: grant)          // Files.Handle.open(grant, mode: .read)
        dirty = true
    }
    // ... draw, wait
}
Example: exporting as CSV or JSON (apps/database)
surface.addFileMenu(export: true)

// Menu item Export…:
if !Dialog.save(name: suggested, formats: "CSV=csv\nJSON=json", action: "Export") {
    status = TextLine("A file dialog is open already")
}

// in the loop:
if case .chosen(let grant)? = Dialog.answer() {
    exportRows(json: grant.format == 1, to: grant)
}

func exportRows(json: Bool, to grant: FileGrant) {
    guard case .success(let file) = Files.Handle.open(grant, mode: .replace) else {
        status = TextLine("The export file cannot be written")
        return
    }
    // ... file.write(...), file.close()
}
All 12 declarations of this part (from docs/api/app-api-1.txt)
Dialog.enum Answer
Dialog.nonisolated(unsafe) private(set) static var lastWasSave
Dialog.static func answer() -> Answer?
Dialog.static func open(types: StaticString = "", action: StaticString = "") -> Bool
Dialog.static func save(name: TextLine, formats: StaticString, action: StaticString = "") -> Bool
Dialog.static var isOpen: Bool
FileGrant.let number: Int
FileGrant.var format
FileGrant.var name
FileGrant.var place
enum Dialog
struct FileGrant

update · System updates

Not part of the App-API: every call of this module needs a right that only system programs get. See System-API › update.

protection · Device protection

Not part of the App-API: every call of this module needs a right that only system programs get. See System-API › protection.

Reflex scripts (Develop)

Reflex is the language of Develop: one event in, one reaction out. A Reflex program calls the Shape modules directly by name (robot.move, vision.detections) – without Swift. Every line names its module; from these the compiler collects the modules and thus the rights, which go into the signed manifest when the program is saved. Programs built by Develop get at most: log, window, sound, camera and detections, microphone, their own folder, network only if allowed, and the robot within its limits through the actuator service – never system rights.

Building blocks: state, on module.event(…) -> State, every 200 ms, realtime every 1 ms (Develop proves the worst-case time, at most 80 % of the period), emit module.call(…) for effects, func, screen { … }, test. Units are part of the types (40°, 0.4 s, 880 Hz).

The system calls that Reflex calls by name are listed with their right in the modules above (robot, arm, vision, camera, sound, microphone, signal, screen, ask).

Reflexon …Events

CallWhat it doesShape call · time budget
Program
on start / on stopProgram starts / should stop (last chance to save).eventsystem.start0x0002_0007
every 200 msTimer.
Seeing & hearing
on vision.detections(seen: Detections)New detections from Video.≤ 10 µsvision.detections0x0021_0001
on microphone.loud(heard: Loudness)Louder than a level (bang, stalling motor).eventmicrophone.loud0x0031_0008
on microphone.voice(change: VoiceChange)Speech started or ended.eventmicrophone.voice0x0031_0009
on camera.frame(…)A new camera image.≤ 10 µscamera.frame0x0020_0002
Robot
on robot.moved(m: Motion)A movement ended (reached, limited or stopped).eventrobot.moved0x0101_0004
Window
on Name() (button in screen)A button of the window was pressed.eventscreen.pressed0x0010_0003

Reflexemit …Calls & effects

CallWhat it doesShape call · time budget
Robot
emit robot.move(joint:, to:, in:)Move a joint (within the limits of the actuator service).≤ 20 µsrobot.move0x0101_0001
robot.state(joint:)State of a joint (also in the real-time handler, from the ring).≤ 5 µsrobot.state0x0101_0002
arm.forward / arm.inverse / arm.jointsKinematics of the arm.≤ 20 µsarm.inverse0x0102_0002
Sound & image
emit sound.tone(pitch:, length:)A tone.≤ 20 µssound.tone0x0030_0001
camera.toWorld(p)Image point → world point.≤ 2 µscamera.toWorld0x0020_0003
Computing & asking
signal.spectrum / filter / stats / sineSpectra and filters over measurement series.≤ 500 µssignal.spectrum0x0040_0001
ask.claude(…)Ask a cloud AI (through its API, with the owner's key from Settings › Privacy).no budgetask.claude0x0050_0001
Window
screen { Title Text Big Button Slider Chart Picture Row Column }Window as a description; the appearance comes from the system.≤ 200 µsscreen.show0x0010_0001
Example: clapping stops the arm (apps/develop/examples/clap-stop.reflex)
state Listener {
    bangs: Int32 = 0
    lastBang: Time = 0
    talking: Bool = false
}

/// A bang: hold the arm (every joint stays where it is) and beep.
on microphone.loud(heard: Loudness) -> Listener {
    if isBang(level: heard.peak) and heard.taken - lastBang > 1 s {
        emit robot.move(joint: 1, to: 0°, in: 2 s)
        emit sound.tone(pitch: 660 Hz, length: 150 ms)
        return self with { bangs: bangs + 1, lastBang: heard.taken }
    }
    return self
}

on microphone.voice(change: VoiceChange) -> Listener {
    if change.speaking and not talking {
        emit robot.move(joint: 5, to: 20°, in: 0.3 s)
    }
    return self with { talking: change.speaking }
}

func isBang(BangLevel { level: Float32 }) -> Bool { return level > -6 }

test "a clap is a bang" { expect isBang(level: -3) }
Example: real-time handler, proven by Develop (apps/develop/guide/6-realtime.reflex)
state Hold {
    target: Angle = 30°
    periods: Int32 = 0
}

realtime every 1 ms -> Hold {
    let joint = robot.state(joint: 1)
    if periods % 20 == 0 {
        emit robot.move(joint: 1, to: joint.angle + step(gap: target - joint.angle).value, in: 20 ms)
    }
    return self with { periods: periods + 1 }
}

func step(Gap { gap: Angle }) -> Turn {
    if gap > 1° { return Turn(value: 1°) }
    if gap < -1° { return Turn(value: -1°) }
    return Turn(value: gap)
}

shape Turn { value: Angle }

System-API

For system programs only – not part of the App-API, may change

This part lists what system programs need: everything that requires a right outside the 9 rights a normal program, not signed by the system, can have (Capability.fromDevelop in kernel/lib/AppManifest.swift: camera.use, channels.ipc, files.own, network.outgoing, sound.microphone, sound.play, system.log, system.status, ui.surface). Only a program with the system's key gets such rights; a manifest that asks for them for a program in /apps is refused.

These calls are not part of the App-API: they are not frozen at 1.0 and may change. This part is organised by the same modules as the App-API.

Rights23 rights for system programs only

RightModule
system.log.readsystem
system.powersystem
system.privacysystem
system.timesystem
programs.buildprograms
programs.launchprograms
files.macfiles
files.systemfiles
database.editdatabase
network.incomingnetwork
ui.displayui
ui.inputui
ui.input.provideui
sound.microphone.providesound
sound.volumesound
camera.providecamera
device.canrobot
device.usbrobot
safety.actuatorsafety
safety.stopsafety
files.dialogdialog
system.updateupdate
system.protectionprotection

system · Information, time, log, real time, text

For system programs only – not part of the App-API, may change

Setting the clock (the time service, system.time), switching off and restarting (system.power), reading the system log (Console, Activity: system.log.read) and setting secrets such as API keys (Settings: system.privacy).

What every program may use of it: App-API › system.

Rights

RightMeaningShape call · time budget
system.log.readRead the system log (Console, Activity).≤ 20 µssystem.readLog0x0002_0005
system.timeSet the system clock (time service via NTS).≤ 5 µssystem.adjustClock0x0002_000A
system.powerSwitch off and restart.no budgetsystem.power0x0002_0004
system.privacySet secrets such as API keys for programs (Settings).≤ 5 msprograms.setSecret0x0006_0004

System callssystemModule 0x0002 · The robot itself: info, time, log, power, randomness, processors, worker threads; events start/stop.

CallRequest → answerRightTime budget · ID
system.powerPowerRequest → Donesystem.powerno budget0x0002_0004
system.readLogLogRead → LogTextsystem.log.read≤ 20 µs0x0002_0005
system.adjustClockClockAdjust → Nowsystem.time≤ 5 µs0x0002_000A

System callsSystemCallprimitive system calls (enum SystemCall)

NameWhat it doesRightNumber
deviceWaitDriver: wait for an interruptdevice.usb10
inputReceiveDisplay service: fetch inputui.input12

SwiftSystemSetting the clock, power

CallWhat it doesShape call · time budget
Time
System.adjustClock(byMilliseconds offset: Int64) -> UInt64?Adjust the clock (system.time).≤ 5 µssystem.adjustClock0x0002_000A
Power
System.power(restart: Bool)Off or restart (system.power); returns only if refused.no budgetsystem.power0x0002_0004

SwiftProgramsReading the system log (system.log.read)

CallWhat it doesShape call · time budget
Reading the log
Programs.logEnd / Programs.logLine(from:into:)Follow the system log (system.log.read).≤ 20 µssystem.readLog0x0002_0005
Example
var position = Programs.logEnd
var line = InlineArray<160, UInt8>(repeating: 0)
while let length = Programs.logLine(from: &position, into: &line) { /* line[0..<length] */ }
Pattern (short, not copied from a program)
All 4 declarations of this part (from docs/api/app-api-1.txt)
Programs.static func logLine(from position: inout UInt64, into line: inout InlineArray<160, UInt8>) -> Int?
Programs.static var logEnd: UInt64
System.static func adjustClock(byMilliseconds offset: Int64) -> UInt64?
System.static func power(restart: Bool)

programs · The program itself, settings, other programs

For system programs only – not part of the App-API, may change

Starting, stopping and listing other programs, reading their signature and crashes, deleting them (desktop, Console, Files, Activity: programs.launch) and building programs from scripts (Develop: programs.build).

What every program may use of it: App-API › programs.

Rights

RightMeaningShape call · time budget
programs.launchStart, stop and list programs, hand over documents, read crashes.≤ 50 msprograms.launch0x0006_0007
programs.buildBuild programs from scripts with this robot's key (Develop).≤ 3 sprograms.build0x0006_0010

System callsprogramsModule 0x0006 · The program itself and the others: document, Settings, secret, start/stop, lists, crashes, building.

CallRequest → answerRightTime budget · ID
programs.setSecretSecretWrite → Donesystem.privacy≤ 5 ms0x0006_0004
programs.hasSecretSecretQuery → SecretPresencesystem.privacy≤ 2 ms0x0006_0005
programs.launchProgramName → Doneprograms.launch≤ 50 ms0x0006_0007
programs.stopProgramName → Doneprograms.launch≤ 50 µs0x0006_0008
programs.openOpenDocument → Doneprograms.launch (+ files.system for files not its own)≤ 50 ms0x0006_0009
programs.runningProgramListQuery → RunningProgramsprograms.launch≤ 50 µs0x0006_000A
programs.installedProgramListQuery → InstalledProgramsprograms.launch≤ 20 ms0x0006_000B
programs.presentationProgramName → ProgramLookprograms.launch≤ 5 ms0x0006_000C
programs.crashesProgramListQuery → CrashListprograms.launch≤ 20 µs0x0006_000D
programs.signatureProgramName → SignatureCheckprograms.launch≤ 50 ms0x0006_000F
programs.buildBuildProgram → BuiltProgramprograms.build≤ 3 s0x0006_0010
programs.signShareSharePackage → ShareSignatureprograms.build≤ 20 ms0x0006_0011
programs.checkShareSharePackage → ShareCheckprograms.build≤ 20 ms0x0006_0012
programs.uninstallUninstall → Donefiles.system + programs.launch≤ 3 s0x0006_0013
programs.leftoversProgramListQuery → Leftoversfiles.system≤ 50 ms0x0006_0014
programs.deleteLeftoverLeftoverDelete → Donefiles.system + programs.launch≤ 3 s0x0006_0015

SwiftProgramsStarting, stopping, lists, crashes, signature, deleting

CallWhat it doesShape call · time budget
Starting & stopping
Programs.launch(_ name: Span<UInt8>) -> FileError?Start a system program or app (programs.launch).≤ 50 msprograms.launch0x0006_0007
Example
_ = callcost.withUTF8Buffer { Programs.launch(Span(_unsafeElements: $0)) }
from apps/apicheck (shortened)
Programs.stop(_ name: Span<UInt8>) -> FileError?Stop a running program (not services).≤ 50 µsprograms.stop0x0006_0008
Example
return Programs.stop(name.span.extracting(0..<count)) == nil
from apps/activity (shortened)
Programs.open(_ program: Span<UInt8>, document path: Span<UInt8>) -> FileError?Start a program with a document or hand the document to it.≤ 50 msprograms.open0x0006_0009
Example
return Programs.open(program.span, document: path.span) == nil
from apps/files (shortened)
Lists
Programs.running(at index: Int) -> Running?The index-th running program (index 0 asks afresh).≤ 50 µsprograms.running0x0006_000A
Example
while let program = Programs.running(at: index) { index += 1 }
from apps/console (shortened)
Programs.installed(at index: Int) -> Running?The index-th installed program.≤ 20 msprograms.installed0x0006_000B
Example
while let entry = Programs.installed(at: index) { index += 1 }
from apps/display (shortened)
Programs.Running: name, id, version, kind, realtime, period, missed, worstLatency, onDemand, helper, seesCamera, hearsMicrophone …What an entry shows.
Programs.Running.hiddenFromDock newInstalled with dock = no.
Crashes & signature
Programs.crash(at index: Int) -> Crash?The last 8 crashes, newest first: name, reason, sequence, wallClock, pc, memoryLimit, reportPath.≤ 20 µsprograms.crashes0x0006_000D
Example
while let crash = Programs.crash(at: index) { System.log(crash.reportPath); index += 1 }
Pattern (short, not copied from a program)
Programs.signature(of name: Span<UInt8>) -> SignatureState?Check the signature as at start.≤ 50 msprograms.signature0x0006_000F
Programs.presentation(of name: Span<UInt8>, into buffer: UnsafeMutableRawPointer) -> Presentation?Title, group and symbol of a program (Dock).≤ 5 msprograms.presentation0x0006_000C
Deleting
Programs.uninstall(_ name: Span<UInt8>, deleteData: Bool, password: Span<UInt8>) -> TextLine?Delete a program from /apps (owner's password; files.system + programs.launch).≤ 3 sprograms.uninstall0x0006_0013
Programs.leftover(at:) / Programs.deleteLeftover(_:password:)Data folders of deleted programs.≤ 50 msprograms.leftovers0x0006_0014
Example: listing the last crashes (programs.launch)
var index = 0
while let crash = Programs.crash(at: index) {
    var line = TextLine()
    for i in 0..<crash.nameLength { line.append(byte: crash.name[i]) }
    line.append(": ")
    line.append(crash.reportPath)
    System.log(line)
    index += 1
}
All 53 declarations of this part (from docs/api/app-api-1.txt)
Programs.Crash.init()
Programs.Crash.var memoryLimit: UInt64
Programs.Crash.var name
Programs.Crash.var nameLength
Programs.Crash.var pc: UInt64
Programs.Crash.var reason
Programs.Crash.var reportPath: TextLine
Programs.Crash.var sequence: UInt64
Programs.Crash.var wallClock: Int64
Programs.Leftover.var deleted: Int64
Programs.Leftover.var id
Programs.Leftover.var idLength
Programs.Leftover.var size: UInt64
Programs.Leftover.var version: UInt64
Programs.Presentation.var category
Programs.Presentation.var iconLength
Programs.Presentation.var title
Programs.Presentation.var titleRefused
Programs.Running.var hearsMicrophone
Programs.Running.var helper
Programs.Running.var hiddenFromDock
Programs.Running.var id
Programs.Running.var idLength
Programs.Running.var kind
Programs.Running.var missed: UInt64
Programs.Running.var name
Programs.Running.var nameLength
Programs.Running.var onDemand
Programs.Running.var period: UInt64
Programs.Running.var periods: UInt64
Programs.Running.var realtime
Programs.Running.var seesCamera
Programs.Running.var sends
Programs.Running.var slot
Programs.Running.var version: UInt64
Programs.Running.var worstLatency: UInt64
Programs.static func crash(at index: Int) -> Crash?
Programs.static func deleteLeftover(_ id: Span<UInt8>, password: Span<UInt8>) -> TextLine?
Programs.static func installed(at index: Int) -> Running?
Programs.static func launch(_ name: Span<UInt8>) -> FileError?
Programs.static func leftover(at index: Int) -> Leftover?
Programs.static func open(_ program: Span<UInt8>, document path: Span<UInt8>) -> FileError?
Programs.static func presentation(of name: Span<UInt8>, into buffer: UnsafeMutableRawPointer) -> Presentation?
Programs.static func running(at index: Int) -> Running?
Programs.static func signature(of name: Span<UInt8>) -> SignatureState?
Programs.static func stop(_ name: Span<UInt8>) -> FileError?
Programs.static func uninstall(_ name: Span<UInt8>, deleteData: Bool, password: Span<UInt8>) -> TextLine?
Programs.static let presentationBytes
Programs.static let presentationIcon
Programs.struct Crash
Programs.struct Leftover
Programs.struct Presentation
Programs.struct Running

files · Files and folders

For system programs only – not part of the App-API, may change

The whole DATA volume (files.system: Console, Files), the Mac folder in the VM (files.mac), snapshots for the time slider and “show in Files”.

What every program may use of it: App-API › files.

Rights

RightMeaningShape call · time budget
files.systemThe whole DATA volume (/apps read-only), snapshots.≤ 50 µsfiles.snapshot0x0003_000C
files.macIn addition the Mac folder mac/… (SOFTrobotsVM only).

System callsfilesModule 0x0003 · The program's files, folders, volume and snapshots.

CallRequest → answerRightTime budget · ID
files.revealFileQuery → Doneprograms.launch + files.ownno budget0x0003_000A
files.snapshotSnapshotQuery → SnapshotInfofiles.system≤ 50 µs0x0003_000C
files.takeSnapshotSnapshotQuery → SnapshotInfofiles.system≤ 50 ms0x0003_000D
files.deleteSnapshotSnapshotQuery → Donefiles.system≤ 50 ms0x0003_000E
files.restoreRestoreFile → Restoredfiles.system≤ 2 s0x0003_000F

SwiftFilesShowing in Files (programs.launch + files.own)

CallWhat it doesShape call · time budget
Showing
Files.reveal(_ path: Span<UInt8>) -> FileError?staticShows a file from the program's own folder in Files (web downloads; needs programs.launch).no budgetfiles.reveal0x0003_000A
Example
_ = name.withUnsafeBufferPointer { Files.reveal(Span(_unsafeElements: $0)) }   // e.g. "downloads/x.pdf"
Pattern (short, not copied from a program)

SwiftFilesSnapshots, the time slider (files.system)

CallWhat it doesShape call · time budget
Snapshots
Files.snapshot(after previous: UInt64) -> Snapshot?staticThe snapshot after previous (0: the oldest).≤ 50 µsfiles.snapshot0x0003_000C
Example
while let next = Files.snapshot(after: previous) { list.append(next); previous = next.id }
from apps/files (shortened)
Files.takeSnapshot() -> Result<UInt64, FileError>staticTake a snapshot now (kept until deleted).≤ 50 msfiles.takeSnapshot0x0003_000D
Example
if case .success(let id) = Files.takeSnapshot() { kept = id }
Pattern (short, not copied from a program)
Files.deleteSnapshot(_ id: UInt64) -> FileError?staticDelete a snapshot and free the space used only by it.≤ 50 msfiles.deleteSnapshot0x0003_000E
Example
if next.kind == .requested { _ = Files.deleteSnapshot(next.id) }
from apps/slidercheck (shortened)
Restoring
Files.restore(_ path: Span<UInt8>, snapshot: UInt64) -> Result<(name: InlineArray<80, UInt8>, length: Int), FileError>staticCopy a file/folder back from a snapshot; nothing is overwritten ("name (HH.MM).ext").≤ 2 sfiles.restore0x0003_000F
Example
switch Files.restore(path.span.extracting(0..<length), snapshot: snapshots[shown].id) {
case .success(let restored): note(restored.name, restored.length)
case .failure(let error): problem = TextLine(error.text)
}
from apps/files (shortened)
All 10 declarations of this part (from docs/api/app-api-1.txt)
Files.Snapshot.var generation: UInt64
Files.Snapshot.var id: UInt64
Files.Snapshot.var kind
Files.Snapshot.var time: UInt64
Files.static func deleteSnapshot(_ id: UInt64) -> FileError?
Files.static func restore(_ path: Span<UInt8>, snapshot: UInt64) -> Result<(name: InlineArray<80, UInt8>, length: Int), FileError>
Files.static func reveal(_ path: Span<UInt8>) -> FileError?
Files.static func snapshot(after previous: UInt64) -> Snapshot?
Files.static func takeSnapshot() -> Result<UInt64, FileError>
Files.struct Snapshot

database · SOFTrobotsDB

For system programs only – not part of the App-API, may change

Writing every database on DATA, not only the own ones (the program Database: database.edit); the schema's rules still hold for every row.

What every program may use of it: App-API › database.

Rights

RightMeaningShape call · time budget
database.editWrite any database on DATA, not only its own (program Database).≤ 1 msdatabase.write0x0004_0002

network · Network, TLS, cloud AI

For system programs only – not part of the App-API, may change

Accepting connections (only the program Server: network.incoming and listens = …).

What every program may use of it: App-API › network.

Rights

RightMeaningShape call · time budget
network.incomingAccept connections on the ports of the listens = line (program Server).≤ 50 µsnetwork.listen0x0005_000C

System callsnetworkModule 0x0005 · Network: names, TCP, UDP, listening (get/post planned).

CallRequest → answerRightTime budget · ID
network.listenListen → Listeningnetwork.incoming≤ 50 µs0x0005_000C
network.acceptAccept → Acceptednetwork.incoming≤ 10 s0x0005_000D
network.listenerInfoListenerRequest → ListenerInfonetwork.incoming≤ 20 µs0x0005_000E
network.closeListenerListenerRequest → Donenetwork.incoming≤ 50 µs0x0005_000F

SwiftNetwork.Listener · Network.PeerIncoming (network.incoming)

CallWhat it doesShape call · time budget
Listening
Network.Listener.init?(port: UInt16, backlog: UInt8 = 8)Listen; nil if the port is not in the manifest, is taken, or an emergency stop is in effect.≤ 50 µsnetwork.listen0x0005_000C
Example
guard let listener = Network.Listener(port: 8080, backlog: 4) else { return }
from apps/listencheck (shortened)
Network.Listener.close()Stop listening; accepted connections remain.≤ 50 µsnetwork.closeListener0x0005_000F
Accepting
Network.Listener.accept(timeout: UInt64 = 1_000_000_000) -> (connection: Network.Connection, peer: Network.Peer)?Accept the next connection.≤ 10 snetwork.accept0x0005_000D
Example
if let (connection, peer) = listener.accept(timeout: 1_000_000_000) {
    // peer.ipv4 / peer.port; connection.send(...), connection.close()
}
Pattern (short, not copied from a program)
Network.Peer: ipv4, ipv6, overIPv6, portWho has connected.
State
Network.Listener.info() -> ListenerInfo?Accepted, refused, half open, waiting.≤ 20 µsnetwork.listenerInfo0x0005_000E
All 11 declarations of this part (from docs/api/app-api-1.txt)
Network.Listener.func accept(timeout: UInt64 = 1_000_000_000) -> (connection: Network.Connection, peer: Network.Peer)?
Network.Listener.func close()
Network.Listener.func info() -> ListenerInfo?
Network.Listener.init?(port: UInt16, backlog: UInt8 = 8)
Network.Listener.let handle: ListenerHandle
Network.Peer.let ipv4: UInt32
Network.Peer.let ipv6: InlineArray<16, UInt8>
Network.Peer.let overIPv6: Bool
Network.Peer.let port: UInt16
Network.struct Listener
Network.struct Peer

ui · Windows, drawing, views, input, menus, progress

For system programs only – not part of the App-API, may change

Owning the screen (the display service: ui.display), receiving input (ui.input, a primitive system call) and delivering it (input drivers: ui.input.provide).

What every program may use of it: App-API › ui.

Rights

RightMeaningShape call · time budget
ui.displayOwn the screen (display service only).≤ 5 msdisplay.open0x0011_0001
ui.input.provide / ui.inputDeliver input events (drivers) or receive them (display service).≤ 5 µsdisplay.submitInput0x0011_0006

System callsdisplayModule 0x0011 · Screen and window memory (ui.surface, ui.display).

CallRequest → answerRightTime budget · ID
display.openDisplayQuery → ScreenInfoui.display≤ 5 ms0x0011_0001
display.flushPixelRect → Doneui.display≤ 200 µs0x0011_0002
display.screenshotDisplayQuery → Doneui.display≤ 50 ms0x0011_0003
display.surfaceSurfaceQuery → SurfaceStateui.display≤ 20 µs0x0011_0005
display.submitInputInputEvent → Doneui.input.provide≤ 5 µs0x0011_0006

SwiftScreenDisplay service only (ui.display)

CallWhat it doesShape call · time budget
Screen
Screen.open() -> (canvas: Canvas, needsFlush: Bool)?staticTakes over the screen.≤ 5 msdisplay.open0x0011_0001
Example
guard let (screen, needsFlush) = Screen.open() else { return }   // only with ui.display
from apps/display (shortened)
Screen.flush(_ rect: Rect)staticShows a changed rectangle (virtio-gpu).≤ 200 µsdisplay.flush0x0011_0002
Screen.saveScreenshot() -> BoolstaticSaves the screen as PNG in /data/screenshots.≤ 50 msdisplay.screenshot0x0011_0003
Windows & input
Screen.surface(_ index: Int) -> SurfaceInfostaticWindow number index as the service sees it.≤ 20 µsdisplay.surface0x0011_0005
Screen.input(into events: inout InlineArray<96, UInt64>) -> IntstaticFetch input events.inputReceive (system call 12)
Screen.wait(timeout: UInt64) / .notify(_ index: Int)staticWait for programs / wake a window.wait / surfaceNotify

SwiftSystemDelivering input (ui.input.provide)

CallWhat it doesShape call · time budget
Only the display service and drivers
System.submitInput(kind: UInt64, code: UInt64, value: UInt64)Deliver an input event (ui.input.provide).≤ 5 µsdisplay.submitInput0x0011_0006
All 17 declarations of this part (from docs/api/app-api-1.txt)
Screen.static func flush(_ rect: Rect)
Screen.static func input(into events: inout InlineArray<96, UInt64>) -> Int
Screen.static func notify(_ index: Int)
Screen.static func open() -> (canvas: Canvas, needsFlush: Bool)?
Screen.static func saveScreenshot() -> Bool
Screen.static func surface(_ index: Int) -> SurfaceInfo
Screen.static func wait(timeout: UInt64)
SurfaceInfo.var generation: UInt64
SurfaceInfo.var kind: UInt8
SurfaceInfo.var owner
SurfaceInfo.var pixels: UInt64
SurfaceInfo.var realtime
SurfaceInfo.var ring: UInt64
SurfaceInfo.var stride
System.static func submitInput(kind: UInt64, code: UInt64, value: UInt64)
enum Screen
struct SurfaceInfo

sound · Playing and listening

For system programs only – not part of the App-API, may change

Setting the master volume (Settings: sound.volume), the MIC indicator and its stop (display service: system.protection) and offering a microphone (test microphone: sound.microphone.provide).

What every program may use of it: App-API › sound.

Rights

RightMeaningShape call · time budget
sound.volumeSet the master volume.≤ 50 µssound.setVolume0x0030_0009
sound.microphone.provideOffer a microphone (test microphone).≤ 1 msmicrophone.provide0x0031_0006

System callsmicrophoneModule 0x0031 · The robot's microphones (sound.microphone, sound.microphone.provide).

CallRequest → answerRightTime budget · ID
microphone.listenersListenersRequest → Listenerssystem.protection≤ 20 µs0x0031_0004
microphone.stopAllStopListening → Donesystem.protection≤ 1 ms0x0031_0005
microphone.provideProvideMicrophone → ProvidedMicrophonesound.microphone.provide≤ 1 ms0x0031_0006
microphone.pushPushSamples → Donesound.microphone.provide≤ 200 µs0x0031_0007

System callssoundModule 0x0030 · Sound through the system's mixer (sound.play; tone/play/stop planned).

CallRequest → answerRightTime budget · ID
sound.setVolumeMasterVolume → Donesound.volume≤ 50 µs0x0030_0009

SwiftSound.OutputMaster volume (sound.volume)

CallWhat it doesShape call · time budget
Volume
Sound.Output.setMasterVolume(_ volume: Int) -> BoolstaticSet the master volume (sound.volume).≤ 50 µssound.setVolume0x0030_0009
Example
_ = Sound.Output.setMasterVolume(70)   // only with sound.volume
Pattern (short, not copied from a program)

SwiftSound.MicrophoneMIC indicator (system.protection), offering a microphone (sound.microphone.provide)

CallWhat it doesShape call · time budget
Listeners (MIC indicator)
Sound.Microphone.listeners(into names: inout InlineArray<512, UInt8>) -> (length: Int, count: Int)Who is listening right now (MIC indicator; system.protection).≤ 20 µsmicrophone.listeners0x0031_0004
Sound.Microphone.stopAll() -> BoolStop all listeners (Stop on the MIC card; system.protection).≤ 1 msmicrophone.stopAll0x0031_0005
Example
_ = Sound.Microphone.stopAll()   // Stop on the MIC card
from apps/display (shortened)
Offering a microphone
Sound.Microphone.provide(_ name: StaticString, channels: Int = 1) -> Int?Offer a microphone (sound.microphone.provide).≤ 1 msmicrophone.provide0x0031_0006
Example
guard let microphone = Sound.Microphone.provide("Test microphone", channels: 1) else { return }
from apps/testmicrophone (shortened)
Sound.Microphone.push(_ id: Int, samples: Int) -> Bool / .pushBuffer / .pushRoomFeed samples from pushBuffer (at most 80 ms stereo).≤ 200 µsmicrophone.push0x0031_0007
All 7 declarations of this part (from docs/api/app-api-1.txt)
Sound.Microphone.static func listeners(into names: inout InlineArray<512, UInt8>) -> (length: Int, count: Int)
Sound.Microphone.static func provide(_ name: StaticString, channels: Int = 1) -> Int?
Sound.Microphone.static func push(_ id: Int, samples: Int) -> Bool
Sound.Microphone.static func stopAll() -> Bool
Sound.Microphone.static let pushRoom
Sound.Microphone.static var pushBuffer: UnsafeMutablePointer<Int16>
Sound.Output.static func setMasterVolume(_ volume: Int) -> Bool

camera · Cameras, vision and detections

For system programs only – not part of the App-API, may change

Offering a camera and pushing pictures into it (test camera, USB driver: camera.provide).

What every program may use of it: App-API › camera.

Rights

RightMeaningShape call · time budget
camera.provideOffer a camera and push images into it (test camera).≤ 1 mscamera.provide0x0020_0007

System callscameraModule 0x0020 · The robot's cameras (camera.use, camera.provide).

CallRequest → answerRightTime budget · ID
camera.provideProvideCamera → ProvidedCameracamera.provide≤ 1 ms0x0020_0007
camera.pushPushFrame → Donecamera.provide≤ 500 µs0x0020_0008

SwiftCameraOffering a camera (camera.provide)

CallWhat it doesShape call · time budget
Offering a camera
Camera.provide(_ name: StaticString, width: Int, height: Int) -> Int?Become the provider of a camera (camera.provide).≤ 1 mscamera.provide0x0020_0007
Example
guard let id = Camera.provide("Test camera", width: 640, height: 480) else { return }   // camera.provide
Pattern (short, not copied from a program)
Camera.push(_ id: Int, count: Int) -> Bool / .frameBuffer / .frameRoomFeed the JPEG in frameBuffer (at most 448 KiB) as the next image.≤ 500 µscamera.push0x0020_0008
Example
// Copy the JPEG bytes to Camera.frameBuffer (at most Camera.frameRoom), then:
_ = Camera.push(id, count: jpeg.count)
Pattern (short, not copied from a program)
All 4 declarations of this part (from docs/api/app-api-1.txt)
Camera.static func provide(_ name: StaticString, width: Int, height: Int) -> Int?
Camera.static func push(_ id: Int, count: Int) -> Bool
Camera.static let frameRoom
Camera.static var frameBuffer: UnsafeMutableRawBufferPointer

robot · Arms, kinematics, actuator service, CAN

For system programs only – not part of the App-API, may change

Drivers for USB and CAN controllers (device.usb, device.can): opening controllers, DMA memory, waiting for interrupts.

What every program may use of it: App-API › robot.

Rights

RightMeaningShape call · time budget
device.usb / device.canDrivers: map the registers of a USB or CAN FD controller, DMA memory.≤ 1 msdevices.open0x0009_0001

System callsdevicesModule 0x0009 · Controllers for driver programs (device.usb, device.can).

CallRequest → answerRightTime budget · ID
devices.openControllerQuery → Controllerdevice.usb or device.can≤ 1 ms0x0009_0001
devices.allocateDMARequest → DMAMemorydevice.usb≤ 1 ms0x0009_0002

SwiftSystemDrivers: controllers, DMA, interrupts

CallWhat it doesShape call · time budget
Only the display service and drivers
System.openUSBController(_:) / .openCANController(_:) / .allocateDMA(_:) / .waitForDevice(timeout:)Drivers: registers, DMA memory, interrupts (device.usb, device.can).≤ 1 msdevices.open0x0009_0001
All 4 declarations of this part (from docs/api/app-api-1.txt)
System.static func allocateDMA(_ size: UInt64) -> (UInt64, UInt64)?
System.static func openCANController(_ index: Int) -> UInt64?
System.static func openUSBController(_ index: Int) -> UInt64?
System.static func waitForDevice(timeout: UInt64) -> Bool

safety · The emergency stop

For system programs only – not part of the App-API, may change

Triggering and releasing the emergency stop (safety.stop) and driving actuators (the actuator service: safety.actuator; it is woken at once on an emergency stop and must make the actuators safe).

What every program may use of it: App-API › safety.

Rights

RightMeaningShape call · time budget
safety.stopTrigger and release the emergency stop.≤ 20 µssafety.stop0x0100_0002
safety.actuatorDrive actuators: woken immediately on an emergency stop, must make them safe (actuator service).

System callssafetyModule 0x0100 · The emergency stop (reading is free, stop/release with safety.stop).

CallRequest → answerRightTime budget · ID
safety.stopEmergencyStop → Donesafety.stop≤ 20 µs0x0100_0002
safety.releaseSafetyQuery → Donesafety.stop≤ 20 µs0x0100_0003

SwiftSystemTriggering and releasing the emergency stop (safety.stop)

CallWhat it doesShape call · time budget
Triggering & releasing
System.emergencyStop(reason: UInt64) -> BoolStop all actuators immediately (safety.stop).≤ 20 µssafety.stop0x0100_0002
Example
let stopped = System.emergencyStop(reason: 5)
from apps/server (shortened)
System.releaseEmergencyStop() -> BoolRelease the stop; actuators wait for the next command from their programs.≤ 20 µssafety.release0x0100_0003
Example
System.releaseEmergencyStop()
from apps/arm (shortened)
Example: watching the emergency stop in the actuator service (apps/actuators)
var safety = System.safetyGeneration
if safety & 1 == 1 { motors.emergencyStop(true) }
while true {
    let now = System.safetyGeneration
    if now != safety { motors.emergencyStop(now & 1 == 1); safety = now }
    // ...
}
All 2 declarations of this part (from docs/api/app-api-1.txt)
System.static func emergencyStop(reason: UInt64) -> Bool
System.static func releaseEmergencyStop() -> Bool

clipboard · Copy and paste

For system programs only – not part of the App-API, may change

Granting one read of the clipboard when the owner chose “Paste” (display service: ui.display).

What every program may use of it: App-API › clipboard.

Rights

No right of its own: granting needs ui.display (module ui).

System callsclipboardModule 0x0012 · Copy and paste.

CallRequest → answerRightTime budget · ID
clipboard.grantPasteGrant → Doneui.displayno budget0x0012_0003

SwiftClipboardGranting (display service, ui.display)

CallWhat it doesShape call · time budget
Granting (service)
Clipboard.grant(process slot: Int)staticGives program slot one read access (display service only).no budgetclipboard.grant0x0012_0003
Example
if id == EditMenu.paste { Clipboard.grant(process: windows[window].info.owner) }
from apps/display (shortened)
All 1 declarations of this part (from docs/api/app-api-1.txt)
Clipboard.static func grant(process slot: Int)

dialog · Opening and saving through the system

For system programs only – not part of the App-API, may change

Showing the open and save dialog and reporting the choice (only the program chooser: files.dialog).

What every program may use of it: App-API › dialog.

Rights

RightMeaningShape call · time budget
files.dialog newShow the system's open/save dialog and report the choice (program chooser only).≤ 5 msdialog.answer0x0013_0004

System callsdialogModule 0x0013 · The system's open and save dialog (new, 10 Nov).

CallRequest → answerRightTime budget · ID
dialog.questions newQuestionsRequest → DialogQuestionsfiles.dialog≤ 50 µs0x0013_0003
dialog.answer newDialogAnswer → Donefiles.dialog≤ 5 ms0x0013_0004

System callsdialogOnly the system program chooser (files.dialog)

CallWhat it doesShape call · time budget
Only with files.dialog
dialog.questions newOpen questions of all programs (the chooser shows them).≤ 50 µsdialog.questions0x0013_0003
dialog.answer newThe person's choice for question number; the kernel checks place and type and asks “Replace?”.≤ 5 msdialog.answer0x0013_0004
Example: the file dialog itself: never in the Dock (apps/chooser/manifest)
name = chooser
id = de.softrobots.chooser
title = File Dialog
category = system
capabilities = system.log, ui.surface, files.system, files.dialog
kind = system
start = demand
helper = display
# Never in the dock, not even while a dialog is open (2026-11-10).
dock = no

update · System updates

For system programs only – not part of the App-API, may change

Installing signed system updates into the system copy that is not running, choosing the start screen and start sound (Settings, Update: system.update).

Rights

RightMeaningShape call · time budget
system.updateInstall signed system updates into the resting system copy.≤ 60 supdate.install0x0008_0002

System callsupdateModule 0x0008 · System copies A/B and updates (system.update).

CallRequest → answerRightTime budget · ID
update.statusUpdateQuery → UpdateStatesystem.update≤ 5 µs0x0008_0001
update.installUpdatePackage → Donesystem.update≤ 60 s0x0008_0002
update.textStartStartLook → Donesystem.update≤ 50 ms0x0008_0003
update.startSoundStartSound → Donesystem.update≤ 50 ms0x0008_0004

SwiftSystemUpdates (system.update)

CallWhat it doesShape call · time budget
Updates (system.update)
System.updateStatus() -> UpdateStatus?Which system copy (A/B) is running, trial run, fallback, versions.≤ 5 µsupdate.status0x0008_0001
System.installUpdate(_ path: Span<UInt8>) -> UpdateResultInstall a signed package into the resting copy; starts after the restart.≤ 60 supdate.install0x0008_0002
System.setTextStart(_ text: Bool) -> Bool / System.setStartSound(_ on: Bool) -> BoolText start instead of animation / start sound.≤ 50 msupdate.textStart0x0008_0003
All 18 declarations of this part (from docs/api/app-api-1.txt)
System.static func installUpdate(_ path: Span<UInt8>) -> UpdateResult
System.static func setStartSound(_ on: Bool) -> Bool
System.static func setTextStart(_ text: Bool) -> Bool
System.static func updateStatus() -> UpdateStatus?
UpdateStatus.var active
UpdateStatus.var installing
UpdateStatus.var onTrial
UpdateStatus.var rolledBack
UpdateStatus.var running
UpdateStatus.var startSound
UpdateStatus.var textStart
UpdateStatus.var trial: Int?
UpdateStatus.var triesLeft
UpdateStatus.var unsupported
UpdateStatus.var versionA
UpdateStatus.var versionB
enum UpdateResult
struct UpdateStatus

protection · Device protection

For system programs only – not part of the App-API, may change

Device protection: password for DATA, unlocking, screen lock, the owner's choices (display service only: system.protection).

Rights

RightMeaningShape call · time budget
system.protectionDevice protection: password, unlocking, screen lock, MIC indicator (display service only).≤ 5 µsprotection.status0x0007_0001

System callsprotectionModule 0x0007 · Device protection: password for DATA, lock, owner choice (system.protection).

CallRequest → answerRightTime budget · ID
protection.statusProtectionQuery → ProtectionStatussystem.protection≤ 5 µs0x0007_0001
protection.setUpPassword → RecoveryKeysystem.protection≤ 3 s0x0007_0002
protection.unlockPassword → Donesystem.protection≤ 3 s0x0007_0003
protection.verifyPassword → Donesystem.protection≤ 3 s0x0007_0004
protection.choicesProtectionQuery → OwnerChoicessystem.protection≤ 2 ms0x0007_0005

SwiftSystemDisplay service only (system.protection)

CallWhat it doesShape call · time budget
Only the display service and drivers
System.protectionStatus() / .protectionSetUp / .protectionCheck / .ownerChoices()Device protection and owner choice (system.protection).≤ 5 µsprotection.status0x0007_0001
All 5 declarations of this part (from docs/api/app-api-1.txt)
System.enum ProtectionResult
System.static func ownerChoices() -> (lockMinutes: Int?, appearance: Appearance, dock: InlineArray<160, UInt8>, dockCount: Int, buddy: Int)
System.static func protectionCheck<let n: Int>(_ password: InlineArray<n, UInt8>, count: Int, unlock: Bool) -> ProtectionResult
System.static func protectionSetUp<let n: Int>(_ password: InlineArray<n, UInt8>, count: Int,
System.static func protectionStatus() -> (state: ProtectionState, development: Bool, wait: Int)

Libraries

Tools a program can use that do not talk to the system: they come with a profile file uses-… in the program folder and are built in. They have their own list (docs/api/libraries.txt, 874 declarations, tools/api/symbols.py --libraries) and are not frozen at 1.0 – they may keep evolving.

Overview

LibraryWhat forFileDeclarations
webWeb: HTML, CSS, HTTPuses-web279
imagePictures and PDFuses-image173
svgSVGuses-svg105
soundSound: tools and formatsuses-heap118
archiveArchives: ZIP, Deflateuses-archive79
sqlSQLuses-sql52
mathsMathsevery profile25
videoVideo: VP9uses-video25
qrQR codesuses-qr10
opusOpususes-opus8

web · Web: HTML, CSS, HTTP

Reading HTML (tree, tokenizer), evaluating CSS (selectors, cascade, lengths, media), HTTP requests and responses, URLs – the base of the program Web.

Source: userland/web/ · file uses-web · 279 declarations

All 279 declarations of the library (docs/api/libraries.txt)
CSSAttributeTest.var ignoreCase: Bool
CSSAttributeTest.var name: String
CSSAttributeTest.var op: UInt8
CSSAttributeTest.var value: String
CSSCompound.var attributes: [CSSAttributeTest]
CSSCompound.var classes: [String]
CSSCompound.var id
CSSCompound.var pseudos: [CSSPseudo]
CSSCompound.var tag
CSSDeclaration.var important: Bool
CSSDeclaration.var name: String
CSSDeclaration.var value: String
CSSDisplay.var isInlineLevel: Bool
CSSLength.func resolve(_ base: Double) -> Double
CSSLength.init(px: Double = 0, percent: Double = 0, kind: UInt8 = 0)
CSSLength.static func pixels(_ value: Double) -> CSSLength
CSSLength.static let auto
CSSLength.var isAuto: Bool
CSSLength.var isLength: Bool
CSSLength.var isNone: Bool
CSSLength.var kind: UInt8
CSSLength.var percent: Double
CSSLength.var px: Double
CSSMedia.static func matches(_ query: String, _ viewport: CSSViewport) -> Bool
CSSParser.static func declarations(_ text: String) -> [CSSDeclaration]
CSSParser.static func parse(_ text: String, viewport: CSSViewport) -> CSSStyleSheet
CSSParser.static let limit
CSSRule.var declarations: [CSSDeclaration]
CSSRule.var selectors: [CSSSelector]
CSSSelector.static func parse(_ text: String) -> CSSSelector?
CSSSelector.var combinators: [UInt8]
CSSSelector.var compounds: [CSSCompound]
CSSSelector.var pseudoElement
CSSSelector.var specificity
CSSSelector.var subject: CSSCompound
CSSStyle.func border(_ side: Int) -> Double
CSSStyle.func inherited() -> CSSStyle
CSSStyle.init()
CSSStyle.mutating func apply(_ name: String, _ rawValue: String, parent: CSSStyle, units: CSSUnits)
CSSStyle.var alignItems
CSSStyle.var alignSelf
CSSStyle.var aspectRatio
CSSStyle.var background
CSSStyle.var basis
CSSStyle.var borderBox
CSSStyle.var borderColor
CSSStyle.var borderSpacing
CSSStyle.var borderStyleSet
CSSStyle.var borderWidth
CSSStyle.var captionBottom
CSSStyle.var clear: UInt8
CSSStyle.var clipsOverflow
CSSStyle.var collapseBorders
CSSStyle.var color
CSSStyle.var columnGap
CSSStyle.var condensed
CSSStyle.var display
CSSStyle.var family
CSSStyle.var flexDirection: UInt8
CSSStyle.var flexWrap
CSSStyle.var float
CSSStyle.var fontSize
CSSStyle.var fontWeight
CSSStyle.var gridArea
CSSStyle.var gridAreas: [[String]]
CSSStyle.var gridColumnSpan
CSSStyle.var gridColumnStart
CSSStyle.var gridColumns: [CSSLength]
CSSStyle.var grow
CSSStyle.var height
CSSStyle.var inset
CSSStyle.var invisibleBox
CSSStyle.var italic
CSSStyle.var justifyContent
CSSStyle.var lineHeight
CSSStyle.var lineHeightPixels
CSSStyle.var lineThrough
CSSStyle.var listStyle
CSSStyle.var margin
CSSStyle.var masked
CSSStyle.var maxHeight
CSSStyle.var maxWidth
CSSStyle.var minHeight
CSSStyle.var minWidth
CSSStyle.var objectFit: UInt8
CSSStyle.var order
CSSStyle.var padding
CSSStyle.var position
CSSStyle.var rowGap
CSSStyle.var scrollsOverflow
CSSStyle.var shrink
CSSStyle.var textAlign
CSSStyle.var textIndent
CSSStyle.var transform
CSSStyle.var underline
CSSStyle.var usedLineHeight: Double
CSSStyle.var variables
CSSStyle.var verticalAlign
CSSStyle.var visible
CSSStyle.var whiteSpace
CSSStyle.var width
CSSStyleSheet.init()
CSSStyleSheet.var imports: [String]
CSSStyleSheet.var rules: [CSSRule]
CSSUnits.init(fontSize: Double, rootFontSize: Double, viewport: CSSViewport)
CSSUnits.var fontSize: Double
CSSUnits.var rootFontSize: Double
CSSUnits.var viewport: CSSViewport
CSSValue.static func color(_ text: String, current: RGBA) -> RGBA?
CSSValue.static func length(_ text: String, _ units: CSSUnits, allowAuto: Bool = true) -> CSSLength?
CSSValue.static func mediaLength(_ text: String) -> Double?
CSSValue.static func number(_ text: String) -> Double?
CSSValue.static func parts(_ value: String) -> [String]
CSSValue.static func substitute(_ value: String, _ variables: [String: String], depth: Int = 0) -> String?
CSSValue.static func substitute(_ value: String, lookup: (String) -> String?, depth: Int = 0) -> String?
CSSValue.static func url(_ text: String) -> String?
CSSVariables.func lookup(_ name: String, from scope: Int) -> String?
CSSVariables.private(set) var parents: [Int]
CSSVariables.private(set) var tables: [[String: String]]
CSSViewport.init(width: Int, height: Int)
CSSViewport.var height: Int
CSSViewport.var width: Int
Charset.static func utf8(_ bytes: [UInt8], charset: String) -> [UInt8]
DefaultStyle.static let css
ElementTree.func matches(_ compound: CSSCompound, _ node: Int) -> Bool
ElementTree.func matches(_ selector: CSSSelector, _ node: Int) -> Bool
ElementTree.init(_ document: HTMLDocument)
ElementTree.let document: HTMLDocument
ElementTree.private(set) var classes: [[String]]
ElementTree.private(set) var ids: [String]
ElementTree.private(set) var parent: [Int32]
ElementTree.private(set) var position: [Int32]
ElementTree.private(set) var previous: [Int32]
ElementTree.private(set) var siblings: [Int32]
GlyphImage.var coverage: [UInt8]
GlyphImage.var left
HTMLDocument.init()
HTMLDocument.private(set) var baseHref: String?
HTMLDocument.private(set) var nodes: [HTMLNode]
HTMLDocument.private(set) var styleSources: [StyleSource]
HTMLDocument.private(set) var styles: [String]
HTMLDocument.private(set) var title
HTMLDocument.private(set) var truncated
HTMLDocument.static func parse(_ bytes: [UInt8]) -> HTMLDocument
HTMLDocument.static let html
HTMLDocument.static let maxDepth
HTMLDocument.static let maxNodes
HTMLNode.func attribute(_ name: String) -> String?
HTMLNode.var attributes: [(name: String, value: String)]
HTMLNode.var children: [Int]
HTMLNode.var parent: Int
HTMLNode.var tag: String
HTMLNode.var text: String
HTMLTokenizer.init(_ bytes: [UInt8])
HTMLTokenizer.mutating func next() -> HTMLToken?
HTMLTokenizer.mutating func rawText(until name: String) -> String
HTMLTokenizer.static func decode(_ text: String) -> String
HTTPRequest.static func get(_ url: WebURL) -> [UInt8]
HTTPRequest.static func get(_ url: WebURL, from offset: Int) -> [UInt8]
HTTPRequest.static func post(_ url: WebURL, body: [UInt8]) -> [UInt8]
HTTPRequest.static let userAgent
HTTPResponse.enum State: Equatable
HTTPResponse.func header(_ name: String) -> String?
HTTPResponse.init()
HTTPResponse.mutating func completeDownload(_ whole: [UInt8])
HTTPResponse.mutating func feed(_ bytes: Span<UInt8>) -> State
HTTPResponse.mutating func finish()
HTTPResponse.private(set) var body: [UInt8]
HTTPResponse.private(set) var headers: [(name: String, value: String)]
HTTPResponse.private(set) var leftover
HTTPResponse.private(set) var state
HTTPResponse.private(set) var status
HTTPResponse.static let limit
HTTPResponse.var charset: String
HTTPResponse.var contentType: String
HTTPResponse.var expectedLength: Int?
HTTPResponse.var isRedirect: Bool
HTTPResponse.var reusable: Bool
OutlineFont.func advance(_ glyph: Int) -> Int
OutlineFont.func glyph(_ code: UInt32) -> Int?
OutlineFont.func kerning(_ first: UInt32, _ second: UInt32) -> Double
OutlineFont.func outline(_ index: Int, _ body: (_ command: Int, _ x: Int, _ y: Int, _ cx: Int, _ cy: Int) -> Void)
OutlineFont.func render(_ index: Int, size: Double, slant: Double = 0, stretch: Double = 1) -> GlyphImage
OutlineFont.init(unitsPerEm: Int, ascent: Int, descent: Int, lineGap: Int, codes: StaticString, offsets: StaticString, data: StaticString,
OutlineFont.init(unitsPerEm: Int, ascent: Int, descent: Int, lineGap: Int, codes: [UInt8], offsets: [UInt8], data: [UInt8],
OutlineFont.let ascent: Int
OutlineFont.let descent: Int
OutlineFont.let lineGap: Int
OutlineFont.let unitsPerEm: Int
OutlineFont.var glyphCount: Int
PageMemory.Entry.var body: [UInt8]
PageMemory.Entry.var contentType: String
PageMemory.func entry(_ address: String) -> Entry?
PageMemory.init()
PageMemory.mutating func forget(_ address: String)
PageMemory.mutating func keep(_ address: String, body: [UInt8], contentType: String, noStore: Bool)
PageMemory.private(set) var bytes
PageMemory.static func forbids(cacheControl: String?) -> Bool
PageMemory.static let budget
PageMemory.struct Entry
PageMemory.var count: Int
RGBA.init(_ r: UInt8, _ g: UInt8, _ b: UInt8, _ a: UInt8 = 255)
RGBA.static let black
RGBA.var r: UInt8, g: UInt8, b: UInt8, a: UInt8
ResolvedStyles.init()
ResolvedStyles.var after: [Int: (text: String, style: CSSStyle)]
ResolvedStyles.var before: [Int: (text: String, style: CSSStyle)]
ResolvedStyles.var canvas
ResolvedStyles.var styles: [CSSStyle]
ResolvedStyles.var variables
Sides.init(_ values: [T])
Sides.init(repeating value: T)
Sides.subscript(_ side: Int) -> T
Sides.var top: T, right: T, bottom: T, left: T
String.func collapsingSpaces() -> String
String.func hasSubstring(_ part: String) -> Bool
StyleResolver.static func resolve(_ document: HTMLDocument, sheets: [CSSStyleSheet], viewport: CSSViewport) -> ResolvedStyles
StyleSource.var href: String?
StyleSource.var media: String
StyleSource.var text: String
WebURL.init(scheme: String, host: String, port: Int? = nil, path: String, query: String? = nil, fragment: String? = nil)
WebURL.static func parse(_ text: String) -> WebURL?
WebURL.static let start
WebURL.var fragment: String?
WebURL.var host: String
WebURL.var path: String
WebURL.var port: Int?
WebURL.var query: String?
WebURL.var scheme: String
enum CSSAlign: UInt8
enum CSSAlignment: UInt8
enum CSSDisplay: UInt8
enum CSSFamily: UInt8
enum CSSFloat: UInt8
enum CSSListStyle: UInt8
enum CSSMedia
enum CSSParser
enum CSSPosition: UInt8
enum CSSTransform: UInt8
enum CSSValue
enum CSSVerticalAlign: UInt8
enum CSSWhiteSpace: UInt8
enum Charset
enum DefaultStyle
enum HTMLToken
enum HTTPRequest
enum StyleResolver
func resolve(_ reference: String) -> WebURL?
indirect enum CSSPseudo
static func percentEncoded(_ text: String) -> String
static func search(_ words: String) -> WebURL
struct CSSAttributeTest
struct CSSCompound
struct CSSDeclaration
struct CSSLength: Equatable, Sendable
struct CSSRule
struct CSSSelector
struct CSSStyle
struct CSSStyleSheet
struct CSSUnits
struct CSSVariables
struct CSSViewport
struct ElementTree
struct GlyphImage: Sendable
struct HTMLDocument
struct HTMLNode
struct HTMLTokenizer
struct HTTPResponse
struct OutlineFont: Sendable
struct PageMemory
struct RGBA: Equatable, Sendable
struct ResolvedStyles
struct Sides<T>
struct StyleSource
struct WebURL: Equatable, Sendable
var effectivePort: Int
var requestTarget: String
var secure: WebURL
var text: String

image · Pictures and PDF

With uses-image (needs uses-heap): decode and encode images, write and read PDF. A Picture holds RGBA pixels. Reading PDF is untrusted input – so the programs Reader and Image read only the one document handed to them. QR codes with uses-qr (without a heap).

Containers and codecs for recording and playback: Matroska/WebM (uses-image), VP9 (uses-video), Opus (uses-opus), WAV and FLAC (with uses-heap). Camera records MKV with MJPEG, sound and detections; Video plays MKV and WebM (VP9 + Opus).

Source: userland/image/ · file uses-image · 173 declarations

SwiftPictureA picture

CallWhat it doesShape call · time budget
Image
Picture(width: Int = 0, height: Int = 0, pixels: [UInt8] = [], scale: Int = 1)An image of RGBA pixels.
Example
var picture = Picture(width: 64, height: 48, pixels: [UInt8](repeating: 255, count: 64 * 48 * 4))
from apps/apicheck (shortened)
Picture.maxFile / .maxPixelsstaticLimits against inputs that are too large.
PictureError.textShort sentence for messages.
Decoding
Picture.decode(_ file: [UInt8]) -> Result<Picture, PictureError>staticPNG, JPEG, GIF, WebP, BMP or TIFF by signature.
Example
guard case .success(let picture) = Picture.decode(Array(jpeg[0..<taken.count])) else { return false }
from apps/video (shortened)

SwiftPNG · JPEG · GIF · WebP · BMP · TIFFFormats

CallWhat it doesShape call · time budget
PNG & JPEG
PNG.encode(_ picture: Picture) -> [UInt8]? / .decode / .hasSignature / .size(_:)PNG lossless (RGB if opaque, otherwise RGBA); size without decoding.
Example
guard let png = PNG.encode(picture), case .success(let decodedPNG) = PNG.decode(png) else { return }
from apps/apicheck (shortened)
JPEG.encode(_ picture: Picture, quality: Int = 85) -> [UInt8]? / .decode / .hasSignatureJPEG (baseline, 4:2:0, quality 1 … 100).
Example
guard let jpeg = JPEG.encode(picture, quality: 85) else { return }
from apps/apicheck (shortened)
GIF & WebP
GIF.decode / .hasSignature / .maxFramesGIF, first image.
GIFAnimation.parse(_ file: [UInt8]) -> Result<GIFAnimation, PictureError>Animated GIF: advance(), show(_:), delay(_:), frameCount, pixels.
Example
guard case .success(var animation) = GIFAnimation.parse(bytes) else { return }
let wait = animation.advance()   // ms until the next image; show animation.pixels
Pattern (short, not copied from a program)
WebP.decode / .hasSignatureWebP (lossy and lossless).
WebPAnimation.parse(_ file: [UInt8]) -> Result<WebPAnimation, PictureError>Animated WebP, like GIFAnimation.
BMP & TIFF
BMP.encode / .decode / .hasSignature, TIFF.encode / .decode / .hasSignatureRead and write BMP and TIFF.
Inflating & sinks
Inflater.zlib(_:limit:) / .zlib(_:size:) / .gzip(_:limit:)Inflate zlib/gzip (with a size limit).
PNGSink / ByteCollector (ByteSink)Destinations for bytes when encoding.

SwiftPDFDocumentWriting PDF

CallWhat it doesShape call · time budget
Document
PDFDocument(width: Double = PDFDocument.a4.width, height: Double = PDFDocument.a4.height)New document (dimensions in points).
Example
var pdf = PDFDocument()   // A4
from apps/image (shortened)
PDFDocument.newPage() / .data() -> [UInt8]New page / the finished PDF.
Example
pdf.newPage()
let bytes = pdf.data()   // then Files.Handle.open(…, mode: .replace) and write
Pattern (short, not copied from a program)
PDFDocument.data(userPassword: [UInt8], ownerPassword: [UInt8], random: [UInt8]) -> [UInt8]Encrypted PDF.
Setting content
PDFDocument.text(_ text: String, x: Double, y: Double, size: Double = 11, font: Font = .regular, colour: (UInt8, UInt8, UInt8) = (0, 0, 0))Set text.
Example
pdf.text(name.isEmpty ? "Picture" : name, x: margin, y: margin + 14, size: 16, font: .bold)
from apps/image (shortened)
PDFDocument.picture(_ picture: Picture, x:y:width:height:, jpeg: [UInt8]? = nil) -> BoolInsert an image (optionally the JPEG directly).
PDFDocument.line(x0:y0:x1:y1:width:colour:) / .rectangle(x:y:width:height:fill:)Line, filled rectangle.
Dimensions
PDFDocument.width(_ text: String, size: Double, font: Font = .regular) -> Double / .a4staticText width, A4 dimensions.

SwiftPDFReaderReading PDF

CallWhat it doesShape call · time budget
Open
PDFReader.init(_ bytes: [UInt8], password: [UInt8] = []) throws(PDFReadError)Opens a PDF (encrypted ones too).
Example
var opened = try PDFReader(fileBytes, password: password)
from apps/reader (shortened)
Pages & text
PDFReader.pageCount / .page(_ index: Int) -> PDFPage?Pages (width, height, rotate, content, resources).
Example
guard var reader = try? PDFReader(bytes), let page = reader.page(0) else { return }
from apps/files (shortened)
PDFReader.text(page index: Int) -> [PDFTextRun]Text pieces of a page with position and size.
Navigation
PDFReader.outline() / .links(page:)Table of contents, links.
Example
outlineItems = opened.outline()   // [(level, title, page)]
from apps/reader (shortened)
Raw data & permissions
PDFReader.object / .resolve / .streamBytes / .decode / .decodeBytes / .trailerRaw objects for your own evaluation (PDFObject, PDFDictionary).
PDFReader.isEncrypted / .openedAsOwner / .permissions / .textString(_:) / .maximumFile / .maximumStreamEncryption, permissions, limits.

SwiftMatroskaWriterWriting MKV (MJPEG, sound, detections)

CallWhat it doesShape call · time budget
Creating
MatroskaWriter.init(width: Int, height: Int, detections: Bool = false, soundRate: Int = 0, soundChannels: Int = 1)New writer.
MatroskaWriter.header(app: StaticString = "") -> [UInt8]Header of the file.
Writing tracks
MatroskaWriter.frame(_ jpeg: [UInt8], milliseconds: Int) -> [UInt8]One image.
MatroskaWriter.sound(_ samples: [UInt8], milliseconds: Int) -> [UInt8]A piece of sound.
MatroskaWriter.detections(_ text: [UInt8], milliseconds: Int) -> [UInt8]Detections as a subtitle track.
Finishing
MatroskaWriter.finish() -> [UInt8] / .frames / .lastTimeFinish (index).

SwiftMatroskaIndex · MatroskaTrack · MatroskaFrameReading MKV/WebM

CallWhat it doesShape call · time budget
Reading & seeking
MatroskaIndex(size: Int, read: @escaping (Int, Int) -> [UInt8]) throws(MatroskaError)Reads the structure through a read function (without loading everything).
Example
guard let index = try? MatroskaIndex(size: Int(size), read: reader) else { return }
from apps/video (shortened)
MatroskaIndex.tracks / .frames / .duration / .docType / .seek(_ milliseconds: Int, track: Int) -> IntTracks, frames (track, time, offset, length, key), seeking.
Tracks
MatroskaTrack.isCodec(_ name: StaticString) -> Bool / .codec / .codecPrivate / .sampleRate / .widthCodec of a track ("V_VP9", "A_OPUS").
Example
opus = track.isCodec("A_OPUS") ? OpusDecoder(head: track.codecPrivate) : nil
from apps/video (shortened)
MatroskaID.ebml / .cluster / .tracks / .cues …Element IDs.
Example: saving a window as PNG or JPEG (sdk-apps/about)
guard let bytes = jpeg ? JPEG.encode(picture, quality: 90) : PNG.encode(picture),
      case .success(let file) = jpeg ? Files.Handle.open("window.jpg", mode: .replace) : Files.Handle.open("window.png", mode: .replace) else {
    saved = TextLine("Could not save the picture")
    return
}
bytes.withUnsafeBufferPointer { buffer in _ = file.write(Span(_unsafeElements: buffer)) }
_ = file.close()
Example: outputting an image as PDF (apps/image)
var pdf = PDFDocument()
let margin = 40.0
pdf.text(name.isEmpty ? "Picture" : name, x: margin, y: margin + 14, size: 16, font: .bold)
pdf.text(String(shown.width) + " x " + String(shown.height) + " pixels · SOFTrobots OS Image",
         x: margin, y: margin + 32, size: 10, colour: (110, 110, 110))
_ = pdf.picture(shown, x: margin, y: margin + 50, width: 400, height: 300)
let bytes = pdf.data()
Example: opening a PDF and reading pages (apps/reader)
do {
    var opened = try PDFReader(fileBytes, password: password)
    for index in 0..<opened.pageCount {
        if let page = opened.page(index) {
            let turned = page.rotate == 90 || page.rotate == 270
            pageSizes.append(turned ? (page.height, page.width) : (page.width, page.height))
        }
    }
    let runs = opened.text(page: 0)     // [PDFTextRun]: text, x, y, size, width
} catch {
    // wrong password, damaged …
}
Example: starting a recording as MKV and appending images (apps/video, Recording.swift)
guard case .success(let file) = Files.Handle.open(path, mode: .replace) else { return false }
var writer = MatroskaWriter(width: picture.width * picture.scale, height: picture.height * picture.scale, detections: true,
                            soundRate: recordSoundFormat.rate, soundChannels: recordSoundFormat.channels)
let header = writer.header()
_ = header.withUnsafeBufferPointer { file.write(Span(_unsafeElements: $0)) }

// per camera image:
let milliseconds = Int((System.time &- recordStarted) / 1_000_000)
let piece = writer.frame(Array(jpeg[0..<jpegCount]), milliseconds: milliseconds)
_ = piece.withUnsafeBufferPointer { file.write(Span(_unsafeElements: $0)) }
All 173 declarations of the library (docs/api/libraries.txt)
BMP.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
BMP.static func encode(_ picture: Picture) -> [UInt8]?
BMP.static func hasSignature(_ file: [UInt8]) -> Bool
GIF.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
GIF.static func hasSignature(_ file: [UInt8]) -> Bool
GIF.static let maxFrames
GIFAnimation.func delay(_ frame: Int) -> Int
GIFAnimation.let height: Int
GIFAnimation.let loopCount: Int
GIFAnimation.let width: Int
GIFAnimation.mutating func advance() -> Int
GIFAnimation.mutating func show(_ target: Int)
GIFAnimation.private(set) var index
GIFAnimation.private(set) var pixels: [UInt8]
GIFAnimation.static func parse(_ file: [UInt8]) -> Result<GIFAnimation, PictureError>
GIFAnimation.var frameCount: Int
HuffmanCode.mutating func build(_ lengths: [UInt8], _ start: Int, _ count: Int) -> Bool
HuffmanCode.static let fastBits
HuffmanCode.var counts
HuffmanCode.var fast
HuffmanCode.var symbols
Inflater.static func gzip(_ input: [UInt8], limit: Int) -> Result<[UInt8], InflateError>
Inflater.static func zlib(_ input: [UInt8], limit: Int) -> Result<[UInt8], InflateError>
Inflater.static func zlib(_ input: [UInt8], size: Int) -> Result<[UInt8], InflateError>
JPEG.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
JPEG.static func encode(_ picture: Picture, quality: Int = 85) -> [UInt8]?
JPEG.static func hasSignature(_ file: [UInt8]) -> Bool
MatroskaFrame.var key: Bool
MatroskaFrame.var length: Int
MatroskaFrame.var offset: Int
MatroskaFrame.var time: Int
MatroskaFrame.var track: Int
MatroskaID.static let audio
MatroskaID.static let bitDepth
MatroskaID.static let cluster
MatroskaID.static let codecID
MatroskaID.static let cueClusterPosition
MatroskaID.static let cues
MatroskaID.static let ebml
MatroskaID.static let timestampScale
MatroskaID.static let tracks
MatroskaIndex.func seek(_ milliseconds: Int, track: Int) -> Int
MatroskaIndex.init(size: Int, read: @escaping (Int, Int) -> [UInt8]) throws(MatroskaError)
MatroskaIndex.private(set) var docType: [UInt8]
MatroskaIndex.private(set) var duration
MatroskaIndex.private(set) var frames: [MatroskaFrame]
MatroskaIndex.private(set) var tracks: [MatroskaTrack]
MatroskaTrack.func isCodec(_ name: StaticString) -> Bool
MatroskaTrack.var codec: [UInt8]
MatroskaTrack.var codecDelay
MatroskaTrack.var codecPrivate: [UInt8]
MatroskaTrack.var number
MatroskaTrack.var sampleRate
MatroskaTrack.var type
MatroskaTrack.var width
MatroskaWriter.init(width: Int, height: Int, detections: Bool = false, soundRate: Int = 0, soundChannels: Int = 1)
MatroskaWriter.mutating func detections(_ text: [UInt8], milliseconds: Int) -> [UInt8]
MatroskaWriter.mutating func finish() -> [UInt8]
MatroskaWriter.mutating func frame(_ jpeg: [UInt8], milliseconds: Int) -> [UInt8]
MatroskaWriter.mutating func header(app: StaticString = "") -> [UInt8]
MatroskaWriter.mutating func sound(_ samples: [UInt8], milliseconds: Int) -> [UInt8]
MatroskaWriter.private(set) var frames
MatroskaWriter.private(set) var lastTime
PDFDictionary.init()
PDFDictionary.subscript(_ key: StaticString) -> PDFObject?
PDFDictionary.var keys: [[UInt8]]
PDFDictionary.var values: [PDFObject]
PDFDocument.enum Font: Int
PDFDocument.init(width: Double = PDFDocument.a4.width, height: Double = PDFDocument.a4.height)
PDFDocument.let width: Double, height: Double
PDFDocument.mutating func data() -> [UInt8]
PDFDocument.mutating func data(userPassword: [UInt8], ownerPassword: [UInt8], random: [UInt8]) -> [UInt8]
PDFDocument.mutating func line(x0: Double, y0: Double, x1: Double, y1: Double, width w: Double = 0.5, colour: (UInt8, UInt8, UInt8) = (0, 0, 0))
PDFDocument.mutating func newPage()
PDFDocument.mutating func picture(_ picture: Picture, x: Double, y: Double, width w: Double, height h: Double, jpeg: [UInt8]? = nil) -> Bool
PDFDocument.mutating func rectangle(x: Double, y: Double, width w: Double, height h: Double, fill: (UInt8, UInt8, UInt8))
PDFDocument.mutating func text(_ text: String, x: Double, y: Double, size: Double = 11, font: Font = .regular,
PDFDocument.static func width(_ text: String, size: Double, font: Font = .regular) -> Double
PDFDocument.static let a4
PDFObject.func isName(_ text: StaticString) -> Bool
PDFObject.var array: [PDFObject]?
PDFObject.var bytes: [UInt8]?
PDFObject.var dictionary: PDFDictionary?
PDFObject.var integer: Int?
PDFObject.var name: [UInt8]?
PDFObject.var number: Double?
PDFPage.var content: [UInt8]
PDFPage.var height: Double
PDFPage.var originX: Double
PDFPage.var originY: Double
PDFPage.var resources: PDFDictionary
PDFPage.var rotate: Int
PDFPage.var width: Double
PDFReader.init(_ bytes: [UInt8], password: [UInt8] = []) throws(PDFReadError)
PDFReader.mutating func decode(_ dictionary: PDFDictionary, _ start: Int, _ length: Int) -> [UInt8]?
PDFReader.mutating func decodeBytes(_ input: [UInt8], _ dictionary: PDFDictionary) -> [UInt8]?
PDFReader.mutating func links(page index: Int) -> [(x: Double, y: Double, width: Double, height: Double, page: Int, uri: [UInt8])]
PDFReader.mutating func object(_ number: Int, depth: Int = 0) -> PDFObject?
PDFReader.mutating func outline() -> [(level: Int, title: [UInt8], page: Int)]
PDFReader.mutating func page(_ index: Int) -> PDFPage?
PDFReader.mutating func resolve(_ value: PDFObject, depth: Int = 0) -> PDFObject
PDFReader.mutating func streamBytes(_ value: PDFObject) -> [UInt8]?
PDFReader.mutating func text(page index: Int) -> [PDFTextRun]
PDFReader.private(set) var isEncrypted
PDFReader.private(set) var openedAsOwner
PDFReader.private(set) var permissions: UInt32
PDFReader.private(set) var trailer
PDFReader.static func textString(_ bytes: [UInt8]) -> [UInt8]
PDFReader.static let maximumFile
PDFReader.static let maximumStream
PDFReader.var pageCount: Int
PDFTextRun.var size: Double
PDFTextRun.var text: [UInt8]
PDFTextRun.var width: Double
PDFTextRun.var x: Double
PDFTextRun.var y: Double
PNG.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
PNG.static func encode(_ picture: Picture) -> [UInt8]?
PNG.static func hasSignature(_ file: [UInt8]) -> Bool
PNG.static func size(_ file: [UInt8]) -> (width: Int, height: Int)?
PNGSink.mutating func write(_ data: Span<UInt8>) -> Bool
PNGSink.var bytes
Picture.init(width: Int = 0, height: Int = 0, pixels: [UInt8] = [], scale: Int = 1)
Picture.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
Picture.static let maxFile
Picture.static let maxPixels
Picture.var height
Picture.var pixels: [UInt8]
Picture.var scale
Picture.var width
PictureError.var text: StaticString
TIFF.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
TIFF.static func encode(_ picture: Picture) -> [UInt8]?
TIFF.static func hasSignature(_ file: [UInt8]) -> Bool
WebP.static func decode(_ file: [UInt8]) -> Result<Picture, PictureError>
WebP.static func hasSignature(_ file: [UInt8]) -> Bool
WebPAnimation.func delay(_ frame: Int) -> Int
WebPAnimation.let height: Int
WebPAnimation.let loopCount: Int
WebPAnimation.let width: Int
WebPAnimation.mutating func advance()
WebPAnimation.mutating func show(_ target: Int)
WebPAnimation.private(set) var index
WebPAnimation.private(set) var pixels: [UInt8]
WebPAnimation.static func parse(_ file: [UInt8]) -> Result<WebPAnimation, PictureError>
WebPAnimation.var frameCount: Int
enum BMP
enum GIF
enum InflateError: UInt8, Error
enum JPEG
enum MatroskaError: Error, Equatable
enum MatroskaID
enum PDFObject
enum PDFReadError: Error, Equatable
enum PNG
enum PictureError: UInt8, Error
enum TIFF
enum WebP
struct GIFAnimation
struct HuffmanCode
struct Inflater
struct MatroskaFrame
struct MatroskaIndex
struct MatroskaTrack
struct MatroskaWriter
struct PDFDictionary
struct PDFDocument
struct PDFPage
struct PDFReader
struct PDFTextRun
struct PNGSink: ByteSink
struct Picture
struct WebPAnimation

svg · SVG

Reading and drawing SVG: document, paths, matrices, colours, fonts, onto a canvas or into a picture.

Source: userland/svg/ · file uses-svg · 105 declarations

All 105 declarations of the library (docs/api/libraries.txt)
PDFCharacter.var run: Int
PDFCharacter.var text: [UInt8]
PDFCharacter.var x: Double, y: Double, width: Double, height: Double
PDFRender.static func characters(_ reader: inout PDFReader, _ index: Int, scale: Double) -> [PDFCharacter]
PDFRender.static func page(_ reader: inout PDFReader, _ index: Int, scale: Double, maximumPixels: Int = 40_000_000) -> SVGCanvas?
SVGCanvas.func straightRGBA() -> [UInt8]
SVGCanvas.init(width: Int, height: Int)
SVGCanvas.let height: Int
SVGCanvas.let width: Int
SVGCanvas.var pixels: [UInt8]
SVGColor.init(_ r: Float, _ g: Float, _ b: Float, _ a: Float = 1)
SVGColor.static func parse(_ raw: String) -> SVGColor?
SVGColor.static let black
SVGColor.static let transparent
SVGColor.var r: Float, g: Float, b: Float, a: Float
SVGDocument.func text(of index: Int) -> String
SVGDocument.init()
SVGDocument.private(set) var ids: [String: Int]
SVGDocument.private(set) var nodes: [SVGNode]
SVGDocument.private(set) var styles: [String]
SVGDocument.static func build(root: Int, _ element: (Int) -> (name: String, attributes: [(name: String, value: String)], children: [Int], text: String))
SVGDocument.static func parse(_ bytes: [UInt8]) -> Result<SVGDocument, SVGError>
SVGDocument.static let maxDepth
SVGDocument.static let maxNodes
SVGFonts.init(sans: OutlineFont? = nil, bold: OutlineFont? = nil, mono: OutlineFont? = nil, serif: OutlineFont? = nil)
SVGFonts.var bold: OutlineFont?
SVGFonts.var mono: OutlineFont?
SVGFonts.var sans: OutlineFont?
SVGFonts.var serif: OutlineFont?
SVGImage.func render(width: Int, height: Int) -> SVGCanvas
SVGImage.func render(width: Int, height: Int, sceneWidth: Double, sceneHeight: Double, x: Double, y: Double) -> SVGCanvas
SVGImage.func renderRGBA(width: Int, height: Int) -> [UInt8]
SVGImage.init(_ document: SVGDocument)
SVGImage.let intrinsicHeight: Double
SVGImage.let intrinsicWidth: Double
SVGImage.nonisolated(unsafe) static var fonts
SVGImage.nonisolated(unsafe) static var loadFonts: (() -> SVGFonts)?
SVGImage.static func parse(_ bytes: [UInt8]) -> Result<SVGImage, SVGError>
SVGImage.static let maxDrawn
SVGImage.static let maxSide
SVGImage.var currentColor: SVGColor?
SVGLength.enum Unit: Sendable
SVGLength.func resolve(_ reference: Double, fontSize: Double) -> Double
SVGLength.init(_ value: Double, _ unit: Unit)
SVGLength.static func parse(_ text: String) -> SVGLength?
SVGLength.var unit: Unit
SVGLength.var value: Double
SVGMatrix.func apply(_ x: Double, _ y: Double) -> (Double, Double)
SVGMatrix.func multiplied(_ m: SVGMatrix) -> SVGMatrix
SVGMatrix.init()
SVGMatrix.init(_ a: Double, _ b: Double, _ c: Double, _ d: Double, _ e: Double, _ f: Double)
SVGMatrix.static func rotate(_ degrees: Double) -> SVGMatrix
SVGMatrix.static func scale(_ x: Double, _ y: Double) -> SVGMatrix
SVGMatrix.static func skewX(_ degrees: Double) -> SVGMatrix
SVGMatrix.static func skewY(_ degrees: Double) -> SVGMatrix
SVGMatrix.static func translate(_ x: Double, _ y: Double) -> SVGMatrix
SVGMatrix.static let identity
SVGMatrix.var a
SVGMatrix.var inverse: SVGMatrix?
SVGMatrix.var scaleFactor: Double
SVGNode.func attribute(_ name: String) -> String?
SVGNode.init(name: String, attributes: [(name: String, value: String)] = [], parent: Int = -1, children: [Int] = [], text: String = "")
SVGNode.var attributes: [(name: String, value: String)]
SVGNode.var children: [Int]
SVGNode.var name: String
SVGNode.var parent: Int
SVGNode.var text: String
SVGNumberScanner.init(_ text: String)
SVGNumberScanner.mutating func number() -> Double?
SVGNumberScanner.mutating func unit() -> String
SVGNumberScanner.var atEnd: Bool
SVGPath.func bounds() -> (Double, Double, Double, Double)?
SVGPath.func flattened(tolerance: Double) -> [SVGPolyline]
SVGPath.func transformed(_ m: SVGMatrix) -> SVGPath
SVGPath.init()
SVGPath.init(_ segments: [SVGSegment])
SVGPath.static func ellipse(cx: Double, cy: Double, rx: Double, ry: Double) -> SVGPath
SVGPath.static func line(_ x1: Double, _ y1: Double, _ x2: Double, _ y2: Double) -> SVGPath
SVGPath.static func parse(_ data: String) -> SVGPath
SVGPath.static func poly(_ text: String, closed: Bool) -> SVGPath
SVGPath.static func rect(x: Double, y: Double, width: Double, height: Double, rx rIn: Double, ry rYIn: Double) -> SVGPath
SVGPath.var isEmpty: Bool
SVGPath.var segments: [SVGSegment]
SVGPolyline.var closed
SVGPolyline.var points: [(Double, Double)]
enum PDFRender
enum SVGError: Error, Equatable, Sendable
enum SVGFillRule: Sendable
enum SVGLineCap: Sendable
enum SVGLineJoin: Sendable
enum SVGPaintFallback: Equatable, Sendable
enum SVGPaintValue: Equatable, Sendable
enum SVGSegment: Equatable, Sendable
struct PDFCharacter
struct SVGCanvas: Sendable
struct SVGColor: Equatable, Sendable
struct SVGDocument: Sendable
struct SVGFonts: Sendable
struct SVGImage: Sendable
struct SVGLength: Equatable, Sendable
struct SVGMatrix: Equatable, Sendable
struct SVGNode: Sendable
struct SVGNumberScanner
struct SVGPath: Sendable
struct SVGPolyline: Sendable

sound · Sound: tools and formats

Playing (sound.play): every program gets a ring that the kernel's mixer plays (48 kHz, stereo, Int16). Listening (sound.microphone): the kernel writes what a microphone hears into one ring per microphone (48 kHz, 16 bit, mono/stereo, about 1.4 s), mapped read-only into every listening program; the level of each 10 ms period sits next to it. The microphone runs only while someone listens; the red MIC indicator names every program, and the owner can stop them all. The tools (level, auto level, noise gate, voice detection, editing) come with uses-heap.

Source: userland/sound/ · file uses-heap · 118 declarations

SwiftLevelMeter · AutoLevel · NoiseGate · VoiceDetector · SoundEditLevel, dynamics, voice, editing

CallWhat it doesShape call · time budget
Level
LevelMeter.measure(_ samples: Span<Int16>) -> SoundLevelRMS and peak in dBFS.
Example
let level = LevelMeter.measure(span)   // level.peak, level.rms in dBFS
from apps/sound (shortened)
LevelMeter.periods(_ samples: Span<Int16>, channels: Int = 1) -> [SoundLevel]Level per 10 ms period.
LevelMeter.decibels / .amplitude / .linear / .floor / .fullScaleConversions dB ↔ amplitude.
Dynamics
AutoLevel(target: Double = -12, minimumGain: -12, maximumGain: 24, silence: -55, ceiling: -1, channels: 1, gain: 0)Automatic gain with limiter; process(&samples).
Example
autoLevel = AutoLevel(channels: channels, gain: Double(choices.gain))
autoLevel.process(&span)
from apps/sound (shortened)
NoiseGate(threshold: Double = -50, holdMilliseconds: 200, fadeMilliseconds: 5, channels: 1)Noise gate; process(&samples), isOpen.
Example
gate = NoiseGate(channels: channels)
gate.process(&span)
from apps/sound (shortened)
Voice
VoiceDetector(margin: 10, minimumLevel: -65, crossings: 0.004...0.25, hangoverMilliseconds: 300, channels: 1, noiseFloor: nil)Is someone speaking? detect(period) -> Bool, level, noiseFloor.
Example
voice = VoiceDetector(channels: channels)
speaking = voice.detect(span)
from apps/sound (shortened)
VoiceDetector.voiceParts(_ samples: [Int16], channels: Int = 1, gapMilliseconds: Int = 300, shortestMilliseconds: Int = 200) -> [Range<Int>]Speech passages of a recording.
Example
voiceParts = VoiceDetector.voiceParts(sound.samples, channels: sound.channels)
from apps/sound (shortened)
Recording & editing
PreRecordBuffer(seconds: Int = 5, channels: Int = 1): append / .drain / .clear / .framesThe last seconds before recording starts.
Example
preRecord = PreRecordBuffer(seconds: 5, channels: channels)
preRecord.append(span)            // every period
let before = preRecord.drain()    // when recording starts
from apps/sound (shortened)
SoundEdit.trim / .trimSilenceEnds / .splitAtPauses / .normalize / .voiceBounds / .overviewTrim, shorten silence, split at pauses, normalise, waveform.
Example
let samples = SoundEdit.trimSilenceEnds(sound.samples, channels: sound.channels)
let parts = SoundEdit.splitAtPauses(sound.samples, channels: sound.channels)
from apps/sound (shortened)
OverviewBuilder(framesPerColumn:channels:reserveSeconds:): append / .overview(columns:)Build a waveform continuously (WaveColumn min/max).
Format
SoundFormat.rate / .periodFrames / .frames(milliseconds:)48 kHz, 480 frames per 10 ms.

SwiftWAV · FLACReading WAV, writing and reading FLAC

CallWhat it doesShape call · time budget
WAV
WAV(_ file: Span<UInt8>)Reads a WAV header: rate, channels, bits, float, frames, dataStart, milliseconds.
Example
} else if let wav = head.withUnsafeBufferPointer({ WAV(Span(_unsafeElements: $0)) }) {
from apps/sound (shortened)
WAV.render(_ file: Span<UInt8>, from first: Int, count: Int, into out: UnsafeMutablePointer<Int16>) -> Int / .sample(_:_:_:)Frames as Int16 (stereo 48 kHz for Sound.Output).
Writing FLAC
FLACEncoder(rate: Int, channels: Int, bits: Int, blockSize: Int = 4096, maxLPCOrder: Int = 12)FLAC encoder.
Example
let encoder = FLACEncoder(rate: rate, channels: channels, bits: 16)
file.pending = encoder.header()
from apps/sound (shortened)
FLACEncoder.header() / .encode(_ samples: Span<Int16> | Span<Int32>) -> [UInt8] / .finish()Header, blocks, finish (with the final header).
Reading FLAC
FLACDecoder(_ data: [UInt8]) / .init(length:read:) throws(FLACError)Read FLAC (whole or through a read function).
Example
if var decoder = try? FLACDecoder(flac) {
    while let block = try? decoder.nextBlock(), !block.isEmpty { for value in block { decoded.append(Int16(truncatingIfNeeded: value)) } }
}
from apps/miccheck (shortened)
FLACDecoder.nextBlock() throws(FLACError) -> [Int32] / .seek(toSample:) / .info: FLACInfoNext block, seeking, stream info (rate, channels, bits, totalSamples, md5).
Example: writing a FLAC file (apps/sound, SoundFile.swift)
var encoder = FLACEncoder(rate: rate, channels: channels, bits: 16)
pending = encoder.header()
// per 10 ms period:
pending += encoder.encode(samples)          // Span<Int16>
// at the end:
let (tail, finalHeader) = encoder.finish()
All 118 declarations of the library (docs/api/libraries.txt)
AutoLevel.init(target: Double = -12, minimumGain: Double = -12, maximumGain: Double = 24, silence: Double = -55,
AutoLevel.let ceiling: Double
AutoLevel.let channels: Int
AutoLevel.let maximumGain: Double
AutoLevel.let minimumGain: Double
AutoLevel.let silence: Double
AutoLevel.let target: Double
AutoLevel.mutating func process(_ samples: inout MutableSpan<Int16>)
AutoLevel.private(set) var gain: Double
AutoLevel.private(set) var limit
AutoLevel.var reduction: Double
FLACDecoder.init(_ data: [UInt8]) throws(FLACError)
FLACDecoder.init(length: Int, read: @escaping (_ offset: Int, _ count: Int) -> [UInt8]) throws(FLACError)
FLACDecoder.mutating func nextBlock() throws(FLACError) -> [Int32]
FLACDecoder.mutating func seek(toSample sample: Int) throws(FLACError)
FLACDecoder.private(set) var info: FLACInfo
FLACDecoder.private(set) var position
FLACEncoder.func header() -> [UInt8]
FLACEncoder.init(rate: Int, channels: Int, bits: Int, blockSize: Int = 4096, maxLPCOrder: Int = 12)
FLACEncoder.let bits: Int
FLACEncoder.let blockSize: Int
FLACEncoder.let channels: Int
FLACEncoder.let rate: Int
FLACEncoder.mutating func encode(_ samples: Span<Int16>) -> [UInt8]
FLACEncoder.mutating func encode(_ samples: Span<Int32>) -> [UInt8]
FLACEncoder.mutating func finish() -> (tail: [UInt8], finalHeader: [UInt8])
FLACInfo.init(rate: Int, channels: Int, bits: Int, totalSamples: Int = 0, minBlock: Int = 4096, maxBlock: Int = 4096,
FLACInfo.var bits: Int
FLACInfo.var channels: Int
FLACInfo.var maxBlock: Int
FLACInfo.var maxFrame: Int
FLACInfo.var md5: [UInt8]
FLACInfo.var minBlock: Int
FLACInfo.var minFrame: Int
FLACInfo.var rate: Int
FLACInfo.var totalSamples: Int
LevelMeter.static func amplitude(_ decibels: Double) -> Double
LevelMeter.static func decibels(_ amplitude: Double) -> Double
LevelMeter.static func linear(_ decibels: Double) -> Double
LevelMeter.static func measure(_ samples: Span<Int16>) -> SoundLevel
LevelMeter.static func periods(_ samples: Span<Int16>, channels: Int = 1) -> [SoundLevel]
LevelMeter.static let floor
LevelMeter.static let fullScale
NoiseGate.init(threshold: Double = -50, holdMilliseconds: Int = 200, fadeMilliseconds: Int = 5, channels: Int = 1)
NoiseGate.let channels: Int
NoiseGate.let fadeFrames: Int
NoiseGate.let holdFrames: Int
NoiseGate.let threshold: Double
NoiseGate.mutating func process(_ samples: inout MutableSpan<Int16>)
NoiseGate.private(set) var isOpen
OverviewBuilder.func overview(columns count: Int) -> [WaveColumn]
OverviewBuilder.init(framesPerColumn: Int = SoundFormat.periodFrames, channels: Int = 1, reserveSeconds: Int = 600)
OverviewBuilder.let channels: Int
OverviewBuilder.let framesPerColumn: Int
OverviewBuilder.mutating func append(_ period: Span<Int16>)
OverviewBuilder.private(set) var columns: [WaveColumn]
OverviewBuilder.private(set) var frames
OverviewBuilder.var allColumns: [WaveColumn]
PreRecordBuffer.init(seconds: Int = 5, channels: Int = 1)
PreRecordBuffer.let capacity: Int
PreRecordBuffer.let channels: Int
PreRecordBuffer.mutating func append(_ period: Span<Int16>)
PreRecordBuffer.mutating func clear()
PreRecordBuffer.mutating func drain() -> [Int16]
PreRecordBuffer.mutating func drain(into output: inout [Int16])
PreRecordBuffer.var frames: Int
SoundEdit.static func normalize(_ samples: [Int16], channels: Int = 1, peak: Double = -1) -> [Int16]
SoundEdit.static func overview(_ samples: [Int16], channels: Int = 1, columns: Int) -> [WaveColumn]
SoundEdit.static func splitAtPauses(_ samples: [Int16], channels: Int = 1, minimumPartMilliseconds: Int = 2000,
SoundEdit.static func trim(_ samples: [Int16], channels: Int = 1, from: Int, to: Int) -> [Int16]
SoundEdit.static func trimSilenceEnds(_ samples: [Int16], channels: Int = 1, paddingMilliseconds: Int = 50) -> [Int16]
SoundEdit.static func voiceBounds(_ samples: [Int16], channels: Int = 1, paddingMilliseconds: Int = 50) -> Range<Int>?
SoundFormat.static func frames(milliseconds: Int) -> Int
SoundFormat.static let periodFrames
SoundFormat.static let rate
SoundLevel.init(rms: Double, peak: Double)
SoundLevel.var peak: Double
SoundLevel.var rms: Double
VoiceDetector.init(margin: Double = 10, minimumLevel: Double = -65, crossings: ClosedRange<Double> = 0.004...0.25,
VoiceDetector.let channels: Int
VoiceDetector.let crossings: ClosedRange<Double>
VoiceDetector.let hangoverPeriods: Int
VoiceDetector.let margin: Double
VoiceDetector.let minimumLevel: Double
VoiceDetector.mutating func detect(_ period: Span<Int16>) -> Bool
VoiceDetector.private(set) var heard
VoiceDetector.private(set) var level
VoiceDetector.private(set) var noiseFloor
VoiceDetector.static func voiceParts(_ samples: [Int16], channels: Int = 1, gapMilliseconds: Int = 300,
WAV.func render(_ file: Span<UInt8>, from first: Int, count: Int, into out: UnsafeMutablePointer<Int16>) -> Int
WAV.func sample(_ file: Span<UInt8>, _ frame: Int, _ channel: Int) -> Int32
WAV.init?(_ file: Span<UInt8>)
WAV.let bits: Int
WAV.let channels: Int
WAV.let dataStart: Int
WAV.let float: Bool
WAV.let frames: Int
WAV.let rate: Int
WAV.var milliseconds: Int
WAV.var outputFrames: Int
WaveColumn.init(min: Int16, max: Int16)
WaveColumn.var max: Int16
WaveColumn.var min: Int16
enum FLACError: Error, Equatable
enum LevelMeter
enum SoundEdit
enum SoundFormat
struct AutoLevel
struct FLACDecoder
struct FLACEncoder
struct FLACInfo: Equatable
struct NoiseGate
struct OverviewBuilder
struct PreRecordBuffer
struct SoundLevel: Equatable
struct VoiceDetector
struct WAV
struct WaveColumn: Equatable

archive · Archives: ZIP, Deflate

With uses-archive (needs uses-heap): read and write ZIP; a password always means WinZip AES-256. Plus raw DEFLATE and CRC32.

Source: userland/archive/ · file uses-archive · 79 declarations

SwiftZipArchive · ZipEntryReading

CallWhat it doesShape call · time budget
Reading contents
ZipArchive.entries<S: ByteSource>(_ source: inout S) -> Result<[ZipEntry], ZipError>Read the table of contents.
Example
var source = bytesSource            // a ByteSource over the file
guard case .success(let entries) = ZipArchive.entries(&source) else { return }
Pattern (short, not copied from a program)
ZipEntry: name, size, compressedSize, crc, isDirectory, isEncrypted, isLink, method, aes…One entry.
Extracting
ZipArchive.extract(_ entries: [ZipEntry], from source: S, to destination: inout D, password: [UInt8]?) -> Result<ZipSummary, ZipError>Extract entries (ZipSummary: files, folders, bytes, skipped).
ZipArchive.safePath(_ entry: ZipEntry) -> [UInt8]?Safe path (no “..”, no absolute path).

SwiftZipWriterWriting

CallWhat it doesShape call · time budget
Write
ZipWriter.beginFile(_ file: Span<UInt8>, time: ZipTime, password: [UInt8]?, salt: Span<UInt8>, _ sink: inout Sink) -> Result<Void, ZipError>Begin a file (with a password: AES-256).
ZipWriter.write(_ data: Span<UInt8>, _ sink: inout Sink) / .endFile(_:) / .addFolder(_:time:_:) / .finish(_:)Data, end of file, folder, finish.
Time
ZipTime(unixSeconds: Int64, offsetSeconds: Int64)Timestamp.

SwiftDeflater · StreamInflater · CRC32Deflate & checksums

CallWhat it doesShape call · time budget
Deflate & checksums
Deflater.compress(_:_:) / .finish(_:) / .reset()Compress raw DEFLATE.
StreamInflater.next(_ source: inout S) -> Result<Range<Int>?, InflateError> / .reset() / .totalInflate raw DEFLATE piece by piece.
CRC32.add(_ bytes: Span<UInt8>) / .checksum / .reset()CRC-32.
Example
var crc = CRC32()
crc.add(data.span)
let sum = crc.checksum
Pattern (short, not copied from a program)
All 79 declarations of the library (docs/api/libraries.txt)
ByteCollector.mutating func write(_ data: Span<UInt8>) -> Bool
ByteCollector.var bytes
CRC32.func step(_ crc: UInt32, _ byte: UInt8) -> UInt32
CRC32.init()
CRC32.mutating func add(_ bytes: Span<UInt8>)
CRC32.mutating func reset()
CRC32.var checksum: UInt32
Deflater.init()
Deflater.mutating func compress<Sink: ByteSink>(_ data: Span<UInt8>, _ sink: inout Sink) -> Bool
Deflater.mutating func finish<Sink: ByteSink>(_ sink: inout Sink) -> Bool
Deflater.mutating func reset()
Deflater.static func canonicalCodes(_ lengths: [UInt8], _ count: Int) -> [UInt16]
Deflater.static func huffmanLengths(_ frequencies: [UInt32], _ count: Int, limit: Int) -> [UInt8]
Deflater.static let distanceBase: InlineArray<30, UInt16>
Deflater.static let distanceExtra: InlineArray<30, UInt8>
Deflater.static let lengthBase: InlineArray<29, UInt16>
Deflater.static let lengthExtra: InlineArray<29, UInt8>
StreamInflater.init()
StreamInflater.mutating func next<S: ByteSource>(_ source: inout S) -> Result<Range<Int>?, InflateError>
StreamInflater.mutating func reset()
StreamInflater.private(set) var total: UInt64
StreamInflater.static let flushAt
StreamInflater.static let history
ZipArchive.static func entries<S: ByteSource>(_ source: inout S) -> Result<[ZipEntry], ZipError>
ZipArchive.static func extract<S: ByteSource, D: ZipDestination>(_ entries: [ZipEntry], from source: S, to destination: inout D,
ZipArchive.static func safePath(_ entry: ZipEntry) -> [UInt8]?
ZipEntry.var aesMethod: UInt16
ZipEntry.var aesStrength: UInt8
ZipEntry.var aesVersion: UInt16
ZipEntry.var compressedSize: UInt64
ZipEntry.var crc: UInt32
ZipEntry.var dosTime: UInt32
ZipEntry.var external: UInt32
ZipEntry.var flags: UInt16
ZipEntry.var isDirectory: Bool
ZipEntry.var isEncrypted: Bool
ZipEntry.var isLink: Bool
ZipEntry.var madeBy: UInt16
ZipEntry.var method: UInt16
ZipEntry.var name: [UInt8]
ZipEntry.var offset: UInt64
ZipEntry.var size: UInt64
ZipError.var text: StaticString
ZipInput.init(source: S)
ZipInput.mutating func bytes(_ wanted: Int) -> [UInt8]?
ZipInput.mutating func read(into out: inout [UInt8]) -> Int
ZipInput.mutating func skip(to target: UInt64) -> Bool
ZipInput.var failure: ZipError
ZipInput.var remaining: UInt64
ZipInput.var source: S
ZipSummary.var bytes: UInt64
ZipSummary.var files
ZipSummary.var folders
ZipSummary.var skipped
ZipTime.init()
ZipTime.init(unixSeconds: Int64, offsetSeconds: Int64)
ZipTime.var dos: UInt32
ZipTime.var unix: UInt32
ZipWriter.init()
ZipWriter.mutating func addFolder<Sink: ByteSink>(_ folder: Span<UInt8>, time: ZipTime, _ sink: inout Sink) -> Result<Void, ZipError>
ZipWriter.mutating func beginFile<Sink: ByteSink>(_ file: Span<UInt8>, time: ZipTime, password: [UInt8]?, salt: Span<UInt8>,
ZipWriter.mutating func endFile<Sink: ByteSink>(_ sink: inout Sink) -> Result<Void, ZipError>
ZipWriter.mutating func finish<Sink: ByteSink>(_ sink: inout Sink) -> Result<Void, ZipError>
ZipWriter.mutating func write<Sink: ByteSink>(_ data: Span<UInt8>, _ sink: inout Sink) -> Result<Void, ZipError>
ZipWriter.var written: UInt64
enum ZipArchive
enum ZipError: UInt8, Error
protocol ByteSink
protocol ByteSource
protocol ZipDestination
struct ByteCollector: ByteSink
struct CRC32
struct Deflater
struct StreamInflater
struct ZipEntry
struct ZipInput<S: ByteSource>: ByteSource
struct ZipSummary
struct ZipTime
struct ZipWriter

sql · SQL

Translating SQL statements into SOFTrobotsDB queries and write sets (SQL.translate, run with Database.next(query:aggregate:grouped:into:)); plus the description of the tables.

Source: userland/sql/ · file uses-sql · 52 declarations

All 52 declarations of the library (docs/api/libraries.txt)
DatabaseDescription.static func enumValue(_ description: Span<UInt8>, _ field: DescribedField, _ text: Span<UInt8>, _ start: Int, _ length: Int) -> Int?
DatabaseDescription.static func field(_ description: Span<UInt8>, _ table: DescribedTable, named text: Span<UInt8>, _ start: Int, _ length: Int) -> Int?
DatabaseDescription.static func table(_ description: Span<UInt8>, _ index: Int) -> DescribedTable?
DatabaseDescription.static func table(_ description: Span<UInt8>, named name: Span<UInt8>) -> (index: Int, table: DescribedTable)?
DatabaseDescription.static func tableCount(_ description: Span<UInt8>) -> Int
DatabaseDescription.static func withEnumName<R>(_ description: Span<UInt8>, _ field: DescribedField, _ value: Int, _ body: (Span<UInt8>) -> R) -> R?
DescribedField.init()
DescribedField.var enumCount: Int
DescribedField.var enumStart: Int
DescribedField.var flags: UInt8
DescribedField.var isFloat: Bool
DescribedField.var isOptional: Bool
DescribedField.var isSigned: Bool
DescribedField.var isText: Bool
DescribedField.var isUnique: Bool
DescribedField.var isVariable: Bool
DescribedField.var maximum: Int
DescribedField.var nameLength: Int
DescribedField.var nameStart: Int
DescribedField.var reference: Int
DescribedField.var size: Int
DescribedField.var type: UInt8
DescribedTable.init()
DescribedTable.var fieldCount
DescribedTable.var fields
DescribedTable.var indexCount
DescribedTable.var indexFields
DescribedTable.var indexLengths
DescribedTable.var nameLength
DescribedTable.var nameStart
SQL.static func lookup(_ description: Span<UInt8>, table index: Int, field: Int, id: UInt64,
SQL.static func translate(_ text: Span<UInt8>, _ description: Span<UInt8>,
SQLError.var message: StaticString
SQLError.var position: Int
SQLStatement.init()
SQLStatement.var aggregate
SQLStatement.var aggregateField
SQLStatement.var columnCount
SQLStatement.var columns
SQLStatement.var group
SQLStatement.var hasJoins: Bool
SQLStatement.var joinField
SQLStatement.var joinInner
SQLStatement.var joinTable
SQLStatement.var length
SQLStatement.var table
enum DatabaseDescription
enum SQL
struct DescribedField
struct DescribedTable
struct SQLError: Error
struct SQLStatement

maths · Maths

Without a heap you need fixed building blocks: TextLine is a line of fixed size (160 bytes), WallClock computes calendar times (Berlin), Maths provides the functions of the maths library for every profile.

Source: userland/maths/ · no file, in every profile · 25 declarations

SwiftMathsFunctions of the maths library

CallWhat it doesShape call · time budget
Maths
Maths.sin, .cos, .tan, .asin, .acos, .atan, .atan2, .sinCosTrigonometry.
Example
let out = p.x * Maths.cos(yaw) + p.y * Maths.sin(yaw)
from apps/fpcheck (shortened)
Maths.sqrt, .hypot, .pow, .exp, .log, .log2, .log10Roots, powers, logarithms.
Maths.floor, .ceil, .round, .trunc, .fmod, .radians, .degreesRounding and converting.
Maths.pi, .eConstants.
All 25 declarations of the library (docs/api/libraries.txt)
Maths.static func acos(_ x: Double) -> Double
Maths.static func asin(_ x: Double) -> Double
Maths.static func atan(_ value: Double) -> Double
Maths.static func atan2(_ y: Double, _ x: Double) -> Double
Maths.static func ceil(_ x: Double) -> Double
Maths.static func cos(_ x: Double) -> Double
Maths.static func degrees(_ radians: Double) -> Double
Maths.static func exp(_ x: Double) -> Double
Maths.static func floor(_ x: Double) -> Double
Maths.static func fmod(_ x: Double, _ y: Double) -> Double
Maths.static func hypot(_ x: Double, _ y: Double) -> Double
Maths.static func log(_ x: Double) -> Double
Maths.static func log10(_ x: Double) -> Double
Maths.static func log2(_ x: Double) -> Double
Maths.static func pow(_ x: Double, _ y: Double) -> Double
Maths.static func radians(_ degrees: Double) -> Double
Maths.static func round(_ x: Double) -> Double
Maths.static func sin(_ x: Double) -> Double
Maths.static func sinCos(_ x: Double) -> (sin: Double, cos: Double)
Maths.static func sqrt(_ x: Double) -> Double
Maths.static func tan(_ x: Double) -> Double
Maths.static func trunc(_ x: Double) -> Double
Maths.static let e
Maths.static let pi
enum Maths

video · Video: VP9

Containers and codecs for recording and playback: Matroska/WebM (uses-image), VP9 (uses-video), Opus (uses-opus), WAV and FLAC (with uses-heap). Camera records MKV with MJPEG, sound and detections; Video plays MKV and WebM (VP9 + Opus).

Source: userland/video/ · file uses-video · 25 declarations

SwiftVP9Decoder · VP9PictureVideo (VP9)

CallWhat it doesShape call · time budget
Video (VP9)
VP9Decoder() / .decode(_ packet: [UInt8]) throws(VP9Error) -> VP9Picture?Decode a VP9 packet.
Example
guard let shown = try? vp9.decode(bytes) else { return }
let picture = Picture(width: shown.width, height: shown.height, pixels: shown.rgba())
from apps/video (shortened)
VP9Picture.rgba() -> [UInt8] / .y, u, v, yStride, uvStride, width, heightImage as RGBA or YUV planes.
All 25 declarations of the library (docs/api/libraries.txt)
VP9Bench.static func computeLoop(_ seed: UInt64) -> UInt64
VP9Decoder.init()
VP9Decoder.mutating func decode(_ packet: [UInt8]) throws(VP9Error) -> VP9Picture?
VP9Decoder.nonisolated(unsafe) static var loopThreads
VP9Decoder.nonisolated(unsafe) static var pause: (() -> Void)?
VP9Decoder.nonisolated(unsafe) static var runParallel: ((@convention(c) (UnsafeMutableRawPointer?, Int, Int) -> Void,
VP9Decoder.var maxPixels
VP9Error.var text: StaticString
VP9Picture.func rgba() -> [UInt8]
VP9Picture.func rgba(into out: inout [UInt8])
VP9Picture.var chromaHeight: Int
VP9Picture.var chromaWidth: Int
VP9Picture.var colorSpace: Int
VP9Picture.var fullRange: Bool
VP9Picture.var height: Int
VP9Picture.var u: [UInt8]
VP9Picture.var uvStride: Int
VP9Picture.var v: [UInt8]
VP9Picture.var width: Int
VP9Picture.var y: [UInt8]
VP9Picture.var yStride: Int
enum VP9Bench
enum VP9Error: UInt8, Error
struct VP9Decoder
struct VP9Picture

qr · QR codes

With uses-image (needs uses-heap): decode and encode images, write and read PDF. A Picture holds RGBA pixels. Reading PDF is untrusted input – so the programs Reader and Image read only the one document handed to them. QR codes with uses-qr (without a heap).

Source: userland/qr/ · file uses-qr · 10 declarations

SwiftQRCodeEncoding

CallWhat it doesShape call · time budget
Encoding
QRCode.encode(_ bytes: Span<UInt8>, correction: QRCorrection = .medium, mask: Int? = nil) -> QRCode?staticQR code in byte mode (versions 1 … 10, levels L/M/Q/H).
Example
invitationQR = QRCode.encode(bytes.span.extracting(0..<text.count), correction: .medium)
from apps/server (shortened)
QRCode.capacity(version: Int, correction: QRCorrection) -> IntstaticHow many bytes fit.
Read
QRCode.isDark(x: Int, y: Int) -> Bool / .size / .version / .correction / .maskRead modules.
Example: QR code for an invitation (apps/server)
invitationQR = QRCode.encode(bytes.span.extracting(0..<text.count), correction: .medium)
guard let code = invitationQR else { return }
let modules = code.size + 8
for y in 0..<code.size { for x in 0..<code.size where code.isDark(x: x, y: y) { /* fill the module */ } }
All 10 declarations of the library (docs/api/libraries.txt)
QRCode.func isDark(x: Int, y: Int) -> Bool
QRCode.let correction: QRCorrection
QRCode.let mask: Int
QRCode.let version: Int
QRCode.static func capacity(version: Int, correction: QRCorrection) -> Int
QRCode.static func encode(_ bytes: Span<UInt8>, correction: QRCorrection = .medium, mask: Int? = nil) -> QRCode?
QRCode.static let maximumVersion
QRCode.var size: Int
enum QRCorrection: Sendable
struct QRCode: Sendable

opus · Opus

Containers and codecs for recording and playback: Matroska/WebM (uses-image), VP9 (uses-video), Opus (uses-opus), WAV and FLAC (with uses-heap). Camera records MKV with MJPEG, sound and detections; Video plays MKV and WebM (VP9 + Opus).

Source: userland/opus/ · file uses-opus · 8 declarations

SwiftOpusDecoderSound (Opus)

CallWhat it doesShape call · time budget
Sound (Opus)
OpusDecoder(head: [UInt8]) / .decode(_ packet: [UInt8]) throws(OpusError) -> [Float] / .reset()Opus packets to float samples; channels, preSkip, gain.
All 8 declarations of the library (docs/api/libraries.txt)
OpusDecoder.init?(head: [UInt8])
OpusDecoder.mutating func decode(_ packet: [UInt8]) throws(OpusError) -> [Float]
OpusDecoder.mutating func reset()
OpusDecoder.private(set) var channels: Int
OpusDecoder.private(set) var gain: Float
OpusDecoder.private(set) var preSkip: Int
enum OpusError: Error, Equatable
struct OpusDecoder

Assignment & completeness

Every declaration of docs/api/app-api-1.txt and every system call of shapes/*.shape is assigned to exactly one module, as App-API or System-API (numbers “App · System”). The complete list per module is at the end of each module section (“All … declarations”).

Assignment

ModuleSystem-call modulesRightsSystem callsSwift declarations
systemcore, system2 · 49 · 397 · 4
programsprograms0 · 25 · 1638 · 53
filesfiles1 · 210 · 544 · 10
databasedatabase0 · 16 · 0134 · 0
networkask, network1 · 112 · 427 · 11
uidisplay, screen1 · 32 · 5354 · 17
soundmicrophone, signal, sound2 · 213 · 538 · 7
cameracamera, vision1 · 110 · 267 · 4
robotarm, devices, robot0 · 26 · 297 · 4
safetysafety0 · 21 · 24 · 2
channelschannels, peers1 · 03 · 026 · 0
clipboardclipboard0 · 03 · 14 · 1
dialogdialog0 · 12 · 212 · 0
updateupdate0 · 10 · 40 · 18
protectionprotection0 · 10 · 50 · 5
Total24 modules9 · 2382 · 56942 · 136

Completeness

About 1,000 declarations are named one by one with an explanation above, all others in the lists per module. Deliberately only summarised (fields in one line) is what a program does not call directly:

SurfaceMessage constants (the wire protocol between Surface and the display service) · layout offsets of DetectionRing · individual fields of Usage, SystemStatus, UpdateStatus, ZipEntry, ProcessorInfo, FLACInfo, VP9Picture, UIDesign (palette), Chart colours, MatroskaID constants · internals of Deflater (tables, Huffman) and HuffmanCode · the result-builder technique of the views (ViewBuilder, ViewList, ListAnd, ListOf1) · helper protocols ByteSource, ByteSink, ZipDestination, ZipInput · Presentation.presentationIcon/-Bytes.

Not in app-api-1.txt: SecureConnection (uses-tls, not declared public) and the table code generated per program (openDatabase, <Table>). The list still holds 136 declarations that belong to the System-API here (e.g. Screen, Programs.launch, System.installUpdate); the App-API without them has 942.