[info] differentiate between kitty animation and kitty selfref #2161

NEWS.md

@@ -1,6 +1,11 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 2.4.1 (not yet released)
+  * `notcurses_check_pixel_support()` still returns 0 if there is no support
+    for bitmap graphics, but now returns an `ncpixelimple_e` to differentiate
+    the pixel backend otherwise. This result is strictly informative.
+
 * 2.4.0 (2021-09-06)
   * Mouse events in the Linux console are now reported from GPM when built
     with `-DUSE_GPM=on`.

USAGE.md

@@ -334,10 +334,10 @@ bool notcurses_cansextants(const struct notcurses* nc);
 // Can we draw Braille? The Linux console cannot.
 bool notcurses_canbraille(const struct notcurses* nc);
 
-// This function must successfully return before NCBLIT_PIXEL is available.
+// Returns a non-zero constant corresponding to some pixel-blitting
-// Returns -1 on error, 0 for no support, or 1 if pixel output is supported.
+// mechanism if bitmap support (via any mechanism) has been detected,
-// Must not be called concurrently with either input or rasterization.
+// or else 0 (NCPIXEL_NONE).
-int notcurses_check_pixel_support(struct notcurses* nc);
+ncpixelimpl_e notcurses_check_pixel_support(struct notcurses* nc);
 ```
 
 ## Direct mode

doc/man/man3/notcurses_capabilities.3.md

@@ -36,7 +36,7 @@ notcurses_capabilities - runtime capability detection
 
 **bool notcurses_canbraille(const struct notcurses* ***nc***);**
 
-**int notcurses_check_pixel_support(struct notcurses* ***nc***);**
+**ncpixelimpl_e notcurses_check_pixel_support(struct notcurses* ***nc***);**
 
 # DESCRIPTION
 
@@ -86,8 +86,9 @@ quadrants and halfblocks, respectively. **notcurses_canbraille** returns
 **true** if Unicode Braille is expected to work on the terminal. None of
 these functions return **true** unless UTF-8 encoding is in use.
 
-**notcurses_check_pixel_support** returns 1 if bitmap support (via any
+**notcurses_check_pixel_support** returns a non-zero pixel implementation
-mechanism) has been detected, and otherwise 0.
+if bitmap support (via any mechanism) has been detected, and otherwise 0
+(**NCPIXEL_NONE**).
 
 # NOTES
 
@@ -95,8 +96,6 @@ Some terminals advertise support for TrueColor, but then downsample or
 otherwise degrade the provided RGB. In this case **notcurses_cantruecolor**
 will return **true**, but the full spectrum will not be available.
 
-# RETURN VALUES
-
 # SEE ALSO
 
 **notcurses(3)**,

include/notcurses/notcurses.h

@@ -1423,8 +1423,20 @@ API bool notcurses_cansextant(const struct notcurses* nc)
 API bool notcurses_canbraille(const struct notcurses* nc)
   __attribute__ ((nonnull (1))) __attribute__ ((pure));
 
+// pixel blitting implementations. informative only; don't special-case
+// based off any of this information!
+typedef enum {
+  NCPIXEL_NONE = 0,
+  NCPIXEL_SIXEL,           // sixel
+  NCPIXEL_LINUXFB,         // linux framebuffer
+  NCPIXEL_ITERM2,          // iTerm2
+  NCPIXEL_KITTY_STATIC,    // kitty prior to C=1 and animation
+  NCPIXEL_KITTY_ANIMATED,  // kitty with animation but not selfref
+  NCPIXEL_KITTY_SELFREF,   // kitty with reflexive composition
+} ncpixelimpl_e;
+
 // Can we blit pixel-accurate bitmaps?
-API int notcurses_check_pixel_support(const struct notcurses* nc)
+API ncpixelimpl_e notcurses_check_pixel_support(const struct notcurses* nc)
   __attribute__ ((nonnull (1))) __attribute__ ((pure));
 
 // whenever a new field is added here, ensure we add the proper rule to

src/info/main.c

@@ -341,23 +341,34 @@ tinfo_debug_bitmaps(struct ncplane* n, const tinfo* ti, const char* indent){
                  ti->bg_collides_default & 0xfffffful,
                  (ti->bg_collides_default & 0x01000000) ? "" : "not ");
   finish_line(n);
-  if(!ti->pixel_draw && !ti->pixel_draw_late){
+  ncpixelimpl_e blit = notcurses_check_pixel_support(ncplane_notcurses(n));
-    ncplane_printf(n, "%sno bitmap graphics detected", indent);
+  switch(blit){
-  }else{ // we do have support; draw one
+    case NCPIXEL_NONE:
-    if(ti->color_registers){
+      ncplane_printf(n, "%sno bitmap graphics detected", indent);
+      break;
+    case NCPIXEL_SIXEL:
       if(ti->sixel_maxy){
         ncplane_printf(n, "%smax sixel size: %dx%d colorregs: %u",
                       indent, ti->sixel_maxy, ti->sixel_maxx, ti->color_registers);
       }else{
         ncplane_printf(n, "%ssixel colorregs: %u", indent, ti->color_registers);
       }
-    }else if(ti->pixel_draw_late){
+      break;
+    case NCPIXEL_LINUXFB:
       ncplane_printf(n, "%sframebuffer graphics supported", indent);
-    }else if(ti->sixel_maxy_pristine){
+      break;
+    case NCPIXEL_ITERM2:
+      ncplane_printf(n, "%siTerm2 graphics supported", indent);
+      break;
+    case NCPIXEL_KITTY_STATIC:
       ncplane_printf(n, "%srgba pixel graphics support", indent);
-    }else{ // FIXME differentiate between 1st and 2nd gen?
+      break;
-      ncplane_printf(n, "%srgba pixel animation support", indent);
+    case NCPIXEL_KITTY_ANIMATED:
-    }
+      ncplane_printf(n, "%s1st gen rgba pixel animation support", indent);
+      break;
+    case NCPIXEL_KITTY_SELFREF:
+      ncplane_printf(n, "%s2nd gen rgba pixel animation support", indent);
+      break;
   }
   finish_line(n);
 }

src/lib/notcurses.c

@@ -984,11 +984,8 @@ recursive_lock_init(pthread_mutex_t *lock){
 #endif
 }
 
-int notcurses_check_pixel_support(const notcurses* nc){
+ncpixelimpl_e notcurses_check_pixel_support(const notcurses* nc){
-  if(nc->tcache.pixel_draw || nc->tcache.pixel_draw_late){
+  return nc->tcache.pixel_implementation;
-    return 1;
-  }
-  return 0;
 }
 
 // FIXME cut this up into a few distinct pieces, yearrrgh

src/lib/termdesc.c

@@ -67,6 +67,7 @@ setup_sixel_bitmaps(tinfo* ti, int fd, bool invert80){
   ti->pixel_trans_auxvec = sixel_trans_auxvec;
   ti->sprixel_scale_height = 6;
   set_pixel_blitter(sixel_blit);
+  ti->pixel_implementation = NCPIXEL_SIXEL;
   sprite_init(ti, fd);
 }
 
@@ -91,17 +92,20 @@ setup_kitty_bitmaps(tinfo* ti, int fd, kitty_graphics_e level){
     ti->pixel_rebuild = kitty_rebuild;
     ti->sixel_maxy_pristine = INT_MAX;
     set_pixel_blitter(kitty_blit);
+    ti->pixel_implementation = NCPIXEL_KITTY_STATIC;
   }else{
     if(level == KITTY_ANIMATION){
       ti->pixel_wipe = kitty_wipe_animation;
       ti->pixel_rebuild = kitty_rebuild_animation;
       ti->sixel_maxy_pristine = 0;
       set_pixel_blitter(kitty_blit_animated);
+      ti->pixel_implementation = NCPIXEL_KITTY_ANIMATED;
     }else{
       ti->pixel_wipe = kitty_wipe_selfref;
       ti->pixel_rebuild = kitty_rebuild_selfref;
       ti->sixel_maxy_pristine = 0;
       set_pixel_blitter(kitty_blit_selfref);
+      ti->pixel_implementation = NCPIXEL_KITTY_SELFREF;
     }
   }
   sprite_init(ti, fd);
@@ -124,6 +128,7 @@ setup_fbcon_bitmaps(tinfo* ti, int fd){
   ti->pixel_wipe = fbcon_wipe;
   ti->pixel_trans_auxvec = kitty_trans_auxvec;
   set_pixel_blitter(fbcon_blit);
+  ti->pixel_implementation = NCPIXEL_LINUXFB;
   sprite_init(ti, fd);
 }
 #endif

src/lib/termdesc.h

@@ -150,7 +150,9 @@ typedef struct tinfo {
   // bg_collides_default is either 0x0000000 or (if in use) 0x1RRGGBB.
   uint32_t bg_collides_default;
 
-  // bitmap support. if we support bitmaps, pixel_draw will be non-NULL
+  // bitmap support. if we support bitmaps, pixel_implementation will be a
+  // value other than NCPIXEL_NONE.
+  ncpixelimpl_e pixel_implementation;
   // wipe out a cell's worth of pixels from within a sprixel. for sixel, this
   // means leaving out the pixels (and likely resizes the string). for kitty,
   // this means dialing down their alpha to 0 (in equivalent space).