mirror of
https://github.com/dankamongmen/notcurses.git
synced 2024-11-04 06:00:30 +00:00
81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
% notcurses_render(3)
|
|
% nick black <nickblack@linux.com>
|
|
% v1.1.6
|
|
|
|
# NAME
|
|
|
|
notcurses_render - sync the physical display to the virtual ncplanes
|
|
|
|
# SYNOPSIS
|
|
|
|
**#include <notcurses.h>**
|
|
|
|
**int notcurses_render(struct notcurses* nc);**
|
|
|
|
**char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff, cell* c);**
|
|
|
|
# DESCRIPTION
|
|
|
|
**notcurses_render** syncs the physical display to the context's prepared
|
|
ncplanes. It is necessary to call **notcurses_render** 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 **notcurses_resize(3)** is called
|
|
internally *following* the render.
|
|
|
|
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). All ncplanes are
|
|
locked while generating the frame. 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 **FILE**. If
|
|
the **renderfp** value was not NULL in the original call to notcurses_init(3),
|
|
the frame will be written to that **FILE** as well. This write does not affect
|
|
statistics.
|
|
|
|
Each cell can be rendered in isolation, though synthesis of the stream carries
|
|
dependencies between cells.
|
|
|
|
## Cell rendering algorithm
|
|
|
|
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 **P0**, **P1**...**Pi**, where 0 < **i** ≤ **N**. At each cell, rendering starts at
|
|
the topmost intersecting plane **P0**. The algorithm descends until either:
|
|
|
|
* it has locked in an extended grapheme cluster, and fore/background colors, or
|
|
* all **i** planes have been examined
|
|
|
|
At each plane **P**, we consider a cell **C**. This cell is the intersecting cell,
|
|
unless that cell has no EGC. In that case, **C** is the plane's default cell.
|
|
|
|
* If we have not yet determined an EGC, and **C** has a non-zero EGC, use the EGC and style of **C**.
|
|
* If we have not yet locked in a foreground color, and **C** is not foreground-transparent, use the foreground color of **C** (see [BUGS][] below). If **C** is **CELL_ALPHA_OPAQUE**, lock the color in.
|
|
* If we have not yet locked in a background color, and **C** is not background-transparent, use the background color of **C** (see [BUGS][] below). If **C** is **CELL_ALPHA_OPAQUE**, lock the color in.
|
|
|
|
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.
|
|
|
|
# RETURN VALUES
|
|
|
|
On success, 0 is returned. On failure, a non-zero value is returned. A success
|
|
will result in the **renders** stat being increased by 1. A failure will result
|
|
in the **failed_renders** stat being increased by 1.
|
|
|
|
# BUGS
|
|
|
|
In addition to the RGB colors, it is possible to use the "default foreground color"
|
|
and "default background color" inherited from the terminal. Since
|
|
notcurses doesn't know what these colors are, they are not considered for
|
|
purposes of color blending.
|
|
|
|
# SEE ALSO
|
|
|
|
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_ncplane(3)**,
|
|
**notcurses_output(3)**, **notcurses_resize(3)**, **notcurses_stats(3)**,
|
|
**console_codes(4)**, **utf-8(7)**
|