comment and move ncpixel API

doc/man/index.html

@@ -76,9 +76,10 @@
 <br/>
 <small>Notcurses.com is a participant in the Amazon Services LLC Associates
   Program, an affiliate advertising program designed to provide a means for
-  sites to earn advertising fees by advertising and linking to Amazon.</small>
-<br/>
-© 2019-2020 <a href="mailto:nickblack@linux.com">nickblack@linux.com</a><br/>
+  sites to earn advertising fees by advertising and linking to Amazon.
+  <br/>
+  © 2019-2020 <a href="mailto:nickblack@linux.com">nickblack@linux.com</a>
+</small>
 </center>
 </body>
 </html>

include/notcurses/notcurses.h

@@ -184,82 +184,6 @@ channel_set_rgb(unsigned* channel, int r, int g, int b){
   return 0;
 }
 
-static inline uint32_t
-ncpixel(int r, int g, int b){
-  if(r < 0) r = 0;
-  if(r > 255) r = 255;
-  if(g < 0) g = 0;
-  if(g > 255) g = 255;
-  if(b < 0) b = 0;
-  if(b > 255) b = 255;
-  return 0xff000000ul | r | (b << 8u) | (g << 16u);
-}
-
-static inline unsigned
-ncpixel_a(uint32_t pixel){
-  return (pixel & 0xff0000fful) >> 24u;
-}
-
-static inline unsigned
-ncpixel_r(uint32_t pixel){
-  return (pixel & 0x000000fful);
-}
-
-static inline int
-ncpixel_g(uint32_t pixel){
-  return (pixel & 0x00ff0000ul) >> 16u;
-}
-
-static inline int
-ncpixel_b(uint32_t pixel){
-  return (pixel & 0x0000ff00ul) >> 8u;
-}
-
-static inline int
-ncpixel_set_a(uint32_t* pixel, int a){
-  if(a > 255 || a < 0){
-    return -1;
-  }
-  *pixel = (*pixel & 0x00fffffful) | (a << 24u);
-  return 0;
-}
-
-static inline int
-ncpixel_set_r(uint32_t* pixel, int r){
-  if(r > 255 || r < 0){
-    return -1;
-  }
-  *pixel = (*pixel & 0xffffff00ul) | r;
-  return 0;
-}
-
-static inline int
-ncpixel_set_g(uint32_t* pixel, int g){
-  if(g > 255 || g < 0){
-    return -1;
-  }
-  *pixel = (*pixel & 0xff00fffful) | (g << 16u);
-  return 0;
-}
-
-static inline int
-ncpixel_set_b(uint32_t* pixel, int b){
-  if(b > 255 || b < 0){
-    return -1;
-  }
-  *pixel = (*pixel & 0xffff00fful) | (b << 8u);
-  return 0;
-}
-
-// set the RGB values of an RGB pixel
-static inline int
-ncpixel_set_rgb(uint32_t* pixel, int r, int g, int b){
-  if(ncpixel_set_r(pixel, r) || ncpixel_set_g(pixel, g) || ncpixel_set_b(pixel, b)){
-    return -1;
-  }
-  return 0;
-}
-
 // Set the three 8-bit components of a 32-bit channel, and mark it as not using
 // the default color. Retain the other bits unchanged. r, g, and b will be
 // clipped to the range [0..255].
@@ -2413,6 +2337,85 @@ API int ncblit_rgba(const void* data, int linesize,
 API int ncblit_bgrx(const void* data, int linesize,
                     const struct ncvisual_options* vopts);
 
+// The ncpixel API facilitates direct management of the pixels within an
+// ncvisual (ncvisuals keep a backing store of 32-bit RGBA pixels, and render
+// them down to terminal graphics in ncvisual_render()).
+static inline uint32_t
+ncpixel(int r, int g, int b){
+  if(r < 0) r = 0;
+  if(r > 255) r = 255;
+  if(g < 0) g = 0;
+  if(g > 255) g = 255;
+  if(b < 0) b = 0;
+  if(b > 255) b = 255;
+  return 0xff000000ul | r | (b << 8u) | (g << 16u);
+}
+
+static inline unsigned
+ncpixel_a(uint32_t pixel){
+  return (pixel & 0xff0000fful) >> 24u;
+}
+
+static inline unsigned
+ncpixel_r(uint32_t pixel){
+  return (pixel & 0x000000fful);
+}
+
+static inline int
+ncpixel_g(uint32_t pixel){
+  return (pixel & 0x00ff0000ul) >> 16u;
+}
+
+static inline int
+ncpixel_b(uint32_t pixel){
+  return (pixel & 0x0000ff00ul) >> 8u;
+}
+
+static inline int
+ncpixel_set_a(uint32_t* pixel, int a){
+  if(a > 255 || a < 0){
+    return -1;
+  }
+  *pixel = (*pixel & 0x00fffffful) | (a << 24u);
+  return 0;
+}
+
+static inline int
+ncpixel_set_r(uint32_t* pixel, int r){
+  if(r > 255 || r < 0){
+    return -1;
+  }
+  *pixel = (*pixel & 0xffffff00ul) | r;
+  return 0;
+}
+
+static inline int
+ncpixel_set_g(uint32_t* pixel, int g){
+  if(g > 255 || g < 0){
+    return -1;
+  }
+  *pixel = (*pixel & 0xff00fffful) | (g << 16u);
+  return 0;
+}
+
+static inline int
+ncpixel_set_b(uint32_t* pixel, int b){
+  if(b > 255 || b < 0){
+    return -1;
+  }
+  *pixel = (*pixel & 0xffff00fful) | (b << 8u);
+  return 0;
+}
+
+// set the RGB values of an RGB pixel
+static inline int
+ncpixel_set_rgb(uint32_t* pixel, int r, int g, int b){
+  if(ncpixel_set_r(pixel, r) || ncpixel_set_g(pixel, g) || ncpixel_set_b(pixel, b)){
+    return -1;
+  }
+  return 0;
+}
+
 // An ncreel is a notcurses region devoted to displaying zero or more
 // line-oriented, contained panels between which the user may navigate. If at
 // least one panel exists, there is an active panel. As much of the active