This document is an updated proposal to address feedback on the first
proposal, which included: "overengineered", "hopelessly
-overengineered", and "unnecessarily complex."
+overengineered", and "unnecessarily complex." I perceive this
+feedback as a positive: it is far easier to imagine a feature and
+remove it, than to fail to picture it and need to shoehorn it in
+later.
-I perceive this feedback as a positive: it is far easier to imagine a
-feature and remove it, than to fail to picture it and need it later.
The original proposal was a superset of every image format referenced,
and generalized beyond to multimedia. This proposal is sharply
reduced from that to: "put this pixel rectangle from the image, into
that cell-based rectangle with specific scaling policy". It is mostly
-a subset of the iTerm2 protocol, with specifications for what happens
-to the cursor, and more precise definitions of the
-"preserveAspectRatio" equivalent options.
+a subset of the iTerm2 protocol, with:
+
+* Specifications for what happens to the cursor.
+
+* More precise definitions of the "preserveAspectRatio" equivalent
+ options.
+
+* Explicit restriction to a Cell-based target region.
+
+* Definition that pixels not covered by image are set to the current
+ background color.
3. Elimination of response codes, and with it:
- The ability for multiplexers to blindly pass on the sequences to
- their host terminal.
+ their host terminal (because unique IDs are not generated by the
+ terminal).
- The ability for applications to reliably detect success or
failure of image display operations.
- The pixels are drawn starting at the upper-left corner of the text
cursor position.
+ - All pixels in the target Cell rectangle that are not covered by
+ the image itself are set the current background color (like
+ sixel raster attributes).
+
- If scroll is specified as 1 (enabled), then:
a. The screen is scrolled up if the image overflows into the
- Pixels that would be drawn to the right of the visible region on
screen are discarded.
+ - If scale is "none", then pixels that would be drawn outside the
+ target Cell rectangle are discarded.
+
The keys for the key-value pairs that must be supported by the
terminal are listed below:
-| Key | Default Value | Description |
-|--------------|---------------|----------------------------------------------|
-| type | "image/rgb" | mime-type describing data field |
-| width | 1 | Number of Cells or pixels wide to display in |
-| height | 1 | Number of Cells or pixels high to display in |
-| scale | "none" | Scale/zoom option, see below |
-| sourceX | 0 | Media source X position to display |
-| sourceY | 0 | Media source Y position to display |
-| sourceWidth | "auto" | Media width in pixels to display |
-| sourceHeight | "auto" | Media height in pixels to display |
-| scroll | 0 | If 0, scroll the display if needed |
+| Key | Default Value | Description |
+|--------------|---------------|---------------------------------------|
+| type | "image/rgb" | mime-type describing data field |
+| width | 1 | Number of Cell columns to display in |
+| height | 1 | Number of Cells rows to display in |
+| scale | "none" | Scale/zoom option, see below |
+| sourceX | 0 | Media source X position to display |
+| sourceY | 0 | Media source Y position to display |
+| sourceWidth | "auto" | Media width in pixels to display |
+| sourceHeight | "auto" | Media height in pixels to display |
+| scroll | 0 | If 0, scroll the display if needed |
A terminal may support additional keys. If a key is specified but not
supported by the terminal, then it is ignored without error.
A terminal with cached images feature must support the following new
sequences:
-| Sequence | Command | Description |
-|--------------------------------------|-----------|-------------------------|
-| OSC 1 3 4 0 ; F i l e = {args} : {data} BEL | CSTORE | Display media at (x, y) |
-| OSC 1 3 4 1 ; Pi ; {args} ST | CDISPLAY | Display media at (x, y) |
+| Sequence | Command | Description |
+|--------------------------------------|-----------|--------------------------|
+| OSC 1 3 4 0 ; F i l e = {args} : {data} BEL | CSTORE | Store image in cache |
+| OSC 1 3 4 0 ; F i l e = {args} : {data} ST | CSTORE | Store image in cache |
+| OSC 1 3 4 1 ; Pi ; {args} BEL | CDISPLAY | Display image at (x, y) |
+| OSC 1 3 4 1 ; Pi ; {args} ST | CDISPLAY | Display image at (x, y) |
The keys for the key-value pairs that must be supported by the
terminal are listed below:
-| Key | Default Value | Description |
-|--------------|---------------|----------------------------------------------|
-| id | 0 | ID to refer to the image |
-| width | 1 | Number of Cells or pixels wide to display in |
-| height | 1 | Number of Cells or pixels high to display in |
-| scale | "none" | Scale/zoom option, see below |
-| sourceX | 0 | Media source X position to display |
-| sourceY | 0 | Media source Y position to display |
-| sourceWidth | "auto" | Media width in pixels to display |
-| sourceHeight | "auto" | Media height in pixels to display |
-| scroll | 0 | If 1, scroll the display if needed |
+| Key | Default Value | Description |
+|--------------|---------------|---------------------------------------|
+| id | 0 | ID to refer to the image |
+| width | 1 | Number of Cell columns to display in |
+| height | 1 | Number of Cells rows to display in |
+| scale | "none" | Scale/zoom option, see below |
+| sourceX | 0 | Media source X position to display |
+| sourceY | 0 | Media source Y position to display |
+| sourceWidth | "auto" | Media width in pixels to display |
+| sourceHeight | "auto" | Media height in pixels to display |
+| scroll | 0 | If 1, scroll the display if needed |
A terminal may support additional keys. If a key is specified but not
supported by the terminal, then it is ignored without error.
"sourceHeight" can be "auto", which means use the maximum available
width/height (given sourceX/sourceY) from the media's inherent
dimensions.
+
+
+
+Miscellaneous Items
+-------------------
+
+"image/rgb" and "image/rgba" also need width/height fields. Propose
+to specify them as 16-bit unsigned ints, followed by 24-bit or 32-bit
+data. If data is short, then the rest of the image is assumed to be
+current background color (like sixel raster attributes).