Function: ghostel--kitty-display-image

ghostel--kitty-display-image is a natively compiled function defined in ghostel-kitty.el.

Signature

(ghostel--kitty-display-image DATA ABS-ROW VP-COL GRID-COLS GRID-ROWS PIXEL-W PIXEL-H)

Documentation

Display a kitty graphics image placement in the buffer.

Called from the native module during redraw for each visible placement. DATA is a unibyte PPM string of the placement's source rect. ABS-ROW is the buffer row (0-indexed from point-min) of the image's top: libghostty's screen row, which the renderer keeps equal to the buffer line. May be negative when the top is above the first line. VP-COL is the column (may be negative — image partially off the left). GRID-COLS and GRID-ROWS are the cell dimensions. PIXEL-W and PIXEL-H are the rendered pixel dimensions.

The image is sized to fill its grid cells and then sliced per row, with each slice applied on its own buffer line. Slicing — rather than a single multi-line display property — is required for the image to actually occupy each cell row (otherwise Emacs draws the image once at the first character of the range and the remaining rows show the underlying text or stay blank). Mirrors the virtual-placeholder path's
:ascent \=center' and line-height clamping so slices tile flush
across rows.

Falls back to PIXEL-W/PIXEL-H when GRID-COLS/GRID-ROWS arrive as 0 — libghostty hasn't computed the cell layout yet on the first redraw after a placement (a subsequent layout change would fix it, but the user shouldn't have to trigger one).

Source Code

;; Defined in /nix/store/1252krff0gb2kisjcpp45m50cpdskfrl-emacs-packages-deps/share/emacs/site-lisp/ghostel-kitty.el
(defun ghostel--kitty-display-image (data abs-row vp-col grid-cols grid-rows pixel-w pixel-h)
  "Display a kitty graphics image placement in the buffer.
Called from the native module during redraw for each visible placement.
DATA is a unibyte PPM string of the placement's source rect.
ABS-ROW is the buffer row (0-indexed from `point-min') of the image's
top: libghostty's screen row, which the renderer keeps equal to the
buffer line.  May be negative when the top is above the first line.
VP-COL is the column (may be negative — image partially off the left).
GRID-COLS and GRID-ROWS are the cell dimensions.
PIXEL-W and PIXEL-H are the rendered pixel dimensions.

The image is sized to fill its grid cells and then sliced per row, with
each slice applied on its own buffer line.  Slicing — rather than a
single multi-line `display' property — is required for the image to
actually occupy each cell row (otherwise Emacs draws the image once at
the first character of the range and the remaining rows show the
underlying text or stay blank).  Mirrors the virtual-placeholder path's
`:ascent \\='center' and `line-height' clamping so slices tile flush
across rows.

Falls back to PIXEL-W/PIXEL-H when GRID-COLS/GRID-ROWS arrive as 0 —
libghostty hasn't computed the cell layout yet on the first redraw
after a placement (a subsequent layout change would fix it, but the
user shouldn't have to trigger one)."
  (when (display-graphic-p)
    (condition-case err
        (let* ((cw (default-font-width))
               (ch (default-font-height))
               (g-cols (if (> grid-cols 0) grid-cols
                         (max 1 (/ (+ pixel-w cw -1) cw))))
               (g-rows (if (> grid-rows 0) grid-rows
                         (max 1 (/ (+ pixel-h ch -1) ch))))
               (img (create-image data 'pbm t
                                  :width (* g-cols cw)
                                  :height (* g-rows ch)
                                  :scale 1
                                  :ascent 'center))
               (skip (max 0 abs-row))
               (start-row (max 0 (- abs-row)))
               ;; Clamp negative vp-col (image partially scrolled off
               ;; the left edge): start the buffer range at column 0
               ;; and skip the off-screen pixel columns inside the
               ;; slice.
               (vp-col-clamped (max 0 vp-col))
               (start-col (max 0 (- vp-col)))
               (slice-x (* start-col cw))
               (visible-cols (max 0 (- g-cols start-col)))
               (slice-w (* visible-cols cw)))
          (when (> visible-cols 0)
            (save-excursion
              (goto-char (point-min))
              (when (zerop (forward-line skip))
                ;; Skip rows already in materialized scrollback — they
                ;; got their overlays in an earlier emit and
                ;; `kitty-clear' preserves scrollback overlays.
                ;; Re-applying here would stack a second overlay on
                ;; every scrolled-in row.
                (let ((row start-row)
                      (more t)
                      (vp-start (or (ghostel--viewport-start) (point-min))))
                  (while (and more (< row g-rows))
                    (when (>= (point) vp-start)
                      (ghostel--kitty-apply-row-slice
                       row cw ch img
                       vp-col-clamped visible-cols slice-x slice-w))
                    (setq row (1+ row))
                    (unless (zerop (forward-line 1))
                      (setq more nil))))))))
      (error
       (setq ghostel--kitty-last-error err)
       (message "ghostel: kitty image error: %S" err)))))