Files
openhmi-nx/docs/FORMAT.md
T

497 lines
26 KiB
Markdown
Raw Normal View History

# The Nextion Editor `.HMI` project format
Verified against **Nextion Editor 1.68.2 (build 1.68.2.3035)**. Reverse-engineered black-box: by editing projects in Nextion Editor, saving, and comparing
files, and by asking the Editor whether hand-made files load ("oracle" tests). The Editor itself was
never decompiled or decrypted. Everything here was checked against real files; open points are
marked **OPEN**.
All integers are little-endian.
## 1. Container
An `.HMI` file is a tiny file system.
| Offset | Contents |
|---|---|
| `0x000000` | file table: `count` (u32), `count` × 28-byte entries, then the table checksum (u32) |
| `0x080000` | backup copy of the file table (byte-identical, incl. checksum) |
| `0x380000` | u32 `0xFFFFFFFF` |
| `0x6FFFF8` | ASCII `ver21234` |
| `0x700000` | entry data, packed back to back |
The space between these areas is normally zero (older files can contain stale data, e.g. at
`0x100000`, which is ignored).
### File table entry (28 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 16 | name, NUL padded (`main.HMI`, `Program.s`, `0.pa`, `0.i`, `0.is`, `0.zi`, ...) |
| 16 | 4 | start offset in the file |
| 20 | 4 | size |
| 24 | 1 | deleted flag |
| 25 | 3 | unknown (looks like uninitialised memory; **is** covered by the table checksum) |
When the Editor replaces an entry it appends the new data to the end of the file, adds a new
entry, and marks the old entry deleted: deleted flag = 1 **and first byte of the name = 0**
(e.g. `\0ain.HMI`). The Editor finds entries by name, so setting only the flag is not enough.
Deleted entries stay in the table and their data stays in the file.
If the primary table's checksum fails the Editor silently uses the backup table. If both fail it
reports "Version mismatch". The Editor also rewrites a file when opening it (it repairs the
primary table from the backup, among other things) -- never reuse a test file after opening it.
### Entry names
| Name | Contents |
|---|---|
| `main.HMI` | project header (display model, resource list) -- 224 bytes |
| `Program.s` | start-up script, plain text (no checksum) |
| `N.pa` | page N |
| `N.i` | picture N as the display uses it (section 4) |
| `N.is` | picture N's original source file (section 4) |
| `N.zi` | font N (section 5) |
### `main.HMI` (project header)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (section 2) |
| 4 | 4 | header size = 0x60 = start of the resource list |
| 8 | 1 | 1 (**OPEN**) |
| 9 | 1 | 0x41 in a 2019 file, 0x44 after saving with Editor 1.68 (Editor/format revision?) |
| 10 | 1 | 0x21 |
| 11 | 1 | display series: 0 = Basic (T), 1 = Enhanced (K), 3 = Intelligent (P), 6 = Edge (E), 100 = Discovery (F) |
| 12 | 1 | display direction in 90° steps (Setting > Display: 0 = 0°, 1 = 90°, 2 = 180°, 3 = 270°). Basic panels are portrait at 0°, so a 480×320 Basic project has 1; Intelligent panels are landscape at 0°. Page sizes follow (the Editor shows a 480×272 Intelligent project with 1 as 272×480). An unsupported value made the Editor fail to load ("'null' is not a supported encoding name") |
| 13 | 1 | character encoding (Setting > Display): 1 ascii, 2 gb2312, 3 iso-8859-1, 4-11 iso-8859-2..9, 12 iso-8859-13, 13 iso-8859-15, 14 iso-8859-11, 15 ks_c_5601-1987, 16 big5, 17-20 windows-1255..1258, 21 windows-874, 22 koi8-r, 23 shift-jis, 24 utf-8 (all measured; `models.ENCODINGS`) |
| 14 | 1 | 0x4F |
| 16 | 4 | model id (e.g. 0xB23BC018 NX4832T035_011, 0x181169DA NX4827P043_011); must match the series byte, otherwise the Editor falls back to its first model |
| 24 | 4 | 0x60 |
| 28 | 4 | resource count |
| 36 | 4 | 1 or 2 (**OPEN**) |
| 0x41 | 1 | 3 after switching to an Intelligent model (**OPEN**) |
| 0x60 | 16 × count | resource list: type[8] + name[8], e.g. `pa`/`3.pa`, `i`/`0.i`, `zi`/`0.zi` |
Adding a page = new `N.pa` entry + one resource-list entry + count + 1 + new checksum (verified:
the Editor shows pages added this way). `.is` entries are not listed.
## 2. Checksums
All three use CRC-32 with polynomial `0x04C11DB7`, MSB-first (not reflected), initial value
`0xFFFFFFFF`, no final XOR -- the algorithm of the STM32 hardware CRC unit. They differ in how
input is fed.
### Page checksum (first 4 bytes of every `N.pa`)
Every input **byte** is zero-extended to a 32-bit word and fed as one word. Input:
```
page[4:] # whole page after the checksum field
+ datasize (4 bytes, LE) # = page header offset 4
+ numberobj (4 bytes, LE) # = page header offset 12
+ page[20] + page[21] # header bytes 20 and 21
```
Evidence: two saves differing in one bit place that bit's influence at `x^(32·k)` -- adjacent file
bytes are exactly 32 bits apart in the CRC stream; a fixed 10-word tail appears after the page;
the tail contents were solved over pages of different lengths and component counts; then
verified on 276 Editor-written pages (including a 2019 file) and by the Editor accepting pages
built from scratch.
### `main.HMI` checksum (first 4 bytes)
Same word-per-byte scheme. Input: `main[4:] + main[16:20] + main[4:8] + main[10] + main[14]`.
**OPEN**: the last two tail bytes were 0x21, 0x4F in every sample; they may be constants (they equal
the page header's "version" bytes) rather than fields.
### File table checksum (u32 right after the last entry)
Input read as **little-endian 32-bit words**: the table from `count` through the last entry, then
the constant word `0x43454441` (ASCII "ADEC").
## 3. Pages (`N.pa`)
### Header (56 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (above) |
| 4 | 4 | datasize = total page length |
| 8 | 4 | infoaddr = 56 (start of component table) |
| 12 | 4 | numberobj = component count |
| 16 | 4 | password |
| 20 | 1 | locked |
| 21 | 1 | 0x4F in every file seen (**OPEN**) |
| 22 | 1 | 0x21 (33) in every file seen -- format version? |
| 23 | 1 | 0 (**OPEN**) |
| 24 | 16 | page name |
| 40 | 16 | reserved (zero) |
### Component table
`numberobj` entries of `(u32 offset, u32 size, u32 unknown=0)`. Offset is relative to byte 56.
The page itself is component 0.
### Component data
A sequence of records `u32 length + bytes`, ending with an empty record. Records are grouped:
a header record `"<group>-<n>"` is followed by n records.
* `att-<n>`: attributes. Each record = 16-byte NUL-padded name + value. Integers are unsigned
LE of 1, 2 or 4 bytes (`val` has a different width per component type); `objname`, `txt`
(and other text attributes) are raw text in the project encoding (iso-8859-1 by default).
* `codes<event>-<n>`: event code, one record per line. Seen: `codesload` (preinitialize),
`codesloadend` (postinitialize), `codesdown` (touch press), `codesup` (touch release),
`codesunload` (page exit), `codestimer`, `codesslide` (slider move).
Attribute names seen so far: `aph bco bco1 bco2 borderc borderw ch dis disup down drag effect en
endx endy first font format groupid0 groupid1 h hig id isbr key left lenth lockobj maxval minval
mode movex movey objname pco pco2 pic pic1 pic2 picc picc1 picc2 psta pw right sendkey spax spay
sta style tim time txt txt_maxl type up val vscope w wid x xcen y ycen`.
Text attributes are `objname` and every attribute that has a length-limit companion in the same
component (`txt`/`txt_maxl`, `path`/`path_m`, `dir`/`dir_m`, `filter`/`filter_m`,
`format`/`format_m`, `vvs2`/`vvs2_m`). The same name can be a number elsewhere (`dir` is a u8 on
scrolling text, `format` a u8 on number).
Component `type` values (all placed in Editor 1.68; full default attribute lists in
`src/nxhmi/templates_*.json`):
| type | component | | type | component |
|---|---|---|---|---|
| 0 | waveform | | 59 | xfloat |
| 1 | slider | | 60 | ExPicture * |
| 2 | Gmov * | | 61 | ComboBox * |
| 3 | Video * | | 62 | SLText * |
| 4 | Audio * | | 63 | FileStream * |
| 5 | TouchCap | | 65 | FileBrowser * |
| 51 | timer | | 66 | DataRecord * |
| 52 | variable | | 67 | Switch * |
| 53 | dual-state button | | 68 | TextSelect * |
| 54 | number | | 98 | button |
| 55 | scrolling text | | 106 | progress bar |
| 56 | checkbox | | 109 | hotspot |
| 57 | radio | | 112 | picture |
| 58 | QRcode | | 113 | crop |
| 116 | text | | 121 | page |
| 122 | gauge | | | |
\* Intelligent series only. Attribute sets of shared types are identical on Basic and Intelligent
projects. `sta` on pages/texts: 1 = solid colour, 2 = picture.
## 4. Pictures
`N.is` = 27-byte header + the original image file, untouched (verified byte-identical with the
PNG that was imported):
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0A 64 01 01` |
| 8 | 4 | data offset = 27 |
| 12 | 2+2 | width, height |
| 16 | 4 | length of the embedded file |
| 24 | 3 | file type, e.g. `png` |
`N.i` = 24-byte header + pixels:
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0A+direction, quality, 01, <format>` -- 0 = raw RGB565 (Basic, Enhanced), 3 = raw with a 20-byte zero header (Discovery), 4 = run-length or JPEG (Intelligent, Edge) |
| 8 | 4 | data offset = 24 |
| 12 | 2+2 | width, height |
| 16 | 4 | data length (format 0: w × h × 2) |
Format 0: RGB565 little-endian, converted by plain truncation (`r>>3, g>>2, b>>3`), stored in the
panel's native scan order -- column by column, each column bottom-to-top:
`offset = 2 * (x * height + (height - 1 - y))`. Verified pixel-exact (480×320 and 64×64, Editor
output byte-identical to ours). The order follows the display direction, see format 4.
Per series (measured by letting Editor 1.68 convert our pictures/fonts in each series):
| Series | Picture format | Stored direction (pictures and fonts) | Font glyph data |
|---|---|---|---|
| Basic, Enhanced | 0 | project direction | unpadded |
| Intelligent | 4 | project direction | 8-byte aligned |
| Edge | 4 (same encoder, same rules, also the JPEG variant for quality < 100) | project direction | unpadded (accepted as is) |
| Discovery | 3: 20 zero bytes, then raw RGB565 | always 0 (row by row), whatever the project direction | 8-byte aligned |
Discovery, Enhanced and Edge offer the 20 Basic component types (the Intelligent-only ones are
greyed out) with exactly the Basic default attributes; Enhanced and Edge draw like Basic on the
canvas (3D frame order, colours).
Format 4 (Intelligent series) -- decoded and re-encoded byte-identically (28 Editor samples, all
four directions, with and without alpha):
- Header as above; byte 0 = 0x0A + display direction (also for format 0: a landscape Basic
project, direction 1, writes 0x0B); +16 data length; +20 offset of the alpha section within the
data (0 = opaque picture).
- Pixel order: the picture rotated by the display direction (`pictures.stored_order`): 0 = row
by row, 1 = column by column bottom to top (same as format 0 on Basic), 2 = 180°, 3 = columns
from the right, top down.
- Data: u32 1, u32 stored width, u32 stored height (swapped for directions 1/3), u32 0, u32 0,
then blocks. A block is a u32 control word of eight 4-bit ops (low nibble first):
- `1`..`13`: run of that many pixels in the colour of the op's slot (slot = nibble index);
- `14`: run of N pixels, N in the next three nibbles (12 bits), colour of the op's slot;
- `15`: N literal pixels (N in the next three nibbles); their colours follow the control
word and end the block;
- `0`: nothing.
Run blocks carry 8 colour slots (RGB565 LE) after the control word; the last block is padded
with zero slots to 8.
- How the Editor encodes: split the pixels into runs of one colour of at most 13; pack 8 runs
per block; a block of eight 13-runs of one colour becomes op 14 (consecutive such blocks merge,
N = 104 × blocks, at most 39). Busy stretches become literal pixels: when the next block would
have at least 7 runs covering at most 10 pixels (and 8+ pixels are left), the next **8 pixels**
go into a literal block, and this repeats (merging) while the condition holds (12 designed run
patterns, plus the 28 samples).
- Alpha section: 7-bit alpha (`a * 127 // 255`) per pixel in storage order, run-length coded --
a byte with bit 7 set is one pixel of alpha `b & 0x7F`, otherwise `b` is the alpha and the next
byte the run length (≤ 255). Fully transparent pixels store colour 0.
- Pictures of 1-2 pixels stay format 0 (seen: 1x1, 2x1, 1x2; 8x1 is converted); nxhmi does the
same. The Editor shows a message box per picture while converting format-0 pictures it finds
in an Intelligent project.
- Compressed quality (picture list right-click > "Compressed quality setting", 1-99; shown as
"Q:nn"): header byte 1 = quality (100 = 0x64 for the run-length variant). Data: u32 **0**
(JPEG), u32 width and height padded up to multiples of 16, u32 0, u32 0, then a baseline JPEG
of the padded picture (black padding at the right/bottom, *then* rotated into stored order),
4:2:0, 96 dpi JFIF -- byte-identical to libjpeg (Pillow) at that quality for opaque pictures
(18/18 samples: qualities 1/30/50/99, landscape and portrait). Then, if the picture has alpha,
the same alpha run section, covering the *padded* picture (padding alpha 0), at the offset in
header +20. With alpha the Editor first passes the colours through premultiplied alpha; nxhmi
approximates that step (JPEG a few levels off in some pixels; alpha section identical). The
simulator decodes the JPEG like libjpeg (opaque pictures render pixel-exact); transparent ones
blend within 1 level.
Adding a picture = `N.is` + `N.i` + a `i`/`N.i` resource-list entry (kept grouped with the other
`i` entries) -- verified in the Editor.
## 5. Fonts (`N.zi`, format version 6)
Header 44 bytes: magic `04 FF 00` + `0x0A + display direction` (like pictures), u16 encoding (3 = iso-8859-1), u8 width, u8 height,
multi-byte range (2 bytes), code range first/last, u32 character count, u8 version = 6,
u8 name length (twice) + 0, u32 length of name+map+glyphs, u32 name offset = 0x2C, 16 unknown
bytes. Then the name, the character map, the glyph data.
Header byte 0x1E = 1 when the Font Creator's "Anti-aliasing of fonts" box was ticked. Such fonts
still hold 1-bit glyphs (Windows' thinner anti-aliased outline, thresholded); the Intelligent
simulator draws them with two colours only. Byte 18 (second name length) is 0 in fresh Font
Creator output and the name length after a re-save; both load.
Character map: 10 bytes per character: u16 code, u8 glyph advance width, u8 extra columns on the
left, u8 extra columns on the right (glyphs that overhang, e.g. `j`, `f`, `W`; the stored glyph is
advance + left + right wide and drawn starting `left` px before the pen position),
u24 glyph offset (relative to the map start), u16 glyph length. In Intelligent projects the glyph
data starts at a multiple of 8 from the map start (zero padding after the map); Basic fonts have no padding.
Glyph: mode byte (0x01 = black/white), then run-length codes over the pixels in the same order
as pictures for the project's display direction (runs continue across rows/columns): at 90° column
by column, bottom to top; at 0° row by row. When an Intelligent project is compiled, the Editor
converts a 90° font to the project direction; our encoder reproduces that conversion byte for byte.
| Code | Meaning |
|---|---|
| `00 0xxxxx` | x transparent |
| `00 1xxxxx` | x ink |
| `01 0xxxxx` | x transparent, 1 ink |
| `01 1xxxxx` | x transparent, 2 ink |
| `10 0xxxxx` | x transparent, 3 ink |
| `10 1xxxxx` | x transparent, 4 ink |
| `11 tttiii` | ttt transparent, iii ink |
The Editor encodes greedily (transparent run + 1..4 ink if possible, else the 3+3-bit form, else a
plain run); our encoder reproduces a 224-glyph Editor font byte for byte. The v3/v5 write-ups in
github.com/hagronnestad/nextion-font-editor were a useful starting point; v6 differs (scan order,
B/W codes `10`/`11`). **OPEN**: the remaining unknown header bytes (0x1F, 0x20).
Multi-byte fonts (Font Creator "Specified character" range; verified for GB2312, Big5, Shift-JIS,
KS C 5601 and UTF-8, round-trip byte-identical, rendered pixel-exact in the simulator):
| Header | Meaning | GB2312 | Big5 | Shift-JIS | KS C 5601 | UTF-8 |
|---|---|---|---|---|---|---|
| 1, 2 | end of the first trail-byte range, trail codes skipped after it | FF 00 | 7E 22 | 7E 01 | FF 00 | FF 00 |
| 4 | encoding (main.HMI numbering) | 2 | 16 | 23 | 15 | 24 |
| 5 | 2 = multi-byte (0 for single-byte fonts) | 2 | 2 | 2 | 2 | 2 |
| 6 | width (0 for multi-byte) | 0 | 0 | 0 | 0 | 0 |
| 8, 9 | lead-byte range | A1 F7 | A0 F9 | 81 EF | A1 C8 | FF FF |
| 10, 11 | trail-byte range | A1 FE | 40 FE | 40 FC | A1 FE | 00 FF |
| 0x1C, 0x1D | end of the first lead range, lead codes skipped | FF 00 | FF 00 | 9F 40 | FF 00 | FF 00 |
| 0x20 | ? | 4 | 5 | 5 | 4 | 5 |
Map codes: double-byte encodings store the character's two bytes as a little-endian u16 (GB2312
中 = bytes D6 D0 -> 0xD0D6); UTF-8 fonts store the Unicode code point. The map is sorted by
code. The display splits text into characters by taking every byte >= 0x81 together with the
next byte (not limited to header 8-9: KS C hanja leads above C8 still pair; Shift-JIS half-width
katakana pair up as well, so they cannot be shown); a character without a glyph advances by the
width of the space glyph.
## 6. Not yet covered
See `docs/NOTES.md`.
## 7. Compiled firmware (`.tft`)
Measured on Editor 1.68.2.3035, model NX4832T035 (Basic series), landscape. Everything below is
reproduced byte for byte by `nxhmi.tft_build` for the supported subset unless marked **OPEN**.
All integers little-endian. "CRC" = the word-per-byte CRC of section 2 with seed 0xFFFFFFFF.
### 7.1 File map
| Range | Contents |
|---|---|
| 0x00000-0x0FFFF | header; unused bytes are FF |
| 0x10000-`base` | resource area, size = u32@0x40, a multiple of 0x10000, zero-padded |
| `base`-end | page section: code blob, attribute records, page table, object records, FF padding to a multiple of 4, trailer |
Header:
| Offset | Field |
|---|---|
| 0x00 | 12 constant bytes `00 01 44 4E 78 45 01 00 4C D3 00 00` (**OPEN**: meaning; probably format/Editor version) |
| 0x0C | u16 width, height, height, width |
| 0x14 | `01 00 00 02` (**OPEN**) |
| 0x18, 0x1E | u32 file offset of `cd0.dll` (twice; u16 0 between) |
| 0x22 | u32 size of `cd0.dll` |
| 0x26, 0x2A | u32 file offset, size of `asp0.dll` |
| 0x2E | u32 model id (as in main.HMI) |
| 0x32 | `21 00 00 00 01 00 0C 00 00 00` (**OPEN**) |
| 0x3C | u32 file size |
| 0x40 | u32 resource area size |
| 0x44 | CRC of the resource area |
| 0x48 | u32 0, 8 x FF, u32 0 |
| 0x58 | u32 size of code blob + attribute records |
| 0xC4 | CRC of `[0x00, 0xC4)` |
| 0xC8 | layout table: 19 u32, each XOR 0xEBAB2932 |
| 0x18C | CRC of `[0xC8, 0x18C)` as stored |
Layout table words: 0, 1, 3 = code blob size; 4 = 0x10000; 5 = `base`; 6 = page table offset;
7 = object records offset; 8 = pictures offset; 12 = fonts offset; 13 = offset of the program
inside the blob; 14 = page count | component count << 16; 15 = picture count; 17 = font count;
18 = 3; the rest 0 (**OPEN**: probably audio/video/gmov resources).
Trailer (last 4 bytes): CRC of everything before it, XOR `(file length & 0xFF) ^ 0x56`.
### 7.2 Resource area
A 0x90-byte directory of 12 entries `(u32 offset from 0x10000, u32 size, u32 0)`, then the data
in the same order: seven files copied verbatim from the Editor's install folder (`input.bin`,
`asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll`), all pictures, all fonts;
entries 9-11 are empty.
- Pictures: the 24-byte headers of all `N.i` entries first, then their pixel data. In each
header, u32@4 = picture number and u32@8 = offset of its data from the start of the picture
block. (One picture: identical to the `.i` entry.)
- Fonts: the 44-byte headers of all `N.zi` entries first, then the rest of each font; u32@0x18
of a header = offset of that font's data from the start of the font block.
### 7.3 Code blob
Offsets in this section are relative to `base`.
```
u32 0x24 + 6*pages, u32 3, u32 0x1C, u32 4, u32 0x20, u32 4, u32 0x24, u32 6*pages, u32 0, u32 0
page names: (u32 name hash, u16 page number), sorted by hash
program
per page: code blocks of its components, name list, RAM image, init code
```
The first eight words describe three tables at 4 + offset: table 0 (4 zero bytes, **OPEN**),
table 1 (global variables, see 7.6; 4 zero bytes without globals) and the page names.
**Name hash** = CRC of the name NUL-padded to 14 bytes. Names are not stored anywhere else.
Everything after the page names is a sequence of **chunks**: `u32 length` + bytes. A chunk is one
tokenised script line; an empty chunk ends a section.
- Program: one chunk per `Program.s` statement (comments and blank lines dropped), then a chunk
`page 0` added by the Editor, then the empty chunk.
- Component block (the page itself is component 0):
- draw section -- lines, empty chunk. Page: `fill x,y,w,h,<bco>` (command `09 0D 04`, colour
as a reference to the page's `bco` record).
Types that draw themselves (progress bar, gauge, QR code, text ...) have their own script
here, generated from the attributes (**OPEN** per type).
- erase section (types with a rectangle only; empty for the page) -- `fill x,y,w,h,<page bco>`,
empty chunk.
- events: a label chunk (`down`, `up`, `unload`, `timer`, `slide` -- plain text), the event's
lines, empty chunk. Page: down, up, unload. Hotspot: down, up. Variable: none.
- After the last component of a page: one chunk with the name list `(u32 hash, u16 id)` sorted
by hash; one chunk with the RAM image followed by 8 zero bytes; type-specific init lines
(timer: 7.6; slider, touch cap -- **OPEN**); the page's Preinitialize lines; the chunk
`09 21 08`; the page's Postinitialize lines; empty chunk.
RAM image: 4 x FF, one FF per component of the page (the page included) padded with FF to a
multiple of 4, then every RAM-stored attribute of every component in component order,
each aligned to its size, each component padded to 4. For a page: `sta` (u8), pad, `bco` (u16).
### 7.4 Attribute records (24 bytes)
Every component owns a fixed number of record slots (page 33, hotspot 27, variable 11,
timer 11, touch cap 10, progress bar 33, slider 40, gauge 41, QR code 33 ...); unused slots are
all zero. Record numbers are global (pages concatenated) in script references and page-relative
in the object records.
| Offset | Field |
|---|---|
| 0 | u32 RAM address of the component's data (page: of its second word) |
| 4 | i32 value (constant attributes) or RAM address of the value |
| 8, 12 | i32 maximum, minimum |
| 16 | u8 page number, u8 component id of the component to redraw on change; FF FF = none |
| 18 | u8 0, u8 change action (0 = none; timers use 1 for `tim`, 2 for `en`) |
| 20 | u8 kind: 0x01 constant; 0x0B/0x0C/0x0D/0x0E x/y/w/h; 0x08 endx/endy; 0x21, 0x22, 0x31, 0x32, 0x39, 0x3F RAM-stored |
| 21 | u8 size in bytes |
| 22 | u16 0 |
Slots seen in all types: 0 `type`, 1 `id`, 3 `vscope`, 9-14 `x y w h endx endy`.
### 7.5 Page table (16 bytes per page) and object records (232 bytes per component)
Page: u16 first object number, u16 component count, u32 offset of the name-list chunk, u32
offset of the page's first attribute record (from `base`), u32 RAM image size.
Object:
| Offset | Field |
|---|---|
| 0 | u8 type, u8 id, u8 0, u8 flags (0x37 visible types, 0x27 timer/touch cap, 0x07 variable) |
| 4 | u32 offset of the draw section, FFFFFFFF if empty |
| 8 | u32 offset of the erase section, FFFFFFFF if none/empty |
| 0x0C | u32 x 4: offset of the first line of the down, up, timer, unload event; FFFFFFFF when the event is empty |
| 0x1C | u32 RAM address as in the records |
| 0x20 | `00 00 7F 00`, u32 0 |
| 0x28 | u16 x, y, w, h, endx, endy (0,0,1,1,0,0 for invisible types) |
| 0x34 | u32 offset of the component's code block |
| 0x38 | 88 x u16: record number (page-relative) of well-known attributes, FFFF = absent. Positions: 1 vscope, 2 sta, 4 bco, 16 pco, 20 val, 42 x, 43 y, 44 endx, 45 endy, 46 w, 47 h, 49 id, 62 type (**OPEN**: the others) |
### 7.6 Script tokens
A script line is stored as text with some parts replaced by binary tokens
(`nxhmi.tft_code`; tables there):
| Token | Meaning |
|---|---|
| `09 ii tt` | a command at the start of a line; `tt` = 04 for names of up to 4 letters, 08 for longer ones, `ii` = index in that table (`page` 0B/04, `print` 04/08 ...). The arguments follow, tokenised like an expression (`printh`: plain text) |
| `04 tt iiii 00` | system variable or colour constant, same two tables (`dim` 0003/04, `WHITE` 0000/08 ...) |
| `05` + u32 | global variable declared in Program.s: its offset in the global RAM (4 bytes each, in declaration order) |
| `01` + u32 | component attribute (`va0.val`, `page0.va0.val`): global attribute record number |
| `03` + i32 | number: hex literals and decimal literals of four or more digits (a leading minus is folded in); shorter decimals stay text |
Operators, commas, quotes, component and page names used as command arguments (`ref m0`,
`page page0`) and the array forms `b[1].x`, `p[0].b[2].val` stay text.
`int a=0,b=5` lines in Program.s produce no chunk: the values go into header table 1 of the code
blob (u32 each, then 4 zero bytes), and one 12-byte descriptor per variable `(CRC of the bare
name, offset, 9)`, sorted by hash, sits between the code blob and the attribute records (layout
word 2 = count, word 3 = offset of the attribute records). All RAM addresses in attribute
records start after this global RAM: address = 4 + 4*globals + offset in the page RAM image.
Control flow becomes jumps; `skip` counts bytes (chunks including their length words) from the
end of the jumping chunk and may be negative:
- `09 00 04 <lhs>,<rhs>,<op>,<03 skip>` -- continue when `lhs op rhs` holds, otherwise jump.
`op`: 1 `==`, 2 `<`, 3 `>`, 4 `<=`, 6 `!=`; 5 `>=` is inferred (**OPEN**).
- `T ` + `03 skip` -- jump always (end of an `if` body that has an `else`; end of a loop body).
- `a&&b`: one test per term, each skipping to the else part. `a||b`: every term but the last is
inverted and skips to the body.
- `for(init;cond;step)` = init line, tests, body, step line, jump back.
Timers: the event section is the label `timer`, a chunk `S ` + `03 1`, the event lines; the
page's init code gets `09 22 08 <en>,<id>,<tim>,0` and `L ` + `03 <offset of the first event line>`.