# Runtime API reference Access the runtime API with `#include ` This reference is also available in [markdown format](api.md) and as [structured JSON data](api.json) ## Types ### `PBSysErr` ```c typedef enum PB_ENUM_TYPE(int32_t) { PBSysErr_NONE = 0, // no error PBSysErr_INVALID = -1, // invalid data PBSysErr_NO_MEM = -2, // cannot allocate memory PBSysErr_BAD_HANDLE = -3, // invalid handle PBSysErr_BAD_NAME = -4, // invalid or misformed name PBSysErr_NOT_FOUND = -5, // resource not found PBSysErr_NAME_TOO_LONG = -6, // name too long PBSysErr_CANCELED = -7, // operation canceled PBSysErr_NOT_SUPPORTED = -8, // not supported PBSysErr_EXISTS = -9, // already exists PBSysErr_END = -10, // end of resource PBSysErr_ACCESS_DENIED = -11, // access denied PBSysErr_AGAIN = -12, // temporarily unavailable PBSysErr_DEFERRED = -13, // operation deferred PBSysErr_ALREADY = -14, // operation already in progress PBSysErr_IO_ERR = -15, // I/O error PBSysErr_BAD_ADDRESS = -16, // bad address /* PBSysErr_SHOULD_WAIT indicates that the operation cannot currently be performed but could succeed if the caller waits for a prerequisite to be satisfied. For example, waiting for a thread to terminate before reading its exit status. */ PBSysErr_SHOULD_WAIT = -17, PBSysErr_TIMEOUT = -18, // deadline reached // PBSysErr_BUFFER_TOO_SMALL indicates that a caller-provided buffer is too small PBSysErr_BUFFER_TOO_SMALL = -19, PBSysErr_BAD_MODE = -20, // unsupported or invalid mode PBSysErr_TOO_LARGE = -21, // value too large, e.g. overflow or limit PBSysErr_BUSY = -22, // resource busy PBSysErr_UNKNOWN = -2000000000, // unknown or internal error } PBSysErr; ``` PBSysErr defines error codes ### `PBSysThreadFlags` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef i64 PBSysAudioBuffer; ``` `Handle` to the sound mixer buffer and sound handles (u32 id, gen) ### `PBSysAudioSound` ```c typedef i64 PBSysAudioSound; ``` ### `PBSysVec2` ```c typedef struct PBSysVec2 { f32 x, y; } PBSysVec2; ``` ### `PBSysTextureFormat` ```c typedef enum PB_ENUM_TYPE(u32) { PBSysTextureFormat_UNKNOWN, PBSysTextureFormat_RGBA8, PBSysTextureFormat_BGRA8, PBSysTextureFormat_RGBAF16, } PBSysTextureFormat; ``` ### `PBSys2DTransform` ```c 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` ```c typedef struct PBSysCanvasAABB { f32 x1, y1; f32 x2, y2; } PBSysCanvasAABB; ``` ### `PBSysCanvasCmdKind` ```c 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` ```c 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` ```c typedef enum PBSysCanvasFeature { PBSysCanvasFeature_HDR, // supports >1.0 color values for extended dynamic range } PBSysCanvasFeature; ``` ### `PBSysCanvasCmd` ```c 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` ```c typedef u32 PBSysCanvasStrokeFlags; ``` ### `PBSysCanvasCmdRect` ```c typedef struct PBSysCanvasCmdRect { PBSysCanvasCmd cmd; PBSysCanvasAABB bounds; u64 fillColor; // wire color (see above) } PBSysCanvasCmdRect; ``` ### `PBSysCanvasCmdRoundedRect` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef struct PBSysCanvasCmdClipPush { PBSysCanvasCmd cmd; i32 x1, y1; i32 x2, y2; } PBSysCanvasCmdClipPush; ``` ### `PBSysCanvasCmdClipPop` ```c typedef struct PBSysCanvasCmdClipPop { PBSysCanvasCmd cmd; } PBSysCanvasCmdClipPop; ``` ### `PBSysCanvasCmdTextureSet` ```c typedef struct PBSysCanvasCmdTextureSet { PBSysCanvasCmd cmd; PBSysHandle texture; // PBSysHandle_INVALID clears to default u32 _reserved; } PBSysCanvasCmdTextureSet; ``` ### `PBSysCanvasCmdTransformPush` ```c typedef struct PBSysCanvasCmdTransformPush { PBSysCanvasCmd cmd; PBSys2DTransform transform; } PBSysCanvasCmdTransformPush; ``` ### `PBSysCanvasCmdTransformPop` ```c typedef struct PBSysCanvasCmdTransformPop { PBSysCanvasCmd cmd; } PBSysCanvasCmdTransformPop; ``` ### `PBSysCanvasCmdGroupPush` ```c 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` ```c typedef struct PBSysCanvasCmdGroupPop { PBSysCanvasCmd cmd; // cmd.flags must be 0 } PBSysCanvasCmdGroupPop; ``` ### `PBSysCanvasMaskFlags` ```c typedef u32 PBSysCanvasMaskFlags; ``` PBSysCanvasMaskFlags select how mask coverage is computed from the mask's rendered pixels. Default (0) uses the alpha channel. ### `PBSysCanvasCmdGroupMask` ```c typedef struct PBSysCanvasCmdGroupMask { PBSysCanvasCmd cmd; // cmd.flags is a PBSysCanvasMaskFlags value } PBSysCanvasCmdGroupMask; ``` ### `PBSysChannelFlags` ```c 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` ```c typedef struct PBSysClockInfo { char timeZoneName[63]; // IANA time zone identifier (e.g. "") u8 timeZoneNameLen; // length of timeZoneName } PBSysClockInfo; ``` ### `PBSysPointerKind` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef enum PBSysKeyboardFlags PB_ENUM_TYPE(u16){ PBSysKeyboardFlag_REPEAT = 1u << 0, // i.e. key is being held down } PBSysKeyboardFlags; ``` ### `PBSysGamepadButton` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef struct PBSysSignalEvent { PBSysEvent event; PBSysHandle handle; PBSysSignals signals; PBSysSignals pulseSignals; PBSysObjectType objectType; u16 _reserved; } PBSysSignalEvent; ``` ### `PBSysFilePanelEvent` ```c typedef struct PBSysFilePanelEvent { PBSysEvent event; PBSysHandle handle; } PBSysFilePanelEvent; ``` ### `PBSysInputEvent` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef struct PBSysFileId { u8 data[32]; } PBSysFileId; ``` ### `PBSysFileMode` ```c typedef u16 PBSysFileMode; ``` ### `PBSysFileModes` ```c 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` ```c 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` ```c typedef enum PBSysFileReadFlags PB_ENUM_TYPE(u64){ PBSysFileReadFlag_SYNC = 1 << 0, // blocking read } PBSysFileReadFlags; ``` ### `PBSysFileWriteFlags` ```c typedef enum PBSysFileWriteFlags PB_ENUM_TYPE(u64){ PBSysFileWriteFlag_SYNC = 1 << 0, // blocking write } PBSysFileWriteFlags; ``` ### `PBSysFileListEntryType` ```c 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` ```c typedef struct PBSysFileListEntry { u64 id; // file's unique ID within the file system (inode ID or similar) PBSysFileListEntryType type; } PBSysFileListEntry; ``` ### `PBSysGuiPresentation` ```c typedef i64 PBSysGuiPresentation; ``` ### `PBSysGuiPrefsFlags` ```c typedef u64 PBSysGuiPrefsFlags; ``` ### `PBSysGuiPrefs` ```c 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` ```c typedef u16 PBSysHandleName; ``` PBSysHandleName names special well-defined objects ### `PBSysHandleInfo` ```c typedef struct PBSysHandleInfo { PBSysHandle handle; PBSysRights rights; PBSysHandleName name; PBSysObjectType objectType; PBSysObjectId objectId; } PBSysHandleInfo; ``` ### `PBSysHidDeviceType` ```c typedef enum PBSysHidDeviceType PB_ENUM_TYPE(u16){ PBSysHidDeviceType_NONE, PBSysHidDeviceType_GAMEPAD, } PBSysHidDeviceType; ``` ### `PBSysHidDeviceFlags` ```c 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` ```c 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` ```c typedef struct PBSysHidDeviceInfo { PBSysHidDeviceType type; PBSysHidDeviceFlags flags; u32 gamepadAxisMask; // PBSysGamepadAxis bits u32 gamepadButtonMask; // PBSysGamepadButton bits u32 hapticsLocalityMask; // PBSysHidHapticsLocality bits } PBSysHidDeviceInfo; ``` ### `PBSysNetSessionConfig` ```c 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` ```c typedef u32 PBSysNetTransportFlags; ``` ### `PBSysNetTransportConfig` ```c 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` ```c 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` ```c typedef u64 PBSysNetTransportStreamFlags; ``` PBSysNetTransportStreamFlags control behavior of `PBSysNetTransportOpenStream` ### `PBSysStreamWriteFlags` ```c typedef enum PBSysStreamWriteFlags PB_ENUM_TYPE(u32){ PBSysStreamWrite_SYNC = 1, // complete write immediately or fail with PBSysErr_AGAIN } PBSysStreamWriteFlags; ``` ### `PBSysStreamStats` ```c 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` ```c typedef struct PBSysTextplanSelectionRect { i32 x, y; i32 width, height; } PBSysTextplanSelectionRect; ``` ### `PBSysTextplanSelection` ```c typedef struct PBSysTextplanSelection { u64 anchor; u64 caret; u64 lastDown; } PBSysTextplanSelection; ``` ### `PBTextPlanLayoutFlags` ```c typedef u32 PBTextPlanLayoutFlags; ``` ### `PBTextPlanLayoutFlag` ```c 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` ```c typedef u32 PBSysTextureCreateFlags; ``` ### `PBSysWindowSignals` ```c 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` ```c typedef enum PBSysThreadFeature { PBSysThreadFeature_EXIT_MAIN, // can exit main thread (i.e. unavailable on Web) PBSysThreadFeature_START, // can start threads } PBSysThreadFeature; ``` ### `PBSysWindowFullScreenFlag` ```c typedef enum PB_ENUM_TYPE(PBSysWindowFullScreenFlags) { PBSysWindowFullScreenFlag_ENABLE = 1 << 0, // enable full-screen (absense means disabled) } PBSysWindowFullScreenFlag; ``` ### `PBSysThreadConfig` ```c 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` ```c typedef enum PB_ENUM_TYPE(PBSysWindowOpenSurfaceCanvasFlags) { /* PBSysWindowOpenSurfaceCanvasFlag_WEBGPU opens the window surface canvas for direct guest WebGPU rendering. */ PBSysWindowOpenSurfaceCanvasFlag_WEBGPU = 1 << 0, } PBSysWindowOpenSurfaceCanvasFlag; ``` ### `PBSysWindowFullScreenFlags` ```c typedef u64 PBSysWindowFullScreenFlags; ``` ### `PBSysWindowSetRectFlags` ```c typedef u64 PBSysWindowSetRectFlags; ``` ### `PBSysWindowCreateTextureFlags` ```c typedef PBSysTextureCreateFlags PBSysWindowCreateTextureFlags; ``` PBSysWindowCreateTextureFlags is deprecated; use `PBSysTextureCreateFlags` ### `PBSysWindowStyle` ```c typedef u64 PBSysWindowStyle; ``` ### `PBSysCursorStyleFlags` ```c typedef u64 PBSysCursorStyleFlags; ``` ### `PBSysCursorStyleFlag` ```c enum PBSysCursorStyleFlag PB_ENUM_TYPE(PBSysCursorStyleFlags){ PBSysCursorStyleFlag_HIDDEN = 1 << 0, }; ``` ### `PBSysWindowRenderFlags` ```c typedef u64 PBSysWindowRenderFlags; ``` ### `PBSysWindowRenderFlag` ```c 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` ```c typedef u64 PBSysWindowOpenSurfaceCanvasFlags; ``` ### `PBSysCursorStyle` ```c 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` ```c 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` ```c 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` ```c 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` ```c typedef enum PBSysTextAttributeValueNumerals PB_ENUM_TYPE(u32){ PBSysTextAttributeValueNumerals_LINING = 0u, PBSysTextAttributeValueNumerals_TABULAR = 1u, PBSysTextAttributeValueNumerals_OLD_STYLE = 2u, } PBSysTextAttributeValueNumerals; ``` ### `PBSysTextAttributeValueBool` ```c typedef enum PBSysTextAttributeValueBool PB_ENUM_TYPE(u32){ PBSysTextAttributeValueBool_OFF = 0u, PBSysTextAttributeValueBool_ON = 1u, PBSysTextAttributeValueBool_ON_NO_SYNTHESIS = 2u, } PBSysTextAttributeValueBool; ``` ### `PBSysTextAttributeValueDecoration` ```c typedef struct PBSysTextAttributeValueDecoration { PBSysTextAttributeValueDecorationStyle style; u64 color; } PBSysTextAttributeValueDecoration; ``` ### `PBSysTextAttributeValueFeature` ```c typedef struct PBSysTextAttributeValueFeature { u32 tag; u32 value; } PBSysTextAttributeValueFeature; ``` ### `PBSysTextAttributeValueDirection` ```c typedef enum PBSysTextAttributeValueDirection PB_ENUM_TYPE(u32){ PBSysTextAttributeValueDirection_DEFAULT = 0u, } PBSysTextAttributeValueDirection; ``` ### `PBSysTextAttributeValueAlignment` ```c typedef enum PBSysTextAttributeValueAlignment PB_ENUM_TYPE(u32){ PBSysTextAttributeValueAlignment_START = 0u, PBSysTextAttributeValueAlignment_END = 1u, PBSysTextAttributeValueAlignment_CENTER = 2u, PBSysTextAttributeValueAlignment_JUSTIFY = 3u, } PBSysTextAttributeValueAlignment; ``` ### `PBSysTextAttributeType` ```c 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` ```c 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` ```c typedef struct PBSysPositionedTextAttribute { u32 start; PBSysTextAttribute attribute; } PBSysPositionedTextAttribute; ``` ### `PBWindowWorkspaceOpenURLConfig` ```c typedef struct PBWindowWorkspaceOpenURLConfig { // Currently, no flags are defined. u32 flags; } PBWindowWorkspaceOpenURLConfig; ``` ### `PBSysCallOp` ```c 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` ```c 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` ```c typedef struct PBSysHandlePair { PBSysHandle a, b; } PBSysHandlePair; ``` ### `PBSysTime` ```c typedef u64 PBSysTime; ``` PBSysTime represents a point in system time (nanoseconds in monotonic-clock space) ### `PBSysDuration` ```c typedef i64 PBSysDuration; ``` PBSysDuration represents a duration of time, measured in nanoseconds. ### `PBSysDate` ```c 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` ```c typedef struct PBSysStr { uint32_t len; uint8_t bytes[]; } PBSysStr; ``` ### `PBSysBuf` ```c typedef struct PBSysBuf { const uint8_t* nullable bytes; size_t len; } PBSysBuf; ``` ### `PBSysObjectId` ```c typedef u32 PBSysObjectId; ``` PBSysObjectId uniquely identifies a system object ### `PBSysSignals` ```c 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` ```c typedef void (*PBSysThreadEntry)(uint64_t, uint64_t); ``` PBSysThreadEntry ### `PBSysGuiSignals` ```c 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` ```c typedef enum PB_ENUM_TYPE(PBSysSignals) { PBSysNetTransportSignal_READY = 1u << 0, // connection is established and active PBSysNetTransportSignal_CLOSED = 1u << 1, // connection is closed } PBSysNetTransportSignals; ``` ### `PBSysNetSessionSignals` ```c 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` ```c 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` ```c 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` ```c typedef enum PB_ENUM_TYPE(uint32_t) { PBSysClockSignal_TIME_ZONE = 1u << 0, // time zone changed (pulse) } PBSysClockSignals; ``` ### `PBSysStreamSignals` ```c 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` ```c typedef enum PB_ENUM_TYPE(PBSysNetTransportFlags) { PBSysNetTransportFlag_TLS = 1u << 0, // enable TLS (DTLS for UDP) } PBSysNetTransportFlag; ``` BEGIN generated code ### `PBSysNetTransportStreamFlag` ```c 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` ```c 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` ```c typedef enum PB_ENUM_TYPE(u64) { PBSysHandleList_FILTER = 0xff, // mask for a PBSysHandleListFilter_ value } PBSysHandleListFlags; ``` ### `PBSysHandleListFilter` ```c 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` ```c 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` ```c 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` ```c macro void PBSysObject_FOREACH(macro(NAME) m) ``` calls a macro `m` for each object name, e.g. `m(Thread)` ### `PBSysEventSize_MAX` ```c #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` ```c macro PB_ENUM_TYPE(T) -> :T ``` Usage example: enum Foo PB_ENUM_TYPE(uint16_t) { Foo_A, Foo_B }; ### `PB_DEPRECATED` ```c macro void PB_DEPRECATED(const char* message [,const char* replacement]) ``` marks a symbol as deprecated ### `PB_DEPRECATED_REPLACED_BY` ```c macro void PB_DEPRECATED_REPLACED_BY(ID newName) ``` marks a symbol as deprecated, replaced by a symbol with name `newName` ## Functions ### `PBSysAudioOutputInit` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysAudioBufferDestroy(PBSysHandle audio, PBSysAudioBuffer buffer); ``` PBSysAudioBufferDestroy destroys an `audio` `buffer` (and frees the associated memory with it). - Required rights: `PBSysRight_WRITE` ### `PBSysAudioBufferPlay` ```c 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` ```c 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` isn`t currently playing (e.g. it already finished), there`s 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysTime PBSysClockMonotonic(); ``` PBSysClockMonotonic returns the current system time - Required rights: none ### `PBSysClockRead` ```c 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` ```c PBSysErr PBSysClockReadInfo(PBSysHandle clock, PBSysClockInfo* info, u32 infoSize); ``` PBSysClockReadInfo retrieves information about a `clock` - Required rights: `PBSysRight_READ` ### `PBSysEventPoll` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysHandleClose(PBSysHandle handle); ``` PBSysHandleClose closes a `handle`. The `handle` is invalid after this call. - Required rights: none ### `PBSysHandleDuplicate` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysNetEncrypt(PBSysHandle net, const u8* inBuf, u32 inBufLen, const u8* keyBuf, u32 keyBufLen, u8* outBuf, u32 outBufLen); ``` Private API. - Required rights: none ### `PBSysNetDecrypt` ```c PBSysErr PBSysNetDecrypt(PBSysHandle net, const u8* inBuf, u32 inBufLen, const u8* keyBuf, u32 keyBufLen, u8* outBuf, u32 outBufLen); ``` Private API. - Required rights: none ### `PBSysNetEncryptAsymmetric` ```c PBSysErr PBSysNetEncryptAsymmetric(PBSysHandle net, const u8* inBuf, u32 inBufLen, const u8* publicKeyBuf, u32 publicKeyBufLen, u8* outBuf, u32 outBufLen); ``` Private API. - Required rights: none ### `PBSysNetDecryptAsymmetric` ```c PBSysErr PBSysNetDecryptAsymmetric(PBSysHandle net, const u8* inBuf, u32 inBufLen, const u8* privateKeyBuf, u32 privateKeyBufLen, u8* outBuf, u32 outBufLen); ``` Private API. - Required rights: none ### `PBSysNetSessionId` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c u64 PBSysTextplanHitTest(PBSysHandle textPlan, i32 x, i32 y); ``` - Required rights: none ### `PBSysTextplanGetCaretBounds` ```c u64 PBSysTextplanGetCaretBounds(PBSysHandle textPlan, u64 caretTextIndex); ``` - Required rights: none ### `PBSysTextplanGetSelectionRects` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c u32 PBSysTextureGetWidth(PBSysHandle texture); ``` PBSysTextureGetWidth returns the width of a `texture`, in pixels. - Required rights: `PBSysRight_READ` ### `PBSysTextureGetHeight` ```c u32 PBSysTextureGetHeight(PBSysHandle texture); ``` `PBSysTextureGetWidth` returns the height of a `texture`, in pixels. - Required rights: `PBSysRight_READ` ### `PBSysThreadEnterMain` ```c void PBSysThreadEnterMain(u64 flags); ``` PBSysThreadEnterMain - `flags`: are bits of PBSysThread_ - Required rights: none ### `PBSysThreadStart` ```c PBSysHandle PBSysThreadStart(PBSysHandle parentThread, u64 flags, const PBSysThreadConfig* config, u64 configSize); ``` PBSysThreadStart starts a new thread. - Required rights: `PBSysRight_MANAGE_THREAD` ### `PBSysThreadExit` ```c PBSysErr PBSysThreadExit(PBSysHandle thread, i32 status); ``` PBSysThreadExit stops a `thread` and sets its exit `status`. - Required rights: `PBSysRight_MANAGE_THREAD` ### `PBSysThreadExitStatus` ```c i32 PBSysThreadExitStatus(PBSysHandle thread); ``` PBSysThreadExitStatus returns the exit status of `thread`. - Returns: `PBSysErr` on error. - Required rights: `PBSysRight_MANAGE_THREAD` ### `PBSysThreadExitProcess` ```c PBSysErr PBSysThreadExitProcess(PBSysHandle thread, i32 status); ``` PBSysThreadExitProcess terminated the process. - Required rights: `PBSysRight_MANAGE_PROCESS` ### `PBSysThreadWrite` ```c 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` ```c 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` ```c 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` ```c PBSysHandle PBSysThreadWindowCreate(PBSysHandle thread, const PBSysWindowConfig* config, usize configSize); ``` PBSysThreadWindowCreate creates a window associated with a `thread`. - Required rights: `PBSysRight_WRITE` ### `PBSysThreadNetConnect` ```c PBSysHandle PBSysThreadNetConnect(PBSysHandle thread, u32 ipAddr, u16 tcpPort); ``` Note: Draft API; arguments will change - Required rights: `PBSysRight_NETWORK` ### `PBSysThreadHostControllerConnect` ```c PBSysHandle PBSysThreadHostControllerConnect(PBSysHandle thread); ``` Note: Draft API; arguments will change - Required rights: none ### `PBSysThreadHostControllerRequest` ```c i64 PBSysThreadHostControllerRequest(PBSysHandle thread, const u8* buf, u32 bufLen); ``` Note: Draft API; arguments will change - Required rights: none ### `PBSysThreadReadRandom` ```c 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` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysWindowInfoGet(PBSysHandle window, PBSysWindowInfo* info, u64 infoSize); ``` PBSysWindowInfoGet retrieves latest `window` metrics and timing hints. - Required rights: `PBSysRight_READ` ### `PBSysWindowSetRect` ```c 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` ```c PBSysErr PBSysWindowSetStyle(PBSysHandle window, PBSysWindowStyle style, u64 flags); ``` PBSysWindowSetStyle sets the `style` of a `window`. - Required rights: `PBSysRight_WRITE` ### `PBSysWindowSetTitle` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysWindowSetRenderFlags(PBSysHandle window, PBSysWindowRenderFlags flags); ``` PBSysWindowSetRenderFlags controls behavior of `window` rendering. - Required rights: `PBSysRight_WRITE` ### `PBSysWindowOpenSurfaceCanvas` ```c 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` ```c 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` ```c 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` ```c 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` ```c PBSysErr PBSysWindowClipboardWriteText(PBSysHandle window, const u8* text, u64 textSize); ``` PBSysWindowClipboardWriteText sets the `text` on the clipboard. - Required rights: `PBSysRight_WRITE` ### `PBSysWindowClipboardReadText` ```c i64 PBSysWindowClipboardReadText(PBSysHandle window, u8* buffer, u64 bufferSize); ``` `PBSysWindowClipboardWriteText` reads the text from the clipboard. - Required rights: `PBSysRight_READ` ### `PBSysWindowWorkspaceOpenURL` ```c 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` ```c PBSysWindowFullScreenFlags PBSysWindowFullScreenGet(PBSysHandle window); ``` PBSysWindowFullScreenGet returns the current full-screen state of a `window` - Required rights: `PBSysRight_READ` ### `PBSysWindowFullScreenSet` ```c PBSysErr PBSysWindowFullScreenSet(PBSysHandle window, PBSysWindowFullScreenFlags flags); ``` `PBSysWindowFullScreenGet` configures full-screen state of a `window` - Required rights: `PBSysRight_WRITE` ### `PBSysWindowSetCursor` ```c 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`