X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;f=docs%2Fimages2.md;h=26268cf5d884c7a5b0f9276ebfac682180f0f15b;hb=03f6ef47b94f4db8f7d19ca1f3fec3a0edc10ed1;hp=34c13418a959e260e2ef0530c540a833e1ecf9c0;hpb=9a1dfe2bd9a0a1310b05ea0cd5aade5c2536b547;p=fanfix.git diff --git a/docs/images2.md b/docs/images2.md index 34c1341..26268cf 100644 --- a/docs/images2.md +++ b/docs/images2.md @@ -13,17 +13,26 @@ definitions. 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. @@ -47,7 +56,8 @@ in this revised proposal are: 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. @@ -172,6 +182,10 @@ For the OSC 1 3 3 8 sequence: - 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 @@ -195,22 +209,25 @@ For the OSC 1 3 3 8 sequence: - 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. @@ -329,10 +346,12 @@ Cached Images - New Sequences 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) | @@ -444,17 +463,17 @@ For the CDISPLAY command: 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. @@ -493,3 +512,13 @@ is displayed, and the cursor does not move. "sourceWidth" and "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).