add and document sprixelbytes stat #1801

NEWS.md

@@ -27,6 +27,7 @@ rearrangements of Notcurses.
   * Added `NCDIRECT_OPTION_VERBOSE` and `NCDIRECT_OPTION_VERY_VERBOSE`.
     They map to `NCLOGLEVEL_WARNING` and `NCLOGLEVEL_TRACE`, respectively.
   * New functions `ncvisual_from_rgb_packed()` and `ncvisual_from_rgb_loose()`.
+  * New stat `sprixelbytes`.
 
 * 2.3.4 (2021-06-12)
   * Added the flag `NCVISUAL_OPTION_NOINTERPOLATE` to use non-interpolative

USAGE.md

@@ -3399,6 +3399,7 @@ typedef struct ncstats {
   uint64_t refreshes;        // refresh requests (non-optimized redraw)
   uint64_t sprixelemissions; // sprixel draw count
   uint64_t sprixelelisions;  // sprixel elision count
+  uint64_t sprixelbytes;     // sprixel bytes emitted
 
   // current state -- these can decrease
   uint64_t fbbytes;          // total bytes devoted to all active framebuffers

doc/man/man3/notcurses_stats.3.md

@@ -40,6 +40,7 @@ typedef struct ncstats {
   uint64_t refreshes;        // refreshes (unoptimized redraws)
   uint64_t sprixelemissions; // sprixel draw count
   uint64_t sprixelelisions;  // sprixel elision count
+  uint64_t sprixelbytes;     // sprixel bytes emitted
 
   // current state -- these can decrease
   uint64_t fbbytes;          // bytes devoted to framebuffers
@@ -107,6 +108,8 @@ plane.
 **sprixelemissions** is the number of sprixel draws. **sprixelelisions** is
 the number of times a sprixel was elided--essentially, the number of times
 a sprixel appeared in a rendered frame without freshly drawing it.
+**sprixelbytes** is the number of bytes used for sprixel drawing. It does not
+include move/delete operations, nor glyphs used to erase sprixels.
 
 # NOTES
 

include/notcurses/notcurses.h

@@ -1404,6 +1404,7 @@ typedef struct ncstats {
   int64_t raster_min_ns;     // min ns spent in raster for a frame
   uint64_t sprixelemissions; // sprixel draw count
   uint64_t sprixelelisions;  // sprixel elision count
+  uint64_t sprixelbytes;     // sprixel bytes emitted
 } ncstats;
 
 // Allocate an ncstats object. Use this rather than allocating your own, since