s/NCBLIT_SIXEL/NCBLIT_PIXEL/g #1095

USAGE.md

@@ -298,7 +298,7 @@ bool notcurses_canchangecolor(const struct notcurses* nc);
 // Is our encoding UTF-8? Requires LANG being set to a UTF-8 locale.
 bool notcurses_canutf8(const struct notcurses* nc);
 
-// Can we blit to Sixel? This requires being built against libsixel.
+// Can we blit to Sixel? Without NCOPTION_VERIFY_SIXEL, this always returns false.
 bool notcurses_cansixel(const struct notcurses* nc);
 
 // Can we draw sextants? This requires Unicode 13.

doc/man/man3/notcurses_capabilities.3.md

@@ -30,7 +30,7 @@ notcurses_capabilities - runtime capability detection
 
 **bool notcurses_canbraille(const struct notcurses* ***nc***);**
 
-**bool notcurses_cansixel(const struct notcurses* ***nc***);**
+**bool notcurses_canpixel(const struct notcurses* ***nc***);**
 
 # DESCRIPTION
 
@@ -65,14 +65,16 @@ UTF-8 encoding, and the locale was successfully loaded.
 **notcurses_cansextant** returns **true** if the heuristics suggest
 that the terminal can properly render Unicode 13 sextants.
 
-**notcurses_cansixel** returns **true** if the terminal advertises
-support for Sixel. **notcurses_canbraille** returns **true** if Braille
-is expected to work on the terminal.
+**notcurses_canpixel** returns **true** if the terminal advertises
+support for pixel graphics (e.g. Sixel).
+
+**notcurses_canbraille** returns **true** if Braille is expected to work on the
+terminal.
 
 # BUGS
 
-Notcurses does not yet have Sixel support, and thus **notcurses_cansixel**
-will always return **false**.
+**notcurses_canpixel** currently only returns non-zero if 
+**NCOPTION_VERIFY_SIXEL** was passed to **notcurses_init(3)**.
 
 # NOTES
 
@@ -85,4 +87,5 @@ will return **true**, but the full spectrum will not be available.
 # SEE ALSO
 
 **notcurses(3)**,
+**notcurses_init(3)**,
 utf8(7)

doc/man/man3/notcurses_visual.3.md

@@ -27,7 +27,7 @@ typedef enum {
   NCBLIT_4x1,     // four vertical levels
   NCBLIT_BRAILLE, // 4 rows, 2 cols (braille)
   NCBLIT_8x1,     // eight vertical levels
-  NCBLIT_SIXEL,   // not yet implemented
+  NCBLIT_PIXEL,   // pixel graphics
 } ncblitter_e;
 
 #define NCVISUAL_OPTION_NODEGRADE 0x0001
@@ -46,12 +46,6 @@ struct ncvisual_options {
 typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
 ```
 
-**bool notcurses_canopen_images(const struct notcurses* ***nc***);**
-
-**bool notcurses_canopen_videos(const struct notcurses* ***nc***);**
-
-**bool notcurses_cansixel(const struct notcurses* ***nc***);**
-
 **struct ncvisual* ncvisual_from_file(const char* ***file***);**
 
 **struct ncvisual* ncvisual_from_rgba(const void* ***rgba***, int ***rows***, int ***rowstride***, int ***cols***);**
@@ -162,13 +156,18 @@ The different **ncblitter_e** values select from among available glyph sets:
 * **NCBLIT_4x1**: Adds ¼ and ¾ blocks (▂▆) to **NCBLIT_2x1**.
 * **NCBLIT_BRAILLE**: 4 rows and 2 columns of braille (⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿).
 * **NCBLIT_8x1**: Adds ⅛, ⅜, ⅝, and ⅞ blocks (▇▅▃▁) to **NCBLIT_4x1**.
-* **NCBLIT_SIXEL**: Not yet implemented.
+* **NCBLIT_PIXEL**: Adds pixel graphics.
 
 **NCBLIT_4x1** and **NCBLIT_8x1** are intended for use with plots, and are
 not really applicable for general visuals. **NCBLIT_BRAILLE** doesn't tend
 to work out very well for images, but (depending on the font) can be very
 good for plots.
 
+A string can be transformed to a blitter with **notcurses_lex_blitter**,
+recognizing **ascii**, **halfblock**, **quadblitter**, **sexblitter**,
+**fourstep**, **braille**, **eightstep**, and **pixel**. Conversion in the
+opposite direction is performed with **notcurses_str_blitter**.
+
 In the absence of scaling, for a given set of pixels, more rows and columns in
 the blitter will result in a smaller output image. An image rendered with
 **NCBLIT_1x1** will be twice as tall as the same image rendered with
@@ -179,6 +178,11 @@ depends on **NCSCALE_NONE**). If the output size is held constant (using for
 instance **NCSCALE_SCALE_HIRES** and a large image), more rows and columns will
 result in more effective resolution.
 
+A string can be transformed to a scaling mode with **notcurses_lex_scalemode**,
+recognizing **stretch**, **scalehi**, **hires**, **scale**, and **none**.
+Conversion in the opposite direction is performed with
+**notcurses_str_scalemode**.
+
 Assuming a cell is twice as tall as it is wide, **NCBLIT_1x1** (and indeed
 any NxN blitter) will stretch an image by a factor of 2 in the vertical
 dimension. **NCBLIT_2x1** will not distort the image whatsoever, as it maps a
@@ -201,10 +205,6 @@ information.
 
 # RETURN VALUES
 
-**notcurses_canopen_images** and **notcurses_canopen_videos** returns true if
-images and videos, respecitvely, can be decoded, or false if Notcurses was
-built with insufficient multimedia support.
-
 **ncvisual_from_file** returns an **ncvisual** object on success, or **NULL**
 on failure. Success indicates that the specified **file** was opened, and
 enough data was read to make a firm codec identification. It does not imply
@@ -244,9 +244,6 @@ linked library. OpenImageIO does not support subtitles.
 **ncvisual_rotate** currently supports only **M_PI**/2 and -**M_PI**/2
 radians for **rads**, but this will change soon.
 
-**NCBLIT_SIXEL** is not yet implemented, and is only infrequently supported
-among terminals.
-
 Bad font support can ruin **NCBLIT_2x2**, **NCBLIT_3x2**, **NCBLIT_4x1**,
 **NCBLIT_BRAILLE**, and **NCBLIT_8x1**. Braille glyphs ought ideally draw only
 the raised dots, rather than drawing all eight dots with two different styles.

include/notcurses/notcurses.h

@@ -67,7 +67,7 @@ typedef enum {
   NCBLIT_4x1,     // four vertical levels     █▆▄▂
   NCBLIT_BRAILLE, // 4 rows, 2 cols (braille) ⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿
   NCBLIT_8x1,     // eight vertical levels    █▇▆▅▄▃▂▁
-  NCBLIT_SIXEL,   // not yet implemented
+  NCBLIT_PIXEL,   // pixel graphics
 } ncblitter_e;
 
 // Alignment within a plane or terminal. Left/right-justified, or centered.
@@ -1234,8 +1234,8 @@ API bool notcurses_cansextant(const struct notcurses* nc);
 // Can we reliably use Unicode Braille?
 API bool notcurses_canbraille(const struct notcurses* nc);
 
-// Can we blit to Sixel?
-API bool notcurses_cansixel(const struct notcurses* nc);
+// Can we blit to pixel graphics?
+API bool notcurses_canpixel(const struct notcurses* nc);
 
 typedef struct ncstats {
   // purely increasing stats
@@ -3432,8 +3432,6 @@ struct blitset {
   bool fill;
 };
 
-API extern const struct blitset notcurses_blitters[];
-
 // replaced by ncvisual_media_defblitter(). this original version never returns
 // NCBLIT_3x2.
 static inline ncblitter_e

src/lib/blit.c

@@ -837,7 +837,7 @@ braille_blit(ncplane* nc, int placey, int placex, int linesize,
 
 // NCBLIT_DEFAULT is not included, as it has no defined properties. It ought
 // be replaced with some real blitter implementation by the calling widget.
-const struct blitset notcurses_blitters[] = {
+static const struct blitset notcurses_blitters[] = {
    { .geom = NCBLIT_8x1,     .width = 1, .height = 8, .egcs = L" ▁▂▃▄▅▆▇█",
      .blit = tria_blit,      .name = "eightstep",     .fill = false, },
    { .geom = NCBLIT_1x1,     .width = 1, .height = 1, .egcs = L" █",
@@ -852,8 +852,8 @@ const struct blitset notcurses_blitters[] = {
      .blit = tria_blit,      .name = "fourstep",      .fill = false, },
    { .geom = NCBLIT_BRAILLE, .width = 2, .height = 4, .egcs = L"⠀⢀⢠⢰⢸⡀⣀⣠⣰⣸⡄⣄⣤⣴⣼⡆⣆⣦⣶⣾⡇⣇⣧⣷⣿",
      .blit = braille_blit,   .name = "braille",       .fill = true,  },
-   { .geom = NCBLIT_SIXEL,   .width = 1, .height = 6, .egcs = L"",
-     .blit = NULL,           .name = "sixel",         .fill = true,  }, // FIXME
+   { .geom = NCBLIT_PIXEL,   .width = 1, .height = 6, .egcs = L"",
+     .blit = NULL, /* FIXME*/.name = "pixel",         .fill = true,  },
    { .geom = 0,              .width = 0, .height = 0, .egcs = NULL,
      .blit = NULL,           .name = NULL,            .fill = false,  },
 };
@@ -937,6 +937,44 @@ int ncblit_rgba(const void* data, int linesize, const struct ncvisual_options* v
                     leny, lenx, blend);
 }
 
+const struct blitset* lookup_blitset(const tinfo* tcache, ncblitter_e setid, bool may_degrade) {
+  if(setid == NCBLIT_DEFAULT){ // ought have resolved NCBLIT_DEFAULT before now
+    return NULL;
+  }
+  // without braille support, NCBLIT_BRAILLE decays to NCBLIT_3x2
+  if(!tcache->braille && setid == NCBLIT_BRAILLE){
+    if(may_degrade){
+      setid = NCBLIT_3x2;
+    }else{
+      return NULL;
+    }
+  }
+  // without sextant support, NCBLIT_3x2 decays to NCBLIT_2x2
+  if(!tcache->sextants && setid == NCBLIT_3x2){
+    if(may_degrade){
+      setid = NCBLIT_2x2;
+    }else{
+      return NULL;
+    }
+  }
+  // the only viable blitter in ASCII is NCBLIT_1x1
+  if(!tcache->utf8 && setid != NCBLIT_1x1){
+    if(may_degrade){
+      setid = NCBLIT_1x1;
+    }else{
+      return NULL;
+    }
+  }
+  const struct blitset* bset = notcurses_blitters;
+  while(bset->egcs){
+    if(bset->geom == setid){
+      return bset;
+    }
+    ++bset;
+  }
+  return NULL;
+}
+
 ncblitter_e ncvisual_media_defblitter(const notcurses* nc, ncscale_e scale){
   return rgba_blitter_default(&nc->tcache, scale);
 }

src/lib/blitset.h

@@ -3,45 +3,6 @@
 
 #include "notcurses/notcurses.h"
 
-static inline const struct blitset*
-lookup_blitset(const tinfo* tcache, ncblitter_e setid, bool may_degrade) {
-  if(setid == NCBLIT_DEFAULT){ // ought have resolved NCBLIT_DEFAULT before now
-    return NULL;
-  }
-  // without braille support, NCBLIT_BRAILLE decays to NCBLIT_3x2
-  if(!tcache->braille && setid == NCBLIT_BRAILLE){
-    if(may_degrade){
-      setid = NCBLIT_3x2;
-    }else{
-      return NULL;
-    }
-  }
-  // without sextant support, NCBLIT_3x2 decays to NCBLIT_2x2
-  if(!tcache->sextants && setid == NCBLIT_3x2){
-    if(may_degrade){
-      setid = NCBLIT_2x2;
-    }else{
-      return NULL;
-    }
-  }
-  // the only viable blitter in ASCII is NCBLIT_1x1
-  if(!tcache->utf8 && setid != NCBLIT_1x1){
-    if(may_degrade){
-      setid = NCBLIT_1x1;
-    }else{
-      return NULL;
-    }
-  }
-  const struct blitset* bset = notcurses_blitters;
-  while(bset->egcs){
-    if(bset->geom == setid){
-      return bset;
-    }
-    ++bset;
-  }
-  return NULL;
-}
-
 // number of pixels that map to a single cell, height-wise
 static inline int
 encoding_y_scale(const struct blitset* bset) {
@@ -69,28 +30,6 @@ rgba_blitter_default(const tinfo* tcache, ncscale_e scale){
   return NCBLIT_3x2;
 }
 
-static inline const struct blitset*
-rgba_blitter_low(const tinfo* tcache, ncscale_e scale, bool maydegrade,
-                 ncblitter_e blitrec) {
-  if(blitrec == NCBLIT_DEFAULT){
-    blitrec = rgba_blitter_default(tcache, scale);
-  }
-  const struct blitset* bset = lookup_blitset(tcache, blitrec, maydegrade);
-  if(bset && !bset->blit){ // FIXME remove this once all blitters are enabled
-    bset = NULL;
-  }
-  return bset;
-}
-
-// RGBA visuals all use NCBLIT_2x1 by default (or NCBLIT_1x1 if not in
-// UTF-8 mode), but an alternative can be specified.
-static inline const struct blitset*
-rgba_blitter(const struct notcurses* nc, const struct ncvisual_options* opts) {
-  const bool maydegrade = !(opts && (opts->flags & NCVISUAL_OPTION_NODEGRADE));
-  const ncscale_e scale = opts ? opts->scaling : NCSCALE_NONE;
-  return rgba_blitter_low(&nc->tcache, scale, maydegrade, opts ? opts->blitter : NCBLIT_DEFAULT);
-}
-
 static inline ncblitter_e
 ncplot_defblitter(const notcurses* nc){
   if(notcurses_canutf8(nc)){

src/lib/internal.h

@@ -667,6 +667,30 @@ memdup(const void* src, size_t len){
 
 ALLOC void* bgra_to_rgba(const void* data, int rows, int rowstride, int cols);
 
+API const struct blitset* lookup_blitset(const tinfo* tcache, ncblitter_e setid, bool may_degrade);
+
+static inline const struct blitset*
+rgba_blitter_low(const tinfo* tcache, ncscale_e scale, bool maydegrade,
+                 ncblitter_e blitrec) {
+  if(blitrec == NCBLIT_DEFAULT){
+    blitrec = rgba_blitter_default(tcache, scale);
+  }
+  const struct blitset* bset = lookup_blitset(tcache, blitrec, maydegrade);
+  if(bset && !bset->blit){ // FIXME remove this once all blitters are enabled
+    bset = NULL;
+  }
+  return bset;
+}
+
+// RGBA visuals all use NCBLIT_2x1 by default (or NCBLIT_1x1 if not in
+// UTF-8 mode), but an alternative can be specified.
+static inline const struct blitset*
+rgba_blitter(const struct notcurses* nc, const struct ncvisual_options* opts) {
+  const bool maydegrade = !(opts && (opts->flags & NCVISUAL_OPTION_NODEGRADE));
+  const ncscale_e scale = opts ? opts->scaling : NCSCALE_NONE;
+  return rgba_blitter_low(&nc->tcache, scale, maydegrade, opts ? opts->blitter : NCBLIT_DEFAULT);
+}
+
 static inline int
 rgba_blit_dispatch(ncplane* nc, const struct blitset* bset, int placey,
                    int placex, int linesize, const void* data, int begy,