WIP EVO DOC

Author: adriweb

evo-doc/8ca2-background-image.md

@@ -1,6 +1,10 @@
 # `.8ca2` background images
 
-Sample files: `Image1.8ca2` through `Image7.8ca2`.
+Sample files:
+
+- `Image1.8ca2` through `Image7.8ca2`
+- `testData/evo/img_compare/background.8ca2`
+- `testData/evo/img_compare/background_ticonnectevo.8ca2`
 
 Metadata:
 
@@ -31,10 +35,25 @@ size    = 33601
 data    = byte string, length 33601
 ```
 
+We have a hard-coded CBOR prefix of 70 bytes long before the RGB565 pixel data:
+
+```text
+BF                                      top-level map(*)
+  "metaData": BF
+    "type":    5
+    "version": 1
+    "flags":   1
+    "name":    44 B0 E8 00 00          Image1 token, patched per slot
+  FF
+  "version": 1
+  "size":    0x8341                    33601
+  "data":    59 83 41 0B ...           byte string, first byte marker
+```
+
 The image data byte string is:
 
 ```text
-data[0]      image-format marker; 0x16 in the provided samples
+data[0]      image-format marker
 data[1..]    33600 bytes of RGB565 pixel data
 ```
 
@@ -48,7 +67,9 @@ format = RGB565, little-endian words
 ```
 
 The converter draws the input image onto a 160 by 105 white canvas,
-converts RGBA8888 to RGB565, then writes rows bottom-to-top:
+preserving aspect ratio and centering the result. It disables canvas
+image smoothing, converts RGBA8888 to RGB565, then writes rows
+bottom-to-top:
 
 ```text
 stored row 0   = source/display row 104
@@ -68,4 +89,10 @@ let g6 = (word >> 5) & 0x3f;
 let b5 = word & 0x1f;
 ```
 
-It seems `0x0b` is the first data byte made by the converter but all provided calculator files use `0x16`?
+Observed data markers:
+
+```text
+0x0B  TI Connect Evo image import output
+0x16  calculator/exported samples and img2calc-generated output
+```
+

evo-doc/8ci2-picture.md

@@ -0,0 +1,87 @@
+# `.8ci2` pictures
+
+Sample files:
+
+- `Pic1.8ci2` through `Pic6.8ci2`
+- `testData/evo/img_compare/Zelda.8ci2`
+
+Metadata:
+
+```text
+metaData.type    = 4
+metaData.version = 1
+metaData.flags   = 1
+metaData.name    = Pic token, little-endian, then 0000
+```
+
+Observed Pic name tokens:
+
+```text
+Pic1  E880 TOK_VAR_PIC1
+Pic2  E881 TOK_VAR_PIC2
+Pic3  E882 TOK_VAR_PIC3
+Pic4  E883 TOK_VAR_PIC4
+Pic5  E884 TOK_VAR_PIC5
+Pic6  E885 TOK_VAR_PIC6
+```
+
+The token table also defines `Pic7` through `Pic9` and `Pic0`:
+
+```text
+Pic7  E886 TOK_VAR_PIC7
+Pic8  E887 TOK_VAR_PIC8
+Pic9  E888 TOK_VAR_PIC9
+Pic0  E889 TOK_VAR_PIC0
+```
+
+Body fields:
+
+```text
+version = 1
+size    = 33441
+data    = byte string, length 33441
+```
+
+Observed data layout:
+
+```text
+data[0]      picture-format marker; 0x0F in the provided samples
+data[1..]    33440 bytes of packed pixel data
+```
+
+`33440 = 160 * 209`, which is 209 rows with 160 bytes per row. Each
+byte stores two 4-bit pixels, so the pixel geometry is:
+
+```text
+width  = 320 pixels
+height = 209 pixels
+bpp    = 4
+stride = 160 bytes per row
+```
+
+img2calc generates type `4` `.8ci2` files with this layout:
+
+```text
+size = 33441
+data = 0F followed by 33440 packed 4-bpp bytes
+```
+
+For each output byte, img2calc writes the left pixel in the high nibble
+and the right pixel in the low nibble:
+
+```text
+byte = (left_palette_index << 4) | right_palette_index
+```
+
+For `.8ci2`, img2calc writes rows top-to-bottom: output byte 0 is the
+leftmost two pixels of display row 0. This differs from img2calc's
+`.8ca2` path, where it vertically flips while reading the RGB pixels, so
+the stored RGB565 payload is bottom-to-top.
+
+The sample bytes are packed 4-bit color indices:
+
+```text
+byte 0x03  two pixels: color 0, color 3
+byte 0x30  two pixels: color 3, color 0
+byte 0x33  two pixels: color 3, color 3
+```

evo-doc/8xl2-list.md

@@ -24,7 +24,10 @@ L6  E835 TOK_VAR_LIST_6
 
 Custom named lists use `TOK_VAR_LIST_NAME` followed by variable-letter
 tokens, then `0000`. The user-facing list marker `(L)` is not stored as
-an ordinary `L` character; it is represented by `E836`.
+an ordinary `L` character; it is represented by `E836`. The calculator
+UI allows custom list names up to five letters; the exported files
+currently present in the sample tree include one-letter, three-letter,
+and generated formula-list names.
 
 Examples:
 

evo-doc/8xn2-number.md

@@ -11,6 +11,12 @@ metaData.flags   = 0 or 8 in the samples
 metaData.name    = variable token, little-endian, then 0000
 ```
 
+The observed `metaData.flags = 8` top-level samples are `X.8xn2` and
+`Y.8xn2`. The same metadata flag appears on nested `XMIN`, `XMAX`,
+`YMIN`, and `YMAX` entries in `Window.8xw2`. This appears tied to
+special graph/window coordinate variables, not to the scalar data format
+itself.
+
 Body fields:
 
 ```text

evo-doc/8xp2-program.md

@@ -188,3 +188,58 @@ PREC.8xp2:
 ```
 
 `PREC.8xp2` contains `TOK_COLON` (`E418`) for multiple statements on one source line.
+
+## Additional token samples
+
+The `more/seq` samples confirm that program data remains a plain
+little-endian 16-bit token stream even for sequence and graph-related
+commands.
+
+`prgm_only_seq_command.8xp2` has program name `A` and contains only:
+
+```text
+E44D TOK_SERIES
+0000 TOK_EOS
+```
+
+`missing2.8xp2` has program name `B`:
+
+```text
+E6C6 TOK_RECV_MBL
+E41C TOK_NEW_LINE
+E6C7 TOK_SEND_MBL
+E41C TOK_NEW_LINE
+E593 TOK_MGT
+E41C TOK_NEW_LINE
+E4F9 TOK_DEL_LAST
+0000 TOK_EOS
+```
+
+`missing.8xp2` has program name `A` and includes one token per line for
+several sequence-window variables and commands:
+
+```text
+E9A3 TOK_VAR_UTHETA_MIN
+E9A4 TOK_VAR_UTHETA_MAX
+E9A6 TOK_VAR_UT_MIN
+E9A7 TOK_VAR_UT_MAX
+E9AC TOK_VAR_UN_MAX
+E9AA TOK_VAR_UN_MIN
+E9A8 TOK_VAR_UT_STEP
+E9A5 TOK_VAR_UTHETA_STEP
+E9B0 TOK_VAR_UPLOT_STEP
+E99F TOK_VAR_UXRES
+E59C TOK_AUTO_FILL_ON
+E59D TOK_AUTO_FILL_OFF
+E59E TOK_AUTO_CALC_ON
+E59F TOK_AUTO_CALC_OFF
+E600 TOK_DRAWLINE
+E601 TOK_DRAWDOT
+E60A TOK_WEBOFF
+E41A TOK_APOST
+E499 TOK_DT
+0000 TOK_EOS
+```
+
+Every entry except the last is followed by `E41C TOK_NEW_LINE` in the
+file.

evo-doc/8xt2-table-setup.md

@@ -13,7 +13,8 @@ metaData.name    = E8BC 0000
 
 `E8BC` is `TOK_VAR_TBLSETUP`.
 
-The top-level body contains:
+The top-level body has no scalar `version` or `size` fields in the
+sample. It contains:
 
 ```text
 data = indefinite CBOR array of nested custom scalar entries
@@ -52,5 +53,7 @@ TBL_STEP:
   data words = 0001 0001 001F
 ```
 
-The custom scalar encoding matches the exact integer-like samples in `.8xn2`.
-
+The custom scalar encoding matches the exact integer-like samples in
+`.8xn2`. The top-level settings container owns the array; only the
+nested type `17` entries have scalar `version`, `flags`, `arraylen`,
+`size`, and `data` fields.

evo-doc/8xv2-appvar.md

@@ -20,7 +20,10 @@ data    = app-specific byte string
 ```
 
 Unlike `.8xp2` and `.8xy2`, the appvar data is not a generic TI-BASIC
-token stream. It is owned by the corresponding app or system feature.
+token stream and has no `arraylen` field. It is owned by the
+corresponding app or system feature. Readers should treat the payload as
+opaque unless they implement the specific appvar subtype, and writers
+should preserve it byte-for-byte when round-tripping.
 
 ## `PolyCnfg.8xv2`
 
@@ -57,4 +60,3 @@ data = 08 53 53 4f 01 01 01 00 96 e5 82 e5 85 e5 87 e5
 ```
 
 The ASCII bytes at `data[1..3]` spell `SSO`.
-

evo-doc/8xw2-window.md

@@ -25,7 +25,7 @@ Each nested entry is itself a CBOR map with:
 ```text
 metaData.type    = 17
 metaData.version = 1
-metaData.flags   = 0
+metaData.flags   = 0 or 8
 metaData.name    = setting token, little-endian, then 0000
 
 version   = 1
@@ -38,11 +38,11 @@ data      = custom scalar payload
 Observed `Window.8xw2` entries:
 
 ```text
-00  E98F TOK_VAR_XMIN         size 12
-01  E990 TOK_VAR_XMAX         size 12
+00  E98F TOK_VAR_XMIN         metaData.flags 8, size 12
+01  E990 TOK_VAR_XMAX         metaData.flags 8, size 12
 02  E991 TOK_VAR_XSCL         size 6
-03  E993 TOK_VAR_YMIN         size 12
-04  E994 TOK_VAR_YMAX         size 12
+03  E993 TOK_VAR_YMIN         metaData.flags 8, size 12
+04  E994 TOK_VAR_YMAX         metaData.flags 8, size 12
 05  E995 TOK_VAR_YSCL         size 6
 06  E992 TOK_VAR_X_RES        size 6
 07  E9B2 TOK_VAR_DELTA_X      size 12
@@ -80,6 +80,6 @@ THETA_MAX:
 ```
 
 The nested scalar `data` encoding matches the `.8xn2` custom scalar
-shape, but the semantic mapping of all numeric words is still under
-investigation.
-
+shape. The observed nested `metaData.flags = 8` values are limited to
+the X/Y min/max coordinate variables in this sample. Other window
+variables use `metaData.flags = 0`.

evo-doc/8xy2-equation.md

@@ -11,6 +11,10 @@ metaData.flags   = 4 in the sample
 metaData.name    = equation token, little-endian, then 0000
 ```
 
+The body has no `flags` key. The observed metadata flag `4` appears to
+belong to equation graph/display state rather than to the expression
+token stream. More equation samples are needed before naming this bit.
+
 For `Y1.8xy2`:
 
 ```text
@@ -63,4 +67,3 @@ an expression rather than a multi-line program.
 26 E411 TOK_RPAREN
 27 0000 TOK_EOS
 ```
-

evo-doc/8xz2-rclwindw.md

@@ -14,14 +14,28 @@ metaData.name    = E8BB 0000
 `E8BB` is labeled `TOK_VAR_ZSTO` in the token table and displayed by
 the web app as `RclWindw` / user zoom.
 
-The top-level body contains:
+The top-level body has no scalar `version` or `size` fields in the
+sample. It contains:
 
 ```text
 data = indefinite CBOR array of nested custom scalar entries
 ```
 
 Each nested entry uses `metaData.type = 17` and the same custom scalar
-layout as `.8xn2` number data.
+layout as `.8xn2` number data:
+
+```text
+metaData.type    = 17
+metaData.version = 1
+metaData.flags   = 0
+metaData.name    = setting token, little-endian, then 0000
+
+version   = 1
+flags     = 0
+arraylen  = number of 16-bit words in data
+size      = byte length of data; equals arraylen * 2
+data      = custom scalar payload
+```
 
 Observed entries:
 
@@ -63,4 +77,3 @@ UTHETA_MAX:
 UTHETA_STEP:
   00 57 99 38 69 99 08 13 01 ff 23 00
 ```
-