Glyph protocol: render registered glyphs

Cells containing a codepoint from the registration block that had a
registered glyph when they were printed are rendered with that glyph,
into the area the character occupies: its cell, the cells given to it
by the text sizing protocol, or two cells when it is followed by a space
and the width of its viewBox when fit to the cell height is more than
one cell.

The glyph is bound to the text when it is printed, by storing a
reference to it in the text cache entry of the cell. Changing or
clearing a registration affects only text printed afterwards, so
programs using the same codepoints do not change each other's output
and registering never requires re-rendering lines. Bound entries are
kept in a separate map so that other text is not slowed down. Glyphs
are interned by a seeded hash of their content.

Glyphs that use only the foreground color are alpha masks and glyphs
that use only fixed colors are colored sprites. Glyphs that mix them are
a colored sprite followed in the sprite map by a sprite with the weight
of the foreground color, which the cell shader combines with the
foreground color, so that selection, cursor and other foreground color
changes apply to them exactly.

Sprites of a glyph are freed when the glyph is, which happens only when
no cell uses it, and are reused. Each window can keep alive a limited
number and size of glyphs, beyond which registration fails with
no_space, so a program that keeps registering and printing new glyphs
cannot exhaust memory or sprites for other windows.
This commit is contained in:
Kovid Goyal 2026-11-19 11:50:11 +05:30
parent 6c0ca821d8
commit cb7cf51d87
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
15 changed files with 1248 additions and 70 deletions

View file

@ -197,6 +197,45 @@ The status is shown in the tab bar via the :code:`tab.program_status` field of
:code:`on_program_status_change`.
Glyphs registered by programs
---------------------------------
kitty implements the `Glyph Protocol
<https://github.com/raphamorim/rio/blob/main/specs/glyph-protocol.md>`__,
which lets programs register vector glyphs for the codepoints
:code:`U+100000` to :code:`U+1003FF` and then use them as icons in their
output, without needing a font. kitty implements it as follows:
* Only the :code:`vg` payload format, SVG path data with fills, strokes,
gradients and clips, is supported. The font based :code:`glyf`,
:code:`colrv0` and :code:`colrv1` formats are not.
* The :code:`width` key is ignored. A glyph is rendered into the cells its
character occupies. Use the :doc:`text sizing protocol <text-sizing-protocol>`
to render glyphs in more than one cell or at a larger size. As with other
private use characters, a glyph followed by a space is rendered in two cells,
when the width of its viewBox, scaled to the height of a cell, is more than
one cell.
* Queries for grapheme clusters are not supported. Queries for codepoints
outside the registration block are answered with :code:`reason=unknown`, as
kitty does not perform font lookups while parsing input. Queries for
codepoints in the registration block are answered from the registrations.
* The glyph registered for a codepoint is bound to the text when it is
printed. Changing or clearing a registration affects only text printed
afterwards, so programs using the same codepoints for different glyphs do not
change each other's output, in the scrollback or on screen. Colors that use
the foreground color are applied when the glyph is drawn, so they follow
changes to the foreground color, such as selection and the cursor.
* Each window can keep alive a limited number of glyphs, whether registered or
used by its text, including text in the scrollback. Beyond that, new
registrations fail with :code:`no_space` until text using glyphs is erased
or scrolls out of the scrollback. Glyphs and the GPU memory used to draw
them are released when no longer used by any text.
kitty specific private escape codes
---------------------------------------

View file

@ -1807,3 +1807,6 @@ def render_vg(
align: tuple[str, str] = ('center', 'center'),
repeat: int = 1,
) -> RenderedVG: ...
def vg_live_glyph_memory() -> int: ...
def vg_set_window_limits(memory: int = ..., count: int = ...) -> None: ...
def set_glyph_protocol_sprite_limits(total: int = ..., per_window: int = ..., per_glyph: int = ...) -> None: ...

View file

@ -16,6 +16,7 @@
#include "shaped-run-cache.h"
#include "print-graphics.h"
#include "simd-string.h"
#include "vector-glyph.h"
#define MISSING_GLYPH 1
#define MAX_NUM_EXTRA_GLYPHS_PUA 4u
@ -25,7 +26,13 @@
static PyObject *python_send_to_gpu_impl = NULL;
extern PyTypeObject Line_Type;
enum { NO_FONT = -3, MISSING_FONT = -2, BLANK_FONT = -1, BOX_FONT = 0 };
enum { GLYPH_FONT = -4, NO_FONT = -3, MISSING_FONT = -2, BLANK_FONT = -1, BOX_FONT = 0 };
// The maximum number of sprite slots used for glyphs registered with the glyph
// protocol in a font group, the number one window can use, and the maximum
// number of sprites (one per cell) for each glyph, which can be rendered with
// different parameters. Sprites are freed when their glyph is, these bound the
// GPU memory programs can make kitty use.
static size_t MAX_GLYPH_PROTOCOL_SPRITES = 65536u, MAX_GLYPH_PROTOCOL_SPRITES_PER_WINDOW = 16384u, MAX_GLYPH_PROTOCOL_ENTRIES_PER_GLYPH = 1024u;
typedef enum { LIGATURE_UNKNOWN, INFINITE_LIGATURE_START, INFINITE_LIGATURE_MIDDLE, INFINITE_LIGATURE_END } LigatureType;
@ -134,6 +141,62 @@ static bool
cmpr_decorations_key(DecorationsKey a, DecorationsKey b) {
return a.val == b.val;
}
// Sprites of glyphs registered with the glyph protocol. A glyph can be rendered
// with different parameters, each of which has its own sprites. A sprite is
// identified by the content hash of the glyph and the parameters.
typedef struct GlyphSpriteKey {
uint64_t hash;
uint8_t col, num_cols, scale, subscale, multicell_y, align, unused1, unused2;
} GlyphSpriteKey;
static_assert(sizeof(GlyphSpriteKey) == 16, "Fix the ordering of GlyphSpriteKey");
typedef struct GlyphSpriteValue {
SpritePosition sp;
// The id of the glyph registry of the window charged for the sprite slots
uint64_t owner;
// The number of slots in the sprite map used, zero for sprites that are
// MISSING_GLYPH because the glyph is too complex to render
uint8_t num_slots;
} GlyphSpriteValue;
static uint64_t
hash_glyph_sprite_key(GlyphSpriteKey k) {
uint64_t params;
memcpy(&params, (const uint8_t *)&k + sizeof(k.hash), sizeof(params));
return vt_hash_integer(k.hash ^ (params * 0x9E3779B97F4A7C15ull));
}
static bool
cmpr_glyph_sprite_key(GlyphSpriteKey a, GlyphSpriteKey b) {
return memcmp(&a, &b, sizeof(a)) == 0;
}
#define NAME glyph_sprite_map
#define KEY_TY GlyphSpriteKey
#define VAL_TY GlyphSpriteValue
#define HASH_FN hash_glyph_sprite_key
#define CMPR_FN cmpr_glyph_sprite_key
#include "kitty-verstable.h"
// The keys of the sprites of a glyph, so that they can be freed with the glyph
typedef struct GlyphSprites {
size_t count, capacity;
GlyphSpriteKey *keys;
} GlyphSprites;
#define NAME glyph_sprites_map
#define KEY_TY uint64_t
#define VAL_TY GlyphSprites *
#define HASH_FN vt_hash_integer
#define CMPR_FN vt_cmpr_integer
#include "kitty-verstable.h"
// Sprite slots that were freed, for reuse
typedef struct SpriteHoles {
sprite_index *items;
size_t count, capacity;
} SpriteHoles;
#define NAME decorations_index_map_t
#define KEY_TY DecorationsKey
#define VAL_TY DecorationMetadata
@ -153,6 +216,15 @@ typedef struct {
fallback_font_map_t fallback_font_map;
scaled_font_map_t scaled_font_map;
decorations_index_map_t decorations_index_map;
// Sprites for glyphs registered with the glyph protocol, keyed by the
// content hash of the glyph. The sprites of a glyph are freed when the
// glyph is, as no cell can use it then, and the freed slots are reused.
glyph_sprites_map glyph_sprites;
glyph_sprite_map glyph_sprite_positions;
// Freed single slots and pairs of adjacent slots in the same row of the sprite map
SpriteHoles single_holes, pair_holes;
// The number of slots in use by glyph sprites
size_t glyph_protocol_sprite_count;
} FontGroup;
static FontGroup *font_groups = NULL;
@ -269,6 +341,17 @@ del_font_group(FontGroup *fg) {
vt_cleanup(&fg->fallback_font_map);
vt_cleanup(&fg->scaled_font_map);
vt_cleanup(&fg->decorations_index_map);
for (glyph_sprites_map_itr i = vt_first(&fg->glyph_sprites); !vt_is_end(i); i = vt_next(i)) {
free(i.data->val->keys);
free(i.data->val);
}
vt_cleanup(&fg->glyph_sprites);
vt_cleanup(&fg->glyph_sprite_positions);
free(fg->single_holes.items);
free(fg->pair_holes.items);
zero_at_ptr(&fg->single_holes);
zero_at_ptr(&fg->pair_holes);
fg->glyph_protocol_sprite_count = 0;
for (size_t i = 0; i < fg->fonts_count; i++) del_font(fg->fonts + i);
free(fg->fonts);
fg->fonts = NULL;
@ -440,9 +523,7 @@ calculate_underline_exclusion_zones(pixel *buf, const FontGroup *fg, DecorationG
}
static sprite_index
current_send_sprite_to_gpu(FontGroup *fg, pixel *buf, DecorationMetadata dec, FontCellMetrics scaled_metrics) {
sprite_index ans = current_sprite_index(&fg->sprite_tracker);
if (!do_increment(fg)) return 0;
upload_sprite(FontGroup *fg, sprite_index ans, pixel *buf, DecorationMetadata dec, FontCellMetrics scaled_metrics) {
if (python_send_to_gpu_impl) {
python_send_to_gpu(fg, ans, buf);
return ans;
@ -458,6 +539,13 @@ current_send_sprite_to_gpu(FontGroup *fg, pixel *buf, DecorationMetadata dec, Fo
return ans;
}
static sprite_index
current_send_sprite_to_gpu(FontGroup *fg, pixel *buf, DecorationMetadata dec, FontCellMetrics scaled_metrics) {
sprite_index ans = current_sprite_index(&fg->sprite_tracker);
if (!do_increment(fg)) return 0;
return upload_sprite(fg, ans, buf, dec, scaled_metrics);
}
// }}}
@ -851,6 +939,7 @@ static bool allow_use_of_box_fonts = true;
// - MISSING_FONT
// - BLANK_FONT
// - BOX_FONT
// - GLYPH_FONT
// - an index in the fonts list
static ssize_t
font_for_cell(
@ -886,6 +975,9 @@ font_for_cell(
if (allow_use_of_box_fonts) return BOX_FONT;
/* fallthrough */
default:
// Glyphs registered with the glyph protocol, bound to the cell
// when it was printed, take precedence over fonts
if (cell_registered_glyph(cpu_cell, tc)) return GLYPH_FONT;
// Optimisation to avoid rendering spaces, except in the case of
// scaled multicells as the decorations there have to rendered
// scaled as well.
@ -1097,8 +1189,9 @@ extract_cell_region(Canvas *canvas, unsigned i, Region *src, const Region *dest,
static void
set_cell_sprite(GPUCell *cell, const SpritePosition *sp) {
cell->sprite_idx = sp->idx & 0x7fffffff;
if (sp->colored) cell->sprite_idx |= 0x80000000;
cell->sprite_idx = sp->idx & SPRITE_INDEX_MASK;
if (sp->colored) cell->sprite_idx |= SPRITE_COLORED_FLAG;
if (sp->fg_mix) cell->sprite_idx |= SPRITE_FG_MIX_FLAG;
}
static Region
@ -1267,6 +1360,273 @@ render_box_cell(FontGroup *fg, RunFont rf, CPUCell *cpu_cell, GPUCell *gpu_cell,
#undef failed
}
// Glyph protocol {{{
static inline uint8_t
unpremultiply(uint8_t c, uint8_t a) {
if (!a) return 0;
const unsigned v = ((unsigned)c * 255u + a / 2u) / a;
return v > 255u ? 255u : (uint8_t)v;
}
// Write the rendered glyph into the canvas, at the specified offset. For
// glyphs that mix the foreground color and fixed colors, also write the
// foreground weight, relative to the alpha, into fg_canvas.
static void
copy_registered_glyph_to_canvas(const VGRender *r, pixel *canvas, pixel *fg_canvas, unsigned stride, unsigned x_offset) {
for (unsigned y = 0; y < r->height; y++) {
pixel *dest = canvas + (size_t)y * stride + x_offset, *fg_dest = fg_canvas ? fg_canvas + (size_t)y * stride + x_offset : NULL;
for (unsigned x = 0; x < r->width; x++) {
const size_t i = (size_t)y * r->width + x;
if (!r->color) {
dest[x] = 0xffffff00u | r->fg[i];
continue;
}
const uint8_t *c = r->color + 4 * i, a = c[3];
dest[x] = ((pixel)unpremultiply(c[0], a) << 24) | ((pixel)unpremultiply(c[1], a) << 16) | ((pixel)unpremultiply(c[2], a) << 8) | a;
if (fg_dest) fg_dest[x] = 0xffffff00u | unpremultiply(r->fg[i], a);
}
}
}
static bool
push_hole(SpriteHoles *h, sprite_index idx) {
if (h->count >= h->capacity) {
const size_t cap = MAX(64u, h->capacity * 2);
sprite_index *items = realloc(h->items, cap * sizeof(items[0]));
if (!items) return false;
h->items = items;
h->capacity = cap;
}
h->items[h->count++] = idx;
return true;
}
// Allocate a slot in the sprite map for a glyph sprite, or two adjacent slots
// in the same row if pair is true, reusing freed slots. Returns 0 on failure.
static sprite_index
alloc_glyph_sprite_slot(FontGroup *fg, bool pair) {
if (pair) {
if (fg->pair_holes.count) return fg->pair_holes.items[--fg->pair_holes.count];
if (fg->sprite_tracker.x + 1 >= fg->sprite_tracker.xnum) {
// The slot at the end of the row cannot start a pair
const sprite_index skipped = current_sprite_index(&fg->sprite_tracker);
if (!do_increment(fg)) return 0;
push_hole(&fg->single_holes, skipped);
}
const sprite_index ans = current_sprite_index(&fg->sprite_tracker);
if (!do_increment(fg) || !do_increment(fg)) return 0;
return ans;
}
if (fg->single_holes.count) return fg->single_holes.items[--fg->single_holes.count];
if (fg->pair_holes.count) {
const sprite_index ans = fg->pair_holes.items[--fg->pair_holes.count];
if (!push_hole(&fg->single_holes, ans + 1)) return 0;
return ans;
}
const sprite_index ans = current_sprite_index(&fg->sprite_tracker);
if (!do_increment(fg)) return 0;
return ans;
}
static void
free_glyph_sprites(FontGroup *fg, uint64_t content_hash) {
glyph_sprites_map_itr i = vt_get(&fg->glyph_sprites, content_hash);
if (vt_is_end(i)) return;
GlyphSprites *gs = i.data->val;
for (size_t k = 0; k < gs->count; k++) {
glyph_sprite_map_itr si = vt_get(&fg->glyph_sprite_positions, gs->keys[k]);
if (vt_is_end(si)) continue;
const GlyphSpriteValue *v = &si.data->val;
if (v->num_slots) {
// If pushing fails the slot is leaked, which is harmless
push_hole(v->num_slots > 1 ? &fg->pair_holes : &fg->single_holes, v->sp.idx);
fg->glyph_protocol_sprite_count -= MIN(fg->glyph_protocol_sprite_count, (size_t)v->num_slots);
// The window may have been closed already
GlyphRegistry *owner = glyph_registry_for_id(v->owner);
if (owner) owner->sprite_slots -= MIN(owner->sprite_slots, (size_t)v->num_slots);
}
vt_erase_itr(&fg->glyph_sprite_positions, si);
}
free(gs->keys);
free(gs);
vt_erase_itr(&fg->glyph_sprites, i);
}
// Called when a glyph registered with the glyph protocol is freed. At that
// point no cell uses the glyph, so its sprites can be reused. Lines that used
// it have had their text changed and so are dirty and will be re-rendered
// before their render data is next used.
static void
on_vector_glyph_freed(uint64_t content_hash) {
for (size_t i = 0; i < num_font_groups; i++) free_glyph_sprites(font_groups + i, content_hash);
}
// Create the entry for a sprite, the caller must ensure it does not exist
static GlyphSpriteValue *
create_glyph_sprite(FontGroup *fg, GlyphSpriteKey key) {
GlyphSprites *gs;
glyph_sprites_map_itr it = vt_get(&fg->glyph_sprites, key.hash);
if (vt_is_end(it)) {
gs = calloc(1, sizeof(GlyphSprites));
if (!gs) return NULL;
if (vt_is_end(vt_insert(&fg->glyph_sprites, key.hash, gs))) {
free(gs);
return NULL;
}
} else gs = it.data->val;
if (gs->count >= gs->capacity) {
const size_t cap = MAX(8u, gs->capacity * 2);
GlyphSpriteKey *k = realloc(gs->keys, cap * sizeof(k[0]));
if (!k) return NULL;
gs->keys = k;
gs->capacity = cap;
}
glyph_sprite_map_itr si = vt_insert(&fg->glyph_sprite_positions, key, (GlyphSpriteValue){0});
if (vt_is_end(si)) return NULL;
gs->keys[gs->count++] = key;
return &si.data->val;
}
static size_t
num_glyph_sprite_entries(FontGroup *fg, uint64_t hash) {
glyph_sprites_map_itr it = vt_get(&fg->glyph_sprites, hash);
return vt_is_end(it) ? 0 : it.data->val->count;
}
// Render the glyph registered for the codepoint of cpu_cell into num_cols
// cells, the glyph being rendered into an area of glyph_width scaled cells
static void
render_registered_glyph(FontGroup *fg, RunFont rf, CPUCell *cpu_cell, GPUCell *gpu_cells, unsigned num_cols, unsigned glyph_width, const TextCache *tc) {
#define failed \
{ \
if (PyErr_Occurred()) PyErr_Print(); \
for (unsigned i = 0; i < num_cols; i++) gpu_cells[i].sprite_idx = MISSING_GLYPH; \
return; \
}
const VGGlyph *g = cell_registered_glyph(cpu_cell, tc);
GlyphRegistry *owner = tc_glyph_registry(tc);
if (!g || num_cols > UINT8_MAX) failed;
const uint8_t subscale = ((rf.subscale_n & 0xf) << 4) | (rf.subscale_d & 0xf);
GlyphSpriteKey keys[UINT8_MAX];
GlyphSpriteValue *values[UINT8_MAX];
unsigned num_missing = 0;
for (unsigned i = 0; i < num_cols; i++) {
keys[i] = (GlyphSpriteKey){
.hash = g->content_hash,
.col = i,
.num_cols = num_cols,
.scale = rf.scale,
.subscale = subscale,
.multicell_y = rf.multicell_y,
.align = rf.align.val};
glyph_sprite_map_itr si = vt_get(&fg->glyph_sprite_positions, keys[i]);
values[i] = vt_is_end(si) ? NULL : &si.data->val;
if (!values[i]) num_missing++;
}
if (!num_missing) {
for (unsigned i = 0; i < num_cols; i++) set_cell_sprite(gpu_cells + i, &values[i]->sp);
return;
}
// Bound the sprites a glyph, a window and all windows can use, before creating anything
const char *limit = NULL;
if (num_glyph_sprite_entries(fg, g->content_hash) + num_missing > MAX_GLYPH_PROTOCOL_ENTRIES_PER_GLYPH) limit = "glyph";
else if (owner->sprite_slots + 2 * num_missing > MAX_GLYPH_PROTOCOL_SPRITES_PER_WINDOW) limit = "window";
else if (fg->glyph_protocol_sprite_count + 2 * num_missing > MAX_GLYPH_PROTOCOL_SPRITES) limit = "all windows";
if (limit) {
static monotonic_t last_warned = 0;
const monotonic_t now = monotonic();
if (!last_warned || now - last_warned > s_double_to_monotonic_t(60.0)) {
log_error("Too many sprites used by glyphs registered with the glyph protocol in %s, not rendering more of them", limit);
last_warned = now;
}
failed;
}
// The values are stored in a hash map, so insertions can invalidate pointers to them
for (unsigned i = 0; i < num_cols; i++) {
if (!values[i] && !create_glyph_sprite(fg, keys[i])) {
PyErr_NoMemory();
failed;
}
}
for (unsigned i = 0; i < num_cols; i++) {
glyph_sprite_map_itr si = vt_get(&fg->glyph_sprite_positions, keys[i]);
if (vt_is_end(si)) failed;
values[i] = &si.data->val;
}
#define sp(i) (&values[i]->sp)
const FontCellMetrics unscaled_metrics = fg->fcm;
const float scale = apply_scale_to_font_group(fg, &rf);
const FontCellMetrics scaled_metrics = fg->fcm;
if (scale != 1) apply_scale_to_font_group(fg, NULL);
ensure_canvas_can_fit(fg, num_cols + 1, rf.scale);
const unsigned glyph_w = scaled_metrics.cell_width * glyph_width, glyph_h = scaled_metrics.cell_height;
const unsigned full_width = unscaled_metrics.cell_width * num_cols;
unsigned right_shift = 0;
if (rf.subscale_n && rf.subscale_d && rf.align.horizontal && glyph_w < full_width) {
right_shift = full_width - glyph_w;
if (rf.align.horizontal == 2) right_shift /= 2;
}
const unsigned stride = MAX(glyph_w + right_shift, full_width);
VGRender r;
switch (vg_render(g, glyph_w, glyph_h, &r)) {
case VG_RENDER_OK: break;
case VG_RENDER_OUT_OF_MEMORY: PyErr_NoMemory(); failed;
case VG_RENDER_TOO_COMPLEX:
// Remember the failure so the glyph is not rendered again
for (unsigned i = 0; i < num_cols; i++) {
if (!values[i]->sp.rendered) {
values[i]->sp = (SpritePosition){.idx = MISSING_GLYPH, .rendered = true};
values[i]->num_slots = 0;
}
set_cell_sprite(gpu_cells + i, &values[i]->sp);
}
return;
}
const bool fg_mix = r.color && r.fg;
RAII_ALLOC(pixel, fg_buf, fg_mix ? calloc(1, fg->canvas.size_in_bytes) : NULL);
if (fg_mix && !fg_buf) {
vg_render_free(&r);
PyErr_NoMemory();
failed;
}
copy_registered_glyph_to_canvas(&r, fg->canvas.buf, fg_buf, stride, right_shift);
const bool colored = r.color != NULL;
vg_render_free(&r);
Region src = {.right = stride, .bottom = glyph_h}, dest = src;
dest.right = full_width;
calculate_regions_for_line(rf, unscaled_metrics.cell_height, &src, &dest);
const DecorationMetadata dm = index_for_decorations(fg, rf, src, dest, scaled_metrics);
Canvas fg_canvas = {.buf = fg_buf, .size_in_bytes = fg->canvas.size_in_bytes};
for (unsigned i = 0; i < num_cols; i++) {
if (!sp(i)->rendered) {
// The foreground weight sprite of a glyph with foreground mixing
// must be in the same row of the sprite map, directly to the right
const sprite_index idx = alloc_glyph_sprite_slot(fg, fg_mix);
if (!idx) failed;
Region s = src;
pixel *b = extract_cell_region(&fg->canvas, i, &s, &dest, stride, unscaled_metrics);
upload_sprite(fg, idx, b, dm, scaled_metrics);
if (fg_mix) {
s = src;
b = extract_cell_region(&fg_canvas, i, &s, &dest, stride, unscaled_metrics);
upload_sprite(fg, idx + 1, b, (DecorationMetadata){0}, scaled_metrics);
}
fg->glyph_protocol_sprite_count += fg_mix ? 2 : 1;
owner->sprite_slots += fg_mix ? 2 : 1;
values[i]->owner = owner->id;
values[i]->num_slots = fg_mix ? 2 : 1;
sp(i)->idx = idx;
sp(i)->rendered = true;
sp(i)->colored = colored;
sp(i)->fg_mix = fg_mix;
}
set_cell_sprite(gpu_cells + i, sp(i));
}
#undef sp
#undef failed
}
// }}}
static void
load_hb_buffer(CPUCell *first_cpu_cell, index_type num_cells, const TextCache *tc, ListOfChars *lc) {
size_t num = 0;
@ -2197,6 +2557,23 @@ render_run(
first_gpu_cell += rf.scale;
}
break;
case GLYPH_FONT:
if (pua_space_ligature) {
// A registered glyph followed by spaces, rendered across all the cells
render_registered_glyph(fg, rf, first_cpu_cell, first_gpu_cell, num_cells, num_cells, tc);
break;
}
while (num_cells) {
// Never write past the end of the run, even for a multicell
// char that is cut off
const unsigned cols = MIN(num_cells, MAX(1u, first_cpu_cell->is_multicell ? mcd_x_limit(first_cpu_cell) : 1u));
const unsigned glyph_width = first_cpu_cell->is_multicell ? first_cpu_cell->width : 1;
render_registered_glyph(fg, rf, first_cpu_cell, first_gpu_cell, cols, MAX(1u, glyph_width), tc);
num_cells -= cols;
first_cpu_cell += cols;
first_gpu_cell += cols;
}
break;
case MISSING_FONT:
while (num_cells--) {
first_gpu_cell->sprite_idx = MISSING_GLYPH;
@ -2295,7 +2672,15 @@ render_line(FONTS_DATA_HANDLE fg_, Line *line, index_type lnum, Cursor *cursor,
if (cell_font.font_idx != MISSING_FONT && ((!is_main_font && !is_emoji_presentation && cp.is_symbol) ||
(cell_font.font_idx != BOX_FONT && (is_private_use(cp))) || is_non_emoji_dingbat(first_ch, cp))) {
unsigned int desired_cells = 1;
if (cell_font.font_idx > 0) {
if (cell_font.font_idx == GLYPH_FONT) {
// The width of the viewBox when it fits the height of the cell
const VGGlyph *g = cell_registered_glyph(cpu_cell, line->text_cache);
if (g) {
const double w = (double)g->placement.vb[2] / g->placement.vb[3] * fg->fcm.cell_height;
// Clamped before conversion, the number of cells is limited below in any case
desired_cells = (unsigned int)MAX(1., MIN(256., ceil(w / fg->fcm.cell_width - 0.001)));
}
} else if (cell_font.font_idx > 0) {
Font *font = (fg->fonts + cell_font.font_idx);
glyph_index glyph_id = glyph_id_for_codepoint(font->face, first_ch);
@ -2487,6 +2872,11 @@ initialize_font_group(FontGroup *fg) {
vt_init(&fg->fallback_font_map);
vt_init(&fg->scaled_font_map);
vt_init(&fg->decorations_index_map);
vt_init(&fg->glyph_sprites);
vt_init(&fg->glyph_sprite_positions);
zero_at_ptr(&fg->single_holes);
zero_at_ptr(&fg->pair_holes);
fg->glyph_protocol_sprite_count = 0;
#define I(attr) \
if (descriptor_indices.attr) fg->attr##_font_idx = initialize_font(fg, descriptor_indices.attr, #attr); \
else fg->attr##_font_idx = -1;
@ -2908,6 +3298,16 @@ set_allow_use_of_box_fonts(PyObject *self UNUSED, PyObject *val) {
Py_RETURN_NONE;
}
static PyObject *
set_glyph_protocol_sprite_limits(PyObject *self UNUSED, PyObject *args) {
size_t total = 65536u, per_window = 16384u, per_glyph = 1024u;
if (!PyArg_ParseTuple(args, "|nnn", &total, &per_window, &per_glyph)) return NULL;
MAX_GLYPH_PROTOCOL_SPRITES = total;
MAX_GLYPH_PROTOCOL_SPRITES_PER_WINDOW = per_window;
MAX_GLYPH_PROTOCOL_ENTRIES_PER_GLYPH = per_glyph;
Py_RETURN_NONE;
}
static PyObject *
sprite_idx_to_pos(PyObject *self UNUSED, PyObject *args) {
unsigned x, y, z, idx, xnum, ynum;
@ -2932,6 +3332,7 @@ pyrender_box_char(PyObject *self UNUSED, PyObject *args) {
static PyMethodDef module_methods[] = {
METHODB(set_font_data, METH_VARARGS),
METHODB(sprite_idx_to_pos, METH_VARARGS),
METHODB(set_glyph_protocol_sprite_limits, METH_VARARGS),
METHODB(free_font_data, METH_NOARGS),
METHODB(create_test_font_group, METH_VARARGS),
METHODB(sprite_map_set_layout, METH_VARARGS),
@ -2952,6 +3353,7 @@ static PyMethodDef module_methods[] = {
bool
init_fonts(PyObject *module) {
vg_set_free_callback(on_vector_glyph_freed);
harfbuzz_buffer = hb_buffer_create();
if (harfbuzz_buffer == NULL || !hb_buffer_allocation_successful(harfbuzz_buffer) || !hb_buffer_pre_allocate(harfbuzz_buffer, 2048)) {
PyErr_NoMemory();

View file

@ -13,12 +13,20 @@ typedef union SpritePosition {
sprite_index idx : sizeof(sprite_index) * 8;
bool rendered : 1;
bool colored : 1;
uint32_t : 30;
// A colored sprite that is followed by a sprite with the weight of
// the foreground color, see vector-glyph-render.c
bool fg_mix : 1;
uint32_t : 29;
};
uint64_t val;
} SpritePosition;
static_assert(sizeof(SpritePosition) == sizeof(uint64_t), "Fix ordering of SpritePosition");
// Flags in the sprite index of a cell, must match cell.slang
#define SPRITE_INDEX_MASK 0x3fffffffu
#define SPRITE_FG_MIX_FLAG 0x40000000u
#define SPRITE_COLORED_FLAG 0x80000000u
typedef struct {
int x;
} *SPRITE_POSITION_MAP_HANDLE;

View file

@ -744,7 +744,7 @@ add_combining_char(Line *self, PyObject *args) {
text_in_cell(cell, self->text_cache, &lc);
ensure_space_for_chars(&lc, lc.count + 1);
lc.chars[lc.count++] = new_char;
cell->ch_or_idx = tc_get_or_insert_chars(self->text_cache, &lc);
cell->ch_or_idx = tc_get_or_insert_chars_with_glyph(self->text_cache, &lc, cell_registered_glyph(cell, self->text_cache));
cell->ch_is_idx = true;
Py_RETURN_NONE;
}

View file

@ -226,6 +226,12 @@ cell_set_chars(CPUCell *c, TextCache *tc, const ListOfChars *lc) {
}
}
// The glyph registered with the glyph protocol bound to the cell when its text was printed
static inline struct VGGlyph *
cell_registered_glyph(const CPUCell *c, const TextCache *tc) {
return c->ch_is_idx ? tc_glyph_at_index(tc, c->ch_or_idx) : NULL;
}
static inline char_type
cell_first_char(const CPUCell *c, const TextCache *tc) {
if (c->ch_is_idx) {

View file

@ -281,7 +281,12 @@ do_screen_reset(Screen *self, bool is_hard_reset) {
screen_cursor_position(self, 1, 1);
set_dynamic_color(self, 111, NULL); // does default_bg_changed processing
colorprofile_reset(self->color_profile);
if (is_hard_reset) reset_style_table_if_unused(self);
if (is_hard_reset) {
reset_style_table_if_unused(self);
// Release glyphs registered with the glyph protocol that were bound
// to cells that no longer exist
if (vg_live_glyph_memory()) screen_garbage_collect_text_cache(self);
}
CALLBACK("on_reset", "O", is_hard_reset ? Py_True : Py_False);
}
@ -1313,6 +1318,8 @@ screen_garbage_collect_text_cache(Screen *self) {
tc_gc_end(self->text_cache, gc);
// the GC remaps all cache indices so the memoized tab indices are stale
memset(&self->tab_cache, 0, sizeof(self->tab_cache));
GlyphRegistry *gr = tc_glyph_registry(self->text_cache);
memset(gr->bound_idx_plus_1, 0, sizeof(gr->bound_idx_plus_1));
}
static void
@ -1406,6 +1413,28 @@ screen_garbage_collect_style_table(Screen *self) {
}
}
// Glyph protocol print time binding: a cell with a codepoint from the
// registration block that has a registered glyph stores the glyph in its text
// cache entry, so that later changes to the registration do not affect it
static void
bind_registered_glyph(Screen *self, CPUCell *c, char_type first_char) {
GlyphRegistry *r = tc_glyph_registry(self->text_cache);
VGGlyph *g = glyph_registry_get(r, first_char);
if (!g) return;
const unsigned slot = first_char - GLYPH_BLOCK_FIRST;
if (!c->ch_is_idx && r->bound_idx_plus_1[slot]) {
// The common case of a cell with just the codepoint
c->ch_or_idx = r->bound_idx_plus_1[slot] - 1;
c->ch_is_idx = true;
return;
}
RAII_ListOfChars(lc);
text_in_cell(c, self->text_cache, &lc);
c->ch_or_idx = tc_get_or_insert_chars_with_glyph(self->text_cache, &lc, g);
c->ch_is_idx = true;
if (lc.count == 1) r->bound_idx_plus_1[slot] = c->ch_or_idx + 1;
}
static bool
add_combining_chars(Screen *self, const char_type *chars, size_t num_chars, index_type x, index_type y) {
// Adds num_chars combining chars to the cell at x, y with a single lookup in the text cache
@ -1420,7 +1449,8 @@ add_combining_chars(Screen *self, const char_type *chars, size_t num_chars, inde
ensure_space_for_chars(self->lc, self->lc->count + num_chars);
memcpy(self->lc->chars + self->lc->count, chars, num_chars * sizeof(chars[0]));
self->lc->count += num_chars;
cell->ch_or_idx = tc_get_or_insert_chars(self->text_cache, self->lc);
// A glyph bound to the cell when it was printed stays bound
cell->ch_or_idx = tc_get_or_insert_chars_with_glyph(self->text_cache, self->lc, cell_registered_glyph(cell, self->text_cache));
cell->ch_is_idx = true;
if (cell->is_multicell) {
char_type ch_and_idx = cell->ch_and_idx;
@ -1794,8 +1824,8 @@ draw_non_ascii_run(Screen *self, text_loop_state *s, const uint32_t *chars, size
// of width one or two in the current line, keeping all state in locals so it is
// not reloaded for every char. Stops at the first char needing the scalar path:
// ASCII, invalid, zero width, a char that combines with the previous cell, the
// image placeholder, a char that does not fit in the line or an existing multicell
// cell. The caller must ensure there is no charset translation or insert mode and
// image placeholder, a glyph protocol codepoint, a char that does not fit in the
// line or an existing multicell cell. The caller must ensure there is no charset translation or insert mode and
// that the cursor is within the line. Returns the number of chars drawn.
const index_type columns = self->columns;
index_type x = self->cursor->x, last_x = x;
@ -1818,7 +1848,7 @@ draw_non_ascii_run(Screen *self, text_loop_state *s, const uint32_t *chars, size
size_t i = 0;
for (; i < num_chars; i++) {
const char_type ch = chars[i];
if (ch < DEL || ch == IMAGE_PLACEHOLDER_CHAR) break;
if (ch < DEL || ch == IMAGE_PLACEHOLDER_CHAR || is_glyph_block_codepoint(ch)) break;
const CharDrawInfo info = char_draw_info_for(ch);
const index_type width = info.cells;
if (width == 0 || x + width > columns || cp[x].is_multicell) break;
@ -2006,6 +2036,7 @@ draw_text_loop(Screen *self, const uint32_t *chars, size_t num_chars, text_loop_
} else {
*fc = s->cc;
cell_set_char(fc, ch);
if (UNLIKELY(is_glyph_block_codepoint(ch))) bind_registered_glyph(self, fc, ch);
s->prev.y = self->cursor->y;
s->prev.x = self->cursor->x;
s->prev.cc = fc;
@ -2093,6 +2124,7 @@ handle_fixed_width_multicell_command(Screen *self, CPUCell mcd, ListOfChars *lc)
mcd.hyperlink_id = s.cc.hyperlink_id;
mcd.style_idx = s.cc.style_idx;
cell_set_chars(&mcd, self->text_cache, lc);
if (lc->count && is_glyph_block_codepoint(lc->chars[0])) bind_registered_glyph(self, &mcd, lc->chars[0]);
move_cursor_past_multicell(self, width);
if (height > 1) {
if (self->cursor->y <= self->margin_bottom) {
@ -2466,7 +2498,7 @@ screen_handle_graphics_command(Screen *self, const GraphicsCommand *cmd, const u
// Glyph protocol {{{
// The payload formats kitty supports, advertised in the reply to the s verb
#define GLYPH_SUPPORTED_FORMATS ""
#define GLYPH_SUPPORTED_FORMATS "vg"
static bool
glyph_is_registered(Screen *self, char_type cp) {
@ -2533,6 +2565,28 @@ glyph_reply_status(Screen *self, const GlyphCommand *cmd, const char *reason) {
else glyph_reply(self, GLYPH_PROTOCOL_PREFIX "%c;%sstatus=0", cmd->verb, cp);
}
// Whether the glyphs kept alive by this window are within the per window limits
static bool
glyph_window_within_limits(Screen *self, const VGGlyph *new_glyph) {
const GlyphRegistry *r = tc_glyph_registry(self->text_cache);
size_t count, memory;
#define within \
(tc_bound_glyph_usage(self->text_cache, &count, &memory), \
count + r->num_registered + 1 <= vg_window_glyph_limit && memory + r->memory + new_glyph->memory_size <= vg_window_memory_limit)
if (within) return true;
// Text that used glyphs may have been erased or scrolled out of the
// scrollback, garbage collect to release its glyphs. At most once a
// second, as it is expensive with a large scrollback.
const monotonic_t now = monotonic();
if (tc_has_adds_since_last_gc(self->text_cache) && (!self->last_glyph_limit_gc_at || now - self->last_glyph_limit_gc_at > s_double_to_monotonic_t(1.0))) {
self->last_glyph_limit_gc_at = now;
screen_garbage_collect_text_cache(self);
return within;
}
#undef within
return false;
}
static const char *
glyph_register(Screen *self, const GlyphCommand *cmd, const uint8_t *buf) {
if (!cmd->has_cp || !cmd->cp_valid || !is_glyph_block_codepoint(cmd->cp)) return "out_of_namespace";
@ -2551,10 +2605,16 @@ glyph_register(Screen *self, const GlyphCommand *cmd, const uint8_t *buf) {
}
return "malformed_payload";
}
const bool ok = glyph_registry_set(tc_glyph_registry(self->text_cache), cmd->cp, g);
// A new glyph that takes the memory used by all glyphs over the budget
// is rejected, registering a glyph that already exists uses no memory
// Checked regardless of whether the glyph already exists, so that the
// result does not reveal whether other windows use it
if (vg_live_glyph_memory() > VG_MEMORY_BUDGET || !glyph_window_within_limits(self, g)) {
vg_decref(g);
return "no_space";
}
glyph_registry_set(tc_glyph_registry(self->text_cache), cmd->cp, g);
vg_decref(g);
if (!ok) return "no_space";
self->is_dirty = true;
return NULL;
}
@ -4555,6 +4615,9 @@ screen_pause_rendering(Screen *self, bool pause, int for_in_ms) {
// free extra cursors
free(self->paused_rendering.extra_cursors.locations);
zero_at_ptr(&self->paused_rendering.extra_cursors);
// The snapshot is kept for reuse, but its text must not keep text
// cache entries, and the glyph protocol glyphs they hold, alive
if (self->paused_rendering.linebuf) linebuf_clear(self->paused_rendering.linebuf, BLANK_CHAR);
return true;
}
if (self->paused_rendering.expires_at) return false;

View file

@ -142,6 +142,8 @@ typedef struct {
CursorRenderInfo cursor;
} last_rendered;
bool is_dirty, scroll_changed, reload_all_gpu_data, sgr_blink_was_used;
// When the text cache was last garbage collected to stay within the glyph protocol limits
monotonic_t last_glyph_limit_gc_at;
// set once a multiline (scale > 1) char has been drawn, used to skip scanning for such chars in hot paths
bool multiline_chars_used;
// set when multiline chars may be cut off at the bottom of the main ([0]) or

View file

@ -26,13 +26,21 @@ static const bool ONLY_BACKGROUND = RENDER_MODE == 1;
[[vk::binding(2)]]
uniform Sampler2D<uint> sprite_decorations_map; // a single channel R32UI texture // binding slots: see SHADER_BINDING_SLOTS in slang.py
static const uint SPRITE_INDEX_MASK = 0x7fffffff;
// Must match SPRITE_INDEX_MASK and the flags in glyph-cache.h
static const uint SPRITE_INDEX_MASK = 0x3fffffff;
static const uint SPRITE_COLORED_MASK = 0x80000000;
static const uint SPRITE_COLORED_SHIFT = 31u;
// A colored sprite whose color is to be combined with the foreground color
// weighted by the alpha of the sprite to its right in the sprite map, used for
// glyphs registered with the glyph protocol, see vector-glyph-render.c
static const uint SPRITE_FG_MIX_MASK = 0x40000000;
// Set in underline_exclusion_pos when the glyph, decorations, and cursor sprite
// are all 0. The block cursor is sprite 0 and its color is already in the
// background. Packed into an existing flat varying to not use another slot.
static const uint SKIP_TEXT_FLAG = 0x80000000u;
// Set in underline_exclusion_pos when the sprite has SPRITE_FG_MIX_MASK set
static const uint FG_MIX_FLAG = SPRITE_FG_MIX_MASK;
static const uint UNDERLINE_EXCLUSION_POS_MASK = ~(SKIP_TEXT_FLAG | FG_MIX_FLAG);
// The uniform parameters of the program, shared by all its stages. See
// PUSH_CONSTANTS_MAX_SIZE in slang.py for why they are declared this way.
@ -85,7 +93,7 @@ to_sprite_pos(uint2 pos, uint idx) {
uint
to_underline_exclusion_pos(uint2 sprite_idx) {
uint3 c = to_sprite_coords(sprite_idx[0]);
uint3 c = to_sprite_coords(sprite_idx[0] & SPRITE_INDEX_MASK);
uint cell_top_px = c.y * (crd.cell_height + 1u);
return cell_top_px + crd.cell_height;
}
@ -197,7 +205,7 @@ vertex_main([[vk::location(0)]] uint2 cell_input, [[vk::location(2)]] uint is_se
uint cursor_sprite = cell_data.cursor_fg_sprite_idx * uint(cell_data.has_cursor);
vo.cursor_pos = to_sprite_pos(cell_data.pos, cursor_sprite);
uint skip_text = uint((sprite_idx[0] & SPRITE_INDEX_MASK) == 0u && decs[0] == 0u && decs[1] == 0u && cursor_sprite == 0u);
vo.underline_exclusion_pos = to_underline_exclusion_pos(sprite_idx) | (skip_text * SKIP_TEXT_FLAG);
vo.underline_exclusion_pos = to_underline_exclusion_pos(sprite_idx) | (skip_text * SKIP_TEXT_FLAG) | (sprite_idx[0] & SPRITE_FG_MIX_MASK);
}
// }}}
@ -268,11 +276,17 @@ foreground_contrast(float4 over, float3 under, float text_contrast, float text_g
}
float4
load_text_foreground_color(float3 sprite_pos, float colored_sprite, float3 cell_foreground) {
load_text_foreground_color(float3 sprite_pos, float colored_sprite, float3 cell_foreground, uint underline_exclusion_pos) {
// For colored sprites use the color from the sprite rather than the text foreground
// Return non-premultiplied foreground color
float4 text_fg = sprites.SampleLevel(sprite_pos, 0);
return float4(lerp(cell_foreground, text_fg.xyz, colored_sprite), text_fg.w);
float3 rgb = lerp(cell_foreground, text_fg.xyz, colored_sprite);
if ((underline_exclusion_pos & FG_MIX_FLAG) != 0u) {
// The sprite to the right has the weight of the foreground color, relative to the alpha
float fg_weight = sprites.SampleLevel(sprite_pos + float3(1.0f / float(crd.sprites_xnum), 0.0f, 0.0f), 0).w;
rgb += cell_foreground * fg_weight;
}
return float4(rgb, text_fg.w);
}
float4
@ -290,7 +304,7 @@ calculate_premul_foreground_from_sprites(
float3 sz = float3(texture_size(sprites));
float underline_alpha = sprites.SampleLevel(underline_pos, 0).w;
int3 fetch_coord = int3(int(sprite_pos.x * sz.x), int(underline_exclusion_pos), int(sprite_pos.z));
int3 fetch_coord = int3(int(sprite_pos.x * sz.x), int(underline_exclusion_pos & UNDERLINE_EXCLUSION_POS_MASK), int(sprite_pos.z));
float underline_exclusion = texel_fetch(sprites, fetch_coord).w;
underline_alpha *= 1.0 - underline_exclusion;
@ -321,7 +335,7 @@ fragment_main(VertexOutput vo)
// be undefined. The sprites texture has no mipmaps, so LOD 0 is identical.
if (!ONLY_BACKGROUND && (vo.underline_exclusion_pos & SKIP_TEXT_FLAG) == 0u) {
// blend in the foreground color
float4 text_fg = load_text_foreground_color(vo.sprite_pos, vo.colored_sprite, vo.cell_foreground);
float4 text_fg = load_text_foreground_color(vo.sprite_pos, vo.colored_sprite, vo.cell_foreground, vo.underline_exclusion_pos);
text_fg = adjust_foreground_contrast_with_background(text_fg, vo.background, uniforms.text_contrast, uniforms.text_gamma_adjustment);
float4 text_fg_premul = calculate_premul_foreground_from_sprites(
vo.sprite_pos,

View file

@ -809,7 +809,8 @@ extern GlobalState global_state;
static inline void
sprite_index_to_pos(unsigned idx, unsigned xnum, unsigned ynum, unsigned *x, unsigned *y, unsigned *z) {
div_t r = div(idx & 0x7fffffff, ynum * xnum), r2 = div(r.rem, xnum);
// The two high bits are flags, see SPRITE_INDEX_MASK
div_t r = div(idx & 0x3fffffff, ynum * xnum), r2 = div(r.rem, xnum);
*z = r.quot;
*y = r2.quot;
*x = r2.rem;

View file

@ -14,6 +14,14 @@ typedef struct Chars {
} Chars;
static_assert(sizeof(Chars) == sizeof(void *) + sizeof(size_t), "reorder Chars");
// Entries bound to a glyph registered with the glyph protocol are rare, so
// they are kept out of the main map, to not slow down the common case. They
// are interned in a separate map, keyed by their text and glyph.
typedef struct BoundChars {
Chars text;
VGGlyph *glyph;
} BoundChars;
#define NAME chars_map
#define KEY_TY Chars
#define VAL_TY char_type
@ -23,6 +31,15 @@ static bool cmpr_chars(Chars a, Chars b);
#define CMPR_FN cmpr_chars
#include "kitty-verstable.h"
#define NAME bound_chars_map
#define KEY_TY BoundChars
#define VAL_TY char_type
static uint64_t hash_bound_chars(BoundChars k);
static bool cmpr_bound_chars(BoundChars a, BoundChars b);
#define HASH_FN hash_bound_chars
#define CMPR_FN cmpr_bound_chars
#include "kitty-verstable.h"
#define MA_NAME Chars
#define MA_BLOCK_SIZE 16u
#define MA_ARENA_NUM_BLOCKS 128u
@ -40,6 +57,15 @@ typedef struct TextCache {
unsigned adds_since_last_gc, adds_between_gcs;
CellStyleTable *style_table;
GlyphRegistry *glyph_registry;
// Parallel to array.items, the glyph bound to each entry, NULL until the
// first entry is bound. Entries own a reference to their glyph.
struct {
VGGlyph **items;
size_t capacity;
} glyphs;
bound_chars_map bound_map;
// The number of entries bound to glyphs and the memory of those glyphs
size_t bound_count, bound_memory;
} TextCache;
static uint64_t
hash_chars(Chars k) {
@ -49,6 +75,20 @@ static bool
cmpr_chars(Chars a, Chars b) {
return a.count == b.count && memcmp(a.chars, b.chars, sizeof(a.chars[0]) * a.count) == 0;
}
static uint64_t
hash_bound_chars(BoundChars k) {
return hash_chars(k.text) ^ ((uint64_t)(uintptr_t)k.glyph * 0x9E3779B97F4A7C15ull);
}
static bool
cmpr_bound_chars(BoundChars a, BoundChars b) {
return a.glyph == b.glyph && cmpr_chars(a.text, b.text);
}
static void
release_glyphs(VGGlyph **items, size_t count) {
if (items)
for (size_t i = 0; i < count; i++) items[i] = vg_decref(items[i]);
}
#define TEXT_CACHE_IMPLEMENTATION
#include "text-cache.h"
@ -74,12 +114,16 @@ tc_alloc(void) {
return NULL;
}
vt_init(&ans->map);
vt_init(&ans->bound_map);
ans->refcnt = 1;
return ans;
}
static void
free_text_cache(TextCache *self) {
release_glyphs(self->glyphs.items, MIN(self->glyphs.capacity, self->array.count));
free(self->glyphs.items);
vt_cleanup(&self->bound_map);
vt_cleanup(&self->map);
Chars_free_all(&self->arena);
free(self->array.items);
@ -169,7 +213,7 @@ tc_chars_at_index_ansi(const TextCache *self, char_type idx, ANSIBuf *output) {
}
static char_type
copy_and_insert(TextCache *self, const Chars key) {
copy_and_insert(TextCache *self, const Chars key, VGGlyph *glyph) {
if (self->array.count > MAX_CHAR_TYPE_VALUE) fatal("Too many items in TextCache");
ensure_space_for(&(self->array), items, Chars, self->array.count + 1, capacity, 256, false);
char_type *copy = Chars_get(&self->arena, key.count * sizeof(key.chars[0]));
@ -179,20 +223,64 @@ copy_and_insert(TextCache *self, const Chars key) {
Chars *k = self->array.items + self->array.count++;
k->count = key.count;
k->chars = copy;
chars_map_itr i = vt_insert(&self->map, *k, ans);
if (vt_is_end(i)) fatal("Out of memory");
if (glyph) {
if (self->glyphs.capacity <= ans) {
const size_t cap = MAX(self->array.capacity, (size_t)ans + 1);
VGGlyph **g = realloc(self->glyphs.items, cap * sizeof(g[0]));
if (!g) fatal("Out of memory");
memset(g + self->glyphs.capacity, 0, (cap - self->glyphs.capacity) * sizeof(g[0]));
self->glyphs.items = g;
self->glyphs.capacity = cap;
}
self->glyphs.items[ans] = vg_incref(glyph);
self->bound_count++;
self->bound_memory += glyph->memory_size;
if (vt_is_end(vt_insert(&self->bound_map, ((BoundChars){.text = *k, .glyph = glyph}), ans))) fatal("Out of memory");
} else if (vt_is_end(vt_insert(&self->map, *k, ans))) fatal("Out of memory");
return ans;
}
VGGlyph *
tc_glyph_at_index(const TextCache *self, char_type idx) {
return idx < self->glyphs.capacity ? self->glyphs.items[idx] : NULL;
}
static char_type
get_or_insert(TextCache *self, Chars key, VGGlyph *glyph, bool *added) {
*added = false;
if (glyph) {
bound_chars_map_itr i = vt_get(&self->bound_map, ((BoundChars){.text = key, .glyph = glyph}));
if (!vt_is_end(i)) return i.data->val;
} else {
chars_map_itr i = vt_get(&self->map, key);
if (!vt_is_end(i)) return i.data->val;
}
*added = true;
return copy_and_insert(self, key, glyph);
}
char_type
tc_get_or_insert_chars(TextCache *self, const ListOfChars *chars) {
Chars key = {.count = chars->count, .chars = chars->chars};
chars_map_itr i = vt_get(&self->map, key);
if (vt_is_end(i)) {
self->adds_since_last_gc++;
return copy_and_insert(self, key);
}
return i.data->val;
return tc_get_or_insert_chars_with_glyph(self, chars, NULL);
}
char_type
tc_get_or_insert_chars_with_glyph(TextCache *self, const ListOfChars *chars, VGGlyph *glyph) {
bool added;
const char_type ans = get_or_insert(self, (Chars){.count = chars->count, .chars = chars->chars}, glyph, &added);
if (added) self->adds_since_last_gc++;
return ans;
}
void
tc_bound_glyph_usage(const TextCache *self, size_t *count, size_t *memory) {
*count = self->bound_count;
*memory = self->bound_memory;
}
bool
tc_has_adds_since_last_gc(const TextCache *self) {
return self->adds_since_last_gc > 0;
}
char_type
@ -219,6 +307,8 @@ tc_should_gc(const TextCache *self) {
struct TextCacheGCData {
Chars *old_items;
char_type old_count;
VGGlyph **old_glyphs;
size_t old_glyphs_capacity;
CharsMonotonicArena old_arena;
// old index -> new index + 1, 0 means not yet remapped
char_type *map;
@ -243,6 +333,14 @@ tc_gc_begin(TextCache *self) {
self->array.capacity = 256;
self->array.count = 0;
zero_at_ptr(&self->arena);
gc->old_glyphs = self->glyphs.items;
gc->old_glyphs_capacity = self->glyphs.capacity;
zero_at_ptr(&self->glyphs);
// Recomputed as the live entries are re-inserted
self->bound_count = 0;
self->bound_memory = 0;
vt_cleanup(&self->bound_map);
vt_init(&self->bound_map);
vt_cleanup(&self->map);
vt_init(&self->map);
// Avoid rehashing repeatedly as the live entries are re-inserted, the live
@ -256,9 +354,9 @@ bool
tc_gc_map_index(TextCache *self, TextCacheGCData *gc, char_type old_idx, char_type *new_idx) {
if (old_idx >= gc->old_count) return false;
if (!gc->map[old_idx]) {
Chars key = gc->old_items[old_idx];
chars_map_itr i = vt_get(&self->map, key);
char_type nidx = vt_is_end(i) ? copy_and_insert(self, key) : i.data->val;
VGGlyph *glyph = old_idx < gc->old_glyphs_capacity ? gc->old_glyphs[old_idx] : NULL;
bool added;
const char_type nidx = get_or_insert(self, gc->old_items[old_idx], glyph, &added);
gc->map[old_idx] = nidx + 1;
}
*new_idx = gc->map[old_idx] - 1;
@ -275,6 +373,9 @@ tc_gc_end(TextCache *self, TextCacheGCData *gc) {
// is harmless, the map grows as needed.
(void)vt_reserve(&self->map, self->array.count + MAX(TEXT_CACHE_ADDS_BETWEEN_GCS, self->array.count));
free(gc->map);
// The entries that are still referenced hold their own reference to their glyph
release_glyphs(gc->old_glyphs, MIN(gc->old_glyphs_capacity, gc->old_count));
free(gc->old_glyphs);
free(gc->old_items);
Chars_free_all(&gc->old_arena);
free(gc);

View file

@ -66,6 +66,16 @@ TextCache *tc_decref(TextCache *self);
void tc_chars_at_index(const TextCache *self, char_type idx, ListOfChars *ans);
unsigned tc_chars_at_index_ansi(const TextCache *self, char_type idx, ANSIBuf *output);
char_type tc_get_or_insert_chars(TextCache *self, const ListOfChars *chars);
// Glyph protocol print time binding: cells whose text was printed when a
// glyph was registered for its first codepoint store the glyph in their entry,
// which holds a reference to it.
struct VGGlyph;
char_type tc_get_or_insert_chars_with_glyph(TextCache *self, const ListOfChars *chars, struct VGGlyph *glyph);
struct VGGlyph *tc_glyph_at_index(const TextCache *self, char_type idx);
// The number of entries bound to glyphs and the memory used by their glyphs,
// which includes entries no longer used by cells until the next garbage collection
void tc_bound_glyph_usage(const TextCache *self, size_t *count, size_t *memory);
bool tc_has_adds_since_last_gc(const TextCache *self);
char_type tc_num_entries(const TextCache *self);
// Garbage collection: TextCache interns unique cell texts forever, so a

View file

@ -8,7 +8,23 @@
// Parsing of the vg payload format of the glyph protocol, see vector-glyph.h
#include "vector-glyph.h"
#include "cross-platform-random.h"
#include "monotonic.h"
#include <math.h>
#include <xxhash.h>
// Glyphs are interned by the hash of their content, so that registering the
// same glyph again, at any codepoint in any screen, uses the same object
#define NAME glyph_intern_map
#define KEY_TY uint64_t
#define VAL_TY VGGlyph *
#define HASH_FN vt_hash_integer
#define CMPR_FN vt_cmpr_integer
#include "kitty-verstable.h"
static glyph_intern_map interned_glyphs;
static bool interned_glyphs_initialized = false;
// The memory used by all live glyphs, whether registered or bound to cells
static size_t live_glyph_memory = 0;
// Matrices {{{
void
@ -45,11 +61,26 @@ vg_incref(VGGlyph *g) {
return g;
}
static void (*free_callback)(uint64_t content_hash) = NULL;
void
vg_set_free_callback(void (*callback)(uint64_t content_hash)) {
free_callback = callback;
}
static void
vg_free(VGGlyph *g) {
// Only successfully parsed glyphs have a hash and could have been rendered
if (free_callback && g->content_hash) free_callback(g->content_hash);
if (g->interned) {
glyph_intern_map_itr i = vt_get(&interned_glyphs, g->content_hash);
if (!vt_is_end(i) && i.data->val == g) vt_erase_itr(&interned_glyphs, i);
live_glyph_memory -= MIN(live_glyph_memory, g->memory_size);
}
free(g->layers);
free(g->verbs);
free(g->points);
free(g->key);
free(g);
}
@ -699,13 +730,73 @@ parse(Parser *p, const uint8_t *payload, size_t sz) {
return validate_clips(p);
}
// The identity of a glyph: its placement and payload. Placement is serialized
// explicitly to not depend on struct padding. Returns NULL on out of memory.
static uint8_t *
content_key(const uint8_t *payload, size_t sz, const GlyphPlacement *placement, size_t *key_len) {
const int32_t enums[3] = {placement->fit, placement->align_h, placement->align_v};
*key_len = sizeof(placement->vb) + sizeof(enums) + sz;
uint8_t *key = malloc(*key_len);
if (!key) return NULL;
memcpy(key, placement->vb, sizeof(placement->vb));
memcpy(key + sizeof(placement->vb), enums, sizeof(enums));
memcpy(key + sizeof(placement->vb) + sizeof(enums), payload, sz);
return key;
}
// The hash is seeded with a random value so that collisions cannot be
// engineered. Interning compares the full content regardless.
static uint64_t
content_hash(const uint8_t *key, size_t key_len) {
static uint64_t seed = 0;
static bool seeded = false;
if (!seeded) {
if (!secure_random_bytes(&seed, sizeof(seed))) seed = (uint64_t)monotonic() ^ (uint64_t)(uintptr_t)&seed;
seeded = true;
}
const uint64_t ans = XXH3_64bits_withSeed(key, key_len, seed);
// Zero means no hash, see vg_free()
return ans ? ans : 1;
}
size_t
vg_live_glyph_memory(void) {
return live_glyph_memory;
}
VGGlyph *
vg_parse(const uint8_t *payload, size_t sz, const GlyphPlacement *placement, VGError *err, const char **err_msg) {
*err = VG_OUT_OF_MEMORY;
*err_msg = "out of memory";
if (!interned_glyphs_initialized) {
vt_init(&interned_glyphs);
interned_glyphs_initialized = true;
}
size_t key_len;
uint8_t *key = content_key(payload, sz, placement, &key_len);
if (!key) return NULL;
const uint64_t hash = content_hash(key, key_len);
glyph_intern_map_itr existing = vt_get(&interned_glyphs, hash);
if (!vt_is_end(existing)) {
VGGlyph *e = existing.data->val;
const bool same = e->key_len == key_len && memcmp(e->key, key, key_len) == 0;
free(key);
// Different content with the same hash cannot be interned, and the
// hash identifies sprites, so refuse it. Practically impossible with
// a random seed.
if (!same) return NULL;
*err = VG_OK;
*err_msg = NULL;
return vg_incref(e);
}
VGGlyph *g = calloc(1, sizeof(VGGlyph));
if (!g) return NULL;
if (!g) {
free(key);
return NULL;
}
g->refcnt = 1;
g->key = key;
g->key_len = key_len;
g->placement = *placement;
g->layers = malloc(VG_MAX_LAYERS * sizeof(g->layers[0]));
if (!g->layers) return vg_decref(g);
@ -725,30 +816,57 @@ vg_parse(const uint8_t *payload, size_t sz, const GlyphPlacement *placement, VGE
// Release unused space
VGLayer *layers = realloc(g->layers, MAX(1u, g->num_layers) * sizeof(g->layers[0]));
if (layers) g->layers = layers;
g->memory_size =
sizeof(VGGlyph) + g->num_layers * sizeof(g->layers[0]) + p->verbs_capacity * sizeof(g->verbs[0]) + p->points_capacity * 2 * sizeof(g->points[0]);
g->memory_size = sizeof(VGGlyph) + g->num_layers * sizeof(g->layers[0]) + p->verbs_capacity * sizeof(g->verbs[0]) +
p->points_capacity * 2 * sizeof(g->points[0]) + key_len;
// Every glyph must be interned, as sprites are identified by the hash
if (vt_is_end(vt_insert(&interned_glyphs, hash, g))) return vg_decref(g);
g->content_hash = hash;
g->interned = true;
live_glyph_memory += g->memory_size;
*err = VG_OK;
*err_msg = NULL;
return g;
}
// Registrations {{{
static size_t total_registered_memory = 0;
size_t
glyph_registry_total_memory(void) {
return total_registered_memory;
}
#define NAME registry_map
#define KEY_TY uint64_t
#define VAL_TY GlyphRegistry *
#define HASH_FN vt_hash_integer
#define CMPR_FN vt_cmpr_integer
#include "kitty-verstable.h"
static registry_map registries;
static bool registries_initialized = false;
GlyphRegistry *
glyph_registry_alloc(void) {
return calloc(1, sizeof(GlyphRegistry));
static uint64_t id_counter = 0;
if (!registries_initialized) {
vt_init(&registries);
registries_initialized = true;
}
GlyphRegistry *ans = calloc(1, sizeof(GlyphRegistry));
if (!ans) return NULL;
ans->id = ++id_counter;
if (vt_is_end(vt_insert(&registries, ans->id, ans))) {
free(ans);
return NULL;
}
return ans;
}
GlyphRegistry *
glyph_registry_for_id(uint64_t id) {
if (!registries_initialized) return NULL;
registry_map_itr i = vt_get(&registries, id);
return vt_is_end(i) ? NULL : i.data->val;
}
void
glyph_registry_free(GlyphRegistry *self) {
if (self) {
glyph_registry_clear_all(self);
vt_erase(&registries, self->id);
free(self);
}
}
@ -756,25 +874,23 @@ glyph_registry_free(GlyphRegistry *self) {
static void
release(GlyphRegistry *self, unsigned idx) {
VGGlyph *g = self->glyphs[idx];
self->bound_idx_plus_1[idx] = 0;
if (g) {
total_registered_memory -= MIN(total_registered_memory, g->memory_size);
self->memory -= MIN(self->memory, g->memory_size);
self->glyphs[idx] = vg_decref(g);
self->num_registered--;
}
}
bool
void
glyph_registry_set(GlyphRegistry *self, char_type cp, VGGlyph *g) {
const unsigned idx = cp - GLYPH_BLOCK_FIRST;
const VGGlyph *existing = self->glyphs[idx];
const size_t freed = existing ? existing->memory_size : 0;
if (total_registered_memory - MIN(freed, total_registered_memory) + g->memory_size > VG_REGISTRY_MEMORY_BUDGET) return false;
vg_incref(g);
release(self, idx);
self->glyphs[idx] = vg_incref(g);
total_registered_memory += g->memory_size;
self->glyphs[idx] = g;
self->memory += g->memory_size;
self->num_registered++;
self->generation++;
return true;
}
void
@ -789,6 +905,7 @@ glyph_registry_clear(GlyphRegistry *self, char_type cp) {
void
glyph_registry_clear_all(GlyphRegistry *self) {
memset(self->bound_idx_plus_1, 0, sizeof(self->bound_idx_plus_1));
if (!self->num_registered) return;
for (unsigned i = 0; i < GLYPH_BLOCK_SIZE && self->num_registered; i++) release(self, i);
self->generation++;
@ -941,8 +1058,26 @@ py_parse_vg(PyObject *self UNUSED, PyObject *args) {
return ans;
}
static PyObject *
py_vg_live_glyph_memory(PyObject *self UNUSED, PyObject *args UNUSED) {
return PyLong_FromSize_t(live_glyph_memory);
}
size_t vg_window_memory_limit = VG_WINDOW_MEMORY_LIMIT, vg_window_glyph_limit = VG_WINDOW_GLYPH_LIMIT;
static PyObject *
py_vg_set_window_limits(PyObject *self UNUSED, PyObject *args) {
size_t mem = VG_WINDOW_MEMORY_LIMIT, count = VG_WINDOW_GLYPH_LIMIT;
if (!PyArg_ParseTuple(args, "|nn", &mem, &count)) return NULL;
vg_window_memory_limit = mem;
vg_window_glyph_limit = count;
Py_RETURN_NONE;
}
static PyMethodDef methods[] = {
{"parse_vg", py_parse_vg, METH_VARARGS, "Parse a vg payload with the specified viewBox, for testing"},
{"vg_live_glyph_memory", py_vg_live_glyph_memory, METH_NOARGS, "The memory used by all live vector glyphs, for testing"},
{"vg_set_window_limits", py_vg_set_window_limits, METH_VARARGS, "Set the per window limits on glyphs, for testing"},
{NULL, NULL, 0, NULL},
};

View file

@ -146,10 +146,19 @@ typedef struct VGGlyph {
bool uses_fg, uses_fixed_color;
// The number of bytes of memory used by this glyph
size_t memory_size;
// A hash of the payload and placement, identifying the rendered glyph.
// Uses a random seed so that collisions cannot be engineered.
uint64_t content_hash;
bool interned;
// The serialized placement and payload, the identity of the glyph
uint8_t *key;
size_t key_len;
} VGGlyph;
// Parse a vg payload. On success returns a glyph with a reference count of one.
// On failure returns NULL and sets *err and *err_msg, which points to a static string.
// Parse a vg payload. On success returns a new reference to a glyph, which is
// shared with all other glyphs with the same payload and placement. On
// failure returns NULL and sets *err and *err_msg, which points to a static
// string.
VGGlyph *vg_parse(const uint8_t *payload, size_t sz, const GlyphPlacement *placement, VGError *err, const char **err_msg);
VGGlyph *vg_incref(VGGlyph *g);
@ -190,31 +199,56 @@ void vg_render_free(VGRender *r);
// Always returns NULL
VGGlyph *vg_decref(VGGlyph *g);
// The memory used by all live glyphs
size_t vg_live_glyph_memory(void);
// Set a function to be called with the content hash of every glyph that is freed
void vg_set_free_callback(void (*callback)(uint64_t content_hash));
// Registrations {{{
// The memory budget for registered glyphs, across all sessions
#define VG_REGISTRY_MEMORY_BUDGET (64u * 1024u * 1024u)
// The memory budget for all live glyphs, registered or bound to cells, across
// all sessions. Registering new glyphs fails when it is exceeded. A backstop,
// the per window limits below are what normally apply.
#define VG_MEMORY_BUDGET (256u * 1024u * 1024u)
// Limits on the glyphs a window (screen) can keep alive: those registered plus
// those bound to text in the window. Glyphs used both ways are counted twice.
// When they are exceeded, registering fails, so that a program that keeps
// registering and printing new glyphs cannot exhaust memory or sprites for
// other windows.
#define VG_WINDOW_MEMORY_LIMIT (32u * 1024u * 1024u)
#define VG_WINDOW_GLYPH_LIMIT 8192u
extern size_t vg_window_memory_limit, vg_window_glyph_limit;
// The glyphs registered for the codepoints of the registration block in one
// session (screen)
typedef struct GlyphRegistry {
VGGlyph *glyphs[GLYPH_BLOCK_SIZE];
// For every slot, one plus the index in the text cache of the entry for
// the codepoint alone bound to the registered glyph, or zero. A cache for
// binding glyphs to cells when printing, must be cleared when text cache
// indices change.
char_type bound_idx_plus_1[GLYPH_BLOCK_SIZE];
uint32_t num_registered;
// The memory used by the registered glyphs
size_t memory;
// Unique for every registry, never reused
uint64_t id;
// The number of sprite slots used for rendering glyphs in this window
size_t sprite_slots;
// Incremented whenever a registration changes
uint32_t generation;
} GlyphRegistry;
GlyphRegistry *glyph_registry_alloc(void);
// Returns NULL if the registry no longer exists
GlyphRegistry *glyph_registry_for_id(uint64_t id);
void glyph_registry_free(GlyphRegistry *self);
// Returns a borrowed reference or NULL
static inline VGGlyph *
glyph_registry_get(const GlyphRegistry *self, char_type cp) {
return is_glyph_block_codepoint(cp) ? self->glyphs[cp - GLYPH_BLOCK_FIRST] : NULL;
}
// Register g for cp, taking a new reference to g. cp must be in the
// registration block. Returns false if this would exceed the memory budget.
bool glyph_registry_set(GlyphRegistry *self, char_type cp, VGGlyph *g);
// Register g for cp, taking a new reference to g. cp must be in the registration block.
void glyph_registry_set(GlyphRegistry *self, char_type cp, VGGlyph *g);
void glyph_registry_clear(GlyphRegistry *self, char_type cp);
void glyph_registry_clear_all(GlyphRegistry *self);
// The memory used by all registrations in all sessions
size_t glyph_registry_total_memory(void);
// }}}

View file

@ -1,11 +1,24 @@
#!/usr/bin/env python
# License: GPL v3 Copyright: 2026, Kovid Goyal <kovid at kovidgoyal.net>
import array
import math
from kitty.fast_data_types import parse_glyph_command, parse_vg, render_vg
from kitty.fast_data_types import (
DECAWM,
parse_glyph_command,
parse_vg,
render_vg,
set_glyph_protocol_sprite_limits,
sprite_idx_to_pos,
test_render_line,
vg_live_glyph_memory,
vg_set_window_limits,
)
from kitty.fonts.render import setup_for_testing
from .base import BaseTest, parse_bytes
from .base import BaseTest, draw_multicell, parse_bytes
from .fonts import FontBaseTest
class Dump(list):
@ -147,9 +160,9 @@ class TestGlyphProtocol(BaseTest):
parse_bytes(s, f'\x1b_25a1;{cmd}\x1b\\'.encode())
self.ae(s.callbacks.wtcbuf.decode(), ''.join(f'\x1b_25a1;{x}\x1b\\' for x in expected))
q('s', ['s;fmt='])
q('s', ['s;fmt=vg'])
# replies are sent in the order the requests arrive
q('s\x1b\\\x1b_25a1;q;cp=41', ['s;fmt=', 'q;cp=41;reason=unknown'])
q('s\x1b\\\x1b_25a1;q;cp=41', ['s;fmt=vg', 'q;cp=41;reason=unknown'])
q('q;cp=E0A0', ['q;cp=e0a0;reason=unknown'])
q('q;cp=100000', ['q;cp=100000;status='])
q('q;cp=1003ff', ['q;cp=1003ff;status='])
@ -697,3 +710,350 @@ class TestGlyphProtocol(BaseTest):
# Determinism
p = 'stroke=1.5,lin(0 0 24 24 reflect / 0 fg / 1 #00ff0080):M3 12c3-8 6-8 9 0s6 8 9 0|fill=evenodd,fg@0.5:' + circle
self.ae(r(p, 37, 71), r(p, 37, 71))
class GlyphRendering(FontBaseTest):
def sprite(self, sprite_idx):
pos = sprite_idx_to_pos(sprite_idx, setup_for_testing.xnum, setup_for_testing.ynum)
pixels = array.array('I', self.sprites[pos])
# the last row is the underline exclusion zone
return pixels[: self.cell_width * self.cell_height]
def register(self, s, cp, layers, vb='0 0 24 24', **kw):
extra = ''.join(f';{k}={v}' for k, v in kw.items())
s.callbacks.wtcbuf = b''
parse_bytes(s, f'\x1b_25a1;r;cp={cp:x};fmt=vg;vb={vb}{extra};{layers}\x1b\\'.encode())
self.ae(s.callbacks.wtcbuf, f'\x1b_25a1;r;cp={cp:x};status=0\x1b\\'.encode())
def render(self, s, text, y=0):
s.reset_mode(DECAWM)
s.cursor_position(y + 1, 1)
s.erase_in_line(2)
s.draw(text)
line = s.line(y)
test_render_line(line)
return line
def test_registered_glyph_rendering(self):
s = self.create_screen(cols=8, lines=4, scrollback=0)
cw, ch = self.cell_width, self.cell_height
full = 'fill=nonzero,fg:M-24 -24H48V48H-24Z'
self.register(s, 0x100000, full)
line = self.render(s, '\U00100000x')
idx = line.sprite_at(0)
self.ae(idx & 0xC0000000, 0)
self.ae(set(self.sprite(idx)), {0xFFFFFF00 | 255})
# unregistered codepoints in the block are rendered via fonts
line = self.render(s, '\U00100001x')
self.assertNotEqual(line.sprite_at(0), idx)
# a glyph with fixed colors is a colored sprite with unpremultiplied colors
self.register(s, 0x100002, 'fill=nonzero,#ff000080:M-24 -24H48V48H-24Z')
line = self.render(s, '\U00100002x')
cidx = line.sprite_at(0)
self.ae(cidx & 0xC0000000, 0x80000000)
self.ae(set(self.sprite(cidx)), {0xFF000080})
# a glyph mixing fixed colors and the foreground color has the weight
# of the foreground color in the sprite to its right
self.register(s, 0x100003, 'fill=nonzero,fg:M-24 -24H48V48H-24Z|fill=nonzero,#0000ff80:M-24 -24H48V48H-24Z', fit='stretch')
line = self.render(s, '\U00100003x')
midx = line.sprite_at(0)
self.ae(midx & 0xC0000000, 0xC0000000)
midx &= 0x3FFFFFFF
pos, fg_pos = (sprite_idx_to_pos(i, setup_for_testing.xnum, setup_for_testing.ynum) for i in (midx, midx + 1))
self.ae(fg_pos, (pos[0] + 1, pos[1], pos[2]))
# K = (0, 0, 128) with A = 255 and F = 127, relative to alpha
self.ae(set(self.sprite(midx)), {0x000080FF})
self.ae(set(self.sprite(midx + 1)), {0xFFFFFF00 | 127})
# identical glyphs share sprites, even at different codepoints
self.register(s, 0x100004, full)
self.ae(self.render(s, '\U00100004x').sprite_at(0), idx)
# changing a registration changes the rendering
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H24V12H0Z', fit='stretch')
line = self.render(s, '\U00100000x')
half_idx = line.sprite_at(0)
self.assertNotEqual(half_idx, idx)
pixels = self.sprite(half_idx)
self.ae(set(pixels[: cw * (ch // 2 - 1)]), {0xFFFFFF00 | 255})
self.ae(set(pixels[cw * (ch // 2 + 1) :]), {0xFFFFFF00})
# a clear makes the codepoint render via fonts again
parse_bytes(s, b'\x1b_25a1;c;cp=100000;reply=0\x1b\\')
self.assertNotIn(self.render(s, '\U00100000x').sprite_at(0), (idx, half_idx))
def test_registered_glyph_width(self):
s = self.create_screen(cols=8, lines=4, scrollback=0)
cw, ch = self.cell_width, self.cell_height
self.assertGreater(ch, cw)
# a square glyph followed by a space is rendered across two cells, as
# its width when fitting the cell height is more than one cell
sq = 'fill=nonzero,fg:M0 0H24V24H0Z'
self.register(s, 0x100000, sq)
line = self.render(s, '\U00100000 x')
left, right = self.sprite(line.sprite_at(0)), self.sprite(line.sprite_at(1))
coverage = sum(p & 0xFF for p in left) + sum(p & 0xFF for p in right)
self.assertAlmostEqual(coverage / 255, ch * ch, delta=ch)
# the glyph is centered in the two cells
self.ae(sum(p & 0xFF for p in left), sum(p & 0xFF for p in right))
# without a trailing space it is rendered in one cell
line = self.render(s, '\U00100000x')
self.assertAlmostEqual(sum(p & 0xFF for p in self.sprite(line.sprite_at(0))) / 255, cw * cw, delta=cw)
# a glyph whose viewBox fits in one cell is not widened
self.register(s, 0x100001, sq, vb='0 0 8 24')
line = self.render(s, '\U00100001 x')
self.ae(line.sprite_at(1), 0)
def test_registered_glyph_text_sizing(self):
s = self.create_screen(cols=8, lines=4, scrollback=0)
cw, ch = self.cell_width, self.cell_height
# with s=2 the glyph covers 2x2 cells
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H24V24H0Z', fit='stretch')
draw_multicell(s, '\U00100000', scale=2)
total = 0
for y in range(2):
line = s.line(y)
test_render_line(line)
for x in range(2):
total += sum(p & 0xFF for p in self.sprite(line.sprite_at(x))) / 255
self.ae(total, 4 * cw * ch)
# with w=3 the glyph covers 3 cells
s.reset()
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H12V24H0Z', fit='stretch')
draw_multicell(s, '\U00100000', width=3)
line = s.line(0)
test_render_line(line)
cov = [sum(p & 0xFF for p in self.sprite(line.sprite_at(x))) / 255 for x in range(3)]
# the left half of the 3 cell wide area is covered
self.assertAlmostEqual(sum(cov), 1.5 * cw * ch, delta=ch)
self.ae(cov[0], cw * ch)
self.ae(cov[2], 0)
def test_registered_glyphs_are_bound_when_printed(self):
s = self.create_screen(cols=8, lines=4, scrollback=20)
base_memory = vg_live_glyph_memory()
circle = 'fill=nonzero,fg:M12 2A10 10 0 1 1 12 22A10 10 0 1 1 12 2Z'
square = 'fill=nonzero,fg:M2 2H22V22H2Z'
self.register(s, 0x100000, circle)
line = self.render(s, '\U00100000x')
circle_idx = line.sprite_at(0)
# the text of the cell is just the codepoint
self.ae(str(line), '\U00100000x')
# re-registering does not change what was already printed
self.register(s, 0x100000, square)
test_render_line(line)
self.ae(line.sprite_at(0), circle_idx)
# but text printed later uses the new glyph
line2 = self.render(s, '\U00100000x', y=1)
square_idx = line2.sprite_at(0)
self.assertNotEqual(square_idx, circle_idx)
# combining chars keep the glyph bound to the cell
s.cursor_position(1, 2)
s.draw('\u0301')
self.ae(str(s.line(0)), '\U00100000\u0301x')
line = s.line(0)
test_render_line(line)
self.ae(line.sprite_at(0), circle_idx)
# clearing does not affect printed text
parse_bytes(s, b'\x1b_25a1;c;reply=0\x1b\\')
for y, idx in ((0, circle_idx), (1, square_idx)):
line = s.line(y)
test_render_line(line)
self.ae(line.sprite_at(0), idx)
# but text printed later is not rendered with a registered glyph
self.assertNotIn(self.render(s, '\U00100000x', y=2).sprite_at(0), (circle_idx, square_idx))
# registering identical glyphs shares the glyph objects
self.register(s, 0x100001, circle)
self.register(s, 0x100002, circle)
self.ae(self.render(s, '\U00100001\U00100002', y=3).sprite_at(0), circle_idx)
self.ae(s.line(3).sprite_at(1), circle_idx)
# text with bound glyphs keeps them alive until the text is gone
self.assertGreater(vg_live_glyph_memory(), base_memory)
parse_bytes(s, b'\x1b_25a1;c;reply=0\x1b\\')
self.assertGreater(vg_live_glyph_memory(), base_memory)
s.erase_in_display(3, False)
s.erase_in_display(2, False)
s.garbage_collect_text_cache()
self.ae(vg_live_glyph_memory(), base_memory)
# text in the scrollback keeps its glyphs
self.register(s, 0x100003, circle)
s.draw('\U00100003')
for i in range(6):
s.index()
s.garbage_collect_text_cache()
self.assertGreater(vg_live_glyph_memory(), base_memory)
# RIS releases all glyphs
s.reset()
self.ae(vg_live_glyph_memory(), base_memory)
def test_registered_glyphs_in_multicell(self):
s = self.create_screen(cols=8, lines=4, scrollback=0)
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H24V24H0Z', fit='stretch')
draw_multicell(s, '\U00100000', scale=2)
line = s.line(0)
test_render_line(line)
first = line.sprite_at(0)
# re-registering does not change the multicell char
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H12V24H0Z', fit='stretch')
for y in range(2):
line = s.line(y)
test_render_line(line)
self.ae(sum(p & 0xFF for x in range(2) for p in self.sprite(line.sprite_at(x))) / 255, 2 * self.cell_width * self.cell_height)
self.ae(s.line(0).sprite_at(0), first)
def test_registered_glyph_sprites_are_reused(self):
import gc
# free screens from earlier tests, as freeing their glyphs creates holes
gc.collect()
s = self.create_screen(cols=8, lines=4, scrollback=0)
def glyph(i, mixed=False):
ans = f'fill=nonzero,fg:M0 0H{1 + i % 23}V24H0Z'
if mixed:
ans += f'|fill=nonzero,#ff0000:M0 0H24V{1 + i % 23}H0Z'
return ans
def show(i, mixed=False):
self.register(s, 0x100000, glyph(i, mixed))
return self.render(s, '\U00100000x').sprite_at(0) & 0x3FFFFFFF
def release():
# erase the text and the registration, so the glyph is freed
s.erase_in_display(2, False)
parse_bytes(s, b'\x1b_25a1;c;reply=0\x1b\\')
s.garbage_collect_text_cache()
a = show(1)
release()
self.ae(show(2), a)
release()
# a pair of slots for a glyph mixing fg and fixed colors is reused for another such glyph
m = show(3, True)
release()
self.ae(show(4, True), m)
release()
# single slots are reused before pairs are split
self.ae(show(5), a)
# and then pairs are split into single slots
self.register(s, 0x100001, glyph(6))
self.register(s, 0x100002, glyph(7))
line = self.render(s, '\U00100001\U00100002', y=1)
self.ae([line.sprite_at(x) for x in range(2)], [m, m + 1])
release()
# registering and printing new glyphs uses a bounded number of sprites
before = len(self.sprites)
for i in range(200):
show(100 + i, i % 3 == 0)
if i % 10 == 9:
s.garbage_collect_text_cache()
self.assertLess(len(self.sprites) - before, 40)
def test_registered_glyph_window_limits(self):
self.addCleanup(vg_set_window_limits)
vg_set_window_limits(1 << 30, 10)
s = self.create_screen(cols=8, lines=4, scrollback=100)
def reg(screen, i):
screen.callbacks.wtcbuf = b''
parse_bytes(screen, f'\x1b_25a1;r;cp=100000;fmt=vg;vb=0 0 24 24;fill=nonzero,fg:M0 0H{i / 4}V1Z\x1b\\'.encode())
return screen.callbacks.wtcbuf.decode()
ok, full = '\x1b_25a1;r;cp=100000;status=0\x1b\\', '\x1b_25a1;r;cp=100000;status=1;reason=no_space\x1b\\'
# each new glyph printed into the scrollback is kept alive by the text
results = []
for i in range(1, 20):
results.append(reg(s, i))
s.draw('\U00100000')
s.linefeed()
s.carriage_return()
self.ae(results[:8], [ok] * 8)
self.ae(results[-1], full)
# other windows are not affected
s2 = self.create_screen()
self.ae(reg(s2, 50), ok)
# once the text is gone the glyphs are released and registering works again
s.erase_in_display(3, False)
s.erase_in_display(2, False)
s.garbage_collect_text_cache()
self.ae(reg(s, 60), ok)
# the text cache is garbage collected automatically when the limits are reached
s3 = self.create_screen(cols=8, lines=4, scrollback=0)
for i in range(1, 6):
self.ae(reg(s3, i), ok)
s3.draw('\U00100000')
s3.erase_in_display(2, False)
for i in range(6, 12):
self.ae(reg(s3, i), ok, f'registration {i} failed')
s3.draw('\U00100000')
def test_registered_glyph_sprite_limits(self):
import gc
gc.collect()
self.addCleanup(set_glyph_protocol_sprite_limits)
MISSING = 1
# each glyph can be rendered with a limited number of distinct parameters
set_glyph_protocol_sprite_limits(65536, 16384, 12)
s = self.create_screen(cols=8, lines=4, scrollback=0)
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H24V24H0Z')
results = []
for n in range(1, 8):
s.reset_mode(DECAWM)
s.cursor_position(1, 1)
draw_multicell(s, '\U00100000', width=2, subscale_n=n, subscale_d=8)
line = s.line(0)
test_render_line(line)
results.append(line.sprite_at(0))
# 2 sprites per variant, the seventh variant exceeds the limit of 12
self.assertNotIn(MISSING, results[:6])
self.ae(results[6], MISSING)
# each window can use a limited number of sprite slots
# 2 slots are reserved per sprite, as glyphs mixing colors use a pair
set_glyph_protocol_sprite_limits(65536, 6, 1024)
s = self.create_screen(cols=8, lines=4, scrollback=0)
for i in range(8):
self.register(s, 0x100000 + i, f'fill=nonzero,fg:M0 0H{i + 1}V24H0Z')
line = self.render(s, ''.join(chr(0x100000 + i) for i in range(8)))
sprites = [line.sprite_at(x) for x in range(8)]
self.assertNotIn(MISSING, sprites[:5])
self.ae(sprites[5:], [MISSING] * 3)
# other windows are not affected
s2 = self.create_screen(cols=8, lines=4, scrollback=0)
self.register(s2, 0x100000, 'fill=nonzero,fg:M0 0H20V24H0Z')
self.assertNotEqual(self.render(s2, '\U00100000').sprite_at(0), MISSING)
# once the glyphs are no longer used the window can render again
s.erase_in_display(2, False)
parse_bytes(s, b'\x1b_25a1;c;reply=0\x1b\\')
s.garbage_collect_text_cache()
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H21V24H0Z')
self.assertNotEqual(self.render(s, '\U00100000').sprite_at(0), MISSING)
set_glyph_protocol_sprite_limits()
# glyphs that are too complex to render are rendered as the missing glyph
s = self.create_screen(cols=8, lines=8, scrollback=0)
bomb = 'stroke=0.001,fg:M0.5 0' + ' q2e-05 2e-05 0 4e-05 q-2e-05 -2e-05 0 -4e-05' * 64
self.register(s, 0x100001, bomb, vb=f'0 0 1 {1 / 4096}', fit='cover')
draw_multicell(s, '\U00100001', scale=7)
for i in range(2): # the second time the failure is cached
line = s.line(0)
test_render_line(line)
self.ae([line.sprite_at(x) for x in range(7)], [MISSING] * 7)
def test_paused_rendering_releases_glyphs(self):
import gc
gc.collect()
base = vg_live_glyph_memory()
s = self.create_screen(cols=8, lines=4, scrollback=0)
self.register(s, 0x100000, 'fill=nonzero,fg:M0 0H24V24H0Z')
s.draw('\U00100000')
self.assertTrue(s.pause_rendering(True, 5000))
self.assertTrue(s.pause_rendering(False, 0))
s.reset()
self.ae(vg_live_glyph_memory(), base)