From d994a47fc8c529fc84c049250e40b1a5ea8b2cee Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Fri, 19 Jun 2026 11:36:43 +0530 Subject: [PATCH] Cleanup previous PR --- docs/changelog.rst | 5 ++++- docs/graphics-protocol.rst | 32 ++++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 9b5349f36..b18d01a62 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -176,9 +176,12 @@ Detailed list of changes 0.50.0 [future] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Graphics protocol: Add a new :ref:`transient usage hint ` that clients can send to terminals to indicate an image is meant for only short duration use (:pull:`10092`) + - kitten @ get-text: Add support for :code:`alternate` and :code:`alternate_scrollback` extents to fetch text from the alternate screen buffer (:iss:`10165`) -- Wayland: Fix first OS window being a few cells too small when :opt:`initial_window_width`/:opt:`initial_window_height` are set in cells and a fractional display scale is in use (:iss:`10146`) +- Wayland: Fix first OS window being a few cells too small when ``initial_window_width/initial_window_height`` are set in cells and a fractional display scale is in use (:iss:`10146`) + 0.47.4 [2026-06-15] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst index 925beb688..752231b86 100644 --- a/docs/graphics-protocol.rst +++ b/docs/graphics-protocol.rst @@ -834,6 +834,27 @@ use the ``i`` key with the image id for all future communication. The ability to use image numbers (see :doc:`kittens/query_terminal` to query kitty version) +.. _image_usage_hints: + +Usage hints +----------------------------- + +Clients can specify *usage hints* when creating images using the ``N`` key. +These hints allow the terminal to optimise resource consumption such as caching +strategies. The value of ``N`` is a bitmask. + +Currently the only usage hint defined is ``transient (N == 1)``. +The terminal is free to assume that an image with this hint +will be used for only a short time, and so may, for example, evict its +data before other images when the image is soft deleted, has no visible +placements and the terminal is under storage pressure, or skip writing +its data to disk. The terminal is also free to ignore the hint. If an +animation frame with the *transient* hint is composited onto another +frame, and any of the involved frames have the hint, the resulting +composited frame also has the hint. This hint must be specified when the +image or frame data is transmitted. It has no effect on placement commands. + + .. _animation_protocol: Animation @@ -1052,16 +1073,7 @@ Key Value Default Description ``only z`` ``m`` zero or one ``0`` Whether there is more chunked data available. ``N`` bitmask ``0`` Usage hints from the client to the terminal about the intended use of - the image. Only one hint is currently defined, the ``1`` bit which means - *transient*. The terminal is free to assume that an image with this hint - will be used for only a short time, and so may, for example, evict its - data before other images when the image is soft deleted, has no visible - placements and the terminal is under storage pressure, or skip writing - its data to disk. The terminal is also free to ignore the hint. If an - animation frame with the *transient* hint is composited onto another - frame, and any of the involved frames have the hint, the resulting - composited frame also has the hint. - + the image. **Keys for image display** ----------------------------------------------------------- ``x`` Positive integer ``0`` The left edge (in pixels) of the image area to display