Merge pull request #149 from hzeller/feature-20250110-full-cell-jump

sixel: Implement DEC-accurate calculation of cursor position for jumping

Author: hzeller

man/timg.1

@@ -499,9 +499,13 @@ connection that can\[cq]t keep up with playing videos.
 Or if you have a very slow CPU.
 .TP
 \f[B]TIMG_SIXEL_NEWLINE_WORKAROUND\f[R]
-Set this environment variable to 1 if you are on a Sixel terminal and
-notice that videos `scroll' or grid\-view items are not perfectly
-aligned vertically.
+Set this environment variable if you are on a Sixel terminal and notice
+that videos `scroll' or grid\-view items are not perfectly aligned
+vertically.
+Sometimes this manifests only for pictures of a particular height.
+Valid values are 0, 1, 2, 3 which address various subtle differences in
+which sixel terminals behave.
+Default 0.
 .SH EXAMPLES
 Some example invocations including scrolling text or streaming an online
 video are put together at \c

man/timg.1.md

@@ -424,9 +424,12 @@ Exit code is
     slow CPU.
 
 **TIMG_SIXEL_NEWLINE_WORKAROUND**
-:   Set this environment variable to 1 if you are on a Sixel terminal and
+:   Set this environment variable if you are on a Sixel terminal and
     notice that videos 'scroll' or grid-view items are not perfectly aligned
-    vertically.
+    vertically. Sometimes this manifests only for pictures of a particular
+    height.
+    Valid values are 0, 1, 2, 3 which address various subtle differences in
+    which sixel terminals behave. Default 0.
 
 # EXAMPLES
 

src/sixel-canvas.cc

@@ -36,8 +36,11 @@ namespace timg {
 
 SixelCanvas::SixelCanvas(BufferedWriteSequencer *ws, ThreadPool *thread_pool,
                          bool required_cursor_placement_workaround,
-                         const DisplayOptions &opts)
-    : TerminalCanvas(ws), options_(opts), executor_(thread_pool) {
+                         bool full_cell_jump, const DisplayOptions &opts)
+    : TerminalCanvas(ws),
+      options_(opts),
+      full_cell_jump_(full_cell_jump),
+      executor_(thread_pool) {
     // Terminals might have different understanding where the curosr is placed
     // after an image is sent.
     // Apparently the original dec terminal placed it afterwards, but some
@@ -153,11 +156,18 @@ void SixelCanvas::Send(int x, int dy, const Framebuffer &fb_orig,
 int SixelCanvas::cell_height_for_pixels(int pixels) const {
     assert(pixels <= 0);  // Currently only use-case
     pixels = -pixels;
-    // Unlike the other exact pixel canvases where we have to round to the
-    // next even cell_y_px, here we first need to round to the next even 6
-    // first.
-    return -((round_to_sixel(pixels) + options_.cell_y_px - 1) /
-             options_.cell_y_px);
+    if (full_cell_jump_) {
+        // https://github.com/hzeller/timg/issues/145#issuecomment-2579962760
+        // As DEC intended.
+        return -((round_to_sixel(pixels) - 6) / options_.cell_y_px + 1);
+    }
+    else {
+        // Unlike the other exact pixel canvases where we have to round to the
+        // next even cell_y_px, here we first need to round to the next even 6
+        // first.
+        return -((round_to_sixel(pixels) + options_.cell_y_px - 1) /
+                 options_.cell_y_px);
+    }
 }
 
 }  // namespace timg

src/sixel-canvas.h

@@ -28,7 +28,7 @@ class ThreadPool;
 class SixelCanvas final : public TerminalCanvas {
 public:
     SixelCanvas(BufferedWriteSequencer *ws, ThreadPool *thread_pool,
-                bool required_cursor_placement_workaround,
+                bool required_cursor_placement_workaround, bool full_cell_jump,
                 const DisplayOptions &opts);
 
     int cell_height_for_pixels(int pixels) const final;
@@ -38,6 +38,7 @@ class SixelCanvas final : public TerminalCanvas {
 
 private:
     const DisplayOptions &options_;
+    const bool full_cell_jump_;
     ThreadPool *const executor_;
     const char *cursor_move_before_;
     const char *cursor_move_after_;

src/term-query.cc

@@ -224,11 +224,12 @@ const char *QueryBackgroundColor() {
 }
 
 TermGraphicsInfo QuerySupportedGraphicsProtocol() {
-    TermGraphicsInfo result;
+    TermGraphicsInfo result{};
     result.preferred_graphics = GraphicsProtocol::kNone;
-    result.known_broken_sixel_cursor_placement =
-        timg::GetBoolenEnv("TIMG_SIXEL_NEWLINE_WORKAROUND");
-    result.in_tmux = false;
+    const int sixel_env_bits = timg::GetIntEnv("TIMG_SIXEL_NEWLINE_WORKAROUND");
+    result.known_broken_sixel_cursor_placement = sixel_env_bits & 0b01;
+    result.sixel_full_cell_jump                = sixel_env_bits & 0b10;
+    result.in_tmux                             = false;
 
     // Environment variables can be changed, so guesses from environment
     // variables are just that: guesses.
@@ -299,6 +300,12 @@ TermGraphicsInfo QuerySupportedGraphicsProtocol() {
                       if (find_str(data, len, "tmux")) {
                           result.in_tmux = true;
                       }
+                      if (find_str(data, len, "WindowsTerminal")) {
+                          // TODO: check again once name is established
+                          // https://github.com/microsoft/terminal/issues/18382
+                          result.known_broken_sixel_cursor_placement = true;
+                          result.sixel_full_cell_jump                = true;
+                      }
                       // We finish once we found the response to DSR5
                       return find_str(data, len, TERM_CSI "0");
                   });

src/term-query.h

@@ -44,6 +44,7 @@ enum class GraphicsProtocol {
 struct TermGraphicsInfo {
     GraphicsProtocol preferred_graphics;
     bool known_broken_sixel_cursor_placement;  // see SixelCanvas impl. doc
+    bool sixel_full_cell_jump;
     bool in_tmux;
 };
 

src/timg.cc

@@ -128,6 +128,7 @@ struct PresentationOptions {
     // Rendering
     Pixelation pixelation         = Pixelation::kNotChosen;
     bool sixel_cursor_workaround  = false;
+    bool sixel_full_cell_jump     = false;
     bool tmux_workaround          = false;
     bool terminal_use_upper_block = false;
     bool use_256_color = false;  // For terminals that don't do 24 bit color
@@ -331,9 +332,9 @@ static int PresentImages(LoadedImageSources *loaded_sources,
 #ifdef WITH_TIMG_SIXEL
     case Pixelation::kSixelGraphics:
         compression_pool.reset(new ThreadPool(sequencer->max_queue_len() + 1));
-        canvas.reset(new timg::SixelCanvas(sequencer, compression_pool.get(),
-                                           present.sixel_cursor_workaround,
-                                           display_opts));
+        canvas.reset(new timg::SixelCanvas(
+            sequencer, compression_pool.get(), present.sixel_cursor_workaround,
+            present.sixel_full_cell_jump, display_opts));
         break;
 #endif
     case Pixelation::kHalfBlock:
@@ -770,8 +771,8 @@ int main(int argc, char *argv[]) {
     if (present.pixelation == Pixelation::kNotChosen) {
         present.pixelation = Pixelation::kQuarterBlock;  // Good default.
         if (term.font_width_px > 0 && term.font_height_px > 0) {
-            auto graphics_info      = timg::QuerySupportedGraphicsProtocol();
-            present.tmux_workaround = graphics_info.in_tmux;
+            const auto graphics_info = timg::QuerySupportedGraphicsProtocol();
+            present.tmux_workaround  = graphics_info.in_tmux;
             switch (graphics_info.preferred_graphics) {
             case timg::GraphicsProtocol::kIterm2:
                 present.pixelation = Pixelation::kiTerm2Graphics;
@@ -784,6 +785,8 @@ int main(int argc, char *argv[]) {
                 present.pixelation = Pixelation::kSixelGraphics;
                 present.sixel_cursor_workaround =
                     graphics_info.known_broken_sixel_cursor_placement;
+                present.sixel_full_cell_jump =
+                    graphics_info.sixel_full_cell_jump;
 #else
                 present.pixelation = Pixelation::kQuarterBlock;
 #endif
@@ -804,6 +807,7 @@ int main(int argc, char *argv[]) {
         auto graphics_info = timg::QuerySupportedGraphicsProtocol();
         present.sixel_cursor_workaround =
             graphics_info.known_broken_sixel_cursor_placement;
+        present.sixel_full_cell_jump = graphics_info.sixel_full_cell_jump;
     }
 #endif
 
@@ -1031,12 +1035,12 @@ int main(int argc, char *argv[]) {
                 PixelationToString(present.pixelation));
 #ifdef WITH_TIMG_SIXEL
         if (present.pixelation == Pixelation::kSixelGraphics) {
-            if (present.sixel_cursor_workaround) {
-                fprintf(stderr, " (with cursor placment workaround)");
-            }
-            else {
-                fprintf(stderr, " (with default cursor placement)");
-            }
+            fprintf(stderr, " (%s and %s)",
+                    present.sixel_cursor_workaround
+                        ? "with cursor placment workaround"
+                        : "with default cursor placement",
+                    present.sixel_full_cell_jump ? "full cursor cell jump"
+                                                 : "default cursor cell jump");
         }
 #endif
         if (present.pixelation == Pixelation::kKittyGraphics) {

src/utils.cc

@@ -39,6 +39,14 @@ float GetFloatEnv(const char *env_var, float default_value) {
     return (*err == '\0' ? result : default_value);
 }
 
+int GetIntEnv(const char *env_name, int default_value) {
+    const char *const value = getenv(env_name);
+    if (!value) return default_value;
+    char *err        = nullptr;
+    const int result = strtol(value, &err, 10);
+    return (*err == '\0' ? result : default_value);
+}
+
 std::string HumanReadableByteValue(int64_t byte_count) {
     float print_bytes = byte_count;
     const char *unit  = "Bytes";

src/utils.h

@@ -26,6 +26,9 @@ bool GetBoolenEnv(const char *env_name, bool default_value = false);
 // Get float value from named environment variable.
 float GetFloatEnv(const char *env_var, float default_value);
 
+// Get float value from named environment variable.
+int GetIntEnv(const char *env_name, int default_value = 0);
+
 // Given number of bytes, return a human-readable version of that
 // (e.g. "13.2 MiB").
 std::string HumanReadableByteValue(int64_t byte_count);