.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_plane" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_plane - operations on ncplanes
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
#define NCPLANE_OPTION_HORALIGNED 0x0001ull

typedef struct ncplane_options {
  int y;            // vertical placement relative to parent plane
  union {
    int x;
    ncalign_e align;
  } horiz;          // horizontal placement relative to parent plane
  int rows;         // number of rows, must be positive
  int cols;         // number of columns, must be positive
  void* userptr;    // user curry, may be NULL
  const char* name; // name (used only for debugging), may be NULL
  int (*resizecb)(struct ncplane*); // callback when parent is resized
  uint64_t flags;   // closure over NCPLANE_OPTION_*
} ncplane_options;
\f[R]
.fi
.PP
\f[B]struct ncplane* ncplane_create(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncplane_options*
\f[R]\f[I]nopts\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* notcurses_top(struct notcurses*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* notcurses_bottom(struct notcurses*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncplane_reparent(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], struct ncplane*
\f[R]\f[I]newparent\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncplane_dup(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
void* \f[R]\f[I]opaque\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_resize(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]keepy\f[R]\f[B], int \f[R]\f[I]keepx\f[R]\f[B], int
\f[R]\f[I]keepleny\f[R]\f[B], int \f[R]\f[I]keeplenx\f[R]\f[B], int
\f[R]\f[I]yoff\f[R]\f[B], int \f[R]\f[I]xoff\f[R]\f[B], int
\f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_move_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_yx(const struct ncplane* \f[R]\f[I]n\f[R]\f[B], int*
restrict \f[R]\f[I]y\f[R]\f[B], int* restrict
\f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_y(const struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_x(const struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncplane_parent(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]const struct ncplane* ncplane_parent_const(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_base_cell(struct ncplane* \f[R]\f[I]ncp\f[R]\f[B],
const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_base(struct ncplane* \f[R]\f[I]ncp\f[R]\f[B], const
char* \f[R]\f[I]egc\f[R]\f[B], uint32_t \f[R]\f[I]stylemask\f[R]\f[B],
uint64_t \f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_base(struct ncplane* \f[R]\f[I]ncp\f[R]\f[B], cell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_move_top(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_move_bottom(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_move_above(struct ncplane* restrict
\f[R]\f[I]n\f[R]\f[B], struct ncplane* restrict
\f[R]\f[I]above\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_move_below(struct ncplane* restrict
\f[R]\f[I]n\f[R]\f[B], struct ncplane* restrict
\f[R]\f[I]below\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncplane_below(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncplane_above(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]char* ncplane_at_cursor(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
uint16_t* \f[R]\f[I]stylemask\f[R]\f[B], uint64_t*
\f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_at_cursor_cell(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]char* ncplane_at_yx(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], uint16_t*
\f[R]\f[I]stylemask\f[R]\f[B], uint64_t*
\f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_at_yx_cell(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], cell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t* ncplane_rgba(const struct ncplane*
\f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]begy\f[R]\f[B], int
\f[R]\f[I]begx\f[R]\f[B], int \f[R]\f[I]leny\f[R]\f[B], int
\f[R]\f[I]lenx\f[R]\f[B]);\f[R]
.PP
\f[B]char* ncplane_contents(const struct ncplane*
\f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]begy\f[R]\f[B], int
\f[R]\f[I]begx\f[R]\f[B], int \f[R]\f[I]leny\f[R]\f[B], int
\f[R]\f[I]lenx\f[R]\f[B]);\f[R]
.PP
\f[B]void* ncplane_set_userptr(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
void* \f[R]\f[I]opaque\f[R]\f[B]);\f[R]
.PP
\f[B]void* ncplane_userptr(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_dim_yx(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int* restrict \f[R]\f[I]rows\f[R]\f[B], int* restrict
\f[R]\f[I]cols\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_dim_y(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_dim_x(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_cursor_yx(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int* restrict \f[R]\f[I]y\f[R]\f[B], int* restrict
\f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_translate(const struct ncplane*
\f[R]\f[I]src\f[R]\f[B], const struct ncplane* \f[R]\f[I]dst\f[R]\f[B],
int* restrict \f[R]\f[I]y\f[R]\f[B], int* restrict
\f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncplane_translate_abs(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int* restrict \f[R]\f[I]y\f[R]\f[B], int*
restrict \f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t ncplane_channels(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_channels(struct ncplane* \f[R]\f[I]nc\f[R]\f[B],
uint64_t \f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_bchannel(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_fchannel(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_fg_rgb8(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_bg_rgb8(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_fg_alpha(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_bg_alpha(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_fg_rgb8(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], unsigned* \f[R]\f[I]r\f[R]\f[B], unsigned*
\f[R]\f[I]g\f[R]\f[B], unsigned* \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]static inline unsigned ncplane_bg_rgb8(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], unsigned* \f[R]\f[I]r\f[R]\f[B], unsigned*
\f[R]\f[I]g\f[R]\f[B], unsigned* \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_fg_rgb8(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]r\f[R]\f[B], int \f[R]\f[I]g\f[R]\f[B], int
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_bg_rgb8(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]r\f[R]\f[B], int \f[R]\f[I]g\f[R]\f[B], int
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_fg_rgb8_clipped(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]r\f[R]\f[B], int
\f[R]\f[I]g\f[R]\f[B], int \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_bg_rgb8_clipped(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]r\f[R]\f[B], int
\f[R]\f[I]g\f[R]\f[B], int \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_fg_rgb8(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
uint32_t \f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_bg_rgb8(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
uint32_t \f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_fg_default(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_bg_default(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_fg_alpha(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_bg_alpha(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_fg_palindex(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]idx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_set_bg_palindex(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]idx\f[R]\f[B]);\f[R]
.PP
\f[B]uint16_t ncplane_styles(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_set_styles(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_on_styles(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_off_styles(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_greyscale(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_blit_bgrx(struct ncplane* \f[R]\f[I]nc\f[R]\f[B], int
\f[R]\f[I]placey\f[R]\f[B], int \f[R]\f[I]placex\f[R]\f[B], int
\f[R]\f[I]linesize\f[R]\f[B], ncblitter_e \f[R]\f[I]blitter\f[R]\f[B],
const unsigned char* \f[R]\f[I]data\f[R]\f[B], int
\f[R]\f[I]begy\f[R]\f[B], int \f[R]\f[I]begx\f[R]\f[B], int
\f[R]\f[I]leny\f[R]\f[B], int \f[R]\f[I]lenx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_blit_rgba(struct ncplane* \f[R]\f[I]nc\f[R]\f[B], int
\f[R]\f[I]placey\f[R]\f[B], int \f[R]\f[I]placex\f[R]\f[B], int
\f[R]\f[I]linesize\f[R]\f[B], ncblitter_e \f[R]\f[I]blitter\f[R]\f[B],
const unsigned char* \f[R]\f[I]data\f[R]\f[B], int
\f[R]\f[I]begy\f[R]\f[B], int \f[R]\f[I]begx\f[R]\f[B], int
\f[R]\f[I]leny\f[R]\f[B], int \f[R]\f[I]lenx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_destroy(struct ncplane* \f[R]\f[I]ncp\f[R]\f[B]);\f[R]
.PP
\f[B]void notcurses_drop_planes(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_mergedown(const struct ncplane*
\f[R]\f[I]src\f[R]\f[B], struct ncplane* \f[R]\f[I]dst\f[R]\f[B], int
\f[R]\f[I]begsrcy\f[R]\f[B], int \f[R]\f[I]begsrcx\f[R]\f[B], int
\f[R]\f[I]leny\f[R]\f[B], int \f[R]\f[I]lenx\f[R]\f[B], int
\f[R]\f[I]dsty\f[R]\f[B], int \f[R]\f[I]dstx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_mergedown_simple(const struct ncplane* restrict
\f[R]\f[I]src\f[R]\f[B], struct ncplane* restrict
\f[R]\f[I]dst\f[R]\f[B]);\f[R]
.PP
\f[B]void ncplane_erase(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncplane_set_scrolling(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
bool \f[R]\f[I]scrollp\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_rotate_cw(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_rotate_ccw(struct ncplane* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.SS DESCRIPTION
.PP
Ncplanes are the fundamental drawing object of notcurses.
All output functions take a \f[B]struct ncplane\f[R] as an argument.
They can be any size, and placed anywhere.
In addition to its framebuffer\[en]a rectilinear matrix of cells (see
\f[B]notcurses_cell(3)\f[R])\[en]an ncplane is defined by:
.IP \[bu] 2
a base cell, used for any cell on the plane without a glyph,
.IP \[bu] 2
the egcpool backing its cells,
.IP \[bu] 2
a current cursor location,
.IP \[bu] 2
a current style, foreground channel, and background channel,
.IP \[bu] 2
its geometry,
.IP \[bu] 2
a configured user pointer,
.IP \[bu] 2
position relative to the standard plane,
.IP \[bu] 2
the plane, if any, to which it is bound,
.IP \[bu] 2
the next plane bound by the plane to which it is bound,
.IP \[bu] 2
the head of the list of its bound planes,
.IP \[bu] 2
its z-index, and
.IP \[bu] 2
a name (used only for debugging).
.PP
New planes can be created with \f[B]ncplane_create\f[R].
If a plane is bound to another, x and y coordinates are relative to the
plane to which it is bound, and if this latter plane moves, all its
bound planes move along with it.
When a plane is destroyed, all planes bound to it (directly or
transitively) are destroyed.
\f[B]ncplane_reparent\f[R] detaches the plane \f[B]n\f[R] from any plane
to which it is bound, and binds it to \f[B]newparent\f[R] if
\f[B]newparent\f[R] is not \f[B]NULL\f[R].
All planes bound to \f[B]n\f[R] move along with it during a reparenting
operation.
.PP
\f[B]ncplane_destroy\f[R] destroys a particular ncplane, after which it
must not be used again.
\f[B]notcurses_drop_planes\f[R] destroys all ncplanes other than the
stdplane.
Any references to such planes are, of course, invalidated.
It is undefined to destroy a plane concurrently with any other operation
involving that plane, or any operation involving the z-axis.
.PP
It is an error for two threads to concurrently mutate a single ncplane.
So long as rendering is not taking place, however, multiple threads may
safely output to multiple ncplanes.
So long as all threads are readers, multiple threads may work with a
single ncplane.
A reading function is any which accepts a \f[B]const struct
ncplane\f[R].
.PP
\f[B]ncplane_translate\f[R] translates coordinates expressed relative to
the plane \f[B]src\f[R], and writes the coordinates of that cell
relative to \f[B]dst\f[R].
The cell need not intersect with \f[B]dst\f[R], though this will yield
coordinates which are invalid for writing or reading on \f[B]dst\f[R].
If \f[B]dst\f[R] is \f[B]NULL\f[R], it is taken to refer to the standard
plane.
\f[B]ncplane_translate_abs\f[R] takes coordinates expressed relative to
the standard plane, and returns coordinates relative to \f[B]dst\f[R],
returning \f[B]false\f[R] if the coordinates are invalid for
\f[B]dst\f[R].
.PP
\f[B]ncplane_mergedown\f[R] writes to \f[B]dst\f[R] the frame that would
be rendered if only \f[B]src\f[R] and \f[B]dst\f[R] existed on the
z-axis, ad \f[B]dst\f[R] represented the entirety of the rendering
region.
Only those cells where \f[B]src\f[R] intersects with \f[B]dst\f[R] might
see changes.
It is an error to merge a plane onto itself.
.PP
\f[B]ncplane_erase\f[R] zeroes out every cell of the plane, dumps the
egcpool, and homes the cursor.
The base cell is preserved.
.PP
When a plane is resized (whether by \f[B]ncplane_resize\f[R],
\f[B]SIGWINCH\f[R], or any other mechanism), a depth-first recursion is
performed on its children.
Each child plane having a non-\f[B]NULL\f[R] \f[B]resizecb\f[R] will see
that callback invoked following resizing of its parent\[cq]s plane.
If it returns non-zero, the resizing cascade terminates, returning
non-zero.
Otherwise, resizing proceeds recursively.
.SS Scrolling
.PP
All planes, including the standard plane, are created with scrolling
disabled.
Control scrolling on a per-plane basis with
\f[B]ncplane_set_scrolling\f[R].
Attempting to print past the end of a line will stop at the plane
boundary, and indicate an error.
On a plane 10 columns wide and two rows high, printing
\[lq]0123456789\[rq] at the origin should succeed, but printing
\[lq]01234567890\[rq] will by default fail at the eleventh character.
In either case, the cursor will be left at location 0x10; it must be
moved before further printing can take place.
If scrolling is enabled, the first row will be filled with 01234546789,
the second row will have 0 written to its first column, and the cursor
will end up at 1x1.
Note that it is still an error to manually attempt to move the cursor
off-plane, or to specify off-plane output.
Boxes do not scroll; attempting to draw a 2x11 box on our 2x10 plane
will result in an error and no output.
When scrolling is enabled, and output takes place while the cursor is
past the end of the last row, the first row is discarded, all other rows
are moved up, the last row is cleared, and output begins at the
beginning of the last row.
This does not take place until output is generated (i.e.\ it is possible
to fill a plane when scrolling is enabled).
.SH RETURN VALUES
.PP
\f[B]ncplane_new\f[R], \f[B]ncplane_bound\f[R],
\f[B]ncplane_aligned\f[R], and \f[B]ncplane_dup\f[R] all return a new
\f[B]struct ncplane\f[R] on success, or \f[B]NULL\f[R] on failure.
.PP
\f[B]ncplane_userptr\f[R] returns the configured user pointer for the
ncplane, and cannot fail.
.PP
\f[B]ncplane_below\f[R] returns the plane below the specified ncplane.
If the provided plane is the bottommost plane, NULL is returned.
It cannot fail.
.PP
\f[B]ncplane_set_scrolling\f[R] returns \f[B]true\f[R] if scrolling was
previously enabled, and \f[B]false\f[R] otherwise.
.PP
\f[B]ncplane_at_yx\f[R] and \f[B]ncplane_at_cursor\f[R] return a
heap-allocated copy of the EGC at the relevant cell, or NULL if the cell
is invalid.
The caller should free this result.
\f[B]ncplane_at_yx_cell\f[R] and \f[B]ncplane_at_cursor_cell\f[R]
instead load these values into a \f[B]cell\f[R], which is invalidated if
the associated plane is destroyed.
The caller should release this cell with \f[B]cell_release\f[R].
.PP
Functions returning \f[B]int\f[R] return 0 on success, and non-zero on
error.
.PP
All other functions cannot fail (and return \f[B]void\f[R]).
.SH NOTES
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_cell(3)\f[R],
\f[B]notcurses_output(3)\f[R], \f[B]notcurses_stdplane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.