TermBuf::ImageStore
Stability: stable — changes only in a major release.
The images a terminal is currently showing, and the sequences that put them there.
Images are not cells. The buffer knows nothing about them: they are drawn over the screen after each frame's cells go out, and an application that writes text where one sits gets both. That is the whole of the model: placement and management, not compositing.
Everything here needs Capability::KittyGraphics. Without it nothing is
sent and #place still returns a placement, so an application does not have
to branch on whether the terminal draws pictures.
Constants
The largest base64 payload one escape sequence may carry, from the protocol. Anything longer is split across continuation chunks.
Suppresses the terminal's acknowledgements but not its complaints.
q=2 would silence both, and did: a path a terminal refused to read cost
an afternoon because the EINVAL explaining exactly why was thrown away.
An error is worth hearing, and Terminal#images registers a response
pattern for these so one arrives as an Events::Response rather than as
a burst of keystrokes nobody pressed.
What a temporary file has to be called before a terminal will read it.
The protocol says the file must be a temporary one, and terminals check
that rather than take the caller's word. Measured against ghostty 1.3.2,
which answers EINVAL: temporary file not named correctly for a path
with this string nowhere in it, and EINVAL: temporary file not in temp dir for one outside the directory TMPDIR names — /tmp included,
which is not the temporary directory on a Mac.
Constructors
Class methods
A path in the system temporary directory named so that a terminal will
read it. See TEMP_MARKER. Used by Prober#probe_temp_file too, so that
what is asked about and what is later sent are named the same way.
Instance methods
Registers image and returns the id the protocol refers to it by.
Registering is not sending. The pixels go out the first time the image is placed, and once only however many placements follow.
What the terminal can do, which decides whether anything is sent at all and which transport carries it.
Draws image over the cells of bounds, sending the pixels if this is the first time it has been needed.
z decides what it sits over. See Placement#z.
Draws image over the cells of bounds, sending the pixels if this is the first time it has been needed.
z decides what it sits over. See Placement#z.
Sends every placement again, which is what a forced repaint needs: the screen it is recovering from may have been cleared by something else.
Drops the placements that no longer fit on a screen this size. What is left is redrawn by the next forced repaint.
Everything queued since the last time this was asked, and empties the queue.
An application places an image on whatever fibre it draws from; the bytes go out on the one that owns the buffer, after that frame's cells, so that a picture sits over the text rather than under it.
Whether the pixels travel through a file rather than through the escape sequence. Settled by the probe at startup; a file is cheaper for anything larger than a few kilobytes and impossible over ssh.