.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_render" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_render - sync the physical display to the virtual ncplanes
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.PP
\f[B]int notcurses_render(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]char* notcurses_at_yx(struct notcurses* \f[R]\f[I]nc\f[R]\f[B], int
\f[R]\f[I]yoff\f[R]\f[B], int \f[R]\f[I]xoff\f[R]\f[B], uint16_t*
\f[R]\f[I]styles\f[R]\f[B], uint64_t*
\f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_render_to_file(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], FILE* \f[R]\f[I]fp\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_render_to_buffer(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], char\f[R] \f[B]\f[BI]buf\f[B]\f[R], size_t*
\f[B]\f[BI]buflen\f[B]\f[R]);**
.SH DESCRIPTION
.PP
\f[B]notcurses_render\f[R] syncs the physical display to the
context\[cq]s prepared ncplanes.
It is necessary to call \f[B]notcurses_render\f[R] to generate any
visible output; the various notcurses_output(3) calls only draw to the
virtual ncplanes.
Most of the notcurses statistics are updated as a result of a render
(see notcurses_stats(3)), and screen geometry is refreshed (similarly to
\f[B]notcurses_refresh\f[R]) \f[I]following\f[R] the render.
.PP
While \f[B]notcurses_render\f[R] is called, you \f[B]must not call any
other functions on the same notcurses context\f[R], with the one
exception of \f[B]notcurses_getc\f[R] (and its input-related helpers;
see \f[B]notcurses_input(3)\f[R].).
.PP
\f[B]notcurses_render_to_buffer\f[R] performs the render and raster
processes of \f[B]notcurses_render\f[R], but does not write the
resulting buffer to the terminal.
The user is responsible for writing the buffer to the terminal in its
entirety.
If there is an error, subsequent frames will be out of sync, and
\f[B]notcurses_refresh(3)\f[R] must be called.
.PP
A render operation consists of two logical phases: generation of the
rendered scene, and blitting this scene to the terminal (these two
phases might actually be interleaved, streaming the output as it is
rendered).
Frame generation requires determining an extended grapheme cluster,
foreground color, background color, and style for each cell of the
physical terminal.
Writing the scene requires synthesizing a set of UTF-8-encoded
characters and escape codes appropriate for the terminal (relying on
terminfo(5)), and writing this sequence to the output \f[B]FILE\f[R].
If the \f[B]renderfp\f[R] value was not NULL in the original call to
\f[B]notcurses_init\f[R], the frame will be written to that
\f[B]FILE\f[R] as well.
This write does not affect statistics.
.PP
Each cell can be rendered in isolation, though synthesis of the stream
carries dependencies between cells.
.SS Cell rendering algorithm
.PP
Recall that there is a total ordering on the N ncplanes, and that the
standard plane always exists, with geometry equal to the physical
screen.
Each cell of the physical screen is thus intersected by some totally
ordered subset of planes \f[B]P0\f[R], \f[B]P1\f[R]\&...\f[B]Pi\f[R],
where 0 < \f[B]i\f[R] \[<=] \f[B]N\f[R].
At each cell, rendering starts at the topmost intersecting plane
\f[B]P0\f[R].
The algorithm descends until either:
.IP \[bu] 2
it has locked in an extended grapheme cluster, and fore/background
colors, or
.IP \[bu] 2
all \f[B]i\f[R] planes have been examined
.PP
At each plane \f[B]P\f[R], we consider a cell \f[B]C\f[R].
This cell is the intersecting cell, unless that cell has no EGC.
In that case, \f[B]C\f[R] is the plane\[cq]s default cell.
.IP \[bu] 2
If we have not yet determined an EGC, and \f[B]C\f[R] has a non-zero
EGC, use the EGC and style of \f[B]C\f[R].
.IP \[bu] 2
If we have not yet locked in a foreground color, and \f[B]C\f[R] is not
foreground-transparent, use the foreground color of \f[B]C\f[R] (see
BUGS below).
If \f[B]C\f[R] is \f[B]CELL_ALPHA_OPAQUE\f[R], lock the color in.
.IP \[bu] 2
If we have not yet locked in a background color, and \f[B]C\f[R] is not
background-transparent, use the background color of \f[B]C\f[R] (see
BUGS below).
If \f[B]C\f[R] is \f[B]CELL_ALPHA_OPAQUE\f[R], lock the color in.
.PP
If the algorithm concludes without an EGC, the cell is rendered with no
glyph and a default background.
If the algorithm concludes without a color locked in, the color as
computed thus far is used.
.PP
\f[B]notcurses_at_yx\f[R] retrieves a call \f[I]as rendered\f[R].
The EGC in that cell is copied and returned; it must be
\f[B]free(3)\f[R]d by the caller.
.SH RETURN VALUES
.PP
On success, 0 is returned.
On failure, a non-zero value is returned.
A success will result in the \f[B]renders\f[R] stat being increased by
1.
A failure will result in the \f[B]failed_renders\f[R] stat being
increased by 1.
.PP
\f[B]notcurses_at_yx\f[R] returns a heap-allocated copy of the
cell\[cq]s EGC on success, and \f[B]NULL\f[R] on failure.
.SH BUGS
.PP
In addition to the RGB colors, it is possible to use the \[lq]default
foreground color\[rq] and \[lq]default background color\[rq] inherited
from the terminal.
Since notcurses doesn\[cq]t know what these colors are, they are not
considered for purposes of color blending.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_cell(3)\f[R],
\f[B]notcurses_input(3)\f[R], \f[B]notcurses_output(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]notcurses_refresh(3)\f[R],
\f[B]notcurses_stats(3)\f[R], \f[B]console_codes(4)\f[R],
\f[B]utf-8(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.