Archives/notcurses
2
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses.git synced 2024-11-08 01:10:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
78ff79fb34
notcurses/doc/man/man3/notcurses_ncplane.3.md

159 lines
5.2 KiB
Markdown
Raw Normal View History

ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
% notcurses_ncplane(3)
% nick black <nickblack@linux.com>
Debian: move all symbols/history to 1.1.8
2020-02-12 00:11:34 +00:00
% v1.1.8
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
# NAME
Docs/API sweep for 1.0.0 #244 #249 (#250) * sync up some docs #244 * sync README and man page * notcurses_output() man page work * pull attr/channels from output functions #244 * witherworm: clean up explicit moves #244 * still more man page work * notcurses_lines, last of the man pages i think * panelreel man page #244 * debian: ruby-ronn->pandoc * debian: full multiarch compliance * debian: symbols file * pandoc: fix syntax for lexgrog * fm6.mkv: strip audio * pandoc: fix up apropos man syntax #249 * ncurses_lines man page
2020-01-04 07:37:55 +00:00
notcurses_ncplane - operations on notcurses planes
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
# SYNOPSIS
**#include <notcurses.h>**
**struct ncplane* ncplane_new(struct notcurses* nc, int rows, int cols, int yoff, int xoff, void* opaque);**
**struct ncplane* ncplane_aligned(struct ncplane* n, int rows, int cols, int yoff, ncalign_e align, void* opaque);**
implement ncplane_dup()
2020-01-15 17:22:10 +00:00
**struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
**int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keepleny, int keeplenx, int yoff, int xoff, int ylen, int xlen);**
**int ncplane_move_yx(struct ncplane* n, int y, int x);**
**void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);**
Selector widget #166, subtitles #95 (#301) Get rid of annoying empty line in notcurses-view (and ncvisuals at offsets in general) Implement most of the Selector widget. Need to add styling and scrolling still. #166 Reenable ubuntu focal build Subtitles! We decode them, and display them in notcurses-view. If ncvisual_simple_streamer() is provided an extra ncplane, it will use it to display subtitles. #95 We now build Python by default, as things are working much better. ncplane_set_base() now takes channel, attrword, and EGC, so you can usually avoid having to set up and release a cell. ncplane_set_base_cell() takes over duty from ncplane_set_base() for ease of conversion. notcurses-demo and notcurses-view now both accept a 0 for delay multiplier, meaning 'go as fast as you possibly can'. Very small multipliers (e.g. 0.00001) no longer cause floating point exceptions. fading routines no longer cause floating point exceptions on very small timescales.
2020-01-30 13:55:01 +00:00
**int ncplane_set_base_cell(struct ncplane* ncp, const cell* c);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
Selector widget #166, subtitles #95 (#301) Get rid of annoying empty line in notcurses-view (and ncvisuals at offsets in general) Implement most of the Selector widget. Need to add styling and scrolling still. #166 Reenable ubuntu focal build Subtitles! We decode them, and display them in notcurses-view. If ncvisual_simple_streamer() is provided an extra ncplane, it will use it to display subtitles. #95 We now build Python by default, as things are working much better. ncplane_set_base() now takes channel, attrword, and EGC, so you can usually avoid having to set up and release a cell. ncplane_set_base_cell() takes over duty from ncplane_set_base() for ease of conversion. notcurses-demo and notcurses-view now both accept a 0 for delay multiplier, meaning 'go as fast as you possibly can'. Very small multipliers (e.g. 0.00001) no longer cause floating point exceptions. fading routines no longer cause floating point exceptions on very small timescales.
2020-01-30 13:55:01 +00:00
**int ncplane_set_base(struct ncplane* ncp, uint64_t channels, uint32_t attrword, const char* egc);**
**int ncplane_base(struct ncplane* ncp, cell* c);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
**int ncplane_destroy(struct ncplane* ncp);**
**int ncplane_move_top(struct ncplane* n);**
**int ncplane_move_bottom(struct ncplane* n);**
**int ncplane_move_above(struct ncplane* n, struct ncplane* above);**
**int ncplane_move_below(struct ncplane* n, struct ncplane* below);**
**struct ncplane* ncplane_below(struct ncplane* n);**
**int ncplane_at_cursor(struct ncplane* n, cell* c);**
**int ncplane_at_yx(struct ncplane* n, int y, int x, cell* c);**
**void* ncplane_set_userptr(struct ncplane* n, void* opaque);**
**void* ncplane_userptr(struct ncplane* n);**
Chun Li demo (#251) * chun li demo * ncvisual_decode: allow multiple renders of the same frame * add -H to notcurses-demo man page * update section 1 man page versions
2020-01-04 12:21:54 +00:00
**void ncplane_dim_yx(struct ncplane* n, int* restrict rows, int* restrict cols);**
**static inline int ncplane_dim_y(struct ncplane* n);**
**static inline int ncplane_dim_x(struct ncplane* n);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
**int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**void ncplane_cursor_yx(struct ncplane* n, int* restrict y, int* restrict x);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**uint64_t ncplane_channels(struct ncplane* n);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**uint32_t ncplane_attr(struct ncplane* n);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_bchannel(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_fchannel(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_fg(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_bg(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_fg_alpha(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_bg_alpha(struct ncplane* nc);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_fg_rgb(struct ncplane* n, unsigned* r, unsigned* g, unsigned* b);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**static inline unsigned ncplane_bg_rgb(struct ncplane* n, unsigned* r, unsigned* g, unsigned* b);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**int ncplane_set_fg_rgb(struct ncplane* n, int r, int g, int b);**
**int ncplane_set_bg_rgb(struct ncplane* n, int r, int g, int b);**
**void ncplane_set_fg_rgb_clipped(struct ncplane* n, int r, int g, int b);**
**void ncplane_set_bg_rgb_clipped(struct ncplane* n, int r, int g, int b);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**int ncplane_set_fg(struct ncplane* n, unsigned channel);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**int ncplane_set_bg(struct ncplane* n, unsigned channel);**
**void ncplane_set_fg_default(struct ncplane* n);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**void ncplane_set_bg_default(struct ncplane* n);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
**int ncplane_set_fg_alpha(struct ncplane* n, int alpha);**
**int ncplane_set_bg_alpha(struct ncplane* n, int alpha);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
ruins color cycling demo #253 (#287) * palette_set: update pal256 damage map #230 * drone: use newest builders * palette: send oc on exit for color reset #285 * palette_new: copy existing palette in #230 * Python: use checkRGB everywhere * more palette unit testing * add ncplane_set_*_palindex() * render fg palindex #230 * palette index color is out of 1000 * jungle demo works #253
2020-01-19 01:42:29 +00:00
**int ncplane_set_fg_palindex(struct ncplane* n, int idx);**
**int ncplane_set_bg_palindex(struct ncplane* n, int idx);**
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**void ncplane_styles_set(struct ncplane* n, unsigned stylebits);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**void ncplane_styles_on(struct ncplane* n, unsigned stylebits);**
notcurses_ncplane.3: add ncplane_clipped()
2020-01-12 09:12:43 +00:00
add ncplane_dim_[yx] quick accessors
2020-01-04 09:34:29 +00:00
**void ncplane_styles_off(struct ncplane* n, unsigned stylebits);**
**unsigned ncplane_styles(struct ncplane* n);**
notcurses_view: accept -s option
2020-01-17 09:31:46 +00:00
**void ncplane_greyscale(struct ncplane* n);**
rgba_blit()/bgrx_blit() #311
2020-02-02 07:20:01 +00:00
**int bgrx_blit(struct ncplane* nc, int placey, int placex, int linesize, const unsigned char* data, int begy, int begx, int leny, int lenx);**
**int rgba_blit(struct ncplane* nc, int placey, int placex, int linesize, const unsigned char* data, int begy, int begx, int leny, int lenx);**
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
## DESCRIPTION
Ncplanes are the fundamental drawing object of notcurses. All output functions
man page syntax fixes
2020-01-03 09:18:44 +00:00
take a **struct ncplane** as an argument. They can be any size, and placed
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
anywhere. In addition to its framebuffer--a rectilinear matrix of cells
(see **notcurses_cell(3)**)--an ncplane is defined by:
* a base cell, used for any cell on the plane without a glyph,
* the egcpool backing its cells,
* a current cursor location,
* a current style, foreground channel, and background channel,
* its geometry,
* a configured user pointer,
* its position relative to the visible plane, and
* its z-index.
# RETURN VALUES
implement ncplane_dup()
2020-01-15 17:22:10 +00:00
**ncplane_new(3)**, **ncplane_aligned(3)**, and **ncplane_dup(3)** all return a
new **struct ncplane** on success, or **NULL** on failure.
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
ncmenu: remove dumb restrictions/special casing
2020-02-10 20:18:28 +00:00
**ncplane_userptr(3)** returns the configured user pointer for the ncplane, and
cannot fail.
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
**ncplane_below(3)** returns the plane below the specified ncplane. If the provided
plane is the bottommost plane, NULL is returned. It cannot fail.
Functions returning **int** return 0 on success, and non-zero on error.
All other functions either cannot fail (and return **void**).
Chun Li demo (#251) * chun li demo * ncvisual_decode: allow multiple renders of the same frame * add -H to notcurses-demo man page * update section 1 man page versions
2020-01-04 12:21:54 +00:00
# NOTES
It would be reasonable to expect many of these functions to accept `const struct notcurses`
parameters. Alas, almost all must manipulate the mutex contained within the object.
ronn -> pandoc #245
2020-01-02 02:23:11 +00:00
# SEE ALSO
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_output(3)**,
**notcurses_stdplane(3)**
Reference in New Issue Copy Permalink