document new function ncvisual_inflate() #1546

NEWS.md

@@ -2,11 +2,12 @@ This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
 * 2.2.7 (not yet released)
-  * `cell_extended_gcluster()` has been deprecated in favor of the new
+  * All remaining functions prefixed with `cell_` or `cells_` have been
-    function `nccell_extended_gcluster()`, which the former now wraps.
+    deprecated in favor of versions prefixed with `nccell_` or `nccell_`,
-    It will be removed in ABI3. The same treatment has been applied to
+    respectively, which the former now wrap. The old versions will be
-    `cell_load_egc32()`, `cell_load_char()`, `cellcmp()`, `cell_init()`,
+    removed in ABI3.
-    `cell_extract()`, `cell_load()`, and `cell_prime()`.
+  * `ncvisual_inflate()` has been added to perform non-interpolative
+    enlarging. It is intended for use with pixel art.
 
 * 2.2.6 (2021-04-12)
   * `ncplane_rgba()` has been deprecated in favor of the new function

USAGE.md

@@ -3076,6 +3076,10 @@ int ncvisual_rotate(struct ncvisual* n, double rads);
 // transformation, unless the size is unchanged.
 int ncvisual_resize(struct ncvisual* n, int rows, int cols);
 
+// Inflate each pixel in the image to 'scale'x'scale' pixels. It is an error
+// if 'scale' is less than 1. The original color is retained.
+int ncvisual_inflate(struct ncvisual* n, int scale);
+
 // Polyfill at the specified location within the ncvisual 'n', using 'rgba'.
 int ncvisual_polyfill_yx(struct ncvisual* n, int y, int x, uint32_t rgba);
 

doc/man/man3/notcurses_visual.3.md

@@ -76,6 +76,8 @@ typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
 
 **int ncvisual_resize(struct ncvisual* ***n***, int ***rows***, int ***cols***);**
 
+**int ncvisual_inflate(struct ncvisual* ***n***, int ***scale***);**
+
 **int ncvisual_polyfill_yx(struct ncvisual* ***n***, int ***y***, int ***x***, uint32_t ***rgba***);**
 
 **int ncvisual_at_yx(const struct ncvisual* ***n***, int ***y***, int ***x***, uint32_t* ***pixel***);**
@@ -109,10 +111,14 @@ and codecs, but does not verify that the entire file is well-formed.
 per frame. **ncvisual_decode_loop** will return to the first frame,
 as if **ncvisual_decode** had never been called.
 
-Once the visual is loaded, it can be transformed using **ncvisual_rotate**
+Once the visual is loaded, it can be transformed using **ncvisual_rotate**,
-and **ncvisual_resize**. These are persistent operations, unlike any scaling
+**ncvisual_resize**, and **ncvisual_inflate**. These are persistent operations,
-that takes place at render time. If a subtitle is associated with the frame,
+unlike any scaling that takes place at render time. If a subtitle is associated
-it can be acquired with **ncvisual_subtitle**.
+with the frame, it can be acquired with **ncvisual_subtitle**.
+**ncvisual_resize** uses the media layer's best scheme to enlarge or shrink the
+original data, typically involving some interpolation. **ncvisual_inflate**
+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

include/notcurses/notcurses.h

@@ -2735,11 +2735,16 @@ API int ncvisual_decode_loop(struct ncvisual* nc)
 API int ncvisual_rotate(struct ncvisual* n, double rads)
   __attribute__ ((nonnull (1)));
 
-// Resize the visual so that it is 'rows' X 'columns'. This is a lossy
+// Resize the visual so that it is 'rows' X 'columns', using the best scheme
-// transformation, unless the size is unchanged.
+// available. This is a lossy transformation, unless the size is unchanged.
 API int ncvisual_resize(struct ncvisual* n, int rows, int cols)
   __attribute__ ((nonnull (1)));
 
+// Inflate each pixel in the image to 'scale'x'scale' pixels. It is an error
+// if 'scale' is less than 1. The original color is retained.
+API int ncvisual_inflate(struct ncvisual* n, int scale)
+  __attribute__ ((nonnull (1)));
+
 // Polyfill at the specified location within the ncvisual 'n', using 'rgba'.
 API int ncvisual_polyfill_yx(struct ncvisual* n, int y, int x, uint32_t rgba)
   __attribute__ ((nonnull (1)));