gca — Return the current axes handle in MATLAB and RunMat.
gca returns the handle for the current axes in the active figure. Optional struct mode returns a snapshot of current axes context for diagnostics and tooling.
Syntax
ax = gca()
s = gca('struct')Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
mode | StringScalar | Yes | — | Only 'struct' is supported. |
Returns
| Name | Type | Description |
|---|---|---|
ax | NumericScalar | Current axes handle. |
s | Any | Axes state struct with handle/figure/rows/cols/index fields. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:gca:InvalidArgument | Unsupported arguments are provided. | gca: unsupported arguments |
How gca works
gca()returns a scalar numeric axes handle.gca('struct')returns a struct with fieldshandle,figure,rows,cols, andindex.- The current axes reflect the active subplot when
subplothas been used. - Unsupported arguments raise
gcaplotting errors.
Does RunMat run gca on the GPU?
gca performs no provider dispatch; it only reads the active axes state from the plotting registry.
GPU memory and residency
gca returns host-side handles or structs and does not interact with GPU residency.
Examples
Read the current axes handle
figure(1);
ax = gca()Expected output:
% ax is a numeric axes handleInspect the active subplot layout
subplot(2, 2, 3);
info = gca("struct")Expected output:
info =
struct with fields:
handle
figure
rows
cols
indexUsing gca with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how gca changes the result.
Run a small gca example, explain the result, then change one input and compare the output.
FAQ
What is special about gca('struct')?⌄
It is a RunMat extension that returns a struct snapshot of the active axes state instead of just the encoded numeric handle.
Does gca reflect subplot selection?⌄
Yes. When a subplot is active, gca reports that subplot's axes handle and metadata.
Does gca run on the GPU?⌄
No. It only reads host-side plotting state.
Related Plotting functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how gca is executed, line by line, in Rust.
- View the source for gca 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.