diff --git a/NEWS.md b/NEWS.md index 844addcf7..ba0aab83c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,10 @@ This document attempts to list user-visible changes and any major internal rearrangements of Notcurses. +* 2.2.10 (not yet released) + * Added `NCVISUAL_OPTION_CHILDPLANE` to interpret the `n` field of + `ncvisual_options` as a parent plane. + * 2.2.9 (2021-05-03) * Added two new stats, `sprixelemissions` and `sprixelelisions`. * Added `notcurses_canhalfblock()` and `notcurses_canquadrant()`. diff --git a/USAGE.md b/USAGE.md index 217b7ff0d..b6c462fc0 100644 --- a/USAGE.md +++ b/USAGE.md @@ -3149,6 +3149,8 @@ const char* notcurses_str_blitter(ncblitter_e blitter); #define NCVISUAL_OPTION_BLEND 0x0002ull // use CELL_ALPHA_BLEND with visual #define NCVISUAL_OPTION_HORALIGNED 0x0004ull // x is an alignment, not absolute #define NCVISUAL_OPTION_VERALIGNED 0x0008ull // y is an alignment, not absolute +#define NCVISUAL_OPTION_ADDALPHA 0x0010ull // transcolor is transparent +#define NCVISUAL_OPTION_CHILDPLANE 0x0020ull // new plane is child of n struct ncvisual_options { // if no ncplane is provided, one will be created using the exact size @@ -3176,6 +3178,7 @@ struct ncvisual_options { // chosen for NCBLIT_DEFAULT. ncblitter_e blitter; // glyph set to use (maps input to output cells) uint64_t flags; // bitmask over NCVISUAL_OPTION_* + uint32_t transcolor; // used only if NCVISUAL_OPTION_ADDALPHA is set }; typedef enum { diff --git a/doc/man/man3/notcurses_visual.3.md b/doc/man/man3/notcurses_visual.3.md index 45177fffc..63e3acb32 100644 --- a/doc/man/man3/notcurses_visual.3.md +++ b/doc/man/man3/notcurses_visual.3.md @@ -35,6 +35,7 @@ typedef enum { #define NCVISUAL_OPTION_HORALIGNED 0x0004 #define NCVISUAL_OPTION_VERALIGNED 0x0008 #define NCVISUAL_OPTION_ADDALPHA 0x0010 +#define NCVISUAL_OPTION_CHILDPLANE 0x0020 struct ncvisual_options { struct ncplane* n; @@ -121,18 +122,18 @@ maps each pixel to ***scale***x***scale*** pixels square, retaining the original color; it is an error if ***scale*** is less than one. **ncvisual_from_rgba** and **ncvisual_from_bgra** both require a number of -**rows**, a number of image columns **cols**, and a virtual row 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 +***rows***, a number of image columns **cols**, and a virtual row 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. -**ncvisual_from_plane** requires specification of a rectangle via **begy**, -**begx**, **leny**, and **lenx**. The only valid characters within this +**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. **ncvisual_subtitle** will return a UTF-8-encoded subtitle corresponding to @@ -140,17 +141,20 @@ the current frame if such a subtitle was decoded. Note that a subtitle might be returned for multiple frames, or might not. **ncvisual_render** blits the visual to an **ncplane**, based on the contents -of its **struct ncvisual_options**. If **n** is not **NULL**, it specifies the -plane on which to render, and **y**/**x** specify a location within that plane. -Otherwise, a new plane will be created, and placed at **y**/**x** relative to -the rendering area. **begy**/**begx** specify the upper left corner of a -subsection of the **ncvisual** to render, while **leny**/**lenx** specify the -geometry of same. **flags** is a bitfield over: +of its **struct ncvisual_options**. If ***n*** is not **NULL**, it specifies the +plane on which to render, and ***y***/***x*** specify a location within that plane. +Otherwise, a new plane will be created, and placed at ***y***/***x*** relative to +the rendering area. ***begy***/***begx*** specify the upper left corner of a +subsection of the **ncvisual** to render, while ***leny***/***lenx*** specify the +geometry of same. ***flags*** is a bitfield over: * **NCVISUAL_OPTION_NODEGRADE** If the specified blitter is not available, fail rather than degrading. * **NCVISUAL_OPTION_BLEND**: Render with **CELL_ALPHA_BLEND**. * **NCVISUAL_OPTION_HORALIGNED**: Interpret ***x*** as an **ncalign_e**. * **NCVISUAL_OPTION_VERALIGNED**: Interpret ***y*** as an **ncalign_e**. +* **NCVISUAL_OPTION_ADDALPHA**: Interpret the lower 24 bits of ***transcolor*** + as a transparent color. +* **NCVISUAL_OPTION_CHILDPLANE**: Make a new plane, as a child of ***n***. **ncvisual_blitter_geom** allows the caller to determine any or all of the visual's pixel geometry, the blitter to be used, and that blitter's scaling @@ -162,23 +166,26 @@ Code scanners, due to its 1:1 aspect ratio). # OPTIONS -**begy** and **begx** specify the upper left corner of the image to start -drawing. **leny** and **lenx** specify the area of the subimage drawn. -**leny** and/or **lenx** may be specified as a negative number to draw +***begy*** and ***begx*** specify the upper left corner of the image to start +drawing. ***leny*** and ***lenx*** specify the area of the subimage drawn. +***leny*** and/or ***lenx*** may be specified as a negative number to draw through the bottom right corner of the image. -The **n** field specifies the plane to use. If this is **NULL**, a new plane +The ***n*** field specifies the plane to use. If this is **NULL**, a new plane will be created, having the precise geometry necessary to blit the specified section of the image. This might be larger (or smaller) than the visual area. -**y** and **x** have different meanings depending on whether or not **n** was -**NULL**. If not (drawing onto a preexisting plane), they specify where in -the plane to start drawing. If **n** was **NULL** (new plane), they specify -the origin of the new plane relative to the standard plane. If the **flags** -field contains **NCVISUAL_OPTION_HORALIGNED**, the **x** parameter is -interpreted as an **ncalign_e** rather than an absolute position. If the -**flags** field contains **NCVISUAL_OPTION_VERALIGNED**, the **y** parameter -is interpreted as an **ncalign_e** rather than an absolute position. +***y*** and ***x*** have different meanings depending on whether or not +***n*** is **NULL**. If not (drawing onto a preexisting plane), they specify +where in the plane to start drawing. If **n** was **NULL** (new plane), they +specify the origin of the new plane relative to the standard plane. If the +***flags*** field contains **NCVISUAL_OPTION_HORALIGNED**, the ***x*** parameter +is interpreted as an **ncalign_e** rather than an absolute position. If the +***flags*** field contains **NCVISUAL_OPTION_VERALIGNED**, the ***y*** parameter +is interpreted as an **ncalign_e** rather than an absolute position. If the +***flags*** field contains **NCVISUAL_OPTION_CHILDPLANE**, ***n*** must be +non-**NULL**, and the ***x*** and ***y*** parameters are interpreted relative +to that plane. # BLITTERS