SOFTrobots OS · App-API
Overview
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.
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: 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.
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.
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
| Level | Old | New |
|---|---|---|
| Right | apps.launch | programs.launch |
| Right | develop.build | programs.build |
| Right | device.camera | camera.use |
| Right | device.microphone | sound.microphone |
| Right | microphone.provide | sound.microphone.provide |
| Right | input.receive | ui.input |
| Right | input.provide | ui.input.provide |
| Right | display.own | ui.display |
| Right | ipc | channels.ipc |
| System-call module | net.* (net.receive, net.connect …) | network.* (network.receive, network.connect …) |
| System-call module | db.* (db.open, db.query …) | database.* (database.open, database.query …) |
| Swift | Apps | Programs |
| Swift | File | Files.Handle |
| Swift | WriteSet | Database.Write |
| Swift | Query | Database.Query |
| Swift | QueryPage | Database.Page |
| Swift | NetConnection | Network.Connection |
| Swift | NetPeer | Network.Peer |
| Swift | NetListener | Network.Listener |
| Swift | DatagramSocket | Network.Datagram |
| Swift | SoundOutput | Sound.Output |
| Swift | Microphone | Sound.Microphone |
| Swift | MicrophoneInfo | Sound.MicrophoneInfo |
| Swift | MicrophoneRing | Sound.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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Identity | ||
name = hello | Program name (required). | |
id = de.softrobots.hello | Identity as a reverse domain (required since 8 Nov); the data folder is /data/<id>. | |
version = 1.0.3 | Version (required); a program is only replaced by a higher one. | |
api = 1 | App-API version the program was built for; a system that offers less does not start it. | |
| Rights & documents | ||
capabilities = system.log, ui.surface | The program's rights (table below). | |
opens = txt, md | Document types the program opens (up to 16); required for double-click in Files and Files.Handle.openDocument. | |
takes = png, jpg | Document 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 new | Never show in the Dock, not even while running (the file dialog chooser). | |
start = demand | update | Do not start at boot, only on request (or at the first start of a new system copy). | |
helper = video | Serves only another program; not offered in lists. | |
title / category / icon | Display name, group (system, productivity, media, robot, tools) and SVG symbol 24 × 24. | |
| Memory | ||
memory = 512 | Heap limit in MiB (16 … 2048, default 256); the line also makes it a guarantee. | |
stack = 4096 | Stack size in KiB (64 … 8192). | |
| Real time & data | ||
realtime = 1000 200 stop | Real-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 = detections | A publication that others read without system calls (detection or arm ring). | |
subscribe = camera.detections | Up to two publications of other programs, mapped read-only at start. | |
| Network | ||
connects = api.anthropic.com | The only hosts the program may reach. | |
listens = 443, 80 | TCP ports to listen on (with network.incoming, up to 8). | |
Profilesuses-…Profiles: which libraries are built in
| Call | What it does | Shape 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-heap | Arrays, strings, classes; plus the sound library (WAV, FLAC, level, voice detection). | |
uses-ui | Surface, Canvas, Views, Keyboard, InputField, UITheme, Chart, ScrollBar. | |
uses-image | Picture, PNG, JPEG, GIF, WebP, BMP, TIFF, PDF writing/reading, Matroska (needs uses-heap). | |
uses-archive | ZIP reading/writing with WinZip AES-256, Deflate (needs uses-heap). | |
uses-tls | TLS 1.3 (SecureConnection), DNS over HTTPS, crypto, trust anchors. | |
uses-ai | A cloud AI through its API (type Claude; key in Settings › Privacy) – needs uses-tls and uses-heap. | |
uses-video / uses-opus | VP9 decoder / Opus decoder (needs uses-heap and uses-image). | |
uses-svg / uses-web / uses-sql | SVG renderer; browser code; SQL translator for databases (read-only). | |
uses-vision / uses-infer | AprilTag, colour blobs, motion / int8 inference (detectors). | |
uses-qr / uses-httpserver | QR code encoder / HTTP/1.1 server building blocks. | |
uses-reflex / uses-reflexrt | Reflex 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-uisystem · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
system.log | Write lines to the system log. | ≤ 5 µssystem.log0x0002_0003 |
system.status | Read 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
system.info | InfoRequest → SystemInfo | none | ≤ 5 µs0x0002_0001 |
system.now | NowRequest → Now | none | ≤ 1 µs0x0002_0002 |
system.log | LogLine → Done | system.log | ≤ 5 µs0x0002_0003 |
system.processorTimes | InfoRequest → ProcessorTimes | system.status | ≤ 5 µs0x0002_0006 |
system.random | RandomRequest → RandomBytes | none | ≤ 5 µs0x0002_0009 |
system.processor | ProcessorQuery → Processor | system.status | ≤ 5 µs0x0002_000B |
system.bootTimes | InfoRequest → BootTimes | system.status | ≤ 5 µs0x0002_000C |
system.realtime | RealtimeQuery → RealtimeStats | none | ≤ 2 µs0x0002_000D |
system.startWorker | WorkerStart → WorkerStarted | none | ≤ 1 ms0x0002_000E |
system.start event | Started | Reflex event | event0x0002_0007 |
system.stop event | Stopping | Reflex event | event0x0002_0008 |
System callsSystemCallprimitive system calls (enum SystemCall)
| Name | What it does | Right | Number |
|---|---|---|---|
exit | Exit the program | none | 0 |
yield | Give up processor time | none | 1 |
sleep | Sleep (ns) | none | 2 |
wait | Wait for window/service | none | 3 |
periodWait | Real time: next period | none | 4 |
memoryGrow | Grow the heap | none | 5 |
workerWake | Wake a worker thread | none | 6 |
workerExit | End a worker thread | none | 7 |
channelNotify | Channel: wake the other side | channels.ipc | 8 |
channelWait | Channel: wait | channels.ipc | 9 |
surfaceNotify | Window: wake the service | none | 11 |
shapeCall | Shape call: all modules below | none | 13 |
System callscoreModule 0x0001 · Shapes shared by all modules: problem, point, rotation, pose, pixel rectangle.
No calls – only shared shapes.
SwiftSystemInformation, log, time, flow, randomness
| Call | What it does | Shape 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 |
Examplefrom apps/actuators (shortened) | ||
System.processor(_ index: Int) -> ProcessorInfo? | Core, clock rate, temperature, name (system.status). | ≤ 5 µssystem.processor0x0002_000B |
ExamplePattern (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 |
Examplefrom 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) -> Bool | One line into the system log (at most 160 bytes; system.log). | ≤ 5 µssystem.log0x0002_0003 |
Examplefrom apps/reader (shortened) | ||
System.log(_ text: UnsafeRawBufferPointer, level: LogLevel) -> Bool | With level .debug/.info/.warning/.error (Activity › Log). | ≤ 5 µssystem.log0x0002_0003 |
| Time | ||
System.time: UInt64 / System.now() -> Now | ns since start / wall clock (ns since 1970), since start, time zone. | ≤ 1 µssystem.now0x0002_0002 |
Examplefrom apps/develop (shortened) | ||
System.wallClock: UInt64 | Milliseconds since 1970 (0 while unknown). | ≤ 1 µssystem.now0x0002_0002 |
| Flow | ||
System.sleep(nanoseconds: UInt64) | Sleep. | sleep (system call 2) |
Examplefrom apps/dialogcheck (shortened) | ||
System.yield() | Give up processor time. | yield (system call 1) |
System.exit(_ code: UInt64) -> Never | Exit the program. | exit (system call 0) |
Examplefrom sdk-apps/greeter (shortened) | ||
| Randomness | ||
System.random<let n: Int>(_ buffer: inout InlineArray<n, UInt8>) -> Bool | Random bytes from the kernel's generator (keys, nonces). | ≤ 5 µssystem.random0x0002_0009 |
ExamplePattern (short, not copied from a program) | ||
SwiftSystemReal time
| Call | What it does | Shape 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) |
Examplefrom apps/control (shortened) | ||
System.time: UInt64 | Nanoseconds 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 |
Examplefrom apps/control (shortened) | ||
SwiftRecorderMeasurement series without a system call
| Call | What it does | Shape call · time budget |
|---|---|---|
| Recording | ||
Recorder.attach() -> Recorder?static | The program's recording; nil without a record = line. | |
ExamplePattern (short, not copied from a program) | ||
Recorder.push(time: UInt64, _ data: Span<UInt8>) -> Bool | Append a record (time + up to recordSize − 8 bytes); false if the ring was full (counted). | |
Examplefrom apps/rtrecord (shortened) | ||
| State | ||
Recorder.dropped / .recordSize / .flight | Dropped records, record size, flight recorder (overwrites the oldest; saved only on an emergency stop or a crash). | |
SwiftTextLineA line of fixed size
| Call | What it does | Shape 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. | |
Examplefrom apps/ipcping (shortened) | ||
| Read | ||
TextLine.count / .subscript(index:) / .forEachByte(_:) / .capacity | Read. | |
SwiftWallClock · CivilTimeCalendar time
| Call | What it does | Shape call · time budget |
|---|---|---|
| Converting | ||
WallClock.civil(unixMilliseconds: Int64) -> CivilTime | ms since 1970 → year, month, day, hour, minute, second, millisecond. | |
Examplefrom apps/files (shortened) | ||
WallClock.berlinOffset(unixSeconds: Int64) -> Int64 | Offset 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". | |
Examplefrom 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 TextLineprograms · 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
programs.document | DocumentRequest → HandedDocument | none | ≤ 5 µs0x0006_0001 |
programs.settings | SettingsRequest → SettingsData | none | ≤ 200 µs0x0006_0002 |
programs.saveSettings | SettingsData → Done | none | ≤ 2 ms0x0006_0003 |
programs.ownSecret | SettingsRequest → SecretData | none | ≤ 2 ms0x0006_0006 |
programs.usage | ProgramListQuery → UsageList | system.status | ≤ 100 µs0x0006_000E |
SwiftProgramsThe handed-over document, usage
| Call | What it does | Shape 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 |
Examplefrom 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 |
Examplefrom apps/activity (shortened) | ||
Programs.Usage.buddyStage: Int | Buddy'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)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Loading | ||
Settings.load() -> Settings?static | The settings saved last (empty the first time); nil while DATA is locked, and for real-time programs. | ≤ 200 µsprograms.settings0x0006_0002 |
Examplefrom apps/apicheck (shortened) | ||
| Read | ||
Settings.value(_ key: StaticString) -> TextLine? | Value of a key. | |
Examplefrom apps/apicheck (shortened) | ||
Settings.number(_ key: StaticString) -> Int? | Value as an integer. | |
Examplefrom apps/apicheck (shortened) | ||
| Set | ||
Settings.set(_ key: StaticString, _ value: TextLine) -> Bool | Sets a text; false if 4 KiB would be exceeded. | |
Examplefrom apps/apicheck (shortened) | ||
Settings.set(_ key: StaticString, number: Int) -> Bool | Sets a number. | |
Examplefrom apps/apicheck (shortened) | ||
| Save | ||
Settings.save() -> Bool | Writes the settings. | ≤ 2 msprograms.saveSettings0x0006_0003 |
Examplefrom 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 Settingsfiles · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
files.own | Files in its own folder /data/<id>; nothing else exists. | ≤ 2 msfiles.open0x0003_0001 |
System callsfilesModule 0x0003 · The program's files, folders, volume and snapshots.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
files.open | OpenFile → FileOpened | files.own or files.system (+ files.mac for mac/, + system.log.read for crashes/, logs/) | ≤ 2 ms0x0003_0001 |
files.read | FileRead → FileData | none | ≤ 2 ms0x0003_0002 |
files.write | FileWrite → FileWritten | none | ≤ 2 ms0x0003_0003 |
files.close | FileRequest → Done | none | ≤ 5 ms0x0003_0004 |
files.list | ListFolder → FolderEntries | files.own or files.system (+ files.system for a snapshot) | ≤ 2 ms0x0003_0005 |
files.info | FileQuery → FileInfo | files.own or files.system (+ files.system for a snapshot) | ≤ 200 µs0x0003_0006 |
files.makeFolder | FileQuery → Done | files.own or files.system | ≤ 2 ms0x0003_0007 |
files.remove | FileQuery → Done | files.own or files.system | ≤ 2 ms0x0003_0008 |
files.rename | Rename → Done | files.own or files.system | ≤ 2 ms0x0003_0009 |
files.volume | VolumeQuery → VolumeInfo | system.status or files.system or files.own | ≤ 50 µs0x0003_000B |
SwiftFiles.HandleAn open file
| Call | What it does | Shape call · time budget |
|---|---|---|
| Open | ||
Files.Handle.open(_ path: Span<UInt8> | StaticString, mode: Mode) -> Result<Files.Handle, FileError>static | Opens a file; mode .read, .replace (create/truncate), .append, .update (read and write at any position). | ≤ 2 msfiles.open0x0003_0001 |
Examplefrom sdk-apps/notes (shortened) | ||
Files.Handle.openDocument(mode: Mode) -> Result<Files.Handle, FileError>static | Opens the document handed over by Files (see Programs.document). | ≤ 2 msfiles.open0x0003_0001 |
Examplefrom apps/reader (shortened) | ||
Files.Handle.open(_ grant: FileGrant, mode: Mode) -> Result<Files.Handle, FileError>static new | Opens 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 |
Examplefrom 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 |
Examplefrom apps/sound (shortened) | ||
| Write | ||
Files.Handle.write(_ data: Span<UInt8>) -> FileError? | Appends all bytes (in pieces of 16 KiB). | ≤ 2 msfiles.write0x0003_0003 |
Examplefrom 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 |
Examplefrom apps/sound (shortened) | ||
| Close | ||
Files.Handle.close() -> FileError? | Closes and commits the changes. | ≤ 5 msfiles.close0x0003_0004 |
Examplefrom sdk-apps/about (shortened) | ||
| Constants | ||
Files.Handle.chunk = 16384 / .handle: UInt64static | Bytes per system call / number of the file. | |
SwiftFilesFolders, info and changes by path
| Call | What it does | Shape call · time budget |
|---|---|---|
| Folders | ||
Files.entry(in path: Span<UInt8>, at index: Int, snapshot: UInt64? = nil) -> Result<Entry?, FileError>static | The index-th entry of a folder (optionally as in a snapshot); nil after the last one. Index 0 reads afresh. | ≤ 2 msfiles.list0x0003_0005 |
Examplefrom apps/testcamera (shortened) | ||
Files.makeDirectory(_ path: Span<UInt8>) -> FileError?static | Create a folder (empty path: the program's own folder). | ≤ 2 msfiles.makeFolder0x0003_0007 |
Examplefrom apps/sound (shortened) | ||
Files.Entry: isDirectory, size, modified, name, nameLength | A folder entry. | |
| Info | ||
Files.info(_ path: Span<UInt8> | StaticString, snapshot: UInt64? = nil) -> Result<(isDirectory: Bool, size: UInt64, modified: UInt64), FileError>static | Folder?, size (folder: total size), last change. | ≤ 200 µsfiles.info0x0003_0006 |
Examplefrom apps/shapecheck (shortened) | ||
Files.volume(system: Bool = false) -> InlineArray<5, UInt64>?static | DATA or system volume: block size, blocks, used, snapshots, generation. | ≤ 50 µsfiles.volume0x0003_000B |
Examplefrom apps/activity (shortened) | ||
| Changing | ||
Files.remove(_ path: Span<UInt8> | StaticString) -> FileError?static | Delete a file or an empty folder. | ≤ 2 msfiles.remove0x0003_0008 |
Examplefrom apps/shapecheck (shortened) | ||
Files.rename(_ path: Span<UInt8>, to newPath: Span<UInt8>, replacing: Bool) -> FileError?static | Move/rename; with replacing atomically over an existing file. | ≤ 2 msfiles.rename0x0003_0009 |
Examplefrom apps/sharecheck (shortened) | ||
Files.replace(_ path: Span<UInt8>, with data: Span<UInt8>) -> FileError?static | Replace the whole content atomically (first .new, then rename). | ≤ 2 msfiles.open + files.rename0x0003_0001 |
Examplefrom apps/settings (shortened) | ||
SwiftFileErrorErrors
| Call | What it does | Shape 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Document types | ||
FileType.of(_ name: Span<UInt8>) -> FileTypestatic | Type by extension. | |
FileType.label: StaticString / .isText / .isDatabase | Display name and kind. | |
FileType.accepts(_ prefix: Span<UInt8>, complete: Bool) -> Bool | Does the start of the content match the type? | |
FileType.extensionRange / .validUTF8 / .namesSVGElement / .equal / .maxExtensionstatic | Helpers 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 Filesdatabase · 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
database.open | OpenDatabase → DatabaseOpened | files.own or files.system (+ database.edit to write foreign ones) | ≤ 2 ms0x0004_0001 |
database.write | TableWrite → Written | files.own or files.system | ≤ 1 ms0x0004_0002 |
database.query | TableQuery → TablePage | files.own or files.system | ≤ 5 ms0x0004_0003 |
database.describe | DatabaseRequest → Description | files.own or files.system | ≤ 1 ms0x0004_0004 |
database.close | DatabaseRequest → Done | files.own or files.system | ≤ 50 µs0x0004_0005 |
database.readSeries | SeriesRead → SeriesRecords | files.own or files.system | ≤ 5 ms0x0004_0006 |
SwiftDatabaseopening & closing
| Call | What it does | Shape call · time budget |
|---|---|---|
| Opening & closing | ||
Database.open(_ path: StaticString, schema: Span<UInt8>) -> Result<Database, DatabaseError>static | The same with a compiled schema. | ≤ 2 msdatabase.open0x0004_0001 |
Database.open(_ path: Span<UInt8>) -> Result<Database, DatabaseError>static | Opens it as it is (tools such as Console and Database). | ≤ 2 msdatabase.open0x0004_0001 |
Examplefrom apps/database (shortened) | ||
Database.close() | Close. | ≤ 50 µsdatabase.close0x0004_0005 |
Examplefrom apps/dbcheck (shortened) | ||
SwiftDatabase · Database.Writewriting: a write set, all or nothing
| Call | What it does | Shape 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 |
Examplefrom apps/dbcheck (shortened) | ||
| Creating a set | ||
Database.Write.init() / .clear() / .isEmpty | Empty 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 / .insertedCount | ids of the inserted rows. | |
SwiftDatabase.Query · Database.Pagequerying: query, conditions, result page
| Call | What it does | Shape call · time budget |
|---|---|---|
| Queries | ||
Database.next(_ query: inout Database.Query<q>, into page: inout Database.Page<output, cursor>) -> Bool | Runs a query or fetches the next page; false when finished or on error (page.error). | ≤ 5 msdatabase.query0x0004_0003 |
Examplefrom apps/dbcheck (shortened) | ||
Database.next(query: Span<UInt8>, aggregate: Bool, grouped: Bool, into page: …) -> Bool | The same for a query from SQL.translate (uses-sql). | ≤ 5 msdatabase.query0x0004_0003 |
Database.firstValue<R>(query: Span<UInt8>, _ body: (Span<UInt8>?) -> R) -> R | First value of a translated query. | ≤ 5 msdatabase.query0x0004_0003 |
| Table | ||
Database.Query.init(_ table: StaticString) | Query on a table. | |
Examplefrom apps/dbcheck (shortened) | ||
| Filtering | ||
Database.Query.where(_ condition: Condition) / .whereAny(_:_:_:_:) | Condition (AND) / up to four OR conditions. | |
Examplefrom apps/dbcheck (shortened) | ||
| Sorting & limiting | ||
Database.Query.sorted(by field: Int, descending: Bool = false) / .sorted(by:via:descending:) | Sort (also across a reference, join). | |
Examplefrom apps/dbcheck (shortened) | ||
Database.Query.limit(_ rows: Int) / .select(_ field: Int) | At most n rows / only certain fields. | |
Examplefrom apps/dbcheck (shortened) | ||
| Aggregates | ||
Database.Query.count(groupedBy:) / .sum / .minimum / .maximum / .average (_ field: Int, groupedBy: Int? = nil) | Aggregates, optionally grouped. | |
Examplefrom 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). | |
Examplefrom apps/dbcheck (shortened) | ||
FloatField: == != < <= > >= Double | Conditions on floating-point fields. | |
TextField: == StaticString, equals, startsWith, contains, before, after | Conditions on text fields. | |
| Page | ||
Database.Page.init() / .reset() | Create a page / clear it for a new query. | |
Database.Page.rowCount, .error, .plan, .index | Rows, errors, chosen plan (index, range …). | |
| Reading values | ||
Database.Page.id(_ row: Int) / .number(_:_:signed:) / .float / .double / .text / .withBytes / .isNull / .value | Read the values of a row. | |
Database.Page.aggregate(_ row: Int) -> (rows: UInt64, value: Int64?) / .groupNumber / .withGroupBytes | Result of an aggregate or of a group. | |
Examplefrom apps/dbcheck (shortened) | ||
SwiftDatabase · Series · DatabaseErrordescribing, series, errors
| Call | What it does | Shape 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 …). | |
Examplefrom 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).
| Call | What it does | Shape 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 |
Examplefrom apps/dbcheck (shortened) | ||
| Per table | ||
dataSchema: InlineArray<n, UInt8> | The compiled schema of your tables; openDatabase passes it to Database.open(_:schema:). | |
<Table>.table: StaticString | The table name for Database.Query(<Table>.table). <Table> is the name from stored as … with a capital (joints → Joints). | |
<Table>.<field>: NumberField | FloatField | TextField | One 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) -> Row | A 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: Sendablenetwork · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
network.outgoing | Outgoing TCP connections and UDP; restricted by connects =. | ≤ 5 snetwork.connect0x0005_0004 |
System callsnetworkModule 0x0005 · Network: names, TCP, UDP, listening (get/post planned).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
network.get | Get → Response | network.outgoing · not served by the kernel yet | ≤ 2 s0x0005_0001 |
network.post | Post → Response | network.outgoing · not served by the kernel yet | ≤ 2 s0x0005_0002 |
network.resolve | Resolve → Resolved | network.outgoing | ≤ 6 s0x0005_0003 |
network.connect | Connect → Connected | network.outgoing | ≤ 5 s0x0005_0004 |
network.send | SocketSend → Sent | network.outgoing or network.incoming | ≤ 1 s0x0005_0005 |
network.receive | SocketReceive → SocketData | network.outgoing or network.incoming | ≤ 10 s0x0005_0006 |
network.close | SocketRequest → Done | network.outgoing or network.incoming | ≤ 50 µs0x0005_0007 |
network.openDatagram | DatagramOpen → DatagramOpened | network.outgoing | ≤ 5 s0x0005_0008 |
network.sendDatagram | DatagramSend → Done | network.outgoing | ≤ 1 s0x0005_0009 |
network.receiveDatagram | DatagramReceive → DatagramData | network.outgoing | ≤ 10 s0x0005_000A |
network.closeDatagram | DatagramRequest → Done | network.outgoing | ≤ 50 µs0x0005_000B |
System callsaskModule 0x0050 · Asking a cloud AI (Reflex scripts with the key from Settings).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
ask.claude | Question → Answer | none · not served by the kernel yet | no budget0x0050_0001 |
SwiftNetwork.ConnectionA TCP connection
| Call | What it does | Shape call · time budget |
|---|---|---|
| Resolving names | ||
Network.Connection.resolve(_ name: StaticString | Span<UInt8>) -> UInt32?static | IPv4 address of a host name (the network's DNS). | ≤ 6 snetwork.resolve0x0005_0003 |
ExamplePattern (short, not copied from a program) | ||
Network.Connection.resolveIPv6(_ name: Span<UInt8>) -> InlineArray<16, UInt8>?static | IPv6 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 |
ExamplePattern (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>) -> Bool | Send 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 |
ExamplePattern (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>? new | Receive 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 |
ExamplePattern (short, not copied from a program) | ||
SwiftNetwork.DatagramUDP to a server
| Call | What it does | Shape 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>) -> Bool | One 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)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Connecting | ||
SecureConnection.open(_ host: StaticString, port: UInt16 = 443, alpn: StaticString = "", timeout: UInt64 = 10_000_000_000) -> SecureConnection?static | Resolve (DNS over HTTPS), connect, handshake with certificate check. | ≤ 5 snetwork.connect0x0005_0004 |
Examplefrom apps/https (shortened) | ||
SecureConnection.open(host: Span<UInt8>, port: UInt16 = 443, timeout: UInt64 = 10_000_000_000) -> SecureConnection?static | For 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?static | To a known address. | ≤ 5 snetwork.connect0x0005_0004 |
| Sending & receiving | ||
SecureConnection.send(_ data: Span<UInt8>) -> Bool | Encrypt 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 |
Examplefrom apps/https (shortened) | ||
| Close | ||
SecureConnection.close() | Send close_notify and close. | ≤ 50 µsnetwork.close0x0005_0007 |
| Diagnostics | ||
SecureConnection.lastError / .handshakeTime / .handshakes / .lastSlotstatic | Why open failed, duration of the last handshake. | |
SwiftClaudeOne question to a cloud AI through its API (uses-ai)
| Call | What it does | Shape call · time budget |
|---|---|---|
| One question to a cloud AI | ||
Claude.ask(_ question: String, jpeg: [UInt8]? = nil, model: String = defaultModel, maxTokens: Int = 700) -> Answer | Asks (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 |
Examplefrom apps/ask (shortened) | ||
Claude.Answer: text, problem, milliseconds, incomplete | Answer 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 Networkui · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
ui.surface | Show windows (up to three). | ≤ 5 msdisplay.createSurface0x0011_0004 |
System callsdisplayModule 0x0011 · Screen and window memory (ui.surface, ui.display).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
display.createSurface | DisplayQuery → SurfaceMemory | ui.surface | ≤ 5 ms0x0011_0004 |
System callsscreenModule 0x0010 · Windows as a description of views (Reflex).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
screen.show | ScreenView → Done | none · not served by the kernel yet | ≤ 200 µs0x0010_0001 |
screen.ScreenView effect | | Reflex effect | effect0x0010_0002 |
screen.pressed event | Pressed | Reflex event | event0x0010_0003 |
screen.slid event | Slid | Reflex event | event0x0010_0004 |
screen.key event | KeyPress | Reflex event | event0x0010_0005 |
SwiftSurfaceThe program's windows
| Call | What it does | Shape call · time budget |
|---|---|---|
| Creating a window | ||
Surface.create(timeout: UInt64 = 10_000_000_000) -> Surface?static | Requests a window (up to three per program), waiting for the display service if necessary. | ≤ 5 msdisplay.createSurface0x0011_0004 |
Examplefrom apps/text (shortened) | ||
Surface.requestSize(width: Int, height: Int) | Desired content size (the user can change it). | |
Examplefrom apps/sound (shortened) | ||
Surface.setTitle(_ text: TextLine) | Name above the window. | |
Examplefrom apps/web (shortened) | ||
Surface.destroy() | Closes one of several windows (with only one: simply exit). | |
ExamplePattern (short, not copied from a program) | ||
| Fetching events | ||
Surface.nextEvent() -> SurfaceEvent? | Next message from the service, nil if none is waiting; .configure adjusts canvas. | |
Examplefrom sdk-apps/greeter (shortened) | ||
Surface.wait(timeout: UInt64) | Sleeps until the service sends something or timeout ns pass. | wait (system call 3) |
Examplefrom apps/reader (shortened) | ||
| Drawing & showing | ||
Surface.canvas: Canvas | The 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). | |
Examplefrom apps/reader (shortened) | ||
Surface.present(_ rect: Rect) -> Bool | Shows the changed rectangle; false if the ring stayed full (show again later). | |
Examplefrom 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…). | |
Examplefrom sdk-apps/greeter (shortened) | ||
Surface.raise() | Brings the window to the front (e.g. after a handed-over document). | |
Examplefrom apps/database (shortened) | ||
Surface.carry() | Lets the user drag a document; the answer arrives as .dropped. | |
ExamplePattern (short, not copied from a program) | ||
| Internals | ||
Surface.handle: UInt64 | Number of the window (for the system call surfaceNotify). | |
Surface.frameCounter / .frameShownstatic | Byte offsets in the ring page: frame counter (odd = being drawn) and last frame shown. | |
SwiftSurfaceEventWhat the service reports to the program
| Call | What it does | Shape call · time budget |
|---|---|---|
| Window | ||
SurfaceEvent.configure(width: Int, height: Int)case | Size changed / window ready: redraw. | |
SurfaceEvent.focus(Bool)case | Window gains/loses focus. | |
SurfaceEvent.closecase | User closed the window (⌘W): exit the program. | |
| Input | ||
SurfaceEvent.key(code: UInt8, down: Bool)case | Key (HID code); pass it through Keyboard.handle. | |
Examplefrom apps/reader (shortened) | ||
SurfaceEvent.pointer(x: Int, y: Int, buttons: UInt32)case | Pointer moved / button; bit 1 (value 2) = primary button pressed. | |
SurfaceEvent.scroll(x: Int, y: Int, tenths: Int)case | Mouse wheel in tenths of a notch, positive away from the user. | |
Examplefrom apps/reader (shortened) | ||
| Menu & dragging | ||
SurfaceEvent.menu(id: Int)case | A menu item (menu bar, context menu or shortcut) was chosen. | |
SurfaceEvent.dropped(program: InlineArray<32, UInt8>, length: Int, x: Int, y: Int)case | A carried document was dropped over a program. | |
SwiftSurfaceDescribing menus
| Call | What it does | Shape call · time budget |
|---|---|---|
| Building menus | ||
Surface.addMenu(_ index: Int, _ title: StaticString) | Menu number index (0 … 5 menu bar, SurfaceMessage.contextMenu for right-click). | |
Examplefrom 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. | |
Examplefrom apps/reader (shortened) | ||
Surface.addSeparator(_ index: Int) | Separator. | |
Examplefrom apps/reader (shortened) | ||
Surface.publishMenus() | Send the menus to the service (after all add… calls). | |
Examplefrom 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. | |
Examplefrom apps/files (shortened) | ||
Surface.setItem(_ id: Int, on: Bool) | Toggle item on/off. | |
ExamplePattern (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) new | The standard File menu: only the items the program supports, in system order with system shortcuts. | |
Examplefrom 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. | |
Examplefrom apps/reader (shortened) | ||
SwiftFileMenu · EditMenu · MenuIconStandard menus
| Call | What it does | Shape call · time budget |
|---|---|---|
| File menu | ||
FileMenu.new / .open / .save / .saveAs / .export / .showInFiles (911 … 916) new | ids of the standard File menu. | |
FileMenu.contains(_ id: Int) -> Bool new | Does the id belong to the File menu? | |
ExamplePattern (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) -> Bool | Does 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, copy | Symbols for menu items (drawn by the service). | |
SwiftSurfaceReporting progress
| Call | What it does | Shape call · time budget |
|---|---|---|
| Starting a task | ||
Surface.progress(_ title: TextLine, total: UInt64, unit: ProgressUnit = .none, cancellable: Bool = false) -> ProgressTask? new | Starts 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) |
ExamplePattern (short, not copied from a program) | ||
| Reporting progress | ||
Surface.progress(_ task: ProgressTask, done: UInt64) new | How far the task has got (throttled to 10/s). | |
Examplefrom apps/web (shortened) | ||
| Finishing | ||
Surface.progress(_ task: ProgressTask, finished end: ProgressEnd, done: UInt64? = nil) new | Task finished; stays green (or red) in the title for a moment. | |
Examplefrom apps/web (shortened) | ||
| Detecting cancellation | ||
Surface.isCancelled(_ task: ProgressTask) -> Bool new | Has the person pressed Cancel? Ask at any time, even in the middle of a loop. | |
Examplefrom apps/web (shortened) | ||
Surface.cancelRequestsstatic new | Byte offset of the cancel bits in the ring page (one bit per task). | |
SwiftProgressUnit · ProgressEnd · ProgressTaskProgress types
| Call | What it does | Shape call · time budget |
|---|---|---|
| Types | ||
enum ProgressUnit: UInt8 { none, bytes, items } new | What done and total count. | |
enum ProgressEnd: UInt8 { done, failed, cancelled } new | How a task ended. | |
struct ProgressTask { let id: Int } new | A running task of the window. | |
SurfaceMessage.progress new | Message kind 12 (program → service). | |
SwiftCanvasDrawing in pixels (logical points × scale)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Areas | ||
Canvas.fill(_ rect: Rect, _ color: RGB) | Fill a rectangle. | |
ExamplePattern (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. | |
Examplefrom 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) -> Int | Text in the bitmap font; returns the width. | |
Canvas.text(_ text: TextLine, x: Int, baseline: Int, face: FontFace, color: RGB) -> Int | Text in a system font (.body, .heading …) on a baseline. | |
Examplefrom apps/sound (shortened) | ||
Canvas.width(_ text: TextLine, face: FontFace) -> Intstatic | Width of a text in a font. | |
Examplefrom apps/sound (shortened) | ||
Canvas.textWidth(_ line: TextLine, scale: Int = 1) -> Intstatic | Width 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) -> RGB | Colour ↔ 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) -> Canvas | Sub-area as its own Canvas (origin shifted, clipped). | |
ExamplePattern (short, not copied from a program) | ||
Canvas.clip(_ rect: Rect) -> Rect | Clip a rectangle to the surface. | |
Canvas.scaled(_ scale: Int) -> Canvas | The 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. | |
Examplefrom sdk-apps/greeter (shortened) | ||
| Dimensions | ||
Canvas.width, .height, .scale, .stride, .pixelWidth, .pixelHeight, .base | Dimensions (logical and physical) and memory address. | |
SwiftViewsDescribing content instead of drawing it
| Call | What it does | Shape call · time budget |
|---|---|---|
| Arranging | ||
VStack(spacing: Int = 8, @ViewBuilder _ content: () -> Content) | Arrange vertically. | |
Examplefrom 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 / compressible | Custom views: measure and draw. | |
SwiftUIButtons, focus, keyboard navigation
| Call | What it does | Shape call · time budget |
|---|---|---|
| Buttons | ||
UI.init() | Empty state (keep it global). | |
UI.button(at x: Int, _ y: Int) -> Int | id of the button under the pointer (0: none). | |
Examplefrom sdk-apps/greeter (shortened) | ||
UI.pressed / .focused | Pressed 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). | |
Examplefrom 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) -> Int | Tab moves the focus, Enter/Space presses; returns the id of the pressed button. | |
ExamplePattern (short, not copied from a program) | ||
SwiftUITheme · ButtonLook · FileLookThe system's colours and button look
| Call | What it does | Shape call · time budget |
|---|---|---|
| Colours | ||
UITheme.background, .ground, .raised, .line, .text, .muted, .faint, .accent, .accentPressed, .onAccent, .good, .warning …static | System colours (dark or light, depending on the owner's setting). | |
UITheme.codeKeyword, .codeValue, .codeComment, .codeShapestatic | Colours for source code (Develop). | |
UITheme.use(light: Bool) / UITheme.isLight: Boolstatic | Choose / query the light or dark palette. | |
ExamplePattern (short, not copied from a program) | ||
UIDesign.dark / UIDesign.lightstatic | The 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) -> Int | Width of a button. | |
ButtonLook.drawSymbol / .roundedFill / .colours | Symbol, rounded area, colours of a state. | |
| File colours | ||
FileLook.colour(_ name: Span<UInt8>) -> RGB | Colour with which Files shows a file type. | |
SwiftKeyboardInput: key codes to characters
| Call | What it does | Shape call · time budget |
|---|---|---|
| Evaluating keys | ||
Keyboard.init() | State of the modifier keys. | |
Keyboard.handle(code: UInt8, down: Bool) -> Result | Evaluates a .key event: .character, .text, .special(…) or .none. | |
Examplefrom apps/reader (shortened) | ||
Keyboard.utf8(_ code: UInt32, into out: inout InlineArray<4, UInt8>) -> Intstatic | A character as UTF-8. | |
| Modifier keys | ||
Keyboard.shift, .control, .option, .command, .altGr | Pressed modifier keys. | |
SwiftInputFieldInput: a field with selection, undo and clipboard
| Call | What it does | Shape call · time budget |
|---|---|---|
| Creating | ||
InputField.init(maximumLength: Int = 512, secret: Bool = false) | Create a field; secret shows dots (passwords). | |
Examplefrom apps/reader (shortened) | ||
| Passing input on | ||
InputField.key(_ press: Keyboard.Result, _ keyboard: Keyboard) -> Change | Key while the field has the focus; result .none/.moved/.edited/.submit/.cancel. | |
Examplefrom apps/reader (shortened) | ||
InputField.command(_ id: Int) -> Change | Execute a command of the Edit menu (EditMenu ids). | |
Examplefrom apps/reader (shortened) | ||
InputField.pointer(_ x: Int, _ y: Int, down: Bool, pressed: Bool) -> Bool | Pointer event (click, drag); true if the field took it. | |
Examplefrom apps/database (shortened) | ||
| Drawing | ||
InputField.draw(_ canvas: Canvas, _ rect: Rect, focused: Bool) | Draw the field: frame, text, selection, cursor. | |
Examplefrom apps/reader (shortened) | ||
InputField.contains(_ x: Int, _ y: Int) -> Bool | Is 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: TextLine | Read the content (bytes, or the first 160 bytes as a line). | |
Examplefrom apps/reader (shortened) | ||
| Properties | ||
InputField.placeholder, .bordered, .secret, .face, .textColour, .cursorColour, .maximumLength | Appearance and behaviour. | |
InputField.isEmpty, .hasSelection / .cursor, .anchor, .count, .frame | State of the field. | |
SwiftRect · Size · RGBBasic types
| Call | What it does | Shape call · time budget |
|---|---|---|
| Basic types | ||
Rect(x: Int, y: Int, width: Int, height: Int) / .right / .bottom | A 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) -> RGB | A colour; mixing two colours. | |
Canvas.physicalPixel(_:_:) / .setPhysicalPixel(_:_:_:) / .shifts | Pixels in the physical grid (without scale) and the screen's colour format. | |
SwiftScrollBar · ListBar · Chart · DamageTrackerBuilding blocks
| Call | What it does | Shape 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). | |
Examplefrom 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) -> Plot | Chart frame with grid and labels; returns the drawing area. | |
Examplefrom 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. | |
Examplefrom apps/activity (shortened) | ||
Chart.cursor / .endPoint / .dot / .niceTop / .roundedPanel | Cursor, 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>: Viewsound · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
sound.play | Play sound: a ring that the kernel's mixer plays. | ≤ 1 mssound.open0x0030_0006 |
sound.microphone | Listen 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
sound.tone | Tone → Played | none · computed in the program by Reflex | ≤ 20 µs0x0030_0001 |
sound.play | Play → Played | none · not served by the kernel yet | ≤ 100 µs0x0030_0002 |
sound.stop | StopSound → Done | none · not served by the kernel yet | ≤ 20 µs0x0030_0003 |
sound.Tone effect | | Reflex effect | effect0x0030_0004 |
sound.Play effect | | Reflex effect | effect0x0030_0005 |
sound.open | SoundQuery → SoundRing | sound.play | ≤ 1 ms0x0030_0006 |
sound.close | SoundQuery → Done | none | ≤ 5 µs0x0030_0007 |
sound.status | SoundQuery → SoundStatus | none | ≤ 5 µs0x0030_0008 |
System callsmicrophoneModule 0x0031 · The robot's microphones (sound.microphone, sound.microphone.provide).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
microphone.list | MicrophoneListRequest → MicrophoneList | sound.microphone or sound.microphone.provide | ≤ 20 µs0x0031_0001 |
microphone.open | MicrophoneQuery → MicrophoneMap | sound.microphone | ≤ 1 ms0x0031_0002 |
microphone.close | MicrophoneQuery → Done | sound.microphone | ≤ 1 ms0x0031_0003 |
microphone.loud event | Loudness | Reflex event | event0x0031_0008 |
microphone.voice event | VoiceChange | Reflex event | event0x0031_0009 |
System callssignalModule 0x0040 · Measurements over time: spectrum, filter, statistics.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
signal.spectrum | SpectrumRequest → Spectrum | none · computed in the program by Reflex | ≤ 500 µs0x0040_0001 |
signal.filter | FilterRequest → Samples | none · computed in the program by Reflex | ≤ 200 µs0x0040_0002 |
signal.stats | Samples → Stats | none · computed in the program by Reflex | ≤ 50 µs0x0040_0003 |
signal.sine | SineRequest → Samples | none · computed in the program by Reflex | ≤ 2 ms0x0040_0004 |
SwiftSound.OutputPlaying
| Call | What it does | Shape call · time budget |
|---|---|---|
| Open | ||
Sound.Output.open() -> Sound.Output?static | The program's ring (the same one on every call); nil without sound.play or a sound device. | ≤ 1 mssound.open0x0030_0006 |
Examplefrom apps/sound (shortened) | ||
| Playing | ||
Sound.Output.write(_ frames: UnsafePointer<Int16>, count: Int) -> Int | Writes up to count frames (left, right); returns how many fitted. | |
Examplefrom apps/sound (shortened) | ||
Sound.Output.room / .queued / .withDevice: Int | Room now / written but not played / at the device, not yet heard. | |
Examplefrom apps/sound (shortened) | ||
Sound.Output.flush() | Discards what is waiting (stop). | |
Examplefrom apps/sound (shortened) | ||
| Volume | ||
Sound.Output.volume: Int | Own volume 0 … 100 (on top of the master volume). | |
Sound.Output.status: (volume: Int, device: Bool, playing: Bool)static | Master volume, device present, currently playing. | ≤ 5 µssound.status0x0030_0008 |
Examplefrom apps/settings (shortened) | ||
| Close | ||
Sound.Output.close() | The ring is no longer mixed. | ≤ 5 µssound.close0x0030_0007 |
| Constants | ||
Sound.Output.rate = 48_000 / .capacity: Intstatic | Sample rate / size of the ring. | |
SwiftSound.Microphone · Sound.MicrophoneRing · Sound.MicrophoneInfoListening
| Call | What it does | Shape 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 |
Examplefrom apps/sound (shortened) | ||
Sound.Microphone.open(_ id: Int? = nil) -> Sound.MicrophoneRing? | Start listening (nil: the first microphone); starts the microphone. | ≤ 1 msmicrophone.open0x0031_0002 |
Examplefrom apps/sound (shortened) | ||
Sound.Microphone.close(_ id: Int? = nil) -> Bool | Stop listening; the microphone stops when nobody listens any more. | ≤ 1 msmicrophone.close0x0031_0003 |
Examplefrom 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). | |
Examplefrom 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. | |
Examplefrom apps/sound (shortened) | ||
Sound.MicrophoneRing.peakDecibels / .rmsDecibels / .periods / .available / .rate / .channels / .ringFrames | Level 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 Soundcamera · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
camera.use | List cameras and map their image rings read-only. | ≤ 1 mscamera.ring0x0020_0006 |
System callscameraModule 0x0020 · The robot's cameras (camera.use, camera.provide).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
camera.list | CameraListRequest → CameraList | camera.use or camera.provide | ≤ 20 µs0x0020_0001 |
camera.frame | FrameRequest → CameraFrame | camera.use | ≤ 10 µs0x0020_0002 |
camera.toWorld | PixelPoint → WorldPoint | camera.use · computed in the program by Reflex | ≤ 2 µs0x0020_0003 |
camera.fromWorld | WorldPoint → PixelPoint | camera.use · computed in the program by Reflex | ≤ 2 µs0x0020_0004 |
camera.frame event | CameraFrame | Reflex event | event0x0020_0005 |
camera.ring | CameraRingQuery → CameraRingMap | camera.use | ≤ 1 ms0x0020_0006 |
camera.close | CameraRingQuery → Done | camera.use | ≤ 1 ms0x0020_0009 |
System callsvisionModule 0x0021 · What the cameras see: detections, colour masks, motion, markers.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
vision.detections | DetectionFilter → Detections | none · computed in the program by Reflex | ≤ 10 µs0x0021_0001 |
vision.mask | ColorMask → Mask | none · computed in the program by Reflex | ≤ 2 ms0x0021_0002 |
vision.motion | MotionRequest → Motion2D | none · computed in the program by Reflex | ≤ 1 ms0x0021_0003 |
vision.markers | MarkerRequest → Markers | none · computed in the program by Reflex | ≤ 3 ms0x0021_0004 |
vision.detections event | Detections | Reflex event | event0x0021_0005 |
SwiftCamera · CameraInfo · CameraRingChoosing, opening a camera, reading pictures
| Call | What it does | Shape 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 |
Examplefrom apps/video (shortened) | ||
Camera.open(_ id: Int) -> CameraRing? | Map the image ring; starts recording. | ≤ 1 mscamera.ring0x0020_0006 |
Examplefrom apps/server (shortened) | ||
Camera.close(_ id: Int) -> Bool | Unmap the ring; the Mac camera stops when nobody has it any more. | ≤ 1 mscamera.close0x0020_0009 |
Examplefrom 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. | |
Examplefrom apps/video (shortened) | ||
CameraRing.latest / .width / .height / .running | Newest complete image, dimensions, is the camera running? | |
SwiftDetectionReaderReading detections (subscriber)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Read | ||
DetectionReader.newest(after: UInt32 = 0, now: UInt64, maximumAge: UInt64) -> DetectionBatch? | Newest batch, unless it is older than maximumAge ns. | |
Examplefrom apps/rtvision (shortened) | ||
| Classes & model | ||
DetectionReader.classIndex(of name: StaticString) -> Int? / .classByte(_:_:) / .classCount | Find a class by name, read names. | |
ExamplePattern (short, not copied from a program) | ||
DetectionReader.latest / .modelGeneration / .modelName | Newest batch number; the generation rises when the model changes (look up classes again). | |
SwiftDetectionWriterPublishing detections (Video)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Classes & model | ||
DetectionWriter.setClassName(_ index: Int, length: Int, _ byteAt: (Int) -> UInt8) / .classesDone(count: Int) | Write class names once. | |
Examplefrom apps/video (shortened) | ||
DetectionWriter.setModel(length: Int, _ byteAt: (Int) -> UInt8) | Name of the active model (the generation rises). | |
| Write | ||
DetectionWriter.publish(_ batch: DetectionBatch) -> UInt32 | Write a batch as the next one; its number. | |
Examplefrom apps/video (shortened) | ||
DetectionWriter.readers: Int | How many programs are reading right now. | |
SwiftDetectionBatch · Sighting · DetectionRingA batch of detections
| Call | What it does | Shape 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. | |
Examplefrom apps/video (shortened) | ||
Sighting.centreX / .centreY | Centre of the box. | |
| Ring format | ||
DetectionRing.format(_:) / .magic / .version / .Offsets | Layout of the ring (one 16 KiB page). | |
For Reflex scriptsShape calls that Reflex scripts call directly by name
| Call | What it does | Shape call · time budget |
|---|---|---|
| For Reflex and the kernel | ||
vision.detections | Newest detections (ring from Video). | ≤ 10 µsvision.detections0x0021_0001 |
vision.mask / vision.motion / vision.markers | Colour mask with blobs, motion between two images, AprilTag markers. | ≤ 2 msvision.mask0x0021_0002 |
camera.frame / camera.toWorld / camera.fromWorld | Newest 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
robot.move | Move → Motion | none · computed in the program by Reflex | ≤ 20 µs0x0101_0001 |
robot.state | JointQuery → JointState | none · computed in the program by Reflex | ≤ 5 µs0x0101_0002 |
robot.Move effect | | Reflex effect | effect0x0101_0003 |
robot.moved event | Motion | Reflex event | event0x0101_0004 |
System callsarmModule 0x0102 · The arm as a whole: forward/inverse kinematics, joints, torque.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
arm.forward | Angles → ToolPose | none · computed in the program by Reflex | ≤ 2 µs0x0102_0001 |
arm.inverse | Reach → Angles | none · computed in the program by Reflex | ≤ 20 µs0x0102_0002 |
arm.joints | JointsRequest → JointList | none · computed in the program by Reflex | ≤ 10 µs0x0102_0003 |
arm.torque | TorqueCommand → Done | none · not served by the kernel yet | ≤ 1 µs0x0102_0004 |
arm.TorqueCommand effect | | Reflex effect | effect0x0102_0005 |
SwiftArmModelAn arm: joints, reach, tool
| Call | What it does | Shape call · time budget |
|---|---|---|
| Choosing an arm | ||
ArmModel.sr6 / .model(_ index: Int) -> ArmModelstatic | The 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:)static | Arm from the bytes of arm = (Settings › Robot); SR-6 if empty. | |
Examplefrom apps/server (shortened) | ||
| Kinematics | ||
ArmModel.forward(_ q: ArmAngles) -> ArmPose | Joint angles → points of the arm and tool pose. | ≤ 2 µsarm.forward0x0102_0001 |
ExamplePattern (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 |
ExamplePattern (short, not copied from a program) | ||
| Joints & data | ||
ArmModel.joint(_ index: Int) -> ArmJoint / .count / .joints | Joints (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
| Call | What it does | Shape call · time budget |
|---|---|---|
| ArmAngles · ArmPoint · ArmPose · ArmCamera | ||
ArmAngles() / .subscript(_ index: Int) -> Double | Joint angles in radians (up to 7). | |
Examplefrom 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, .pitch | Where 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)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Creating | ||
SimulatedMotors(_ model: ArmModel = .sr6) | Arm in rest position. | |
Examplefrom apps/actuators (shortened) | ||
| Controlling | ||
SimulatedMotors.set(joint: Int, target value: Int32, speed limit: Int32) | Target in 0.01° and speed. | |
Examplefrom apps/actuators (shortened) | ||
SimulatedMotors.step(milliseconds: Int) / .emergencyStop(_ on: Bool) | Simulate the movement / brake immediately. | |
| State | ||
SimulatedMotors.moving / .position / .velocity / .target / .speed / .stopped | State. | |
SwiftArmRing · ArmStateReading the arm state without a system call
| Call | What it does | Shape call · time budget |
|---|---|---|
| Read | ||
ArmRing.read<Ring: SharedWords>(_ ring: Ring) -> ArmState? | Newest complete state (subscription subscribe = actuators.arm). | |
Examplefrom apps/server (shortened) | ||
ArmState.positions, .moving, .stopped, .chosen, .id, .updates | Joint positions and flags. | |
| Writing (service) | ||
ArmRing.write(_:_:) | Written by the actuator service. | |
SwiftCANFrameCAN and CAN FD frames over a channel
| Call | What it does | Shape call · time budget |
|---|---|---|
| Building frames | ||
CANFrame(identifier: UInt32, fd: Bool = true) | Frames up to 64 data bytes. | |
Examplefrom 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) -> Bool | Send a frame over a channel. | |
Examplefrom apps/actuators (shortened) | ||
For Reflex scriptsShape calls that Reflex scripts call directly by name
| Call | What it does | Shape call · time budget |
|---|---|---|
| Moving | ||
robot.move | Start a movement (effect; the actuator service carries it out). | ≤ 20 µsrobot.move0x0101_0001 |
robot.state | Angle, speed, current, temperature of a joint. | ≤ 5 µsrobot.state0x0101_0002 |
arm.torque | Torque 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 SimulatedMotorssafety · 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
safety.state | SafetyQuery → SafetyState | none | ≤ 2 µs0x0100_0001 |
SwiftSystemReading the emergency stop
| Call | What it does | Shape call · time budget |
|---|---|---|
| Reading the state | ||
System.emergencyStopped: Bool | Is the emergency stop in effect right now? | ≤ 2 µssafety.state0x0100_0001 |
Examplefrom apps/arm (shortened) | ||
System.safetyGeneration: UInt64 | Changes with every stop and every release; odd = stopped. | ≤ 2 µssafety.state0x0100_0001 |
Examplefrom apps/actuators (shortened) | ||
System.safetyState: SafetyState | generation, 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Emergency stop | ||
safety.state / stop / release | Read, 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: SafetyStatechannels · 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
| Right | Meaning | Shape call · time budget |
|---|---|---|
channels.ipc | Open channels between programs. | ≤ 1 mschannels.open0x000A_0001 |
System callschannelsModule 0x000A · Message channels between programs (channels.ipc).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
channels.open | ChannelName → ChannelOpened | channels.ipc | ≤ 1 ms0x000A_0001 |
System callspeersModule 0x0110 · Robots nearby (reserved for later).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
peers.list | PeersRequest → PeerList | none · not served by the kernel yet | no budget0x0110_0001 |
peers.send | Envelope → Delivered | none · not served by the kernel yet | no budget0x0110_0002 |
peers.received event | Envelope | Reflex event | event0x0110_0003 |
SwiftChannelA channel
| Call | What it does | Shape call · time budget |
|---|---|---|
| Open | ||
Channel.init?(_ name: StaticString) | Open or join a channel; nil without channels.ipc. | ≤ 1 mschannels.open0x000A_0001 |
Examplefrom apps/ipcping (shortened) | ||
Channel.handle: UInt64 | Number of the channel. | |
| Sending | ||
Channel.send(_ message: Span<UInt8>) -> Bool | Queue a message (at most 256 bytes); false if the ring is full. | |
Examplefrom apps/ipcping (shortened) | ||
Channel.send(_ frame: CANFrame) -> Bool | Send a CAN frame. | |
Channel.notify() | Wake the other side. | channelNotify (system call 8) |
Examplefrom apps/arm (shortened) | ||
| Receiving | ||
Channel.receive(into out: inout InlineArray<256, UInt8>) -> Int? | Oldest received message or nil (does not wait). | |
Examplefrom apps/arm (shortened) | ||
Channel.receiveWaiting(into out: inout InlineArray<256, UInt8>) -> Int | Blocks until a message arrives (lost wake-ups are caught). | channelWait (system call 9) |
Examplefrom 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). | |
Examplefrom apps/benchmark (shortened) | ||
Channel.peerOnSameCPU: Bool | Whether 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) |
Examplefrom apps/develop (shortened) | ||
SwiftPublicationsPublishing and subscribing (publish =, subscribe =)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Publishing | ||
Publications.detections() -> DetectionWriter<SharedRing>?static | The program's own detection ring for writing; nil without publish =. | |
Examplefrom apps/video (shortened) | ||
| Subscribing | ||
Publications.subscription(_ index: Int = 0) -> DetectionReader<SharedRing>?static | The index-th subscription (0 or 1, order in the manifest). | |
Examplefrom apps/rtvision (shortened) | ||
| Raw rings | ||
Publications.ownRing() -> SharedRing? / Publications.subscriptionRing(_ index: Int) -> SharedRing?static | The same rings as raw words (for other formats, e.g. the arm ring). | |
SwiftSharedPage · SharedRingRaw shared words
| Call | What it does | Shape call · time budget |
|---|---|---|
| Raw shared words | ||
SharedPage.load / .store / .loadAcquire / .storeRelease | The channel page word by word (ordered accesses). | |
SharedRing.load32 / .store32 / .loadAcquire32 / .storeRelease32 / .barrier | A 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: SharedWordsclipboard · 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
clipboard.copy | ClipText → Done | ui.surface | ≤ 50 µs0x0012_0001 |
clipboard.paste | PasteRequest → ClipText | none | ≤ 50 µs0x0012_0002 |
clipboard.generation | PasteRequest → ClipGeneration | none | ≤ 2 µs0x0012_0004 |
SwiftClipboardCopying, pasting
| Call | What it does | Shape call · time budget |
|---|---|---|
| Copying | ||
Clipboard.copy(_ text: Span<UInt8>) -> Boolstatic | Text (UTF-8, at most 64 KiB) to the clipboard. | ≤ 50 µsclipboard.copy0x0012_0001 |
Examplefrom apps/console (shortened) | ||
Clipboard.generation: UInt64static | Counter that grows with every copy (the Mac bridge). | ≤ 2 µsclipboard.generation0x0012_0004 |
| Pasting | ||
Clipboard.paste(into buffer: inout MutableSpan<UInt8>) -> Intstatic | Reads into buffer; 0 if empty or not granted right now. | ≤ 50 µsclipboard.paste0x0012_0002 |
Examplefrom 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 Clipboarddialog · 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
dialog.ask new | DialogAsk → DialogTicket | ui.surface | ≤ 1 ms0x0013_0001 |
dialog.result new | DialogTicket → DialogResult | none | ≤ 20 µs0x0013_0002 |
SwiftDialogAsking and fetching the answer
| Call | What it does | Shape call · time budget |
|---|---|---|
| Open | ||
Dialog.open(types: StaticString = "", action: StaticString = "") -> Boolstatic new | Asks 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 |
Examplefrom apps/develop (shortened) | ||
| Save | ||
Dialog.save(name: TextLine, formats: StaticString, action: StaticString = "") -> Boolstatic new | Asks where to save; formats one line per format "Label=extension"; action = word on the button ("Export"). | ≤ 1 msdialog.ask0x0013_0001 |
Examplefrom apps/develop (shortened) | ||
| Fetching the answer | ||
Dialog.answer() -> Answer?static new | The answer as soon as there is one (cheap, ask on every loop pass): .chosen(FileGrant) or .cancelled; nil while open. | ≤ 20 µsdialog.result0x0013_0002 |
Examplefrom apps/develop (shortened) | ||
enum Dialog.Answer { case chosen(FileGrant), cancelled } new | Result of the question. | |
| State | ||
Dialog.isOpen: Boolstatic new | Is a dialog of this program on the screen right now? | |
ExamplePattern (short, not copied from a program) | ||
Dialog.lastWasSavestatic new | Was the last question a save (to tell answers apart)? | |
ExamplePattern (short, not copied from a program) | ||
SwiftFileGrantA grant for exactly one file
| Call | What it does | Shape call · time budget |
|---|---|---|
| Grant | ||
FileGrant.number: Int new | Number of the grant (1 … 16). | |
FileGrant.name: TextLine new | Chosen file name. | |
FileGrant.place: DialogPlace new | Where it is: own folder, Documents or Mac folder. | |
FileGrant.format new | When saving: index of the chosen format. | |
| Opening a file | ||
Files.Handle.open(_ grant: FileGrant, mode: Mode) -> Result<Files.Handle, FileError> new | Opens the granted file (read or write) – without a file right. | ≤ 2 msfiles.open0x0003_0001 |
Examplefrom 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 FileGrantupdate · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Program | ||
on start / on stop | Program starts / should stop (last chance to save). | eventsystem.start0x0002_0007 |
every 200 ms | Timer. | |
| 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
| Call | What it does | Shape 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.joints | Kinematics 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 / sine | Spectra 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
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
| Right | Module |
|---|---|
system.log.read | system |
system.power | system |
system.privacy | system |
system.time | system |
programs.build | programs |
programs.launch | programs |
files.mac | files |
files.system | files |
database.edit | database |
network.incoming | network |
ui.display | ui |
ui.input | ui |
ui.input.provide | ui |
sound.microphone.provide | sound |
sound.volume | sound |
camera.provide | camera |
device.can | robot |
device.usb | robot |
safety.actuator | safety |
safety.stop | safety |
files.dialog | dialog |
system.update | update |
system.protection | protection |
system · Information, time, log, real time, text
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
system.log.read | Read the system log (Console, Activity). | ≤ 20 µssystem.readLog0x0002_0005 |
system.time | Set the system clock (time service via NTS). | ≤ 5 µssystem.adjustClock0x0002_000A |
system.power | Switch off and restart. | no budgetsystem.power0x0002_0004 |
system.privacy | Set 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
system.power | PowerRequest → Done | system.power | no budget0x0002_0004 |
system.readLog | LogRead → LogText | system.log.read | ≤ 20 µs0x0002_0005 |
system.adjustClock | ClockAdjust → Now | system.time | ≤ 5 µs0x0002_000A |
System callsSystemCallprimitive system calls (enum SystemCall)
| Name | What it does | Right | Number |
|---|---|---|---|
deviceWait | Driver: wait for an interrupt | device.usb | 10 |
inputReceive | Display service: fetch input | ui.input | 12 |
SwiftSystemSetting the clock, power
| Call | What it does | Shape 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)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Reading the log | ||
Programs.logEnd / Programs.logLine(from:into:) | Follow the system log (system.log.read). | ≤ 20 µssystem.readLog0x0002_0005 |
ExamplePattern (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
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
programs.launch | Start, stop and list programs, hand over documents, read crashes. | ≤ 50 msprograms.launch0x0006_0007 |
programs.build | Build 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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
programs.setSecret | SecretWrite → Done | system.privacy | ≤ 5 ms0x0006_0004 |
programs.hasSecret | SecretQuery → SecretPresence | system.privacy | ≤ 2 ms0x0006_0005 |
programs.launch | ProgramName → Done | programs.launch | ≤ 50 ms0x0006_0007 |
programs.stop | ProgramName → Done | programs.launch | ≤ 50 µs0x0006_0008 |
programs.open | OpenDocument → Done | programs.launch (+ files.system for files not its own) | ≤ 50 ms0x0006_0009 |
programs.running | ProgramListQuery → RunningPrograms | programs.launch | ≤ 50 µs0x0006_000A |
programs.installed | ProgramListQuery → InstalledPrograms | programs.launch | ≤ 20 ms0x0006_000B |
programs.presentation | ProgramName → ProgramLook | programs.launch | ≤ 5 ms0x0006_000C |
programs.crashes | ProgramListQuery → CrashList | programs.launch | ≤ 20 µs0x0006_000D |
programs.signature | ProgramName → SignatureCheck | programs.launch | ≤ 50 ms0x0006_000F |
programs.build | BuildProgram → BuiltProgram | programs.build | ≤ 3 s0x0006_0010 |
programs.signShare | SharePackage → ShareSignature | programs.build | ≤ 20 ms0x0006_0011 |
programs.checkShare | SharePackage → ShareCheck | programs.build | ≤ 20 ms0x0006_0012 |
programs.uninstall | Uninstall → Done | files.system + programs.launch | ≤ 3 s0x0006_0013 |
programs.leftovers | ProgramListQuery → Leftovers | files.system | ≤ 50 ms0x0006_0014 |
programs.deleteLeftover | LeftoverDelete → Done | files.system + programs.launch | ≤ 3 s0x0006_0015 |
SwiftProgramsStarting, stopping, lists, crashes, signature, deleting
| Call | What it does | Shape call · time budget |
|---|---|---|
| Starting & stopping | ||
Programs.launch(_ name: Span<UInt8>) -> FileError? | Start a system program or app (programs.launch). | ≤ 50 msprograms.launch0x0006_0007 |
Examplefrom apps/apicheck (shortened) | ||
Programs.stop(_ name: Span<UInt8>) -> FileError? | Stop a running program (not services). | ≤ 50 µsprograms.stop0x0006_0008 |
Examplefrom 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 |
Examplefrom apps/files (shortened) | ||
| Lists | ||
Programs.running(at index: Int) -> Running? | The index-th running program (index 0 asks afresh). | ≤ 50 µsprograms.running0x0006_000A |
Examplefrom apps/console (shortened) | ||
Programs.installed(at index: Int) -> Running? | The index-th installed program. | ≤ 20 msprograms.installed0x0006_000B |
Examplefrom apps/display (shortened) | ||
Programs.Running: name, id, version, kind, realtime, period, missed, worstLatency, onDemand, helper, seesCamera, hearsMicrophone … | What an entry shows. | |
Programs.Running.hiddenFromDock new | Installed 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 |
ExamplePattern (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 Runningfiles · Files and folders
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
files.system | The whole DATA volume (/apps read-only), snapshots. | ≤ 50 µsfiles.snapshot0x0003_000C |
files.mac | In addition the Mac folder mac/… (SOFTrobotsVM only). |
System callsfilesModule 0x0003 · The program's files, folders, volume and snapshots.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
files.reveal | FileQuery → Done | programs.launch + files.own | no budget0x0003_000A |
files.snapshot | SnapshotQuery → SnapshotInfo | files.system | ≤ 50 µs0x0003_000C |
files.takeSnapshot | SnapshotQuery → SnapshotInfo | files.system | ≤ 50 ms0x0003_000D |
files.deleteSnapshot | SnapshotQuery → Done | files.system | ≤ 50 ms0x0003_000E |
files.restore | RestoreFile → Restored | files.system | ≤ 2 s0x0003_000F |
SwiftFilesShowing in Files (programs.launch + files.own)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Showing | ||
Files.reveal(_ path: Span<UInt8>) -> FileError?static | Shows a file from the program's own folder in Files (web downloads; needs programs.launch). | no budgetfiles.reveal0x0003_000A |
ExamplePattern (short, not copied from a program) | ||
SwiftFilesSnapshots, the time slider (files.system)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Snapshots | ||
Files.snapshot(after previous: UInt64) -> Snapshot?static | The snapshot after previous (0: the oldest). | ≤ 50 µsfiles.snapshot0x0003_000C |
Examplefrom apps/files (shortened) | ||
Files.takeSnapshot() -> Result<UInt64, FileError>static | Take a snapshot now (kept until deleted). | ≤ 50 msfiles.takeSnapshot0x0003_000D |
ExamplePattern (short, not copied from a program) | ||
Files.deleteSnapshot(_ id: UInt64) -> FileError?static | Delete a snapshot and free the space used only by it. | ≤ 50 msfiles.deleteSnapshot0x0003_000E |
Examplefrom apps/slidercheck (shortened) | ||
| Restoring | ||
Files.restore(_ path: Span<UInt8>, snapshot: UInt64) -> Result<(name: InlineArray<80, UInt8>, length: Int), FileError>static | Copy a file/folder back from a snapshot; nothing is overwritten ("name (HH.MM).ext"). | ≤ 2 sfiles.restore0x0003_000F |
Examplefrom 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 Snapshotdatabase · SOFTrobotsDB
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
database.edit | Write any database on DATA, not only its own (program Database). | ≤ 1 msdatabase.write0x0004_0002 |
network · Network, TLS, cloud AI
Accepting connections (only the program Server: network.incoming and listens = …).
What every program may use of it: App-API › network.
Rights
| Right | Meaning | Shape call · time budget |
|---|---|---|
network.incoming | Accept 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
network.listen | Listen → Listening | network.incoming | ≤ 50 µs0x0005_000C |
network.accept | Accept → Accepted | network.incoming | ≤ 10 s0x0005_000D |
network.listenerInfo | ListenerRequest → ListenerInfo | network.incoming | ≤ 20 µs0x0005_000E |
network.closeListener | ListenerRequest → Done | network.incoming | ≤ 50 µs0x0005_000F |
SwiftNetwork.Listener · Network.PeerIncoming (network.incoming)
| Call | What it does | Shape 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 |
Examplefrom 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 |
ExamplePattern (short, not copied from a program) | ||
Network.Peer: ipv4, ipv6, overIPv6, port | Who 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 Peerui · Windows, drawing, views, input, menus, progress
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
ui.display | Own the screen (display service only). | ≤ 5 msdisplay.open0x0011_0001 |
ui.input.provide / ui.input | Deliver input events (drivers) or receive them (display service). | ≤ 5 µsdisplay.submitInput0x0011_0006 |
System callsdisplayModule 0x0011 · Screen and window memory (ui.surface, ui.display).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
display.open | DisplayQuery → ScreenInfo | ui.display | ≤ 5 ms0x0011_0001 |
display.flush | PixelRect → Done | ui.display | ≤ 200 µs0x0011_0002 |
display.screenshot | DisplayQuery → Done | ui.display | ≤ 50 ms0x0011_0003 |
display.surface | SurfaceQuery → SurfaceState | ui.display | ≤ 20 µs0x0011_0005 |
display.submitInput | InputEvent → Done | ui.input.provide | ≤ 5 µs0x0011_0006 |
SwiftScreenDisplay service only (ui.display)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Screen | ||
Screen.open() -> (canvas: Canvas, needsFlush: Bool)?static | Takes over the screen. | ≤ 5 msdisplay.open0x0011_0001 |
Examplefrom apps/display (shortened) | ||
Screen.flush(_ rect: Rect)static | Shows a changed rectangle (virtio-gpu). | ≤ 200 µsdisplay.flush0x0011_0002 |
Screen.saveScreenshot() -> Boolstatic | Saves the screen as PNG in /data/screenshots. | ≤ 50 msdisplay.screenshot0x0011_0003 |
| Windows & input | ||
Screen.surface(_ index: Int) -> SurfaceInfostatic | Window number index as the service sees it. | ≤ 20 µsdisplay.surface0x0011_0005 |
Screen.input(into events: inout InlineArray<96, UInt64>) -> Intstatic | Fetch input events. | inputReceive (system call 12) |
Screen.wait(timeout: UInt64) / .notify(_ index: Int)static | Wait for programs / wake a window. | wait / surfaceNotify |
SwiftSystemDelivering input (ui.input.provide)
| Call | What it does | Shape 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 SurfaceInfosound · Playing and listening
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
sound.volume | Set the master volume. | ≤ 50 µssound.setVolume0x0030_0009 |
sound.microphone.provide | Offer a microphone (test microphone). | ≤ 1 msmicrophone.provide0x0031_0006 |
System callsmicrophoneModule 0x0031 · The robot's microphones (sound.microphone, sound.microphone.provide).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
microphone.listeners | ListenersRequest → Listeners | system.protection | ≤ 20 µs0x0031_0004 |
microphone.stopAll | StopListening → Done | system.protection | ≤ 1 ms0x0031_0005 |
microphone.provide | ProvideMicrophone → ProvidedMicrophone | sound.microphone.provide | ≤ 1 ms0x0031_0006 |
microphone.push | PushSamples → Done | sound.microphone.provide | ≤ 200 µs0x0031_0007 |
System callssoundModule 0x0030 · Sound through the system's mixer (sound.play; tone/play/stop planned).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
sound.setVolume | MasterVolume → Done | sound.volume | ≤ 50 µs0x0030_0009 |
SwiftSound.OutputMaster volume (sound.volume)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Volume | ||
Sound.Output.setMasterVolume(_ volume: Int) -> Boolstatic | Set the master volume (sound.volume). | ≤ 50 µssound.setVolume0x0030_0009 |
ExamplePattern (short, not copied from a program) | ||
SwiftSound.MicrophoneMIC indicator (system.protection), offering a microphone (sound.microphone.provide)
| Call | What it does | Shape 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() -> Bool | Stop all listeners (Stop on the MIC card; system.protection). | ≤ 1 msmicrophone.stopAll0x0031_0005 |
Examplefrom 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 |
Examplefrom apps/testmicrophone (shortened) | ||
Sound.Microphone.push(_ id: Int, samples: Int) -> Bool / .pushBuffer / .pushRoom | Feed 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) -> Boolcamera · Cameras, vision and detections
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
camera.provide | Offer a camera and push images into it (test camera). | ≤ 1 mscamera.provide0x0020_0007 |
System callscameraModule 0x0020 · The robot's cameras (camera.use, camera.provide).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
camera.provide | ProvideCamera → ProvidedCamera | camera.provide | ≤ 1 ms0x0020_0007 |
camera.push | PushFrame → Done | camera.provide | ≤ 500 µs0x0020_0008 |
SwiftCameraOffering a camera (camera.provide)
| Call | What it does | Shape 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 |
ExamplePattern (short, not copied from a program) | ||
Camera.push(_ id: Int, count: Int) -> Bool / .frameBuffer / .frameRoom | Feed the JPEG in frameBuffer (at most 448 KiB) as the next image. | ≤ 500 µscamera.push0x0020_0008 |
ExamplePattern (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: UnsafeMutableRawBufferPointerrobot · Arms, kinematics, actuator service, CAN
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
device.usb / device.can | Drivers: 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
devices.open | ControllerQuery → Controller | device.usb or device.can | ≤ 1 ms0x0009_0001 |
devices.allocate | DMARequest → DMAMemory | device.usb | ≤ 1 ms0x0009_0002 |
SwiftSystemDrivers: controllers, DMA, interrupts
| Call | What it does | Shape 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) -> Boolsafety · The emergency stop
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
safety.stop | Trigger and release the emergency stop. | ≤ 20 µssafety.stop0x0100_0002 |
safety.actuator | Drive 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
safety.stop | EmergencyStop → Done | safety.stop | ≤ 20 µs0x0100_0002 |
safety.release | SafetyQuery → Done | safety.stop | ≤ 20 µs0x0100_0003 |
SwiftSystemTriggering and releasing the emergency stop (safety.stop)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Triggering & releasing | ||
System.emergencyStop(reason: UInt64) -> Bool | Stop all actuators immediately (safety.stop). | ≤ 20 µssafety.stop0x0100_0002 |
Examplefrom apps/server (shortened) | ||
System.releaseEmergencyStop() -> Bool | Release the stop; actuators wait for the next command from their programs. | ≤ 20 µssafety.release0x0100_0003 |
Examplefrom 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() -> Boolclipboard · Copy and paste
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.
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
clipboard.grant | PasteGrant → Done | ui.display | no budget0x0012_0003 |
SwiftClipboardGranting (display service, ui.display)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Granting (service) | ||
Clipboard.grant(process slot: Int)static | Gives program slot one read access (display service only). | no budgetclipboard.grant0x0012_0003 |
Examplefrom 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
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
| Right | Meaning | Shape call · time budget |
|---|---|---|
files.dialog new | Show 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
dialog.questions new | QuestionsRequest → DialogQuestions | files.dialog | ≤ 50 µs0x0013_0003 |
dialog.answer new | DialogAnswer → Done | files.dialog | ≤ 5 ms0x0013_0004 |
System callsdialogOnly the system program chooser (files.dialog)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Only with files.dialog | ||
dialog.questions new | Open questions of all programs (the chooser shows them). | ≤ 50 µsdialog.questions0x0013_0003 |
dialog.answer new | The 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 = noupdate · System updates
Installing signed system updates into the system copy that is not running, choosing the start screen and start sound (Settings, Update: system.update).
Rights
| Right | Meaning | Shape call · time budget |
|---|---|---|
system.update | Install signed system updates into the resting system copy. | ≤ 60 supdate.install0x0008_0002 |
System callsupdateModule 0x0008 · System copies A/B and updates (system.update).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
update.status | UpdateQuery → UpdateState | system.update | ≤ 5 µs0x0008_0001 |
update.install | UpdatePackage → Done | system.update | ≤ 60 s0x0008_0002 |
update.textStart | StartLook → Done | system.update | ≤ 50 ms0x0008_0003 |
update.startSound | StartSound → Done | system.update | ≤ 50 ms0x0008_0004 |
SwiftSystemUpdates (system.update)
| Call | What it does | Shape 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>) -> UpdateResult | Install a signed package into the resting copy; starts after the restart. | ≤ 60 supdate.install0x0008_0002 |
System.setTextStart(_ text: Bool) -> Bool / System.setStartSound(_ on: Bool) -> Bool | Text 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 UpdateStatusprotection · Device protection
Device protection: password for DATA, unlocking, screen lock, the owner's choices (display service only: system.protection).
Rights
| Right | Meaning | Shape call · time budget |
|---|---|---|
system.protection | Device 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).
| Call | Request → answer | Right | Time budget · ID |
|---|---|---|---|
protection.status | ProtectionQuery → ProtectionStatus | system.protection | ≤ 5 µs0x0007_0001 |
protection.setUp | Password → RecoveryKey | system.protection | ≤ 3 s0x0007_0002 |
protection.unlock | Password → Done | system.protection | ≤ 3 s0x0007_0003 |
protection.verify | Password → Done | system.protection | ≤ 3 s0x0007_0004 |
protection.choices | ProtectionQuery → OwnerChoices | system.protection | ≤ 2 ms0x0007_0005 |
SwiftSystemDisplay service only (system.protection)
| Call | What it does | Shape 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
| Library | What for | File | Declarations |
|---|---|---|---|
web | Web: HTML, CSS, HTTP | uses-web | 279 |
image | Pictures and PDF | uses-image | 173 |
svg | SVG | uses-svg | 105 |
sound | Sound: tools and formats | uses-heap | 118 |
archive | Archives: ZIP, Deflate | uses-archive | 79 |
sql | SQL | uses-sql | 52 |
maths | Maths | every profile | 25 |
video | Video: VP9 | uses-video | 25 |
qr | QR codes | uses-qr | 10 |
opus | Opus | uses-opus | 8 |
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: Stringimage · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Image | ||
Picture(width: Int = 0, height: Int = 0, pixels: [UInt8] = [], scale: Int = 1) | An image of RGBA pixels. | |
Examplefrom apps/apicheck (shortened) | ||
Picture.maxFile / .maxPixelsstatic | Limits against inputs that are too large. | |
PictureError.text | Short sentence for messages. | |
| Decoding | ||
Picture.decode(_ file: [UInt8]) -> Result<Picture, PictureError>static | PNG, JPEG, GIF, WebP, BMP or TIFF by signature. | |
Examplefrom apps/video (shortened) | ||
SwiftPNG · JPEG · GIF · WebP · BMP · TIFFFormats
| Call | What it does | Shape call · time budget |
|---|---|---|
| PNG & JPEG | ||
PNG.encode(_ picture: Picture) -> [UInt8]? / .decode / .hasSignature / .size(_:) | PNG lossless (RGB if opaque, otherwise RGBA); size without decoding. | |
Examplefrom apps/apicheck (shortened) | ||
JPEG.encode(_ picture: Picture, quality: Int = 85) -> [UInt8]? / .decode / .hasSignature | JPEG (baseline, 4:2:0, quality 1 … 100). | |
Examplefrom apps/apicheck (shortened) | ||
| GIF & WebP | ||
GIF.decode / .hasSignature / .maxFrames | GIF, first image. | |
GIFAnimation.parse(_ file: [UInt8]) -> Result<GIFAnimation, PictureError> | Animated GIF: advance(), show(_:), delay(_:), frameCount, pixels. | |
ExamplePattern (short, not copied from a program) | ||
WebP.decode / .hasSignature | WebP (lossy and lossless). | |
WebPAnimation.parse(_ file: [UInt8]) -> Result<WebPAnimation, PictureError> | Animated WebP, like GIFAnimation. | |
| BMP & TIFF | ||
BMP.encode / .decode / .hasSignature, TIFF.encode / .decode / .hasSignature | Read 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Document | ||
PDFDocument(width: Double = PDFDocument.a4.width, height: Double = PDFDocument.a4.height) | New document (dimensions in points). | |
Examplefrom apps/image (shortened) | ||
PDFDocument.newPage() / .data() -> [UInt8] | New page / the finished PDF. | |
ExamplePattern (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. | |
Examplefrom apps/image (shortened) | ||
PDFDocument.picture(_ picture: Picture, x:y:width:height:, jpeg: [UInt8]? = nil) -> Bool | Insert 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 / .a4static | Text width, A4 dimensions. | |
SwiftPDFReaderReading PDF
| Call | What it does | Shape call · time budget |
|---|---|---|
| Open | ||
PDFReader.init(_ bytes: [UInt8], password: [UInt8] = []) throws(PDFReadError) | Opens a PDF (encrypted ones too). | |
Examplefrom apps/reader (shortened) | ||
| Pages & text | ||
PDFReader.pageCount / .page(_ index: Int) -> PDFPage? | Pages (width, height, rotate, content, resources). | |
Examplefrom 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. | |
Examplefrom apps/reader (shortened) | ||
| Raw data & permissions | ||
PDFReader.object / .resolve / .streamBytes / .decode / .decodeBytes / .trailer | Raw objects for your own evaluation (PDFObject, PDFDictionary). | |
PDFReader.isEncrypted / .openedAsOwner / .permissions / .textString(_:) / .maximumFile / .maximumStream | Encryption, permissions, limits. | |
SwiftMatroskaWriterWriting MKV (MJPEG, sound, detections)
| Call | What it does | Shape 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 / .lastTime | Finish (index). | |
SwiftMatroskaIndex · MatroskaTrack · MatroskaFrameReading MKV/WebM
| Call | What it does | Shape 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). | |
Examplefrom apps/video (shortened) | ||
MatroskaIndex.tracks / .frames / .duration / .docType / .seek(_ milliseconds: Int, track: Int) -> Int | Tracks, frames (track, time, offset, length, key), seeking. | |
| Tracks | ||
MatroskaTrack.isCodec(_ name: StaticString) -> Bool / .codec / .codecPrivate / .sampleRate / .width | Codec of a track ("V_VP9", "A_OPUS"). | |
Examplefrom 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 WebPAnimationsvg · 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: Sendablesound · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Level | ||
LevelMeter.measure(_ samples: Span<Int16>) -> SoundLevel | RMS and peak in dBFS. | |
Examplefrom apps/sound (shortened) | ||
LevelMeter.periods(_ samples: Span<Int16>, channels: Int = 1) -> [SoundLevel] | Level per 10 ms period. | |
LevelMeter.decibels / .amplitude / .linear / .floor / .fullScale | Conversions 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). | |
Examplefrom apps/sound (shortened) | ||
NoiseGate(threshold: Double = -50, holdMilliseconds: 200, fadeMilliseconds: 5, channels: 1) | Noise gate; process(&samples), isOpen. | |
Examplefrom 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. | |
Examplefrom apps/sound (shortened) | ||
VoiceDetector.voiceParts(_ samples: [Int16], channels: Int = 1, gapMilliseconds: Int = 300, shortestMilliseconds: Int = 200) -> [Range<Int>] | Speech passages of a recording. | |
Examplefrom apps/sound (shortened) | ||
| Recording & editing | ||
PreRecordBuffer(seconds: Int = 5, channels: Int = 1): append / .drain / .clear / .frames | The last seconds before recording starts. | |
Examplefrom apps/sound (shortened) | ||
SoundEdit.trim / .trimSilenceEnds / .splitAtPauses / .normalize / .voiceBounds / .overview | Trim, shorten silence, split at pauses, normalise, waveform. | |
Examplefrom 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| WAV | ||
WAV(_ file: Span<UInt8>) | Reads a WAV header: rate, channels, bits, float, frames, dataStart, milliseconds. | |
Examplefrom 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. | |
Examplefrom 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). | |
Examplefrom apps/miccheck (shortened) | ||
FLACDecoder.nextBlock() throws(FLACError) -> [Int32] / .seek(toSample:) / .info: FLACInfo | Next 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: Equatablearchive · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Reading contents | ||
ZipArchive.entries<S: ByteSource>(_ source: inout S) -> Result<[ZipEntry], ZipError> | Read the table of contents. | |
ExamplePattern (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
| Call | What it does | Shape 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Deflate & checksums | ||
Deflater.compress(_:_:) / .finish(_:) / .reset() | Compress raw DEFLATE. | |
StreamInflater.next(_ source: inout S) -> Result<Range<Int>?, InflateError> / .reset() / .total | Inflate raw DEFLATE piece by piece. | |
CRC32.add(_ bytes: Span<UInt8>) / .checksum / .reset() | CRC-32. | |
ExamplePattern (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 ZipWritersql · 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 SQLStatementmaths · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Maths | ||
Maths.sin, .cos, .tan, .asin, .acos, .atan, .atan2, .sinCos | Trigonometry. | |
Examplefrom apps/fpcheck (shortened) | ||
Maths.sqrt, .hypot, .pow, .exp, .log, .log2, .log10 | Roots, powers, logarithms. | |
Maths.floor, .ceil, .round, .trunc, .fmod, .radians, .degrees | Rounding and converting. | |
Maths.pi, .e | Constants. | |
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 Mathsvideo · 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)
| Call | What it does | Shape call · time budget |
|---|---|---|
| Video (VP9) | ||
VP9Decoder() / .decode(_ packet: [UInt8]) throws(VP9Error) -> VP9Picture? | Decode a VP9 packet. | |
Examplefrom apps/video (shortened) | ||
VP9Picture.rgba() -> [UInt8] / .y, u, v, yStride, uvStride, width, height | Image 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 VP9Pictureqr · 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
| Call | What it does | Shape call · time budget |
|---|---|---|
| Encoding | ||
QRCode.encode(_ bytes: Span<UInt8>, correction: QRCorrection = .medium, mask: Int? = nil) -> QRCode?static | QR code in byte mode (versions 1 … 10, levels L/M/Q/H). | |
Examplefrom apps/server (shortened) | ||
QRCode.capacity(version: Int, correction: QRCorrection) -> Intstatic | How many bytes fit. | |
| Read | ||
QRCode.isDark(x: Int, y: Int) -> Bool / .size / .version / .correction / .mask | Read 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: Sendableopus · 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)
| Call | What it does | Shape 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 OpusDecoderAssignment & 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
| Module | System-call modules | Rights | System calls | Swift declarations |
|---|---|---|---|---|
system | core, system | 2 · 4 | 9 · 3 | 97 · 4 |
programs | programs | 0 · 2 | 5 · 16 | 38 · 53 |
files | files | 1 · 2 | 10 · 5 | 44 · 10 |
database | database | 0 · 1 | 6 · 0 | 134 · 0 |
network | ask, network | 1 · 1 | 12 · 4 | 27 · 11 |
ui | display, screen | 1 · 3 | 2 · 5 | 354 · 17 |
sound | microphone, signal, sound | 2 · 2 | 13 · 5 | 38 · 7 |
camera | camera, vision | 1 · 1 | 10 · 2 | 67 · 4 |
robot | arm, devices, robot | 0 · 2 | 6 · 2 | 97 · 4 |
safety | safety | 0 · 2 | 1 · 2 | 4 · 2 |
channels | channels, peers | 1 · 0 | 3 · 0 | 26 · 0 |
clipboard | clipboard | 0 · 0 | 3 · 1 | 4 · 1 |
dialog | dialog | 0 · 1 | 2 · 2 | 12 · 0 |
update | update | 0 · 1 | 0 · 4 | 0 · 18 |
protection | protection | 0 · 1 | 0 · 5 | 0 · 5 |
| Total | 24 modules | 9 · 23 | 82 · 56 | 942 · 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.
Nothing found.