/* BUI kit: Blender's interface as a retained-mode C runtime. * * A tree of nodes (layouts, buttons, fields, menus, views, editors), one * input context per window, and a renderer that draws Blender's widgets — * ported from editors/interface/interface_widgets.cc — into a BuiRaster. * * Rendering is damage driven: every state change marks only the node's * rectangle dirty, and a frame redraws and diffs just those regions, so an * idle UI costs nothing and a hover or a scrub costs microseconds. * * Hosts (Python, Qt, a native window) only forward input, present the * raster and receive callbacks through BKHost. * * SPDX-License-Identifier: GPL-2.0-or-later */ #pragma once #include "GPU_raster.h" /* ---- Version and stability ------------------------------------------------ * * The C API is versioned with BUI itself, as MAJOR.MINOR.PATCH: this header, * the Python wheels, the Rust crates and the npm packages all carry the same * number (tools/check_versions.py fails a release when they differ). * * 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, 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, and a deprecated * function (BUI_DEPRECATED) stays for at least one MINOR release. * * 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. BK_version() reports the version of the * library at run time; compare it with BUI_KIT_VERSION from this header when * the two can differ (a shared build, a binding). */ #define BUI_KIT_VERSION_MAJOR 0 #define BUI_KIT_VERSION_MINOR 5 #define BUI_KIT_VERSION_PATCH 1 #define BUI_KIT_VERSION_STRING "0.5.1" /* One number to compare: 0.4.0 is 400, 1.2.3 is 10203. */ #define BUI_KIT_VERSION \ (BUI_KIT_VERSION_MAJOR * 10000 + BUI_KIT_VERSION_MINOR * 100 + BUI_KIT_VERSION_PATCH) #define BUI_KIT_VERSION_AT_LEAST(major, minor, patch) \ (BUI_KIT_VERSION >= (major) * 10000 + (minor) * 100 + (patch)) /* Marks a function that will be removed; the compiler warns where it is used. */ #if defined(__GNUC__) || defined(__clang__) # define BUI_DEPRECATED(message) __attribute__((deprecated(message))) #elif defined(_MSC_VER) # define BUI_DEPRECATED(message) __declspec(deprecated(message)) #else # define BUI_DEPRECATED(message) #endif #ifdef __cplusplus extern "C" { #endif /* The version of the library you are linked against: BUI_KIT_VERSION as it was * when the library was built, and the same as "MAJOR.MINOR.PATCH". */ int BK_version(void); const char *BK_version_string(void); typedef struct BKNode BKNode; typedef struct BKContext BKContext; typedef struct BKTreeItem BKTreeItem; /* Modifier / button state bits for input calls. */ enum { BK_SHIFT = 1, BK_CTRL = 2, BK_ALT = 4, BK_BUTTON1 = 8, BK_BUTTON2 = 16, BK_BUTTON3 = 32 }; /* Mouse cursors requested through BKHost.set_cursor. */ enum { BK_CURSOR_DEFAULT = 0, BK_CURSOR_EW, /* Blender's horizontal arrows over number fields */ BK_CURSOR_NS, BK_CURSOR_TEXT, BK_CURSOR_CROSSHAIR, /* eyedropper, color areas */ BK_CURSOR_HAND, BK_CURSOR_MOVE, /* panel grip */ BK_CURSOR_NONE, /* hidden: continuous grab while scrubbing */ BK_CURSOR_NESW, /* diagonal resize (bottom-left / top-right corner) */ BK_CURSOR_NWSE, /* diagonal resize (top-left / bottom-right corner) */ BK_CURSOR_NOT_ALLOWED, BK_CURSOR_WAIT, BK_CURSOR_PROGRESS, /* busy in the background, still interactive */ }; /* Callback kinds delivered through BKHost.emit. */ enum { BK_EV_CHANGE = 1, /* the node's value changed */ BK_EV_CLICK, /* button pressed */ BK_EV_CALL, /* menu item / hotkey: call `ref` */ BK_EV_RENAME, /* list/tree rename: a = row/item index, text via BK_get_str("edit") */ BK_EV_ACTIVATE, /* grid view double-click / Return: a = index */ BK_EV_TOGGLE, /* tree toggle column: a = column, b = new value, item = ref */ BK_EV_BROWSE, /* path field browse button */ /* Raw events, for nodes with the "events" property (Tk bind, Qt event * handlers): a, b = position relative to the node. */ BK_EV_PRESS, BK_EV_RELEASE, BK_EV_DOUBLE, BK_EV_MOTION, BK_EV_ENTER, BK_EV_LEAVE, BK_EV_KEY, /* ref = "text keysym" (UTF-8), a = mods */ BK_EV_WHEEL, /* a = delta */ BK_EV_SUBMIT, /* text field confirmed (Return) */ BK_EV_VIEW, /* scrolled view changed (nodes with "viewevents") */ BK_EV_SCROLL, /* scrollbar request: a = 0 moveto (b = fraction), 1 units, 2 pages (b = count) */ BK_EV_CONFIGURE, /* geometry changed ("events" nodes): a = width, b = height */ BK_EV_KEYRELEASE, /* ref = "\tkeysym", a = mods */ BK_EV_AREA, /* a screen's areas: a = the area's child index, b = BK_AREA_* (see "screen") */ BK_EV_MOVE, /* a panel was dragged to a new place: a = old index, b = new index */ BK_EV_RESIZE /* an area's region was resized, hidden or shown: a = size, b = hidden */ }; typedef struct BKHost { void *data; void (*request)(void *data); /* schedule a render */ void (*set_cursor)(void *data, int cursor); void (*warp)(void *data, int x, int y); /* move the pointer */ char *(*clipboard_get)(void *data); /* malloc'd UTF-8 or NULL */ void (*clipboard_set)(void *data, const char *text); void (*schedule)(void *data, int ms, int timer); /* call BK_timer(timer) later */ void (*emit)(void *data, BKNode *node, int kind, void *ref, double a, double b); } BKHost; /* Reference hooks for host objects attached to nodes/items/callbacks * (Python INCREF/DECREF). Optional. */ void BK_set_ref_hooks(void (*retain)(void *ref), void (*release)(void *ref)); /* -- global look ------------------------------------------------------------ */ void BK_set_scale(float scale); /* Blender's resolution scale (1 = 20 px widgets) */ float BK_scale(void); /* Blender's UI text shadows (drop shadow, soft one on panel titles); on by default */ void BK_set_text_shadow(int on); int BK_text_shadow(void); int BK_unit(void); /* U.widget_unit in pixels */ void BK_set_font(const char *family); /* The UI text size in points (Blender's UI_DEFAULT_TEXT_POINTS is 11, the default). Browser-look * controls keep their own 13.33 px. */ void BK_set_font_size(float points); float BK_font_size_points(void); /* Themes: Blender's two presets, "dark" (Blender_Dark.xml = the built-in * default) and "light" (Blender_Light.xml), any case ("Blender Light" works * too). Every context relayouts and redraws (its host gets a request). * Returns 0 for an unknown name (the theme stays). Without a call the * BUI_THEME environment variable (dark|light) picks the first theme. */ int BK_set_theme(const char *name); const char *BK_theme_name(void); /* "dark" or "light" */ /* A color of the active theme as RGBA 0..1: "region_bg", "header_bg", * "tabs_bg", "panel_header", "panel_back", "panel_sub_back", "panel_outline", * "text", "text_hi", "emboss", "cursor", "selection", "file_back", * "file_text", "file_header", "file_row_alternate", "node_back", "node_grid", * "node_wire", "node_body", "node_outline", "node_selected", "node_active", * "area_header", or * "." for a widget color set (regular tool toggle radio option * textfield num numslider menu pulldown menu_back menu_item list_item box * scroll progress tooltip tab pie_menu curve; outline outline_sel inner * inner_sel item text text_sel), e.g. "regular.inner". 0 when unknown. */ int BK_theme_color(const char *key, float r_rgba[4]); /* Custom themes. A theme file is JSON in the shape of gpui-kit's, with Blender's own color names: * * { "name": "My themes", "themes": [ { "name": "My Dark", "mode": "dark", * "font.family": "Inter", "font.size": 11, "radius": 0.4, "shadow": true, * "colors": { "background": "#181825", "primary.background": "#89b4fa", * "button.background": "#302d41", "button.corners.top_left": false, * "button.border.width": 2, "node_editor.grid": "#1e1e2e" } } ] } * * A theme starts from the built-in theme named by "mode" ("dark" or "light") and changes what it * lists. "colors" takes plain-English keys ("button.background"), Blender's names * ("user_interface.wcol_regular.inner") and short palette names ("primary.background"), which fill * in several keys; keys the theme sets itself win over the short names. Keys BUI has no use for yet * are ignored (BK_theme_ignored counts them). docs/theming.md lists every key, and * docs/theme-schema.json is a JSON Schema for editors. * * Per widget (button, tool_button, toggle_button, radio_button, checkbox, text_field, number_field, * slider, menu, dropdown, popup, menu_item, list_item, box, scrollbar, progress_bar, tooltip, tab, * pie_menu): border, border.selected, background, background.selected, fill, text, text.selected * (colors), gradient.enabled, gradient.top, gradient.bottom, roundness, border.width (pixels, 0 for * none), emboss.enabled, and corners.top_left / top_right / bottom_left / bottom_right (false keeps * that corner square). */ /* Register the themes of a theme file's text (or file). Returns how many were added (a theme with * the name of an earlier one replaces it) or -1 with a message in BK_theme_error(). Nothing is added * from a file with an error in it. Choose one with BK_set_theme(its name). */ int BK_theme_load_json(const char *json); int BK_theme_load_file(const char *path); const char *BK_theme_error(void); int BK_theme_ignored(void); /* keys of the last load that BUI has no use for */ /* Those keys are not lost: a color ("#rrggbb") or a number a theme lists that BUI has no field for * is the theme's own, and BK_theme_color / BK_theme_num read it by that key while the theme is in * use ("muted.foreground": "#8696A0"; the application decides what it means). */ int BK_theme_count(void); /* registered themes */ const char *BK_theme_at(int index); /* their names, NULL past the end */ /* Set one value of the active theme now (until the next BK_set_theme): a color by key as above, or * a number / boolean (roundness, border.width, gradient.top, emboss.enabled, corners.*, ...). * Return 0 for an unknown key. BK_theme_color reads colors by these keys too. */ int BK_theme_set_color(const char *key, const float rgba[4]); int BK_theme_set_num(const char *key, double value); int BK_theme_num(const char *key, double *r_value); /* For hosts that derive their own colors from the theme (a stylesheet, say): a number that changes * whenever any theme value does, and the built-in theme ("dark" or "light") the active one is * based on. */ int BK_theme_generation(void); const char *BK_theme_mode(void); int BK_icon_id(const char *name); /* 0 when unknown */ int BK_icon_count(void); const char *BK_icon_name(int id); /* Every icon name (Blender's SVG icons, then BUI-only ones), for listings. */ int BK_icon_list_count(void); const char *BK_icon_list_name(int i); /* -- nodes -------------------------------------------------------------------- */ /* Types: column row grid box panel tabs sidetabs scroll label separator * progress button toggle checkbox decorator text search hotkey number slider * dropdown enum swatch popover menubutton menubar list tree gridview ramp * curve normal histogram radio textarea meter custom (see "custom nodes" below) * screen area areaheader sidebar (see "screens, areas and regions" below) */ BKNode *BK_node_new(const char *type); void BK_node_free(BKNode *node); const char *BK_node_type(const BKNode *node); void BK_node_set_ref(BKNode *node, void *ref); /* host object (not retained) */ void *BK_node_ref(const BKNode *node); /* A borrowed wrapper for a C-owned node (a panel body, a popup, a picker * part): retained by the node until it is freed, so host handlers stay * reachable for the node's lifetime. */ void BK_node_set_borrowed_ref(BKNode *node, void *ref); void *BK_node_borrowed_ref(const BKNode *node); int BK_node_add(BKNode *parent, BKNode *child, int index); /* index -1: append */ void BK_node_remove(BKNode *parent, BKNode *child); int BK_node_child_count(const BKNode *node); BKNode *BK_node_child(const BKNode *node, int i); BKNode *BK_node_parent(const BKNode *node); void BK_node_rect(const BKNode *node, int r_rect[4]); void BK_node_natural(BKNode *node, int r_size[2]); void BK_node_invalidate(BKNode *node); /* redraw */ void BK_node_relayout(BKNode *node); /* size/structure changed */ /* Properties by name (see kit_props in kit_core.c for the list). Return 0 when * the key is unknown for this node. * * "html" (number, any node, default 0): 1 switches the node to the browser * look — Chrome's default form controls (2020+ refresh, Windows, light) — * for drawing, natural size and interaction; 0 keeps Blender's. Values, * events and the other properties behave the same in both. It may change at * any time (the node relayouts). Classes with a browser look: button, toggle * (as a button, pressed while on), checkbox, radio, text, search, number * (typed, with spin buttons), slider (: absolute drag), * dropdown (), progress * ("factor" < 0: indeterminate), meter, textarea. Others ignore it. * Natural sizes at scale 1: text/number 153x21, button text+16 x 21, * checkbox/radio 20x19 (13px box + 3px 3px 3px 4px margins, label after it), * range 129x16, select widest+24 x 19, color 50x27, progress 160x16, * meter 80x16, textarea 182 x (rows*15+6) with rows 2 unless "rows" is set. * Dropdown items starting with '\x01' are labels in the html look * (bold, not selectable, the following options indented). * "meter" nodes: value in min..max (default 0..1) plus "low", "high", * "optimum" (the HTML meter's green / yellow / red regions). */ int BK_set_num(BKNode *node, const char *key, double value); int BK_set_str(BKNode *node, const char *key, const char *value); int BK_set_color(BKNode *node, const char *key, const float rgba[4]); int BK_set_strs(BKNode *node, const char *key, const char *const *values, int n); double BK_get_num(BKNode *node, const char *key); const char *BK_get_str(BKNode *node, const char *key); int BK_get_color(BKNode *node, const char *key, float r_rgba[4]); int BK_strs_count(BKNode *node, const char *key); const char *BK_strs_get(BKNode *node, const char *key, int i); /* Link number fields edited together with Alt (vector fields). */ void BK_link_fields(BKNode *const *fields, int n); /* Color ramp / curve / histogram data. */ int BK_ramp_count(BKNode *ramp); void BK_ramp_get(BKNode *ramp, int i, float *r_pos, float r_rgba[4]); void BK_ramp_set(BKNode *ramp, const float *pos, const float (*rgba)[4], int n); int BK_ramp_active(BKNode *ramp); void BK_ramp_evaluate(BKNode *ramp, float t, float r_rgba[4]); int BK_curve_count(BKNode *curve, int channel); void BK_curve_get(BKNode *curve, int channel, int i, float r_xy[2]); void BK_curve_set(BKNode *curve, int channel, const float (*xy)[2], int n); float BK_curve_evaluate(BKNode *curve, int channel, float x); void BK_ramp_set_active_color(BKNode *ramp, const float rgba[4]); void BK_histogram_set(BKNode *hist, const float *bins, int n, int channels); /* Grid view preview colors (alpha 0 = use the item's icon). */ void BK_gridview_set_colors(BKNode *grid, const float (*colors)[4], int n); /* Tree items (owned by their host ref; trees retain the refs). */ BKTreeItem *BK_tree_item_new(const char *label, int icon); void BK_tree_item_free(BKTreeItem *item); void BK_tree_item_set_ref(BKTreeItem *item, void *ref); void *BK_tree_item_ref(const BKTreeItem *item); BKTreeItem *BK_tree_item_parent(const BKTreeItem *item); /* NULL for a root */ void BK_tree_item_add(BKTreeItem *parent, BKTreeItem *child); void BK_tree_item_clear(BKTreeItem *parent); /* detach (and release) all children */ void BK_tree_item_set(BKTreeItem *item, const char *key, double value); double BK_tree_item_get(const BKTreeItem *item, const char *key); void BK_tree_item_set_label(BKTreeItem *item, const char *label); const char *BK_tree_item_label(const BKTreeItem *item); int BK_tree_item_child_count(const BKTreeItem *item); BKTreeItem *BK_tree_item_child(const BKTreeItem *item, int i); void BK_tree_set_roots(BKNode *tree, BKTreeItem *const *roots, int n); BKTreeItem *BK_tree_selected(BKNode *tree); void BK_tree_select(BKNode *tree, BKTreeItem *item); int BK_tree_row_count(BKNode *tree); BKTreeItem *BK_tree_row(BKNode *tree, int row); void BK_tree_row_rect(BKNode *tree, int row, int r_rect[4]); /* Menus. A spec array describes items; nested submenus via `sub`. */ typedef struct BKMenuSpec { const char *text; /* NULL or "-" = separator */ int icon; const char *shortcut; int checked; /* -1 none, 0/1 checkbox */ int enabled; void *ref; /* callable for BK_EV_CALL (retained while open) */ const struct BKMenuSpec *sub; int nsub; void (*fn)(void *data); /* C callback (built-in menus), used when set */ void *data; } BKMenuSpec; void BK_menubutton_set_items(BKNode *button, const BKMenuSpec *items, int n); void BK_open_menu(BKContext *ctx, BKNode *owner, const BKMenuSpec *items, int n, const char *title, int at_x, int at_y); /* The interactive node under (x, y) in window pixels (ui_but_find_mouse_over): the top popup * first, then the header and the root. NULL over nothing. A pie answers for the whole window. */ BKNode *BK_hit_at(BKContext *ctx, int x, int y); /* The pie centre is (at_x, at_y) in window pixels, or the pointer when either is -100000. */ void BK_open_pie( BKContext *ctx, const BKMenuSpec *items, int n, const char *title, int at_x, int at_y); /* -- geometry managers (children of a "frame") ------------------------------------ * Tk's pack / grid / place, also used for Qt layouts. Keys (numbers): * pack: side (0 top, 1 bottom, 2 left, 3 right), fill (1 x, 2 y, 3 both), * expand, anchor (BK_ANCHOR_*), padx0 padx1 pady0 pady1 ipadx ipady * grid: row column rowspan columnspan sticky (BK_ANCHOR_* bits) + pads * place: x y relx rely width height relwidth relheight anchor * Any manager: reqwidth / reqheight override the natural size (Tk width=). */ enum { BK_GEOM_NONE = 0, BK_GEOM_PACK, BK_GEOM_GRID, BK_GEOM_PLACE }; enum { BK_ANCHOR_N = 1, BK_ANCHOR_S = 2, BK_ANCHOR_W = 4, BK_ANCHOR_E = 8 }; void BK_geom_set_manager(BKNode *child, int manager); int BK_geom_manager(const BKNode *child); void BK_geom_set(BKNode *child, const char *key, double value); double BK_geom_get(const BKNode *child, const char *key); /* Frame grid weights (Tk columnconfigure / Qt setColumnStretch). */ void BK_frame_grid_weight(BKNode *frame, int column_axis, int index, double weight, int minsize); /* -- screens, areas and regions (Blender's editors/screen) ------------------------------ * "screen" (bScreen): areas on a graph of shared vertices and edges. The user drags an edge * between areas to resize them (Shift: move every aligned edge; Ctrl: snap to fractions and * other edges; Escape or right-click cancels), and drags an area's corner to split it (inside * the area), join it into a neighbor, dock it beside or into any other area (left, right, top, * bottom, or center to replace it), or out of the window (BK_AREA_WINDOW). Ctrl-drag on a * corner swaps two areas. Right-click on an edge or a header offers the same as a menu, with * Maximize Area (Ctrl+Space) and Focus Mode (Ctrl+Alt+Space). * * Its children are "area" nodes. The first is added with BK_node_add and fills the screen; the * others come from BK_area_split, BK_area_dock and the user. Removing an area (BK_node_remove) * closes it: a neighbor takes its place. * screen properties: "layout" (string: the arrangement, to save and restore; set it after the * areas exist: it applies to them in child order), "ops" (string: "all", or * "resize" for edges only), "transparent" (number: 1 = the host draws what * is inside the regions, the screen only edges and handles; the screen then * sends BK_EV_CONFIGURE whenever an area or region moved, so the host lays * its content out again, and leaves the pointer to the host's content) * screen events: BK_EV_AREA with BK_AREA_NEW (a = the new area's child index; the screen * made it, the host fills it) and BK_EV_CHANGE (the layout changed: save * "layout"). Areas get BK_EV_AREA with BK_AREA_CLOSE and BK_AREA_WINDOW * themselves (a = their child index), so a host that handles events later * still knows which. * * "area" (ScrArea): "editor" (string, which editor it shows: new areas copy it, the host fills * them on BK_AREA_NEW), "full" (string: "", "maximized" or "focus"). An area also works on its * own, outside a screen. Its children are regions and one main view: a child is a region when * it is an "areaheader" (a header), a "sidebar" (the sidebar) or has the "region" property: * "header", "tool_header", "footer", "asset_shelf", "channels", "nav_bar", "toolbar", * "sidebar", "execute" or "hud" (floating, the Adjust Last Operation panel). One of each. * region properties: "size" (unscaled pixels across the area), "hidden", "overlap" (drawn over * the main view, the default for toolbars, sidebars, tool headers, footers), * "resizable", "maxsize", "side" ("left", "right", "top", "bottom": the * ones its type allows), "hotkey" (toggles it while the pointer is over the * area: "n", "t", "ctrl+]" ...) * region events: BK_EV_RESIZE (a = size, b = hidden) when the user resizes, hides, shows * or flips it * * Setters return 0 for a value they don't take (a second region of a type, a side the type * can't be on, an unknown name). * * Panels ("panel") in a region: drag one by its grip to reorder (BK_EV_MOVE when it lands * elsewhere: lists of panels reorder their data); in a sidebar with category tabs Shift+click * on a header pins the panel ("pinned": shown in every category; BK_EV_TOGGLE, a = -1, b = * pinned), and a click on the pin unpins it. */ typedef enum { BK_AXIS_H = 'h', BK_AXIS_V = 'v' } BKScreenAxis; /* the new edge's direction */ typedef enum { BK_DOCK_LEFT, BK_DOCK_RIGHT, BK_DOCK_TOP, BK_DOCK_BOTTOM, BK_DOCK_CENTER } BKDock; enum { BK_AREA_NEW = 1, /* a new area (a split): fill it for its "editor" */ BK_AREA_CLOSE, /* the area is about to leave the screen (joined, closed, docked away) */ BK_AREA_WINDOW /* the user dragged the area out of the window: open it in one */ }; /* Splits `area` at `factor` (0..1, from the left or bottom): the new area (the side past 0.5) or * NULL when the area is too small. */ BKNode *BK_area_split(BKNode *area, BKScreenAxis axis, float factor); /* `gone` joins into `keep`, neighbors along an edge (trimming what overhangs). 0: not neighbors. */ int BK_area_join(BKNode *keep, BKNode *gone); /* Moves `area` beside `target` (taking `factor` of it) or into its place (BK_DOCK_CENTER). */ int BK_area_dock(BKNode *area, BKNode *target, BKDock where, float factor); int BK_area_swap(BKNode *a, BKNode *b); int BK_area_close(BKNode *area); /* 0: no neighbor to take its place */ /* -- images (kit/intern/image: Blender's imbuf design) ---------------------------------- * One decoder per format for every binding: PNG, GIF (animated), BMP, TGA, QOI, PNM * (Wuffs), JPEG (libjpeg-turbo, DCT-scaled thumbnails, EXIF orientation), WebP * (libwebp: lossy, lossless, animated), Radiance HDR, SVG (nanosvg; BUI_IMAGE_SVG). * Pixels are premultiplied 0xAARRGGBB, decoded at the size they are drawn. * Synchronous decodes run on any thread; the cache and loader are UI-thread APIs. */ typedef struct BKImBuf BKImBuf; enum { BK_IMAGE_NONE = 0, BK_IMAGE_PNG, BK_IMAGE_JPEG, BK_IMAGE_WEBP, BK_IMAGE_GIF, BK_IMAGE_BMP, BK_IMAGE_TGA, BK_IMAGE_QOI, BK_IMAGE_HDR, BK_IMAGE_PNM, BK_IMAGE_SVG, BK_IMAGE_VIDEO, /* a frame of a BKVideo */ }; /* CSS object-fit */ enum { BK_FIT_FILL = 0, BK_FIT_CONTAIN, BK_FIT_COVER, BK_FIT_NONE, BK_FIT_SCALE_DOWN }; typedef struct BKImageInfo { int format; /* BK_IMAGE_* */ int width, height, frames; } BKImageInfo; /* Header only (no pixels): 0 when the data is not an image BUI reads. */ int BK_image_probe(const void *data, size_t len, BKImageInfo *r_info); int BK_image_probe_file(const char *path, BKImageInfo *r_info); const char *BK_image_format_name(int format); /* "png", NULL for unknown */ /* Decode (any thread). max_w/max_h: fit within, never upscaled; 0 = no limit. * NULL on failure. Free with BK_imbuf_free. */ BKImBuf *BK_imbuf_decode(const void *data, size_t len, int max_w, int max_h); BKImBuf *BK_imbuf_load(const char *path, int max_w, int max_h); BKImBuf *BK_imbuf_from_rgba(const unsigned char *rgba, int w, int h, int stride); /* straight RGBA */ BKImBuf *BK_imbuf_from_argb(const uint32_t *argb, int w, int h); /* premultiplied */ void BK_imbuf_free(BKImBuf *ib); int BK_imbuf_size(const BKImBuf *ib, int *r_w, int *r_h); /* returns the frame count */ int BK_imbuf_format(const BKImBuf *ib); const uint32_t *BK_imbuf_pixels(const BKImBuf *ib, int frame); /* premultiplied 0xAARRGGBB */ int BK_imbuf_delay(const BKImBuf *ib, int frame); /* ms; 0 for stills */ int BK_imbuf_loops(const BKImBuf *ib); /* 0 = forever */ int BK_imbuf_rgba(const BKImBuf *ib, int frame, unsigned char *dst); /* straight RGBA, w*h*4 */ /* Frame `frame` alone (GIF / animated WebP decode up to it; stills: frame 0). */ BKImBuf *BK_imbuf_decode_frame(const void *data, size_t len, int frame, int max_w, int max_h); /* A BUI_texture_* (RGBA) holding a frame, for Dear ImGui and textured meshes; * free with BUI_texture_free. 0 on failure. */ int BK_imbuf_texture(const BKImBuf *ib, int frame); /* Replaces texture `tex` (same size) with a frame: an animation's next one. */ int BK_imbuf_texture_update(const BKImBuf *ib, int frame, int tex); /* An animation stepped by the caller (GIF, animated WebP): one frame at a * time at the size drawn (fit within max_w x max_h; 0 = free), looping. * The data is copied. NULL when it is not an animation BUI reads. */ typedef struct BKAnim BKAnim; BKAnim *BK_anim_open(const void *data, size_t len, int max_w, int max_h); /* The next frame (yours: BK_imbuf_free) and how long to show it; NULL on errors. */ BKImBuf *BK_anim_next(BKAnim *anim, int *r_delay_ms); /* Intrinsic size and loop count (0 = forever); returns the frame count. */ int BK_anim_info(const BKAnim *anim, int *r_w, int *r_h, int *r_loops); void BK_anim_free(BKAnim *anim); /* -- video (kit/intern/image: one player for GIF, WebP and video) --------------------- * A