diff --git a/README.asciidoc b/README.asciidoc index 23741c125..e65a67edc 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -66,7 +66,7 @@ latency. * Cross-platform support: kitty currently works on Linux and macOS, but because it uses only OpenGL for rendering, it should be trivial to port to other -platforms. +platforms. * Allows you to open the scrollback buffer and window contents in a separate window using arbitrary programs of your choice. This is useful for browsing @@ -89,8 +89,8 @@ the following dependencies are installed first. === Dependencies * python >= 3.5 -* harfbuzz >= 1.5.0 -* libunistring +* harfbuzz >= 1.5.0 +* libunistring * zlib * libpng * freetype (not needed on macOS) @@ -224,7 +224,7 @@ windows are: |Increase font size | {sc_increase_font_size} |Decrease font size | {sc_decrease_font_size} -|Restore font size | {sc_restore_font_size} +|Restore font size | {sc_restore_font_size} |Toggle fullscreen | {sc_toggle_fullscreen} |Pass current selection to program | {sc_pass_selection_to_program} |=== @@ -339,14 +339,14 @@ render loop to reduce CPU usage. See the link:kitty/kitty.conf[config file] for You can generate detailed per-function performance data using link:https://github.com/gperftools/gperftools[gperftools]. Build kitty with the `--profile` flag which will create an executable called `kitty-profile`. Run -that and perform the task you want to analyse, for example, scrolling a large +that and perform the task you want to analyse, for example, scrolling a large file with `less`. After you quit, function call statistics will be printed to `stdout` and you can use tools like *kcachegrind* for more detailed analysis. Here are some CPU usage numbers for the task of scrolling a file continuously in less. The CPU usage is for the terminal process and X together and is measured using htop. -The measurements are taken at the same font and window size for all terminals on a -`Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz` CPU with a +The measurements are taken at the same font and window size for all terminals on a +`Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz` CPU with a `Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD 7770/8760 / R7 250X]` GPU. |=== @@ -423,7 +423,7 @@ You dont need to build kitty.app to run kitty from source. Simply install the de listed above using brew/MacPorts or similar and then compile and run with: ``` -make +make python3 . ``` @@ -458,7 +458,7 @@ kitty, I ran headlong into more and more gnarly corners of terminal behavior. On all those occasions, either the excellent documentation at link:http://invisible-island.net/xterm/ctlseqs/ctlseqs.html[xterm-ctlseqs] or investigating the behavior and code of xterm or vttest were invaluable tools to -aid my understanding. +aid my understanding. My achievements, if any, in developing kitty would not have been possible without his prior work and the generous sharing of knowledge accumulated over decades. diff --git a/graphics-protocol.asciidoc b/graphics-protocol.asciidoc index 46b94d664..e807b4aa8 100644 --- a/graphics-protocol.asciidoc +++ b/graphics-protocol.asciidoc @@ -8,7 +8,7 @@ to render arbitrary pixel (raster) graphics to the screen of the terminal emulator. The major design goals are * Should not require terminal emulators to understand image formats. - * Should allow specifying graphics to be drawn at individual pixel positions. + * Should allow specifying graphics to be drawn at individual pixel positions. * The graphics should integrate with the text, in particular it should be possible to draw graphics below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically. * Should use optimizations when the client is running on the same computer as the terminal emulator. @@ -21,7 +21,7 @@ To see a quick demo, inside a kitty terminal run: kitty icat path/to/some/image.png ``` -You can also see a screenshot with more sophisticated features such as alpha-blending and text over graphics +You can also see a screenshot with more sophisticated features such as alpha-blending and text over graphics link:https://github.com/kovidgoyal/kitty/issues/33#issuecomment-334436100[here]. toc::[] @@ -33,7 +33,7 @@ window size in pixels and the number of cells per row and column. This can be do Some C code to demonstrate its use ```C -struct ttysize ts; +struct ttysize ts; ioctl(0, TIOCGWINSZ, &ts); printf("number of columns: %i, number of rows: %i, screen width: %i, screen height: %i\n", sz.ws_col, sz.ws_row, sz.ws_xpixel, sz.ws_ypixel); ``` @@ -50,7 +50,7 @@ All graphics escape codes are of the form: ``` This is a so-called _Application Programming Command (APC)_. Most terminal -emulators ignore APC codes, making it safe to use. +emulators ignore APC codes, making it safe to use. The control data is a comma-separated list of `key=value` pairs. The payload is arbitrary binary data, base64-encoded to prevent interoperation problems @@ -124,12 +124,12 @@ The transmission medium is specified using the `t` key. The `t` key defaults to and can take the values: |=== -| Value of `t` | Meaning +| Value of `t` | Meaning | d | Direct (the data is transmitted within the escape code itself) | f | A simple file | t | A temporary file, the terminal emulator will delete the file after reading the pixel data -| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data +| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data |=== ==== Local client @@ -175,9 +175,9 @@ if the data is split into three chunks, the client would send the following sequence of escape codes to the terminal emulator: ``` -_Gs=100,v=30,m=1;\ -_Gm=1;\ -_Gm=0;\ +_Gs=100,v=30,m=1;\ +_Gm=1;\ +_Gm=0;\ ``` Note that only the first escape code needs to have the full set of control @@ -189,7 +189,7 @@ before sending any other graphics related escape codes. === Detecting available transmission mediums Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory -with the terminal emulator, it can send an id with the control data, using the `i` key +with the terminal emulator, it can send an id with the control data, using the `i` key (which can be an arbitrary positive integer up to 4294967295, it must not be zero). If it does so, the terminal emulator will reply after trying to load the image, saying whether loading was successful or not. For example: @@ -207,7 +207,7 @@ to which the terminal emulator will reply (after trying to load the data): Here the `i` value will be the same as was sent by the client in the original request. The message data will be a ASCII encoded string containing only printable characters and spaces. The string will be `OK` if reading the pixel -data succeeded or an error message. +data succeeded or an error message. Sometimes, using an id is not appropriate, for example, if you do not want to replace a previously sent image with the same id, or if you are sending a dummy @@ -245,7 +245,7 @@ be re-transmitted. === Controlling displayed image layout The image is rendered at the current cursor position, from the upper left corner of -the current cell. You can also specify extra `X=3` and `Y=4` pixel offsets to display from +the current cell. You can also specify extra `X=3` and `Y=4` pixel offsets to display from a different origin within the cell. Note that the offsets must be smaller that the size of the cell. By default, the entire image will be displayed (images wider than the available @@ -255,7 +255,7 @@ the top-left corner, width and height of the source rectangle. You can also ask the terminal emulator to display the image in a specified rectangle (num of columns / num of lines), using the control codes `c,r`. `c` is the number of columns -and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit +and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit the specified area. Note that if you specify a start cell offset via the `X,Y` keys, it is not added to the number of rows/columns. @@ -269,7 +269,7 @@ allows rendering of text on top of images. Images can be deleted by using the delete action `a=d`. If specified without any other keys, it will delete all images visible on screen. To delete specific images, -use the `d` key as described in the table below. Note that each value of d has +use the `d` key as described in the table below. Note that each value of d has both a lowercase and an uppercase variant. The lowercase variant only deletes the images without necessarily freeing up the stored image data, so that the images can be re-displayed without needing to resend the data. The uppercase variants will delete @@ -278,7 +278,7 @@ scrollback buffer. The values of the `x` and `y` keys are the same as cursor pos x=1, y=1 is the top left cell). |=== -| Value of `d` | Meaning +| Value of `d` | Meaning | `a` or `A` | Delete all images visible on screen | `i` or `I` | Delete all images with the specified id, specified using the `i` key. @@ -313,7 +313,7 @@ delete older images to make space for the new one. == Control data reference The table below shows all the control data keys as well as what values they can -take, and the default value they take when missing. All integers are 32-bit. +take, and the default value they take when missing. All integers are 32-bit. [cols="^1,<3,^1,<6"] |=== diff --git a/kitty/blit_vertex.glsl b/kitty/blit_vertex.glsl index 7899a7043..89e1f7754 100644 --- a/kitty/blit_vertex.glsl +++ b/kitty/blit_vertex.glsl @@ -5,10 +5,10 @@ #define bottom -1.0f const vec2 pos_map[] = vec2[4]( - vec2(right, top), - vec2(right, bottom), - vec2(left, bottom), - vec2(left, top) + vec2(right, top), + vec2(right, bottom), + vec2(left, bottom), + vec2(left, top) ); out vec2 texcoord; diff --git a/kitty/border_vertex.glsl b/kitty/border_vertex.glsl index c07334fab..864dc55b5 100644 --- a/kitty/border_vertex.glsl +++ b/kitty/border_vertex.glsl @@ -11,10 +11,10 @@ const int RIGHT = 2; const int BOTTOM = 3; const uvec2 pos_map[] = uvec2[4]( - uvec2(RIGHT, TOP), - uvec2(RIGHT, BOTTOM), - uvec2(LEFT, BOTTOM), - uvec2(LEFT, TOP) + uvec2(RIGHT, TOP), + uvec2(RIGHT, BOTTOM), + uvec2(LEFT, BOTTOM), + uvec2(LEFT, TOP) ); vec2 to_opengl(uint x, uint y) { diff --git a/kitty/cell_fragment.glsl b/kitty/cell_fragment.glsl index 1011c5098..b40714198 100644 --- a/kitty/cell_fragment.glsl +++ b/kitty/cell_fragment.glsl @@ -34,7 +34,7 @@ vec4 alpha_blend(vec3 over, float over_alpha, vec3 under, float under_alpha) { // Alpha blend two colors returning the resulting color pre-multiplied by its alpha // and its alpha. // See https://en.wikipedia.org/wiki/Alpha_compositing - float alpha = mix(under_alpha, 1.0f, over_alpha); + float alpha = mix(under_alpha, 1.0f, over_alpha); vec3 combined_color = mix(under * under_alpha, over, over_alpha); return vec4(combined_color, alpha); } @@ -45,7 +45,7 @@ vec3 premul_blend(vec3 over, float over_alpha, vec3 under) { vec4 alpha_blend_premul(vec3 over, float over_alpha, vec3 under, float under_alpha) { // Same as alpha_blend() except that it assumes over and under are both premultiplied. - float alpha = mix(under_alpha, 1.0f, over_alpha); + float alpha = mix(under_alpha, 1.0f, over_alpha); return vec4(premul_blend(over, over_alpha, under), alpha); } // }}} @@ -70,7 +70,7 @@ void main() { final_color = vec4(background.rgb * bg_alpha, bg_alpha); #else final_color = vec4(background.rgb, 1.0f); -#endif +#endif #endif #ifdef SPECIAL @@ -78,10 +78,10 @@ void main() { final_color = vec4(background.rgb * bg_alpha, bg_alpha); #else final_color = vec4(background.rgb, bg_alpha); -#endif +#endif #endif -#if defined(FOREGROUND) || defined(SIMPLE) +#if defined(FOREGROUND) || defined(SIMPLE) // FOREGROUND or SIMPLE vec4 fg = calculate_foreground(); // pre-multiplied foreground diff --git a/kitty/cell_vertex.glsl b/kitty/cell_vertex.glsl index 318e71afb..09d89d12d 100644 --- a/kitty/cell_vertex.glsl +++ b/kitty/cell_vertex.glsl @@ -12,7 +12,7 @@ layout(std140) uniform CellRenderData { uint xnum, ynum, cursor_x, cursor_y, cursor_w; - uint color_table[256]; + uint color_table[256]; }; // Have to use fixed locations here as all variants of the cell program share the same VAO @@ -21,7 +21,7 @@ layout(location=1) in uvec4 sprite_coords; layout(location=2) in uint is_selected; - + const uvec2 cell_pos_map[] = uvec2[4]( uvec2(1, 0), // right, top uvec2(1, 1), // right, bottom @@ -118,27 +118,27 @@ float is_cursor(uint x, uint y) { void main() { // set cell vertex position {{{ - uint instance_id = uint(gl_InstanceID); + uint instance_id = uint(gl_InstanceID); /* The current cell being rendered */ - uint r = instance_id / xnum; - uint c = instance_id - r * xnum; + uint r = instance_id / xnum; + uint c = instance_id - r * xnum; - /* The position of this vertex, at a corner of the cell */ - float left = xstart + c * dx; - float top = ystart - r * dy; - vec2 xpos = vec2(left, left + dx); - vec2 ypos = vec2(top, top - dy); - uvec2 pos = cell_pos_map[gl_VertexID]; + /* The position of this vertex, at a corner of the cell */ + float left = xstart + c * dx; + float top = ystart - r * dy; + vec2 xpos = vec2(left, left + dx); + vec2 ypos = vec2(top, top - dy); + uvec2 pos = cell_pos_map[gl_VertexID]; gl_Position = vec4(xpos[pos.x], ypos[pos.y], 0, 1); // }}} - + // set cell color indices {{{ - uvec2 default_colors = uvec2(default_fg, default_bg); - ivec2 color_indices = ivec2(color1, color2); - uint text_attrs = sprite_coords[3]; - int fg_index = color_indices[(text_attrs >> 6) & REVERSE_MASK]; - int bg_index = color_indices[1 - fg_index]; + uvec2 default_colors = uvec2(default_fg, default_bg); + ivec2 color_indices = ivec2(color1, color2); + uint text_attrs = sprite_coords[3]; + int fg_index = color_indices[(text_attrs >> 6) & REVERSE_MASK]; + int bg_index = color_indices[1 - fg_index]; float cursor = is_cursor(c, r); vec3 bg = to_color(colors[bg_index], default_colors[bg_index]); // }}} @@ -150,7 +150,7 @@ void main() { sprite_pos = to_sprite_pos(pos, sprite_coords.x, sprite_coords.y, sprite_coords.z & Z_MASK); colored_sprite = float((sprite_coords.z & COLOR_MASK) >> 14); - // Foreground + // Foreground uint resolved_fg = resolve_color(colors[fg_index], default_colors[fg_index]); foreground = color_to_vec(resolved_fg); // Selection @@ -165,7 +165,7 @@ void main() { foreground = choose_color(cursor, bg, foreground); decoration_fg = choose_color(cursor, bg, decoration_fg); #endif - // }}} + // }}} // Background {{{ #ifdef NEEDS_BACKROUND diff --git a/kitty/kitty.conf b/kitty/kitty.conf index 51ce436d2..65638b4ba 100644 --- a/kitty/kitty.conf +++ b/kitty/kitty.conf @@ -8,7 +8,7 @@ # bold_font Operator Mono Medium # italic_font Operator Mono Book Italic # bold_italic_font Operator Mono Medium Italic -# +# # You can get a list of full family names available on your computer by running # kitty list-fonts font_family monospace @@ -24,7 +24,7 @@ font_size 11.0 font_size_delta 2 -# Adjust the line height. +# Adjust the line height. # You can use either numbers, which are interpreted as pixels or percentages # (number followed by %), which are interpreted as percentages of the # unmodified line height. You can use negative pixels or percentages less than @@ -32,7 +32,7 @@ font_size_delta 2 adjust_line_height 0 # Change the sizes of the lines used for the box drawing unicode characters -# These values are in pts. They will be scaled by the monitor DPI to arrive at +# These values are in pts. They will be scaled by the monitor DPI to arrive at # a pixel value. There must be four values corresponding to thin, normal, thick, # and very thick lines; box_drawing_scale 0.001, 1, 1.5, 2 @@ -73,7 +73,7 @@ cursor #cccccc cursor_shape block # The interval (in seconds) at which to blink the cursor. Set to zero to -# disable blinking. Note that numbers smaller than repaint_delay will be +# disable blinking. Note that numbers smaller than repaint_delay will be # limited to repaint_delay. cursor_blink_interval 0.5 @@ -226,10 +226,10 @@ color15 #ffffff # Key mapping # For a list of key names, see: http://www.glfw.org/docs/latest/group__keys.html # For a list of modifier names, see: http://www.glfw.org/docs/latest/group__mods.html -# +# # You can use the special action no_op to unmap a keyboard shortcut that is # assigned in the default configuration. -# +# # You can combine multiple actions to be triggered by a single shortcut, using the # syntax below: # map key combine action1 action2 action3 ... @@ -246,7 +246,7 @@ map shift+insert paste_from_selection # pass_selection_to_program. By default, the system's open program is used, but # you can specify your own, for example: # map ctrl+shift+o pass_selection_to_program firefox -map ctrl+shift+o pass_selection_to_program +map ctrl+shift+o pass_selection_to_program # Scrolling map ctrl+shift+up scroll_line_up @@ -260,8 +260,8 @@ map ctrl+shift+end scroll_end map ctrl+shift+h show_scrollback # Window management -map ctrl+shift+enter new_window -map ctrl+shift+n new_os_window +map ctrl+shift+enter new_window +map ctrl+shift+n new_os_window map ctrl+shift+w close_window map ctrl+shift+] next_window map ctrl+shift+[ previous_window @@ -334,11 +334,11 @@ map ctrl+shift+f11 toggle_fullscreen # in hexadecimal>. You can specify multiple code points, separated by commas # and ranges separated by hyphens. symbol_map itself can be specified multiple times. # Syntax is: -# +# # symbol_map codepoints Font Family Name -# +# # For example: -# +# # symbol_map U+E0A0-U+E0A2,U+E0B0-U+E0B3 PowerlineSymbols @@ -347,7 +347,7 @@ map ctrl+shift+f11 toggle_fullscreen # Hide the kitty window's title bar on macOS. macos_hide_titlebar no -# Use the option key as an alt key. With this set to no, kitty will use +# Use the option key as an alt key. With this set to no, kitty will use # the macOS native Option+Key = unicode character behavior. This will # break any Alt+key keyboard shortcuts in your terminal programs, but you # can use the macOS unicode input technique. diff --git a/protocol-extensions.asciidoc b/protocol-extensions.asciidoc index 94dc936e4..d4a8fb684 100644 --- a/protocol-extensions.asciidoc +++ b/protocol-extensions.asciidoc @@ -54,8 +54,8 @@ To reset the underline color (also previously reserved and unused): [59m ``` -A client can query if the terminal emulator supports this underline extension using the -standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence, with the +A client can query if the terminal emulator supports this underline extension using the +standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence, with the mode value `2016`, like this: Client sends: @@ -86,8 +86,8 @@ include: * No way to use modifiers other than `Ctrl` and `Alt` * No way to use multiple modifier keys, other than, `Shift+Alt`. * No way to handle different types of keyboard events, such as press, release or repeat - * No reliable way to distinguish single `Esc` keypresses from the - start of a escape sequence. Currently, client programs use + * No reliable way to distinguish single `Esc` keypresses from the + start of a escape sequence. Currently, client programs use fragile timing related hacks for this, leading to bugs, for example: link:https://github.com/neovim/neovim/issues/2035[neovim #2035] @@ -112,7 +112,7 @@ and to leave _full mode_, use DECRST ``` The number `2017` above is not used for any existing modes, as far as I know. -Client programs can query if the terminal emulator is in _full mode_ by using +Client programs can query if the terminal emulator is in _full mode_ by using the standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence. The new mode works as follows: @@ -135,7 +135,7 @@ The escape sequence encodes the following properties: * Type of event: `press,repeat,release` * Modifiers pressed at the time of the event - * The actual key being pressed + * The actual key being pressed ``` _K\ @@ -165,13 +165,13 @@ regions of the screen, link:https://vt100.net/docs/vt510-rm/DECCARA.html[DECCARA]. However, it is limited to only a few attributes. kitty extends this to work with *all* SGR attributes. So, for example, this can be used to set the background color in -an arbitrary region of the screen. +an arbitrary region of the screen. The motivation for this extension is the various problems with the existing solution for erasing to background color, namely the *background color erase -(bce)* capability. See +(bce)* capability. See link:https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545[this discussion] -for a summary of problems with *bce*. +for a summary of problems with *bce*. For example, to set the background color to blue in a rectangular region of the screen from (3, 4) to (10, 11), you use: