Reference

API Reference

Complete C API documentation for building native PlexyDesk applications. Every function, type, and constant—fully documented.

Header Files

plexy.h

Core API for connections, windows, buffers, and rendering.

plexy_event_loop.h

Event loop with timers, idle callbacks, and fd watches.

plexy_protocol.h

Protocol structures, opcodes, and constants. 

#include <plexy.h>
#include <plexy_event_loop.h>

// Link with: -lplexy

Connection

Establish and manage connections to the compositor.

plexy_connect

Establishes a connection to the PlexyDesk compositor.

Declaration

PlexyConnection* plexy_connect(const char* socket_path);

Parameters

socket_path Path to the compositor socket, or NULL to use the default (/tmp/plexy.sock).

Return Value

A pointer to a PlexyConnection on success, or NULL on failure.

Example

PlexyConnection* conn = plexy_connect(NULL);
if (!conn) {
    fprintf(stderr, "Failed to connect to compositor\n");
    return 1;
}

plexy_disconnect

Closes the connection and releases all associated resources.

Declaration

void plexy_disconnect(PlexyConnection* conn);

Parameters

conn The connection to close. May be NULL.

Discussion

All windows and buffers associated with the connection are automatically destroyed. After calling this function, the connection pointer is invalid.

plexy_get_fd

Returns the file descriptor for the compositor connection.

Declaration

int plexy_get_fd(PlexyConnection* conn);

Return Value

The socket file descriptor, suitable for use with poll() or select().

Discussion

Use this to integrate with external event loops. Poll for POLLIN and call plexy_dispatch() when data is available.

plexy_dispatch

Reads and processes incoming messages from the compositor. Blocks until data is available.

Declaration

int plexy_dispatch(PlexyConnection* conn);

Return Value

Number of messages processed on success, 0 on timeout, or -1 on error (connection closed).

plexy_dispatch_pending

Processes any pending messages without blocking.

Declaration

int plexy_dispatch_pending(PlexyConnection* conn);

Return Value

Number of messages processed, or -1 on error.

plexy_flush

Sends all pending requests to the compositor.

Declaration

int plexy_flush(PlexyConnection* conn);

Return Value

0 on success, or -1 on error.

plexy_get_ui_scale

Returns the global UI scale factor for the display.

Declaration

float plexy_get_ui_scale(PlexyConnection* conn);

Return Value

The UI scale factor (e.g., 1.0, 1.5, 2.0).

plexy_get_screen_size

Retrieves the screen dimensions in pixels.

Declaration

void plexy_get_screen_size(PlexyConnection* conn, 
                           uint32_t* width, 
                           uint32_t* height);

Parameters

width Pointer to receive the screen width.
height Pointer to receive the screen height.

Windows

Create and manage application windows.

plexy_create_window

Creates a new top-level window.

Declaration

PlexyWindow* plexy_create_window(PlexyConnection* conn, 
                                  int32_t x, int32_t y,
                                  uint32_t width, uint32_t height,
                                  const char* title);

Parameters

conn The compositor connection.
x, y Initial position, or -1 for compositor placement.
width, height Window dimensions in pixels.
title Window title (may be NULL).

Return Value

A pointer to the new window, or NULL on failure.

Example

PlexyWindow* win = plexy_create_window(conn, -1, -1, 800, 600, 
                                       "My Application");
if (!win) {
    fprintf(stderr, "Failed to create window\n");
    return 1;
}

plexy_create_popup

Creates a popup window relative to a parent window.

Declaration

PlexyWindow* plexy_create_popup(PlexyConnection* conn,
                                PlexyWindow* parent,
                                int32_t x, int32_t y,
                                uint32_t width, uint32_t height);

Discussion

Popups are transient windows without decorations, positioned relative to their parent. Use for menus, tooltips, and dropdowns.

plexy_destroy_window

Destroys a window and releases its resources.

Declaration

void plexy_destroy_window(PlexyWindow* window);

plexy_window_set_callbacks

Sets the callback functions for window events.

Declaration

void plexy_window_set_callbacks(PlexyWindow* window, 
                                const PlexyWindowCallbacks* callbacks, 
                                void* user_data);

Example

static void on_close(PlexyWindow* win, void* data) {
    bool* running = (bool*)data;
    *running = false;
}

static void on_pointer_motion(PlexyWindow* win, int32_t x, int32_t y, void* data) {
    printf("Mouse: %d, %d\n", x, y);
}

// Set callbacks
bool running = true;
PlexyWindowCallbacks callbacks = {
    .close = on_close,
    .pointer_motion = on_pointer_motion,
};
plexy_window_set_callbacks(win, &callbacks, &running);

Window Properties

// Get window ID
uint32_t plexy_window_get_id(PlexyWindow* window);

// Get window dimensions
void plexy_window_get_size(PlexyWindow* window, 
                           uint32_t* width, uint32_t* height);

// Get logical size (accounting for scale)
void plexy_window_get_logical_size(PlexyWindow* window, 
                                   uint32_t* width, uint32_t* height);

// Get buffer size (pixels to allocate)
void plexy_window_get_buffer_size(PlexyWindow* window, 
                                  uint32_t* width, uint32_t* height);

// Get scale factors
float plexy_window_get_scale(PlexyWindow* window);
uint32_t plexy_window_get_buffer_scale(PlexyWindow* window);

// User data
void plexy_window_set_user_data(PlexyWindow* window, void* user_data);
void* plexy_window_get_user_data(PlexyWindow* window);

Buffers

Manage pixel buffers for rendering.

plexy_create_buffer

Creates a shared memory buffer for software rendering.

Declaration

PlexyBuffer* plexy_create_buffer(PlexyConnection* conn, 
                                 uint32_t width, uint32_t height, 
                                 uint32_t format);

Parameters

format PLEXY_FORMAT_ARGB8888, PLEXY_FORMAT_XRGB8888, or PLEXY_FORMAT_RGBA8888

Example

PlexyBuffer* buf = plexy_create_buffer(conn, 800, 600, PLEXY_FORMAT_ARGB8888);
uint32_t* pixels = (uint32_t*)plexy_buffer_get_data(buf);

// Draw red rectangle
for (int i = 0; i < 800 * 600; i++) {
    pixels[i] = 0xFFFF0000;  // ARGB: opaque red
}

plexy_create_buffer_from_dmabuf

Creates a buffer from a DMA-BUF file descriptor for zero-copy GPU sharing.

Declaration

PlexyBuffer* plexy_create_buffer_from_dmabuf(PlexyConnection* conn,
                                              int fd,
                                              uint32_t width,
                                              uint32_t height,
                                              uint32_t stride,
                                              uint32_t format,
                                              uint64_t modifier);

Parameters

fd DMA-BUF file descriptor (e.g., from GBM).
format DRM fourcc format code (e.g., DRM_FORMAT_ARGB8888).
modifier DRM format modifier, or DRM_FORMAT_MOD_INVALID.

Discussion

Use DMA-BUF for GPU-accelerated applications. The buffer memory is shared directly between the client GPU and compositor without copying.

Buffer Functions

// Get pointer to pixel data (SHM buffers only)
void* plexy_buffer_get_data(PlexyBuffer* buffer);

// Get buffer stride (bytes per row)
uint32_t plexy_buffer_get_stride(PlexyBuffer* buffer);

// Get buffer dimensions
uint32_t plexy_buffer_get_width(PlexyBuffer* buffer);
uint32_t plexy_buffer_get_height(PlexyBuffer* buffer);

// Attach buffer to window
int plexy_window_attach(PlexyWindow* window, PlexyBuffer* buffer);

// Commit pending changes (displays the buffer)
int plexy_window_commit(PlexyWindow* window);

// Commit with damage region for partial updates
int plexy_window_commit_damage(PlexyWindow* window, 
                               int32_t x, int32_t y, 
                               int32_t width, int32_t height,
                               int32_t cursor_x, int32_t cursor_y,
                               int32_t cols, int32_t rows);

// Destroy buffer
void plexy_destroy_buffer(PlexyBuffer* buffer);

Event Callbacks

Callback types for handling window and input events.

PlexyWindowCallbacks Structure

typedef struct {
    // Window configuration changed
    void (*configure)(PlexyWindow* window, uint32_t width, uint32_t height, 
                      void* user_data);
    
    // Window close requested
    void (*close)(PlexyWindow* window, void* user_data);
    
    // Pointer entered window
    void (*pointer_enter)(PlexyWindow* window, int32_t x, int32_t y, 
                          void* user_data);
    
    // Pointer left window
    void (*pointer_leave)(PlexyWindow* window, void* user_data);
    
    // Pointer moved
    void (*pointer_motion)(PlexyWindow* window, int32_t x, int32_t y, 
                           void* user_data);
    
    // Mouse button event
    void (*pointer_button)(PlexyWindow* window, uint32_t button, bool pressed, 
                           int32_t x, int32_t y, void* user_data);
    
    // Scroll/axis event
    void (*pointer_axis)(PlexyWindow* window, int32_t axis, int32_t value, 
                         int32_t discrete, void* user_data);
    
    // Keyboard key event
    void (*key)(PlexyWindow* window, uint32_t keycode, bool pressed, 
                uint32_t modifiers, void* user_data);
    
    // Modifier state changed
    void (*modifiers)(PlexyWindow* window, uint32_t depressed, uint32_t latched,
                      uint32_t locked, uint32_t group, void* user_data);
    
    // Window gained focus
    void (*focus_in)(PlexyWindow* window, void* user_data);
    
    // Window lost focus
    void (*focus_out)(PlexyWindow* window, void* user_data);
    
    // Frame was displayed
    void (*frame_done)(PlexyWindow* window, void* user_data);
    
    // Display scale changed
    void (*scale_changed)(PlexyWindow* window, float scale_factor, 
                          uint32_t buffer_scale, void* user_data);
    
    // Window entered an output
    void (*enter_output)(PlexyWindow* window, uint32_t output_id, void* user_data);
    
    // Window left an output
    void (*leave_output)(PlexyWindow* window, uint32_t output_id, void* user_data);
} PlexyWindowCallbacks;

Important

All callbacks are optional. Set unused callbacks to NULL. The user_data pointer is passed to every callback and can be used to pass application state.

Layer Surfaces

Create panels, docks, and overlays.

plexy_create_layer_surface

Creates a layer surface anchored to screen edges.

Declaration

PlexyLayerSurface* plexy_create_layer_surface(PlexyConnection* conn,
                                               PlexyLayer layer,
                                               PlexyAnchor anchor,
                                               uint32_t width,
                                               uint32_t height,
                                               uint32_t exclusive_zone,
                                               int32_t margin_x,
                                               int32_t margin_y);

Parameters

layer PLEXY_LAYER_BACKGROUND, BOTTOM, TOP, or OVERLAY
anchor Combination of PLEXY_ANCHOR_TOP, BOTTOM, LEFT, RIGHT
exclusive_zone Pixels reserved on the anchored edge, or 0 for none.

Example

// Create a bottom dock panel
PlexyLayerSurface* dock = plexy_create_layer_surface(
    conn,
    PLEXY_LAYER_TOP,
    PLEXY_ANCHOR_BOTTOM | PLEXY_ANCHOR_LEFT | PLEXY_ANCHOR_RIGHT,
    0,      // width: stretch to anchors
    64,     // height: 64px tall
    64,     // exclusive_zone: reserve 64px at bottom
    0, 0    // margins
);

Layer Surface Functions

// Destroy layer surface
void plexy_destroy_layer_surface(PlexyLayerSurface* surface);

// Get surface ID
uint32_t plexy_layer_surface_get_id(PlexyLayerSurface* surface);

// Get surface dimensions
void plexy_layer_surface_get_size(PlexyLayerSurface* surface, 
                                  uint32_t* width, uint32_t* height);

// Set callbacks
void plexy_layer_surface_set_callbacks(PlexyLayerSurface* surface, 
                                       const PlexyLayerSurfaceCallbacks* callbacks, 
                                       void* user_data);

// Attach and commit buffer
int plexy_layer_surface_attach(PlexyLayerSurface* surface, PlexyBuffer* buffer);
int plexy_layer_surface_commit(PlexyLayerSurface* surface);

Event Loop

Integrated event loop with timers and callbacks.

#include <plexy_event_loop.h>

// Create event loop
PlexyEventLoop* plexy_event_loop_create(PlexyConnection* conn);

// Destroy event loop
void plexy_event_loop_destroy(PlexyEventLoop* loop);

// Add a repeating timer (returns timer ID)
uint32_t plexy_event_loop_add_timer(PlexyEventLoop* loop, 
                                     int interval_ms,
                                     PlexyTimerCallback callback,
                                     void* userdata);

// Remove a timer
void plexy_event_loop_remove_timer(PlexyEventLoop* loop, uint32_t timer_id);

// Add an idle callback (runs when no events pending)
uint32_t plexy_event_loop_add_idle(PlexyEventLoop* loop,
                                    PlexyIdleCallback callback,
                                    void* userdata);

// Remove idle callback
void plexy_event_loop_remove_idle(PlexyEventLoop* loop, uint32_t idle_id);

// Watch a file descriptor
uint32_t plexy_event_loop_add_fd(PlexyEventLoop* loop,
                                  int fd,
                                  PlexyFdCallback callback,
                                  void* userdata);

// Stop watching fd
void plexy_event_loop_remove_fd(PlexyEventLoop* loop, uint32_t fd_id);

// Run the event loop (blocks until quit)
int plexy_event_loop_run(PlexyEventLoop* loop);

// Stop the event loop
void plexy_event_loop_quit(PlexyEventLoop* loop);

// Check if running
int plexy_event_loop_is_running(PlexyEventLoop* loop);

Callback Types

// Timer callback: return 0 to keep timer, non-zero to remove
typedef int (*PlexyTimerCallback)(void* userdata);

// Idle callback: return 0 to keep idle, non-zero to remove
typedef int (*PlexyIdleCallback)(void* userdata);

// File descriptor callback: return 0 to keep watching, non-zero to remove
typedef int (*PlexyFdCallback)(int fd, void* userdata);

Constants

Predefined values for formats, buttons, and modifiers.

Pixel Formats

#define PLEXY_FORMAT_ARGB8888  0  // Alpha, Red, Green, Blue (8 bits each)
#define PLEXY_FORMAT_XRGB8888  1  // Ignored, Red, Green, Blue (no alpha)
#define PLEXY_FORMAT_RGBA8888  2  // Red, Green, Blue, Alpha

Mouse Buttons

#define PLEXY_BTN_LEFT   0x110
#define PLEXY_BTN_RIGHT  0x111
#define PLEXY_BTN_MIDDLE 0x112

Keyboard Modifiers

#define PLEXY_MOD_SHIFT  (1 << 0)
#define PLEXY_MOD_CTRL   (1 << 1)
#define PLEXY_MOD_ALT    (1 << 2)
#define PLEXY_MOD_SUPER  (1 << 3)

Layer Types

enum PlexyLayer {
    PLEXY_LAYER_BACKGROUND = 0,  // Desktop wallpaper
    PLEXY_LAYER_BOTTOM = 1,      // Below normal windows
    PLEXY_LAYER_TOP = 2,         // Above windows (panels/docks)
    PLEXY_LAYER_OVERLAY = 3      // Topmost (notifications/lock)
};

Anchor Flags

enum PlexyAnchor {
    PLEXY_ANCHOR_NONE   = 0,
    PLEXY_ANCHOR_TOP    = 1,
    PLEXY_ANCHOR_BOTTOM = 2,
    PLEXY_ANCHOR_LEFT   = 4,
    PLEXY_ANCHOR_RIGHT  = 8
};

// Anchor combinations
// Top panel: PLEXY_ANCHOR_TOP | PLEXY_ANCHOR_LEFT | PLEXY_ANCHOR_RIGHT
// Right sidebar: PLEXY_ANCHOR_TOP | PLEXY_ANCHOR_BOTTOM | PLEXY_ANCHOR_RIGHT

See Also

Protocol Specification →

Wire protocol details for implementing custom clients.

Code Examples →

Complete working examples using the API.

Menu
Overview Features Founders Roadmap Developer FAQ
Become a Founder