src/lib/lib.h

#ifndef LIB_H
#define LIB_H
 
#include "api/canvas.h"
#include "lib/id.h"
#include "lib/queue.h"
#include "platform/platform.h"
#include "render/render.h"
 
/*
 * Lib runtime (internal): one process-global instance for v1.
 *
 * libStart is A_Init. It spawns the worker that owns Platform + Vulkan +
 * the node tree. Public A_* calls push jobs onto the worker queue.
 * Today libWait() joins until the window dies; the design guide wants
 * A_Wait() as a per-frame pump instead — this header still matches code.
 */
 
/* Worker lifecycle for A_IsOpen / A_Init waiting until the window exists. */
typedef enum {
    LIB_STATE_NONE = 0,    /* not started */
    LIB_STATE_STARTING,    /* thread spawned, window/Vulkan not ready */
    LIB_STATE_READY,       /* A_Wait / creates are legal */
    LIB_STATE_BUSY,        /* reserved */
    LIB_STATE_FAILED,      /* Init failed; A_LastError is set */
    LIB_STATE_STOPPING,    /* reserved */
    LIB_STATE_STOPPED      /* thread exited */
} LibState;
 
/*
 * Spawn the worker: platform window, Vulkan, empty tree. Blocks until
 * READY or FAILED. opt may be NULL (defaults). Returns 0 or -1.
 */
int libStart(int width, int height, const char *title, const CanvasOptions *opt);
 
/* Push a quit job and join the worker (A_CloseWindow). */
void libStop(void);
 
/* Join the worker until it exits (current A_Wait implementation). */
void libWait(void);
 
/* Non-zero while the worker is READY or BUSY. */
int libIsOpen(void);
 
/* Enqueue a job for the worker. own=1 → jobFree will free(data). Returns 0 or -1. */
int libPushToWorker(JobFn fn, void *data, int own);
 
/* Worker → main: enqueue a job for the API thread (callbacks). */
int libPushToMain(JobFn fn, void *data, int own);
 
/* Run one main-thread job if present. Returns 0 if a job ran, -1 if empty. */
int libPopMain(void);
 
/* poll(2) fd that wakes when libPushToMain has work. */
int libMainWakeFd(void);
 
LibState libState(void);
 
/* Mark the next wait/frame as needing a redraw. */
void libMarkDirty(void);
 
/* Worker-owned window; NULL-safe only after start. */
Platform *libPlatform(void);
 
/* Worker-owned renderer. */
Renderer *libRenderer(void);
 
#endif