figure — Create or select RunMat plotting figures.

figure creates a new plotting figure or selects an existing one as current. RunMat currently encodes graphics handles as host f64 identifiers instead of MATLAB Figure objects; this is a general graphics-representation gap, not numeric MATLAB equivalence. Double numeric selection is the compatibility form, while typed-integer targets, single-precision targets, the 'next' selector, and typed-integer property values are independently gated RunMat-only extensions.

Syntax

fig = figure()
fig = figure(h)
fig = figure(property, value, ...)
fig = figure(h, property, value, ...)

Inputs

Returns

Errors

How figure works

• figure() creates a new figure and returns RunMat's current host f64 graphics-handle encoding.
• figure(n) selects figure n. If that handle does not exist yet, RunMat creates it.
• In RunMat extension mode, figure('next') creates a new figure instead of selecting an existing one.
• In RunMat extension mode, a positive scalar from any of the eight integer classes is read exactly as a figure identifier and must fit in u32.
• In RunMat extension mode, a positive single-precision scalar can select a figure. Logical and GPU-resident numeric targets reject without provider access.
• Typed-integer values for Position, Color, NumberTitle, Visible, CurrentAxes, and SgTitle are RunMat-only extensions and are rejected in compatibility mode before graphics state changes.
• Integer Position values cross an explicit host f64 geometry boundary only after every authoritative integer element is proved exactly representable. Integer RGB values are read authoritatively and the normal [0,1] constraint admits only exact zero and one components.
• Integer NumberTitle and Visible values use an exact zero/nonzero predicate with no floating conversion. Integer CurrentAxes and SgTitle aliases must be exactly representable before lookup in RunMat's current f64 graphics registry.
• figure('Property', value, ...) creates a fresh figure and applies the requested figure properties.
• figure(n, 'Property', value, ...) selects or creates figure n and applies the requested figure properties.
• figure('Position', [left bottom width height]) stores MATLAB-style figure window geometry and makes it available through get(f, 'Position') and figure scene metadata.
• The selected figure becomes the target for subsequent plotting commands such as plot, subplot, gca, clf, and hold.

Options

• 'Name' sets the figure window name and can be inspected later with get(f, 'Name').
• 'NumberTitle' accepts logical values or MATLAB-style 'on'/'off' strings.
• 'Visible' accepts logical values or MATLAB-style 'on'/'off' strings. Hidden figures keep their graphics state but do not open or update interactive windows until made visible again.
• 'Position' accepts a finite four-element numeric vector [left bottom width height]; width and height must be positive.
• 'Color' accepts supported color letters, full color names such as 'black', or RGB triples, and updates the figure background color.

Does RunMat run figure on the GPU?

figure performs no provider dispatch. GPU-resident arrays passed to later plotting calls may still remain on device when the renderer supports that path.

GPU memory and residency

figure only updates plotting state and returns RunMat's host-side f64 handle encoding. Resident numeric values are not admitted as figure targets and are not gathered.

Examples

Create a fresh figure

f = figure()

Expected output:

% f is a positive numeric figure handle

Selecting the next available figure

f1 = figure();
f2 = figure("next")

Expected output:

% f2 is a different figure handle from f1

Select a specific figure handle

figure(3);
plot(1:5, [1 4 2 5 3]);

Expected output:

% plotting now targets figure 3

Create a named figure with MATLAB-style property pairs

f = figure('Name', 'demo', 'NumberTitle', 'off', 'Visible', 'off');
plot(1:5, [1 4 2 5 3]);

Expected output:

% f is a figure handle whose Name, NumberTitle, and Visible properties are set

Create a figure with explicit geometry

f = figure('Position', [100 100 1000 700]);
pos = get(f, 'Position')

Expected output:

% pos is [100 100 1000 700]

Using figure with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how figure changes the result.

FAQ

Related Plotting functions

More plotting resources

• Styling plots and axes
• Plot replay and export
• Complete plotting guide

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how figure is executed, line by line, in Rust.

• View the source for figure in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing