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_Canvas = 22,
    PBSysObject_Channel = 7,
    PBSysObject_Clock = 1,
    PBSysObject_File = 12,
    PBSysObject_FileList = 14,
    PBSysObject_FilePanel = 20,
    PBSysObject_Gui = 8,
    PBSysObject_Hid = 21,
    PBSysObject_Net = 9,
    PBSysObject_NetSession = 10,
    PBSysObject_NetTransport = 19,
    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_SAME_RIGHTS = 1u << 31,
};

`PBSysAudioBuffer`

typedef i64 PBSysAudioBuffer;

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

`PBSysAudioSound`

typedef i64 PBSysAudioSound;

`PBSysVec2`

typedef struct PBSysVec2 {
    f32 x, y;
} PBSysVec2;

`PBSysTextureFormat`

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

`PBSys2DTransform`

typedef struct PBSys2DTransform {
    PBSysVec2 x; // local +x basis vector in pixels
    PBSysVec2 y; // local +y basis vector in pixels
    PBSysVec2 o; // origin in framebuffer pixels
} PBSys2DTransform;

`PBSysCanvasAABB`

typedef struct PBSysCanvasAABB {
    f32 x1, y1;
    f32 x2, y2;
} PBSysCanvasAABB;

`PBSysCanvasCmdKind`

typedef enum PBSysCanvasCmdKind PB_ENUM_TYPE(u16){
    PBSysCanvasCmdKind_INVALID = 0,
    PBSysCanvasCmdKind_RECT,           // PBSysCanvasCmdRect
    PBSysCanvasCmdKind_ROUNDED_RECT,   // PBSysCanvasCmdRoundedRect
    PBSysCanvasCmdKind_STROKE_RECT,    // PBSysCanvasCmdStrokeRect
    PBSysCanvasCmdKind_COMPLEX_RECT,   // PBSysCanvasCmdComplexRect
    PBSysCanvasCmdKind_GRADIENT_RECT,  // PBSysCanvasCmdGradientRect
    PBSysCanvasCmdKind_TEXT,           // PBSysCanvasCmdText
    PBSysCanvasCmdKind_CLIP_PUSH,      // PBSysCanvasCmdClipPush
    PBSysCanvasCmdKind_CLIP_POP,       // PBSysCanvasCmdClipPop
    PBSysCanvasCmdKind_TEXTURE_SET,    // PBSysCanvasCmdTextureSet
    PBSysCanvasCmdKind_TRANSFORM_PUSH, // PBSysCanvasCmdTransformPush
    PBSysCanvasCmdKind_TRANSFORM_POP,  // PBSysCanvasCmdTransformPop
    PBSysCanvasCmdKind_GROUP_PUSH,     // PBSysCanvasCmdGroupPush
    PBSysCanvasCmdKind_GROUP_POP,      // PBSysCanvasCmdGroupPop
    PBSysCanvasCmdKind_GROUP_MASK,     // PBSysCanvasCmdGroupMask
    PBSysCanvasCmdKind_GRADIENT,       // PBSysCanvasCmdGradient
    PBSysCanvasCmdKind_MESH_GRADIENT,  // PBSysCanvasCmdMeshGradient
} PBSysCanvasCmdKind;

`PBSysCanvasBlendMode`

typedef enum PBSysCanvasBlendMode PB_ENUM_TYPE(u16){
    PBSysCanvasBlendMode_NORMAL = 0,
    PBSysCanvasBlendMode_DARKEN,
    PBSysCanvasBlendMode_MULTIPLY,
    PBSysCanvasBlendMode_PLUS_DARKER,
    PBSysCanvasBlendMode_COLOR_BURN,
    PBSysCanvasBlendMode_LIGHTEN,
    PBSysCanvasBlendMode_SCREEN,
    PBSysCanvasBlendMode_PLUS_LIGHTER,
    PBSysCanvasBlendMode_COLOR_DODGE,
    PBSysCanvasBlendMode_OVERLAY,
    PBSysCanvasBlendMode_SOFT_LIGHT,
    PBSysCanvasBlendMode_HARD_LIGHT,
    PBSysCanvasBlendMode_DIFFERENCE,
    PBSysCanvasBlendMode_EXCLUSION,
    PBSysCanvasBlendMode_HUE,
    PBSysCanvasBlendMode_SATURATION,
    PBSysCanvasBlendMode_COLOR,
    PBSysCanvasBlendMode_LUMINOSITY,
    PBSysCanvasBlendMode_MAX_ = PBSysCanvasBlendMode_LUMINOSITY,
} PBSysCanvasBlendMode;

`PBSysCanvasFeature`

typedef enum PBSysCanvasFeature {
    PBSysCanvasFeature_HDR, // supports >1.0 color values for extended dynamic range
} PBSysCanvasFeature;

`PBSysCanvasCmd`

typedef struct PBSysCanvasCmd {
    u16 size;  // total command size in bytes
    u16 kind;  // PBSysCanvasCmdKind
    u32 flags; // kind-specific; must be 0 unless documented
} PB_ATTR_ALIGNED(8) PBSysCanvasCmd;

`PBSysCanvasStrokeFlags`

typedef u32 PBSysCanvasStrokeFlags;

`PBSysCanvasCmdRect`

typedef struct PBSysCanvasCmdRect {
    PBSysCanvasCmd  cmd;
    PBSysCanvasAABB bounds;
    u64             fillColor; // wire color (see above)
} PBSysCanvasCmdRect;

`PBSysCanvasCmdRoundedRect`

typedef struct PBSysCanvasCmdRoundedRect {
    PBSysCanvasCmd  cmd;
    PBSysCanvasAABB bounds;
    u64             fillColor;       // wire color (see above)
    f32             cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
} PBSysCanvasCmdRoundedRect;

`PBSysCanvasCmdStrokeRect`

typedef struct PBSysCanvasCmdStrokeRect {
    PBSysCanvasCmd  cmd; // cmd.flags is a PBSysCanvasStrokeFlags value
    PBSysCanvasAABB bounds;
    f32             cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
    u64             strokeColor;     // wire color (see above)
    f32             strokeWidth;     // px
} PBSysCanvasCmdStrokeRect;

`PBSysCanvasCmdComplexRect`

typedef struct PBSysCanvasCmdComplexRect {
    PBSysCanvasCmd  cmd;
    PBSysCanvasAABB bounds;
    u64             fillColor;       // wire color (see above)
    f32             cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
    u64             strokeColor;     // wire color (see above)
    f32             strokeWidth;     // px
    u32             strokeFlags;     // 1=stroke_inside, 2=stroke_outside
    f32             blur;            // px
    f32             uvMinX, uvMinY;
    f32             uvMaxX, uvMaxY;
} PBSysCanvasCmdComplexRect;

`PBSysCanvasCmdGradientRect`

typedef struct PBSysCanvasCmdGradientRect {
    PBSysCanvasCmd  cmd; // flags bits 0..1: PBSysCanvasGradientSpace (OKLCH not allowed)
    PBSysCanvasAABB bounds;
    u64             fillColors[4];   // tl, tr, bl, br
    f32             cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
} PBSysCanvasCmdGradientRect;

`PBSysCanvasGradientKind`

typedef enum PBSysCanvasGradientKind PB_ENUM_TYPE(u16){
    PBSysCanvasGradientKind_LINEAR = 0, // p0 -> p1 is the ramp axis
    PBSysCanvasGradientKind_RADIAL = 1, // p0 = center, |p1 - p0| = the t=1 radius
    PBSysCanvasGradientKind_CONIC = 2,  // p0 = center, atan2(p1 - p0) = the t=0 angle
    PBSysCanvasGradientKind_MAX_ = PBSysCanvasGradientKind_CONIC,
} PBSysCanvasGradientKind;

`PBSysCanvasGradientSpace`

typedef enum PBSysCanvasGradientSpace PB_ENUM_TYPE(u16){
    PBSysCanvasGradientSpace_LINEAR_P3 = 0, // working space (cheapest)
    PBSysCanvasGradientSpace_OKLAB = 1,     // perceptual; CSS oklab behavior
    PBSysCanvasGradientSpace_OKLCH = 2,     // polar OKLab; hue-arc interpolation
    PBSysCanvasGradientSpace_MAX_ = PBSysCanvasGradientSpace_OKLCH,
} PBSysCanvasGradientSpace;

`PBSysCanvasGradientSpread`

typedef enum PBSysCanvasGradientSpread PB_ENUM_TYPE(u16){
    PBSysCanvasGradientSpread_PAD = 0,     // clamp to the edge stops
    PBSysCanvasGradientSpread_REPEAT = 1,  // fract(t)
    PBSysCanvasGradientSpread_REFLECT = 2, // triangle wave
    PBSysCanvasGradientSpread_MAX_ = PBSysCanvasGradientSpread_REFLECT,
} PBSysCanvasGradientSpread;

`PBSysCanvasGradientFlags`

typedef u32 PBSysCanvasGradientFlags;

GRADIENT cmd.flags. HUE_LONGER selects the longer hue arc between adjacent stops (OKLCH space only; default is the shorter arc).

`PBSysCanvasGradientStop`

typedef struct PBSysCanvasGradientStop {
    f32 offset;    // position along the ramp in [0, 1]; ascending, ties = hard stop
    u32 _reserved; // must be 0
    u64 color;     // wire color (see above)
} PBSysCanvasGradientStop;

`PBSysCanvasCmdGradient`

typedef struct PBSysCanvasCmdGradient {
    PBSysCanvasCmd          cmd; // cmd.flags is a PBSysCanvasGradientFlags value
    PBSysCanvasAABB         bounds;
    f32                     cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
    u16                     kind;            // PBSysCanvasGradientKind
    u16                     space;           // PBSysCanvasGradientSpace
    u16                     spread;          // PBSysCanvasGradientSpread
    u16                     stopCount;       // 2..16
    f32                     p0[2];           // see PBSysCanvasGradientKind
    f32                     p1[2];
    PBSysCanvasGradientStop stops[]; // stopCount entries
} PBSysCanvasCmdGradient;

`PBSysCanvasMeshPoint`

typedef struct PBSysCanvasMeshPoint {
    f32 x, y;      // local px, relative to bounds top-left, pre-transform
    f32 weight;    // per-point influence multiplier, finite and > 0 (1.0 = default)
    u32 _reserved; // must be 0
    u64 color;     // wire color (see above)
} PBSysCanvasMeshPoint;

`PBSysCanvasCmdMeshGradient`

typedef struct PBSysCanvasCmdMeshGradient {
    PBSysCanvasCmd       cmd; // flags must be 0
    PBSysCanvasAABB      bounds;
    f32                  cornerRadius[4]; // (tl, tr, br, bl) px; finite and >= 0
    u16                  space;           // PBSysCanvasGradientSpace (OKLCH not allowed)
    u16                  pointCount;      // 2..16
    f32                  falloff;         // IDW sharpness, clamped to [0.5, 8]; 2.0 = default look
    PBSysCanvasMeshPoint points[];        // pointCount entries
} PBSysCanvasCmdMeshGradient;

`PBSysCanvasCmdText`

typedef struct PBSysCanvasCmdText {
    PBSysCanvasCmd       cmd;
    PBSysCanvasAABB      bounds; // x1,y1 is text origin; x2,y2 reserved for future bounds use
    PBSysHandle          textPlan;
    PBSysCanvasTextFlags flags;
    u64                  fillColor; // wire color (see above)
} PBSysCanvasCmdText;

`PBSysCanvasCmdClipPush`

typedef struct PBSysCanvasCmdClipPush {
    PBSysCanvasCmd cmd;
    i32            x1, y1;
    i32            x2, y2;
} PBSysCanvasCmdClipPush;

`PBSysCanvasCmdClipPop`

typedef struct PBSysCanvasCmdClipPop {
    PBSysCanvasCmd cmd;
} PBSysCanvasCmdClipPop;

`PBSysCanvasCmdTextureSet`

typedef struct PBSysCanvasCmdTextureSet {
    PBSysCanvasCmd cmd;
    PBSysHandle    texture; // PBSysHandle_INVALID clears to default
    u32            _reserved;
} PBSysCanvasCmdTextureSet;

`PBSysCanvasCmdTransformPush`

typedef struct PBSysCanvasCmdTransformPush {
    PBSysCanvasCmd   cmd;
    PBSys2DTransform transform;
} PBSysCanvasCmdTransformPush;

`PBSysCanvasCmdTransformPop`

typedef struct PBSysCanvasCmdTransformPop {
    PBSysCanvasCmd cmd;
} PBSysCanvasCmdTransformPop;

`PBSysCanvasCmdGroupPush`

typedef struct PBSysCanvasCmdGroupPush {
    PBSysCanvasCmd cmd;        // cmd.flags must be 0
    u16            blendMode;  // PBSysCanvasBlendMode
    u16            _reserved;  // must be 0
    f32            opacity;    // 0..1
    f32            blur;       // gaussian blur radius in px, 0..100 (0 = none)
    u32            _reserved2; // must be 0
} PBSysCanvasCmdGroupPush;

`PBSysCanvasCmdGroupPop`

typedef struct PBSysCanvasCmdGroupPop {
    PBSysCanvasCmd cmd; // cmd.flags must be 0
} PBSysCanvasCmdGroupPop;

`PBSysCanvasMaskFlags`

typedef u32 PBSysCanvasMaskFlags;

PBSysCanvasMaskFlags select how mask coverage is computed from the mask's rendered pixels. Default (0) uses the alpha channel.

`PBSysCanvasCmdGroupMask`

typedef struct PBSysCanvasCmdGroupMask {
    PBSysCanvasCmd cmd; // cmd.flags is a PBSysCanvasMaskFlags value
} PBSysCanvasCmdGroupMask;

`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;

`PBSysGamepadButton`

typedef enum PBSysGamepadButton PB_ENUM_TYPE(u16){
    PBSysGamepadButton_A = 0,
    PBSysGamepadButton_B,
    PBSysGamepadButton_X,
    PBSysGamepadButton_Y,
    PBSysGamepadButton_LEFT_SHOULDER,
    PBSysGamepadButton_RIGHT_SHOULDER,
    PBSysGamepadButton_LEFT_TRIGGER,
    PBSysGamepadButton_RIGHT_TRIGGER,
    PBSysGamepadButton_LEFT_THUMBSTICK,
    PBSysGamepadButton_RIGHT_THUMBSTICK,
    PBSysGamepadButton_MENU,
    PBSysGamepadButton_OPTIONS,
    PBSysGamepadButton_HOME,
    PBSysGamepadButton_COUNT,
} PBSysGamepadButton;

`PBSysGamepadAxis`

typedef enum PBSysGamepadAxis PB_ENUM_TYPE(u16){
    PBSysGamepadAxis_LEFT_X = 0,   PBSysGamepadAxis_LEFT_Y,        PBSysGamepadAxis_RIGHT_X,
    PBSysGamepadAxis_RIGHT_Y,      PBSysGamepadAxis_DPAD_X,        PBSysGamepadAxis_DPAD_Y,
    PBSysGamepadAxis_LEFT_TRIGGER, PBSysGamepadAxis_RIGHT_TRIGGER, PBSysGamepadAxis_COUNT,
} PBSysGamepadAxis;

`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,

    // file panels
    PBSysEventType_FILE_PANEL_CLOSED,

    // gamepad
    PBSysEventType_GAMEPAD_CONNECTED,
    PBSysEventType_GAMEPAD_DISCONNECTED,
    PBSysEventType_GAMEPAD_BUTTON_DOWN,
    PBSysEventType_GAMEPAD_BUTTON_UP,
    PBSysEventType_GAMEPAD_AXIS_MOVE,

    // webgpu
    PBSysEventType_WGPU_CALLBACK,
} 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;

`PBSysFilePanelEvent`

typedef struct PBSysFilePanelEvent {
    PBSysEvent  event;
    PBSysHandle handle;
} PBSysFilePanelEvent;

`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;

`PBSysGamepadEvent`

typedef struct PBSysGamepadEvent {
    PBSysInputEvent inputEvent;
    u16 control; // PBSysGamepadButton for button events, PBSysGamepadAxis for axis events
    u16 flags;   // currently unused
    f32 value;   // scalar value for changed control
    f32 x;       // x axis for 2D controls, otherwise 0
    f32 y;       // y axis for 2D controls, otherwise 0
} PBSysGamepadEvent;

`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_TRUNCATE = 1 << 3, // truncate to length 0 (only valid with WRITE)

    PBSysFileOpenFlag_EXCLUSIVE = 1 << 6, // fail if file exists (only valid with CREATE)
    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_RW = PBSysFileMode_USER_RW << 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_RW = PBSysFileMode_GROUP_RW << 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_RW = PBSysFileMode_OTHER_RW << 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;

`PBSysGuiPresentation`

typedef i64 PBSysGuiPresentation;

`PBSysGuiPrefsFlags`

typedef u64 PBSysGuiPrefsFlags;

`PBSysGuiPrefs`

typedef struct {
    PBSysGuiPrefsFlags flags;
    u64                selectionColor; // wire color; i.e. background of text selection
    u64                accentColor;    // wire color; for things like macOS window controls
} PBSysGuiPrefs;

`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;

`PBSysHidDeviceType`

typedef enum PBSysHidDeviceType PB_ENUM_TYPE(u16){
    PBSysHidDeviceType_NONE,
    PBSysHidDeviceType_GAMEPAD,
} PBSysHidDeviceType;

`PBSysHidDeviceFlags`

typedef enum PBSysHidDeviceFlags PB_ENUM_TYPE(u32){
    PBSysHidDevice_HAS_PLAYER_INDEX = 1u << 0, // device can indicate a logical player number
    PBSysHidDevice_HAS_HAPTICS = 1u << 1,      // device supports haptic feedback
} PBSysHidDeviceFlags;

`PBSysHidHapticsLocality`

typedef enum PBSysHidHapticsLocality PB_ENUM_TYPE(u32){
    PBSysHidHaptics_DEFAULT = 1u << 0,      PBSysHidHaptics_ALL = 1u << 1,
    PBSysHidHaptics_HANDLES = 1u << 2,      PBSysHidHaptics_LEFT_HANDLE = 1u << 3,
    PBSysHidHaptics_RIGHT_HANDLE = 1u << 4, PBSysHidHaptics_TRIGGERS = 1u << 5,
    PBSysHidHaptics_LEFT_TRIGGER = 1u << 6, PBSysHidHaptics_RIGHT_TRIGGER = 1u << 7,
} PBSysHidHapticsLocality;

`PBSysHidDeviceInfo`

typedef struct PBSysHidDeviceInfo {
    PBSysHidDeviceType  type;
    PBSysHidDeviceFlags flags;
    u32                 gamepadAxisMask;     // PBSysGamepadAxis bits
    u32                 gamepadButtonMask;   // PBSysGamepadButton bits
    u32                 hapticsLocalityMask; // PBSysHidHapticsLocality bits
} PBSysHidDeviceInfo;

`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;

`PBSysNetTransportFlags`

typedef u32 PBSysNetTransportFlags;

`PBSysNetTransportConfig`

typedef struct PBSysNetTransportConfig {
    /*
    idleTimeoutMs determines how long a connection may stay idle without I/O happening, in milliseconds. Once a connection has been idle for idleTimeoutMs, it's closed (assuming keep-alive is disabled.) A timeout of `0` means "default."
    */
    u32 idleTimeoutMs;

    PBSysNetTransportFlags flags;

    /*
    alpn is "Application-Layer Protocol Negotiation" for TLS and QUIC. A semicolon-separated ALPN list, in priority order.
    Required to be non-zero for QUIC.
    Currently only one ALPN is supported.
    */
    const u8* nullable alpn;
    u32                alpnLen;

    // sni is "Server Name Indication" for TLS and QUIC
    const u8* nullable sni;
    u32                sniLen;

    // certPem is a PEM-encoded root certificate for TLS and QUIC peer verification
    const u8* nullable certPem;
    u32                certPemLen;
} PBSysNetTransportConfig;

`PBSysNetFeature`

typedef enum PBSysNetFeature PB_ENUM_TYPE(u64){
    PBSysNetFeature_TCP,  // PBSysNetTransportOpen supports "tcp:" URI
    PBSysNetFeature_UDP,  // PBSysNetTransportOpen supports "udp:" URI
    PBSysNetFeature_QUIC, // PBSysNetTransportOpen supports "quic:" URI
} PBSysNetFeature;

`PBSysNetTransportStreamFlags`

typedef u64 PBSysNetTransportStreamFlags;

PBSysNetTransportStreamFlags control behavior of PBSysNetTransportOpenStream

`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;

`PBTextPlanLayoutFlags`

typedef u32 PBTextPlanLayoutFlags;

`PBTextPlanLayoutFlag`

enum PBTextPlanLayoutFlag PB_ENUM_TYPE(PBTextPlanLayoutFlags){

    // PBTextPlanLayout_PREFORMATTED prevents trimming of trailing/leading/duplicate whitespace
    PBTextPlanLayout_PREFORMATTED = 1u << 0,

    // PBTextPlanLayout_ONE_LINE: Text is placed on a single line; newline characters are ignored
    PBTextPlanLayout_ONE_LINE = 1u << 1,

    /*
    PBTextPlanLayout_ALWAYS_SET_HEIGHT: The computed height (see PBSysTextplanGetSize) will be set to the height of the single line, even if the input text is an empty string.

    Implied by PBTextPlanLayout_ONE_LINE.
    */
    PBTextPlanLayout_ALWAYS_SET_HEIGHT = 1u << 2,

    PBTextPlanLayout_REPLACE_WITH_BULLETS = 1u << 3,
};

`PBSysTextureCreateFlags`

typedef u32 PBSysTextureCreateFlags;

`PBSysWindowSignals`

typedef enum PB_ENUM_TYPE(PBSysSignals) {
    // 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 finished 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,

    // PBSysWindowSignal_FULLSCREEN is active when the window is in full-screen mode
    PBSysWindowSignal_FULLSCREEN = 1u << 5,
} PBSysWindowSignals;

`PBSysThreadFeature`

typedef enum PBSysThreadFeature {
    PBSysThreadFeature_EXIT_MAIN, // can exit main thread (i.e. unavailable on Web)
    PBSysThreadFeature_START,     // can start threads
} PBSysThreadFeature;

`PBSysWindowFullScreenFlag`

typedef enum PB_ENUM_TYPE(PBSysWindowFullScreenFlags) {
    PBSysWindowFullScreenFlag_ENABLE = 1 << 0, // enable full-screen (absense means disabled)
} PBSysWindowFullScreenFlag;

`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;

`PBSysWindowOpenSurfaceCanvasFlag`

typedef enum PB_ENUM_TYPE(PBSysWindowOpenSurfaceCanvasFlags) {
    /*
    PBSysWindowOpenSurfaceCanvasFlag_WEBGPU opens the window surface canvas for direct guest WebGPU rendering.
    */
    PBSysWindowOpenSurfaceCanvasFlag_WEBGPU = 1 << 0,
} PBSysWindowOpenSurfaceCanvasFlag;

`PBSysWindowFullScreenFlags`

typedef u64 PBSysWindowFullScreenFlags;

`PBSysWindowSetRectFlags`

typedef u64 PBSysWindowSetRectFlags;

`PBSysWindowCreateTextureFlags`

typedef PBSysTextureCreateFlags PBSysWindowCreateTextureFlags;

PBSysWindowCreateTextureFlags is deprecated; use PBSysTextureCreateFlags

`PBSysWindowStyle`

typedef u64 PBSysWindowStyle;

`PBSysCursorStyleFlags`

typedef u64 PBSysCursorStyleFlags;

`PBSysCursorStyleFlag`

enum PBSysCursorStyleFlag PB_ENUM_TYPE(PBSysCursorStyleFlags){
    PBSysCursorStyleFlag_HIDDEN = 1 << 0,
};

`PBSysWindowRenderFlags`

typedef u64 PBSysWindowRenderFlags;

`PBSysWindowRenderFlag`

enum PBSysWindowRenderFlag PB_ENUM_TYPE(PBSysWindowRenderFlags){
    /*
    PBSysWindowRenderFlag_PRESENT_IMMEDIATE disables display- and/or OS compositor-synchronized rendering.

    In certain scenarios this can significantly reduce latency, for example when dragging a UI element on the screen where the OS mouse cursor would be ahead of the dragged element by a few frames.

    However, enabling this may lead to visual artifacts like "tearing" if you render outside of FRAME_SYNC signals, or if your rendering is taking too long during GPU framebuffer presentation/flip.
    */
    PBSysWindowRenderFlag_PRESENT_IMMEDIATE = 1 << 0,
};

`PBSysWindowOpenSurfaceCanvasFlags`

typedef u64 PBSysWindowOpenSurfaceCanvasFlags;

`PBSysCursorStyle`

typedef enum PBSysCursorStyle PB_ENUM_TYPE(uint16_t){
    PBSysCursorStyle_DEFAULT = 0,
    PBSysCursorStyle_ARROW = 1,
    PBSysCursorStyle_TEXT = 2,
    PBSysCursorStyle_TEXT_VERTICAL = 3,
    PBSysCursorStyle_POINTING_HAND = 4,
    PBSysCursorStyle_CLOSED_HAND = 5,
    PBSysCursorStyle_OPEN_HAND = 6,
    PBSysCursorStyle_RESIZE_N = 10,     // ↑ up
    PBSysCursorStyle_RESIZE_NE = 20,    // ↗ up right
    PBSysCursorStyle_RESIZE_E = 8,      // → right
    PBSysCursorStyle_RESIZE_SE = 21,    // ↘ down right
    PBSysCursorStyle_RESIZE_S = 11,     // ↓ down
    PBSysCursorStyle_RESIZE_SW = 22,    // ↙ down left
    PBSysCursorStyle_RESIZE_W = 7,      // ← left
    PBSysCursorStyle_RESIZE_NW = 23,    // ↖ up left
    PBSysCursorStyle_RESIZE_W_E = 9,    // ↔︎ left & right
    PBSysCursorStyle_RESIZE_N_S = 12,   // ↕︎ up & down
    PBSysCursorStyle_RESIZE_NE_SW = 24, // ⤢ up right & down left
    PBSysCursorStyle_RESIZE_NW_SE = 25, // ⤡ up left & down right
    PBSysCursorStyle_MOVE_N = 26,       // ↑ move a horizontal divider line upwards
    PBSysCursorStyle_MOVE_S = 27,       // ↓ move a horizontal divider line downwards
    PBSysCursorStyle_MOVE_N_S = 28,     // ↕︎ move a horizontal divider line up or down
    PBSysCursorStyle_MOVE_W = 29,       // ← move a vertical divider line leftwards
    PBSysCursorStyle_MOVE_E = 30,       // → move a vertical divider line rightwards
    PBSysCursorStyle_MOVE_W_E = 31,     // ↔︎ move a vertical divider line left or right
    PBSysCursorStyle_MOVE_N_S_W_E = 32, // + move two intersecting divider lines
    PBSysCursorStyle_CROSSHAIR = 13,
    PBSysCursorStyle_DISAPPEARING_ITEM = 14,
    PBSysCursorStyle_NOT_ALLOWED = 15,
    PBSysCursorStyle_DRAG_LINK = 16,
    PBSysCursorStyle_DRAG_COPY = 17,
    PBSysCursorStyle_CONTEXT_MENU = 18,
    PBSysCursorStyle_CUSTOM_IMAGE = 19,

    // deprecated names (August 2026, version 0.5)
    PBSysCursorStyle_RESIZE_LEFT = PBSysCursorStyle_RESIZE_W,
    PBSysCursorStyle_RESIZE_RIGHT = PBSysCursorStyle_RESIZE_E,
    PBSysCursorStyle_RESIZE_LEFT_RIGHT = PBSysCursorStyle_RESIZE_W_E,
    PBSysCursorStyle_RESIZE_UP = PBSysCursorStyle_RESIZE_N,
    PBSysCursorStyle_RESIZE_DOWN = PBSysCursorStyle_RESIZE_S,
    PBSysCursorStyle_RESIZE_UP_DOWN = PBSysCursorStyle_RESIZE_N_S,
} PBSysCursorStyle;

`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
    /*
    pxPerInch is the physical pixel density of the display the window is
    currently on (pixels per inch). 0 when unknown (e.g. web, or displays
    that do not report a physical size). 0 is reported rather than a guess
    so that measured density stays distinguishable from the fallback;
    PBWindowPxPerInch applies the documented fallback (96 * dpScale, the
    CSS reference density) for callers that just want a usable number.
    */
    f32              pxPerInch;
    PBSysWindowStyle style;
    PBSysTime        frameTime; // estimated presentation time of next frame
} PBSysWindowInfo;

`PBSysTextAttributeValueDecorationStyle`

typedef enum PBSysTextAttributeValueDecorationStyle PB_ENUM_TYPE(u32){
    PBSysTextAttributeValueDecorationStyle_OFF = 0u,
    PBSysTextAttributeValueDecorationStyle_SINGLE = 1u,
    PBSysTextAttributeValueDecorationStyle_DOUBLE = 2u,
    PBSysTextAttributeValueDecorationStyle_DOTTED = 3u,
    PBSysTextAttributeValueDecorationStyle_DASHED = 4u,
    PBSysTextAttributeValueDecorationStyle_DOT_DASH = 5u,
    PBSysTextAttributeValueDecorationStyle_WAVY = 6u,
    PBSysTextAttributeValueDecorationStyle_BELOW = 7u,
} PBSysTextAttributeValueDecorationStyle;

`PBSysTextAttributeValueNumerals`

typedef enum PBSysTextAttributeValueNumerals PB_ENUM_TYPE(u32){
    PBSysTextAttributeValueNumerals_LINING = 0u,
    PBSysTextAttributeValueNumerals_TABULAR = 1u,
    PBSysTextAttributeValueNumerals_OLD_STYLE = 2u,
} PBSysTextAttributeValueNumerals;

`PBSysTextAttributeValueBool`

typedef enum PBSysTextAttributeValueBool PB_ENUM_TYPE(u32){
    PBSysTextAttributeValueBool_OFF = 0u,
    PBSysTextAttributeValueBool_ON = 1u,
    PBSysTextAttributeValueBool_ON_NO_SYNTHESIS = 2u,
} PBSysTextAttributeValueBool;

`PBSysTextAttributeValueDecoration`

typedef struct PBSysTextAttributeValueDecoration {
    PBSysTextAttributeValueDecorationStyle style;
    u64                                    color;
} PBSysTextAttributeValueDecoration;

`PBSysTextAttributeValueFeature`

typedef struct PBSysTextAttributeValueFeature {
    u32 tag;
    u32 value;
} PBSysTextAttributeValueFeature;

`PBSysTextAttributeValueDirection`

typedef enum PBSysTextAttributeValueDirection PB_ENUM_TYPE(u32){
    PBSysTextAttributeValueDirection_DEFAULT = 0u,
} PBSysTextAttributeValueDirection;

`PBSysTextAttributeValueAlignment`

typedef enum PBSysTextAttributeValueAlignment PB_ENUM_TYPE(u32){
    PBSysTextAttributeValueAlignment_START = 0u,
    PBSysTextAttributeValueAlignment_END = 1u,
    PBSysTextAttributeValueAlignment_CENTER = 2u,
    PBSysTextAttributeValueAlignment_JUSTIFY = 3u,
} PBSysTextAttributeValueAlignment;

`PBSysTextAttributeType`

typedef enum PBSysTextAttributeType {
    PBSysTextAttribute_VARIABLE_AXIS = 1,       // see PBSysTextAttributeValueFeature feature
    PBSysTextAttribute_OTYPE_FEATURE = 2,       // see PBSysTextAttributeValueFeature feature
    PBSysTextAttribute_LIGATURES = 3,           // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_SUPERSCRIPT = 4,         // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_SUBSCRIPT = 5,           // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_SMALL_CAPS = 6,          // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_NUMERALS = 7,            // see PBSysTextAttributeValueNumerals numerals
    PBSysTextAttribute_KERNING = 8,             // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_ITALICS = 9,             // see PBSysTextAttributeValueBool b
    PBSysTextAttribute_UNDERLINE = 10,          // see PBSysTextAttributeValueDecoration decoration
    PBSysTextAttribute_STRIKE_THROUGH = 11,     // see PBSysTextAttributeValueDecoration decoration
    PBSysTextAttribute_FONT_FAMILY = 12,        // see u32 u
    PBSysTextAttribute_SIZE = 13,               // see f32 f
    PBSysTextAttribute_WEIGHT = 14,             // see f32 f
    PBSysTextAttribute_STRETCH = 15,            // see f32 f
    PBSysTextAttribute_CHARACTER_SPACING = 16,  // see f32 f
    PBSysTextAttribute_OUTLINE_THICKNESS = 17,  // see f32 f
    PBSysTextAttribute_COLOR = 18,              // see u64 color
    PBSysTextAttribute_OUTLINE_COLOR = 20,      // see u64 color
    PBSysTextAttribute_SHADOW_COLOR = 21,       // see u64 color
    PBSysTextAttribute_SHADOW_BLUR_RADIUS = 22, // see f32 f
    PBSysTextAttribute_SHADOW_OFFSET_X = 23,    // see f32 f
    PBSysTextAttribute_SHADOW_OFFSET_Y = 24,    // see f32 f
    PBSysTextAttribute_ALIGNMENT = 26,          // see PBSysTextAttributeValueAlignment alignment
    PBSysTextAttribute_DIRECTION = 27,          // see PBSysTextAttributeValueDirection direction
    PBSysTextAttribute_LINE_HEIGHT_MULTIPLIER = 31, // see f32 f
    PBSysTextAttribute_TAB_SIZE = 33,               // see f32 f
} PBSysTextAttributeType;

`PBSysTextAttribute`

typedef struct PBSysTextAttribute {
    PBSysTextAttributeType type;
    union {
        /*
        feature is used by PBSysTextAttribute_VARIABLE_AXIS, PBSysTextAttribute_OTYPE_FEATURE
        */
        PBSysTextAttributeValueFeature feature;

        /*
        b is used by PBSysTextAttribute_LIGATURES, PBSysTextAttribute_SUPERSCRIPT, PBSysTextAttribute_SUBSCRIPT, PBSysTextAttribute_SMALL_CAPS, PBSysTextAttribute_KERNING, PBSysTextAttribute_ITALICS
         */
        PBSysTextAttributeValueBool b;

        PBSysTextAttributeValueNumerals numerals; // used by PBSysTextAttribute_NUMERALS
        u32                             u;        // used by PBSysTextAttribute_FONT_FAMILY

        /*
        decoration is used by PBSysTextAttribute_UNDERLINE, PBSysTextAttribute_STRIKE_THROUGH
        */
        PBSysTextAttributeValueDecoration decoration;

        /*
        f is used by PBSysTextAttribute_SIZE, PBSysTextAttribute_WEIGHT, PBSysTextAttribute_STRETCH, PBSysTextAttribute_CHARACTER_SPACING, PBSysTextAttribute_OUTLINE_THICKNESS, PBSysTextAttribute_SHADOW_BLUR_RADIUS, PBSysTextAttribute_SHADOW_OFFSET_X, PBSysTextAttribute_SHADOW_OFFSET_Y, PBSysTextAttribute_LINE_HEIGHT_MULTIPLIER, PBSysTextAttribute_TAB_SIZE
        */
        f32 f;

        /*
        color is used by PBSysTextAttribute_COLOR, PBSysTextAttribute_OUTLINE_COLOR, PBSysTextAttribute_SHADOW_COLOR
        */
        u64 color;

        PBSysTextAttributeValueAlignment alignment; // used by PBSysTextAttribute_ALIGNMENT
        PBSysTextAttributeValueDirection direction; // used by PBSysTextAttribute_DIRECTION
    };
} PBSysTextAttribute;

`PBSysPositionedTextAttribute`

typedef struct PBSysPositionedTextAttribute {
    u32                start;
    PBSysTextAttribute attribute;
} PBSysPositionedTextAttribute;

`PBWindowWorkspaceOpenURLConfig`

typedef struct PBWindowWorkspaceOpenURLConfig {
    // Currently, no flags are defined.
    u32 flags;
} PBWindowWorkspaceOpenURLConfig;

`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_AudioBufferPlayAfter = 165,
    PBSysCallOp_AudioBufferUpload = 167,
    PBSysCallOp_AudioOutputInit = 122,
    PBSysCallOp_AudioSetVolume = 120,
    PBSysCallOp_AudioSoundGetPosition = 166,
    PBSysCallOp_AudioSoundIsPlaying = 168,
    PBSysCallOp_AudioSoundPlayback = 174,
    PBSysCallOp_AudioSoundSeek = 172,
    PBSysCallOp_AudioSoundTell = 173,
    PBSysCallOp_CanvasCreateTexture = 157,
    PBSysCallOp_CanvasCreateTextureFromData = 158,
    PBSysCallOp_CanvasOpen = 159,
    PBSysCallOp_CanvasRender = 155,
    PBSysCallOp_CanvasResize = 162,
    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_FilePanelGetResult = 143,
    PBSysCallOp_GuiPrefsGet = 170,
    PBSysCallOp_GuiPresentationGet = 135,
    PBSysCallOp_GuiPresentationSet = 136,
    PBSysCallOp_HandleClose = 70,
    PBSysCallOp_HandleDuplicate = 71,
    PBSysCallOp_HandleList = 77,
    PBSysCallOp_HidDeviceInfoGet = 150,
    PBSysCallOp_HidDeviceName = 149,
    PBSysCallOp_HidDeviceSetPlayerIndex = 148,
    PBSysCallOp_NetDecrypt = 131,
    PBSysCallOp_NetDecryptAsymmetric = 141,
    PBSysCallOp_NetEncrypt = 130,
    PBSysCallOp_NetEncryptAsymmetric = 142,
    PBSysCallOp_NetSessionOpen = 90,
    PBSysCallOp_NetTransportOpen = 132,
    PBSysCallOp_NetSessionId = 93,
    PBSysCallOp_NetSessionOpenStream = 91,
    PBSysCallOp_NetTransportOpenStream = 133,
    PBSysCallOp_NetTransportSetKeepAlive = 134,
    PBSysCallOp_ObjectFeatures = 153,
    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_TextureGetHeight = 145,
    PBSysCallOp_TextureGetWidth = 146,
    PBSysCallOp_TextureWrite = 106,
    PBSysCallOp_ThreadEnterMain = 59,
    PBSysCallOp_ThreadExit = 30,
    PBSysCallOp_ThreadExitProcess = 31,
    PBSysCallOp_ThreadExitStatus = 47,
    PBSysCallOp_ThreadHostControllerConnect = 79,
    PBSysCallOp_ThreadHostControllerRequest = 163,
    PBSysCallOp_ThreadLogWrite = 32,
    PBSysCallOp_ThreadNetConnect = 42,
    PBSysCallOp_ThreadRead = 76,
    PBSysCallOp_ThreadReadRandom = 139,
    PBSysCallOp_ThreadStart = 33,
    PBSysCallOp_ThreadWGpuOp = 160,
    PBSysCallOp_ThreadWGpuOpAsync = 161,
    PBSysCallOp_ThreadWindowCreate = 41,
    PBSysCallOp_ThreadWrite = 75,
    PBSysCallOp_WindowClipboardReadText = 107,
    PBSysCallOp_WindowClipboardWriteText = 108,
    PBSysCallOp_WindowCopyTitle = 126,
    PBSysCallOp_WindowCreateTexture = 109,
    PBSysCallOp_WindowCreateTextureFromData = 110,
    PBSysCallOp_WindowFilePanelCreate = 144,
    PBSysCallOp_WindowFrameSyncEnable = 63,
    PBSysCallOp_WindowFullScreenGet = 137,
    PBSysCallOp_WindowFullScreenSet = 138,
    PBSysCallOp_WindowInfoGet = 64,
    PBSysCallOp_WindowOpenSurfaceCanvas = 156,
    PBSysCallOp_WindowSetCursor = 151,
    PBSysCallOp_WindowSetRect = 87,
    PBSysCallOp_WindowSetRenderFlags = 152,
    PBSysCallOp_WindowSetStyle = 127,
    PBSysCallOp_WindowSetTitle = 80,
    PBSysCallOp_WindowSizeLimitsSet = 128,
    PBSysCallOp_WindowTextplanCreate = 36,
    PBSysCallOp_WindowTextplanCreate2 = 154,
    PBSysCallOp_WindowWorkspaceOpenURL = 171,
    PBSysCallOp_READ = 9,               // 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.

`PBSysThreadEntry`

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

PBSysThreadEntry

`PBSysGuiSignals`

typedef enum PB_ENUM_TYPE(PBSysSignals) {
    // PBSysGuiSignal_PRESENTATION is pulsed when the application's presentation flags changes
    PBSysGuiSignal_PRESENTATION = 1u << 0, // pulse

    // PBSysGuiSignal_PREFS is pulsed when the system UI preferences change.
    // Read the current preferences with PBSysGuiPrefsGet.
    PBSysGuiSignal_PREFS = 1u << 1, // pulse
} PBSysGuiSignals;

`PBSysNetTransportSignals`

typedef enum PB_ENUM_TYPE(PBSysSignals) {
    PBSysNetTransportSignal_READY = 1u << 0,  // connection is established and active
    PBSysNetTransportSignal_CLOSED = 1u << 1, // connection is closed
} PBSysNetTransportSignals;

`PBSysNetSessionSignals`

typedef enum PB_ENUM_TYPE(PBSysSignals) {
    /*
    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.)

`PBSysAudioSoundPlaybackFlags`

typedef enum PB_ENUM_TYPE(u64) {
    PBSysAudioSoundPlaybackFlag_RESUME = 1 << 0,      // resume (instead of pause)
    PBSysAudioSoundPlaybackFlag_RESUME_LOOP = 1 << 1, // restart playback when end is reached
} PBSysAudioSoundPlaybackFlags;

`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;

`PBSysNetTransportFlag`

typedef enum PB_ENUM_TYPE(PBSysNetTransportFlags) {
    PBSysNetTransportFlag_TLS = 1u << 0, // enable TLS (DTLS for UDP)
} PBSysNetTransportFlag;

BEGIN generated code

`PBSysNetTransportStreamFlag`

typedef enum PB_ENUM_TYPE(PBSysNetTransportStreamFlags) {
    PBSysNetTransportStream_READ = 1u << 0,  // create a stream that can be read from
    PBSysNetTransportStream_WRITE = 1u << 1, // create a stream that can be written to
    PBSysNetTransportStream_RW = PBSysNetTransportStream_READ | PBSysNetTransportStream_WRITE,

    /*
    PBSysNetTransportStream_UNRELIABLE requests an unreliable stream. For QUIC this maps to QUIC DATAGRAM frames, where each write sends one datagram and each read receives one datagram. The flag is ignored for inherently unreliable protocols like UDP. Setting this flag for TCP causes PBSysNetTransportOpenStream to fail with PBSysErr_NOT_SUPPORTED.
    */
    PBSysNetTransportStream_UNRELIABLE = 1u << 2,
} PBSysNetTransportStreamFlag;

BEGIN generated code

`PBSysGuiPresentationFlag`

typedef enum PB_ENUM_TYPE(PBSysGuiPresentation) {
    PBSysGuiPresentation_DEFAULT = 0,
    PBSysGuiPresentation_HIDE_DOCK = 1 << 1,                 // dock is disabled
    PBSysGuiPresentation_AUTOHIDE_MENU_BAR = 1 << 2,         // Menu bar appears when moused to
    PBSysGuiPresentation_HIDE_MENU_BAR = 1 << 3,             // Menu bar is disabled
    PBSysGuiPresentation_DISABLE_PROCESS_SWITCHING = 1 << 4, // Cmd+Tab UI is disabled
    PBSysGuiPresentation_DISABLE_FORCE_QUIT = 1 << 5,        // Cmd+Tab UI is disabled
    PBSysGuiPresentation_DISABLE_LOGOUT = 1 << 6,            // Restart/Shut Down/Log Out disabled
    PBSysGuiPresentation_DISABLE_CURSOR_HIGHLIGHT = 1 << 7,  // disable "Shake mouse to locate"
    PBSysGuiPresentation_FULLSCREEN = 1 << 8, // app is in full-screen mode (read only flag)

    PBSysGuiPresentation_KIOSK =
        PBSysGuiPresentation_HIDE_DOCK | PBSysGuiPresentation_HIDE_MENU_BAR
        | PBSysGuiPresentation_DISABLE_PROCESS_SWITCHING | PBSysGuiPresentation_DISABLE_FORCE_QUIT
        | PBSysGuiPresentation_DISABLE_LOGOUT,
} PBSysGuiPresentationFlag;

`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_BY_HANDLE = 4,      // predicate is of type PBSysHandle
} PBSysHandleListFilter;

`PBSysGuiPrefsFlag`

typedef enum PB_ENUM_TYPE(PBSysGuiPrefsFlags) {
    PBSysGuiPrefsFlag_BRIGHT = 1u << 0,
    PBSysGuiPrefsFlag_DARK = 1u << 1,
    PBSysGuiPrefsFlag_HIGH_CONTRAST = 1u << 2,
    PBSysGuiPrefsFlag_AUTOHIDE_SCROLLBARS = 1u << 3, // scrollbars visible only when scrolling
} PBSysGuiPrefsFlag;

`PBSysCanvasTextFlags`

typedef enum PB_ENUM_TYPE(u32) {
    PBSysCanvasTextFlag_OVERRIDE_COLOR = 1u << 0,
} PBSysCanvasTextFlags;

Constants

Name	Type	Value	Description
`PBSysCanvasGradientFlag_HUE_LONGER`	`PBSysCanvasGradientFlags`	`1`
`PBSysCanvasMaskFlag_INVERT`	`PBSysCanvasMaskFlags`	`2`	coverage = 1 - coverage (cutouts). Note: an inverted mask does not
tighten the group's bounds.
`PBSysCanvasMaskFlag_LUMINANCE`	`PBSysCanvasMaskFlags`	`1`	coverage from the luminance of the mask's color (times alpha) instead
of alpha alone: white reveals, black hides
`PBSysCanvasStrokeFlag_INSIDE`	`PBSysCanvasStrokeFlags`	`1`
`PBSysCanvasStrokeFlag_OUTSIDE`	`PBSysCanvasStrokeFlags`	`2`
`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`	`PBSysSignals`	`4294967295`
`PBSysSignal_SYSTEM_ALL`	`PBSysSignals`	`16777215`
`PBSysSignal_USER_0`	`PBSysSignals`	`16777216`
`PBSysSignal_USER_1`	`PBSysSignals`	`33554432`
`PBSysSignal_USER_2`	`PBSysSignals`	`67108864`
`PBSysSignal_USER_3`	`PBSysSignals`	`134217728`
`PBSysSignal_USER_4`	`PBSysSignals`	`268435456`
`PBSysSignal_USER_5`	`PBSysSignals`	`536870912`
`PBSysSignal_USER_6`	`PBSysSignals`	`1073741824`
`PBSysSignal_USER_7`	`PBSysSignals`	`2147483648`
`PBSysSignal_USER_ALL`	`PBSysSignals`	`4278190080`
`PBSysTextplanSelectionAdjustment_ALL_GRANULARITY`	`u32`	`4`
`PBSysTextplanSelectionAdjustment_BACKWARDS`	`u32`	`8`
`PBSysTextplanSelectionAdjustment_DELETE_AFTERWARDS`	`u32`	`64`
`PBSysTextplanSelectionAdjustment_IN_LINE_GRANULARITY`	`u32`	`32`
`PBSysTextplanSelectionAdjustment_LINE_ENDS_GRANULARITY`	`u32`	`128`
`PBSysTextplanSelectionAdjustment_LINE_GRANULARITY`	`u32`	`2`
`PBSysTextplanSelectionAdjustment_MAKE_SELECTION`	`u32`	`16`
`PBSysTextplanSelectionAdjustment_TO_MOUSE_RIGHT_CLICK`	`u32`	`2147483648`
`PBSysTextplanSelectionAdjustment_WORD_GRANULARITY`	`u32`	`1`
`PBSysTextureCreateFlag_NEAREST`	`PBSysTextureCreateFlags`	`2`	nearest-neighbor filtering (default: linear)
`PBSysTextureCreateFlag_RENDER_ATTACHMENT`	`PBSysTextureCreateFlags`	`16`	texture can be rendered to
`PBSysTextureCreateFlag_STREAMING`	`PBSysTextureCreateFlags`	`1`	hint: texture will be updated frequently
`PBSysTextureCreateFlag_WRAP_U`	`PBSysTextureCreateFlags`	`4`	repeat along U axis (default: clamp)
`PBSysTextureCreateFlag_WRAP_V`	`PBSysTextureCreateFlags`	`8`	repeat along V axis (default: clamp)
`PBSysWindowCreateTextureFlag_NEAREST`	`PBSysWindowCreateTextureFlags`	`2`
`PBSysWindowCreateTextureFlag_RENDER_ATTACHMENT`	`PBSysWindowCreateTextureFlags`	`16`
`PBSysWindowCreateTextureFlag_STREAMING`	`PBSysWindowCreateTextureFlags`	`1`
`PBSysWindowCreateTextureFlag_WRAP_U`	`PBSysWindowCreateTextureFlags`	`4`
`PBSysWindowCreateTextureFlag_WRAP_V`	`PBSysWindowCreateTextureFlags`	`8`
`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 };

`PB_DEPRECATED`

macro void PB_DEPRECATED(const char* message [,const char* replacement])

marks a symbol as deprecated

`PB_DEPRECATED_REPLACED_BY`

macro void PB_DEPRECATED_REPLACED_BY(ID newName)

marks a symbol as deprecated, replaced by a symbol with name newName

Functions

`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: PBSysRight_WRITE

`PBSysAudioSetVolume`

void PBSysAudioSetVolume(PBSysHandle audio,
                         f32         volume);

PBSysAudioSetVolume sets the global volume of the sound mixer.

volume: Normalized value in the range [0.0–1.0] (0–100%)
Required rights: PBSysRight_WRITE

`PBSysAudioBufferCreate`

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

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

Required rights: PBSysRight_WRITE

`PBSysAudioBufferCreateFromFile`

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

PBSysAudioBufferCreateFromFile 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.

flags: Unused. Pass 0.
Required rights: PBSysRight_WRITE

`PBSysAudioBufferDestroy`

PBSysErr PBSysAudioBufferDestroy(PBSysHandle      audio,
                                 PBSysAudioBuffer buffer);

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

Required rights: PBSysRight_WRITE

`PBSysAudioBufferPlay`

PBSysAudioSound PBSysAudioBufferPlay(PBSysHandle      audio,
                                     PBSysAudioBuffer buffer,
                                     u64              flags);

PBSysAudioBufferPlay starts playing an instance of an audio buffer.

buffer: The buffer to play
flags: Unused. Pass 0.
Returns: the handle to the playing sound in the sound mixer.
Required rights: PBSysRight_WRITE

`PBSysAudioBufferPlayAfter`

PBSysAudioSound PBSysAudioBufferPlayAfter(PBSysHandle      audio,
                                          PBSysAudioBuffer buffer,
                                          PBSysAudioSound  playingSound);

PBSysAudioBufferPlayAfter creates a new sound from buffer, like PBSysAudioBufferPlay, but instead of starting it right away, schedules it to start playing seamlessly (gaplessly) the moment playingSound finishes. Callers can chain further buffers onto the sound this returns to keep streaming audio as a sequence of small buffers rendered just-in-time.

If playingSound isnt currently playing (e.g. it already finished), theres nothing to wait for, so the new sound starts playing immediately instead.

Returns: the handle to the (possibly not yet started) sound in the sound mixer.
Required rights: PBSysRight_WRITE

`PBSysAudioBufferUpload`

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

PBSysAudioBufferUpload replaces the sample data of an existing, no-longer-playing audio buffer in place, without allocating a new buffer or sound-mixer slot. Intended for a small fixed ring of buffers used to stream audio, where each buffer is refilled and re-queued (via PBSysAudioBufferPlayAfter) only after PBSysAudioSoundIsPlaying reports its previous sound has finished.

It is a caller error to upload into a buffer that a currently-playing (or not-yet-finished, queued) sound still references.

Required rights: PBSysRight_WRITE

`PBSysAudioSoundPlayback`

PBSysErr PBSysAudioSoundPlayback(PBSysHandle                  audio,
                                 PBSysAudioSound              sound,
                                 f32                          speed,
                                 PBSysAudioSoundPlaybackFlags flags);

PBSysAudioSoundPlayback controls playback of a sound.

PBSysAudioSoundPlayback( … , PBSysAudioSoundPlaybackFlag_RESUME) resumes playback; stops playing when end of sound is reached.
PBSysAudioSoundPlayback( … , PBSysAudioSoundPlaybackFlag_RESUME_LOOP) resumes playback, loop around and restarts playback when end of sound is reached.
PBSysAudioSoundPlayback( … , 0) pauses playback.
speed: Playback speed. (1.0 = 1x, 2.0 = 2x and so on.) Currently only 1.0 is supported.
flags: Set to 0 to pause playback.
Required rights: PBSysRight_WRITE

`PBSysAudioSoundTell`

f32 PBSysAudioSoundTell(PBSysHandle     audio,
                        PBSysAudioSound sound,
                        u64             flags);

PBSysAudioSoundTell returns the current playback position.

flags: Unused. Pass 0.
Returns: Normalized playback position ([0.0–1.0]), i.e. 0.0 = not started, 1.0 = ended. Returns <0.0 if audio handle does not have PBSysRight_READ rights.
Required rights: PBSysRight_READ

`PBSysAudioSoundSeek`

PBSysErr PBSysAudioSoundSeek(PBSysHandle     audio,
                             PBSysAudioSound sound,
                             f32             position,
                             u64             flags);

PBSysAudioSoundSeek changes the playback position.

position: Normalized position to seek to, clamped to [0.0–1.0].
flags: Unused. Pass 0.
Required rights: PBSysRight_WRITE

`PBSysAudioSoundGetPosition`

u64 PBSysAudioSoundGetPosition(PBSysHandle     audio,
                               PBSysAudioSound sound);

PBSysAudioSoundGetPosition returns the current playback position, in sample frames, of sound within its buffer. This reflects what the mixer has actually consumed as of the last audio callback, i.e. what's truly audible right now -- not merely queued or rendered ahead of time.

Returns 0 if sound is invalid or hasn't started playing yet.

Required rights: PBSysRight_READ

`PBSysAudioSoundIsPlaying`

bool PBSysAudioSoundIsPlaying(PBSysHandle     audio,
                              PBSysAudioSound sound);

PBSysAudioSoundIsPlaying returns true if sound is the one currently being mixed into the output right now, according to the mixer itself -- not a locally-predicted end time. A sound that hasn't started yet (waiting on a PBSysAudioBufferPlayAfter predecessor) or that has already finished playing both report false.

Intended for driving gapless streaming playback: poll this instead of guessing when a queued buffer will finish, and recycle/refill it (see PBSysAudioBufferUpload) once it reports false.

Required rights: PBSysRight_READ

`PBSysCanvasOpen`

PBSysHandle PBSysCanvasOpen(u32 widthInPx,
                            u32 heightInPx,
                            u64 flags);

PBSysCanvasOpen creates a fixed-size offscreen canvas.

The returned canvas can be rendered to with PBSysCanvasRender and composited into another canvas with PBSysCanvasCmdTextureSet.

widthInPx: horizontal size in pixels
heightInPx: vertical size in pixels
flags: Unused. Pass 0
Required rights: none

`PBSysCanvasResize`

PBSysErr PBSysCanvasResize(PBSysHandle canvas,
                           u32         widthInPx,
                           u32         heightInPx,
                           u64         flags);

PBSysCanvasResize changes the size of an offscreen canvas.

Previous canvas contents are discarded. Render again after resizing.

canvas: offscreen canvas to resize
widthInPx: new horizontal size in pixels
heightInPx: new vertical size in pixels
flags: Unused. Pass 0
Required rights: PBSysRight_WRITE

`PBSysCanvasCreateTexture`

PBSysHandle PBSysCanvasCreateTexture(PBSysHandle             canvas,
                                     PBSysTextureFormat      format,
                                     u32                     widthInPx,
                                     u32                     heightInPx,
                                     PBSysTextureCreateFlags flags);

PBSysCanvasCreateTexture creates a GPU texture associated with a canvas. The texture can be uploaded to via PBSysTextureWrite and set as the active texture with PBSysCanvasCmdTextureSet.

format: pixel format
widthInPx: texture width in pixels
heightInPx: texture height in pixels
flags: PBSysTextureCreateFlags
Required rights: none

`PBSysCanvasCreateTextureFromData`

PBSysHandle PBSysCanvasCreateTextureFromData(PBSysHandle             canvas,
                                             PBSysTextureFormat      format,
                                             const void*             data,
                                             u64                     dataSize,
                                             PBSysTextureCreateFlags flags);

PBSysCanvasCreateTextureFromData decodes image data and creates a GPU texture in one step. Supported encoded formats include PNG, JPEG, WebP, GIF, BMP, and TGA.

format: destination pixel format
data: encoded image bytes
dataSize: size of data in bytes
flags: PBSysTextureCreateFlags
Required rights: none

`PBSysCanvasRender`

PBSysErr PBSysCanvasRender(PBSysHandle           canvas,
                           u64                   backgroundColor,
                           const PBSysCanvasCmd* cmds,
                           u32                   cmdsSize,
                           u64                   flags);

PBSysCanvasRender submits renderer commands to a canvas

canvas: to render to
backgroundColor: clears the canvas before rendering; wire color format
cmds: command queue
cmdsSize: size in bytes of cmds
flags: Unused. Pass 0.
Required rights: PBSysRight_WRITE

`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

`PBSysFilePanelGetResult`

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

PBSysFilePanelGetResult reads the selected file path from the file panel. Zero is returned if the panel was canceled.

Required rights: PBSysRight_READ

`PBSysGuiPresentationGet`

PBSysGuiPresentation PBSysGuiPresentationGet(PBSysHandle gui);

PBSysGuiPresentationGet reads the app's current presentation configuration

Returns: Flags as a positive integer or PBSysErr_ACCESS_DENIED
Required rights: PBSysRight_READ

`PBSysGuiPresentationSet`

PBSysGuiPresentation PBSysGuiPresentationSet(PBSysHandle          gui,
                                             PBSysGuiPresentation flags);

PBSysGuiPresentationSet configures the app's presentation

Returns: previous value as a positive integer or PBSysErr_ACCESS_DENIED
Required rights: PBSysRight_WRITE

`PBSysGuiPrefsGet`

PBSysErr PBSysGuiPrefsGet(PBSysHandle    gui,
                          PBSysGuiPrefs* config,
                          u32            configSize);

PBSysGuiPrefsGet reads the current system UI preferences (e.g. dark mode, high contrast etc.)

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

`PBSysHidDeviceSetPlayerIndex`

PBSysErr PBSysHidDeviceSetPlayerIndex(PBSysHandle hid,
                                      u32         deviceId,
                                      u32         playerIndex,
                                      u32         flags);

PBSysHidDeviceSetPlayerIndex assigns a logical player number to an HID device. On devices with player indicators, this may update the matching indicator.

deviceId: HID device to assign the player index to
playerIndex: 0 for "unset", 1, 2, 3 or 4 for player 1, 2, 3 or 4
flags: Unused. Pass 0
Required rights: PBSysRight_WRITE

`PBSysHidDeviceName`

i32 PBSysHidDeviceName(PBSysHandle hid,
                       u32         deviceId,
                       u8*         buf,
                       u32         bufCap,
                       u32         flags);

PBSysHidDeviceName retrieves a human-readable name describing a device, as UTF-8 text.

deviceId: HID device to read name of
buf: storage for name
bufCap: size of buf, in bytes
flags: Unused. Pass 0
Returns: Number of bytes that would have been copied into buf as if bufCap was infinitely large, or PBSysErr as a negative value on error
Required rights: PBSysRight_READ

`PBSysHidDeviceInfoGet`

PBSysErr PBSysHidDeviceInfoGet(PBSysHandle         hid,
                               u32                 deviceId,
                               PBSysHidDeviceInfo* info,
                               u32                 infoSize,
                               u32                 flags);

PBSysHidDeviceInfoGet retrieves general information about a device.

deviceId: HID device to query
info: result storage
infoSize: size of PBSysHidDeviceInfo, for ABI compatibility
flags: Unused. Pass 0
Required rights: PBSysRight_READ

`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

`PBSysNetTransportOpen`

PBSysHandle PBSysNetTransportOpen(PBSysHandle                    net,
                                  const u8*                      uri,
                                  u32                            uriLen,
                                  const PBSysNetTransportConfig* config,
                                  u32                            configSize);

PBSysNetTransportOpen opens a connection to a network endpoint.

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

quic:host:port QUIC transport tcp:host:port TCP/IP socket udp:host:port UDP/IP socket

The underlying implementation may not support the requested protocol.

The object to which a handle is returned will have its PBSysNetTransportSignal_READY 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 NetTransport 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

`PBSysNetEncrypt`

PBSysErr PBSysNetEncrypt(PBSysHandle net,
                         const u8*   inBuf,
                         u32         inBufLen,
                         const u8*   keyBuf,
                         u32         keyBufLen,
                         u8*         outBuf,
                         u32         outBufLen);

Private API.

Required rights: none

`PBSysNetDecrypt`

PBSysErr PBSysNetDecrypt(PBSysHandle net,
                         const u8*   inBuf,
                         u32         inBufLen,
                         const u8*   keyBuf,
                         u32         keyBufLen,
                         u8*         outBuf,
                         u32         outBufLen);

Private API.

Required rights: none

`PBSysNetEncryptAsymmetric`

PBSysErr PBSysNetEncryptAsymmetric(PBSysHandle net,
                                   const u8*   inBuf,
                                   u32         inBufLen,
                                   const u8*   publicKeyBuf,
                                   u32         publicKeyBufLen,
                                   u8*         outBuf,
                                   u32         outBufLen);

Private API.

Required rights: none

`PBSysNetDecryptAsymmetric`

PBSysErr PBSysNetDecryptAsymmetric(PBSysHandle net,
                                   const u8*   inBuf,
                                   u32         inBufLen,
                                   const u8*   privateKeyBuf,
                                   u32         privateKeyBufLen,
                                   u8*         outBuf,
                                   u32         outBufLen);

Private API.

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

`PBSysNetTransportOpenStream`

PBSysHandle PBSysNetTransportOpenStream(PBSysHandle                  netTransport,
                                        PBSysNetTransportStreamFlags flags);

PBSysNetTransportOpenStream opens a stream within a network transport.

The returned stream will have its PBSysStreamSignal_WRITABLE activated when the connection has been established and the stream is ready. If PBSysNetTransportStream_WRITE is not present in flags, PBSysStreamSignal_WRITABLE will never become active. For QUIC, PBSysNetTransportStream_WRITE without PBSysNetTransportStream_READ opens a locally initiated unidirectional stream. QUIC READ-only streams are not currently supported.

netTransport: Network transport, handle to a NetTransport object
flags: PBSysNetTransportStreamFlags
Returns: Handle to a Stream object, or PBSysErr (negative value) on error.
Required rights: PBSysRight_WRITE

`PBSysNetTransportSetKeepAlive`

PBSysErr PBSysNetTransportSetKeepAlive(PBSysHandle netTransport,
                                       i64         intervalNsec);

PBSysNetTransportSetKeepAlive configures a transport's keep-alive interval. When keep-alive is enabled, a transport stays open even across long periods of no I/O. When keep-alive is disabled, a transport connection closes after idleTimeoutMs (as configured by PBSysNetTransportConfig.)

Setting intervalNsec to a negative value means "enable keep-alive with implemention-default interval" while setting intervalNsec to 0 means "disable keep-alive."

Keep-alive is disabled by default.

intervalNsec: How long between keep-alive pings in nanoseconds.
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 PBSysSignalEvent 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

`PBSysObjectFeatures`

u64 PBSysObjectFeatures(PBSysHandle handle);

PBSysObjectFeatures returns a bitmap of features available for the object referred to by handle.

The bit positions in the resulting bitmap is object-type dependant.

Returns: bitmap of available features
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,
                        PBTextPlanLayoutFlags flags,
                        i32                   width,
                        i32                   height);

PBSysTextplanLayout lays a text document into a rectangular bounding box.

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.

textPlan: The text plan to contain the resulting layout.
flags: Flags bitwise OR-ed together controlling the text layout operation.
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.
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, 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 * bytes per pixel)
widthInPx: width of the upload region
heightInPx: height of the upload region
Required rights: PBSysRight_WRITE

`PBSysTextureGetWidth`

u32 PBSysTextureGetWidth(PBSysHandle texture);

PBSysTextureGetWidth returns the width of a texture, in pixels.

Required rights: PBSysRight_READ

`PBSysTextureGetHeight`

u32 PBSysTextureGetHeight(PBSysHandle texture);

PBSysTextureGetWidth returns the height of a texture, in pixels.

Required rights: PBSysRight_READ

`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 one log message 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

`PBSysThreadHostControllerRequest`

i64 PBSysThreadHostControllerRequest(PBSysHandle thread,
                                     const u8*   buf,
                                     u32         bufLen);

Note: Draft API; arguments will change

Required rights: none

`PBSysThreadReadRandom`

PBSysErr PBSysThreadReadRandom(PBSysHandle thread,
                               u8*         buf,
                               u32         bufLen);

PBSysThreadReadRandom gets high-quality random bytes.

buf: The output buffer.
bufLen: Size in bytes of buf. Must be no more than 100 bytes.
Required rights: none

`PBSysThreadWGpuOp`

i64 PBSysThreadWGpuOp(PBSysWgpuOp op,
                      const void* inPtr,
                      usize       inPtrSize,
                      void*       outPtr,
                      usize       outPtrSize);

PBSysThreadWGpuOp issues a WebGPU operation on the calling thread

Required rights: none

`PBSysThreadWGpuOpAsync`

i64 PBSysThreadWGpuOpAsync(PBSysWgpuOp op,
                           const void* inPtr,
                           usize       inPtrSize,
                           void*       outPtr,
                           usize       outPtrSize);

PBSysThreadWGpuOpAsync issues a WebGPU operation on the calling thread that may need to suspend on web runtimes.

Required rights: none

`PBSysWindowCreateTexture`

PBSysHandle PBSysWindowCreateTexture(PBSysHandle             window,
                                     PBSysTextureFormat      format,
                                     u32                     widthInPx,
                                     u32                     heightInPx,
                                     PBSysTextureCreateFlags 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.

DEPRECATED Use PBSysCanvasCreateTexture instead

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

`PBSysWindowCreateTextureFromData`

PBSysHandle PBSysWindowCreateTextureFromData(PBSysHandle             window,
                                             PBSysTextureFormat      format,
                                             const void*             data,
                                             u64                     dataSize,
                                             PBSysTextureCreateFlags 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.

DEPRECATED Use PBSysCanvasCreateTextureFromData instead

data: pointer to encoded image bytes (e.g. a PNG file loaded into memory)
dataSize: number of bytes at data
flags: PBSysTextureCreateFlags
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.

Programs must render their initial frame explicitly (with PBSysCanvasRender), not in response to a FRAME_SYNC signal: a window is only revealed after its first frame has been rendered, and the platform's frame-sync driver may not deliver signals for a window that has not been revealed yet. After the first frame, FRAME_SYNC signals pace subsequent frames.

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

`PBSysWindowSetRenderFlags`

PBSysErr PBSysWindowSetRenderFlags(PBSysHandle            window,
                                   PBSysWindowRenderFlags flags);

PBSysWindowSetRenderFlags controls behavior of window rendering.

Required rights: PBSysRight_WRITE

`PBSysWindowOpenSurfaceCanvas`

PBSysHandle PBSysWindowOpenSurfaceCanvas(PBSysHandle                       window,
                                         PBSysWindowOpenSurfaceCanvasFlags flags);

PBSysWindowOpenSurfaceCanvas returns a handle to the canvas for a window's drawable surface.

The rights given to the returned canvas handle depends on the rights of the window handle; if the window handle only has READ rights, then the returned handle also only has READ rights.

flags: Pass 0 to use the default Playbit canvas renderer. Pass PBSysWindowOpenSurfaceCanvasFlag_WEBGPU to use the canvas as a WebGPU surface source. These modes are exclusive.
Required rights: PBSysRight_READ

`PBSysWindowTextplanCreate2`

PBSysHandle PBSysWindowTextplanCreate2(PBSysHandle                         window,
                                       const u8*                           text,
                                       u64                                 textSize,
                                       const PBSysPositionedTextAttribute* attributes,
                                       u32                                 attributeSize,
                                       u32                                 attributesLen);

PBSysWindowTextplanCreate2 creates a text plan object associated with a window. The styling attributes are specified as an array.

text: encoded as UTF-8 data
textSize: size in bytes of text
attributes: attributes. Must not be NULL
attributeSize: size of one PBSysPositionedTextAttribute, for ABI compatibility
attributesLen: number of attributes at attributes. Must be at least 1.
Required rights: PBSysRight_WRITE

`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.

DEPRECATED Use PBSysWindowTextplanCreate2 instead

fontFamily: 0 = sans, 1 = mono
size: fixed point; 1.0 = 64
weight: between 1 and 999
color: 0xRRGGBBAA
Required rights: PBSysRight_WRITE

`PBSysWindowFilePanelCreate`

PBSysHandle PBSysWindowFilePanelCreate(PBSysHandle window,
                                       bool        save);

PBSysWindowFilePanelCreate shows a file panel to the user.

save: True for a save-file panel, false for an open-file panel.
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

`PBSysWindowWorkspaceOpenURL`

PBSysErr PBSysWindowWorkspaceOpenURL(PBSysHandle                           window,
                                     const u8*                             url,
                                     u64                                   urlSize,
                                     const PBWindowWorkspaceOpenURLConfig* config,
                                     u64                                   configSize);

PBSysWindowWorkspaceOpenURL opens a URL in user's workspace with the provided configuration settings. By default, the default application will be launched or activated to open the URL.

Required rights: PBSysRight_READ

`PBSysWindowFullScreenGet`

PBSysWindowFullScreenFlags PBSysWindowFullScreenGet(PBSysHandle window);

PBSysWindowFullScreenGet returns the current full-screen state of a window

Required rights: PBSysRight_READ

`PBSysWindowFullScreenSet`

PBSysErr PBSysWindowFullScreenSet(PBSysHandle                window,
                                  PBSysWindowFullScreenFlags flags);

PBSysWindowFullScreenGet configures full-screen state of a window

Required rights: PBSysRight_WRITE

`PBSysWindowSetCursor`

PBSysErr PBSysWindowSetCursor(PBSysHandle           window,
                              PBSysCursorStyle      style,
                              PBSysHandle           image,
                              PBSysCursorStyleFlags flags);

PBSysWindowSetCursor sets the appearance of the mouse cursor.

style: determines how the cursor is presented.
image: should be the handle of an image if style is PBSysCursorStyle_CUSTOM_IMAGE, otherwise the image parameter is ignored and should be 0.
Required rights: PBSysRight_WRITE