Graphics protocol: Add indexed color image formats
Some checks are pending
CI / Linux (python=3.14 cc=clang sanitize=1) (push) Waiting to run
CI / Linux (python=3.12 cc=gcc sanitize=0) (push) Waiting to run
CI / Linux (python=3.13 cc=gcc sanitize=1) (push) Waiting to run
CI / Linux package (push) Waiting to run
CI / Bundle test (macos-latest) (push) Waiting to run
CI / Bundle test (ubuntu-latest) (push) Waiting to run
CI / macOS Brew (push) Waiting to run
CI / Test ./dev.sh and benchmark (push) Waiting to run
CodeQL / CodeQL-Build (actions, ubuntu-latest) (push) Waiting to run
CodeQL / CodeQL-Build (c, macos-latest) (push) Waiting to run
CodeQL / CodeQL-Build (c, ubuntu-latest) (push) Waiting to run
CodeQL / CodeQL-Build (go, ubuntu-latest) (push) Waiting to run
CodeQL / CodeQL-Build (python, ubuntu-latest) (push) Waiting to run
Depscan / Scan dependencies for vulnerabilities (push) Waiting to run

Add two new image formats, f=8 with one byte per pixel that is an index
into the terminal color palette and f=16 with a palette index followed by
an alpha byte. Indices 0-247 are the SGR 256 color table entries and
248-255 are special colors: default background, default foreground,
selection background and foreground, cursor, cursor text, URL color and
one reserved slot. Such images change color automatically when the
terminal colors change.

The images are uploaded as integer textures and drawn by a separate
shader program that looks up colors in the existing per window color
table uniform block, so a color scheme change costs nothing extra and
rendering of normal images is unaffected. Programs are switched only at
boundaries between runs of indexed and normal images in draw order. The
shader does bilinear filtering after the palette lookup since integer
textures cannot be filtered. Animation and frame composition are not
supported for these formats.

Closes #10666
This commit is contained in:
Kovid Goyal 2026-10-15 22:00:03 +05:30
parent 7dbfb0e1ce
commit 535c7502e8
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
17 changed files with 354 additions and 22 deletions

View file

@ -231,6 +231,11 @@ Detailed list of changes
0.50.0 [future]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Graphics protocol: Add two new :ref:`indexed color image formats
<indexed_color_data>` whose pixels are indices into the terminal color
palette, so that images automatically change color along with the terminal
color scheme (:iss:`9379`)
- Allow docking kitty windows to the edges of other windows or of the tab, for
status bars, file trees, etc. Create them with :code:`launch --type=window-dock`
or :code:`launch --type=tab-dock`, see :ref:`docks`

View file

@ -281,7 +281,9 @@ emulator must understand pixel data in three formats, 24-bit RGB, 32-bit RGBA an
PNG. This is specified using the ``f`` key in the control data. ``f=32`` (which is the
default) indicates 32-bit RGBA data and ``f=24`` indicates 24-bit RGB data and ``f=100``
indicates PNG data. The PNG format is supported both for convenience, and as a compact way
of transmitting paletted images.
of transmitting paletted images. Additionally, ``f=8`` and ``f=16`` indicate
:ref:`indexed color data <indexed_color_data>`, whose colors come from the
terminal color scheme.
RGB and RGBA data
~~~~~~~~~~~~~~~~~~~
@ -297,6 +299,60 @@ Here the width and height are specified using the ``s`` and ``v`` keys respectiv
``f=24`` there are three bytes per pixel and therefore the pixel data must be ``3 * 10 * 20 = 600``
bytes.
.. _indexed_color_data:
Indexed color data
~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 0.50.0
In these formats every pixel is an index into the terminal's color palette,
rather than an actual color. The image is drawn using the current colors of
the terminal and is automatically redrawn when they change, for example, when
the user switches from a dark to a light color theme. This is useful for
graphics such as charts and diagrams that should match the colors of the text
around them. As with RGB data, the image dimensions **must** be sent in the
control data. For example::
<ESC>_Gf=16,s=10,v=20;<payload><ESC>\
With ``f=8`` every pixel is a single byte, the palette index, and the image is
fully opaque, so the data must be ``10 * 20 = 200`` bytes. With ``f=16`` every
pixel is two bytes, the palette index followed by the alpha (opacity) of the
pixel, from ``0`` (fully transparent) to ``255`` (fully opaque), so the data
must be ``2 * 10 * 20 = 400`` bytes. Use a transparent pixel when you want
whatever is below the image, such as the terminal background, to show through,
and partially transparent pixels to anti-alias edges.
The palette index maps to colors as follows:
=========== ====================================================================
Index Color
=========== ====================================================================
0 - 247 The same colors as in the SGR 256 color table, that is the 16
ANSI colors, the 6x6x6 color cube and the first sixteen shades
of the grayscale ramp
248 The default background color
249 The default foreground color
250 The selection background color
251 The selection foreground color
252 The cursor color
253 The cursor text color
254 The color used to highlight URLs on mouse hover
255 Reserved for future use, currently the default foreground color
=========== ====================================================================
When a terminal setting means one of the special colors at ``250 - 253`` is
taken from the cell it is drawn over, the default foreground color is used
for ``250`` and ``252`` and the default background color for ``251`` and
``253``. Note that ``248`` is always drawn as an opaque color, ignoring any
background opacity of the terminal window, use transparent pixels instead to
let the actual window background show through.
Animation and frame composition are not supported for images in these formats.
Clients can check for support by sending a :ref:`query <querying>` with
``f=8`` and checking for an ``OK`` response.
PNG data
~~~~~~~~~~~~~~~
@ -426,6 +482,8 @@ position when the final chunk is received. Finally, terminals must not display
anything, until the entire sequence is received and validated.
.. _querying:
Querying support and available transmission mediums
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1078,7 +1136,7 @@ Key Value Default Description
**Keys for image transmission**
-----------------------------------------------------------
``f`` Positive integer. ``32`` The format in which the image data is sent.
``(24, 32, 100)``.
``(8, 16, 24, 32, 100)``.
``t`` Single character. ``d`` The transmission medium used.
``(d, f, t, s)``.
``s`` Positive integer. ``0`` The width of the image being sent.

View file

@ -536,6 +536,15 @@ colorprofile_to_color(const ColorProfile *self, DynamicColor entry, DynamicColor
return entry;
}
// Resolve to an actual RGB color, using fallback for special colors, that
// is colors that depend on the cell they are used in.
static color_type
resolved_dynamic_color(const ColorProfile *self, DynamicColor overridden, DynamicColor configured, color_type fallback) {
DynamicColor ans = colorprofile_to_color(self, overridden, configured);
if (ans.type == COLOR_IS_INDEX) ans = colorprofile_to_color(self, ans, ans);
return ans.type == COLOR_IS_RGB ? (color_type)ans.rgb : fallback;
}
color_type
colorprofile_to_color_with_fallback(ColorProfile *self, DynamicColor entry, DynamicColor defval, DynamicColor fallback, DynamicColor fallback_defval) {
switch (entry.type) {
@ -710,6 +719,24 @@ copy_color_table_to_buffer(ColorProfile *self, color_type *buf, int offset, size
*buf = self->mark_foregrounds[i];
buf += stride;
}
// Copy the special colors used by indexed color images, these must be in
// the order defined in the graphics protocol documentation.
const color_type fg = resolved_dynamic_color(self, self->overridden.default_fg, self->configured.default_fg, 0);
const color_type bg = resolved_dynamic_color(self, self->overridden.default_bg, self->configured.default_bg, 0);
const color_type specials[NUM_INDEXED_IMAGE_SPECIAL_COLORS] = {
bg,
fg,
resolved_dynamic_color(self, self->overridden.highlight_bg, self->configured.highlight_bg, fg),
resolved_dynamic_color(self, self->overridden.highlight_fg, self->configured.highlight_fg, bg),
resolved_dynamic_color(self, self->overridden.cursor_color, self->configured.cursor_color, fg),
resolved_dynamic_color(self, self->overridden.cursor_text_color, self->configured.cursor_text_color, bg),
OPT(url_color),
fg, // reserved
};
for (i = 0; i < arraysz(specials); i++) {
*buf = specials[i];
buf += stride;
}
self->dirty = false;
}

View file

@ -1001,6 +1001,7 @@ PyInit_fast_data_types(void) {
s(BLINK, blink);
#undef s
PyModule_AddIntConstant(m, "MARK_MASK", MARK_MASK);
PyModule_AddIntConstant(m, "NUM_INDEXED_IMAGE_SPECIAL_COLORS", NUM_INDEXED_IMAGE_SPECIAL_COLORS);
PyModule_AddIntConstant(m, "DECORATION_MASK", DECORATION_MASK);
PyModule_AddStringMacro(m, ERROR_PREFIX);
#ifdef KITTY_VCS_REV

View file

@ -298,6 +298,10 @@ typedef struct TransparentDynamicColor {
#define MARK_MASK (3u)
// Number of special colors such as the default foreground and background
// that indexed color images can use, they are the last colors in the
// 256 color palette available to such images, see graphics-protocol.rst
#define NUM_INDEXED_IMAGE_SPECIAL_COLORS (8u)
typedef struct {
PyObject_HEAD

View file

@ -306,8 +306,10 @@ DIM: int
GRAPHICS_ALPHA_MASK_PROGRAM: int
GRAPHICS_PROGRAM: int
GRAPHICS_PREMULT_PROGRAM: int
GRAPHICS_INDEXED_PROGRAM: int
MARK: int
MARK_MASK: int
NUM_INDEXED_IMAGE_SPECIAL_COLORS: int
DECORATION_MASK: int
FILE_TRANSFER_CODE: int
ESC_CSI: int

View file

@ -277,6 +277,7 @@ grman_pause_rendering(GraphicsManager *self, GraphicsManager *dest) {
dest->num_of_below_refs = 0;
dest->num_of_negative_refs = 0;
dest->num_of_positive_refs = 0;
dest->num_of_indexed_refs = 0;
if (self == NULL) return;
dest->window_id = self->window_id;
dest->layers_dirty = true;
@ -692,7 +693,7 @@ get_free_client_id(const GraphicsManager *self) {
}
#define MAX_DATA_SZ (4u * 100000000u)
enum FORMATS { RGB = 24, RGBA = 32, PNG = 100 };
enum FORMATS { INDEXED = 8, INDEXED_ALPHA = 16, RGB = 24, RGBA = 32, PNG = 100 };
static bool
is_file_transmission(const unsigned char transmission_type) {
@ -905,6 +906,14 @@ initialize_load_data(
self->currently_loading.is_4byte_aligned = data_fmt == RGBA || (self->currently_loading.width % 4 == 0);
self->currently_loading.is_opaque = data_fmt == RGB;
break;
case INDEXED:
case INDEXED_ALPHA:
self->currently_loading.indexed_px_sz = data_fmt / 8;
self->currently_loading.data_sz = (size_t)g->data_width * g->data_height * self->currently_loading.indexed_px_sz;
if (!self->currently_loading.data_sz) ABRT("EINVAL", "Zero width/height not allowed");
self->currently_loading.is_4byte_aligned = ((size_t)self->currently_loading.width * self->currently_loading.indexed_px_sz) % 4 == 0;
self->currently_loading.is_opaque = data_fmt == INDEXED;
break;
default: ABRT("EINVAL", "Unknown image format: %u", data_fmt);
}
self->currently_loading.loading_for.image_id = img->internal_id;
@ -938,7 +947,9 @@ upload_to_gpu(GraphicsManager *self, Image *img, const bool is_opaque, const boo
if (!make_window_context_current(self->window_id)) return;
self->context_made_current_for_this_command = true;
}
if (img->texture) { send_image_to_gpu(&img->texture->id, data, img->width, img->height, is_opaque, is_4byte_aligned, true, REPEAT_CLAMP); }
if (!img->texture) return;
if (img->indexed_px_sz) send_indexed_image_to_gpu(&img->texture->id, data, img->width, img->height, img->indexed_px_sz, is_4byte_aligned);
else send_image_to_gpu(&img->texture->id, data, img->width, img->height, is_opaque, is_4byte_aligned, true, REPEAT_CLAMP);
}
static Image *
@ -958,6 +969,7 @@ handle_add_command(GraphicsManager *self, const GraphicsCommand *g, const uint8_
free_image_resources(self, img);
img->texture = new_texture_ref();
img->root_frame_data_loaded = false;
img->indexed_px_sz = 0;
img->is_drawn = false;
img->current_frame_shown_at = 0;
img->extra_framecnt = 0;
@ -993,7 +1005,8 @@ handle_add_command(GraphicsManager *self, const GraphicsCommand *g, const uint8_
self->currently_loading.loading_for = (const ImageAndFrame){0};
img = process_image_data(self, img, g, fmt);
if (!img) return NULL;
size_t required_sz = (size_t)(self->currently_loading.is_opaque ? 3 : 4) * self->currently_loading.width * self->currently_loading.height;
const size_t px_sz = self->currently_loading.indexed_px_sz ? self->currently_loading.indexed_px_sz : (self->currently_loading.is_opaque ? 3 : 4);
size_t required_sz = px_sz * self->currently_loading.width * self->currently_loading.height;
if (self->currently_loading.data_sz != required_sz)
ABRT(
"EINVAL",
@ -1005,6 +1018,7 @@ handle_add_command(GraphicsManager *self, const GraphicsCommand *g, const uint8_
if (self->currently_loading.loading_completed_successfully) {
img->width = self->currently_loading.width;
img->height = self->currently_loading.height;
img->indexed_px_sz = self->currently_loading.indexed_px_sz;
if (img->root_frame.id) remove_from_cache(self, (const ImageAndFrame){.image_id = img->internal_id, .frame_id = img->root_frame.id});
img->root_frame = (const Frame){
.id = ++img->frame_id_counter,
@ -1505,6 +1519,7 @@ grman_update_layers(
self->num_of_below_refs = 0;
self->num_of_negative_refs = 0;
self->num_of_positive_refs = 0;
self->num_of_indexed_refs = 0;
ImageRect r;
float screen_width = dx * num_cols, screen_height = dy * num_rows;
float screen_bottom = screen_top - screen_height;
@ -1575,6 +1590,8 @@ grman_update_layers(
rd->image_id = img->internal_id;
rd->ref_id = ref->internal_id;
rd->texture_id = texture_id_for_img(img);
rd->indexed_px_sz = img->indexed_px_sz;
if (img->indexed_px_sz) self->num_of_indexed_refs++;
img->is_drawn = true;
refitr = vt_next(refitr);
}
@ -1867,6 +1884,7 @@ handle_animation_frame_load_command(GraphicsManager *self, GraphicsCommand *g, I
if (is_chunked_continuation) {
INIT_CHUNKED_LOAD; // g now points to the command that started the chunked load
}
if (img->indexed_px_sz || fmt == INDEXED || fmt == INDEXED_ALPHA) ABRT("EINVAL", "Animation is not supported for indexed color images");
uint32_t frame_number = g->frame_number;
if (!frame_number || frame_number > img->extra_framecnt + 2) frame_number = img->extra_framecnt + 2;
bool is_new_frame = frame_number == img->extra_framecnt + 2;
@ -2214,6 +2232,10 @@ cfd_free(CoalescedFrameData *p) {
static void
handle_compose_command(GraphicsManager *self, bool *is_dirty, const GraphicsCommand *g, Image *img) {
if (img->indexed_px_sz) {
set_command_failed_response("EINVAL", "Composition is not supported for indexed color images");
return;
}
Frame *src_frame = frame_for_number(img, g->frame_number);
if (!src_frame) {
set_command_failed_response("ENOENT", "No source frame number %u exists in image id: %u\n", g->frame_number, img->client_id);
@ -2835,7 +2857,7 @@ image_as_dict(GraphicsManager *self, Image *img) {
"{sI sI sI sI sI sI sI "
"sO sI sO "
"sI sI sI "
"sI sI sy# sN}",
"sI sI sy# sN sI}",
"texture_id",
texture_id_for_img(img),
U(client_id),
@ -2860,9 +2882,10 @@ image_as_dict(GraphicsManager *self, Image *img) {
U(displayed_frame_id),
"data",
cfd.buf,
(Py_ssize_t)((cfd.is_opaque ? 3 : 4) * img->width * img->height),
(Py_ssize_t)((img->indexed_px_sz ? img->indexed_px_sz : (cfd.is_opaque ? 3 : 4)) * img->width * img->height),
"extra_frames",
frames);
frames,
U(indexed_px_sz));
free(cfd.buf);
return ans;
#undef B
@ -2944,7 +2967,7 @@ W(update_layers) {
ans,
i,
Py_BuildValue(
"{sN sN sI si sK sK}",
"{sN sN sI si sK sK sI}",
"src_rect",
R(src_rect),
"dest_rect",
@ -2956,7 +2979,9 @@ W(update_layers) {
"image_id",
r->image_id,
"ref_id",
r->ref_id));
r->ref_id,
"indexed_px_sz",
(unsigned int)r->indexed_px_sz));
#undef R
}
return ans;
@ -3068,6 +3093,7 @@ grman_render_data(GraphicsManager *self) {
.num_of_below_refs = self->num_of_below_refs,
.num_of_negative_refs = self->num_of_negative_refs,
.num_of_positive_refs = self->num_of_positive_refs,
.num_of_indexed_refs = self->num_of_indexed_refs,
};
return ans;
}

View file

@ -52,6 +52,8 @@ typedef struct {
ImageRect src_rect, dest_rect;
uint32_t texture_id, group_count;
int z_index;
// Zero for normal images, otherwise the number of bytes per pixel of an indexed color image
uint8_t indexed_px_sz;
id_type image_id, ref_id;
} ImageRenderData;
@ -110,6 +112,9 @@ typedef struct {
uint32_t client_id, client_number, width, height;
TextureRef *texture;
id_type internal_id;
// Zero for normal images, otherwise the number of bytes per pixel of an
// indexed color image. Such images cannot have more than one frame.
uint8_t indexed_px_sz;
bool root_frame_data_loaded;
id_type ref_id_counter;
@ -139,6 +144,7 @@ typedef struct {
uint8_t *data;
bool is_4byte_aligned;
bool is_opaque, loading_completed_successfully;
uint8_t indexed_px_sz;
uint32_t width, height;
GraphicsCommand start_command;
ImageAndFrame loading_for;
@ -162,6 +168,8 @@ typedef struct {
bool layers_dirty;
// The number of images below MIN_ZINDEX / 2, then the number of refs between MIN_ZINDEX / 2 and -1 inclusive, then the number of refs above 0 inclusive.
size_t num_of_below_refs, num_of_negative_refs, num_of_positive_refs;
// The number of visible refs to indexed color images
size_t num_of_indexed_refs;
unsigned int last_scrolled_by;
float last_scroll_offset_lines;
size_t used_storage;
@ -217,7 +225,7 @@ tex_pos_y(const int px_from_top_margin, const unsigned texture_height) {
typedef struct GraphicsRenderData {
size_t count, capacity, num_of_below_refs, num_of_negative_refs, num_of_positive_refs;
size_t count, capacity, num_of_below_refs, num_of_negative_refs, num_of_positive_refs, num_of_indexed_refs;
ImageRenderData *images;
} GraphicsRenderData;

View file

@ -28,6 +28,7 @@ enum {
GRAPHICS_PROGRAM,
GRAPHICS_PREMULT_PROGRAM,
GRAPHICS_ALPHA_MASK_PROGRAM,
GRAPHICS_INDEXED_PROGRAM,
BGIMAGE_PROGRAM,
TINT_PROGRAM,
TRAIL_PROGRAM,
@ -403,6 +404,23 @@ send_image_to_gpu(GLuint *tex_id, const void *data, GLsizei width, GLsizei heigh
glTexImage2D(GL_TEXTURE_2D, 0, GL_SRGB_ALPHA, width, height, 0, is_opaque ? GL_RGB : GL_RGBA, GL_UNSIGNED_BYTE, data);
}
// Indexed color images are stored as integer textures with the palette index
// in the red channel and, if bytes_per_pixel is 2, alpha in the green channel.
// Integer textures cannot be filtered, the shader does its own filtering after
// the palette lookup.
void
send_indexed_image_to_gpu(GLuint *tex_id, const void *data, GLsizei width, GLsizei height, unsigned bytes_per_pixel, bool is_4byte_aligned) {
if (!(*tex_id)) { glGenTextures(1, tex_id); }
glBindTexture(GL_TEXTURE_2D, *tex_id);
glPixelStorei(GL_UNPACK_ALIGNMENT, is_4byte_aligned ? 4 : 1);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
const bool has_alpha = bytes_per_pixel == 2;
glTexImage2D(GL_TEXTURE_2D, 0, has_alpha ? GL_RG8UI : GL_R8UI, width, height, 0, has_alpha ? GL_RG_INTEGER : GL_RED_INTEGER, GL_UNSIGNED_BYTE, data);
}
// }}}
// Rounded rect {{{
@ -522,6 +540,7 @@ upload_gamma_lut(void) {
for (int i = CELL_PROGRAM; i < CELL_PROGRAM_SENTINEL; i++) U(i);
U(BORDERS_PROGRAM);
U(PADDING_PROGRAM);
U(GRAPHICS_INDEXED_PROGRAM);
#undef U
unbind_program();
}
@ -568,6 +587,11 @@ init_cell_program(void) {
C(sprite_idx, 1);
C(is_selected, 2);
#undef C
// Indexed color images get their colors from the color table of the window they are in
{
UniformBlock ct = program_uniform_block(GRAPHICS_INDEXED_PROGRAM, "ColorTable");
glUniformBlockBinding(program_id(GRAPHICS_INDEXED_PROGRAM), ct.index, COLOR_TABLE_BINDING_POINT);
}
if (shader_globals_vao_idx == -1) {
shader_globals_vao_idx = create_vao();
@ -1281,9 +1305,11 @@ draw_graphics(int program, ImageRenderData *data, GLuint start, GLuint count, fl
glActiveTexture(GL_TEXTURE0 + GRAPHICS_UNIT);
GLint src_rect_loc = program_uniform_location(program, "src_rect");
GLint dest_rect_loc = program_uniform_location(program, "dest_rect");
const GLint has_alpha_loc = program == GRAPHICS_INDEXED_PROGRAM ? program_uniform_location(program, "has_alpha") : -1;
for (GLuint i = 0; i < count;) {
ImageRenderData *group = data + start + i;
glBindTexture(GL_TEXTURE_2D, group->texture_id);
if (has_alpha_loc > -1) glUniform1ui(has_alpha_loc, group->indexed_px_sz == 2);
if (group->group_count == 0) {
i++;
continue;
@ -1356,7 +1382,7 @@ set_cell_uniforms(bool force) {
if (!constants_set || force) {
float text_contrast = 1.0f + OPT(text_contrast) * 0.01f;
float text_gamma_adjustment = OPT(text_gamma_adjustment) < 0.01f ? 1.0f : 1.0f / OPT(text_gamma_adjustment);
for (int i = GRAPHICS_PROGRAM; i <= GRAPHICS_ALPHA_MASK_PROGRAM; i++) {
for (int i = GRAPHICS_PROGRAM; i <= GRAPHICS_INDEXED_PROGRAM; i++) {
bind_program(i);
glUniform1i(program_uniform_location(i, "image"), GRAPHICS_UNIT);
}
@ -2238,6 +2264,28 @@ draw_tint(const UIRenderData *ui) {
draw_quad(true, 0);
}
// Draw a range of the image render data. Indexed color images need a
// different program, so when any are present, switch programs at the
// boundaries between runs of indexed and normal images, preserving draw order.
static void
draw_image_layer(const UIRenderData *ui, ssize_t vao_idx, GLuint start, GLuint count) {
if (!ui->grd.num_of_indexed_refs) {
draw_graphics(GRAPHICS_PROGRAM, ui->grd.images, start, count, ui->inactive_text_alpha);
return;
}
CELL_BUFFERS;
// The color table may not be bound yet, for example, when the window has a background image
bind_vao_uniform_buffer(vao_idx, color_table_buffer, COLOR_TABLE_BINDING_POINT);
const ImageRenderData *data = ui->grd.images;
for (GLuint run_start = start, end = start + count; run_start < end;) {
const bool is_indexed = data[run_start].indexed_px_sz != 0;
GLuint run_end = run_start + 1;
while (run_end < end && (data[run_end].indexed_px_sz != 0) == is_indexed) run_end++;
draw_graphics(is_indexed ? GRAPHICS_INDEXED_PROGRAM : GRAPHICS_PROGRAM, ui->grd.images, run_start, run_end - run_start, ui->inactive_text_alpha);
run_start = run_end;
}
}
static void
draw_cells_with_layers(const UIRenderData *ui, ssize_t vao_idx) {
if (ui->has_background_image && OPT(background_tint) > 0) draw_tint(ui);
@ -2245,16 +2293,13 @@ draw_cells_with_layers(const UIRenderData *ui, ssize_t vao_idx) {
if (has_content_between_background_and_foreground) {
if (!ui->has_background_image) call_cell_program(CELL_BG_PROGRAM, ui, vao_idx, false, DRAW_DEFAULT_BG);
if (ui->window_logo != NULL) draw_window_logo(ui);
if (ui->grd.num_of_below_refs > 0) draw_graphics(GRAPHICS_PROGRAM, ui->grd.images, 0, ui->grd.num_of_below_refs, ui->inactive_text_alpha);
if (ui->grd.num_of_below_refs > 0) draw_image_layer(ui, vao_idx, 0, ui->grd.num_of_below_refs);
call_cell_program(CELL_BG_PROGRAM, ui, vao_idx, false, DRAW_NON_DEFAULT_BG);
if (ui->grd.num_of_negative_refs)
draw_graphics(GRAPHICS_PROGRAM, ui->grd.images, ui->grd.num_of_below_refs, ui->grd.num_of_negative_refs, ui->inactive_text_alpha);
if (ui->grd.num_of_negative_refs) draw_image_layer(ui, vao_idx, ui->grd.num_of_below_refs, ui->grd.num_of_negative_refs);
call_cell_program(CELL_FG_PROGRAM, ui, vao_idx, false, DRAW_NEITHER_BG);
} else call_cell_program(CELL_PROGRAM, ui, vao_idx, false, ui->has_background_image ? DRAW_NON_DEFAULT_BG : DRAW_BOTH_BG);
if (ui->grd.num_of_positive_refs > 0)
draw_graphics(
GRAPHICS_PROGRAM, ui->grd.images, ui->grd.num_of_below_refs + ui->grd.num_of_negative_refs, ui->grd.num_of_positive_refs, ui->inactive_text_alpha);
if (ui->grd.num_of_positive_refs > 0) draw_image_layer(ui, vao_idx, ui->grd.num_of_below_refs + ui->grd.num_of_negative_refs, ui->grd.num_of_positive_refs);
draw_visual_bell(ui);
draw_drag_preview_overlay(ui);
@ -3840,6 +3885,7 @@ init_shaders(PyObject *module) {
C(GRAPHICS_PROGRAM);
C(GRAPHICS_PREMULT_PROGRAM);
C(GRAPHICS_ALPHA_MASK_PROGRAM);
C(GRAPHICS_INDEXED_PROGRAM);
C(BGIMAGE_PROGRAM);
C(TINT_PROGRAM);
C(TRAIL_PROGRAM);

View file

@ -44,8 +44,11 @@ public struct CellRenderData {
// Uniform Blocks (adjust binding slots as needed for your pipeline layout)
public ConstantBuffer<CellRenderData> crd;
// The SGR color table, then the mark background and foreground colors and
// finally the special colors used by indexed color images.
#define INDEXED_IMAGE_SPECIAL_COLORS_OFFSET (NUM_COLORS + MARK_MASK + MARK_MASK + 2)
public struct ColorTable {
uint color_table[NUM_COLORS + MARK_MASK + MARK_MASK + 2];
uint color_table[INDEXED_IMAGE_SPECIAL_COLORS_OFFSET + NUM_INDEXED_IMAGE_SPECIAL_COLORS];
};
public ConstantBuffer<ColorTable> ctb;
@ -96,6 +99,17 @@ color_to_vec(uint c) {
return float3(gamma_lut[r], gamma_lut[g], gamma_lut[b]);
}
// Convert an entry in the palette of indexed color images to a linear color.
// The palette is the SGR color table with its last few entries replaced by
// special colors such as the default foreground and background.
public float3
indexed_image_color(uint idx) {
const uint first_special = NUM_COLORS - NUM_INDEXED_IMAGE_SPECIAL_COLORS;
idx &= BYTE_MASK;
const uint slot = idx < first_special ? idx : idx + (INDEXED_IMAGE_SPECIAL_COLORS_OFFSET - first_special);
return color_to_vec(color_table[slot]);
}
public float
one_if_equal_zero_otherwise(float a, float b) {
return (1.0f - zero_or_one(abs(float(a) - float(b))));

View file

@ -0,0 +1,54 @@
#language slang 2026
// Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
// Distributed under terms of the GPLv3 license.
// Renders images whose pixels are indices into the terminal color palette, so
// that they change automatically when the terminal colors change. This is a
// separate program from graphics.slang so that rendering of normal images has
// no overhead because of it.
import blit_common;
import background;
struct VSOutput {
float2 texcoord : TEXCOORD;
float4 position : SV_Position;
};
[shader("vertex")]
VSOutput
vertex_main(uint vertex_id: SV_VertexID, uniform float4 src_rect, uniform float4 dest_rect, ) {
BlitOutput ans = get_coords_for_blit(vertex_id, src_rect, dest_rect);
return { ans.texcoord, float4(ans.position[0], ans.position[1], 0.0, 1.0) };
}
// The red channel is the palette index and, when has_alpha is non-zero, the
// green channel is the straight alpha.
uniform Sampler2D<uint4> image;
float4
premult_color_at(int2 pos, uint has_alpha) {
uint4 px = image[pos];
float alpha = has_alpha != 0 ? float(px.g) / 255.0 : 1.0;
return float4(indexed_image_color(px.r) * alpha, alpha);
}
[shader("fragment")]
float4
fragment_main(float2 texcoord: TEXCOORD, uniform uint has_alpha, uniform float extra_alpha)
: SV_Target {
// Integer textures cannot be filtered and anyway the palette lookup must
// happen before interpolation, so do bilinear filtering here. When the
// image is not scaled this reduces to reading a single pixel.
int width, height;
image.GetDimensions(width, height);
const int2 limit = int2(width - 1, height - 1);
const float2 pos = texcoord * float2(width, height) - 0.5;
const float2 base = floor(pos);
const float2 frac = pos - base;
const int2 p0 = clamp(int2(base), int2(0, 0), limit);
const int2 p1 = clamp(int2(base) + int2(1, 1), int2(0, 0), limit);
const float4 top = lerp(premult_color_at(p0, has_alpha), premult_color_at(int2(p1.x, p0.y), has_alpha), frac.x);
const float4 bottom = lerp(premult_color_at(int2(p0.x, p1.y), has_alpha), premult_color_at(p1, has_alpha), frac.x);
return lerp(top, bottom, frac.y) * extra_alpha;
}

View file

@ -42,6 +42,7 @@ from kitty.fast_data_types import (
DIM,
GLSL_VERSION,
GRAPHICS_ALPHA_MASK_PROGRAM,
GRAPHICS_INDEXED_PROGRAM,
GRAPHICS_PREMULT_PROGRAM,
GRAPHICS_PROGRAM,
MARK,
@ -49,6 +50,7 @@ from kitty.fast_data_types import (
MAX_CUSTOM_SHADER_GROUPS,
MAX_SHADER_ANIM_USER_EVENT_NAME_LEN,
MAX_SHADER_ANIM_USER_EVENTS,
NUM_INDEXED_IMAGE_SPECIAL_COLORS,
PADDING_PROGRAM,
POINTER_MAP_SIZE,
REVERSE,
@ -285,6 +287,7 @@ class LoadShaderPrograms:
'rounded_rect': ROUNDED_RECT_PROGRAM,
'border': BORDERS_PROGRAM,
'padding': PADDING_PROGRAM,
'indexed_graphics': GRAPHICS_INDEXED_PROGRAM,
}.items():
vert, frag = glsl_shaders(name)
compile_program(prog, (vert,), (frag,), metadata[name], allow_recompile)
@ -734,6 +737,7 @@ class SlangFile(NamedTuple):
match os.path.basename(self.path):
case 'background.slang' | 'cell.slang':
ans['MARK_MASK'] = str(MARK_MASK)
ans['NUM_INDEXED_IMAGE_SPECIAL_COLORS'] = str(NUM_INDEXED_IMAGE_SPECIAL_COLORS)
ans['REVERSE_SHIFT'] = str(REVERSE)
ans['STRIKE_SHIFT'] = str(STRIKETHROUGH)
ans['DIM_SHIFT'] = str(DIM)

View file

@ -1600,6 +1600,26 @@ PYWRAP0(apply_options_update) {
Py_RETURN_NONE;
}
// Indexed color images use the url color, so the color tables on the GPU must
// be refreshed when it changes
static void
mark_all_color_profiles_dirty(void) {
for (size_t o = 0; o < global_state.num_os_windows; o++) {
OSWindow *osw = global_state.os_windows + o;
for (size_t t = 0; t < osw->num_tabs; t++) {
Tab *tab = osw->tabs + t;
for (size_t w = 0; w < tab->num_windows; w++) {
Screen *screen = tab->windows[w].render_data.screen;
if (screen) {
screen->color_profile->dirty = true;
screen->paused_rendering.color_profile.dirty = true;
screen->is_dirty = true;
}
}
}
}
}
PYWRAP1(patch_global_colors) {
PyObject *spec;
int configured;
@ -1623,7 +1643,9 @@ PYWRAP1(patch_global_colors) {
P(scrollbar_track_color);
if (configured) {
P(background);
const color_type prev_url_color = OPT(url_color);
P(url_color);
if (OPT(url_color) != prev_url_color) mark_all_color_profiles_dirty();
}
if (PyErr_Occurred()) return NULL;
Py_RETURN_NONE;

View file

@ -782,6 +782,7 @@ void set_gpu_viewport(unsigned w, unsigned h);
void free_texture(uint32_t *);
void free_framebuffer(uint32_t *);
void send_image_to_gpu(uint32_t *, const void *, int32_t, int32_t, bool, bool, bool, RepeatStrategy);
void send_indexed_image_to_gpu(uint32_t *, const void *, int32_t, int32_t, unsigned, bool);
void send_sprite_to_gpu(FONTS_DATA_HANDLE fg, sprite_index, pixel *, sprite_index);
void blank_canvas(float, color_type, bool);
void blank_os_window(OSWindow *);

View file

@ -937,6 +937,52 @@ class TestGraphics(BaseTest):
self.ae(put_image(s, 8, 16, id=2, z=-1)[1], 'OK')
self.ae(group_counts(), (2, 1, 1, 2, 1))
def test_indexed_color_images(self):
s, g, pl, sl = load_helpers(self)
li = make_send_command(s)
# Loading
self.ae(pl('ab', s=1, v=1, f=8, a='q'), 'OK')
self.ae(g.image_count, 0)
img = sl(bytes(range(8)), s=4, v=2, f=8)
self.ae(img['indexed_px_sz'], 1)
img = sl(bytes(range(8)), s=2, v=2, f=16)
self.ae(img['indexed_px_sz'], 2)
data = bytes(range(256)) * 4
img = sl(zlib.compress(data), s=32, v=16, f=16, o='z', expecting_data=data)
self.ae(img['indexed_px_sz'], 2)
img = g.image_for_client_id(1)
self.ae(pl(bytes(range(3)), s=3, v=1, f=8), 'OK')
img = g.image_for_client_id(1)
self.ae((img['indexed_px_sz'], img['is_4byte_aligned'], img['data']), (1, False, bytes(range(3))))
self.assertTrue(pl(bytes(range(5)), s=3, v=1, f=16).startswith('ENODATA'))
self.assertTrue(pl(b'', s=0, v=1, f=8).startswith('EINVAL'))
# Replacing an indexed image with a normal one
img = sl(b'abcd', s=1, v=1, f=32)
self.ae(img['indexed_px_sz'], 0)
# Animation is not supported
def unsupported(r, what='Animation'):
self.ae((r.code, r.msg), ('EINVAL', f'{what} is not supported for indexed color images'))
self.ae(li(b'abcd', s=2, v=2, f=8, a='t').code, 'OK')
unsupported(li(b'abcd', s=2, v=2, f=8, a='f'))
unsupported(li(b'abcd', s=1, v=1, f=32, a='f'))
unsupported(li(b'', a='c', r=1, c=1, w=1, h=1, x=1, s=0, v=0, f=0), 'Composition')
self.ae(g.image_for_client_id(1)['extra_frames'], ())
self.ae(li(b'abcd', s=1, v=1, f=32, a='t').code, 'OK')
unsupported(li(b'abcd', s=2, v=2, f=8, a='f'))
# Render data
cw, ch = 10, 20
s, dx, dy, put_image, put_ref, layers, rect_eq = put_helpers(self, cw, ch)
self.ae(put_image(s, 10, 20, id=1)[1], 'OK')
self.ae(parse_response(send_command(s, 'a=T,f=16,i=2,s=2,v=2,z=-1', b'\x01\xff' * 4)), 'OK')
self.ae(parse_response(send_command(s, 'a=T,f=8,i=3,s=2,v=2,z=1', b'\xf8' * 4)), 'OK')
self.ae(tuple((x['image_id'], x['indexed_px_sz']) for x in layers(s)), ((2, 2), (1, 0), (3, 1)))
self.ae(s.grman.image_count, 3)
def test_image_parents(self):
cw, ch = 10, 20
iw, ih = 10, 20

View file

@ -44,9 +44,11 @@ const (
type GRT_f int // enum
const (
GRT_format_rgba GRT_f = iota // 32
GRT_format_rgb // 24
GRT_format_png // 100
GRT_format_rgba GRT_f = iota // 32
GRT_format_rgb // 24
GRT_format_png // 100
GRT_format_indexed // 8
GRT_format_indexed_alpha // 16
)
type GRT_t int // enum

View file

@ -94,6 +94,18 @@ func TestGraphicsCommandSerialization(t *testing.T) {
t.Fatalf("Failed to parse payload:\n%s", diff)
}
for _, x := range []struct {
f GRT_f
s string
}{{GRT_format_indexed, "f=8"}, {GRT_format_indexed_alpha, "f=16"}} {
gc = &GraphicsCommand{}
gc.SetFormat(x.f).SetDataWidth(2).SetDataHeight(1)
test_serialize("ab", x.s, "s=2", "v=1")
if q = from_full_apc_escape_code(gc.AsAPC(nil)); q.Format() != x.f {
t.Fatalf("Failed to parse format %s, got: %s", x.s, q.Format())
}
}
test_chunked_payload([]byte("abcd"))
data := make([]byte, 8111)
_, _ = rand.Read(data)