pixel documentation

USAGE.md

@@ -91,13 +91,6 @@ typedef enum {
 // doing something weird (setting a locale not based on LANG).
 #define NCOPTION_INHIBIT_SETLOCALE   0x0001
 
-// Checking for pixel support might require writing a control sequence, and
-// then reading a reply directly from the terminal. If the terminal doesn't
-// support this, the application will lock up. If you'll be using pixels, set
-// this flag to perform the check in notcurses_init(). You must otherwise call
-// notcurses_check_pixel() before NCBLIT_PIXEL will become available.
-#define NCOPTION_VERIFY_PIXEL        0x0002ull
-
 // We typically install a signal handler for SIGWINCH that generates a resize
 // event in the notcurses_getc() queue. Set to inhibit this handler.
 #define NCOPTION_NO_WINCH_SIGHANDLER 0x0004
@@ -308,10 +301,10 @@ bool notcurses_cansextants(const struct notcurses* nc);
 // Can we draw Braille? The Linux console cannot.
 bool notcurses_canbraille(const struct notcurses* nc);
 
-// If NCOPTION_VERIFY_PIXEL was not supplied to notcurses_init(), this
-// function must successfully return before NCBLIT_PIXEL is available. Returns
-// -1 on error, 0 if pixel mode is not supported, or 1 if it is supported.
-int notcurses_check_pixel(struct notcurses* nc);
+// This function must successfully return before NCBLIT_PIXEL is available.
+// Returns -1 on error, 0 for no support, or 1 if pixel output is supported.
+// Must not be called concurrently with either input or rasterization.
+int notcurses_check_pixel_support(struct notcurses* nc);
 ```
 
 ## Direct mode

doc/man/man3/notcurses_capabilities.3.md

@@ -66,16 +66,12 @@ UTF-8 encoding, and the locale was successfully loaded.
 that the terminal can properly render Unicode 13 sextants.
 
 **notcurses_canpixel** returns **true** if the terminal advertises
-support for pixel graphics (e.g. Sixel).
+support for pixel graphics (e.g. Sixel). This function will not return **true**
+until **notcurses_check_pixel_support** is called, and successfully returns.
 
 **notcurses_canbraille** returns **true** if Braille is expected to work on the
 terminal.
 
-# BUGS
-
-**notcurses_canpixel** currently only returns non-zero if 
-**NCOPTION_VERIFY_SIXEL** was passed to **notcurses_init(3)**.
-
 # NOTES
 
 Some terminals advertise support for TrueColor, but then downsample or
@@ -88,4 +84,5 @@ will return **true**, but the full spectrum will not be available.
 
 **notcurses(3)**,
 **notcurses_init(3)**,
+**notcurses_visual(3)**,
 utf8(7)