Archives/notcurses
2
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses.git synced 2024-10-31 15:20:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

ncvisual.3: update man page

Browse Source
This commit is contained in:
nick black 2020-05-29 01:47:53 -04:00
parent f47bde1c4e
commit 899adf873d
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
1 changed files with 25 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -40,9 +40,7 @@ struct ncvisual_options {
uint64_t flags; // bitmask over NCVISUAL_OPTIONS_* uint64_t flags; // bitmask over NCVISUAL_OPTIONS_*
}; };
typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
``` ```
**bool notcurses_canopen_images(const struct notcurses* nc);** **bool notcurses_canopen_images(const struct notcurses* nc);**
@ -77,32 +75,32 @@ struct ncvisual_options {
# DESCRIPTION # DESCRIPTION
The frame will be scaled to the size of the ncplane per the ncscale_e style. An **ncvisual** is a virtual pixel framebuffer. They can be created from
**ncvisual_render** actually blits the decoded frame to its associated plane. RGBA/BGRA data in memory (**ncvisual_from_rgba**/**ncvisual_from_bgra**),
A subregion of the frame can be specified using **begx**, **begy**, **lenx**, or from the content of a suitable **ncplane** (**ncvisual_from_ncplane**).
and **leny**. To render the rectangle having its origin at **begy**, **begx** If Notcurses was built against a multimedia engine (FFMpeg or OpenImageIO),
and the lower-right corner, -1 can be supplied as **leny** and **lenx**. image and video files can be loaded into visuals using
{0, 0, -1, -1} will thus render the entire visual. Negative values for **begy** **ncvisual_from_file**. **ncvisual_from_file** discovers the container
or **begx** are an error. It is an error to specify any region beyond the and codecs, but does not verify that the entire file is well-formed.
boundaries of the frame. Supplying zero for either **leny** or **lenx** will **ncvisual_decode** ought be invoked to recover the actual frames, once
result in a zero-area rendering. per frame.
It is possible to create an **ncvisual** from memory, rather than from a Once the visual is loaded, it can be transformed using **ncvisual_rotate**
disk, but only using raw RGBA/BGRA 8bpc content. For RGBA, use and **ncvisual_resize**. These are persistent operations, unlike any scaling
**ncvisual_from_rgba**. For BGRA, use **ncvisual_from_bgra**. Both require that takes place at render time. If a subtitle is associated with the frame,
a number of **rows**, a number of image columns **cols**, and a virtual row it can be acquired with **ncvisual_subtitle**.
length of **rowstride** / 4 columns. The input data must provide 32 bits per
pixel, and thus must be at least **rowstride** * **rows** bytes, of
which a **cols** * **rows** * 4-byte subset is used. It is not possible to
**mmap(2)** an image file and use it directly--decompressed, decoded data
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_rgba** and **ncvisual_from_bgra** both require a number of
**ncvisual_from_ncplane**. The existing plane will be bound and decoded to a **rows**, a number of image columns **cols**, and a virtual row length of
new **ncvisual**. Only spaces, half blocks, and full blocks may be present **rowstride** / 4 columns. The input data must provide 32 bits per pixel, and
in the plane. thus must be at least **rowstride** * **rows** bytes, of which a **cols** *
**rows** * 4-byte subset is used. It is not possible to **mmap(2)** an image
file and use it directly--decompressed, decoded data is necessary. The
resulting plane will be ceil(**rows**/2) rows, and **cols** columns.
**ncvisual_from_plane** requires specification of a rectangle via **begy**,
**begx**, **leny**, and **lenx**. The only valid characters within this
region are those used by the **NCBLIT_2x2** blitter, though this may change
in the future.
**ncvisual_rotate** executes a rotation of **rads** radians, in the clockwise **ncvisual_rotate** executes a rotation of **rads** radians, in the clockwise
(positive) or counterclockwise (negative) direction. If the **ncvisual** owns (positive) or counterclockwise (negative) direction. If the **ncvisual** owns