Skip to content

Architecture

This describes the on-disk layout and responsibilities of the FlashBang library as implemented today. Paths are relative to the FlashBang repository root (not this docs repo).

Entry point: package flashbang

src/flashbang.odin is the stable application-facing API. It re-exports types and procedures from:

  • src/widgets/ — immediate-mode widgets, ImmediateContext, layout helpers, hashing, dimension lookup.
  • src/style/ — Theme, resolve_surface, ResolvedSurface, WidgetVisualState, color helpers, default themes.
  • src/rendering/ — DrawList, draw ops, arenas used when enqueueing geometry/text.
  • src/backends/ — interface structs (TextBackend, PlatformBackend, LayoutBackend, ImageBackend, …) passed into the context.
  • src/core/ — shared core types (e.g. ids, separator orientation) used by widgets and exporters.

If a symbol exists on flashbang, tracing it to flashbang.odin first is the fastest way to find the underlying widgets or style definition.

Widgets (src/widgets/)

Each file generally implements one family of controls (e.g. button.odin, label.odin). Some files hold shared immediate-mode infrastructure (notably button.odin defines ImmediateContext and set_immediate_context—historical placement, not “buttons-only” logic).

Shared drawing helpers live in common.odin (emit_surface, emit_separator, apply_layout_override, dimension getters, draw_centered_text, …).

Styling (src/style/)

theme.odin defines Theme and built-in default_theme / basic_theme. Optional fields on Theme are procedure hooks (geometry, resolve, indicators, window chrome, separators, group box label).

resolve.odin implements resolve_surface and apply_color_override (per-widget color overrides layered on a resolved surface).

Rendering (src/rendering/)

Builds a DrawList of neutral ops (rect fills/strokes, text runs, clips, images, etc.). Widgets do not talk to GPU APIs; adapters do.

Backends (src/backends/ + src/adapters/)

backends/interfaces.odin (and related) describe what the host must provide. adapters/ contains concrete integrations (e.g. SDL3, Clay) that live outside the minimal core dependency surface—your app wires the adapter you use.

Text (src/text/)

Types for measure/shape requests and results; widgets call through TextBackend on the context.

Tests and demos

test_app/ is the in-repo stress/demo application. It is not imported by the library but is the best place to see end-to-end usage patterns.