1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# st-graphics
This is a fork of [st](https://st.suckless.org/) that implements a subset of
[kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
If you want this formatted as a single patch, take the last commit from this
branch: [graphics-squashed](https://github.com/sergei-grechanik/st-graphics/tree/graphics-squashed)
(may be slightly outdated).
If you want to combine this with other patches, check out the
[graphics-with-patches branch](https://github.com/sergei-grechanik/st-graphics/tree/graphics-with-patches)
(see also [patch compatibility](#patch-compatibility)).
This repository also includes a simple script to display images `icat-mini.sh`.
Note: to make it work in tmux you need to enable pass-through sequences, i.e.
add something like this to your `.tmux.conf`:
set -gq allow-passthrough all
You also need to make sure that tmux supports 24-bit colors and that it knows
that the client terminal supports 24-bit colors (you may need to install the st
terminfo entry on all systems that you use, including remote ones).
## Installation
As usual, copy `config.def.h` to `config.h`, modify it according to your needs,
run `make install` or `DESTDIR=/some/prefix make install`.
In addition to the standard st dependencies (X11, fontconfig, freetype2),
you will need imlib2 and zlib for the graphics module.
## Configuration
**This fork includes some seemingly unrelated changes, like anysize and
underline color and style. You may want to tweak them too if you don't like the
defaults. See also [patch compatibility](#patch-compatibility).**
You may want to change the graphics-related shortcuts and image size limits (see
`config.def.h`).
Default shortcuts:
- `Ctrl+Shift+RightClick` to preview the clicked image in feh.
- `Ctrl+Shift+MiddleClick` to see debug info (image id, placement id, etc).
- `Ctrl+Shift+F1` to toggle graphics debug mode. It has three states: 1) no
debugging; 2) show general info and print logs to stderr; 3) print logs and
show bounding boxes.
- `Ctrl+Shift+F6` to dump the state of all images to stderr.
- `Ctrl+Shift+F7` to unload all images from ram (but the cache in `/tmp` will be
preserved).
- `Ctrl+Shift+F8` to toggle image display.
## Features
Originally I implemented it to prototype the Unicode placeholder feature (which
is now included in the kitty graphics protocol). Classic placements were
retrofitted later, and under the hood they are implemented via the same
placeholder mechanism. This means that a cell may be occupied only by one
placement. It is the main reason why some things don't work or work a bit
differently.
Here is the list of supported (✅ ), unsupported (❌), and non-standard (⚡)
features.
- Uploading:
- Formats:
- ✅ PNG (`f=100`)
- ✅ RGB, RGBA (`f=24`, `f=32`)
- ✅ Compression with zlib (`o=z`)
- ⚡ jpeg. Actually any format supported by imlib2 should work. The key
value is the same as for png (`f=100`).
- Transmission mediums:
- ✅ Direct (`t=d`)
- ✅ File (`t=f`)
- ✅ Temporary file (`t=t`)
- ✅ Shared memory object (`t=s`)
- ✅ Size and offset specification (`S` and `O` keys) for shared memory
- ❌ Not fully supported for files
- ✅ Image numbers
- ✅ Responses
- ✅ Transmit and display (`a=T`)
- Placement:
- ✅ Classic placements (but see the note above)
- ✅ Unicode placeholders
- ✅ Placement IDs
- ❌ NOTE: Placement IDs must be 24-bit (between 1 and 16777215).
- ✅ Cursor movement policies `C=1` and `C=0`
- ✅ Source rectangle (`x, y, w, h`)
- ✅ The number of rows/columns (`r, c`)
- ❌ Cell offsets (`X, Y`)
- ❌ z-index. Classic placements will erase old placements and the text on
overlap.
- ❌ Relative placements (`P, Q, H, V`)
- Deletion:
- ✅ Deletion of image data when the specifier is uppercase
- ✅ All visible classic placements (`d=a`)
- ✅ By image id/number and placement id (`d=i`, `d=n`)
- ❌ By position (specifiers `c, p, q, x, y, z`)
- ❌ Animation frames (`d=f`)
- Animation - experimental
- ✅ Transferring animation frames (`a=f`)
- ✅ Transferring part of the image (`x, y, s, v`)
- ✅ Background colors (`Y`)
- ✅ Background frames (`c`)
- ❌ Editing the existing frame (`r`)
- ✅ Delays (`z`)
- ✅ Controlling animations (`a=a`)
- ✅ Stop, run, and loading modes (`s`)
- ❌ Number of loop (`v`)
- ✅ Setting the delay (`z`)
- ❌ Animation frame composition (`a=c`)
- ❌ Frame deletion (`d=f`)
- ✅ Kitty's icat kitten is supported. You can also use `icat-mini.sh`
(slower).
## Things I have tested
### Apps that seem to work
- Kitty's icat (including from within tmux).
- [termpdf](https://github.com/dsanson/termpdf.py)
- [ranger](https://github.com/ranger/ranger) - I had to explicitly set
`TERM=kitty`.
- [tpix](https://github.com/jesvedberg/tpix)
- [pixcat](https://github.com/mirukana/pixcat) (modulo some unsupported keys
that are currently ignored).
- [viu](https://github.com/atanunq/viu) - I had to explicitly set
`TERM=kitty`.
- [timg](https://github.com/hzeller/timg) - I had to explicitly pass `-pk`
(i.e. `timg -pk <image>`). If your timg is fresh enough, it even works in
tmux!
- [yazi](https://github.com/sxyazi/yazi) - works if you run it as
`TERM="xterm-kitty" yazi`.
### Apps that sort of work
- [hologram.nvim](https://github.com/edluffy/hologram.nvim) - There are some
glitches, like erasure of parts of the status line.
- [mpv](https://github.com/mpv-player/mpv) - shared memory works
(`mpv --vo=kitty --vo-kitty-use-shm=yes`), but slower than kitty, and there is
an annoying flickering status line at the top (unsupported z-index). There are
also some artifacts on high resolutions.
### Apps that don't work
- [termvisage](https://github.com/AnonymouX47/termvisage) - seems to erase
cells containing the image after image placement. In kitty this has no effect
on classic placements because they aren't attached to cells, but in
st-graphics classic placements are implemented on top of Unicode placements,
so they get erased.
## Patch compatibility
The [graphics-with-patches branch](https://github.com/sergei-grechanik/st-graphics/tree/graphics-with-patches)
contains several patches applied on top of the graphics branch. The patches
include:
- [Boxdraw](https://st.suckless.org/patches/boxdraw) - applied with minimal
conflicts.
- [Scrollback](https://st.suckless.org/patches/scrollback) - quite a few
conflicts, but easy to resolve.
- [Wide glyph support](https://st.suckless.org/patches/glyph_wide_support/)
- [Ligatures](https://st.suckless.org/patches/ligatures) -
required some modifications.
- [Alpha](https://st.suckless.org/patches/alpha)
- [External pipe](https://st.suckless.org/patches/externalpipe)
If you run into any problems with other patches, feel free to open an issue.
### Patches and changes that are included in the graphics implementation
This fork includes some patches and features that are not graphics-related
per se, but are hard to disentangle from the graphics implementation:
- [Anysize](https://st.suckless.org/patches/anysize/) - this patch is applied
and on by default. If you want the "expected" anysize behavior (no centering),
set `anysize_halign` and `anysize_valign` to zero in `config.h`.
- Support for several XTWINOPS control sequences to query information that is
sometimes required for image display (like cell size in pixels).
- Support for decoration (underline) color and style. The decoration color is
used to specify the placement id in Unicode placeholders, so it's hard to make
them separate. The behavior of the underline is different from the upstream
st: it's drawn behind the text and the thickness depends on the font size. You
may need to tweak the code in `xdrawglyphfontspecs` in `x.c` if you don't like
it.
|
