ncplane_qrcode: drop blitter argument, update docs

NEWS.md

@@ -1,6 +1,11 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 2.2.2 (not yet released):
+  * `ncplane_qrcode()` no longer accepts a blitter argument, since `NCBLIT_2x1`
+    is the only one that actually works with qr code scanners. I'm unaware of
+    any external `ncplane_qrcode()` users, so hopefully this isn't a problem.
+
 * 2.2.1 (2021-02-09):
   * Brown-bag release: fix UTF8 discovery in direct mode. Sorry!
 

USAGE.md

@@ -2946,7 +2946,7 @@ int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv, float timescale,
 
 ### QR codes
 
-If build with libqrcodegen support, `ncplane_qrcode()` can be used to draw
+If built with libqrcodegen support, `ncplane_qrcode()` can be used to draw
 a QR code for arbitrary data.
 
 ```c
@@ -2955,11 +2955,9 @@ a QR code for arbitrary data.
 // returned. Otherwise, the QR code "version" (size) is returned. The QR code
 // is (version * 4 + 17) columns wide, and ⌈version * 4 + 17⌉ rows tall (the
 // properly-scaled values are written back to '*ymax' and '*xmax').
-int ncplane_qrcode(struct ncplane* n, ncblitter_e blitter, int* ymax,
-                   int* xmax, const void* data, size_t len);
+int ncplane_qrcode(struct ncplane* n, int* ymax, int* xmax, const void* data, size_t len);
 ```
 
-
 ### Multimedia
 
 When compiled against a suitable engine (FFmpeg and OpenImageIO are both

doc/man/man3/notcurses_visual.3.md

@@ -96,6 +96,8 @@ typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
 
 **ncblitter_e ncvisual_media_defblitter(const struct notcurses ***nc***, ncscale_e ***scaling***);**
 
+**int ncplane_qrcode(struct ncplane* ***n***, int* ***ymax***, int* ***xmax***, const void* ***data***, size_t ***len***)**
+
 # DESCRIPTION
 
 An **ncvisual** is a virtual pixel framebuffer. They can be created from
@@ -144,6 +146,10 @@ geometry of same. **flags** is a bitfield over:
 * **NCVISUAL_OPTION_NODEGRADE** If the specified blitter is not available, fail rather than degrading.
 * **NCVISUAL_OPTION_BLEND**: Render with **CELL_ALPHA_BLEND**.
 
+**ncplane_qrcode** draws an ISO/IEC 18004:2015 QR Code for the **len** bytes of
+**data** using **NCBLIT_2x1** (this is the only blitter that will work with QR
+Code scanners, due to its 1:1 aspect ratio).
+
 # BLITTERS
 
 The different **ncblitter_e** values select from among available glyph sets:

include/ncpp/Plane.hh

@@ -1213,9 +1213,9 @@ namespace ncpp
 			return error_guard_cond<bool, bool> (ret, ret);
 		}
 
-		int qrcode (ncblitter_e blitter, int* ymax, int* xmax, const void *data, size_t len) const NOEXCEPT_MAYBE
+		int qrcode (int* ymax, int* xmax, const void *data, size_t len) const NOEXCEPT_MAYBE
 		{
-			int ret = ncplane_qrcode (plane, blitter, ymax, xmax, data, len);
+			int ret = ncplane_qrcode (plane, ymax, xmax, data, len);
 			return error_guard_cond<int> (ret, ret < 0);
 		}
 

include/notcurses/notcurses.h

@@ -3295,8 +3295,9 @@ API int ncsubproc_destroy(struct ncsubproc* n);
 // returned. Otherwise, the QR code "version" (size) is returned. The QR code
 // is (version * 4 + 17) columns wide, and ⌈version * 4 + 17⌉ rows tall (the
 // properly-scaled values are written back to '*ymax' and '*xmax').
-API int ncplane_qrcode(struct ncplane* n, ncblitter_e blitter, int* ymax,
-                       int* xmax, const void* data, size_t len);
+API int ncplane_qrcode(struct ncplane* n, int* ymax, int* xmax,
+                       const void* data, size_t len)
+  __attribute__ ((nonnull (1, 4)));
 
 // Enable horizontal scrolling. Virtual lines can then grow arbitrarily long.
 #define NCREADER_OPTION_HORSCROLL 0x0001ull

src/demo/qrcode.c

@@ -24,7 +24,7 @@ int qrcode_demo(struct notcurses* nc){
     ncplane_home(n);
     int y = dimy, x = dimx;
     ncplane_home(n);
-    int qlen = ncplane_qrcode(n, NCBLIT_DEFAULT, &y, &x, data, len);
+    int qlen = ncplane_qrcode(n, &y, &x, data, len);
     if(qlen > 0){ // FIXME can fail due to being too large for display; distinguish this case
       ncplane_move_yx(n, (dimy - y) / 2, (dimx - x) / 2);
       ncplane_home(n);

src/lib/fill.c

@@ -571,8 +571,8 @@ qrcode_cols(int version){
   return QR_BASE_SIZE + (version * PER_QR_VERSION);
 }
 
-int ncplane_qrcode(ncplane* n, ncblitter_e blitter, int* ymax, int* xmax,
-                   const void* data, size_t len){
+int ncplane_qrcode(ncplane* n, int* ymax, int* xmax, const void* data, size_t len){
+  const ncblitter_e blitter = NCBLIT_2x1;
   const int MAX_QR_VERSION = 40; // QR library only supports up to 40
   if(*ymax <= 0 || *xmax <= 0){
     return -1;

src/poc/qrcode.c

@@ -6,7 +6,7 @@ static int
 render_qrcode(struct ncplane* n, int dimy, int dimx, const char* text){
   int y = dimy, x = dimx;
   ncplane_home(n);
-  int ver = ncplane_qrcode(n, NCBLIT_2x2, &y, &x, text, strlen(text));
+  int ver = ncplane_qrcode(n, &y, &x, text, strlen(text));
   if(ver < 0){
     return -1;
   }

src/tests/fills.cpp

@@ -573,7 +573,7 @@ TEST_CASE("Fills") {
     const char* qr = "a very simple qr code";
     int dimy, dimx;
     ncplane_dim_yx(n_, &dimy, &dimx);
-    CHECK(0 < ncplane_qrcode(n_, NCBLIT_DEFAULT, &dimy, &dimx, qr, strlen(qr)));
+    CHECK(0 < ncplane_qrcode(n_, &dimy, &dimx, qr, strlen(qr)));
     CHECK(0 == notcurses_render(nc_));
   }
 #endif