gca — Return the current axes handle in MATLAB and RunMat.
gca returns the handle for the current axes in the active figure, or in a specific figure when a figure handle is supplied. Optional struct mode returns a snapshot of current axes context for diagnostics and tooling.
Syntax
ax = gca()
ax = gca(fig)
s = gca('struct')Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
fig | NumericScalar | Yes | — | Figure handle whose current axes should be returned. |
mode | StringScalar | Yes | — | Only 'struct' is supported. |
Returns
| Name | Type | Description |
|---|---|---|
ax | Any | Current axes graphics object; RunMat currently returns its encoded numeric 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(fig)returns the current axes handle for the specified figure handle.gca('struct')returns a struct with fieldshandle,figure,rows,cols, andindex.- The current axes reflect the active subplot when
subplothas been used. - The numeric axes handle can be passed to
getandset, including common axes styling such asFontSize. - 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
indexRead the current axes of a specific figure
f1 = figure(1);
subplot(2, 2, 3);
f2 = figure(2);
ax1 = gca(f1)Expected output:
% ax1 is the current axes handle for figure 1Style the current axes
plot(1:3, [1 2 3]);
set(gca, 'FontSize', 10);Using 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.
Can gca inspect a non-current figure?⌄
Yes. Pass a figure handle, for example gca(fig), to read that figure's current axes without changing the active figure.
Does gca run on the GPU?⌄
No. It only reads host-side plotting state.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
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.