Runtime types
#include <playbit/sys/types.h>
This page summarizes the core runtime types.
Core scalar types
typedef int32_t PBSysHandle;
typedef uint64_t PBSysTime; // monotonic nanoseconds
typedef int64_t PBSysDuration; // nanoseconds
typedef int64_t PBSysDate; // microseconds since 1970-01-01 UTC
typedef uint32_t PBSysRights;
typedef uint32_t PBSysSignals;
PBSysHandle notes:
0is invalid (PBSysHandle_INVALID).1is current thread (PBSysHandle_SELF_THREAD).- Negative values are not valid handles and represent
PBSysErrin syscall returns.
Events
PBSysEvent is the variable-size header used by events produced by PBSysEventPoll:
typedef struct PBSysEvent {
u16 size;
u16 type; // PBSysEventType
PBSysObjectId objectId;
} PBSysEvent;
Each event written by PBSysEventPoll starts with this header, and size tells you how many bytes to advance to find the next event.
Type aliases
PBSysAudioBuffer
typedef i64 PBSysAudioBuffer;
Handle to the sound mixer buffer and sound handles (u32 id, gen)
PBSysAudioSound
typedef i64 PBSysAudioSound;
PBSysDate
typedef i64 PBSysDate;
PBSysDate represents a point in "real" time (microseconds since 1970-01-01 00:00:00 UTC.) Range limit: [290309 BCE, Dec 22, 19:59:05 UTC - 294247, Jan 10, 04:00:54 UTC]
PBSysDuration
typedef i64 PBSysDuration;
PBSysDuration represents a duration of time, measured in nanoseconds.
PBSysFileMode
typedef u16 PBSysFileMode;
PBSysHandle
typedef i32 PBSysHandle;
PBSysHandle represents a handle to a runtime object.
A handle can be thought of as a session or connection to a particular runtime object.
Note: negative values signifies PBSysErr and are invalid as handles.
PBSysHandleName
typedef u16 PBSysHandleName;
PBSysHandleName names special well-defined objects
PBSysObjectId
typedef u32 PBSysObjectId;
PBSysObjectId uniquely identifies a system object
PBSysRights
typedef u32 PBSysRights;
PBSysRights are associated with handles and convey privileges to perform actions on either the associated handle or the object associated with the handle.
PBSysSignals
typedef u32 PBSysSignals;
PBSysSignals is a bitset of signals.
- Bits 1 through 24 are reserved for the system.
- Bits 25 through 32 are reserved for user-defined signals.
PBSysTime
typedef u64 PBSysTime;
PBSysTime represents a point in system time (nanoseconds in monotonic-clock space)
PBSysWindowCreateTextureFlags
typedef u32 PBSysWindowCreateTextureFlags;
PBSysWindowSetRectFlags
typedef u64 PBSysWindowSetRectFlags;
PBSysWindowStyle
typedef u64 PBSysWindowStyle;
Function pointers
PBSysThreadEntry
typedef void (*PBSysThreadEntry)(uint64_t, uint64_t);
PBSysThreadEntry
Enums
PBSysCallOp
typedef enum PBSysCallOp PB_ENUM_TYPE(uint32_t){
PBSysCallOp_None = 0, // invalid
PBSysCallOp_AudioBufferCreate = 117,
PBSysCallOp_AudioBufferCreateFromFile = 121,
PBSysCallOp_AudioBufferDestroy = 118,
PBSysCallOp_AudioBufferPlay = 119,
PBSysCallOp_AudioOutputInit = 122,
PBSysCallOp_AudioSetVolume = 120,
PBSysCallOp_BundleGetResource = 125,
PBSysCallOp_ChannelCreate = 65,
PBSysCallOp_ChannelDisableWrite = 68,
PBSysCallOp_ChannelRead = 66,
PBSysCallOp_ChannelWrite = 67,
PBSysCallOp_ClockMonotonic = 56,
PBSysCallOp_ClockRead = 25,
PBSysCallOp_ClockReadInfo = 60,
PBSysCallOp_EventPoll = 58,
PBSysCallOp_FileListOpen = 98,
PBSysCallOp_FileOpen = 103,
PBSysCallOp_FileRead = 104,
PBSysCallOp_FileWrite = 105,
PBSysCallOp_FileListNext = 102,
PBSysCallOp_GuiCursorStyleSet = 69,
PBSysCallOp_HandleClose = 70,
PBSysCallOp_HandleDuplicate = 71,
PBSysCallOp_HandleList = 77,
PBSysCallOp_NetConnect = 95,
PBSysCallOp_NetSessionOpen = 90,
PBSysCallOp_NetSessionId = 93,
PBSysCallOp_NetSessionOpenStream = 91,
PBSysCallOp_ObjectObserve = 57,
PBSysCallOp_ObjectSignal = 55,
PBSysCallOp_StreamOpenPipePair = 92,
PBSysCallOp_StreamRead = 46,
PBSysCallOp_StreamStatsRead = 94,
PBSysCallOp_StreamWrite = 28,
PBSysCallOp_TextplanGetCaretBounds = 81,
PBSysCallOp_TextplanGetSelectionRects = 83,
PBSysCallOp_TextplanGetSize = 38,
PBSysCallOp_TextplanHitTest = 82,
PBSysCallOp_TextplanLayout = 40,
PBSysCallOp_TextplanMoveSelection = 85,
PBSysCallOp_TextplanMoveSelectionToPoint = 84,
PBSysCallOp_TextplanMoveSelectionVertical = 88,
PBSysCallOp_TextureWrite = 106,
PBSysCallOp_ThreadEnterMain = 59,
PBSysCallOp_ThreadExit = 30,
PBSysCallOp_ThreadExitProcess = 31,
PBSysCallOp_ThreadExitStatus = 47,
PBSysCallOp_ThreadHostControllerConnect = 79,
PBSysCallOp_ThreadLogWrite = 32,
PBSysCallOp_ThreadNetConnect = 42,
PBSysCallOp_ThreadRead = 76,
PBSysCallOp_ThreadStart = 33,
PBSysCallOp_ThreadWindowCreate = 41,
PBSysCallOp_ThreadWrite = 75,
PBSysCallOp_WindowClipboardReadText = 107,
PBSysCallOp_WindowClipboardWriteText = 108,
PBSysCallOp_WindowCopyTitle = 126,
PBSysCallOp_WindowCreateTexture = 109,
PBSysCallOp_WindowCreateTextureFromData = 110,
PBSysCallOp_WindowFrameSyncEnable = 63,
PBSysCallOp_WindowInfoGet = 64,
PBSysCallOp_WindowRendererPackageWrite = 78,
PBSysCallOp_WindowSetRect = 87,
PBSysCallOp_WindowSetStyle = 127,
PBSysCallOp_WindowSetTitle = 80,
PBSysCallOp_WindowSizeLimitsSet = 128,
PBSysCallOp_WindowTextplanCreate = 36,
PBSysCallOp_READ = 9, // legacy
PBSysCallOp_WGPU = 10, // legacy
PBSysCallOp_CURSOR = 14, // legacy
PBSysCallOp_RES_CREATE = 15, // legacy
PBSysCallOp_RES_MUTATE = 16, // legacy
PBSysCallOp_RES_ADVERTISE_NEW = 17, // legacy
PBSysCallOp_TAKE_ROOT_CAP = 18, // legacy
PBSysCallOp_OPEN = 19, // legacy
} PBSysCallOp;
PBSysCallOp defines all syscall operations
PBSysChannelFlags
enum PBSysChannelFlags PB_ENUM_TYPE(uint32_t){
PBSysChannel_DUPLEX = 1u << 0, // created handles support both reading and writing
PBSysChannel_MULTIPLE_WRITERS = 1u << 1, // support multiple concurrent threads writing
PBSysChannel_MULTIPLE_READERS = 1u << 2, // support multiple concurrent threads reading
};
PBSysChannelSignals
typedef enum PB_ENUM_TYPE(uint32_t) {
PBSysChannelSignal_READABLE = 1u << 0, // there are entries to read
PBSysChannelSignal_WRITABLE = 1u << 1, // there's space for writing at least one entry
PBSysChannelSignal_WRITE_DISABLED = 1u << 2, // writing has been closed
} PBSysChannelSignals;
PBSysClockSignals
typedef enum PB_ENUM_TYPE(uint32_t) {
PBSysClockSignal_TIME_ZONE = 1u << 0, // time zone changed (pulse)
} PBSysClockSignals;
PBSysClockSignals describe signals available for clocks (in addition to USER signals)
PBSysCursorStyle
typedef enum PBSysCursorStyle PB_ENUM_TYPE(uint16_t){
PBSysCursorStyle_NONE = 0, //
PBSysCursorStyle_IMAGE, //
PBSysCursorStyle_POINTER, //
PBSysCursorStyle_HAND, //
PBSysCursorStyle_TEXT, //
PBSysCursorStyle_HIDDEN, //
PBSysCursorStyle_LOADING, //
PBSysCursorStyle_BLOCKED, //
PBSysCursorStyle_PAN, //
PBSysCursorStyle_SIZEH, //
PBSysCursorStyle_SIZEV, //
PBSysCursorStyle_SIZENESW, //
PBSysCursorStyle_SIZENWSE, //
PBSysCursorStyle_SCROLLNS, //
PBSysCursorStyle_SCROLLN, //
PBSysCursorStyle_SCROLLS, //
} PBSysCursorStyle;
PBSysErr
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_UNKNOWN = -2000000000, // unknown or internal error
} PBSysErr;
PBSysErr defines error codes
PBSysEventType
typedef enum PBSysEventType PB_ENUM_TYPE(u16){
PBSysEventType_INVALID = 0,
// signal
PBSysEventType_SIGNAL,
// pointer
PBSysEventType_POINTER_ENTER, // pointer started being "in" the surface/window
PBSysEventType_POINTER_LEAVE, // pointer left the surface/window
PBSysEventType_POINTER_DOWN,
PBSysEventType_POINTER_UP,
PBSysEventType_POINTER_MOVE,
PBSysEventType_POINTER_CANCEL, // system canceled a sequence (e.g. OS interruption)
// scroll
PBSysEventType_SCROLL,
// gesture
PBSysEventType_GESTURE_PAN, // translation (typically dp)
PBSysEventType_GESTURE_PINCH, // scale factor (relative)
PBSysEventType_GESTURE_ROTATE, // radians (relative)
// keyboard
PBSysEventType_KEY_DOWN,
PBSysEventType_KEY_UP,
} PBSysEventType;
PBSysEventType defines the type of a PBSysEvent entry
PBSysFileListEntryType
typedef enum PBSysFileListEntryType PB_ENUM_TYPE(u8){
PBSysFileListEntryType_UNKNOWN = 0, // underlying filesyestem does not report types
PBSysFileListEntryType_DIR = 1, // directory
PBSysFileListEntryType_FILE = 2, // regular file
PBSysFileListEntryType_LINK = 3, // symbolic link
PBSysFileListEntryType_SOCKET = 4, // local socket
PBSysFileListEntryType_SPECIAL = 100, // none of the above (e.g. fifo, char dev. etc.)
} PBSysFileListEntryType;
PBSysFileModes
enum PBSysFileModes PB_ENUM_TYPE(PBSysFileMode){
PBSysFileMode_USER_R = 0400, // user (file owner) has read permission
PBSysFileMode_USER_W = 0200, // user has write permission
PBSysFileMode_USER_X = 0100, // user has execute permission
PBSysFileMode_USER_RW = 0600, // user has read and write permissions
PBSysFileMode_USER_RWX = 0700, // user has read, write, and execute permissions
PBSysFileMode_GROUP_R = 0040, // group has read permission
PBSysFileMode_GROUP_W = 0020, // group has write permission
PBSysFileMode_GROUP_X = 0010, // group has execute permission
PBSysFileMode_GROUP_RW = 0060, // group has read and write execute permissions
PBSysFileMode_GROUP_RWX = 0070, // group has read, write, and execute permissions
PBSysFileMode_OTHER_R = 0004, // others have read permission
PBSysFileMode_OTHER_W = 0002, // others have write permission
PBSysFileMode_OTHER_X = 0001, // others have execute permission
PBSysFileMode_OTHER_RW = 0006, // others have read and write execute permissions
PBSysFileMode_OTHER_RWX = 0007, // others have read, write, and execute permissions
};
PBSysFileOpenFlags
typedef enum PBSysFileOpenFlags PB_ENUM_TYPE(u64){
PBSysFileOpenFlag_READ = 1 << 0, // give file PBSysRight_READ
PBSysFileOpenFlag_WRITE = 1 << 1, // give file PBSysRight_WRITE
PBSysFileOpenFlag_APPEND = (1 << 2) | PBSysFileOpenFlag_WRITE, // open in append mode
PBSysFileOpenFlag_CREATE = 1 << 7, // create file if it does not exist
// PBSysFileOpenFlag_MODE_MASK masks mode bits in flags, for use with CREATE flag
PBSysFileOpenFlag_MODE_MASK = 0xffff << 8,
PBSysFileOpenFlag_MODE_USER_R = PBSysFileMode_USER_R << 8,
PBSysFileOpenFlag_MODE_USER_W = PBSysFileMode_USER_W << 8,
PBSysFileOpenFlag_MODE_USER_X = PBSysFileMode_USER_X << 8,
PBSysFileOpenFlag_MODE_USER_RWX = PBSysFileMode_USER_RWX << 8,
PBSysFileOpenFlag_MODE_GROUP_R = PBSysFileMode_GROUP_R << 8,
PBSysFileOpenFlag_MODE_GROUP_W = PBSysFileMode_GROUP_W << 8,
PBSysFileOpenFlag_MODE_GROUP_X = PBSysFileMode_GROUP_X << 8,
PBSysFileOpenFlag_MODE_GROUP_RWX = PBSysFileMode_GROUP_RWX << 8,
PBSysFileOpenFlag_MODE_OTHER_R = PBSysFileMode_OTHER_R << 8,
PBSysFileOpenFlag_MODE_OTHER_W = PBSysFileMode_OTHER_W << 8,
PBSysFileOpenFlag_MODE_OTHER_X = PBSysFileMode_OTHER_X << 8,
PBSysFileOpenFlag_MODE_OTHER_RWX = PBSysFileMode_OTHER_RWX << 8,
} PBSysFileOpenFlags;
PBSysFileOpenFlag_MODE_MASK masks mode bits in flags, for use with CREATE flag
PBSysFileReadFlags
typedef enum PBSysFileReadFlags PB_ENUM_TYPE(u64){
PBSysFileReadFlag_SYNC = 1 << 0, // blocking read
} PBSysFileReadFlags;
PBSysFileWriteFlags
typedef enum PBSysFileWriteFlags PB_ENUM_TYPE(u64){
PBSysFileWriteFlag_SYNC = 1 << 0, // blocking write
} PBSysFileWriteFlags;
PBSysGesturePhase
typedef enum PBSysGesturePhase PB_ENUM_TYPE(u8){
PBSysGesturePhase_CHANGED = 0, // default if platform doesn't provide phases
PBSysGesturePhase_BEGAN = 1,
PBSysGesturePhase_ENDED = 2,
} PBSysGesturePhase;
PBSysHandleListFilter
typedef enum PB_ENUM_TYPE(u8) {
PBSysHandleListFilter_BY_NAME = 1, // predicate is of type PBSysHandleName
PBSysHandleListFilter_BY_OBJECT_ID = 2, // predicate is of type PBSysObjectId
PBSysHandleListFilter_BY_OBJECT_TYPE = 3, // predicate is of type PBSysObjectType
} PBSysHandleListFilter;
PBSysHandleListFilter are possible filters
PBSysHandleListFlags
typedef enum PB_ENUM_TYPE(u64) {
PBSysHandleList_FILTER = 0xff, // mask for a PBSysHandleListFilter_ value
} PBSysHandleListFlags;
PBSysHandleListFlags are flags for PBSysHandleList
PBSysKeyboardFlags
typedef enum PBSysKeyboardFlags PB_ENUM_TYPE(u16){
PBSysKeyboardFlag_REPEAT = 1u << 0, // i.e. key is being held down
} PBSysKeyboardFlags;
PBSysKeyboardKey
typedef enum PBSysKeyboardKey PB_ENUM_TYPE(u16){
PBSysKeyboardKey_None = 0x0000,
// ASCII / Unicode printable (match codepoint)
PBSysKeyboardKey_Space = 0x0020,
PBSysKeyboardKey_Quote = 0x0027,
PBSysKeyboardKey_Comma = 0x002C,
PBSysKeyboardKey_Minus = 0x002D,
PBSysKeyboardKey_Period = 0x002E,
PBSysKeyboardKey_Slash = 0x002F,
PBSysKeyboardKey_0 = 0x0030,
PBSysKeyboardKey_1 = 0x0031,
PBSysKeyboardKey_2 = 0x0032,
PBSysKeyboardKey_3 = 0x0033,
PBSysKeyboardKey_4 = 0x0034,
PBSysKeyboardKey_5 = 0x0035,
PBSysKeyboardKey_6 = 0x0036,
PBSysKeyboardKey_7 = 0x0037,
PBSysKeyboardKey_8 = 0x0038,
PBSysKeyboardKey_9 = 0x0039,
PBSysKeyboardKey_Semicolon = 0x003B,
PBSysKeyboardKey_Equal = 0x003D,
PBSysKeyboardKey_A = 0x0041,
PBSysKeyboardKey_B = 0x0042,
PBSysKeyboardKey_C = 0x0043,
PBSysKeyboardKey_D = 0x0044,
PBSysKeyboardKey_E = 0x0045,
PBSysKeyboardKey_F = 0x0046,
PBSysKeyboardKey_G = 0x0047,
PBSysKeyboardKey_H = 0x0048,
PBSysKeyboardKey_I = 0x0049,
PBSysKeyboardKey_J = 0x004A,
PBSysKeyboardKey_K = 0x004B,
PBSysKeyboardKey_L = 0x004C,
PBSysKeyboardKey_M = 0x004D,
PBSysKeyboardKey_N = 0x004E,
PBSysKeyboardKey_O = 0x004F,
PBSysKeyboardKey_P = 0x0050,
PBSysKeyboardKey_Q = 0x0051,
PBSysKeyboardKey_R = 0x0052,
PBSysKeyboardKey_S = 0x0053,
PBSysKeyboardKey_T = 0x0054,
PBSysKeyboardKey_U = 0x0055,
PBSysKeyboardKey_V = 0x0056,
PBSysKeyboardKey_W = 0x0057,
PBSysKeyboardKey_X = 0x0058,
PBSysKeyboardKey_Y = 0x0059,
PBSysKeyboardKey_Z = 0x005A,
PBSysKeyboardKey_LeftBracket = 0x005B,
PBSysKeyboardKey_Backslash = 0x005C,
PBSysKeyboardKey_RightBracket = 0x005D,
PBSysKeyboardKey_Grave = 0x0060,
// Unicode symbols
PBSysKeyboardKey_Escape = 0x238B, // ESC
PBSysKeyboardKey_Enter = 0x23CE, // RETURN SYMBOL
PBSysKeyboardKey_Tab = 0x21E5, // TAB
PBSysKeyboardKey_Backspace = 0x232B, // ERASE TO THE LEFT
PBSysKeyboardKey_Insert = 0x2380, // INSERT
PBSysKeyboardKey_Delete = 0x2326, // ERASE TO THE RIGHT
PBSysKeyboardKey_Left = 0x2190,
PBSysKeyboardKey_Right = 0x2192,
PBSysKeyboardKey_Down = 0x2193,
PBSysKeyboardKey_Up = 0x2191,
PBSysKeyboardKey_PageUp = 0x21DE,
PBSysKeyboardKey_PageDown = 0x21DF,
PBSysKeyboardKey_Home = 0x21F1,
PBSysKeyboardKey_End = 0x21F2,
PBSysKeyboardKey_CapsLock = 0x21EA,
PBSysKeyboardKey_LeftShift = 0x21E7,
PBSysKeyboardKey_LeftCtrl = 0x2303,
PBSysKeyboardKey_LeftAlt = 0x2325,
PBSysKeyboardKey_LeftSuper = 0x2318,
PBSysKeyboardKey_MediaNext = 0x23ED,
PBSysKeyboardKey_MediaPrev = 0x23EE,
PBSysKeyboardKey_MediaPlay = 0x23F5,
PBSysKeyboardKey_MediaStop = 0x23F9,
// Private use area (0xE000-0xEFFF)
PBSysKeyboardKey_World1 = 0xE000,
PBSysKeyboardKey_World2 = 0xE001,
PBSysKeyboardKey_ScrollLock = 0xE010,
PBSysKeyboardKey_NumLock = 0xE011,
PBSysKeyboardKey_PrintScreen = 0xE012,
PBSysKeyboardKey_Pause = 0xE013,
PBSysKeyboardKey_F1 = 0xE100,
PBSysKeyboardKey_F2 = 0xE101,
PBSysKeyboardKey_F3 = 0xE102,
PBSysKeyboardKey_F4 = 0xE103,
PBSysKeyboardKey_F5 = 0xE104,
PBSysKeyboardKey_F6 = 0xE105,
PBSysKeyboardKey_F7 = 0xE106,
PBSysKeyboardKey_F8 = 0xE107,
PBSysKeyboardKey_F9 = 0xE108,
PBSysKeyboardKey_F10 = 0xE109,
PBSysKeyboardKey_F11 = 0xE10A,
PBSysKeyboardKey_F12 = 0xE10B,
PBSysKeyboardKey_F13 = 0xE10C,
PBSysKeyboardKey_F14 = 0xE10D,
PBSysKeyboardKey_F15 = 0xE10E,
PBSysKeyboardKey_F16 = 0xE10F,
PBSysKeyboardKey_F17 = 0xE110,
PBSysKeyboardKey_F18 = 0xE111,
PBSysKeyboardKey_F19 = 0xE112,
PBSysKeyboardKey_F20 = 0xE113,
PBSysKeyboardKey_F21 = 0xE114,
PBSysKeyboardKey_F22 = 0xE115,
PBSysKeyboardKey_F23 = 0xE116,
PBSysKeyboardKey_F24 = 0xE117,
PBSysKeyboardKey_Numpad0 = 0xE200,
PBSysKeyboardKey_Numpad1 = 0xE201,
PBSysKeyboardKey_Numpad2 = 0xE202,
PBSysKeyboardKey_Numpad3 = 0xE203,
PBSysKeyboardKey_Numpad4 = 0xE204,
PBSysKeyboardKey_Numpad5 = 0xE205,
PBSysKeyboardKey_Numpad6 = 0xE206,
PBSysKeyboardKey_Numpad7 = 0xE207,
PBSysKeyboardKey_Numpad8 = 0xE208,
PBSysKeyboardKey_Numpad9 = 0xE209,
PBSysKeyboardKey_NumpadDot = 0xE20A,
PBSysKeyboardKey_NumpadDivide = 0xE20B,
PBSysKeyboardKey_NumpadMultiply = 0xE20C,
PBSysKeyboardKey_NumpadSubtract = 0xE20D,
PBSysKeyboardKey_NumpadAdd = 0xE20E,
PBSysKeyboardKey_NumpadEnter = 0xE20F,
PBSysKeyboardKey_NumpadEquals = 0xE210,
PBSysKeyboardKey_NumpadClear = 0xE211,
PBSysKeyboardKey_RightShift = 0xE300,
PBSysKeyboardKey_RightCtrl = 0xE301,
PBSysKeyboardKey_RightAlt = 0xE302,
PBSysKeyboardKey_RightSuper = 0xE303,
PBSysKeyboardKey_Menu = 0xE310,
PBSysKeyboardKey_VolumeUp = 0xE320,
PBSysKeyboardKey_VolumeDown = 0xE321,
PBSysKeyboardKey_Mute = 0xE322,
PBSysKeyboardKey_COUNT
} PBSysKeyboardKey;
ASCII / Unicode printable (match codepoint)
PBSysKeyboardModifiers
typedef enum PBSysKeyboardModifiers PB_ENUM_TYPE(u16){
PBSysKeyboardModifier_SHIFT = 1u << 0, // shift
PBSysKeyboardModifier_CTRL = 1u << 1, // control
PBSysKeyboardModifier_ALT = 1u << 2, // aka "option" on mac
PBSysKeyboardModifier_META = 1u << 3, // aka "command", "windows key", "super"
PBSysKeyboardModifier_CAPS_LOCK = 1u << 4, // caps lock
PBSysKeyboardModifier_FN = 1u << 5, // "function"
} PBSysKeyboardModifiers;
PBSysMouseButton
typedef enum PBSysMouseButton PB_ENUM_TYPE(u16){
PBSysMouseButton_Left = 0,
PBSysMouseButton_Right = 1,
PBSysMouseButton_Middle = 2,
PBSysMouseButton_X1 = 3,
PBSysMouseButton_X2 = 4,
// NOTE: unnamed buttons here
PBSysMouseButton_COUNT = 16,
} PBSysMouseButton;
NOTE: unnamed buttons here
PBSysNetSessionSignals
typedef enum PB_ENUM_TYPE(uint32_t) {
/*
PBSysNetSessionSignal_AVAILABLE means the session's underlying AP transport is connected. The runtime may still be authenticating the session while this signal is active without `PBSysNetSessionSignal_READY`.
*/
PBSysNetSessionSignal_AVAILABLE = 1u << 4,
/*
PBSysNetSessionSignal_READY means the session is authenticated and its AP streams may become writable. When this signal is active, `PBSysNetSessionSignal_AVAILABLE` is also active.
*/
PBSysNetSessionSignal_READY = 1u << 0,
} PBSysNetSessionSignals;
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`.
PBSysObjectType
typedef enum PBSysObjectType PB_ENUM_TYPE(uint16_t){
PBSysObject_None = 0, // invalid
PBSysObject_Audio = 16,
PBSysObject_Bundle = 18,
PBSysObject_Channel = 7,
PBSysObject_Clock = 1,
PBSysObject_File = 12,
PBSysObject_FileList = 14,
PBSysObject_Gui = 8,
PBSysObject_Net = 9,
PBSysObject_NetSession = 10,
PBSysObject_Stream = 2,
PBSysObject_Textplan = 3,
PBSysObject_Texture = 15,
PBSysObject_Thread = 4,
PBSysObject_Window = 6,
} PBSysObjectType;
PBSysObjectType expresses a type of object
PBSysPointerFlags
typedef enum PBSysPointerFlags PB_ENUM_TYPE(u16){
PBSysPointerFlag_PRIMARY = 1u << 0, // primary pointer for this device
PBSysPointerFlag_IN_CONTACT = 1u << 1, // touch/pen in contact
PBSysPointerFlag_ERASER = 1u << 2, // pen eraser side/end
PBSysPointerFlag_INVERTED = 1u << 3, // if a platform reports pen inversion
PBSysPointerFlag_COALESCED = 1u << 4, // if event is a coalesced/aggregated update
PBSysPointerFlag_PREDICTED = 1u << 5, // if predicted (some systems provide)
} PBSysPointerFlags;
PBSysPointerKind
typedef enum PBSysPointerKind PB_ENUM_TYPE(u8){
PBSysPointerKind_MOUSE = 1,
PBSysPointerKind_TOUCH = 2,
PBSysPointerKind_TRACKPAD = 3, // used mainly for scroll/gesture sources
PBSysPointerKind_PEN = 4,
} PBSysPointerKind;
PBSysRightsBits
enum PBSysRightsBits PB_ENUM_TYPE(PBSysRights){
PBSysRight_NONE = 0u,
PBSysRight_TRANSFER = 1u << 0,
PBSysRight_DUPLICATE = 1u << 1,
PBSysRight_READ = 1u << 4,
PBSysRight_WRITE = 1u << 5,
PBSysRight_MANAGE_PROCESS = 1u << 6, // start & terminate process
PBSysRight_MANAGE_THREAD = 1u << 7, // start & terminate threads
PBSysRight_NETWORK = 1u << 8, // can connect to networks [DEPRECATED]
PBSysRight_OBSERVE = 1u << 9, // can observe signals
PBSysRight_SIGNAL = 1u << 10, // can manage user signals
PBSysRight_GET_PROPERTY = 1u << 11, // can read object properties
PBSysRight_SET_PROPERTY = 1u << 12, // can change object properties
PBSysRight_SAME_RIGHTS = 1u << 31,
};
PBSysScrollFlags
typedef enum PBSysScrollFlags PB_ENUM_TYPE(u16){
PBSysScrollFlag_PRECISE = 1u << 0, // high-resolution scrolling (trackpad)
PBSysScrollFlag_INVERTED = 1u << 1, // "natural" direction applied or not
PBSysScrollFlag_UNIT_LINES = 1u << 2, // deltas are in lines (vs pixels/dp)
PBSysScrollFlag_UNIT_PAGES = 1u << 3, // deltas are pages
} PBSysScrollFlags;
PBSysScrollPhase
typedef enum PBSysScrollPhase PB_ENUM_TYPE(u8){
PBSysScrollPhase_CHANGED = 0, // default if platform doesn't provide phases
PBSysScrollPhase_BEGAN = 1,
PBSysScrollPhase_ENDED = 2,
PBSysScrollPhase_MOMENTUM = 3, // inertia phase (macOS trackpad, iOS)
} PBSysScrollPhase;
PBSysStreamSignals
typedef enum PB_ENUM_TYPE(uint32_t) {
PBSysStreamSignal_READABLE = 1u << 0,
PBSysStreamSignal_WRITABLE = 1u << 1,
PBSysStreamSignal_PEER_CLOSED = 1u << 2,
PBSysStreamSignal_PEER_WRITE_DISABLED = 1u << 3,
PBSysStreamSignal_WRITE_DISABLED = 1u << 4,
} PBSysStreamSignals;
PBSysStreamSignals describe signals available for streams (in addition to USER signals)
PBSysStreamWriteFlags
typedef enum PBSysStreamWriteFlags PB_ENUM_TYPE(u32){
PBSysStreamWrite_SYNC = 1, // complete write immediately or fail with PBSysErr_AGAIN
} PBSysStreamWriteFlags;
PBSysStreamWriteFlags are flags for PBSysStreamWrite
PBSysTextureFormat
typedef enum PB_ENUM_TYPE(u32) {
PBSysTextureFormat_UNKNOWN,
PBSysTextureFormat_RGBA8,
} PBSysTextureFormat;
PBSysTextureFormat describes the pixel format of a texture
PBSysThreadFlags
typedef enum PB_ENUM_TYPE(u64) {
PBSysThread_NOGUI = 1u << 0, // disable GUI (only has an effect on the main thread)
PBSysThread_AUDIO = 1u << 1, // thread produces audio output
} PBSysThreadFlags;
PBSysThreadFlags are flags for PBSysThreadEnter and PBSysThreadStart
PBSysThreadSignals
typedef enum PB_ENUM_TYPE(uint32_t) {
PBSysThreadSignal_RUNNING = 1u << 0,
PBSysThreadSignal_TERMINATED = 1u << 1,
PBSysThreadSignal_WRITABLE = 1u << 2, // room for writing at least one message
PBSysThreadSignal_READABLE = 1u << 3, // at least one message can be read
} PBSysThreadSignals;
PBSysThreadSignals describe signals available for threads (in addition to USER signals)
PBSysWindowRendererInstructionKind
typedef enum PBSysWindowRendererInstructionKind {
PBSysWindowRendererInstructionKind_SHAPE,
PBSysWindowRendererInstructionKind_TEXT,
PBSysWindowRendererInstructionKind_CLIP_PUSH,
PBSysWindowRendererInstructionKind_CLIP_POP,
PBSysWindowRendererInstructionKind_TEXTURE_SET, // set/clear the active texture for SHAPE draws
} PBSysWindowRendererInstructionKind;
PBSysWindowSignals
typedef enum PB_ENUM_TYPE(u32) {
// PBSysWindowSignal_RESIZE is pulsed when the window's size and/or pixel density changes
PBSysWindowSignal_RESIZE = 1u << 0, // pulse
// PBSysWindowSignal_MOVE is pulsed when the window's position on screen change
PBSysWindowSignal_MOVE = 1u << 1, // pulse
/*
PBSysWindowSignal_FRAME_SYNC is pulsed when the window's display finised presenting a frame. You can retrieve the estimated presentation time of the next frame via frameTime from PBSysWindowInfoGet.
*/
PBSysWindowSignal_FRAME_SYNC = 1u << 2,
/*
PBSysWindowSignal_REPAINT is pulsed when the window's content need to be drawn again. This signal is only used on hosts which does not retain the window contents when a window is not displayed on screen.
*/
PBSysWindowSignal_REPAINT = 1u << 3, // pulse
// PBSysWindowSignal_KEY is active when the window is the key window of the application
PBSysWindowSignal_KEY = 1u << 4,
} PBSysWindowSignals;
PBSysWindowSignal_RESIZE is pulsed when the window's size and/or pixel density changes
Constants
Structs
PBSysBuf
typedef struct PBSysBuf {
const uint8_t* nullable bytes;
size_t len;
} PBSysBuf;
PBSysClockInfo
typedef struct PBSysClockInfo {
char timeZoneName[63]; // IANA time zone identifier (e.g. "")
u8 timeZoneNameLen; // length of timeZoneName
} PBSysClockInfo;
PBSysEvent
typedef struct PBSysEvent {
u16 size; // size of the event
u16 type; // PBSysEventType
PBSysObjectId objectId; // originating object ID, e.g. window (0 means "unknown")
} PB_ATTR_ALIGNED(8) PBSysEvent;
PBSysEventLegacy
typedef struct PBSysEventLegacy {
uint16_t type; // PBSysEventLegacyType
uint8_t _reserved[6];
union {
struct { // PBSysEventLegacy_START
uint32_t flags;
uint32_t sysbufSize;
void* sysbuf;
PBSysHandleInfo* nullable handles;
uint32_t handlesCount;
uint64_t arg1, arg2; // values passed to PBSysThreadStart
} start;
struct { // PBSysEventLegacy_READ
int32_t result;
PBSysHandle from;
uint64_t ud; // associated user data
} read;
struct { // PBSysEventLegacy_WRITE
int32_t result;
PBSysHandle to;
uint64_t ud; // associated user data
} write;
struct { // PBSysEventLegacy_INPUT
uint32_t type;
uint32_t window;
uint16_t index;
uint16_t flags;
uint32_t value;
uint32_t extra1;
uint32_t extra2;
} input;
struct { // PBSysEventLegacy_AUDIO_OUT
uint16_t channelCount;
uint16_t _reserved;
uint32_t sampleCount; // per channel
float sampleRate; // HZ
float* samples; // interleaved, channels * sampleCount
} audioOut;
struct { // PBSysEventLegacy_RESIZE
uint32_t width; // TODO(rsms): unit?
uint32_t height; // TODO(rsms): unit?
uint32_t scaleFactor; // percentage. TODO(rsms): change to f32 or f64
} resize;
struct { // PBSysEventLegacy_DISPLAY_SYNC
uint32_t displayId;
uint32_t width;
uint32_t height;
uint32_t scaleFactor;
uint64_t frameTime; // in PBSysOp_CLOCK space
} displaySync;
struct { // PBSysEventLegacy_WGPU_CALLBACK
PBWgpuCallbackKind kind;
PBSysEventLegacy_WgpuCallback data;
} wgpuCallback;
struct { // PBSysEventLegacy_THREAD_EXIT
PBSysHandle thread; // what thread exited
int32_t status; // value passed to PBSysThreadExit
void* sysbuf; // value passed to PBSysThreadStart
uint32_t sysbufSize; // value passed to PBSysThreadStart
uint64_t arg1, arg2; // values passed to PBSysThreadStart
} threadExit;
struct { // PBSysEventLegacy_TIMER
PBSysHandle timer; // what timer rang
} timer;
struct { // PBSysEventLegacy_SIGNAL
PBSysSignals signals;
PBSysHandle handle;
uint64_t ud; // value provided to PBSysObjectObserve
} signal;
uint8_t _info[64];
};
} PBSysEventLegacy;
PBSysEventLegacy describes an event produced by the Playbit system. See sysevents.h for complete definition.
PBSysFileId
typedef struct PBSysFileId {
u8 data[32];
} PBSysFileId;
PBSysFileListEntry
typedef struct PBSysFileListEntry {
u64 id; // file's unique ID within the file system (inode ID or similar)
PBSysFileListEntryType type;
} PBSysFileListEntry;
PBSysGestureEvent
typedef struct PBSysGestureEvent {
PBSysInputEvent inputEvent;
PBSysGesturePhase phase;
u8 _reserved;
u16 flags; // currenty unused
f32 x, y; // gesture center in window coords (dp) if known
f32 dx, dy; // pan delta (dp) for PAN; else 0
f32 scale; // relative scale delta for PINCH (1.0 means no change; e.g. 1.02)
f32 rotation; // relative rotation delta in radians for ROTATE
} PBSysGestureEvent;
PBSysHandleInfo
typedef struct PBSysHandleInfo {
PBSysHandle handle;
PBSysRights rights;
PBSysHandleName name;
PBSysObjectType objectType;
PBSysObjectId objectId;
} PBSysHandleInfo;
PBSysHandlePair
typedef struct PBSysHandlePair {
PBSysHandle a, b;
} PBSysHandlePair;
PBSysInputEvent
typedef struct PBSysInputEvent {
PBSysEvent event;
PBSysTime timestamp; // time the event occurred
u32 clientId; // originating client ID (0 for "local")
u32 deviceId; // stable per HID
u16 modifiers; // PBSysKeyboardModifiers
u16 _reserved;
} PBSysInputEvent;
PBSysKeyboardEvent
typedef struct PBSysKeyboardEvent {
PBSysInputEvent inputEvent;
PBSysKeyboardKey keyCode; // logical code for the key, i.e. "the A key"
PBSysKeyboardKey deviceCode; // physical key, i.e. "3rd key on 4th row"
u32 text[8]; // Unicode representation
u8 textLen; // number of codepoints in text array
u8 _reserved; //
u16 flags; // PBSysKeyboardFlags
} PBSysKeyboardEvent;
PBSysNetConnectConfig
typedef struct PBSysNetConnectConfig {
u64 flags; // unused, set to 0
} PBSysNetConnectConfig;
PBSysNetSessionConfig
typedef struct PBSysNetSessionConfig {
u64 flags; // unused, set to 0
u64 authId; // local auth state key. Use 0 for default.
const u8* nullable serverAddr; // "host:port" as UTF-8 text. Leave empty for default.
u32 serverAddrLen; // number of bytes at serverAddr
} PBSysNetSessionConfig;
PBSysPenPointerEvent
typedef struct PBSysPenPointerEvent {
PBSysPointerEvent pointerEvent;
f32 pressure; // [0..1]
f32 tangentialPressure; // [0..1] barrel pressure (pen)
f32 tiltX, tiltY; // [-1, +1] 0 = perpendicular
f32 twist; // degrees [0, 359]; barrel rotation (pen)
f32 width, height; // contact ellipse in dp (touch/pen)
f32 altitudeAngle; // [0, π/2] radians (0 = parallel, π/2 = perpendicular)
f32 azimuthAngle; // [0, π/2] radians, direction in the screen plane
} PBSysPenPointerEvent;
PBSysPointerEvent
typedef struct PBSysPointerEvent {
PBSysInputEvent inputEvent;
u32 pointerId; // logical; stable per active contact/stream
u16 flags; // PBSysPointerFlags
u16 buttons; // current button bitmask (mouse/pen)
u8 button; // "changed" button for DOWN/UP/CLICK (0 if n/a)
PBSysPointerKind kind; //
u8 clickCount; // for CLICK (and optionally DOWN/UP if platform provides)
u8 _reserved; //
f32 x, y; // position in window coords (dp)
f32 dx, dy; // delta since last event for this pointerId (dp). 0 if unknown.
} PBSysPointerEvent;
PBSysScrollEvent
typedef struct PBSysScrollEvent {
PBSysInputEvent inputEvent;
PBSysPointerKind kind;
PBSysScrollPhase phase;
u16 flags; // PBSysScrollFlags
f32 x, y; // focus point in window coords if known, else 0
f32 dx, dy; // scroll delta (dp or lines/pages depending on flags)
f32 wheelZ; // optional for 3D wheels; else 0
} PBSysScrollEvent;
PBSysSignalEvent
typedef struct PBSysSignalEvent {
PBSysEvent event;
PBSysHandle handle;
PBSysSignals signals;
PBSysSignals pulseSignals;
PBSysObjectType objectType;
u16 _reserved;
} PBSysSignalEvent;
PBSysStr
typedef struct PBSysStr {
uint32_t len;
uint8_t bytes[];
} PBSysStr;
PBSysStreamStats
typedef struct PBSysStreamStats {
PBSysTime timestamp; // time at which the statistics were gathered
/*
bytesReceived indicates the number of bytes received by this stream, up to the first missing byte. The number does not include any network or transport overhead, and can only increase over time.
*/
u64 bytesReceived;
/*
bytesRead indicates the number of bytes the application has read from this stream. This number can only increase, and is always less than or equal to bytesReceived.
*/
u64 bytesRead;
} PBSysStreamStats;
PBSysTextplanSelection
typedef struct PBSysTextplanSelection {
u64 anchor;
u64 caret;
u64 lastDown;
} PBSysTextplanSelection;
PBSysTextplanSelectionRect
typedef struct PBSysTextplanSelectionRect {
i32 x, y;
i32 width, height;
} PBSysTextplanSelectionRect;
PBSysThreadConfig
typedef struct PBSysThreadConfig {
PBSysThreadEntry entry;
u64 arg1, arg2;
// thread stack memory
void* stack;
u32 stackSize;
/*
rights for the new thread's SELF_THREAD handle. Usually you want this to be PBSysRight_SAME_RIGHTS
*/
PBSysRights rights;
// handles to be transferred from the caller to the new thread
const PBSysHandle* nullable transferHandles;
u32 transferHandlesCount;
} PBSysThreadConfig;
PBSysWindowConfig
typedef struct PBSysWindowConfig {
f32 x, y; // location on screen in dp (-1 = default location)
f32 width, height; // content size in dp (0 = default size)
const u8* nullable title; // UTF-8 text
u32 titleLen; // number of bytes at 'title'
u64 _reserved[4];
} PBSysWindowConfig;
PBSysWindowInfo
typedef struct PBSysWindowInfo {
f32 x, y; // position of top-left corner on screen, in dp
f32 width, height; // size of window in dp (including OS decorations)
f32 minWidth, minHeight; // lower limit of width & height
f32 maxWidth, maxHeight; // upper limit of width & height
f32 contentX, contentY; // offset of content relative to the window frame
f32 contentWidth, contentHeight; // size of window contents in dp
f32 dpScale; // number of pixels per dp
u32 _reserved1;
PBSysWindowStyle style;
PBSysTime frameTime; // estimated presentation time of next frame
} PBSysWindowInfo;
PBSysWindowRendererClipItem
typedef struct PBSysWindowRendererClipItem {
struct {
f32 x, y, z, w;
} bounds;
} PBSysWindowRendererClipItem;
PBSysWindowRendererInstruction
typedef struct PBSysWindowRendererInstruction {
PBSysWindowRendererInstructionKind kind;
union {
// a run of renderable "content"
struct {
u32 runLength;
} content;
// TEXTURE_SET: set active texture; PBSysHandle_INVALID clears to default (no texture)
struct {
PBSysHandle texture;
} setTexture;
};
} PBSysWindowRendererInstruction;
PBSysWindowRendererPackage
typedef struct PBSysWindowRendererPackage {
u64 backgroundColor; // 0xAAAARRRRGGGGBBBB
const PBSysWindowRendererShapeItem* shapes;
u32 shapesLen;
u32 shapeSize;
const PBSysWindowRendererTextItem* texts;
u32 textsLen;
u32 textSize;
const PBSysWindowRendererInstruction* instructions;
u32 instructionsLen;
u32 instructionSize;
const PBSysWindowRendererClipItem* clips;
u32 clipsLen;
u32 clipSize;
} PBSysWindowRendererPackage;
PBSysWindowRendererShapeItem
typedef struct PBSysWindowRendererShapeItem {
struct {
f32 x, y, z, w;
} bounds; // (minX, minY, maxX, maxY)
struct {
u16 x, y, z, w;
} cornerRadius; // Per-corner radii (pixels): (tl, tr, br, bl)
u64 fillColor; // 0xAAAARRRRGGGGBBBB
u64 fillColors[4];
u64 strokeColor; // 0xAAAARRRRGGGGBBBB
f32 strokeWidth; // px
u32 flags; // 1=stroke_inside, 2=stroke_outside, 4=clip
f32 blur; // px
f32 opacity; // 0->1 percent
// UV sub-rectangle for texture sampling.
struct {
f32 x, y;
} uvMin; // top-left UV
struct {
f32 x, y;
} uvMax; // bottom-right UV
u8 padding[8];
} PBSysWindowRendererShapeItem;
PBSysWindowRendererTextItem
typedef struct PBSysWindowRendererTextItem {
struct {
f32 x, y, z, w;
} bounds;
PBSysHandle textPlan;
u64 overrideColor; // 0xAAAARRRRGGGGBBBB
u32 flags; // 1=override color
u8 padding[4];
} PBSysWindowRendererTextItem;
See also System events for runtime event handling patterns.