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;
PBSysCursorStyleFlags
typedef u64 PBSysCursorStyleFlags;
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;
PBSysGuiPresentation
typedef i64 PBSysGuiPresentation;
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
PBSysNetTransportFlags
typedef u32 PBSysNetTransportFlags;
PBSysNetTransportStreamFlags
typedef u64 PBSysNetTransportStreamFlags;
PBSysNetTransportStreamFlags control behavior of PBSysNetTransportOpenStream
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;
PBSysWindowFullScreenFlags
typedef u64 PBSysWindowFullScreenFlags;
PBSysWindowRenderFlags
typedef u64 PBSysWindowRenderFlags;
PBSysWindowSetRectFlags
typedef u64 PBSysWindowSetRectFlags;
PBSysWindowStyle
typedef u64 PBSysWindowStyle;
PBTextPlanLayoutFlags
typedef u32 PBTextPlanLayoutFlags;
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_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_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_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_ThreadLogWrite = 32,
PBSysCallOp_ThreadNetConnect = 42,
PBSysCallOp_ThreadRead = 76,
PBSysCallOp_ThreadReadRandom = 139,
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_WindowFilePanelCreate = 144,
PBSysCallOp_WindowFrameSyncEnable = 63,
PBSysCallOp_WindowFullScreenGet = 137,
PBSysCallOp_WindowFullScreenSet = 138,
PBSysCallOp_WindowInfoGet = 64,
PBSysCallOp_WindowRendererPackageWrite = 78,
PBSysCallOp_WindowSetCursor = 151,
PBSysCallOp_WindowSetRect = 87,
PBSysCallOp_WindowSetRenderFlags = 152,
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_DEFAULT = 0,
PBSysCursorStyle_ARROW,
PBSysCursorStyle_TEXT,
PBSysCursorStyle_TEXT_VERTICAL,
PBSysCursorStyle_POINTING_HAND,
PBSysCursorStyle_CLOSED_HAND,
PBSysCursorStyle_OPEN_HAND,
PBSysCursorStyle_RESIZE_LEFT,
PBSysCursorStyle_RESIZE_RIGHT,
PBSysCursorStyle_RESIZE_LEFT_RIGHT,
PBSysCursorStyle_RESIZE_UP,
PBSysCursorStyle_RESIZE_DOWN,
PBSysCursorStyle_RESIZE_UP_DOWN,
PBSysCursorStyle_CROSSHAIR,
PBSysCursorStyle_DISAPPEARING_ITEM,
PBSysCursorStyle_NOT_ALLOWED,
PBSysCursorStyle_DRAG_LINK,
PBSysCursorStyle_DRAG_COPY,
PBSysCursorStyle_CONTEXT_MENU,
PBSysCursorStyle_CUSTOM_IMAGE,
} PBSysCursorStyle;
PBSysCursorStyleFlag
enum PBSysCursorStyleFlag PB_ENUM_TYPE(PBSysCursorStyleFlags){
PBSysCursorStyleFlag_HIDDEN = 1 << 0,
};
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,
// 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,
} 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_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;
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;
PBSysGamepadAxis
typedef enum PBSysGamepadAxis PB_ENUM_TYPE(u16){
PBSysGamepadAxis_LEFT_X = 0, PBSysGamepadAxis_LEFT_Y, PBSysGamepadAxis_RIGHT_X,
PBSysGamepadAxis_RIGHT_Y, PBSysGamepadAxis_DPAD_X, PBSysGamepadAxis_DPAD_Y,
PBSysGamepadAxis_LEFT_TRIGGER, PBSysGamepadAxis_RIGHT_TRIGGER, PBSysGamepadAxis_COUNT,
} PBSysGamepadAxis;
PBSysGamepadButton
typedef enum PBSysGamepadButton PB_ENUM_TYPE(u16){
PBSysGamepadButton_A = 0,
PBSysGamepadButton_B,
PBSysGamepadButton_X,
PBSysGamepadButton_Y,
PBSysGamepadButton_LEFT_SHOULDER,
PBSysGamepadButton_RIGHT_SHOULDER,
PBSysGamepadButton_LEFT_TRIGGER,
PBSysGamepadButton_RIGHT_TRIGGER,
PBSysGamepadButton_LEFT_THUMBSTICK,
PBSysGamepadButton_RIGHT_THUMBSTICK,
PBSysGamepadButton_MENU,
PBSysGamepadButton_OPTIONS,
PBSysGamepadButton_HOME,
PBSysGamepadButton_COUNT,
} PBSysGamepadButton;
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;
PBSysGuiPresentationFlag
typedef enum PB_ENUM_TYPE(PBSysGuiPresentation) {
PBSysGuiPresentation_DEFAULT = 0,
PBSysGuiPresentation_HIDE_DOCK = 1 << 1, // dock is disabled
PBSysGuiPresentation_AUTOHIDE_MENU_BAR = 1 << 2, // Menu bar appears when moused to
PBSysGuiPresentation_HIDE_MENU_BAR = 1 << 3, // Menu bar is disabled
PBSysGuiPresentation_DISABLE_PROCESS_SWITCHING = 1 << 4, // Cmd+Tab UI is disabled
PBSysGuiPresentation_DISABLE_FORCE_QUIT = 1 << 5, // Cmd+Tab UI is disabled
PBSysGuiPresentation_DISABLE_LOGOUT = 1 << 6, // Restart/Shut Down/Log Out disabled
PBSysGuiPresentation_DISABLE_CURSOR_HIGHLIGHT = 1 << 7, // disable "Shake mouse to locate"
PBSysGuiPresentation_FULLSCREEN = 1 << 8, // app is in full-screen mode (read only flag)
PBSysGuiPresentation_KIOSK =
PBSysGuiPresentation_HIDE_DOCK | PBSysGuiPresentation_HIDE_MENU_BAR
| PBSysGuiPresentation_DISABLE_PROCESS_SWITCHING | PBSysGuiPresentation_DISABLE_FORCE_QUIT
| PBSysGuiPresentation_DISABLE_LOGOUT,
} PBSysGuiPresentationFlag;
PBSysGuiSignals
typedef enum PB_ENUM_TYPE(PBSysSignals) {
// PBSysGuiSignal_PRESENTATION is pulsed when the application's presentation flags changes
PBSysGuiSignal_PRESENTATION = 1u << 0, // pulse
} PBSysGuiSignals;
PBSysGuiSignal_PRESENTATION is pulsed when the application's presentation flags changes
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
PBSysHidDeviceFlags
typedef enum PBSysHidDeviceFlags PB_ENUM_TYPE(u32){
PBSysHidDevice_HAS_PLAYER_INDEX = 1u << 0, // device can indicate a logical player number
PBSysHidDevice_HAS_HAPTICS = 1u << 1, // device supports haptic feedback
} PBSysHidDeviceFlags;
PBSysHidDeviceType
typedef enum PBSysHidDeviceType PB_ENUM_TYPE(u16){
PBSysHidDeviceType_NONE,
PBSysHidDeviceType_GAMEPAD,
} PBSysHidDeviceType;
PBSysHidHapticsLocality
typedef enum PBSysHidHapticsLocality PB_ENUM_TYPE(u32){
PBSysHidHaptics_DEFAULT = 1u << 0, PBSysHidHaptics_ALL = 1u << 1,
PBSysHidHaptics_HANDLES = 1u << 2, PBSysHidHaptics_LEFT_HANDLE = 1u << 3,
PBSysHidHaptics_RIGHT_HANDLE = 1u << 4, PBSysHidHaptics_TRIGGERS = 1u << 5,
PBSysHidHaptics_LEFT_TRIGGER = 1u << 6, PBSysHidHaptics_RIGHT_TRIGGER = 1u << 7,
} PBSysHidHapticsLocality;
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(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;
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`.
PBSysNetTransportFlag
typedef enum PB_ENUM_TYPE(PBSysNetTransportFlags) {
PBSysNetTransportFlag_TLS = 1u << 0, // enable TLS (DTLS for UDP)
} PBSysNetTransportFlag;
PBSysNetTransportSignals
typedef enum PB_ENUM_TYPE(PBSysSignals) {
PBSysNetTransportSignal_READY = 1u << 0, // connection is established and active
PBSysNetTransportSignal_CLOSED = 1u << 1, // connection is closed
} PBSysNetTransportSignals;
PBSysNetTransportSignals describe signals available for network-transport objects
PBSysNetTransportStreamFlag
typedef enum PB_ENUM_TYPE(PBSysNetTransportStreamFlags) {
PBSysNetTransportStream_READ = 1u << 0, // create a stream that can be read from
PBSysNetTransportStream_WRITE = 1u << 1, // create a stream that can be written to
PBSysNetTransportStream_RW = PBSysNetTransportStream_READ | PBSysNetTransportStream_WRITE,
/*
PBSysNetTransportStream_UNRELIABLE requests an unreliable stream. For QUIC this maps to QUIC DATAGRAM frames, where each write sends one datagram and each read receives one datagram. The flag is ignored for inherently unreliable protocols like UDP. Setting this flag for TCP causes PBSysNetTransportOpenStream to fail with PBSysErr_NOT_SUPPORTED.
*/
PBSysNetTransportStream_UNRELIABLE = 1u << 2,
} PBSysNetTransportStreamFlag;
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.
PBSysObjectType
typedef enum PBSysObjectType PB_ENUM_TYPE(uint16_t){
PBSysObject_None = 0, // invalid
PBSysObject_Audio = 16,
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;
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_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_BGRA8,
} 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)
PBSysWindowFullScreenFlag
typedef enum PB_ENUM_TYPE(PBSysWindowFullScreenFlags) {
PBSysWindowFullScreenFlag_ENABLE = 1 << 0, // enable full-screen (absense means disabled)
} PBSysWindowFullScreenFlag;
PBSysWindowRenderFlag
enum PBSysWindowRenderFlag PB_ENUM_TYPE(PBSysWindowRenderFlags){
/*
PBSysWindowRenderFlag_PRESENT_IMMEDIATE disables display- and/or OS compositor-synchronized rendering.
In certain scenarios this can significantly reduce latency, for example when dragging a UI element on the screen where the OS mouse cursor would be ahead of the dragged element by a few frames.
However, enabling this may lead to visual artifacts like "tearing" if you render (i.e. write renderer package) outside of FRAME_SYNC signals, or if your rendering is taking too long (i.e. if you write a renderer package during GPU framebuffer presentation/flip.)
*/
PBSysWindowRenderFlag_PRESENT_IMMEDIATE = 1 << 0,
};
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 (i.e. write renderer package) outside of FRAME_SYNC signals, or if your rendering is taking too long (i.e. if you write a renderer package during GPU framebuffer presentation/flip.)
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(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;
PBSysWindowSignal_RESIZE is pulsed when the window's size and/or pixel density changes
PBTextPlanLayoutFlag
enum PBTextPlanLayoutFlag PB_ENUM_TYPE(PBTextPlanLayoutFlags){
// PBTextPlanLayout_PREFORMATTED prevents trimming of trailing/leading/duplicate whitespace
PBTextPlanLayout_PREFORMATTED = 1u << 0,
// PBTextPlanLayout_ONE_LINE: Text is placed on a single line; newline characters are ignored
PBTextPlanLayout_ONE_LINE = 1u << 1,
/*
PBTextPlanLayout_ALWAYS_SET_HEIGHT: The computed height (see PBSysTextplanGetSize) will be set to the height of the single line, even if the input text is an empty string.
Implied by PBTextPlanLayout_ONE_LINE.
*/
PBTextPlanLayout_ALWAYS_SET_HEIGHT = 1u << 2,
PBTextPlanLayout_REPLACE_WITH_BULLETS = 1u << 3,
};
PBTextPlanLayout_PREFORMATTED prevents trimming of trailing/leading/duplicate whitespace
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;
PBSysFilePanelEvent
typedef struct PBSysFilePanelEvent {
PBSysEvent event;
PBSysHandle handle;
} PBSysFilePanelEvent;
PBSysGamepadEvent
typedef struct PBSysGamepadEvent {
PBSysInputEvent inputEvent;
u16 control; // PBSysGamepadButton for button events, PBSysGamepadAxis for axis events
u16 flags; // currently unused
f32 value; // scalar value for changed control
f32 x; // x axis for 2D controls, otherwise 0
f32 y; // y axis for 2D controls, otherwise 0
} PBSysGamepadEvent;
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;
PBSysHidDeviceInfo
typedef struct PBSysHidDeviceInfo {
PBSysHidDeviceType type;
PBSysHidDeviceFlags flags;
u32 gamepadAxisMask; // PBSysGamepadAxis bits
u32 gamepadButtonMask; // PBSysGamepadButton bits
u32 hapticsLocalityMask; // PBSysHidHapticsLocality bits
} PBSysHidDeviceInfo;
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;
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;
PBSysNetTransportConfig
typedef struct PBSysNetTransportConfig {
/*
idleTimeoutMs determines how long a connection may stay idle without I/O happening, in milliseconds. Once a connection has been idle for idleTimeoutMs, it's closed (assuming keep-alive is disabled.) A timeout of `0` means "default."
*/
u32 idleTimeoutMs;
PBSysNetTransportFlags flags;
/*
alpn is "Application-Layer Protocol Negotiation" for TLS and QUIC. A semicolon-separated ALPN list, in priority order.
Required to be non-zero for QUIC.
Currently only one ALPN is supported.
*/
const u8* nullable alpn;
u32 alpnLen;
// sni is "Server Name Indication" for TLS and QUIC
const u8* nullable sni;
u32 sniLen;
// certPem is a PEM-encoded root certificate for TLS and QUIC peer verification
const u8* nullable certPem;
u32 certPemLen;
} PBSysNetTransportConfig;
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.