Skip to content

Architecture ​

Layers ​

  • Fortran API (figure and the modules it re-exports, figure_testing apart: the modules): Fortran arguments and kinds (int32, real32, real64, logical, character(len=*)), optional arguments, generic interfaces. Strings are converted here (NUL-terminated for cimgui and cimplot), logical to c_bool and back, values copied into C locals for the call.
  • Raw layer, internal: figure_cimgui, figure_cimplot and figure_cimplot3d, the bind(C) interfaces of every public cimgui, cimplot and cimplot3d function Fortran can call directly, and their _enums modules, every public enumerator. All six are generated by scripts/gen_bindings.py from the libraries' metadata and checked for drift in CI (Raw bindings). figure_c_native holds the hand-written interfaces of FIGURE's own glue and the status codes.
  • C APIs (cimgui, cimplot): the C functions generated from Dear ImGui and ImPlot, compiled into libfigure_native.a.
  • Glue (native/figure_native.cpp, native/figure_native.h): what the C APIs cannot offer to Fortran directly (see below), and everything the platform needs: the three modes, the frame loop, the input, the capture. Beside it, one file per subsystem, among them figure_swrast.cpp (the CPU renderer of the frame's draw data, below), figure_remote.cpp (the remote mode's server), figure_process.cpp and figure_task.cpp (programs started from the program and their reader threads, tasks on worker threads: Processes and tasks), figure_items.cpp (the items of each frame, for the paths of Headless testing) and figure_view3d.cpp (the 3-D views' rasterizer, 3-D views).
  • Styles and themes (native/figure_theme.cpp, native/figure_style_generated.cpp): the theme files of themes/, embedded at build time and parsed by the glue; every style colour and variable reached by name, through a table of the style fields generated from the libraries' metadata (Styles).
  • Platform: SDL3 (window, input, display scale) and OpenGL 3, through the official Dear ImGui backends, in window mode. Headless and remote modes open no window and do not start SDL (no SDL_Init): SDL3 serves them for its portable threads, locks and processes.

Modes and renderers ​

The program draws the same way in the three modes; what differs is who turns Dear ImGui's draw data into pixels:

ModeStarted byDraws the framePictures (save_image, test_capture, FIGURE_CAPTURE)
windowapp%initthe GPU, through SDL3 and Dear ImGui's OpenGL 3 backendread back from the GPU
headlessapp%init_headlessnothing: the draw data is built and droppedthe CPU renderer, native/figure_swrast.cpp
remoteapp%init_remotethe browser: the draw lists go to the page, which draws them with WebGLthe CPU renderer, on the program's side

FIGURE has two CPU rasterizers, which do different work:

  • The CPU renderer (native/figure_swrast.cpp) draws a frame's draw data, the whole interface, as the OpenGL 3 backend asks a GPU to; it runs only for a picture of headless or remote mode (Screenshots and videos).
  • The 3-D views' rasterizer (native/figure_view3d.cpp) draws a view3d_object's meshes into an RGBA image, in every mode, window included; the image is then one texture in the draw data, which the GPU, the browser or the CPU renderer draws like any other (Why a software renderer).

The modules ​

The modules use figure re-exports, and figure_testing (generated from their doc comments):

ModuleWhat it holds
figure_appthe application: window, frame loop and lazy redraw.
figure_baseerror handling and string conversion shared by the FIGURE modules.
figure_canvasan area that takes the mouse and drawing primitives: the way to build a widget FIGURE does not have.
figure_dockdocking: windows docked into one another or into a dock space, and layouts set by the program.
figure_editora code editor (code_editor_object) with highlighting, marks, completion and find, and a text diff.
figure_filesfiles and folders: make, remove, time, test, the same on every platform.
figure_groupwidgets that group other widgets: child regions, headers, tabs, tables, trees, id scopes, disabled blocks,
figure_imguiDear ImGui widgets with Fortran arguments.
figure_implotImPlot plots with Fortran arrays.
figure_implot3dsmall 3-D figures with Fortran arrays (ImPlot3D).
figure_markdownMarkdown in the window: a text at the cursor (ig_markdown) and documents (markdown_view_object).
figure_menumenus, popups and keyboard shortcuts.
figure_numbersnumbers and choices: fields, drag boxes and sliders for integers and reals, scalar or vector; angles;
figure_playera player for snapshots: previous, play, next, a slider, a speed and a loop mode.
figure_processprograms started from the program (process_object) and a view of their output (log_view_object).
figure_styleevery colour and variable of the Dear ImGui, ImPlot and ImPlot3D styles, by name.
figure_taskbackground tasks: Fortran procedures run on a worker thread, with progress and cooperative cancel.
figure_textureRGBA images on the GPU, drawn by ig_image and ip_image, and PNG or JPEG files read into pixels.
figure_view3da 3-D view of meshes (view3d_object), drawn by FIGURE's software rasterizer in every mode.
figure_testingsynthetic input for testing interfaces without a display (or with one). (use figure_testing, apart from figure)

The boundary ​

Fortran calls only C functions, through bind(C) interfaces; no C++ type, exception or ABI crosses. A cimgui or cimplot function is bound directly when all its arguments are scalars, pointers or the two-float ImVec2_c (declared in Fortran as the interoperable im_vec2). Functions that take larger structures by value, such as ImPlot's item functions with their ImPlotSpec_c, go through the generated glue (native/figure_glue_generated.cpp): a wrapper figure_<name> takes the structure by pointer, from a Fortran bind(C) mirror type passed by reference (im_plot_spec), and calls the C function with it by value. ip_line calls ImPlot_PlotLine_doublePtrdoublePtr (bound to figure_ImPlot_PlotLine_doublePtrdoublePtr), which calls ImPlot::PlotLine. The generated wrappers are noexcept: an exception would terminate the program rather than unwind through Fortran frames. ImPlotSpec's defaults come from its C++ constructor (figure_ImPlotSpec_default), and figure_test_layout checks that every mirror type has the size of its C struct (Raw bindings).

Conventions of the hand-written glue (figure_native.h):

  • every function is plain C (extern "C") and returns an int status unless documented otherwise;
  • no C++ exception escapes: each function catches them and returns FIG_ERR_EXCEPTION;
  • strings from Fortran arrive as a pointer and a byte length, without NUL terminator;
  • the glue owns the SDL window, the OpenGL context and the Dear ImGui/ImPlot contexts: Fortran never sees them.

The OpenGL calls the glue makes itself (viewport, clear) are loaded through SDL at run time: there is no link-time dependency on libGL or opengl32.

Lifecycle ​

The native layer owns the lifecycle state (not initialized, window, headless, remote; frame open or not) and rejects out-of-order calls with FIG_ERR_STATE. app_object mirrors only whether a frame is open, because next_frame must know whether to close one before opening the next.

Builds ​

The native layer is built once by CMake (scripts/build_native.sh): static libraries, pinned versions fetched with FetchContent, compiled with the same configuration cimgui and cimplot were generated with (cimconfig.h, IMGUI_DISABLE_OBSOLETE_FUNCTIONS), so that their C structures match the C++ ones bit for bit. The Fortran library is built by FoBiS or fpm, which only link figure_native, SDL3 and the platform's libraries (Linux: stdc++ dl pthread m; fpm also links figure_platform). scripts/check_sync.py checks that fobos and fpm.toml agree on those libraries and on the programs they build.

Released under the MIT licence.