Crate ratatui_unity

Expand description

§ratatui_unity

A C ABI wrapper around [ratatui] that renders terminal UIs to RGB24 pixel buffers, suitable for embedding in game engines (e.g. Unity).

The crate is compiled as both cdylib and staticlib so that it can be consumed from any host capable of calling C functions. All public entry points are extern "C" and #[no_mangle]; there is no idiomatic Rust API.

§High-level flow

Create a terminal handle with ratatui_create.
For each frame:
- Call ratatui_begin_frame to reset per-frame state.
- Build a layout tree with ratatui_split / ratatui_inner.
- Optionally set a style with ratatui_set_style before any widget call.
- Queue widget commands (e.g. ratatui_block, ratatui_paragraph, ratatui_chart_begin / ratatui_chart_end, …).
- Call ratatui_end_frame (or ratatui_end_frame_hashed) to draw the queue and rasterize the cell grid into an RGB24 pixel buffer.
When done, call ratatui_destroy to release the handle.

§Memory & lifetime

The handle returned by ratatui_create is an opaque pointer to a heap-allocated TerminalState. The pixel buffer pointer returned by ratatui_end_frame* is owned by the handle and is only valid until the next FFI call that mutates the handle. The caller must copy the bytes before issuing further calls if it wants to retain them.

§Safety

All FFI entry points perform null-pointer checks on the handle and on any pointer argument they dereference. Strings are read as null-terminated *const c_char. Slices passed as (ptr, len) pairs must reference valid memory for the duration of the call.

Functions§

ratatui_barchart: Queues a BarChart.
ratatui_begin_frame: Begins a new frame.
ratatui_block: Queues a Block widget with an optional title and per-edge borders.
ratatui_calendar: Queues a monthly calendar (Monthly).
ratatui_canvas_begin: Starts a Canvas builder.
ratatui_canvas_circle: Draws a colored circle centered at (x, y) with the given radius.
ratatui_canvas_end: Finalizes the pending canvas and queues it for rendering.
ratatui_canvas_layer: Flushes the current canvas layer.
ratatui_canvas_line: Draws a colored line from (x1, y1) to (x2, y2) on the pending canvas.
ratatui_canvas_map: Draws the world map on the pending canvas.
ratatui_canvas_points: Draws a colored point cloud on the pending canvas.
ratatui_canvas_rectangle: Draws a colored rectangle outline anchored at (x, y) with size (w, h).
ratatui_canvas_text: Draws colored text anchored at (x, y) on the pending canvas.
ratatui_chart_begin: Starts a Chart builder.
ratatui_chart_dataset: Adds a Dataset to the pending chart.
ratatui_chart_end: Finalizes the pending chart and queues it for rendering.
ratatui_chart_x_axis: Sets the X axis title and [min, max] data bounds of the pending chart.
ratatui_chart_y_axis: Sets the Y axis title and [min, max] data bounds of the pending chart.
ratatui_create: Creates a terminal instance and returns an opaque handle.
ratatui_destroy: Destroys a terminal handle created by ratatui_create.
ratatui_end_frame: Renders all queued widget commands and rasterizes the cell buffer.
ratatui_end_frame_hashed: Like ratatui_end_frame, but skips rasterization when the cell buffer is unchanged from the previous frame (hash-based dirty check). Returns a valid pixel pointer when content changed, or null when unchanged. The previous frame’s pixel buffer remains valid when null is returned.
ratatui_gauge: Queues a block-style Gauge.
ratatui_get_area_rect: Returns the cell-space rectangle of the given area as a packed u64.
ratatui_hit_test: Returns the most specific area id covering the given terminal cell.
ratatui_inner: Returns a new area id covering the inner rectangle of area_id shrunk by the given margins on each side.
ratatui_line_gauge: Queues a horizontal single-line LineGauge.
ratatui_list: Queues a List widget.
ratatui_paragraph: Queues a uniformly styled Paragraph.
ratatui_pixel_height: Returns the height of the pixel buffer in pixels (rows * cell_height).
ratatui_pixel_width: Returns the width of the pixel buffer in pixels (cols * cell_width).
ratatui_root_area: Returns the id of the root area, which always covers the whole terminal.
ratatui_scrollbar: Queues a Scrollbar.
ratatui_set_background_color: Sets the RGB background color used by the rasterizer for cells whose background is [Color::Reset].
ratatui_set_custom_font: Replaces the embedded JetBrains Mono font with custom TTF bytes.
ratatui_set_style: Sets the pending style consumed by the next widget-producing FFI call.
ratatui_sparkline: Queues a Sparkline from raw u64 samples.
ratatui_split: Splits an existing area into count child areas and writes their ids into out_ids.
ratatui_styled_para_begin: Starts a multi-style paragraph builder.
ratatui_styled_para_end: Finalizes the pending styled paragraph and queues it for rendering.
ratatui_styled_para_newline: Starts a new line in the pending styled paragraph.
ratatui_styled_para_span: Appends a styled Span to the current line of the pending styled paragraph.
ratatui_table: Queues a Table with equal-width columns.
ratatui_table_ex: Queues an extended Table with typed column widths and optional row highlighting.
ratatui_tabs: Queues a Tabs bar.
ratatui_version: Returns the library version as a static null-terminated C string.