Graphics
PBColor
typedef union PBColor {
struct {
PBF16 r, g, b, a; // rgba16float texel order; little endian u64 = 0xAAAABBBBGGGGRRRR
};
u16 channel[4];
u64 u64;
} PBColor;
PBColor is a color with opacity (alpha) in the canvas working space: linear-light extended Display P3. Channels are binary16 in r,g,b,a memory order — the same layout as an rgba16float texel, so the u64 view is both the canvas wire format and PBSysTextureFormat_RGBAF16 pixel data (the little-endian u64 reads 0xAAAABBBBGGGGRRRR). 1.0 (0x3C00) is SDR white / full SDR primary; values above 1.0 are HDR (EDR headroom), negative RGB values express colors outside the P3 gamut. Alpha is in [0, 1]; constructors clamp it.
Rules:
- RGB channels must be finite. Inf/NaN color words produce undefined rendering (the renderer validates in debug builds only). All PBColor constructors sanitize, so this only concerns hand-built u64 words.
- The render target is also binary16, so an unblended fill stores exactly the channel bits of its PBColor (bit-exact wire == framebuffer).
Three kinds of constructors, named by what the channel values mean:
- PBColorRgb/PBColorRgba: SDR working-space values — linear-light P3 in [0, 1] (clamped).
- PBColorRgbHDR/PBColorRgbaHDR: working-space values without the SDR ceiling — linear-light P3, >1.0 is HDR, negative is out-of-gamut.
- PBColorRgbSrgb/PBColorRgbaSrgb (and the *U32 hex forms): sRGB display values — what a browser or design tool shows for those numbers. These decode the sRGB transfer function AND convert sRGB→P3 primaries, so PBColorRgbSrgbU32(0xFF0000) renders like CSS #F00, not like the (more saturated) full P3 red primary.
PBColorF32
typedef struct PBColorF32 {
f32 r, g, b, a;
} PBColorF32;
PBColorF32 is an unpacked f32 view of a color (same meaning as PBColor channels: linear-light extended Display P3), for arithmetic.
PBHsvColor
typedef struct PBHsvColor {
f32 h, s, v, a;
} PBHsvColor;
PBHsvColor is a color in HSV(A) representation, all fields in [0, 1]. Hue, saturation and value are computed over transfer-encoded P3 channel values (display values, like a color picker shows).
PBColorR
f32 PBColorR(PBColor c);
PBColorR returns the red channel as f32 (linear P3).
PBColorG
f32 PBColorG(PBColor c);
PBColorG returns the green channel as f32 (linear P3).
PBColorB
f32 PBColorB(PBColor c);
PBColorB returns the blue channel as f32 (linear P3).
PBColorA
f32 PBColorA(PBColor c);
PBColorA returns the alpha channel as f32.
PBColorUnpack
PBColorF32 PBColorUnpack(PBColor c);
PBColorUnpack expands the channels to f32.
PBColorPack
PBColor PBColorPack(PBColorF32 c);
PBColorPack builds a color from working-space (linear P3) channel values. Sanitizes: NaN→0, RGB clamped to ±65504, alpha clamped to [0, 1].
PBColorRgb
PBColor PBColorRgb(f32 r,
f32 g,
f32 b);
PBColorRgb constructs an opaque color from SDR working-space values: linear-light P3, all channels clamped to [0, 1].
PBColorRgba
PBColor PBColorRgba(f32 r,
f32 g,
f32 b,
f32 a);
PBColorRgba constructs an RGBA color from SDR working-space values: linear-light P3, all channels clamped to [0, 1].
PBColorRgbHDR
PBColor PBColorRgbHDR(f32 r,
f32 g,
f32 b);
PBColorRgbHDR constructs an opaque color from working-space (linear P3) values without the SDR ceiling: >1.0 is HDR, negative is out-of-gamut. Sanitized like PBColorPack.
PBColorRgbaHDR
PBColor PBColorRgbaHDR(f32 r,
f32 g,
f32 b,
f32 a);
PBColorRgbaHDR constructs an RGBA color from working-space (linear P3) values without the SDR ceiling: >1.0 is HDR, negative is out-of-gamut. Sanitized like PBColorPack.
PBColorRgbSrgb
PBColor PBColorRgbSrgb(f32 r,
f32 g,
f32 b);
PBColorRgbSrgb constructs an opaque color from sRGB display values in [0, 1] (sRGB transfer decode + sRGB→P3 gamut conversion).
PBColorRgbaSrgb
PBColor PBColorRgbaSrgb(f32 r,
f32 g,
f32 b,
f32 a);
PBColorRgbaSrgb constructs an RGBA color from sRGB display values in [0, 1] (sRGB transfer decode + sRGB→P3 gamut conversion).
PBColorRgbSrgbU32
PBColor PBColorRgbSrgbU32(u32 rgb);
PBColorRgbSrgbU32 converts sRGB 0xRRGGBB to an opaque color.
PBColorRgbaSrgbU32
PBColor PBColorRgbaSrgbU32(u32 rgba);
PBColorRgbaSrgbU32 converts sRGB 0xRRGGBBAA to an RGBA color.
PBColorWithAlpha
PBColor PBColorWithAlpha(PBColor c,
f32 a);
PBColorWithAlpha returns c with its alpha replaced (clamped to [0, 1]).
PBColorIsZero
bool PBColorIsZero(PBColor c);
PBColorIsZero reports whether all channels are exactly (+)zero.
PBColorEquals
bool PBColorEquals(PBColor c0,
PBColor c1);
PBColorEquals compares channel bits exactly.
PBColorToU64
u64 PBColorToU64(PBColor x);
PBColorToU64 packs the color for the canvas syscall ABI. PBColor, the wire format and the PBSysTextureFormat_RGBAF16 texel format are the same bits, so this is the identity; it exists for call sites that predate the f16 pipeline.
PBColorToU32
u32 PBColorToU32(PBColor x);
PBColorToU32 packs to 8-bit channels as 0xAARRGGBB. The RGB bytes are display-encoded P3, i.e. the transfer function is applied but no gamut conversion (the 8-bit texture pipeline treats bytes as P3-native, NOT sRGB), so PBColorToU32(PBColorRgbSrgbU32(h)) does not round-trip h.
PBColorToRGBA8
u32 PBColorToRGBA8(PBColor x);
PBColorToRGBA8 packs to 8-bit channels in R,G,B,A memory byte order (for PBSysTextureFormat_RGBA8 texture data). The RGB bytes are display-encoded P3, like PBColorToU32.
PBColorFromRGBA8
PBColor PBColorFromRGBA8(u32 x);
PBColorFromRGBA8 is the inverse of PBColorToRGBA8.
PBColorToPackedRGBA
u32 PBColorToPackedRGBA(PBColor x);
PBColorToPackedRGBA packs to 8-bit channels as 0xRRGGBBAA. The RGB bytes are display-encoded P3, like PBColorToU32.
PBColorToHSV
PBHsvColor PBColorToHSV(PBColor rgb);
PBColorToHSV converts to HSV(A), computed over the transfer-encoded P3 channel values (display values, like a color picker shows).
PBHsvColorToRGB
PBColor PBHsvColorToRGB(PBHsvColor hsv);
PBHsvColorToRGB is the inverse of PBColorToHSV.
PBColorSrgbDecode
f32 PBColorSrgbDecode(f32 encoded);
PBColorSrgbDecode applies the inverse sRGB transfer function (which Display P3 shares) to one channel value in [0, 1]: encoded -> linear.
PBColorSrgbEncode
f32 PBColorSrgbEncode(f32 linear);
PBColorSrgbEncode applies the sRGB transfer function (which Display P3 shares) to one channel value in [0, 1]: linear -> encoded.
PBColor_Black
PBColor_Black is opaque black: PBColorRgb(0, 0, 0) (same color in every space)
PBColor_White
PBColor_White is opaque white: PBColorRgb(1, 1, 1) (same color in every space)
PBColor_Red
PBColor_Red is the opaque P3 red primary: PBColorRgb(1, 0, 0)
PBColor_Green
PBColor_Green is the opaque P3 green primary: PBColorRgb(0, 1, 0)
PBColor_Blue
PBColor_Blue is the opaque P3 blue primary: PBColorRgb(0, 0, 1)
PBColor_Magenta
PBColor_Magenta is opaque P3 magenta: PBColorRgb(1, 0, 1)
PBColor_Yellow
PBColor_Yellow is opaque P3 yellow: PBColorRgb(1, 1, 0)
PBColor_Cyan
PBColor_Cyan is opaque P3 cyan: PBColorRgb(0, 1, 1)
PBColor_Red_sRGB
PBColor_Red_sRGB is opaque sRGB red: PBColorRgbSrgb(1, 0, 0)
PBColor_Green_sRGB
PBColor_Green_sRGB is opaque sRGB green: PBColorRgbSrgb(0, 1, 0)
PBColor_Blue_sRGB
PBColor_Blue_sRGB is opaque sRGB blue: PBColorRgbSrgb(0, 0, 1)
PBColor_Magenta_sRGB
PBColor_Magenta_sRGB is opaque sRGB magenta: PBColorRgbSrgb(1, 0, 1)
PBColor_Yellow_sRGB
PBColor_Yellow_sRGB is opaque sRGB yellow: PBColorRgbSrgb(1, 1, 0)
PBColor_Cyan_sRGB
PBColor_Cyan_sRGB is opaque sRGB cyan: PBColorRgbSrgb(0, 1, 1)
PBUIFont
struct PBUIFont {
PBStrSlice family; // font family name (e.g. PBStrLit("Inter"))
f32 size; // font size in pixels (e.g. 16.0)
f32 weight; // font weight between 100-900
};
PBTextCacheEntry
struct PBTextCacheEntry {
u64 hash;
// key
u8* text; // copied into cache arena
u32 textLen;
u8* fontFamily; // copied into cache arena
u32 fontFamilyLen;
u32 fontSize; // scaled 26.6 fixed point
u32 weight;
u32 color;
f32 maxWidth;
f32 maxHeight;
u32 flags;
// value
PBSysHandle plan;
PBVector2 size;
u64 lastFrame;
bool sticky;
};
PBTextCache
struct PBTextCache {
PBArena* arena; // owns entry array
PBTextCacheEntry* entries;
u64 capacity; // power of two
u64 count;
u64 frame; // incremented each PBTextCacheNextFrame()
// context required to create plans
PBWindow window;
};
PBRender
struct PBRender {
PBArena* arena;
u8* cmds;
u32 cmdsSize;
u32 cmdsCap;
};
PBDrawContext
struct PBDrawContext {
PBArena* arena;
PBRender render;
PBTextCache textCache;
PBWindow window;
PBSysHandle canvas;
f32 scale;
u32 clipDepth;
PBColor backgroundColor;
};
PBTexture
struct PBTexture {
PBSysHandle handle;
};
PBStrokeType
typedef enum PB_ENUM_TYPE(uint32_t) {
PBStrokeType_CENTER = 0,
PBStrokeType_INNER = 1,
PBStrokeType_OUTER = 2,
} PBStrokeType;
PBTextplanWidthOfSize
PBSysTextplanGetSize result macros
PBTextureCreate
PBTexture PBTextureCreate(PBWindow window,
PBSysTextureFormat format,
u32 width,
u32 height,
PBSysTextureCreateFlags flags);
PBTextureCreate creates a GPU texture for window with the given format, dimensions, and flags.
Returns a texture with an invalid handle if the GPU is not yet ready; check with PBTextureIsValid.
PBTextureCreateFromData
PBTexture PBTextureCreateFromData(PBWindow window,
const void* data,
u64 dataSize,
PBSysTextureCreateFlags flags);
PBTextureCreateFromData decodes encoded image bytes (PNG, JPEG, WebP, GIF, BMP, TGA) and
creates an upload-ready GPU texture in one call, with no guest-side pixel buffer.
Returns a texture with an invalid handle on failure; check with PBTextureIsValid.
PBTextureIsValid
bool PBTextureIsValid(PBTexture texture);
PBTextureIsValid returns true if the texture handle is valid (i.e. successfully created).
PBTextureWrite
void PBTextureWrite(PBTexture texture,
u32 originX,
u32 originY,
const void* pixels,
u64 pixelSize,
u32 width,
u32 height);
PBTextureWrite uploads a pixel region to the texture starting at (originX, originY).
pixels must point to at least pixelSize bytes covering a width x height region.
PBTextureDestroy
void PBTextureDestroy(PBTexture* texture);
PBTextureDestroy releases the texture's GPU resources and invalidates the handle.
PBDrawSetGlobal
void PBDrawSetGlobal(PBDrawContext* ctx);
PBDrawSetGlobal sets the thread-local draw context used by PBDraw* calls.
PBDrawGetGlobal
PBDrawContext* PBDrawGetGlobal();
PBDrawGetGlobal returns the active thread-local draw context.
PBDrawInit
void PBDrawInit(PBDrawContext* ctx,
PBArena* arena,
PBWindow window);
PBDrawInit initializes draw/render/text-cache state for window.
PBDrawBeginFrame
void PBDrawBeginFrame(PBWindow window);
PBDrawBeginFrame starts a frame and refreshes window scale and per-frame draw state.
PBDrawEndFrame
void PBDrawEndFrame();
PBDrawEndFrame submits queued commands and advances text-cache frame lifetime.
PBDrawSetScale
void PBDrawSetScale(f32 scale);
PBDrawSetScale sets the drawing scale for the current frame. By default, the scale is set to the window's scale (drawing is in dps, not pixels).
PBDrawSetBackgroundColor
void PBDrawSetBackgroundColor(PBColor color);
PBDrawSetBackgroundColor sets the background color.
PBDrawGetScale
f32 PBDrawGetScale();
PBDrawGetScale gets the drawing scale for the current frame.
PBDrawRect
void PBDrawRect(PBRectangle bounds,
PBColor color);
PBDrawRect enqueues a filled rectangle with square corners.
PBDrawRectExt
void PBDrawRectExt(PBRectangle bounds,
PBColor color,
PBVector4 cornerRadius);
PBDrawRectExt enqueues a filled rectangle with per-corner radius.
PBDrawRectExt2
void PBDrawRectExt2(PBRectangle bounds,
PBColor colorTopLeft,
PBColor colorTopRight,
PBColor colorBottomRight,
PBColor colorBottomLeft,
PBVector4 cornerRadius);
PBDrawRectExt enqueues a filled rectangle with per-corner color and radius.
PBDrawRectOutline
void PBDrawRectOutline(PBRectangle bounds,
PBStrokeType type,
PBColor strokeColor,
f32 strokeWidth,
PBVector4 cornerRadius);
PBDrawRectInset
void PBDrawRectInset(PBRectangle bounds,
PBColor strokeColor,
f32 strokeWidth,
PBVector4 cornerRadius);
PBDrawRectInset enqueues an inset rectangle stroke with configurable width and corner radius.
PBDrawRectWithStroke
void PBDrawRectWithStroke(PBRectangle bounds,
PBColor fillColor,
PBColor strokeColor,
f32 strokeWidth,
PBVector4 cornerRadius);
PBDrawRectWithStroke enqueues an rectangle with both a fill and inset stroke with configurable width and corner radius.
PBDrawText
void PBDrawText(PBUIFont font,
PBStrSlice text,
PBColor color,
PBRectangle bounds);
PBDrawText enqueues text rendering into bounds using font and color. Text is assumed to be single-line text.
PBDrawTextAlign
void PBDrawTextAlign(PBUIFont font,
PBStrSlice text,
PBColor color,
PBRectangle bounds,
PBVector2 alignment,
bool multiline);
PBDrawTextAlign enqueues text rendering aligned within the bounding rectangle.
alignment is a PBVector2 where (0,0)=top-left, (0.5,0.5)=center, (1,1)=bottom-right.
If multiline is true, text wraps within the bounds width.
PBDrawTextLine
void PBDrawTextLine(PBUIFont font,
PBStrSlice text,
PBColor color,
PBVector2 pos,
f32 maxWidth);
PBDrawTextLine draws a single line of text. Optionally you can specify maxWidth and maxHeight (or use 0 if none is desired).
PBDrawTextMultiline
void PBDrawTextMultiline(PBUIFont font,
PBStrSlice text,
PBColor color,
PBVector2 pos,
f32 maxWidth,
f32 maxHeight);
PBDrawTextMultiline draws multiple lines of text. Optionally you can specify maxWidth and maxHeight (or use 0 if none is desired).
PBDrawTextWithPlan
void PBDrawTextWithPlan(PBSysHandle plan,
PBRectangle bounds);
PBDrawTextWithPlan enqueues text rendering into bounds using an existing text plan.
The text plan must not be released until the frame is complete.
PBDrawTextWithPlanAndOverrideColor
void PBDrawTextWithPlanAndOverrideColor(PBSysHandle plan,
PBRectangle bounds,
PBColor color);
PBDrawTextWithPlanAndOverrideColor enqueues text rendering into bounds using an existing text plan; the text is drawn is the specified color, rather than the color specified when the text plan was created.
The text plan must not be released until the frame is complete.
PBDrawMeasureText
PBVector2 PBDrawMeasureText(PBUIFont font,
PBStrSlice text,
f32 maxWidth);
PBDrawMeasureText returns measured text size for the given font and max width constraint (in dps).
PBDrawPushClip
void PBDrawPushClip(PBRectangle bounds);
PBDrawPushClip pushes a clip rectangle onto the clip stack, restricting rendering to bounds.
PBDrawPopClip
void PBDrawPopClip();
PBDrawPopClip pops the most recently pushed clip rectangle from the clip stack.
PBDrawResetClip
void PBDrawResetClip();
PBDrawResetClip pops all clip rectangles from the clip stack.
PBDrawTexturedRect
void PBDrawTexturedRect(PBTexture texture,
PBRectangle bounds);
PBDrawTexturedRect draws a texture mapped to bounds, tinted by tintColor.
Use PBColorRgbaSrgb(1,1,1,1) for no tint.
PBDrawTexturedRectExt
void PBDrawTexturedRectExt(PBTexture texture,
PBRectangle bounds,
PBRectangle uv,
PBColor tintColor,
PBVector4 cornerRadius);
PBDrawTexturedRectExt draws a texture mapped to bounds with per-corner radius and tint color.
PBDrawTexturedRectExt2
void PBDrawTexturedRectExt2(PBTexture texture,
PBRectangle bounds,
PBRectangle uv,
PBColor colorTopLeft,
PBColor colorTopRight,
PBColor colorBottomRight,
PBColor colorBottomLeft,
PBVector4 cornerRadius);
Same as PBDrawTexturedRectExt, but allows you to specify a color for each of the 4 vertices.
PBSysGpuCanvasGetWGPUTexture
WGPUTexture PBSysGpuCanvasGetWGPUTexture(PBSysHandle canvas);
PBSysGpuCanvasGetWGPUDevice
WGPUDevice PBSysGpuCanvasGetWGPUDevice(PBSysHandle canvas);
PBSysGpuCanvasGetWGPUQueue
WGPUQueue PBSysGpuCanvasGetWGPUQueue(PBSysHandle canvas);