Skip to content

figure_implot3d ​

figure_implot3d, small 3-D figures with Fortran arrays (ImPlot3D).

ImPlot3D (brenocq/implot3d, MIT) draws plots in a box the user turns with the mouse (right drag: rotate; left drag: pan; wheel or middle drag: zoom; right double click: back to the initial rotation; right click: the plot's menu), through Dear ImGui's draw lists: the same in every mode. It is for figures that are plots, not scenes: probe positions, trajectories, a field as a height surface, up to about 10**4 primitives; meshes of millions of faces belong to view3d_object (plots.md, "3-D plots").

ip3_begin_plot returns true when the plot is visible: then declare its axes (ip3_setup_axes) and items, and close it with ip3_end_plot (only in that case). Items (ip3_line, ip3_scatter, ip3_surface, ip3_mesh) take real(real32) or real(real64) arrays of any stride, read in place during the call as the 2-D items are (figure_implot: ImPlot3D has one byte stride for all the arrays of an item, an array of another stride is copied at it; the dummies are ASYNCHRONOUS). Every item takes an optional spec, built by ip3_spec from ImPlot3D's defaults. A surface is coloured by FIGURE's colormaps (ip_colormap), copied into ImPlot3D's registry at their first use and followed when ig_gradient_edit changes them.

Every procedure refuses a call from a task and a call with no frame open (FIG_ERR_STATE); an item or ip3_text outside a 3-D plot, and ip3_setup_axes after the plot's first item, are usage errors (FIG_ERR_STATE, as app%set_checks says). The begin/end pair registers in the scope record of the frame (errors.md, "Pairing and frames").

Source: src/lib/figure_implot3d.F90

Dependencies

Re-exports ​

NameKindModuleDescription
ImPlot3DMarker_Noneparameterfigure_cimplot3d_enums
ImPlot3DMarker_Autoparameterfigure_cimplot3d_enums
ImPlot3DMarker_Circleparameterfigure_cimplot3d_enums
ImPlot3DMarker_Squareparameterfigure_cimplot3d_enums
ImPlot3DMarker_Diamondparameterfigure_cimplot3d_enums
ImPlot3DMarker_Upparameterfigure_cimplot3d_enums
ImPlot3DMarker_Downparameterfigure_cimplot3d_enums
ImPlot3DMarker_Leftparameterfigure_cimplot3d_enums
ImPlot3DMarker_Rightparameterfigure_cimplot3d_enums
ImPlot3DMarker_Crossparameterfigure_cimplot3d_enums
ImPlot3DMarker_Plusparameterfigure_cimplot3d_enums
ImPlot3DMarker_Asteriskparameterfigure_cimplot3d_enums
ImPlot3DItemFlags_Noneparameterfigure_cimplot3d_enums
ImPlot3DItemFlags_NoLegendparameterfigure_cimplot3d_enums
ImPlot3DItemFlags_NoFitparameterfigure_cimplot3d_enums
ImPlot3DLineFlags_Segmentsparameterfigure_cimplot3d_enums
ImPlot3DLineFlags_Loopparameterfigure_cimplot3d_enums
ImPlot3DLineFlags_SkipNaNparameterfigure_cimplot3d_enums
ImPlot3DSurfaceFlags_NoLinesparameterfigure_cimplot3d_enums
ImPlot3DSurfaceFlags_NoFillparameterfigure_cimplot3d_enums
ImPlot3DSurfaceFlags_NoMarkersparameterfigure_cimplot3d_enums
ImPlot3DMeshFlags_NoLinesparameterfigure_cimplot3d_enums
ImPlot3DMeshFlags_NoFillparameterfigure_cimplot3d_enums
ImPlot3DMeshFlags_NoMarkersparameterfigure_cimplot3d_enums

Contents ​

Variables ​

NameTypeAttributesDescription
mesh_indexinteger(kind=c_int)allocatable, targetThe triangles of the last mesh, 0-based (kept and grown).

Derived Types ​

plot3d_spec_object ​

Style of a 3-D plot item: colours, line weight, markers, flags. Build it with ip3_spec.

The C struct is private so that a spec always starts from ImPlot3D's defaults (a zeroed one draws nothing).

Components

NameTypeAttributesDescription
ctype(im_plot3d_spec)ImPlot3DSpec, as passed to ImPlot3D.

Interfaces ​

ip3_triangles ​

Triangles: each three points (x(i), y(i), z(i)) in a row are one.

Module procedures: ip3_triangles_r32, ip3_triangles_r64

ip3_quads ​

Quadrilaterals: each four points in a row are one.

Module procedures: ip3_quads_r32, ip3_quads_r64

ip3_line ​

A line through the points (x(i), y(i), z(i)).

Module procedures: ip3_line_r32, ip3_line_r64

ip3_scatter ​

Markers at the points (x(i), y(i), z(i)).

Module procedures: ip3_scatter_r32, ip3_scatter_r64

ip3_surface ​

A surface z(i, j) over a grid: x(i), y(j) (a rectilinear grid) or x(i, j), y(i, j) (any grid of quadrilaterals).

Module procedures: ip3_surface_r32, ip3_surface_r64, ip3_surface_grid_r32, ip3_surface_grid_r64

ip3_mesh ​

A mesh of triangles: vertices (x(i), y(i), z(i)), triangles(:, k) the vertices of the k-th (from 1).

Module procedures: ip3_mesh_r32, ip3_mesh_r64

place_field ​

Place a rank-2 array of an item (a surface's field or grid) in a slot.

Module procedures: place_field_r32, place_field_r64

Subroutines ​

ip3_end_plot ​

End the 3-D plot (only after ip3_begin_plot returned true).

Attributes: recursive

fortran
subroutine ip3_end_plot()

Call graph

ip3_setup_axes ​

Labels of the three axes (call right after ip3_begin_plot, before any item); with auto_fit=.true. the axes fit the data every frame, instead of once on first use. limits = [xmin, xmax, ymin, ymax, zmin, zmax]: the initial ranges (set once; the user zooms and pans from them). elevation and azimuth [degrees], both or neither: the initial rotation of the box (set once; a right double click goes back to it). Statuses: FIG_ERR_ARGUMENT for limits of size /= 6 or with a minimum not below its maximum, or one angle without the other (nothing is set up); FIG_ERR_STATE outside a 3-D plot, after its first item, or from a task.

Attributes: recursive

fortran
subroutine ip3_setup_axes(xlabel, ylabel, zlabel, auto_fit, limits, elevation, azimuth, stat)

Arguments

NameTypeIntentAttributesDescription
xlabelcharacter(len=*)inX label.
ylabelcharacter(len=*)inY label.
zlabelcharacter(len=*)inZ label.
auto_fitlogicalinoptionalFit the axes to the data every frame (default: first use).
limitsreal(kind=real64)inoptionalInitial ranges [xmin, xmax, ymin, ymax, zmin, zmax].
elevationreal(kind=real64)inoptionalInitial elevation [degrees].
azimuthreal(kind=real64)inoptionalInitial azimuth [degrees].
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_line_r32 ​

A line through the points (x(i), y(i), z(i)), single precision; read in place with any stride. colors: the segment from point i in colors(:, i) (RGBA in [0, 1]). Statuses: FIG_ERR_ARGUMENT for series of different sizes, colours not (4, size(x)) or out of [0, 1]; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_line_r32(label, x, y, z, spec, colors, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae.
yreal(kind=real32)intarget, asynchronousOrdinates.
zreal(kind=real32)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
colorsreal(kind=real64)inoptionalPer-point RGBA, (4, size(x)).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_scatter_r32 ​

Markers at the points (x(i), y(i), z(i)), single precision; read in place with any stride. colors: each marker filled and outlined in its own colour, colors(:, i) RGBA in [0, 1]; sizes: each its own radius [pixels]. Statuses as ip3_line, and FIG_ERR_ARGUMENT for colours not (4, size(x)) or out of [0, 1], sizes not one per point or below 0.

Attributes: recursive

fortran
subroutine ip3_scatter_r32(label, x, y, z, spec, colors, sizes, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae.
yreal(kind=real32)intarget, asynchronousOrdinates.
zreal(kind=real32)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
colorsreal(kind=real64)inoptionalPer-point RGBA, (4, size(x)).
sizesreal(kind=real64)inoptionalPer-point marker radii [pixels].
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_surface_r32 ​

A surface of heights z(i, j) over the rectilinear grid x(i), y(j), single precision, coloured by colormap from scale_min to scale_max (default: z's finite range). z is read in place when its elements are equally spaced in memory (a whole array, z(:, j1:j2), a(k, :, :)), else copied; x and y are expanded into the grid's two coordinate arrays (two copies: ImPlot3D reads one value per vertex). Statuses: FIG_ERR_ARGUMENT for x, y that do not match z's shape, one scale end without the other or a minimum not below the maximum, more vertices than a C int counts, a colormap not registered; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_surface_r32(label, x, y, z, colormap, scale_min, scale_max, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae of the grid, size(z, 1).
yreal(kind=real32)intarget, asynchronousOrdinates of the grid, size(z, 2).
zreal(kind=real32)intarget, asynchronousHeights.
colormapinteger(kind=int32)inoptionalColormap (ip_colormap; default Viridis).
scale_minreal(kind=real64)inoptionalHeight at the colormap's first colour.
scale_maxreal(kind=real64)inoptionalHeight at its last colour.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_surface_grid_r32 ​

A surface over any grid of quadrilaterals: the vertex (i, j) at (x(i, j), y(i, j), z(i, j)), single precision, coloured as ip3_surface. The three arrays are read in place when their elements are equally spaced in memory with one stride, else copied at the stride of z. Statuses as ip3_surface (x and y of z's shape).

Attributes: recursive

fortran
subroutine ip3_surface_grid_r32(label, x, y, z, colormap, scale_min, scale_max, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real32)intarget, asynchronousOrdinates of the vertices.
zreal(kind=real32)intarget, asynchronousHeights of the vertices.
colormapinteger(kind=int32)inoptionalColormap (ip_colormap; default Viridis).
scale_minreal(kind=real64)inoptionalHeight at the colormap's first colour.
scale_maxreal(kind=real64)inoptionalHeight at its last colour.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_mesh_r32 ​

A mesh of triangles, single precision: vertices (x(i), y(i), z(i)) read in place with any stride, triangles(1:3, k) the vertices of the k-th triangle (from 1; converted to ImPlot3D's 0-based indices: one copy). Statuses: FIG_ERR_ARGUMENT for series of different sizes, triangles without 3 rows or with a vertex outside [1, size(x)]; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_mesh_r32(label, x, y, z, triangles, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real32)intarget, asynchronousOrdinates of the vertices.
zreal(kind=real32)intarget, asynchronousHeights of the vertices.
trianglesinteger(kind=int32)inVertices of each triangle.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_line_r64 ​

A line through the points (x(i), y(i), z(i)), double precision; read in place with any stride. colors: the segment from point i in colors(:, i) (RGBA in [0, 1]). Statuses: FIG_ERR_ARGUMENT for series of different sizes, colours not (4, size(x)) or out of [0, 1]; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_line_r64(label, x, y, z, spec, colors, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae.
yreal(kind=real64)intarget, asynchronousOrdinates.
zreal(kind=real64)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
colorsreal(kind=real64)inoptionalPer-point RGBA, (4, size(x)).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_scatter_r64 ​

Markers at the points (x(i), y(i), z(i)), double precision; read in place with any stride. colors: each marker filled and outlined in its own colour, colors(:, i) RGBA in [0, 1]; sizes: each its own radius [pixels]. Statuses as ip3_line, and FIG_ERR_ARGUMENT for colours not (4, size(x)) or out of [0, 1], sizes not one per point or below 0.

Attributes: recursive

fortran
subroutine ip3_scatter_r64(label, x, y, z, spec, colors, sizes, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae.
yreal(kind=real64)intarget, asynchronousOrdinates.
zreal(kind=real64)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
colorsreal(kind=real64)inoptionalPer-point RGBA, (4, size(x)).
sizesreal(kind=real64)inoptionalPer-point marker radii [pixels].
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_surface_r64 ​

A surface of heights z(i, j) over the rectilinear grid x(i), y(j), double precision, coloured by colormap from scale_min to scale_max (default: z's finite range). z is read in place when its elements are equally spaced in memory (a whole array, z(:, j1:j2), a(k, :, :)), else copied; x and y are expanded into the grid's two coordinate arrays (two copies: ImPlot3D reads one value per vertex). Statuses: FIG_ERR_ARGUMENT for x, y that do not match z's shape, one scale end without the other or a minimum not below the maximum, more vertices than a C int counts, a colormap not registered; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_surface_r64(label, x, y, z, colormap, scale_min, scale_max, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae of the grid, size(z, 1).
yreal(kind=real64)intarget, asynchronousOrdinates of the grid, size(z, 2).
zreal(kind=real64)intarget, asynchronousHeights.
colormapinteger(kind=int32)inoptionalColormap (ip_colormap; default Viridis).
scale_minreal(kind=real64)inoptionalHeight at the colormap's first colour.
scale_maxreal(kind=real64)inoptionalHeight at its last colour.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_surface_grid_r64 ​

A surface over any grid of quadrilaterals: the vertex (i, j) at (x(i, j), y(i, j), z(i, j)), double precision, coloured as ip3_surface. The three arrays are read in place when their elements are equally spaced in memory with one stride, else copied at the stride of z. Statuses as ip3_surface (x and y of z's shape).

Attributes: recursive

fortran
subroutine ip3_surface_grid_r64(label, x, y, z, colormap, scale_min, scale_max, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real64)intarget, asynchronousOrdinates of the vertices.
zreal(kind=real64)intarget, asynchronousHeights of the vertices.
colormapinteger(kind=int32)inoptionalColormap (ip_colormap; default Viridis).
scale_minreal(kind=real64)inoptionalHeight at the colormap's first colour.
scale_maxreal(kind=real64)inoptionalHeight at its last colour.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_mesh_r64 ​

A mesh of triangles, double precision: vertices (x(i), y(i), z(i)) read in place with any stride, triangles(1:3, k) the vertices of the k-th triangle (from 1; converted to ImPlot3D's 0-based indices: one copy). Statuses: FIG_ERR_ARGUMENT for series of different sizes, triangles without 3 rows or with a vertex outside [1, size(x)]; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_mesh_r64(label, x, y, z, triangles, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real64)intarget, asynchronousOrdinates of the vertices.
zreal(kind=real64)intarget, asynchronousHeights of the vertices.
trianglesinteger(kind=int32)inVertices of each triangle.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_text ​

A text centred on the point (x, y, z) of the current 3-D plot (PlotText), in the plot's inlay text colour, hidden when the point is outside the box; angle turns it [radians, counter-clockwise], offset moves it [pixels] (x right, y down). Not an item: no legend entry, no part in fitting the axes. Statuses: FIG_ERR_ARGUMENT for a NaN coordinate or an offset of size /= 2; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_text(text, x, y, z, angle, offset, stat)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText (UTF-8).
xreal(kind=real64)inAbscissa [plot units].
yreal(kind=real64)inOrdinate [plot units].
zreal(kind=real64)inHeight [plot units].
anglereal(kind=real64)inoptionalAngle [radians] (default: 0, horizontal).
offsetreal(kind=real64)inoptionalOffset [pixels], (x right, y down) (default: none).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_image ​

An image on a quadrilateral of the box (PlotImage): corners(:, k) the x, y, z of its four corners, in the image's top-left, top-right, bottom-right, bottom-left order (a rectangle on a plane: a field on a cut, a picture on the floor); tint multiplies its colours (RGBA, default white). An item: a legend entry, part of the fit. Drawn as two triangles, sorted with the other items. Statuses: FIG_ERR_ARGUMENT for corners not 3 x 4, a tint without 4 components, a texture not initialized; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_image(label, texture, corners, tint, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
texturetype(texture_object)inThe image.
cornersreal(kind=real64)inx, y, z of the four corners (3 x 4).
tintreal(kind=real64)inoptionalRGBA multiplier (default 1, 1, 1, 1).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_setup_axis ​

Set up one axis of the 3-D plot being declared (SetupAxis, SetupAxisScale): axis 'x', 'y' or 'z'; scale 'linear' (default), 'log' (base 10: values <= 0 are not shown) or 'symlog'; auto_fit fits the data every frame; invert grows the axis the other way; lock fixes its range against the mouse; no_grid: no grid lines; format a C printf format of one real for the tick labels ('%.1f m', '%.0e'). After ip3_begin_plot (and ip3_setup_axes, which it overrides for that axis), before any item. Statuses: FIG_ERR_ARGUMENT for an unknown axis or scale, a format refused; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.

Attributes: recursive

fortran
subroutine ip3_setup_axis(axis, label, scale, auto_fit, invert, lock, no_grid, format, stat)

Arguments

NameTypeIntentAttributesDescription
axischaracter(len=*)in'x', 'y' or 'z'.
labelcharacter(len=*)inoptionalLabel (default: none).
scalecharacter(len=*)inoptional'linear' (default), 'log', 'symlog'.
auto_fitlogicalinoptionalFit the data every frame.
invertlogicalinoptionalValues grow the other way.
locklogicalinoptionalNo pan or zoom by the user.
no_gridlogicalinoptionalNo grid lines.
formatcharacter(len=*)inoptionalprintf format of the tick labels (one real).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_setup_axis_ticks ​

Ticks of one axis of the 3-D plot being declared at the given values instead of the automatic ones (SetupAxisTicks), labelled labels (one per value; trailing blanks are not shown) or, without them, by the axis's format. Before any item. Statuses: FIG_ERR_ARGUMENT for an unknown axis, values not finite, labels not one per value, more values than a C int counts; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.

Attributes: recursive

fortran
subroutine ip3_setup_axis_ticks(axis, values, labels, stat)

Arguments

NameTypeIntentAttributesDescription
axischaracter(len=*)in'x', 'y' or 'z'.
valuesreal(kind=real64)inTick positions.
labelscharacter(len=*)inoptionalOne label per value.
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_setup_box ​

The box of the 3-D plot being declared: scale its x, y, z sides relative to each other (SetupBoxScale, default 1, 1, 1: a cube); elevation and azimuth [degrees], both or neither, turn it to that view on this frame (SetupBoxRotation: a "top view" button calls it once; called every frame, the user cannot turn it), animate=.true. turning it there smoothly. Before any item. Statuses: FIG_ERR_ARGUMENT for a scale without 3 positive values, one angle without the other; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.

Attributes: recursive

fortran
subroutine ip3_setup_box(scale, elevation, azimuth, animate, stat)

Arguments

NameTypeIntentAttributesDescription
scalereal(kind=real64)inoptionalRelative sides [x, y, z].
elevationreal(kind=real64)inoptionalElevation [degrees].
azimuthreal(kind=real64)inoptionalAzimuth [degrees].
animatelogicalinoptionalTurn there smoothly (default: at once).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_setup_legend ​

Where the 3-D plot's legend goes (SetupLegend): location a compass point, 'n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw' (default, ImPlot3D's) or 'c'; horizontal=.true.: entries in a row; no_buttons=.true.: a click on an entry does not hide its item. Before any item. Statuses: FIG_ERR_ARGUMENT for an unknown location; FIG_ERR_STATE outside a 3-D plot, after its first item, from a task.

Attributes: recursive

fortran
subroutine ip3_setup_legend(location, horizontal, no_buttons, stat)

Arguments

NameTypeIntentAttributesDescription
locationcharacter(len=*)inoptionalCompass point (default 'nw').
horizontallogicalinoptionalEntries in a row (default: a column).
no_buttonslogicalinoptionalEntries do not hide their items.
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_plot_to_pixels ​

The pixel (px, py) where the point (x, y, z) of the 3-D plot being declared is drawn (PlotToPixels), as the box is turned now: a label beside a point, a test's click. Statuses: FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_plot_to_pixels(x, y, z, px, py, stat)

Arguments

NameTypeIntentAttributesDescription
xreal(kind=real64)inAbscissa.
yreal(kind=real64)inOrdinate.
zreal(kind=real64)inHeight.
pxreal(kind=real64)outPixel abscissa.
pyreal(kind=real64)outPixel ordinate.
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_triangles_r64 ​

Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 3; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_triangles_r64(label, x, y, z, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real64)intarget, asynchronousOrdinates.
zreal(kind=real64)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_quads_r64 ​

Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 4; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_quads_r64(label, x, y, z, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real64)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real64)intarget, asynchronousOrdinates.
zreal(kind=real64)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_triangles_r32 ​

Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 3; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_triangles_r32(label, x, y, z, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real32)intarget, asynchronousOrdinates.
zreal(kind=real32)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

ip3_quads_r32 ​

Filled with the spec's fill_color (default: the item's colour), edged with its line_color. Statuses: FIG_ERR_ARGUMENT for series of different sizes or a size not a multiple of 4; FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

fortran
subroutine ip3_quads_r32(label, x, y, z, spec, stat)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLegend label.
xreal(kind=real32)intarget, asynchronousAbscissae of the vertices.
yreal(kind=real32)intarget, asynchronousOrdinates.
zreal(kind=real32)intarget, asynchronousHeights.
spectype(plot3d_spec_object)inoptionalStyle (default: ImPlot3D's).
statinteger(kind=int32)outoptionalStatus.

Call graph

field_range_r32 ​

The heights at a surface's first and last colours: the given ones, else z's finite range (widened by one about its centre when z is flat: ImPlot3D would divide by a zero range, an FPE under traps).

fortran
subroutine field_range_r32(z, scale_min, scale_max, lo, hi)

Arguments

NameTypeIntentAttributesDescription
zreal(kind=real32)inasynchronousHeights.
scale_minreal(kind=real64)inoptionalGiven first height.
scale_maxreal(kind=real64)inoptionalGiven last height.
loreal(kind=c_double)outFirst height.
hireal(kind=c_double)outLast height.

Call graph

field_range_r64 ​

The heights at a surface's first and last colours: the given ones, else z's finite range (widened by one about its centre when z is flat: ImPlot3D would divide by a zero range, an FPE under traps).

fortran
subroutine field_range_r64(z, scale_min, scale_max, lo, hi)

Arguments

NameTypeIntentAttributesDescription
zreal(kind=real64)inasynchronousHeights.
scale_minreal(kind=real64)inoptionalGiven first height.
scale_maxreal(kind=real64)inoptionalGiven last height.
loreal(kind=c_double)outFirst height.
hireal(kind=c_double)outLast height.

Call graph

place_field_r32 ​

Place a rank-2 array of a surface in slot k, single precision: in place when its elements are equally spaced in memory (column after column) at a positive multiple of the element size within a C int and, when stride is given (the item's, set by the field), at that stride; otherwise copied into the slot's scratch, at stride or contiguous (then the item's stride becomes the element size).

fortran
subroutine place_field_r32(d, k, a, stride)

Arguments

NameTypeIntentAttributesDescription
dtype(series_r32)inoutThe item's arrays.
kinteger(kind=int32)inSlot.
areal(kind=real32)intarget, asynchronousArray.
strideinteger(kind=int64)inoptionalThe item's stride [bytes].

Call graph

place_field_r64 ​

Place a rank-2 array of a surface in slot k, double precision: in place when its elements are equally spaced in memory (column after column) at a positive multiple of the element size within a C int and, when stride is given (the item's, set by the field), at that stride; otherwise copied into the slot's scratch, at stride or contiguous (then the item's stride becomes the element size).

fortran
subroutine place_field_r64(d, k, a, stride)

Arguments

NameTypeIntentAttributesDescription
dtype(series_r64)inoutThe item's arrays.
kinteger(kind=int32)inSlot.
areal(kind=real64)intarget, asynchronousArray.
strideinteger(kind=int64)inoptionalThe item's stride [bytes].

Call graph

Functions ​

ip3_begin_plot ​

Begin a 3-D plot; if true, declare its content and call ip3_end_plot.

Attributes: recursive

Returns: logical

fortran
function ip3_begin_plot(title, width, height, equal) result(visible)

Arguments

NameTypeIntentAttributesDescription
titlecharacter(len=*)inTitle (also the plot id; '##id' hides it).
widthreal(kind=real64)inoptionalWidth [pixels] (default: full width).
heightreal(kind=real64)inoptionalHeight [pixels] (default: ImPlot3D's).
equallogicalinoptionalSame scale on the three axes (one unit as many pixels).

Call graph

ip3_spec ​

3-D item style: ImPlot3D's defaults, with the given properties overridden. Colours are RGBA in [0, 1]; an absent colour stays automatic (the next colour of the colormap; a surface's fill: its colormap).

Returns: type(plot3d_spec_object)

fortran
function ip3_spec(line_color, line_weight, fill_color, fill_alpha, marker, marker_size, marker_line_color, marker_fill_color, flags, stat) result(spec)

Arguments

NameTypeIntentAttributesDescription
line_colorreal(kind=real64)inoptionalLine colour, RGBA.
line_weightreal(kind=real64)inoptionalLine weight [pixels] (lines, edges, markers).
fill_colorreal(kind=real64)inoptionalFill colour, RGBA (surfaces, meshes: one colour).
fill_alphareal(kind=real64)inoptionalAlpha multiplier of the fill colours.
markerinteger(kind=int32)inoptionalMarker shape (ImPlot3DMarker_*).
marker_sizereal(kind=real64)inoptionalMarker radius [pixels].
marker_line_colorreal(kind=real64)inoptionalMarker outline colour, RGBA.
marker_fill_colorreal(kind=real64)inoptionalMarker fill colour, RGBA.
flagsinteger(kind=int32)inoptionalItem flags (ImPlot3DItemFlags_*, the item's own).
statinteger(kind=int32)outoptionalStatus: FIG_ERR_ARGUMENT for a colour of size /= 4.

Call graph

ip3_mouse_ray ​

The ray under the pointer, in the 3-D plot's coordinates (PixelsToPlotRay): every point of the box drawn under the pointer is origin + t direction for some t (direction of length 1). True when the pointer is over the plot. A program picks with it: where the ray meets a plane (the floor: t = -origin(3) / direction(3)), the nearest of its points. Linear axes: on a log axis the ray is in the transformed space. Statuses: FIG_ERR_STATE outside a 3-D plot, from a task.

Attributes: recursive

Returns: logical

fortran
function ip3_mouse_ray(origin, direction, stat) result(over)

Arguments

NameTypeIntentAttributesDescription
originreal(kind=real64)outA point of the ray.
directionreal(kind=real64)outIts direction (unit).
statinteger(kind=int32)outoptionalStatus.

Call graph

setup3d_refused ​

True (a usage error reported) outside a 3-D plot or after its first item.

Attributes: recursive

Returns: logical

fortran
function setup3d_refused(caller, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
callercharacter(len=*)inThe procedure.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

opt ​

An optional flag, false when absent.

Attributes: pure

Returns: logical

fortran
function opt(x) result(on)

Arguments

NameTypeIntentAttributesDescription
xlogicalinoptionalFlag.

Call graph

outside_plot ​

True (a usage error reported) when no 3-D plot is being declared: ImPlot3D asserts there.

Attributes: recursive

Returns: logical

fortran
function outside_plot(caller, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
callercharacter(len=*)inThe procedure.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

item_refused ​

True (reported) when an item cannot be drawn: from a task, no frame, no 3-D plot (FIG_ERR_STATE), series of different sizes or more points than a C int counts (FIG_ERR_ARGUMENT).

Attributes: recursive

Returns: logical

fortran
function item_refused(caller, nx, ny, nz, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
callercharacter(len=*)inThe procedure.
nxinteger(kind=int64)inSize of x.
nyinteger(kind=int64)inSize of y.
nzinteger(kind=int64)inSize of z.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

surface_ok ​

Whether a surface can be drawn (reported otherwise): from the main thread in a frame and a 3-D plot, x and y matching z's shape, the scale ends both given or neither and in order, a vertex count a C int holds.

Attributes: recursive

Returns: logical

fortran
function surface_ok(nx, ny, sx, sy, scale_min, scale_max, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
nxinteger(kind=int64)insize(z, 1).
nyinteger(kind=int64)insize(z, 2).
sxinteger(kind=int64)inAbscissae given (size(z, 1) expected).
syinteger(kind=int64)inOrdinates given (size(z, 2) expected).
scale_minreal(kind=real64)inoptionalHeight at the first colour.
scale_maxreal(kind=real64)inoptionalHeight at the last colour.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

grid_ok ​

Whether the vertex arrays of a surface over a grid all have z's shape (FIG_ERR_ARGUMENT otherwise).

Attributes: recursive

Returns: logical

fortran
function grid_ok(sx, sy, sz, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
sxinteger(kind=int64)inShape of x.
syinteger(kind=int64)inShape of y.
szinteger(kind=int64)inShape of z.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

colormap3d_ok ​

The ImPlot3D id of the colormap to draw with (default Viridis), copied from FIGURE's registry; false, with FIG_ERR_ARGUMENT, if it is not registered.

Attributes: recursive

Returns: logical

fortran
function colormap3d_ok(colormap, cmap, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
colormapinteger(kind=int32)inoptionalColormap (ip_colormap), if given.
cmapinteger(kind=c_int)outImPlot3D id.
statinteger(kind=int32)outoptionalStatus, on a failure.

Call graph

triangles_ok ​

Whether a mesh's triangles are 3 rows of vertices in [1, nv] and a count a C int holds (FIG_ERR_ARGUMENT otherwise); if so, their 0-based indices are in mesh_index.

Attributes: recursive

Returns: logical

fortran
function triangles_ok(triangles, nv, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
trianglesinteger(kind=int32)inVertices of each triangle.
nvinteger(kind=int64)inVertices.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

spec_at ​

The C spec to pass: the given one, or ImPlot3D's defaults, with the item's stride (test_plot_stride reads it).

Returns: type(im_plot3d_spec)

fortran
function spec_at(stride, spec) result(c)

Arguments

NameTypeIntentAttributesDescription
strideinteger(kind=int64)inThe item's stride [bytes].
spectype(plot3d_spec_object)inoptionalStyle.

Call graph

per_point_ok ​

Whether the per-point colours, (4, n) in [0, 1], and radii, n finite values >= 0, fit an item of n points.

Returns: logical

fortran
function per_point_ok(who, n, colors, sizes, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
whocharacter(len=*)inCalling procedure, for the message.
ninteger(kind=int64)inPoints.
colorsreal(kind=real64)inoptionalPer-point RGBA.
sizesreal(kind=real64)inoptionalPer-point radii [pixels].
statinteger(kind=int32)outoptionalStatus, on a failure.

Call graph

packed_colors ​

RGBA colours in [0, 1], one per column, packed as Dear ImGui's ImU32 (R in the low byte, A in the high one).

Attributes: pure

Returns: integer(kind=c_int)

fortran
function packed_colors(colors) result(u)

Arguments

NameTypeIntentAttributesDescription
colorsreal(kind=real64)inRGBA, (4, n).

Call graph

rgba_ok ​

Whether an optional colour is absent or has 4 components.

Attributes: pure

Returns: logical

fortran
function rgba_ok(color) result(ok)

Arguments

NameTypeIntentAttributesDescription
colorreal(kind=real64)inoptionalColour, RGBA.

Call graph

rgba ​

RGBA colour as an ImVec4.

Attributes: pure

Returns: type(im_vec4)

fortran
function rgba(color) result(v)

Arguments

NameTypeIntentAttributesDescription
colorreal(kind=real64)inColour, RGBA, 4 components.

Call graph

Released under the MIT licence.