ncblit: accept an ncvisual_options #680

NEWS.md

@@ -1,11 +1,11 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
-* 1.5.0 (not yet released)
+* 1.4.5 (not yet released)
-  * `ncblit_rgba()` and `ncblit_bgrx()` have been renamed `ncplane_blit_rgba()`
+  * `ncblit_rgba()` and `ncblit_bgrx()` have replaced most of their arguments
-    and `ncplane_blit_bgrx()`, to match every other existing ncplane function.
+    with a `const struct ncvisual_options*`. `NCBLIT_DEFAULT` will use
-    In addition, they both now accept an `ncblitter_e` to select the blitting
+    `NCBLITTER_2x1` (with fallback) in this context. The `->n` field must
-    method. `NCBLIT_DEFAULT` will use `NCBLITTER_2x1`.
+    be non-`NULL`--new planes will not be created.
   * Added `ncplane_notcurses_const()`.
 
 * 1.4.4.1 (2020-06-01)

USAGE.md

@@ -1249,21 +1249,19 @@ void ncfadectx_free(struct ncfadectx* nctx);
 Raw streams of RGBA or BGRx data can be blitted directly to an ncplane:
 
 ```c
-// Blit a flat array 'data' of BGRx 32-bit values to the ncplane 'nc', offset
+// Blit a flat array 'data' of RGBA 32-bit values to the ncplane 'vopts->n',
-// from the upper left by 'placey' and 'placex'. Each row ought occupy
+// which mustn't be NULL. the blit begins at 'vopts->y' and 'vopts->x' relative
-// 'linesize' bytes (this might be greater than lenx * 4 due to padding). A
+// to the specified plane. Each source row ought occupy 'linesize' bytes (this
-// subregion of the input can be specified with 'begy'x'begx' and 'leny'x'lenx'.
+// might be greater than 'vopts->lenx' * 4 due to padding or partial blits). A
-int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int linesize,
+// subregion of the input can be specified with the 'begy'x'begx' and
-                      ncblitter_e blitter, const unsigned char* data,
+// 'leny'x'lenx' fields from 'vopts'. Returns the number of pixels blitted, or
-                      int begy, int begx, int leny, int lenx);
+// -1 on error.
+int ncblit_rgba(const void* data, int linesize,
+                const struct ncvisual_options* vopts);
 
-// Blit a flat array 'data' of RGBA 32-bit values to the ncplane 'nc', offset
+// Same as ncblit_rgba(), but for BGRx.
-// from the upper left by 'placey' and 'placex'. Each row ought occupy
+int ncblit_bgrx(const void* data, int linesize,
-// 'linesize' bytes (this might be greater than lenx * 4 due to padding). A
+                const struct ncvisual_options* vopts);
-// subregion of the input can be specified with 'begy'x'begx' and 'leny'x'lenx'.
-int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int linesize,
-                      ncblitter_e blitter, const unsigned char* data,
-                      int begy, int begx, int leny, int lenx);
 ```
 
 

include/ncpp/Plane.hh

@@ -1015,15 +1015,15 @@ namespace ncpp
 
 		static Plane* map_plane (ncplane *ncp, Plane *associated_plane = nullptr) noexcept;
 
-		bool blit_bgrx (int placey, int placex, int linesize, const void* data, int begy, int begx, int leny, int lenx) const NOEXCEPT_MAYBE
+		bool blit_bgrx (const void* data, int linesize, const struct ncvisual_options *vopts) const NOEXCEPT_MAYBE
 		{
-			bool ret = ncplane_blit_bgrx (plane, placey, placex, linesize, NCBLIT_DEFAULT, data, begy, begx, leny, lenx) < 0;
+			bool ret = ncblit_bgrx (data, linesize, vopts) < 0;
 			return error_guard_cond<bool, bool> (ret, ret);
 		}
 
-		bool blit_rgba (int placey, int placex, int linesize, const void* data, int begy, int begx, int leny, int lenx) const NOEXCEPT_MAYBE
+		bool blit_rgba (const void* data, int linesize, const struct ncvisual_options *vopts) const NOEXCEPT_MAYBE
 		{
-			bool ret = ncplane_blit_rgba (plane, placey, placex, linesize, NCBLIT_DEFAULT, data, begy, begx, leny, lenx) < 0;
+			bool ret = ncblit_rgba (data, linesize, vopts) < 0;
 			return error_guard_cond<bool, bool> (ret, ret);
 		}
 

include/notcurses/notcurses.h

@@ -2233,21 +2233,19 @@ API int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv,
                         nc_err_e* ncerr, float timescale, streamcb streamer,
                         const struct ncvisual_options* vopts, void* curry);
 
-// Blit a flat array 'data' of BGRx 32-bit values to the ncplane 'nc', offset
+// Blit a flat array 'data' of RGBA 32-bit values to the ncplane 'vopts->n',
-// from the upper left by 'placey' and 'placex'. Each row ought occupy
+// which mustn't be NULL. the blit begins at 'vopts->y' and 'vopts->x' relative
-// 'linesize' bytes (this might be greater than lenx * 4 due to padding). A
+// to the specified plane. Each source row ought occupy 'linesize' bytes (this
-// subregion of the input can be specified with 'begy'x'begx' and 'leny'x'lenx'.
+// might be greater than 'vopts->lenx' * 4 due to padding or partial blits). A
-API int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex,
+// subregion of the input can be specified with the 'begy'x'begx' and
-                          int linesize, ncblitter_e blitter, const void* data,
+// 'leny'x'lenx' fields from 'vopts'. Returns the number of pixels blitted, or
-                          int begy, int begx, int leny, int lenx);
+// -1 on error.
+API int ncblit_rgba(const void* data, int linesize,
+                    const struct ncvisual_options* vopts);
 
-// Blit a flat array 'data' of RGBA 32-bit values to the ncplane 'nc', offset
+// Same as ncblit_rgba(), but for BGRx.
-// from the upper left by 'placey' and 'placex'. Each row ought occupy
+API int ncblit_bgrx(const void* data, int linesize,
-// 'linesize' bytes (this might be greater than lenx * 4 due to padding). A
+                    const struct ncvisual_options* vopts);
-// subregion of the input can be specified with 'begy'x'begx' and 'leny'x'lenx'.
-API int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex,
-                          int linesize, ncblitter_e blitter, const void* data,
-                          int begy, int begx, int leny, int lenx);
 
 // An ncreel is a notcurses region devoted to displaying zero or more
 // line-oriented, contained panels between which the user may navigate. If at

python/src/notcurses/build_notcurses.py

@@ -323,8 +323,8 @@ struct ncvisual_options {
   ncblitter_e blitter;
   uint64_t flags;
 };
-int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int linesize, ncblitter_e blitter, const unsigned char* data, int begy, int begx, int leny, int lenx);
+struct ncplane* ncblit_bgrx(const void* data, int linesize, const struct ncvisual_options *vopts);
-int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int linesize, ncblitter_e blitter, const unsigned char* data, int begy, int begx, int leny, int lenx);
+struct ncplane* ncblit_rgba(const void* data, int linesize, const struct ncvisual_options *vopts);
 struct ncselector_item {
   char* option;
   char* desc;

src/demo/normal.c

@@ -173,7 +173,12 @@ int normal_demo(struct notcurses* nc){
         goto err;
       }
     }
-    if(ncplane_blit_rgba(nstd, 0, 0, dx * sizeof(*rgba), NCBLIT_DEFAULT, rgba, 0, 0, dy, dx) < 0){
+    struct ncvisual_options vopts = {
+      .n = nstd,
+      .leny = dy,
+      .lenx = dx,
+    };
+    if(ncblit_rgba(rgba, dx * sizeof(*rgba), &vopts) < 0){
       goto err;
     }
     if( (r = demo_render(nc)) ){

src/lib/blit.c

@@ -443,30 +443,56 @@ const struct blitset notcurses_blitters[] = {
      .blit = NULL,           .fill = false,  },
 };
 
-// Blit a flat array 'data' of BGRx 32-bit values to the ncplane 'nc', offset
+int ncblit_bgrx(const void* data, int linesize, const struct ncvisual_options* vopts){
-// from the upper left by 'placey' and 'placex'. Each row ought occupy
+  if(vopts->flags > NCVISUAL_OPTION_BLEND){
-// 'linesize' bytes (this might be greater than lenx * 4 due to padding). A
+    return -1;
-// subregion of the input can be specified with 'begy'x'begx' and 'leny'x'lenx'.
+  }
-int ncplane_blit_bgrx(ncplane* nc, int placey, int placex, int linesize,
+  struct ncplane* nc = vopts->n;
-                      ncblitter_e blitter, const void* data,
+  if(nc == NULL){
-                      int begy, int begx, int leny, int lenx){
+    return -1;
-  const struct blitset* bset = lookup_blitset(ncplane_notcurses(nc), blitter, true);
+  }
+  int lenx = vopts->lenx;
+  int leny = vopts->leny;
+  int begy = vopts->begy;
+  int begx = vopts->begx;
+//fprintf(stderr, "render %dx%d+%dx%d %p\n", begy, begx, leny, lenx, ncv->data);
+  if(begy < 0 || begx < 0 || lenx < -1 || leny < -1){
+    return -1;
+  }
+  const bool degrade = (vopts->flags & NCVISUAL_OPTION_MAYDEGRADE);
+  const struct blitset* bset = lookup_blitset(nc->nc, vopts->blitter, degrade);
   if(bset == NULL){
     return -1;
   }
-  return bset->blit(nc, placey, placex, linesize, data, begy, begx,
+  const bool blend = (vopts->flags & NCVISUAL_OPTION_BLEND);
-                    leny, lenx, true, false);
+  return bset->blit(nc, vopts->y, vopts->x, linesize, data, begy, begx,
+                    leny, lenx, true, blend);
 }
 
-int ncplane_blit_rgba(ncplane* nc, int placey, int placex, int linesize,
+int ncblit_rgba(const void* data, int linesize, const struct ncvisual_options* vopts){
-                      ncblitter_e blitter, const void* data,
+  if(vopts->flags > NCVISUAL_OPTION_BLEND){
-                      int begy, int begx, int leny, int lenx){
+    return -1;
-  const struct blitset* bset = lookup_blitset(ncplane_notcurses(nc), blitter, true);
+  }
+  struct ncplane* nc = vopts->n;
+  if(nc == NULL){
+    return -1;
+  }
+  int lenx = vopts->lenx;
+  int leny = vopts->leny;
+  int begy = vopts->begy;
+  int begx = vopts->begx;
+//fprintf(stderr, "render %dx%d+%dx%d %p\n", begy, begx, leny, lenx, ncv->data);
+  if(begy < 0 || begx < 0 || lenx < -1 || leny < -1){
+    return -1;
+  }
+  const bool degrade = (vopts->flags & NCVISUAL_OPTION_MAYDEGRADE);
+  const struct blitset* bset = lookup_blitset(nc->nc, vopts->blitter, degrade);
   if(bset == NULL){
     return -1;
   }
-  return bset->blit(nc, placey, placex, linesize, data, begy, begx,
+  const bool blend = (vopts->flags & NCVISUAL_OPTION_BLEND);
-                    leny, lenx, false, false);
+  return bset->blit(nc, vopts->y, vopts->x, linesize, data, begy, begx,
+                    leny, lenx, false, blend);
 }
 
 int rgba_blit_dispatch(ncplane* nc, const struct blitset* bset, int placey,

src/poc/rotator.c

@@ -31,8 +31,12 @@ rotate_grad(struct notcurses* nc){
   notcurses_render(nc);
   clock_nanosleep(CLOCK_MONOTONIC, 0, &ts, NULL);;
 
-  if(ncplane_blit_rgba(n, 0, 0, dimx * 4, NCBLIT_DEFAULT,
+  struct ncvisual_options vopts = {
-                       rgba, 0, 0, dimy * 2, dimx) < 0){
+    .n = n,
+    .leny = dimy * 2,
+    .lenx = dimx,
+  };
+  if(ncblit_rgba(rgba, dimx * 4, &vopts) == NULL){
     free(rgba);
     return -1;
   }
@@ -49,9 +53,8 @@ rotate_grad(struct notcurses* nc){
   if(v == NULL){
     return -1;
   }
-  struct ncvisual_options vopts = {
+  vopts.leny = 0;
-    .n = n,
+  vopts.lenx = 0;
-  };
   if(n != ncvisual_render(nc, v, &vopts)){
     ncvisual_destroy(v);
     return -1;
@@ -161,8 +164,14 @@ rotate(struct notcurses* nc){
   notcurses_render(nc);
   clock_nanosleep(CLOCK_MONOTONIC, 0, &ts, NULL);;
 
-  if(ncplane_blit_rgba(n, dimy / 2, XSIZE, XSIZE * 4, NCBLIT_DEFAULT,
+  struct ncvisual_options vopts = {
-                       rgba, 0, 0, 4, XSIZE) < 0){
+    .lenx = XSIZE,
+    .leny = 4,
+    .y = dimy / 2,
+    .x = XSIZE,
+    .n = n,
+  };
+  if(ncblit_rgba(rgba, XSIZE * 4, &vopts) == NULL){
     free(rgba);
     return -1;
   }
@@ -179,11 +188,8 @@ rotate(struct notcurses* nc){
   if(v == NULL){
     return -1;
   }
-  struct ncvisual_options vopts = {
+  vopts.x = (dimx - XSIZE) / 2;
-    .x = (dimx - XSIZE) / 2,
+  vopts.y = dimy / 2;
-    .y = dimy / 2,
-    .n = n,
-  };
   ncvisual_render(nc, v, &vopts);
   notcurses_render(nc);
   clock_nanosleep(CLOCK_MONOTONIC, 0, &ts, NULL);;