blackbeard420/notcurses
1
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses synced 2025-03-09 17:19:03 -04:00
Code Issues Projects Releases Wiki Activity

python/docs: declare ncvisual_from_plane()

Browse Source
This commit is contained in:
nick black 2020-05-06 20:10:01 -04:00
parent 43a685be1e
commit 90dacae213
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
3 changed files with 27 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
USAGE.md
View File

@ -2452,8 +2452,22 @@ a file. Both RGBA and BGRA 8bpc arrangements can be used.
// are actual data. There must be 'rows' lines. The total size of 'rgba'
// must thus be at least (rows * rowstride) bytes, of which (rows * cols * 4)
// bytes are actual data. The resulting plane will be ceil('rows'/2)x'cols'.
ncvisual* ncvisual_from_rgba(notcurses* nc, const void* rgba, int rows, int rowstride, int cols);
struct ncvisual* ncvisual_from_rgba(struct notcurses* nc, const void* rgba,
int rows, int rowstride, int cols);
// ncvisual_from_rgba(), but for BGRA.
ncvisual* ncvisual_from_bgra(notcurses* nc, const void* bgra, int rows, int rowstride, int cols);
struct ncvisual* ncvisual_from_bgra(struct notcurses* nc, const void* bgra,
int rows, int rowstride, int cols);
```
Finally, an `ncvisual` can be "promoted" from the contents of a plane.
```c
// Promote an ncplane 'n' to an ncvisual. The plane should not be associated
// with an existing ncvisual, and may contain only spaces, half blocks, and
// full blocks. The latter will be checked, and any other glyph will result
// in a NULL being returned. This function exists so that planes can be
// subjected to ncvisual transformations. If possible, it's usually better
// to create the ncvisual from memory using ncvisual_from_rgba().
struct ncvisual* ncvisual_from_plane(struct ncplane* n);
```

10
doc/man/man3/notcurses_visual.3.md
View File

@ -32,6 +32,8 @@ typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
**struct ncvisual* ncvisual_from_bgra(struct notcurses* nc, const void* bgra, int rows, int rowstride, int cols);**
**struct ncvisual* ncvisual_from_plane(struct ncplane* n);**
**void ncvisual_destroy(struct ncvisual* ncv);**
**nc_err_e ncvisual_decode(struct ncvisual* nc);**
@ -74,6 +76,11 @@ is necessary. The resulting plane will be ceil(**rows**/2) rows, and **cols**
columns. It will not be necessary to call **ncvisual_decode**, but it is
still necessary to call **ncvisual_render**.
The contents of an **ncplane** can be "promoted" into an **ncvisual** with
**ncvisual_from_ncplane**. The existing plane will be bound and decoded to a
new **ncvisual**. Only spaces, half blocks, and full blocks may be present
in the plane.
**ncvisual_rotate** executes a rotation of **rads** radians, in the clockwise
(positive) or counterclockwise (negative) direction. If the **ncvisual** owns
(created) its underlying **ncplane**, that plane will be resized as necessary
@ -96,6 +103,9 @@ will be updated. **ncvisual_decode** returns **NCERR_SUCCESS** on success, or
likewise updates **err** in the event of an error. **ncvisual_render** returns
the number of cells emitted, or -1 on error.
**ncvisual_from_plane** returns **NULL** if the **ncvisual** cannot be created
and bound. This is usually due to illegal content in the source **ncplane**.
# NOTES
Multimedia decoding requires that Notcurses be built with either FFmpeg or

1
python/src/notcurses/build_notcurses.py
View File

@ -431,6 +431,7 @@ int ncplane_rotate_cw(struct ncplane* n);
int ncplane_rotate_ccw(struct ncplane* n);
int ncvisual_rotate(struct ncvisual* n, double rads);
void ncplane_translate(const struct ncplane* src, const struct ncplane* dst, int* y, int* x);
struct ncvisual* ncvisual_from_plane(struct ncplane* n);
bool ncplane_translate_abs(const struct ncplane* n, int* y, int* x);
typedef enum {
NCPLOT_1x1, // full block █