Spriteful TErminal GrAphics Protocol - revision history

Dank at 07:54, 29 June 2021

2021-06-29T07:54:14Z

← Older revision		Revision as of 07:54, 29 June 2021
Line 6:		Line 6:
	* Autumn Lamonte's [https://gitlab.com/klamonte/jexer/-/wikis/jexer-images Jexer image sequence]		* Autumn Lamonte's [https://gitlab.com/klamonte/jexer/-/wikis/jexer-images Jexer image sequence]
	* ITerm2's [https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment. Image Protocol]		* ITerm2's [https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment. Image Protocol]

			'''nota bene: this was a learning exercise. as the result ended up looking a good deal like Kovid's protocol (see above), i encourage terminal developers to implement that protocol, as it is a major advance over Sixel. if you want to extend it with things discussed below, hit me up.'''

	==Goals as a toolkit developer==		==Goals as a toolkit developer==

Dank at 20:49, 25 June 2021

2021-06-25T20:49:27Z

← Older revision		Revision as of 20:49, 25 June 2021
Line 189:		Line 189:
	* There is no filesystem-based data exchange (Kitty, iTerm)		* There is no filesystem-based data exchange (Kitty, iTerm)
	* There is no terminal-side scaling (Kitty)		* There is no terminal-side scaling (Kitty)

			[[CATEGORY: Terminals]]
			[[CATEGORY: Projects]]

Dank: /* Reloads */ reject reloads from containers with different geometry

2021-06-09T05:20:52Z

Reloads: reject reloads from containers with different geometry

← Older revision		Revision as of 05:20, 9 June 2021
Line 63:		Line 63:

	===Reloads===		===Reloads===
	Reloads the specified graphic with new data. Any part of the graphic which is visible <b>must</b> be updated; this update <b>should</b> be performed without flicker. The new data must be the same geometry as the old data, but it needn't be the same format. The entirety of the data must be provided. '''FIXME we'll want some kind of animation-friendly partial reload.''' If the specified graphic does not exist, no action is taken.		Reloads the specified graphic with new data. Any part of the graphic which is visible <b>must</b> be updated; this update <b>should</b> be performed without flicker. The new data must be the same geometry as the old data, but it needn't be the same format. The entirety of the data must be provided. '''FIXME we'll want some kind of animation-friendly partial reload.''' If the specified graphic does not exist, no action is taken. If the provided data is a container, and the container yields geometry different from that associated with the existing graphic, no action is taken.

	<i>Parameters: identifier, data format, bulk data</i>		<i>Parameters: identifier, data format, bulk data</i>

Dank at 05:17, 9 June 2021

2021-06-09T05:17:48Z

← Older revision		Revision as of 05:17, 9 June 2021
Line 38:		Line 38:
	* ESC (0x1b, 27) starts a new control sequence, terminating any ongoing one. This is necessary to conform to widespread existing behavior, but it is unfortunate, as it means we can't blithely write arbitrary bytes.		* ESC (0x1b, 27) starts a new control sequence, terminating any ongoing one. This is necessary to conform to widespread existing behavior, but it is unfortunate, as it means we can't blithely write arbitrary bytes.
	** If we can discard this restriction, we can eliminate the unwieldy escaping in [[#Minimally encoded BGRA\|BGRA]], and the biasing in [[#Unencoded greyscale\|greyscale]].		** If we can discard this restriction, we can eliminate the unwieldy escaping in [[#Minimally encoded BGRA\|BGRA]], and the biasing in [[#Unencoded greyscale\|greyscale]].
			** Evaluate suggestions against the [https://vt100.net/emu/dec_ansi_parser Williams state machine]
	* We mustn't tread on any defined [https://invisible-island.net/xterm/ctlseqs/ctlseqs.html XTerm control sequences].		* We mustn't tread on any defined [https://invisible-island.net/xterm/ctlseqs/ctlseqs.html XTerm control sequences].

Dank: /* Scrolling */

2021-06-09T04:07:19Z

Scrolling

← Older revision		Revision as of 04:07, 9 June 2021
Line 146:		Line 146:
	Pixels drawn in the lowermost, rightmost cell of the visible area <b>must not</b>, in and of themselves, result in scrolling.		Pixels drawn in the lowermost, rightmost cell of the visible area <b>must not</b>, in and of themselves, result in scrolling.

	Pixels logically below the visible area must be ignored if scrolling is disabled. If scrolling is enabled (see [[#Scrolling\|below]]), such pixels must cause scrolling equivalent to the ceiling of (rows beyond the bottom / cell height), both measured in pixels. For instance, if graphics scrolling is enabled, and cells are 10 pixels tall, and the cursor is on the bottom row when the graphic is emitted, and the graphic is 32 pixels tall, the terminal ought scroll up three rows (10 can be displayed, 32 - 10 = 22, ⌈22 / 10⌉ = 3). If scrolling is disabled, the terminal <i>~~may~~</i> make such pixels visible if the visible area is made taller, ~~but this is not required~~.		Pixels logically below the visible area must be ignored if scrolling is disabled. If scrolling is enabled (see [[#Scrolling\|below]]), such pixels must cause scrolling equivalent to the ceiling of (rows beyond the bottom / cell height), both measured in pixels. For instance, if graphics scrolling is enabled, and cells are 10 pixels tall, and the cursor is on the bottom row when the graphic is emitted, and the graphic is 32 pixels tall, the terminal ought scroll up three rows (10 can be displayed, 32 - 10 = 22, ⌈22 / 10⌉ = 3).

			If scrolling is disabled, the terminal <b>must not</b> make such pixels visible if the visible area is made taller. Rationale: this could result in graphics being drawn over prompts, to the confusion of the user.

	==Terminal obligations==		==Terminal obligations==

Dank at 04:04, 9 June 2021

2021-06-09T04:04:52Z

← Older revision		Revision as of 04:04, 9 June 2021
Line 5:		Line 5:
	* Kovid Goyal's [https://sw.kovidgoyal.net/kitty/graphics-protocol.html Kitty graphics protocol]		* Kovid Goyal's [https://sw.kovidgoyal.net/kitty/graphics-protocol.html Kitty graphics protocol]
	* Autumn Lamonte's [https://gitlab.com/klamonte/jexer/-/wikis/jexer-images Jexer image sequence]		* Autumn Lamonte's [https://gitlab.com/klamonte/jexer/-/wikis/jexer-images Jexer image sequence]
	* ITerm2's [https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment.\|Image Protocol]		* ITerm2's [https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment. Image Protocol]

	==Goals as a toolkit developer==		==Goals as a toolkit developer==

Dank at 04:04, 9 June 2021

2021-06-09T04:04:30Z

← Older revision		Revision as of 04:04, 9 June 2021
Line 1:		Line 1:
	STEGAP is my (incomplete!) proposal for a terminal graphics protocol facilitating bitmapped sprites combined with terminal glyphs and styling. Just being able to blit a bitmap into a terminal is of little use for libraries like [[Notcurses]]. Unfortunately, that's about all that Sixel gives you. Useful background reading might include my [[Theory and Practice of Sprixels]].		STEGAP is my (incomplete!) proposal for a terminal graphics protocol facilitating bitmapped sprites combined with terminal glyphs and styling. Just being able to blit a bitmap into a terminal is of little use for libraries like [[Notcurses]]. Unfortunately, that's about all that Sixel gives you. Useful background reading might include my [[Theory and Practice of Sprixels]].

			Previous work includes:
			* DEC's Sixel protocol, the most widely-implemented (and poorly-specified) of the bunch
			* Kovid Goyal's [https://sw.kovidgoyal.net/kitty/graphics-protocol.html Kitty graphics protocol]
			* Autumn Lamonte's [https://gitlab.com/klamonte/jexer/-/wikis/jexer-images Jexer image sequence]
			* ITerm2's [https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment.\|Image Protocol]

	==Goals as a toolkit developer==		==Goals as a toolkit developer==

Dank: /* Beyond the visible area */

2021-06-09T04:01:41Z

Beyond the visible area

← Older revision		Revision as of 04:01, 9 June 2021
Line 117:		Line 117:
	Pixels above the top of the visible area must be ignored.		Pixels above the top of the visible area must be ignored.

	Pixels beyond the bottom of the visible area depend on whether [[#Scrolling]] is in play.		Pixels beyond the bottom of the visible area depend on whether [[#Scrolling\|scrolling]] is in play.

	==Graphic placement==		==Graphic placement==

Dank: /* Graphic placement */

2021-06-08T07:32:31Z

Graphic placement

← Older revision		Revision as of 07:32, 8 June 2021
Line 123:		Line 123:
	* LTR: graphics are placed with their topmost, leftmost pixel at the current location of the cursor, starting in the top left pixel of the cell.		* LTR: graphics are placed with their topmost, leftmost pixel at the current location of the cursor, starting in the top left pixel of the cell.
	* RTL: graphics are placed with their topmost, rightmost pixel at the current location of the cursor, starting in the top right pixel of the cell.		* RTL: graphics are placed with their topmost, rightmost pixel at the current location of the cursor, starting in the top right pixel of the cell.
	* If text is being drawn top-to-bottom, you can fuck off.		* If text is being drawn top-to-bottom, you can fuck off for now (and probably already are).

	Two arguments allow for pixel offsets to be applied to this implicit origin; the offsets may be negative. Note that this might lead to a negative horizontal and/or vertical coordinate for the graphic's origin; see [[#Beyond the visible area\|above]] to deal with this situation.		Two arguments allow for pixel offsets to be applied to this implicit origin; the offsets may be negative. Note that this might lead to a negative horizontal and/or vertical coordinate for the graphic's origin; see [[#Beyond the visible area\|above]] to deal with this situation.

Dank: /* Coexistence with other graphics protocols */

2021-06-08T07:31:51Z

Coexistence with other graphics protocols

← Older revision		Revision as of 07:31, 8 June 2021
Line 157:		Line 157:
	'''FIXME operating parameters?'''		'''FIXME operating parameters?'''

	===Coexistence with other graphics protocols===		===Coexistence with text and other graphics protocols===
	'''FIXME'''		'''FIXME'''