Skip to content

Latest commit

 

History

History
215 lines (176 loc) · 14.3 KB

c-api.md

File metadata and controls

215 lines (176 loc) · 14.3 KB

The C kit (kit/include/BUI_kit.h)

Everything the Python APIs draw is a tree of kit nodes. You can use the kit directly from C: link bui::kit (it pulls in bui::gpu and bui::core).

add_subdirectory(BUI)
target_link_libraries(myapp PRIVATE bui::kit)

Hello from C

examples/kit_hello.c (cmake --build build --target bui_kit_hello, with -DBUI_BUILD_EXAMPLES=ON):

#include <stdio.h>
#include "BUI_kit.h"

static void on_event(void *data, BKNode *node, int kind, void *ref, double a, double b)
{
  if (kind == BK_EV_CLICK) {
    printf("clicked %s\n", BK_get_str(node, "text"));
  }
  else if (kind == BK_EV_CHANGE) {
    printf("%s = %g\n", BK_get_str(node, "label"), BK_get_num(node, "value"));
  }
}

int main(void)
{
  BKNode *root = BK_node_new("frame");
  BK_set_num(root, "padding", 8);

  BKNode *size = BK_node_new("slider");
  BK_set_str(size, "label", "Size");
  BK_set_num(size, "min", 0);
  BK_set_num(size, "max", 10);
  BK_set_num(size, "value", 2.5);
  BK_node_add(root, size, -1);              /* -1: append */
  BK_geom_set_manager(size, BK_GEOM_PACK);  /* Tk's packer */
  BK_geom_set(size, "fill", 1);             /* fill x */

  BKNode *apply = BK_node_new("button");
  BK_set_str(apply, "text", "Apply");
  BK_node_add(root, apply, -1);
  BK_geom_set_manager(apply, BK_GEOM_PACK);
  BK_geom_set(apply, "fill", 1);
  BK_geom_set(apply, "pady0", 6);

  BKContext *ctx = BK_context_new(root);
  BKHost host = {0};
  host.emit = on_event;                     /* the window fills in the rest */
  BK_context_set_host(ctx, &host);

  if (BK_window_supported()) {              /* Win32, X11, Cocoa */
    BKWindow *win = BK_window_new(ctx, "BUI from C", 320, 120);
    BK_window_show(win);
    BK_window_run();
    BK_window_free(win);
  }
  else {                                    /* elsewhere: render to a raster */
    BuiRaster *r = BUI_raster_create(320, 120);
    BK_render(ctx, r, 320, 120, 1);
    BUI_raster_free(r);
  }
  BK_context_free(ctx);
  BK_node_free(root);
  return 0;
}

Concepts

Concept API
Nodes BK_node_new(type), BK_node_add(parent, child, index), BK_node_remove, BK_node_child(_count), BK_node_parent, BK_node_rect, BK_node_natural, BK_node_invalidate, BK_node_relayout, BK_node_free
Properties BK_set_num / BK_set_str / BK_set_color / BK_set_strs and BK_get_*, by name ("value", "text", "label", "min", "items", "enabled" ...). "set_value" sets a value and notifies.
Geometry BK_geom_set_manager(node, BK_GEOM_PACK / GRID / PLACE), BK_geom_set(node, key, v) (side, fill, expand, anchor, padx0..., row, column, sticky, x, relx, reqwidth ...), BK_frame_grid_weight. Children of frame and canvas nodes.
Context BK_context_new(root): input state, popups, focus, undo. Input goes in with BK_press, BK_release, BK_motion, BK_wheel, BK_key, BK_key_release, BK_button, BK_context_menu (input methods: BK_ime_event, BK_ime_state, see below); frames come out of BK_render(ctx, raster, w, h, full), which returns the number of redrawn regions (0 means nothing changed). BK_configure(ctx, w, h) reports a new window size (BK_EV_CONFIGURE) without drawing, so a host whose handlers rebuild the tree (the Rust binding) can do that before the first draw at the new size; BK_render calls it itself.
Host BKHost: request (schedule a render), set_cursor, warp, clipboard, schedule (timers), emit (events). A BKWindow provides all of them.
Events emit(data, node, kind, ref, a, b). Kinds: BK_EV_CHANGE, CLICK, CALL (menu item or hotkey), RENAME, ACTIVATE, TOGGLE, BROWSE, SUBMIT. With the "events" property you also get raw PRESS / RELEASE / DOUBLE / MOTION / ENTER / LEAVE / KEY / KEYRELEASE / WHEEL / CONFIGURE, plus VIEW and SCROLL for scrolling.
Windows BK_window_new, show, close, set_title, set_size, wm(key, a, b) (position, topmost, alpha, override, transparent, resizable, minsize, state; on Wayland also layer and anchor for wlr-layer-shell), callbacks on_timer, on_close, on_frame, on_focus, timer, run, pump, quit
GPU rendering BUI_gpu_set_default(1) (all new windows), BK_window_set_gpu(win, 1) (one window), BK_window_gpu(win) (1 once frames draw on the GPU). BUI_GPU=1/0 overrides. For your own rasters: BUI_raster_gpu_attach(r, hwnd_or_NULL, wait), BUI_raster_gpu_poll, BUI_raster_is_gpu.
Theme BK_set_theme("dark" / "light") (Blender's Dark or Light preset; every context relayouts and redraws), BK_theme_name(), BK_theme_color(key, rgba) ("region_bg", "text", "regular.inner", or the plain-English and Blender keys of a theme file: "button.background", "user_interface.wcol_regular.inner"). Your own themes: BK_theme_load_file(path) / BK_theme_load_json(text) register the themes of a JSON theme file (-1 and BK_theme_error() on a mistake), BK_set_theme(name) chooses one, BK_theme_set_color(key, rgba) / BK_theme_set_num(key, v) change one value of the active theme (colors, roundness, border.width, corners.top_left, ...), BK_set_font_size(points) sets the UI text size; see theming.md. Without a call, BUI_THEME=dark|light picks the theme. BK_set_scale sets the UI scale; BK_set_text_shadow(0) turns off Blender's UI text shadows (on by default; Python turns them off).
Text BUI_text_measure, BUI_raster_text, BUI_text_add_font(family, flags, data, len) (register a font; needed on wasm)
Raster alpha BUI_raster_set_alpha(r, 1) keeps premultiplied alpha in a CPU raster, BUI_raster_clear makes it transparent, BUI_raster_alpha reads the setting. An opaque raster draws the same bytes as before.
Specialised Canvas display list (BK_canvas_set_item), text area (BK_textarea_*), trees (BK_tree_item_*), menus (BK_open_menu, BK_open_pie), the hit test (BK_hit_at), color ramps and curves, BK_undo / BK_redo
Custom nodes A custom node draws and handles input itself: BK_custom_set(node, &cls, data) with event (pointer with all three buttons and a grab, precise wheel via BK_scroll, keys and text while focused, key releases, focus), frame (called by BK_render when requested with BK_custom_request_frame(node, ms): immediate-mode UIs build their frame there) and draw (raster + rect). BK_custom_set_cursor, BK_node_context. Dear ImGui runs on it: ../bindings/imgui.
File browser BK_node_new("filebrowser"): Blender's File Browser in any window. Strings dir, file, button, search; numbers mode (0 open, 1 save, 2 directory), multiple, hidden, sort, invert; list filters ("Label\tpattern ..."); read state and result. BK_file_dialog(title, mode, dir, file, filters, n, multiple, &paths) runs one in its own window and returns the number of chosen paths (free them with BK_file_dialog_free).
Meshes and textures BUI_texture_create/update/free (RGBA8, shared by every raster and GPU device), BUI_raster_mesh(r, vertices, n, indices, n_idx, flags, tex, clip, ox, oy): indexed triangles with position, UV and color, straight-alpha blending, per-call clip; the same pixels on the software raster, Direct3D 11 and OpenGL.
GPU effects Your own pixel shader over a canvas item: BK_effect_create(name, source, n_inputs, n_floats) (an id > 0, 0 for bad arguments), BK_effect_free, BK_effect_error(id) (the compile/link log of the last GPU attempt: "" when fine, NULL for an unknown id), then a BK_ITEM_EFFECT canvas item (effect, effect_inputs[8] BUI textures, effect_floats; its image is the fallback), or BUI_raster_effect on a raster. The source is GLSL with a small compat set, compiled at run time by Direct3D 11 (d3dcompiler_47.dll, loaded dynamically) and OpenGL; the software raster draws the fallback. See GPU effects.

Node types: frame column row grid box panel tabs sidetabs scroll scrollbar label separator progress button toggle checkbox radio decorator text search hotkey number slider dropdown enum swatch popover menubutton menubar list tree gridview canvas textarea image ramp curve normal histogram custom.

Read the header for the full list. It is the reference: every function has a one-line comment.

Images

kit/intern/image decodes images for every binding (Blender's imbuf design: one BKImBuf type and a format table): PNG, GIF, BMP, TGA, QOI (Wuffs), JPEG (libjpeg-turbo), WebP (libwebp), Radiance HDR, PNM and SVG.

BKImageInfo info;
BK_image_probe(data, len, &info);               /* header only: format, size, frames */
BKImBuf *ib = BK_imbuf_decode(data, len, 256, 256); /* any thread; fit within, never upscaled */
int w, h, frames = BK_imbuf_size(ib, &w, &h);
const uint32_t *px = BK_imbuf_pixels(ib, 0);    /* premultiplied 0xAARRGGBB */
BK_imbuf_free(ib);

/* files on nodes and canvas items: decoded on worker threads at the drawn size */
BK_node_set_image_source(image_node, "photo.jpg", BK_FIT_COVER);
BKCanvasItem it = {.type = BK_ITEM_IMAGE, .coords = box, .ncoords = 4,
                   .src = "photo.jpg", .fit = BK_FIT_COVER};
BK_image_set_budget(128u << 20);                /* the shared cache */

The window hosts wake for finished decodes; a host with its own loop calls BK_image_poll() (or sets BK_image_set_notify). BK_image_exit() joins the workers and frees the cache.

Animated GIF and WebP sources play by themselves (only while on screen, on the context's frame timer: BKHost.schedule with BK_TIMER_CUSTOM); a canvas item's frame (or BK_node_set_image_frame) holds frame n - 1, and BK_set_animations(0) holds them all. To step one yourself: BK_anim_open, then BK_anim_next for each frame and its delay; BK_imbuf_texture_update puts a frame into a texture.

Video

BK_video_* (kit/intern/image/video.c) plays video files through the OS decoders (Media Foundation, GStreamer, AVFoundation; loaded at run time), decoded at the size drawn, in one GPU texture per player, and only while it shows. It autoplays with its sound, played on the default output (WASAPI, CoreAudio, PulseAudio / PipeWire); the frames follow the sound, which plays on while the video is off screen (the picture catches up when it shows again). Only the file's first audio track plays, and each video with sound owns one output stream and thread, so many videos are many streams. The output opens on that thread (up to about 2 s on some drivers; the readers wait at most 3 s to preroll and 2 s per block), never on the UI thread: BK_video_free returns at once and the stream is released on a thread of its own (BK_image_exit waits up to 2 s for those at shutdown). With no output device a video plays silent and tries again every 5 s.

BKVideo *v = BK_video_new("intro.mp4");     /* loads when first drawn */
BK_video_set_loop(v, 1);
BK_video_set_controls(v, 1);                /* Blender-style controls on "video" nodes */
BK_video_set_listener(v, on_state, app);    /* BK_VIDEO_LOADING .. ENDED, ERROR */
BKNode *n = BK_node_new("video");
BK_node_set_video(n, v, BK_FIT_CONTAIN);    /* or a canvas item's .video */
BK_video_seek(v, 10.0);
BK_video_set_rate(v, 2.0);                  /* the sound pauses at rates other than 1 */
BK_video_set_muted(v, 1);                   /* or BK_video_set_volume(v, 0.5) */
BK_video_set_audio_effects(v, 1);           /* keep the system's audio effects (Windows plays RAW otherwise) */
int tex = BK_video_texture(v, 0, 640, 360); /* Dear ImGui: the frame in a texture */
BK_video_free(v);                           /* after nodes / items let go */

BK_video_backends() names what the build has. Optional parts (image formats, video, the GPU renderers, the file browser) are CMake options from features.json; see Binary size.

Versioning and stability

The C API is versioned with BUI itself, as MAJOR.MINOR.PATCH. BUI_kit.h says which version it is, and the library reports its own:

#include "BUI_kit.h"

#if !BUI_KIT_VERSION_AT_LEAST(0, 4, 0)
#  error "BUI 0.4.0 or newer is required"
#endif

/* at run time, when the header and the library can differ (a shared build, a binding) */
if (BK_version() != BUI_KIT_VERSION) {
    fprintf(stderr, "BUI %s linked, header is %s\n", BK_version_string(), BUI_KIT_VERSION_STRING);
}

The macros are BUI_KIT_VERSION_MAJOR, _MINOR, _PATCH, BUI_KIT_VERSION_STRING ("0.4.0") and BUI_KIT_VERSION (one number: 0.4.0 is 400, 1.2.3 is 10203). The Python wheels, Rust crates and npm packages carry the same number, and a release is refused when any of them differs.

Before 1.0 there is no promise that the API stays the same. Any release may add to it, and a release may change or remove a function. Every change that breaks existing code is listed under "C API changes" in CHANGELOG.md, with what to use instead. Pin a release number, not a commit.

From 1.0 on, semantic versioning:

  • a MAJOR release may break the API;
  • a MINOR release only adds to it;
  • a PATCH release only fixes bugs;
  • a function marked BUI_DEPRECATED stays for at least one MINOR release, and the compiler warns where you use it.

ABI. Nodes, contexts and the other handles are opaque and stay that way. The structs you fill in or read (BKHost, BKMenuSpec, BKImageInfo, BKImageStats, BKCanvasItem, BKCustomEvent) can gain fields before 1.0, so rebuild against the header of the library you link.

Showing the kit in your own window

The kit always draws into a BuiRaster: the software raster, or Direct3D 11 / OpenGL instances when the window is on the GPU. To put kit widgets inside your own renderer or framework, render the context into a raster with BK_render(ctx, raster, w, h, full), upload or blit its pixels (32-bit 0x00RRGGBB, rows top-down), and feed input back with BK_press, BK_motion, BK_key and friends. bui.qt.BuiCanvas does exactly this inside a Qt widget.

A different layer: render sinks

Render sinks (api/bui_c_api.h, bui_set_render_sink) are not how the kit draws. They receive the triangles, lines, points and text runs of the immediate-mode GPU seam (gpu/intern/gpu_null.c), which the Qt/QPainter backend, the SVG recorder and buipy.demo_scene use. Kit widgets never pass through a sink. See ../INTEGRATION.md.