Runtime API reference

Access the runtime API with #include <playbit/sys/sys.h>

This reference is also available in markdown format and as structured JSON data

Types

`PBSysThreadFlags`

typedef enum PB_ENUM_TYPE(u64) {
    PBSysThread_NOGUI = 1u << 0, // disable GUI (only has an effect on the main thread)
    PBSysThread_AUDIO = 1u << 1, // thread produces audio output
} PBSysThreadFlags;

`PBSysThreadSignals`

typedef enum PB_ENUM_TYPE(uint32_t) {
    PBSysThreadSignal_RUNNING = 1u << 0,
    PBSysThreadSignal_TERMINATED = 1u << 1,
    PBSysThreadSignal_WRITABLE = 1u << 2, // room for writing at least one message
    PBSysThreadSignal_READABLE = 1u << 3, // at least one message can be read
} PBSysThreadSignals;

`PBSysObjectType`

typedef enum PBSysObjectType PB_ENUM_TYPE(uint16_t){
    PBSysObject_None = 0, // invalid
    PBSysObject_Audio = 16,
    PBSysObject_Bundle = 18,
    PBSysObject_Channel = 7,
    PBSysObject_Clock = 1,
    PBSysObject_File = 12,
    PBSysObject_FileList = 14,
    PBSysObject_Gui = 8,
    PBSysObject_Net = 9,
    PBSysObject_NetSession = 10,
    PBSysObject_Stream = 2,
    PBSysObject_Textplan = 3,
    PBSysObject_Texture = 15,
    PBSysObject_Thread = 4,
    PBSysObject_Window = 6,
} PBSysObjectType;

`PBSysRights`

typedef u32 PBSysRights;

PBSysRights are associated with handles and convey privileges to perform actions on either the associated handle or the object associated with the handle.

`PBSysRightsBits`

enum PBSysRightsBits PB_ENUM_TYPE(PBSysRights){
    PBSysRight_NONE = 0u,

    PBSysRight_TRANSFER = 1u << 0,
    PBSysRight_DUPLICATE = 1u << 1,
    PBSysRight_READ = 1u << 4,
    PBSysRight_WRITE = 1u << 5,
    PBSysRight_MANAGE_PROCESS = 1u << 6, // start & terminate process
    PBSysRight_MANAGE_THREAD = 1u << 7,  // start & terminate threads
    PBSysRight_NETWORK = 1u << 8,        // can connect to networks [DEPRECATED]
    PBSysRight_OBSERVE = 1u << 9,        // can observe signals
    PBSysRight_SIGNAL = 1u << 10,        // can manage user signals
    PBSysRight_GET_PROPERTY = 1u << 11,  // can read object properties
    PBSysRight_SET_PROPERTY = 1u << 12,  // can change object properties

    PBSysRight_SAME_RIGHTS = 1u << 31,
};

`PBSysAudioBuffer`

typedef i64 PBSysAudioBuffer;

Handle to the sound mixer buffer and sound handles (u32 id, gen)

`PBSysAudioSound`

typedef i64 PBSysAudioSound;

`PBSysChannelFlags`

enum PBSysChannelFlags PB_ENUM_TYPE(uint32_t){
    PBSysChannel_DUPLEX = 1u << 0,           // created handles support both reading and writing
    PBSysChannel_MULTIPLE_WRITERS = 1u << 1, // support multiple concurrent threads writing
    PBSysChannel_MULTIPLE_READERS = 1u << 2, // support multiple concurrent threads reading
};

`PBSysClockInfo`

typedef struct PBSysClockInfo {
    char timeZoneName[63]; // IANA time zone identifier (e.g. "")
    u8   timeZoneNameLen;  // length of timeZoneName
} PBSysClockInfo;

`PBSysPointerKind`

typedef enum PBSysPointerKind PB_ENUM_TYPE(u8){
    PBSysPointerKind_MOUSE = 1,
    PBSysPointerKind_TOUCH = 2,
    PBSysPointerKind_TRACKPAD = 3, // used mainly for scroll/gesture sources
    PBSysPointerKind_PEN = 4,
} PBSysPointerKind;

`PBSysPointerFlags`

typedef enum PBSysPointerFlags PB_ENUM_TYPE(u16){
    PBSysPointerFlag_PRIMARY = 1u << 0,    // primary pointer for this device
    PBSysPointerFlag_IN_CONTACT = 1u << 1, // touch/pen in contact
    PBSysPointerFlag_ERASER = 1u << 2,     // pen eraser side/end
    PBSysPointerFlag_INVERTED = 1u << 3,   // if a platform reports pen inversion
    PBSysPointerFlag_COALESCED = 1u << 4,  // if event is a coalesced/aggregated update
    PBSysPointerFlag_PREDICTED = 1u << 5,  // if predicted (some systems provide)
} PBSysPointerFlags;

`PBSysScrollPhase`

typedef enum PBSysScrollPhase PB_ENUM_TYPE(u8){
    PBSysScrollPhase_CHANGED = 0, // default if platform doesn't provide phases
    PBSysScrollPhase_BEGAN = 1,
    PBSysScrollPhase_ENDED = 2,
    PBSysScrollPhase_MOMENTUM = 3, // inertia phase (macOS trackpad, iOS)
} PBSysScrollPhase;

`PBSysScrollFlags`

typedef enum PBSysScrollFlags PB_ENUM_TYPE(u16){
    PBSysScrollFlag_PRECISE = 1u << 0,    // high-resolution scrolling (trackpad)
    PBSysScrollFlag_INVERTED = 1u << 1,   // "natural" direction applied or not
    PBSysScrollFlag_UNIT_LINES = 1u << 2, // deltas are in lines (vs pixels/dp)
    PBSysScrollFlag_UNIT_PAGES = 1u << 3, // deltas are pages
} PBSysScrollFlags;

`PBSysGesturePhase`

typedef enum PBSysGesturePhase PB_ENUM_TYPE(u8){
    PBSysGesturePhase_CHANGED = 0, // default if platform doesn't provide phases
    PBSysGesturePhase_BEGAN = 1,
    PBSysGesturePhase_ENDED = 2,
} PBSysGesturePhase;

`PBSysKeyboardFlags`

typedef enum PBSysKeyboardFlags PB_ENUM_TYPE(u16){
    PBSysKeyboardFlag_REPEAT = 1u << 0, // i.e. key is being held down
} PBSysKeyboardFlags;

`PBSysKeyboardModifiers`

typedef enum PBSysKeyboardModifiers PB_ENUM_TYPE(u16){
    PBSysKeyboardModifier_SHIFT = 1u << 0,     // shift
    PBSysKeyboardModifier_CTRL = 1u << 1,      // control
    PBSysKeyboardModifier_ALT = 1u << 2,       // aka "option" on mac
    PBSysKeyboardModifier_META = 1u << 3,      // aka "command", "windows key", "super"
    PBSysKeyboardModifier_CAPS_LOCK = 1u << 4, // caps lock
    PBSysKeyboardModifier_FN = 1u << 5,        // "function"
} PBSysKeyboardModifiers;

`PBSysKeyboardKey`

typedef enum PBSysKeyboardKey PB_ENUM_TYPE(u16){
    PBSysKeyboardKey_None = 0x0000,

    // ASCII / Unicode printable (match codepoint)
    PBSysKeyboardKey_Space = 0x0020,
    PBSysKeyboardKey_Quote = 0x0027,
    PBSysKeyboardKey_Comma = 0x002C,
    PBSysKeyboardKey_Minus = 0x002D,
    PBSysKeyboardKey_Period = 0x002E,
    PBSysKeyboardKey_Slash = 0x002F,

    PBSysKeyboardKey_0 = 0x0030,
    PBSysKeyboardKey_1 = 0x0031,
    PBSysKeyboardKey_2 = 0x0032,
    PBSysKeyboardKey_3 = 0x0033,
    PBSysKeyboardKey_4 = 0x0034,
    PBSysKeyboardKey_5 = 0x0035,
    PBSysKeyboardKey_6 = 0x0036,
    PBSysKeyboardKey_7 = 0x0037,
    PBSysKeyboardKey_8 = 0x0038,
    PBSysKeyboardKey_9 = 0x0039,

    PBSysKeyboardKey_Semicolon = 0x003B,
    PBSysKeyboardKey_Equal = 0x003D,

    PBSysKeyboardKey_A = 0x0041,
    PBSysKeyboardKey_B = 0x0042,
    PBSysKeyboardKey_C = 0x0043,
    PBSysKeyboardKey_D = 0x0044,
    PBSysKeyboardKey_E = 0x0045,
    PBSysKeyboardKey_F = 0x0046,
    PBSysKeyboardKey_G = 0x0047,
    PBSysKeyboardKey_H = 0x0048,
    PBSysKeyboardKey_I = 0x0049,
    PBSysKeyboardKey_J = 0x004A,
    PBSysKeyboardKey_K = 0x004B,
    PBSysKeyboardKey_L = 0x004C,
    PBSysKeyboardKey_M = 0x004D,
    PBSysKeyboardKey_N = 0x004E,
    PBSysKeyboardKey_O = 0x004F,
    PBSysKeyboardKey_P = 0x0050,
    PBSysKeyboardKey_Q = 0x0051,
    PBSysKeyboardKey_R = 0x0052,
    PBSysKeyboardKey_S = 0x0053,
    PBSysKeyboardKey_T = 0x0054,
    PBSysKeyboardKey_U = 0x0055,
    PBSysKeyboardKey_V = 0x0056,
    PBSysKeyboardKey_W = 0x0057,
    PBSysKeyboardKey_X = 0x0058,
    PBSysKeyboardKey_Y = 0x0059,
    PBSysKeyboardKey_Z = 0x005A,

    PBSysKeyboardKey_LeftBracket = 0x005B,
    PBSysKeyboardKey_Backslash = 0x005C,
    PBSysKeyboardKey_RightBracket = 0x005D,
    PBSysKeyboardKey_Grave = 0x0060,

    // Unicode symbols
    PBSysKeyboardKey_Escape = 0x238B,    // ESC
    PBSysKeyboardKey_Enter = 0x23CE,     // RETURN SYMBOL
    PBSysKeyboardKey_Tab = 0x21E5,       // TAB
    PBSysKeyboardKey_Backspace = 0x232B, // ERASE TO THE LEFT
    PBSysKeyboardKey_Insert = 0x2380,    // INSERT
    PBSysKeyboardKey_Delete = 0x2326,    // ERASE TO THE RIGHT
    PBSysKeyboardKey_Left = 0x2190,
    PBSysKeyboardKey_Right = 0x2192,
    PBSysKeyboardKey_Down = 0x2193,
    PBSysKeyboardKey_Up = 0x2191,
    PBSysKeyboardKey_PageUp = 0x21DE,
    PBSysKeyboardKey_PageDown = 0x21DF,
    PBSysKeyboardKey_Home = 0x21F1,
    PBSysKeyboardKey_End = 0x21F2,

    PBSysKeyboardKey_CapsLock = 0x21EA,
    PBSysKeyboardKey_LeftShift = 0x21E7,
    PBSysKeyboardKey_LeftCtrl = 0x2303,
    PBSysKeyboardKey_LeftAlt = 0x2325,
    PBSysKeyboardKey_LeftSuper = 0x2318,

    PBSysKeyboardKey_MediaNext = 0x23ED,
    PBSysKeyboardKey_MediaPrev = 0x23EE,
    PBSysKeyboardKey_MediaPlay = 0x23F5,
    PBSysKeyboardKey_MediaStop = 0x23F9,

    // Private use area (0xE000-0xEFFF)
    PBSysKeyboardKey_World1 = 0xE000,
    PBSysKeyboardKey_World2 = 0xE001,

    PBSysKeyboardKey_ScrollLock = 0xE010,
    PBSysKeyboardKey_NumLock = 0xE011,
    PBSysKeyboardKey_PrintScreen = 0xE012,
    PBSysKeyboardKey_Pause = 0xE013,

    PBSysKeyboardKey_F1 = 0xE100,
    PBSysKeyboardKey_F2 = 0xE101,
    PBSysKeyboardKey_F3 = 0xE102,
    PBSysKeyboardKey_F4 = 0xE103,
    PBSysKeyboardKey_F5 = 0xE104,
    PBSysKeyboardKey_F6 = 0xE105,
    PBSysKeyboardKey_F7 = 0xE106,
    PBSysKeyboardKey_F8 = 0xE107,
    PBSysKeyboardKey_F9 = 0xE108,
    PBSysKeyboardKey_F10 = 0xE109,
    PBSysKeyboardKey_F11 = 0xE10A,
    PBSysKeyboardKey_F12 = 0xE10B,
    PBSysKeyboardKey_F13 = 0xE10C,
    PBSysKeyboardKey_F14 = 0xE10D,
    PBSysKeyboardKey_F15 = 0xE10E,
    PBSysKeyboardKey_F16 = 0xE10F,
    PBSysKeyboardKey_F17 = 0xE110,
    PBSysKeyboardKey_F18 = 0xE111,
    PBSysKeyboardKey_F19 = 0xE112,
    PBSysKeyboardKey_F20 = 0xE113,
    PBSysKeyboardKey_F21 = 0xE114,
    PBSysKeyboardKey_F22 = 0xE115,
    PBSysKeyboardKey_F23 = 0xE116,
    PBSysKeyboardKey_F24 = 0xE117,

    PBSysKeyboardKey_Numpad0 = 0xE200,
    PBSysKeyboardKey_Numpad1 = 0xE201,
    PBSysKeyboardKey_Numpad2 = 0xE202,
    PBSysKeyboardKey_Numpad3 = 0xE203,
    PBSysKeyboardKey_Numpad4 = 0xE204,
    PBSysKeyboardKey_Numpad5 = 0xE205,
    PBSysKeyboardKey_Numpad6 = 0xE206,
    PBSysKeyboardKey_Numpad7 = 0xE207,
    PBSysKeyboardKey_Numpad8 = 0xE208,
    PBSysKeyboardKey_Numpad9 = 0xE209,
    PBSysKeyboardKey_NumpadDot = 0xE20A,
    PBSysKeyboardKey_NumpadDivide = 0xE20B,
    PBSysKeyboardKey_NumpadMultiply = 0xE20C,
    PBSysKeyboardKey_NumpadSubtract = 0xE20D,
    PBSysKeyboardKey_NumpadAdd = 0xE20E,
    PBSysKeyboardKey_NumpadEnter = 0xE20F,
    PBSysKeyboardKey_NumpadEquals = 0xE210,
    PBSysKeyboardKey_NumpadClear = 0xE211,

    PBSysKeyboardKey_RightShift = 0xE300,
    PBSysKeyboardKey_RightCtrl = 0xE301,
    PBSysKeyboardKey_RightAlt = 0xE302,
    PBSysKeyboardKey_RightSuper = 0xE303,

    PBSysKeyboardKey_Menu = 0xE310,

    PBSysKeyboardKey_VolumeUp = 0xE320,
    PBSysKeyboardKey_VolumeDown = 0xE321,
    PBSysKeyboardKey_Mute = 0xE322,

    PBSysKeyboardKey_COUNT
} PBSysKeyboardKey;

`PBSysMouseButton`

typedef enum PBSysMouseButton PB_ENUM_TYPE(u16){
    PBSysMouseButton_Left = 0,
    PBSysMouseButton_Right = 1,
    PBSysMouseButton_Middle = 2,
    PBSysMouseButton_X1 = 3,
    PBSysMouseButton_X2 = 4,
    // NOTE: unnamed buttons here
    PBSysMouseButton_COUNT = 16,
} PBSysMouseButton;

`PBSysEventType`

typedef enum PBSysEventType PB_ENUM_TYPE(u16){
    PBSysEventType_INVALID = 0,

    // signal
    PBSysEventType_SIGNAL,

    // pointer
    PBSysEventType_POINTER_ENTER, // pointer started being "in" the surface/window
    PBSysEventType_POINTER_LEAVE, // pointer left the surface/window
    PBSysEventType_POINTER_DOWN,
    PBSysEventType_POINTER_UP,
    PBSysEventType_POINTER_MOVE,
    PBSysEventType_POINTER_CANCEL, // system canceled a sequence (e.g. OS interruption)

    // scroll
    PBSysEventType_SCROLL,

    // gesture
    PBSysEventType_GESTURE_PAN,    // translation (typically dp)
    PBSysEventType_GESTURE_PINCH,  // scale factor (relative)
    PBSysEventType_GESTURE_ROTATE, // radians (relative)

    // keyboard
    PBSysEventType_KEY_DOWN,
    PBSysEventType_KEY_UP,
} PBSysEventType;

`PBSysEvent`

typedef struct PBSysEvent {
    u16           size;     // size of the event
    u16           type;     // PBSysEventType
    PBSysObjectId objectId; // originating object ID, e.g. window (0 means "unknown")
} PB_ATTR_ALIGNED(8) PBSysEvent;

`PBSysSignalEvent`

typedef struct PBSysSignalEvent {
    PBSysEvent      event;
    PBSysHandle     handle;
    PBSysSignals    signals;
    PBSysSignals    pulseSignals;
    PBSysObjectType objectType;
    u16             _reserved;
} PBSysSignalEvent;

`PBSysInputEvent`

typedef struct PBSysInputEvent {
    PBSysEvent event;
    PBSysTime  timestamp; // time the event occurred
    u32        clientId;  // originating client ID (0 for "local")
    u32        deviceId;  // stable per HID
    u16        modifiers; // PBSysKeyboardModifiers
    u16        _reserved;
} PBSysInputEvent;

`PBSysPointerEvent`

typedef struct PBSysPointerEvent {
    PBSysInputEvent  inputEvent;
    u32              pointerId;  // logical; stable per active contact/stream
    u16              flags;      // PBSysPointerFlags
    u16              buttons;    // current button bitmask (mouse/pen)
    u8               button;     // "changed" button for DOWN/UP/CLICK (0 if n/a)
    PBSysPointerKind kind;       //
    u8               clickCount; // for CLICK (and optionally DOWN/UP if platform provides)
    u8               _reserved;  //
    f32              x, y;       // position in window coords (dp)
    f32              dx, dy;     // delta since last event for this pointerId (dp). 0 if unknown.
} PBSysPointerEvent;

`PBSysPenPointerEvent`

typedef struct PBSysPenPointerEvent {
    PBSysPointerEvent pointerEvent;
    f32               pressure;           // [0..1]
    f32               tangentialPressure; // [0..1] barrel pressure (pen)
    f32               tiltX, tiltY;       // [-1, +1] 0 = perpendicular
    f32               twist;              // degrees [0, 359]; barrel rotation (pen)
    f32               width, height;      // contact ellipse in dp (touch/pen)
    f32               altitudeAngle;      // [0, π/2] radians (0 = parallel, π/2 = perpendicular)
    f32               azimuthAngle;       // [0, π/2] radians, direction in the screen plane
} PBSysPenPointerEvent;

`PBSysScrollEvent`

typedef struct PBSysScrollEvent {
    PBSysInputEvent  inputEvent;
    PBSysPointerKind kind;
    PBSysScrollPhase phase;
    u16              flags;  // PBSysScrollFlags
    f32              x, y;   // focus point in window coords if known, else 0
    f32              dx, dy; // scroll delta (dp or lines/pages depending on flags)
    f32              wheelZ; // optional for 3D wheels; else 0
} PBSysScrollEvent;

`PBSysGestureEvent`

typedef struct PBSysGestureEvent {
    PBSysInputEvent   inputEvent;
    PBSysGesturePhase phase;
    u8                _reserved;
    u16               flags;    // currenty unused
    f32               x, y;     // gesture center in window coords (dp) if known
    f32               dx, dy;   // pan delta (dp) for PAN; else 0
    f32               scale;    // relative scale delta for PINCH (1.0 means no change; e.g. 1.02)
    f32               rotation; // relative rotation delta in radians for ROTATE
} PBSysGestureEvent;

`PBSysKeyboardEvent`

typedef struct PBSysKeyboardEvent {
    PBSysInputEvent  inputEvent;
    PBSysKeyboardKey keyCode;    // logical code for the key, i.e. "the A key"
    PBSysKeyboardKey deviceCode; // physical key, i.e. "3rd key on 4th row"
    u32              text[8];    // Unicode representation
    u8               textLen;    // number of codepoints in text array
    u8               _reserved;  //
    u16              flags;      // PBSysKeyboardFlags
} PBSysKeyboardEvent;

`PBSysFileId`

typedef struct PBSysFileId {
    u8 data[32];
} PBSysFileId;

`PBSysFileMode`

typedef u16 PBSysFileMode;

`PBSysFileModes`

enum PBSysFileModes PB_ENUM_TYPE(PBSysFileMode){
    PBSysFileMode_USER_R = 0400,    // user (file owner) has read permission
    PBSysFileMode_USER_W = 0200,    // user has write permission
    PBSysFileMode_USER_X = 0100,    // user has execute permission
    PBSysFileMode_USER_RW = 0600,   // user has read and write permissions
    PBSysFileMode_USER_RWX = 0700,  // user has read, write, and execute permissions
    PBSysFileMode_GROUP_R = 0040,   // group has read permission
    PBSysFileMode_GROUP_W = 0020,   // group has write permission
    PBSysFileMode_GROUP_X = 0010,   // group has execute permission
    PBSysFileMode_GROUP_RW = 0060,  // group has read and write execute permissions
    PBSysFileMode_GROUP_RWX = 0070, // group has read, write, and execute permissions
    PBSysFileMode_OTHER_R = 0004,   // others have read permission
    PBSysFileMode_OTHER_W = 0002,   // others have write permission
    PBSysFileMode_OTHER_X = 0001,   // others have execute permission
    PBSysFileMode_OTHER_RW = 0006,  // others have read and write execute permissions
    PBSysFileMode_OTHER_RWX = 0007, // others have read, write, and execute permissions
};

`PBSysFileOpenFlags`

typedef enum PBSysFileOpenFlags PB_ENUM_TYPE(u64){
    PBSysFileOpenFlag_READ = 1 << 0,                               // give file PBSysRight_READ
    PBSysFileOpenFlag_WRITE = 1 << 1,                              // give file PBSysRight_WRITE
    PBSysFileOpenFlag_APPEND = (1 << 2) | PBSysFileOpenFlag_WRITE, // open in append mode
    PBSysFileOpenFlag_CREATE = 1 << 7, // create file if it does not exist

    // PBSysFileOpenFlag_MODE_MASK masks mode bits in flags, for use with CREATE flag
    PBSysFileOpenFlag_MODE_MASK = 0xffff << 8,
    PBSysFileOpenFlag_MODE_USER_R = PBSysFileMode_USER_R << 8,
    PBSysFileOpenFlag_MODE_USER_W = PBSysFileMode_USER_W << 8,
    PBSysFileOpenFlag_MODE_USER_X = PBSysFileMode_USER_X << 8,
    PBSysFileOpenFlag_MODE_USER_RWX = PBSysFileMode_USER_RWX << 8,
    PBSysFileOpenFlag_MODE_GROUP_R = PBSysFileMode_GROUP_R << 8,
    PBSysFileOpenFlag_MODE_GROUP_W = PBSysFileMode_GROUP_W << 8,
    PBSysFileOpenFlag_MODE_GROUP_X = PBSysFileMode_GROUP_X << 8,
    PBSysFileOpenFlag_MODE_GROUP_RWX = PBSysFileMode_GROUP_RWX << 8,
    PBSysFileOpenFlag_MODE_OTHER_R = PBSysFileMode_OTHER_R << 8,
    PBSysFileOpenFlag_MODE_OTHER_W = PBSysFileMode_OTHER_W << 8,
    PBSysFileOpenFlag_MODE_OTHER_X = PBSysFileMode_OTHER_X << 8,
    PBSysFileOpenFlag_MODE_OTHER_RWX = PBSysFileMode_OTHER_RWX << 8,
} PBSysFileOpenFlags;

`PBSysFileReadFlags`

typedef enum PBSysFileReadFlags PB_ENUM_TYPE(u64){
    PBSysFileReadFlag_SYNC = 1 << 0, // blocking read
} PBSysFileReadFlags;

`PBSysFileWriteFlags`

typedef enum PBSysFileWriteFlags PB_ENUM_TYPE(u64){
    PBSysFileWriteFlag_SYNC = 1 << 0, // blocking write
} PBSysFileWriteFlags;

`PBSysFileListEntryType`

typedef enum PBSysFileListEntryType PB_ENUM_TYPE(u8){
    PBSysFileListEntryType_UNKNOWN = 0,   // underlying filesyestem does not report types
    PBSysFileListEntryType_DIR = 1,       // directory
    PBSysFileListEntryType_FILE = 2,      // regular file
    PBSysFileListEntryType_LINK = 3,      // symbolic link
    PBSysFileListEntryType_SOCKET = 4,    // local socket
    PBSysFileListEntryType_SPECIAL = 100, // none of the above (e.g. fifo, char dev. etc.)
} PBSysFileListEntryType;

`PBSysFileListEntry`

typedef struct PBSysFileListEntry {
    u64                    id; // file's unique ID within the file system (inode ID or similar)
    PBSysFileListEntryType type;
} PBSysFileListEntry;

`PBSysCursorStyle`

typedef enum PBSysCursorStyle PB_ENUM_TYPE(uint16_t){
    PBSysCursorStyle_NONE = 0, //
    PBSysCursorStyle_IMAGE,    //
    PBSysCursorStyle_POINTER,  //
    PBSysCursorStyle_HAND,     //
    PBSysCursorStyle_TEXT,     //
    PBSysCursorStyle_HIDDEN,   //
    PBSysCursorStyle_LOADING,  //
    PBSysCursorStyle_BLOCKED,  //
    PBSysCursorStyle_PAN,      //
    PBSysCursorStyle_SIZEH,    //
    PBSysCursorStyle_SIZEV,    //
    PBSysCursorStyle_SIZENESW, //
    PBSysCursorStyle_SIZENWSE, //
    PBSysCursorStyle_SCROLLNS, //
    PBSysCursorStyle_SCROLLN,  //
    PBSysCursorStyle_SCROLLS,  //
} PBSysCursorStyle;

`PBSysHandleName`

typedef u16 PBSysHandleName;

PBSysHandleName names special well-defined objects

`PBSysHandleInfo`

typedef struct PBSysHandleInfo {
    PBSysHandle     handle;
    PBSysRights     rights;
    PBSysHandleName name;
    PBSysObjectType objectType;
    PBSysObjectId   objectId;
} PBSysHandleInfo;

`PBSysNetSessionConfig`

typedef struct PBSysNetSessionConfig {
    u64                flags;         // unused, set to 0
    u64                authId;        // local auth state key. Use 0 for default.
    const u8* nullable serverAddr;    // "host:port" as UTF-8 text. Leave empty for default.
    u32                serverAddrLen; // number of bytes at serverAddr
} PBSysNetSessionConfig;

`PBSysNetConnectConfig`

typedef struct PBSysNetConnectConfig {
    u64 flags; // unused, set to 0
} PBSysNetConnectConfig;

`PBSysStreamWriteFlags`

typedef enum PBSysStreamWriteFlags PB_ENUM_TYPE(u32){
    PBSysStreamWrite_SYNC = 1, // complete write immediately or fail with PBSysErr_AGAIN
} PBSysStreamWriteFlags;

`PBSysStreamStats`

typedef struct PBSysStreamStats {
    PBSysTime timestamp; // time at which the statistics were gathered

    /*
    bytesReceived indicates the number of bytes received by this stream, up to the first missing byte. The number does not include any network or transport overhead, and can only increase over time.
    */
    u64 bytesReceived;

    /*
    bytesRead indicates the number of bytes the application has read from this stream. This number can only increase, and is always less than or equal to bytesReceived.
    */
    u64 bytesRead;
} PBSysStreamStats;

`PBSysTextplanSelectionRect`

typedef struct PBSysTextplanSelectionRect {
    i32 x, y;
    i32 width, height;
} PBSysTextplanSelectionRect;

`PBSysTextplanSelection`

typedef struct PBSysTextplanSelection {
    u64 anchor;
    u64 caret;
    u64 lastDown;
} PBSysTextplanSelection;

`PBSysWindowSignals`

typedef enum PB_ENUM_TYPE(u32) {
    // PBSysWindowSignal_RESIZE is pulsed when the window's size and/or pixel density changes
    PBSysWindowSignal_RESIZE = 1u << 0, // pulse

    // PBSysWindowSignal_MOVE is pulsed when the window's position on screen change
    PBSysWindowSignal_MOVE = 1u << 1, // pulse

    /*
    PBSysWindowSignal_FRAME_SYNC is pulsed when the window's display finised presenting a frame. You can retrieve the estimated presentation time of the next frame via frameTime from PBSysWindowInfoGet.
    */
    PBSysWindowSignal_FRAME_SYNC = 1u << 2,

    /*
    PBSysWindowSignal_REPAINT is pulsed when the window's content need to be drawn again. This signal is only used on hosts which does not retain the window contents when a window is not displayed on screen.
    */
    PBSysWindowSignal_REPAINT = 1u << 3, // pulse

    // PBSysWindowSignal_KEY is active when the window is the key window of the application
    PBSysWindowSignal_KEY = 1u << 4,
} PBSysWindowSignals;

`PBSysThreadConfig`

typedef struct PBSysThreadConfig {
    PBSysThreadEntry entry;
    u64              arg1, arg2;

    // thread stack memory
    void* stack;
    u32   stackSize;

    /*
    rights for the new thread's SELF_THREAD handle. Usually you want this to be PBSysRight_SAME_RIGHTS
    */
    PBSysRights rights;

    // handles to be transferred from the caller to the new thread
    const PBSysHandle* nullable transferHandles;
    u32                         transferHandlesCount;
} PBSysThreadConfig;

`PBSysWindowSetRectFlags`

typedef u64 PBSysWindowSetRectFlags;

`PBSysWindowCreateTextureFlags`

typedef u32 PBSysWindowCreateTextureFlags;

`PBSysWindowStyle`

typedef u64 PBSysWindowStyle;

`PBSysWindowConfig`

typedef struct PBSysWindowConfig {
    f32                x, y;          // location on screen in dp (-1 = default location)
    f32                width, height; // content size in dp (0 = default size)
    const u8* nullable title;         // UTF-8 text
    u32                titleLen;      // number of bytes at 'title'
    u64                _reserved[4];
} PBSysWindowConfig;

`PBSysWindowInfo`

typedef struct PBSysWindowInfo {
    f32              x, y;                        // position of top-left corner on screen, in dp
    f32              width, height;               // size of window in dp (including OS decorations)
    f32              minWidth, minHeight;         // lower limit of width & height
    f32              maxWidth, maxHeight;         // upper limit of width & height
    f32              contentX, contentY;          // offset of content relative to the window frame
    f32              contentWidth, contentHeight; // size of window contents in dp
    f32              dpScale;                     // number of pixels per dp
    u32              _reserved1;
    PBSysWindowStyle style;
    PBSysTime        frameTime; // estimated presentation time of next frame
} PBSysWindowInfo;

`PBSysWindowRendererShapeItem`

typedef struct PBSysWindowRendererShapeItem {
    struct {
        f32 x, y, z, w;
    } bounds; // (minX, minY, maxX, maxY)

    struct {
        u16 x, y, z, w;
    } cornerRadius; // Per-corner radii (pixels): (tl, tr, br, bl)

    u64 fillColor; // 0xAAAARRRRGGGGBBBB
    u64 fillColors[4];
    u64 strokeColor; // 0xAAAARRRRGGGGBBBB
    f32 strokeWidth; // px
    u32 flags;       // 1=stroke_inside, 2=stroke_outside, 4=clip
    f32 blur;        // px
    f32 opacity;     // 0->1 percent

    // UV sub-rectangle for texture sampling.
    struct {
        f32 x, y;
    } uvMin; // top-left UV
    struct {
        f32 x, y;
    } uvMax; // bottom-right UV

    u8 padding[8];
} PBSysWindowRendererShapeItem;

`PBSysWindowRendererTextItem`

typedef struct PBSysWindowRendererTextItem {
    struct {
        f32 x, y, z, w;
    } bounds;

    PBSysHandle textPlan;

    u64 overrideColor; // 0xAAAARRRRGGGGBBBB
    u32 flags;         // 1=override color
    u8  padding[4];
} PBSysWindowRendererTextItem;

`PBSysWindowRendererClipItem`

typedef struct PBSysWindowRendererClipItem {
    struct {
        f32 x, y, z, w;
    } bounds;
} PBSysWindowRendererClipItem;

`PBSysWindowRendererInstructionKind`

typedef enum PBSysWindowRendererInstructionKind {
    PBSysWindowRendererInstructionKind_SHAPE,
    PBSysWindowRendererInstructionKind_TEXT,
    PBSysWindowRendererInstructionKind_CLIP_PUSH,
    PBSysWindowRendererInstructionKind_CLIP_POP,
    PBSysWindowRendererInstructionKind_TEXTURE_SET, // set/clear the active texture for SHAPE draws
} PBSysWindowRendererInstructionKind;

`PBSysWindowRendererInstruction`

typedef struct PBSysWindowRendererInstruction {
    PBSysWindowRendererInstructionKind kind;

    union {
        // a run of renderable "content"
        struct {
            u32 runLength;
        } content;
        // TEXTURE_SET: set active texture; PBSysHandle_INVALID clears to default (no texture)
        struct {
            PBSysHandle texture;
        } setTexture;
    };
} PBSysWindowRendererInstruction;

`PBSysWindowRendererPackage`

typedef struct PBSysWindowRendererPackage {
    u64 backgroundColor; // 0xAAAARRRRGGGGBBBB

    const PBSysWindowRendererShapeItem* shapes;
    u32                                 shapesLen;
    u32                                 shapeSize;

    const PBSysWindowRendererTextItem* texts;
    u32                                textsLen;
    u32                                textSize;

    const PBSysWindowRendererInstruction* instructions;
    u32                                   instructionsLen;
    u32                                   instructionSize;

    const PBSysWindowRendererClipItem* clips;
    u32                                clipsLen;
    u32                                clipSize;
} PBSysWindowRendererPackage;

`PBSysCallOp`

typedef enum PBSysCallOp PB_ENUM_TYPE(uint32_t){
    PBSysCallOp_None = 0, // invalid
    PBSysCallOp_AudioBufferCreate = 117,
    PBSysCallOp_AudioBufferCreateFromFile = 121,
    PBSysCallOp_AudioBufferDestroy = 118,
    PBSysCallOp_AudioBufferPlay = 119,
    PBSysCallOp_AudioOutputInit = 122,
    PBSysCallOp_AudioSetVolume = 120,
    PBSysCallOp_BundleGetResource = 125,
    PBSysCallOp_ChannelCreate = 65,
    PBSysCallOp_ChannelDisableWrite = 68,
    PBSysCallOp_ChannelRead = 66,
    PBSysCallOp_ChannelWrite = 67,
    PBSysCallOp_ClockMonotonic = 56,
    PBSysCallOp_ClockRead = 25,
    PBSysCallOp_ClockReadInfo = 60,
    PBSysCallOp_EventPoll = 58,
    PBSysCallOp_FileListOpen = 98,
    PBSysCallOp_FileOpen = 103,
    PBSysCallOp_FileRead = 104,
    PBSysCallOp_FileWrite = 105,
    PBSysCallOp_FileListNext = 102,
    PBSysCallOp_GuiCursorStyleSet = 69,
    PBSysCallOp_HandleClose = 70,
    PBSysCallOp_HandleDuplicate = 71,
    PBSysCallOp_HandleList = 77,
    PBSysCallOp_NetConnect = 95,
    PBSysCallOp_NetSessionOpen = 90,
    PBSysCallOp_NetSessionId = 93,
    PBSysCallOp_NetSessionOpenStream = 91,
    PBSysCallOp_ObjectObserve = 57,
    PBSysCallOp_ObjectSignal = 55,
    PBSysCallOp_StreamOpenPipePair = 92,
    PBSysCallOp_StreamRead = 46,
    PBSysCallOp_StreamStatsRead = 94,
    PBSysCallOp_StreamWrite = 28,
    PBSysCallOp_TextplanGetCaretBounds = 81,
    PBSysCallOp_TextplanGetSelectionRects = 83,
    PBSysCallOp_TextplanGetSize = 38,
    PBSysCallOp_TextplanHitTest = 82,
    PBSysCallOp_TextplanLayout = 40,
    PBSysCallOp_TextplanMoveSelection = 85,
    PBSysCallOp_TextplanMoveSelectionToPoint = 84,
    PBSysCallOp_TextplanMoveSelectionVertical = 88,
    PBSysCallOp_TextureWrite = 106,
    PBSysCallOp_ThreadEnterMain = 59,
    PBSysCallOp_ThreadExit = 30,
    PBSysCallOp_ThreadExitProcess = 31,
    PBSysCallOp_ThreadExitStatus = 47,
    PBSysCallOp_ThreadHostControllerConnect = 79,
    PBSysCallOp_ThreadLogWrite = 32,
    PBSysCallOp_ThreadNetConnect = 42,
    PBSysCallOp_ThreadRead = 76,
    PBSysCallOp_ThreadStart = 33,
    PBSysCallOp_ThreadWindowCreate = 41,
    PBSysCallOp_ThreadWrite = 75,
    PBSysCallOp_WindowClipboardReadText = 107,
    PBSysCallOp_WindowClipboardWriteText = 108,
    PBSysCallOp_WindowCopyTitle = 126,
    PBSysCallOp_WindowCreateTexture = 109,
    PBSysCallOp_WindowCreateTextureFromData = 110,
    PBSysCallOp_WindowFrameSyncEnable = 63,
    PBSysCallOp_WindowInfoGet = 64,
    PBSysCallOp_WindowRendererPackageWrite = 78,
    PBSysCallOp_WindowSetRect = 87,
    PBSysCallOp_WindowSetStyle = 127,
    PBSysCallOp_WindowSetTitle = 80,
    PBSysCallOp_WindowSizeLimitsSet = 128,
    PBSysCallOp_WindowTextplanCreate = 36,
    PBSysCallOp_READ = 9,               // legacy
    PBSysCallOp_WGPU = 10,              // legacy
    PBSysCallOp_CURSOR = 14,            // legacy
    PBSysCallOp_RES_CREATE = 15,        // legacy
    PBSysCallOp_RES_MUTATE = 16,        // legacy
    PBSysCallOp_RES_ADVERTISE_NEW = 17, // legacy
    PBSysCallOp_TAKE_ROOT_CAP = 18,     // legacy
    PBSysCallOp_OPEN = 19,              // legacy
} PBSysCallOp;

`PBSysHandle`

typedef i32 PBSysHandle;

PBSysHandle represents a handle to a runtime object. A handle can be thought of as a session or connection to a particular runtime object. Note: negative values signifies PBSysErr and are invalid as handles.

`PBSysHandlePair`

typedef struct PBSysHandlePair {
    PBSysHandle a, b;
} PBSysHandlePair;

`PBSysTime`

typedef u64 PBSysTime;

PBSysTime represents a point in system time (nanoseconds in monotonic-clock space)

`PBSysDuration`

typedef i64 PBSysDuration;

PBSysDuration represents a duration of time, measured in nanoseconds.

`PBSysDate`

typedef i64 PBSysDate;

PBSysDate represents a point in "real" time (microseconds since 1970-01-01 00:00:00 UTC.) Range limit: [290309 BCE, Dec 22, 19:59:05 UTC - 294247, Jan 10, 04:00:54 UTC]

`PBSysStr`

typedef struct PBSysStr {
    uint32_t len;
    uint8_t  bytes[];
} PBSysStr;

`PBSysBuf`

typedef struct PBSysBuf {
    const uint8_t* nullable bytes;
    size_t                  len;
} PBSysBuf;

`PBSysObjectId`

typedef u32 PBSysObjectId;

PBSysObjectId uniquely identifies a system object

`PBSysSignals`

typedef u32 PBSysSignals;

PBSysSignals is a bitset of signals.

Bits 1 through 24 are reserved for the system.
Bits 25 through 32 are reserved for user-defined signals.

`PBSysEventLegacy`

typedef struct PBSysEventLegacy {
    uint16_t type; // PBSysEventLegacyType
    uint8_t  _reserved[6];
    union {
        struct { // PBSysEventLegacy_START
            uint32_t                  flags;
            uint32_t                  sysbufSize;
            void*                     sysbuf;
            PBSysHandleInfo* nullable handles;
            uint32_t                  handlesCount;
            uint64_t                  arg1, arg2; // values passed to PBSysThreadStart
        } start;
        struct { // PBSysEventLegacy_READ
            int32_t     result;
            PBSysHandle from;
            uint64_t    ud; // associated user data
        } read;
        struct { // PBSysEventLegacy_WRITE
            int32_t     result;
            PBSysHandle to;
            uint64_t    ud; // associated user data
        } write;
        struct { // PBSysEventLegacy_INPUT
            uint32_t type;
            uint32_t window;
            uint16_t index;
            uint16_t flags;
            uint32_t value;
            uint32_t extra1;
            uint32_t extra2;
        } input;
        struct { // PBSysEventLegacy_AUDIO_OUT
            uint16_t channelCount;
            uint16_t _reserved;
            uint32_t sampleCount; // per channel
            float    sampleRate;  // HZ
            float*   samples;     // interleaved, channels * sampleCount
        } audioOut;
        struct {                  // PBSysEventLegacy_RESIZE
            uint32_t width;       // TODO(rsms): unit?
            uint32_t height;      // TODO(rsms): unit?
            uint32_t scaleFactor; // percentage. TODO(rsms): change to f32 or f64
        } resize;
        struct { // PBSysEventLegacy_DISPLAY_SYNC
            uint32_t displayId;
            uint32_t width;
            uint32_t height;
            uint32_t scaleFactor;
            uint64_t frameTime; // in PBSysOp_CLOCK space
        } displaySync;
        struct { // PBSysEventLegacy_WGPU_CALLBACK
            PBWgpuCallbackKind            kind;
            PBSysEventLegacy_WgpuCallback data;
        } wgpuCallback;
        struct {                    // PBSysEventLegacy_THREAD_EXIT
            PBSysHandle thread;     // what thread exited
            int32_t     status;     // value passed to PBSysThreadExit
            void*       sysbuf;     // value passed to PBSysThreadStart
            uint32_t    sysbufSize; // value passed to PBSysThreadStart
            uint64_t    arg1, arg2; // values passed to PBSysThreadStart
        } threadExit;
        struct {               // PBSysEventLegacy_TIMER
            PBSysHandle timer; // what timer rang
        } timer;
        struct { // PBSysEventLegacy_SIGNAL
            PBSysSignals signals;
            PBSysHandle  handle;
            uint64_t     ud; // value provided to PBSysObjectObserve
        } signal;
        uint8_t _info[64];
    };
} PBSysEventLegacy;

PBSysEventLegacy describes an event produced by the Playbit system. See sysevents.h for complete definition.

`PBSysThreadEntry`

typedef void (*PBSysThreadEntry)(uint64_t, uint64_t);

PBSysThreadEntry

`PBSysTextureFormat`

typedef enum PB_ENUM_TYPE(u32) {
    PBSysTextureFormat_UNKNOWN,
    PBSysTextureFormat_RGBA8,
} PBSysTextureFormat;

`PBSysNetSessionSignals`

typedef enum PB_ENUM_TYPE(uint32_t) {
    /*
    PBSysNetSessionSignal_AVAILABLE means the session's underlying AP transport is connected. The runtime may still be authenticating the session while this signal is active without `PBSysNetSessionSignal_READY`.
    */
    PBSysNetSessionSignal_AVAILABLE = 1u << 4,

    /*
    PBSysNetSessionSignal_READY means the session is authenticated and its AP streams may become writable. When this signal is active, `PBSysNetSessionSignal_AVAILABLE` is also active.
    */
    PBSysNetSessionSignal_READY = 1u << 0,
} PBSysNetSessionSignals;

This file defines all syscalls.

Syscalls are executed via pb_syscall defined in abi.h.

The API only evolves forward; syscalls are backwards compatible, (i.e. a program built for an older system works on newer systems.)

`PBSysChannelSignals`

typedef enum PB_ENUM_TYPE(uint32_t) {
    PBSysChannelSignal_READABLE = 1u << 0,       // there are entries to read
    PBSysChannelSignal_WRITABLE = 1u << 1,       // there's space for writing at least one entry
    PBSysChannelSignal_WRITE_DISABLED = 1u << 2, // writing has been closed
} PBSysChannelSignals;

`PBSysClockSignals`

typedef enum PB_ENUM_TYPE(uint32_t) {
    PBSysClockSignal_TIME_ZONE = 1u << 0, // time zone changed (pulse)
} PBSysClockSignals;

`PBSysStreamSignals`

typedef enum PB_ENUM_TYPE(uint32_t) {
    PBSysStreamSignal_READABLE = 1u << 0,
    PBSysStreamSignal_WRITABLE = 1u << 1,
    PBSysStreamSignal_PEER_CLOSED = 1u << 2,
    PBSysStreamSignal_PEER_WRITE_DISABLED = 1u << 3,
    PBSysStreamSignal_WRITE_DISABLED = 1u << 4,
} PBSysStreamSignals;

`PBSysHandleListFlags`

typedef enum PB_ENUM_TYPE(u64) {
    PBSysHandleList_FILTER = 0xff, // mask for a PBSysHandleListFilter_ value
} PBSysHandleListFlags;

`PBSysHandleListFilter`

typedef enum PB_ENUM_TYPE(u8) {
    PBSysHandleListFilter_BY_NAME = 1,        // predicate is of type PBSysHandleName
    PBSysHandleListFilter_BY_OBJECT_ID = 2,   // predicate is of type PBSysObjectId
    PBSysHandleListFilter_BY_OBJECT_TYPE = 3, // predicate is of type PBSysObjectType
} PBSysHandleListFilter;

Constants

Name	Type	Value	Description
`PBSysHandle_INVALID`	`PBSysHandle`	`0`
`PBSysHandle_SELF_THREAD`	`PBSysHandle`	`1`	current thread
`PBSysHandleName_CONSOLE`	`PBSysHandleName`	``	the console
`PBSysHandleName_NONE`	`PBSysHandleName`	`0`
`PBSysHandleName_USER_MAX`	`PBSysHandleName`	`32767`
`PBSysNetSessionChannelIdMaxLen`	`int`	`64`	max allowed length of a channelId
`PBSysNetSessionIdMaxLen`	`int`	`64`	max allowed length of a sessionId
`PBSysObjectId_MAIN_THREAD`	`PBSysObjectId`	`1`
`PBSysObjectId_ROOT_FS`	`PBSysObjectId`	`2`
`PBSysObjectObserve_ADD`	`u32`	`2`	PBSysObjectObserve_ADD causes `signals` to be added to any signals already observed for the handle. Without this flag, the behavior is that `signals` replaces any already-observed signals. The ADD flag is mainly useful in combination with the ONCE flag.
`PBSysObjectObserve_ONCE`	`u32`	`1`	PBSysObjectObserve_ONCE changes the behavior of event delivery to being "edge" triggered
`PBSysSignal_ALL`	`u32`	`4294967295`
`PBSysSignal_SYSTEM_ALL`	`u32`	`16777215`
`PBSysSignal_USER_0`	`u32`	`16777216`
`PBSysSignal_USER_1`	`u32`	`33554432`
`PBSysSignal_USER_2`	`u32`	`67108864`
`PBSysSignal_USER_3`	`u32`	`134217728`
`PBSysSignal_USER_4`	`u32`	`268435456`
`PBSysSignal_USER_5`	`u32`	`536870912`
`PBSysSignal_USER_6`	`u32`	`1073741824`
`PBSysSignal_USER_7`	`u32`	`2147483648`
`PBSysSignal_USER_ALL`	`u32`	`4278190080`
`PBSysTextplanSelectionAdjustment_ALL_GRANULARITY`	`int`	`4`
`PBSysTextplanSelectionAdjustment_BACKWARDS`	`int`	`8`
`PBSysTextplanSelectionAdjustment_DELETE_AFTERWARDS`	`int`	`64`
`PBSysTextplanSelectionAdjustment_IN_LINE_GRANULARITY`	`int`	`32`
`PBSysTextplanSelectionAdjustment_LINE_ENDS_GRANULARITY`	`int`	`128`
`PBSysTextplanSelectionAdjustment_LINE_GRANULARITY`	`int`	`2`
`PBSysTextplanSelectionAdjustment_MAKE_SELECTION`	`int`	`16`
`PBSysTextplanSelectionAdjustment_TO_MOUSE_RIGHT_CLICK`	`int`	`2147483648`
`PBSysTextplanSelectionAdjustment_WORD_GRANULARITY`	`int`	`1`
`PBSysWindowCreateTextureFlag_NEAREST`	`PBSysWindowCreateTextureFlags`	`2`	nearest-neighbor filtering (default: linear)
`PBSysWindowCreateTextureFlag_STREAMING`	`PBSysWindowCreateTextureFlags`	`1`	hint: texture will be updated frequently
`PBSysWindowCreateTextureFlag_WRAP_U`	`PBSysWindowCreateTextureFlags`	`4`	repeat along U axis (default: clamp)
`PBSysWindowCreateTextureFlag_WRAP_V`	`PBSysWindowCreateTextureFlags`	`8`	repeat along V axis (default: clamp)
`PBSysWindowSetRectFlag_ANIMATE`	`PBSysWindowSetRectFlags`	`8`	animated resize
`PBSysWindowSetRectFlag_CENTER`	`PBSysWindowSetRectFlags`	`16`	center on screen
`PBSysWindowSetRectFlag_ORIGIN`	`PBSysWindowSetRectFlags`	`2`	set position but keep size unchanged
`PBSysWindowSetRectFlag_OUTER`	`PBSysWindowSetRectFlags`	`1`	set outer size, including OS decorations
`PBSysWindowSetRectFlag_SIZE`	`PBSysWindowSetRectFlags`	`4`	set size but keep position unchanged
`PBSysWindowStyle_CLOSABLE`	`PBSysWindowStyle`	`2`	can be closed; has close button
`PBSysWindowStyle_FULLSIZE_CONTENT`	`PBSysWindowStyle`	`64`	PBSysWindowStyle_FULLSIZE_CONTENT enables the content of the window to be drawn underneath the titlebar
`PBSysWindowStyle_HIDDEN_TITLE`	`PBSysWindowStyle`	`32`	PBSysWindowStyle_HIDDEN_TITLE makes the title hidden, not drawn. The title may still appear in other places in the OS, like task switchers.
`PBSysWindowStyle_MINIMIZABLE`	`PBSysWindowStyle`	`4`	can be minimized
`PBSysWindowStyle_RESIZABLE`	`PBSysWindowStyle`	`8`	can be resized
`PBSysWindowStyle_THEME_BRIGHT`	`PBSysWindowStyle`	`128`	PBSysWindowStyle_THEME_BRIGHT overrides the OS default and configures the window to use the OS's bright UI theme
`PBSysWindowStyle_THEME_DARK`	`PBSysWindowStyle`	`256`	PBSysWindowStyle_THEME_DARK overrides the OS default and configures the window to use the OS's dark UI theme
`PBSysWindowStyle_TITLEBAR`	`PBSysWindowStyle`	`1`	has titlebar
`PBSysWindowStyle_TRANSPARENT_TITLEBAR`	`PBSysWindowStyle`	`16`	PBSysWindowStyle_TRANSPARENT_TITLEBAR makes the titlebar is transparent. Implies PBSysWindowStyle_FULLSIZE_CONTENT

Macros

`PBSysObject_FOREACH`

macro void PBSysObject_FOREACH(macro(NAME) m)

calls a macro m for each object name, e.g. m(Thread)

`PBSysEventSize_MAX`

#define PBSysEventSize_MAX usize

PBSysEventSize_MAX is the maximum size used for any single event. In practice only IME events have a chance of being limited by this.

`PB_ENUM_TYPE`

macro PB_ENUM_TYPE(T) -> :T

Usage example:

enum Foo PB_ENUM_TYPE(uint16_t) { Foo_A, Foo_B };

`PBSys_START_MAIN`

#define PBSys_START_MAIN …

the main thread is starting

Functions

`PBSysAudioBufferCreate`

PBSysAudioBuffer PBSysAudioBufferCreate(PBSysHandle audio,
                                        const void* data,
                                        usize       dataSize,
                                        u32         numChannels,
                                        u32         sampleRate,
                                        u32         totalSampleCount);

Creates a new audio buffer and uploads it to the sound mixer.

Required rights: none

`PBSysAudioOutputInit`

bool PBSysAudioOutputInit(PBSysHandle audio);

Inits the audio output backend for sound playback (globally). It has been observed that sometimes this can take a little while (e.g. ~200ms when using bluetooth headphones on MacOS). As such, you should call this at the start of your program if you intend to play audio.

Required rights: none

`PBSysAudioBufferCreateFromFile`

PBSysAudioBuffer PBSysAudioBufferCreateFromFile(PBSysHandle audio,
                                                const void* data,
                                                usize       dataSize);

Creates an audio buffer from a file. At the present moment, we only support raw WAV file data. This function will be extended in the future to support more formats.

Required rights: none

`PBSysAudioBufferDestroy`

PBSysErr PBSysAudioBufferDestroy(PBSysHandle      audio,
                                 PBSysAudioBuffer buffer);

Destroys an audio buffer (and frees the associated memory with it).

Required rights: none

`PBSysAudioBufferPlay`

PBSysAudioSound PBSysAudioBufferPlay(PBSysHandle      audio,
                                     PBSysAudioBuffer buffer);

Starts playing an instance of an audio buffer.

Required rights: none

`PBSysAudioSetVolume`

PBSysErr PBSysAudioSetVolume(PBSysHandle audio,
                             f32         volume);

Sets the global volume of the sound mixer.

Required rights: none

`PBSysBundleGetResource`

i64 PBSysBundleGetResource(PBSysHandle bundle,
                           const u8*   name,
                           usize       nameLen,
                           u8*         dest,
                           usize       destLen);

PBSysBundleGetResource retrieves a bundles resource, as described by the app's manifest at build time.

dest: The memory location in the guest program where the runtime will copy the resource
destLen: How large of a space in guest memory for the runtime to copy into
Returns: The size of the resource which has been loaded, or a PBSysErr value if < 0
Required rights: PBSysRight_READ

`PBSysChannelCreate`

PBSysHandle PBSysChannelCreate(u32          entSize,
                               u32          cap,
                               u32          maxCap,
                               PBSysHandle* readHandleOut,
                               u64          flags);

PBSysChannelCreate creates a channel which supports writing entries of entSize bytes.

If the PBSysChannel_DUPLEX flag is set, the returned handles will have both PBSysRight_READ and PBSysRight_WRITE. PBSysChannel_DUPLEX is implied if readHandleOut is NULL.

If the PBSysChannel_MULTIPLE_WRITERS flag is set, the returned handle will have PBSysRight_DUPLICATE. Similarly, if the PBSysChannel_MULTIPLE_READERS flag is set, a handle returned in readHandleOut will have PBSysRight_DUPLICATE.

readHandleOut: If not NULL, a second handle is returned with PBSysRight_READ.
cap: Initial capacity of the internal buffer, in number of entries. I.e. the total amount of memory allocated for the internal buffer is at least entSize*cap bytes.
maxCap: Limits how much the internal buffer can grow. If maxCap is <= cap, a fixed size is used.
Returns: A handle to the channel with PBSysRight_WRITE.
Required rights: none

`PBSysChannelRead`

i32 PBSysChannelRead(PBSysHandle channel,
                     void*       dstEnts,
                     u32         dstEntSize,
                     u32         dstEntsCap,
                     u64         flags);

PBSysChannelRead reads up to dstEntsCap entries from a channel.

Panics if srcEntSize is different than the entSize the channel was created with.

dstEnts: Must be an array of dstEntsCap number of entries, dstEntSize bytes each.
flags: Should be 0.
Returns: The number of entries read. 0 if there were no entries to be read or if dstEntsCap == 0. PBSysErr_END if the channel is closed.
Required rights: PBSysRight_READ

`PBSysChannelWrite`

i32 PBSysChannelWrite(PBSysHandle channel,
                      const void* srcEnts,
                      u32         srcEntSize,
                      u32         srcEntsCap,
                      u64         flags);

PBSysChannelWrite writes up to srcEntsCap entries to a channel.

Panics if srcEntSize is different than the entSize the channel was created with.

srcEnts: Must be an array of srcEntsCap number of entries, srcEntSize bytes each.
flags: Should be 0.
Returns: The number of entries written. 0 if the channel is full or srcEntsCap == 0. PBSysErr_END if the channel is closed for writing.
Required rights: PBSysRight_WRITE

`PBSysChannelDisableWrite`

PBSysErr PBSysChannelDisableWrite(PBSysHandle channel);

PBSysChannelDisableWrite disables the ability to write to the channel, while reading remains possible. This is useful for "graceful shutdown" of channels; preventing new data from being produces while allowing queued data to be flushed.

Required rights: PBSysRight_WRITE

`PBSysClockMonotonic`

PBSysTime PBSysClockMonotonic();

PBSysClockMonotonic returns the current system time

Required rights: none

`PBSysClockRead`

PBSysDate PBSysClockRead(PBSysHandle clock);

PBSysClockRead returns the current "real" (calendar) time in UTC. On error, a PBSysErr is returned as a negative value. Thus, this function never returns a time value earlier than 1970-01-01 00:00:00.

Required rights: PBSysRight_READ

`PBSysClockReadInfo`

PBSysErr PBSysClockReadInfo(PBSysHandle     clock,
                            PBSysClockInfo* info,
                            u32             infoSize);

PBSysClockReadInfo retrieves information about a clock

Required rights: PBSysRight_READ

`PBSysEventPoll`

i32 PBSysEventPoll(PBSysEvent* events,
                   u32         eventsSize,
                   u64         deadline,
                   u64         deadlineLeeway);

PBSysEventPoll retrieves events from the runtime, suspending the calling thread if needed.

events: Buffer to be populated with produced events.
eventsSize: Total number of bytes available at events. Note that this is not the number of PBSysEvent structs but bytes of memory. The size of a PBSysEvent is variable. Generally this should be at least a kilobyte since IME input events may be arbitrarily large. In most cases single events are small; tens of bytes.
deadline: When to time out. If deadline is U64_MAX, it will wait indefinitely until at least one event can be returned or an error occurs. If deadline is 0, this function only checks for available events without blocking.
deadlineLeeway: Precision request in nanoseconds; how much deadline is willing to fluctuate.
Returns: The number of events written (not the number of bytes.) 0 if deadline was reached, when deadline > 0. 0 if there were no events available, when deadline == 0 or eventsCap == 0. PBSysErr_END if the current thread is exiting (even pipeline shut down.) PBSysErr_NO_MEM if eventsSize is too small for a single event.
Required rights: none

`PBSysFileOpen`

PBSysHandle PBSysFileOpen(PBSysHandle dir,
                          const u8*   path,
                          u32         pathLen,
                          u64         flags);

PBSysFileOpen opens a file or directory that's contained within a directory denoted by dir.

The effective rights given to the opened file must be the same or a subset of the rights given to the fs handle. I.e. on a read-only filesystem you cannot pass PBSysFileOpenFlag_WRITE.

The resulting handle is given PBSysRight_TRANSFER and PBSysRight_DUPLICATE, in addition to PBSysRight_READ and/or PBSysRight_WRITE as defined by flags.

dir: Parent directory, an object of type PBSysObject_File
path: Path as UTF-8 text
pathLen: Size in bytes of path. Must be >0
flags: Bits of PBSysFileOpenFlags
Returns: Handle to a PBSysObject_File object that represents the item at path, or PBSysErr (negative value) on error
Required rights: PBSysRight_READ

`PBSysFileRead`

i64 PBSysFileRead(PBSysHandle     file,
                  const PBSysBuf* bufs,
                  u32             bufCount,
                  u32             flags);

PBSysFileRead reads bytes from a file at its current read cursor into one or more buffers.

Note: Currently only synchronous reads are supported. Returns PBSysErr_NOT_SUPPORTED unless PBSysFileReadFlag_SYNC is set.

flags: Bits of PBSysFileReadFlags
Required rights: PBSysRight_READ

`PBSysFileWrite`

i64 PBSysFileWrite(PBSysHandle     file,
                   const PBSysBuf* bufs,
                   u32             bufCount,
                   u32             flags);

PBSysFileWrite writes bytes from one or more buffers to a file at the file's current write cursor.

Note: Currently only synchronous writes are supported. Returns PBSysErr_NOT_SUPPORTED unless PBSysFileWriteFlag_SYNC is set.

flags: Bits of PBSysFileWriteFlags
Required rights: PBSysRight_WRITE

`PBSysFileListOpen`

PBSysHandle PBSysFileListOpen(PBSysHandle dir,
                              const u8*   path,
                              u32         pathLen,
                              u64         flags);

PBSysFileListOpen begins a list operation of the directory dir/path, or dir if pathLen is 0. Call PBSysFileListNext to retrieve entries and PBSysHandleClose when done.

path: Path as UTF-8 text
pathLen: Size in bytes of path. May be 0 to mean "dir"
flags: Unused. Pass 0.
Returns: a handle to an object of type PBSysObject_FileList
Required rights: none

`PBSysFileListNext`

i32 PBSysFileListNext(PBSysHandle         fileList,
                      u8*                 name,
                      u32                 nameCap,
                      PBSysFileListEntry* entry,
                      u32                 entrySize,
                      u64                 flags);

PBSysFileListNextName read the name of the next entry in a directory listing.

fileList: Handle to object of type PBSysObject_FileList
name: Buffer in which to write name of next entry
nameCap: Capacity of name, in bytes
entry: Optional buffer in which to write additional information about the next entry
entrySize: Size in bytes of entry
Returns: Total number of bytes written to name PBSysErr_END when the end of the list has been reached. PBSysErr_BUFFER_TOO_SMALL if name was too short, in which can you can try again with larger nameCap PBSysErr as a negative value on error.
Required rights: PBSysRight_READ

`PBSysGuiCursorStyleSet`

PBSysErr PBSysGuiCursorStyleSet(PBSysHandle      gui,
                                u32              pointerId,
                                PBSysCursorStyle style,
                                PBSysHandle      image,
                                u64              flags);

PBSysGuiCursorStyleSet sets the appearance of specified pointer's cursor.

pointerId: set to 0 to set cursor for all pointers, or a specific pointerId (e.g. from a PBSysPointerEvent) to set the cursor only for that pointer.
style determines how the cursor is presented.
image should be the handle of an image if style is PBSysCursorStyle_IMAGE, otherwise the image parameter is ignored and should be 0.
flags are unused; pass 0.
Required rights: none

`PBSysHandleClose`

PBSysErr PBSysHandleClose(PBSysHandle handle);

PBSysHandleClose closes a handle. The handle is invalid after this call.

Required rights: none

`PBSysHandleDuplicate`

PBSysHandle PBSysHandleDuplicate(PBSysHandle     handle,
                                 PBSysRights     rights,
                                 PBSysHandleName name);

PBSysHandleDuplicate creates a new handle to the object referred to by handle. rights controls what rights are given and can only be same or less than the rights granted to handle. Use PBSysRight_SAME_RIGHTS for "same rights." Note: The new handle is unconditionally given PBSysRight_TRANSFER.

Returns: A negative value as PBSysError on error.
Required rights: PBSysRight_DUPLICATE

`PBSysHandleList`

i32 PBSysHandleList(PBSysHandleInfo* handles,
                    u32              handlesCap,
                    u32              handleSize,
                    u64              flags,
                    u64              predicate);

PBSysHandleList returns information about handles held by the calling thread. Writes up to handlesCap entries to handles.

flags are bits of PBSysHandleListFlags.

If flags contain a filter; a PBSysHandleListFilter value in the bits PBSysHandleList_FILTER, then predicate is a value for the filter. Only handles matching the filter are returned.

Returns: The total number of handles, which might be more than handlesCap. <0 if an error occurred, as a PBSysErr.
Required rights: none

`PBSysNetSessionOpen`

PBSysHandle PBSysNetSessionOpen(PBSysHandle                  net,
                                const u8*                    sessionId,
                                u32                          sessionIdLen,
                                const PBSysNetSessionConfig* config,
                                u32                          configSize);

PBSysNetSessionOpen opens a Playbit network session

net: Networking capability (handle to an object of type PBSysObject_Net)
sessionId: Session identifier, unique within app-id namespace
sessionIdLen: Size in bytes of sessionId
config: Configuration
configSize: Size in bytes of struct in config parameter
Returns: Handle to a NetSession object, or PBSysErr (negative value) on error. Opening a NetSession starts or attaches to the underlying AP connection asynchronously.
Required rights: none

`PBSysNetConnect`

PBSysHandle PBSysNetConnect(PBSysHandle                  net,
                            const u8*                    uri,
                            u32                          uriLen,
                            const PBSysNetConnectConfig* config,
                            u32                          configSize);

PBSysNetConnect opens a stream connected to a network endpoint.

URIs have the form protocol:node, i.e.

tcp:host:port  TCP/IP socket
local:path     Local socket (aka UNIX socket)

The underlying implementation may not support the requested protocol.

The returned stream will have its PBSysStreamSignal_WRITABLE activated when the connection has been established.

net: Networking capability (handle to an object of type PBSysObject_Net)
uri: URI.
uriLen: Size in bytes of uri
config: Configuration
configSize: Size in bytes of struct in config parameter
Returns: Handle to a NetSession object on success, or PBSysErr (negative value) on error. PBSysErr_NOT_SUPPORTED if the protocol type requested in uri is not supported.
Required rights: none

`PBSysNetSessionId`

PBSysErr PBSysNetSessionId(PBSysHandle netSession,
                           u8*         sessionIdBuf,
                           u32         sessionIdBufCap);

PBSysNetSessionId copies the session identifier bytes of a network session.

netSession: Network session, handle to a NetSession object
sessionIdBuf: Destination buffer for the session identifier bytes
sessionIdBufCap: Size in bytes of sessionIdBuf
Returns: 0 on success, PBSysErr_BUFFER_TOO_SMALL if sessionIdBufCap is too small, or PBSysErr on failure.
Required rights: PBSysRight_READ

`PBSysNetSessionOpenStream`

PBSysHandle PBSysNetSessionOpenStream(PBSysHandle netSession,
                                      const u8*   channelId,
                                      u32         channelIdLen,
                                      u64         flags);

PBSysNetSessionOpenStream opens a stream for a channel in a network session.

netSession: Network session, handle to a NetSession object
channelId: Channel identifier, unique within the network session
channelIdLen: Size in bytes of channelId
flags: Reserved. Must be 0.
Returns: Handle to a Stream object, or PBSysErr (negative value) on error. The stream may become writable later, after the underlying session is authenticated and ready.
Required rights: none

`PBSysObjectObserve`

PBSysErr PBSysObjectObserve(PBSysHandle  handle,
                            PBSysSignals signals,
                            u32          flags);

PBSysObjectObserve configures signal observation of the object referred to by handle.

Signal observation is "level" triggered by default, meaning that whenever an observed signal becomes active, a PBSysEventLegacy.signal is produced, until you cancel observation by calling this function with signals=0. By setting the PBSysObjectObserve_ONCE flag, the behavior changes to be "edge" triggered, where one PBSysObjectObserve call yields just one signal event. If you want to keep observing an object after a signal event in "edge" triggered mode, you need to issue another call to PBSysObjectObserve. ONCE is manily useful for one-off observers of e.g. single-fire timers or threads.

Setting signals to 0 has the effect of canceling observation. If PBSysObjectObserve_ADD is set in flags, setting signals to 0 is an error (PBSysErr_INVALID).

This function may be called multiple times to modify what signals are observed.

Required rights: PBSysRight_OBSERVE

`PBSysObjectSignal`

PBSysErr PBSysObjectSignal(PBSysHandle  handle,
                           PBSysSignals disableUserSignals,
                           PBSysSignals enableUserSignals,
                           PBSysSignals pulseUserSignals);

PBSysObjectSignal clear and/or sets user signals for handle.

First disableUserSignals are applied then enableUserSignals.

Returns: PBSysErr_INVALID if any non-user (i.e. system) signals are included in the bitmasks.
Required rights: none

`PBSysStreamOpenPipePair`

PBSysErr PBSysStreamOpenPipePair(PBSysHandle* handlesOut,
                                 u32          bufferSize,
                                 u64          flags);

PBSysStreamOpenPipePair creates two connected duplex byte streams.

Writes to one handle become readable from the other handle and vice versa.

handlesOut: Receives the two created stream handles on success.
bufferSize: Per-direction buffer capacity in bytes. 0 uses an implementation default.
flags: Must be 0.
Required rights: none

`PBSysStreamRead`

i64 PBSysStreamRead(PBSysHandle     stream,
                    const PBSysBuf* bufs,
                    u32             bufCount,
                    u32             flags);

PBSysStreamRead reads bytes from a stream into one or more buffers.

flags: Unused. Pass 0
Required rights: PBSysRight_READ

`PBSysStreamWrite`

i64 PBSysStreamWrite(PBSysHandle     stream,
                     const PBSysBuf* bufs,
                     u32             bufCount,
                     u32             flags);

PBSysStreamWrite writes bytes from one or more buffers to a stream.

flags: Bits of PBSysStreamWriteFlags
Required rights: PBSysRight_WRITE

`PBSysStreamStatsRead`

PBSysErr PBSysStreamStatsRead(PBSysHandle       stream,
                              PBSysStreamStats* stats,
                              u32               statsSize,
                              u64               flags);

PBSysStreamStatsRead retrieves statistics for a stream.

stats: Storage location for results
statsSize: Capacity of stats in bytes
flags: Unused. Pass 0.
Required rights: none

`PBSysTextplanLayout`

i64 PBSysTextplanLayout(PBSysHandle textPlan,
                        u32         flags,
                        i32         width,
                        i32         height);

PBSysTextplanLayout lays a text document into a rectangular bounding box.

textPlan: The text plan to contain the resulting layout.

flags: Flags bitwise OR-ed together controlling the text layout operation. The available flags are

PBTextPlanLayout_PREFORMATTED = 1<<0: Prevents trimming of trailing/leading/duplicate whitespace.
PBTextPlanLayout_ONE_LINE = 1<<1: When set: the text will be placed on a single line; newline characters are ignored; and PBTextPlanLayout_ALWAYS_SET_HEIGHT is implied. When clear, the text will be wrapped to multiple lines as necessary.
PBTextPlanLayout_ALWAYS_SET_HEIGHT = 1<<2: Implied by PBTextPlanLayout_ONE_LINE. The computed height (see PBSysTextplanGetSize) will be set to the height of the single line, even if the input text is an empty string. Note that #defines are not provided yet for these flags, so you will need to enter the constant values manually.

width: The width of the rectangular bounding box in pixels. Set to 0 for infinite space (and thus preventing line wrapping or truncation).

height: The height of the rectangular bounding box in pixels. Set to 0 for infinite space.

If the system detects that the new bounding box will not affect the existing layout in the text plan, this function will do nothing.

This function performs text shaping and then places the resulting glyphs into lines. If a line were to go off the right side of the box, it will either be truncated with an ellipsis character or wrap to a new line, depending on whether PBTextPlanLayout_ONE_LINE is set.

Once this function has been called, you can use the other text plan functions.

Required rights: PBSysRight_WRITE

`PBSysTextplanGetSize`

u64 PBSysTextplanGetSize(PBSysHandle textPlan);

PBSysTextplanGetSize: Get the size of a text plan's layout.

textPlan: The text plan object.

Return value: The width and height of the plan. The macros PBTextplanWidthOfSize and PBTextplanHeightOfSize can be used to extract the two values from the return value of the function. The returned width is the width of the widest line in the plan in pixels. The returned height is the distance from the top of the first line to the bottom of the last line in pixels.

This function gives no information about where text glyphs may actually be drawn. Glyphs can extend outside the boundaries of the line on which they are placed.

You must call PBSysTextplanLayout before calling this function.

Required rights: PBSysRight_READ

`PBSysTextplanHitTest`

u64 PBSysTextplanHitTest(PBSysHandle textPlan,
                         i32         x,
                         i32         y);

Required rights: none

`PBSysTextplanGetCaretBounds`

u64 PBSysTextplanGetCaretBounds(PBSysHandle textPlan,
                                u64         caretTextIndex);

Required rights: none

`PBSysTextplanGetSelectionRects`

u64 PBSysTextplanGetSelectionRects(PBSysHandle                 textPlan,
                                   u64                         selectionStart,
                                   u64                         selectionEnd,
                                   PBSysTextplanSelectionRect* rects,
                                   u32                         rectsCap,
                                   u32                         rectSize);

PBSysTextplanGetSelectionRects retrieves line-wise selection rectangles relative to the text plan origin.

textPlan: the text plan object
selectionStart: one end of the selection range
selectionEnd: the other end of the selection range
rects: output buffer, or NULL to query the count only
rectsCap: number of entries available in rects
rectSize: size of one entry in rects, usually sizeof(PBSysTextplanSelectionRect)
Returns: the total number of selection rectangles for the requested range
Required rights: PBSysRight_READ

`PBSysTextplanMoveSelectionToPoint`

bool PBSysTextplanMoveSelectionToPoint(PBSysHandle             textPlan,
                                       u32                     mode,
                                       i32                     x,
                                       i32                     y,
                                       PBSysTextplanSelection* selection,
                                       u32                     selectionSize);

PBSysTextplanMoveSelectionToPoint updates a selection by hit-testing a point and applying selection-adjustment flags.

textPlan: the text plan object
mode: a bitwise OR of PBSysTextplanSelectionAdjustment_* flags
x: point x in px relative to the text plan origin
y: point y in px relative to the text plan origin
selection: in-out selection state containing anchor, caret, and lastDown
selectionSize: size of *selection, usually sizeof(PBSysTextplanSelection)
Returns: true if the selection changed
Required rights: PBSysRight_READ

`PBSysTextplanMoveSelection`

bool PBSysTextplanMoveSelection(PBSysHandle             textPlan,
                                u32                     mode,
                                PBSysTextplanSelection* selection,
                                u32                     selectionSize);

PBSysTextplanMoveSelection updates a selection using selection-adjustment flags without hit testing a point.

textPlan: the text plan object
mode: a bitwise OR of PBSysTextplanSelectionAdjustment_* flags
selection: in-out selection state containing anchor, caret, and lastDown
selectionSize: size of *selection, usually sizeof(PBSysTextplanSelection)
Returns: true if the selection changed
Required rights: PBSysRight_READ

`PBSysTextplanMoveSelectionVertical`

bool PBSysTextplanMoveSelectionVertical(PBSysHandle             textPlan,
                                        i32                     preferredX,
                                        bool                    upwards,
                                        bool                    extend,
                                        PBSysTextplanSelection* selection,
                                        u32                     selectionSize);

PBSysTextplanMoveSelectionVertical moves a selection up or down by one visual line while preserving a preferred x position.

textPlan: the text plan object
preferredX: x in px relative to the text plan origin used to preserve column intent
upwards: true to move up one visual line, false to move down
extend: true to extend the current selection instead of collapsing to the moved caret
selection: in-out selection state containing anchor, caret, and lastDown
selectionSize: size of *selection, usually sizeof(PBSysTextplanSelection)
Returns: true if the selection changed
Required rights: PBSysRight_READ

`PBSysTextureWrite`

PBSysErr PBSysTextureWrite(PBSysHandle texture,
                           u32         originXInPx,
                           u32         originYInPx,
                           const void* pixels,
                           u64         pixelSize,
                           u32         widthInPx,
                           u32         heightInPx);

PBSysTextureWrite uploads pixel data to a region of a texture. Pixels must be in the format the texture was created with (RGBA8: 4 bytes per pixel, row-major).

originXInPx: x offset within the texture
originYInPx: y offset within the texture
pixels: pointer to pixel data
pixelCount: number of bytes at pixels (must be >= widthInPx * heightInPx * 4)
widthInPx: width of the upload region
heightInPx: height of the upload region
Required rights: PBSysRight_WRITE

`PBSysThreadEnterMain`

void PBSysThreadEnterMain(u64 flags);

PBSysThreadEnterMain

flags: are bits of PBSysThread_
Required rights: none

`PBSysThreadStart`

PBSysHandle PBSysThreadStart(PBSysHandle              parentThread,
                             u64                      flags,
                             const PBSysThreadConfig* config,
                             u64                      configSize);

PBSysThreadStart starts a new thread.

Required rights: PBSysRight_MANAGE_THREAD

`PBSysThreadExit`

PBSysErr PBSysThreadExit(PBSysHandle thread,
                         i32         status);

PBSysThreadExit stops a thread and sets its exit status.

Required rights: PBSysRight_MANAGE_THREAD

`PBSysThreadExitStatus`

i32 PBSysThreadExitStatus(PBSysHandle thread);

PBSysThreadExitStatus returns the exit status of thread.

Returns: PBSysErr on error.
Required rights: PBSysRight_MANAGE_THREAD

`PBSysThreadExitProcess`

PBSysErr PBSysThreadExitProcess(PBSysHandle thread,
                                i32         status);

PBSysThreadExitProcess terminated the process.

Required rights: PBSysRight_MANAGE_PROCESS

`PBSysThreadWrite`

PBSysErr PBSysThreadWrite(PBSysHandle        thread,
                          const void*        data,
                          u32                dataSize,
                          const PBSysHandle* handles,
                          u32                handlesCount,
                          u64                flags);

PBSysThreadWrite sends a message to a thread. data is copied.

data: to be written
dataSize: is the number of bytes at data
handles: to transfer ownership of to receiver thread
handlesCount: is the number of handles at handles
flags: are currently unused; pass 0.
Required rights: PBSysRight_WRITE

`PBSysThreadRead`

PBSysErr PBSysThreadRead(void*        data,
                         u32*         dataSizeInOut,
                         PBSysHandle* handles,
                         u32*         handlesCountInOut,
                         u64          flags);

PBSysThreadRead receives a message sent to the calling thread.

Messages may contain both byte data and handle payloads and may only be read in their entirety. Partial reads are not possible.

data: is a buffer to place read data into
dataSizeInOut: in: capacity of data, out: bytes read
handles: to accept ownership of, transferred from sender thread
handlesCountInOut: in: capacity of handles, out: handles received
flags: are currently unused; pass 0.
Required rights: none

`PBSysThreadLogWrite`

PBSysErr PBSysThreadLogWrite(PBSysHandle     thread,
                             const PBSysBuf* bufs,
                             u32             bufCount,
                             u32             flags);

PBSysThreadLogWrite writes to the runtime log sink for a thread.

Required rights: none

`PBSysThreadWindowCreate`

PBSysHandle PBSysThreadWindowCreate(PBSysHandle              thread,
                                    const PBSysWindowConfig* config,
                                    usize                    configSize);

PBSysThreadWindowCreate creates a window associated with a thread.

Required rights: PBSysRight_WRITE

`PBSysThreadNetConnect`

PBSysHandle PBSysThreadNetConnect(PBSysHandle thread,
                                  u32         ipAddr,
                                  u16         tcpPort);

Note: Draft API; arguments will change

Required rights: PBSysRight_NETWORK

`PBSysThreadHostControllerConnect`

PBSysHandle PBSysThreadHostControllerConnect(PBSysHandle thread);

Note: Draft API; arguments will change

Required rights: none

`PBSysWindowCreateTexture`

PBSysHandle PBSysWindowCreateTexture(PBSysHandle                   window,
                                     PBSysTextureFormat            format,
                                     u32                           widthInPx,
                                     u32                           heightInPx,
                                     PBSysWindowCreateTextureFlags flags);

PBSysWindowCreateTexture creates an RGBA8 texture associated with a window. The texture can be uploaded to via PBSysTextureWrite and set as the active texture for shape draw calls via a TEXTURE_SET renderer instruction.

format: must be PBSysTextureFormat_RGBA8
flags: PBSysWindowCreateTextureFlags (e.g. STREAMING for frequently updated textures)
Required rights: none

`PBSysWindowCreateTextureFromData`

PBSysHandle PBSysWindowCreateTextureFromData(PBSysHandle                   window,
                                             PBSysTextureFormat            format,
                                             const void*                   data,
                                             u64                           dataSize,
                                             PBSysWindowCreateTextureFlags flags);

PBSysWindowCreateTextureFromData decodes image data and creates a GPU texture in one step. Supported formats: PNG, JPEG, WebP, GIF, BMP, TGA. Pixels are always decoded to RGBA8. The format parameter must be PBSysTextureFormat_RGBA8.

data: pointer to encoded image bytes (e.g. a PNG file loaded into memory)
dataSize: number of bytes at data
flags: PBSysWindowCreateTextureFlags
Required rights: none

`PBSysWindowInfoGet`

PBSysErr PBSysWindowInfoGet(PBSysHandle      window,
                            PBSysWindowInfo* info,
                            u64              infoSize);

PBSysWindowInfoGet retrieves latest window metrics and timing hints.

Required rights: PBSysRight_READ

`PBSysWindowSetRect`

PBSysErr PBSysWindowSetRect(PBSysHandle             window,
                            f32                     x,
                            f32                     y,
                            f32                     width,
                            f32                     height,
                            PBSysWindowSetRectFlags flags);

PBSysWindowSetRect sets the position and size of a window. The actual size of the window may be larger if the size is smaller than the minimum possible window size, according to the host OS.

x & y sets the position on screen of the top-left corner of the window, with a top-left origin. x and y are ignored if PBSysWindowSetRectFlag_CENTER is set.

x: dp
y: dp
width: dp
height: dp
Required rights: PBSysRight_WRITE

`PBSysWindowSetStyle`

PBSysErr PBSysWindowSetStyle(PBSysHandle      window,
                             PBSysWindowStyle style,
                             u64              flags);

PBSysWindowSetStyle sets the style of a window.

Required rights: PBSysRight_WRITE

`PBSysWindowSetTitle`

PBSysErr PBSysWindowSetTitle(PBSysHandle window,
                             const u8*   text,
                             u64         textLen);

PBSysWindowSetTitle sets the title of a window.

text: UTF-8 bytes
textLen: Number of bytes at text
Required rights: PBSysRight_WRITE

`PBSysWindowCopyTitle`

i32 PBSysWindowCopyTitle(PBSysHandle window,
                         u8*         buf,
                         u32         bufCap,
                         u64         flags);

PBSysWindowCopyTitle retrieves the title of a window.

buf: Destination to write UTF-8 bytes
bufCap: Capacity of buf, in bytes
Required rights: PBSysRight_READ

`PBSysWindowSizeLimitsSet`

PBSysErr PBSysWindowSizeLimitsSet(PBSysHandle window,
                                  f32         minWidth,
                                  f32         minHeight,
                                  f32         maxWidth,
                                  f32         maxHeight,
                                  u64         flags);

PBSysWindowSizeLimits sets lower and upper frame size limits.

Use negative numbers to keep values unchanged.

Required rights: PBSysRight_WRITE

`PBSysWindowFrameSyncEnable`

PBSysErr PBSysWindowFrameSyncEnable(PBSysHandle window,
                                    u64         flags);

PBSysWindowFrameSyncEnable controls the production of FRAME_SYNC pulses.

flags: should be 0 (disable) or 1 (enable).
Required rights: none

`PBSysWindowTextplanCreate`

PBSysHandle PBSysWindowTextplanCreate(PBSysHandle window,
                                      const u8*   text,
                                      u64         textSize,
                                      u32         fontFamily,
                                      u32         size,
                                      u32         weight,
                                      u32         color);

PBSysWindowTextplanCreate creates a text plan object associated with a window.

TODO: Proper positioned attributes array.

Required rights: none

`PBSysWindowRendererPackageWrite`

PBSysErr PBSysWindowRendererPackageWrite(PBSysHandle                       window,
                                         const PBSysWindowRendererPackage* package,
                                         usize                             packageSize);

PBSysWindowRendererPackageWrite submits renderer package data for a window.

Required rights: PBSysRight_WRITE

`PBSysWindowClipboardWriteText`

PBSysErr PBSysWindowClipboardWriteText(PBSysHandle window,
                                       const u8*   text,
                                       u64         textSize);

PBSysWindowClipboardWriteText sets the text on the clipboard.

Required rights: PBSysRight_WRITE

`PBSysWindowClipboardReadText`

i64 PBSysWindowClipboardReadText(PBSysHandle window,
                                 u8*         buffer,
                                 u64         bufferSize);

PBSysWindowClipboardWriteText reads the text from the clipboard.

Required rights: PBSysRight_READ