Quickstart

Get the library

Prism Platform ships as a prebuilt library + headers; download the archive for your platform from Releases. It links the system frameworks (Cocoa, Metal, QuartzCore) — add those when you build against it:

# prism-platform-<version>-macos.tar.gz → include/ + lib/
c++ -std=c++20 -Iprism-platform/include app.cpp -Lprism-platform/lib -lprism-platform \
    -framework Cocoa -framework Metal -framework QuartzCore

It has a headless test path (a GPU device with no window) so the RHI is covered by automated tests. (Builds from source with ./build.sh too — the Cocoa/Metal glue compiles alongside the portable C++.)

Open a window, draw a frame

The smallest useful program: create the system, open a window, get a Metal context, and run a pull-based loop that clears the drawable each frame.

#include "prism/platform/System.h"
using namespace prism::platform;

int main() {
    auto sys    = createSystem();
    auto window = sys->createWindow("Hello", 800, 600);
    auto ctx    = window->context();           // CAMetalLayer-backed

    bool running = true;
    while (running) {
        sys->processEvents(/*timeoutSeconds*/ -1);   // <0 block · 0 poll · >0 tick
        for (Event e; sys->nextEvent(e); ) {
            if (e.type == EventType::WindowClose) running = false;
            // … handle CursorMove / ButtonDown / KeyDown …
        }
        ctx->beginFrame();
        // … submit RHI draw work …
        ctx->endFrame();                         // present the drawable
    }
}

What's happening

createSystem / createWindow cross the OS boundary — a real Cocoa NSWindow with a Metal-backed view. See System, window & context.
processEvents + nextEvent are the pull-based loop: you ask the OS to pump (blocking, polling, or on a timeout), then drain the queue. The timeout is what lets an app sleep when idle and wake instantly on input — the model Prism UI's app loop is built on.
The Event you pull is already normalized and carries synthesized intent when fed through EventSynth.
beginFrame / endFrame acquire and present the drawable; the actual drawing is RHI submission in between.

That is the whole contract: pump events, handle them, render a frame, present. Everything else in this manual fills in the pieces — the OS interfaces, the event model, the RHI, and the buses.

‹ Overview System, window & context ›