figure — Create or select plotting figures in MATLAB and RunMat.
figure creates a new plotting figure or selects an existing one as current. With no arguments (or 'next') it allocates a fresh handle; passing a positive numeric handle selects that figure, creating it if needed. Handle selection and creation behavior follow MATLAB semantics.
Syntax
fig = figure()
fig = figure(h)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
h | NumericScalar | No | "next" | Figure handle or 'next' to create/select the next figure. |
Returns
| Name | Type | Description |
|---|---|---|
fig | NumericScalar | Figure handle. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:figure:InvalidArgument | Provided figure handle argument is invalid. | figure: invalid argument |
How figure works
figure()creates a new figure and returns its numeric handle.figure(n)selects figuren. If that handle does not exist yet, RunMat creates it.figure('next')creates a new figure instead of selecting an existing one.- The selected figure becomes the target for subsequent plotting commands such as
plot,subplot,gca,clf, andhold.
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 a host-side numeric handle. It does not affect array residency.
Examples
Create a fresh figure
f = figure()Expected output:
% f is a positive numeric figure handleCreate another figure with the explicit 'next' selector
f1 = figure();
f2 = figure("next")Expected output:
% f2 is a different figure handle from f1Select a specific figure handle
figure(3);
plot(1:5, [1 4 2 5 3]);Expected output:
% plotting now targets figure 3Using figure with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how figure changes the result.
Run a small figure example, explain the result, then change one input and compare the output.
FAQ
Does figure(n) require the handle to exist already?⌄
No. RunMat selects figure n, creating it on demand if necessary.
What does figure('next') do?⌄
It forces creation of a new figure rather than reusing an existing handle.
Does figure draw anything by itself?⌄
No. It only manages the active figure selection. Plotting happens when you call builtins like plot, scatter, or surf.
Related Plotting functions
More plotting resources
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.