add notcurses_default_background() #2432

NEWS.md

@@ -8,6 +8,7 @@ rearrangements of Notcurses.
     and `ncplane_autogrow_p()` functions. When autogrow is enabled, the plane
     is automatically enlarged to accommodate output at its right (no scrolling)
     or bottom (scrolling enabled) boundaries.
+  * Added the new function `notcurses_default_background()`.
 
 * 3.0.0 (2021-12-01) **"In the A"**
   * Made the ABI/API changes that have been planned/collected during 2.x

USAGE.md

@@ -293,6 +293,13 @@ notcurses_term_dim_yx(const struct notcurses* n, unsigned* restrict rows,
 // current screen geometry is returned in 'y' and 'x', if they are not NULL.
 int notcurses_refresh(struct notcurses* n, unsigned* restrict y, unsigned* restrict x);
 
+// Get the default background color, if it is known. Returns -1 on error
+// (unknown background). On success, returns 0, writing the RGB value to
+// 'bg' (if non-NULL) and setting 'bgtrans' high iff the background color
+// is treated as transparent.
+int notcurses_default_background(const struct notcurses* nc,
+                                 uint32_t* bg, unsigned* bgtrans);
+
 // Enable or disable the terminal's cursor, if supported, placing it at
 // 'y', 'x'. Immediate effect (no need for a call to notcurses_render()).
 // It is an error if 'y', 'x' lies outside the standard plane. Can be

doc/man/man3/notcurses_init.3.md

@@ -53,6 +53,8 @@ typedef struct notcurses_options {
 
 **int notcurses_lex_margins(const char* ***op***, notcurses_options* ***opts***);**
 
+**int notcurses_default_background(const struct notcurses* ***nc***, uint32_t* ***bg***, unsigned* ***bgtrans***);**
+
 # DESCRIPTION
 
 **notcurses_init** prepares the terminal for cursor-addressable (multiline)
@@ -166,6 +168,9 @@ zero. The following flags are defined:
     eventually prevent Notcurses from processing messages from the terminal. It
     will furthermore avoid wasting time processing useless input.
 
+**notcurses_default_background** returns the default background color, and
+whether the terminal treats it as transparent, if this could be detected.
+
 ## Fatal signals
 
 It is important to reset the terminal before exiting, whether terminating due
@@ -245,6 +250,9 @@ rendered mode to be used as a normal scrolling shell application.
 
 **notcurses_cursor_disable** returns -1 if the cursor is already invisible.
 
+**notcurses_default_background** returns -1 if the default background color
+could not be detected.
+
 # ENVIRONMENT VARIABLES
 
 The **NOTCURSES_LOGLEVEL** environment variable, if defined, ought be an

include/notcurses/notcurses.h

@@ -3629,6 +3629,14 @@ ncbprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
   return ncnmetric(val, NCBPREFIXSTRLEN + 1, decimal, buf, omitdec, 1024, 'i');
 }
 
+// Get the default background color, if it is known. Returns -1 on error
+// (unknown background). On success, returns 0, writing the RGB value to
+// 'bg' (if non-NULL) and setting 'bgtrans' high iff the background color
+// is treated as transparent.
+API int notcurses_default_background(const struct notcurses* nc,
+                                     uint32_t* bg, unsigned* bgtrans)
+  __attribute__ ((nonnull (1)));
+
 // Enable or disable the terminal's cursor, if supported, placing it at
 // 'y', 'x'. Immediate effect (no need for a call to notcurses_render()).
 // It is an error if 'y', 'x' lies outside the standard plane. Can be

src/info/main.c

@@ -369,16 +369,19 @@ display_logo(struct ncplane* n, const char* path){
 
 static void
 tinfo_debug_bitmaps(struct ncplane* n, const tinfo* ti, const char* indent){
-  if(!(ti->bg_collides_default & 0x80000000)){
-    if(!(ti->bg_collides_default & 0x01000000)){
-      ncplane_printf(n, "%sdefault background 0x%06lx", indent,
-                    ti->bg_collides_default & 0xfffffful);
+  unsigned bgtrans = 0;
+  uint32_t bg = 0;
+  int r = notcurses_default_background(ncplane_notcurses(n), &bg, &bgtrans);
+  if(r){
+    ncplane_printf(n, "couldn't detect default background");
   }else{
+    if(bgtrans){
       ncplane_printf(n, "%sdefault background 0x%06lx considered transparent", indent,
                     ti->bg_collides_default & 0xfffffful);
-    }
     }else{
-    ncplane_printf(n, "couldn't detect default background");
+      ncplane_printf(n, "%sdefault background 0x%06lx", indent,
+                    ti->bg_collides_default & 0xfffffful);
+    }
   }
   finish_line(n);
   ncpixelimpl_e blit = notcurses_check_pixel_support(ncplane_notcurses(n));

src/lib/render.c

@@ -1726,6 +1726,18 @@ int ncdirect_set_fg_rgb(ncdirect* nc, unsigned rgb){
   return 0;
 }
 
+int notcurses_default_background(const struct notcurses* nc,
+                                 uint32_t* bg, unsigned* bgtrans){
+  const tinfo* ti = &nc->tcache;
+  if(ti->bg_collides_default & 0x80000000){
+    logerror("default background could not be determined\n");
+    return -1;
+  }
+  *bgtrans = !!(ti->bg_collides_default & 0x01000000);
+  *bg = ti->bg_collides_default & NC_BG_RGB_MASK;
+  return 0;
+}
+
 int notcurses_cursor_yx(const notcurses* nc, int* y, int* x){
   *y = nc->rstate.y;
   *x = nc->rstate.x;