Difference between revisions of "NEX file format"
(V1.3 extensions proposal - probably final version of proposal, changes documented in text) |
|||
(7 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | The NEX file format was designed as very simple and straightforward format to load self-contained applications into memory and start them. | + | The NEX file format was designed as very simple and straightforward format to load self-contained applications into memory and start them. |
+ | |||
+ | At this time the official Distro supported version is the V1.2 of the specification. | ||
The official distribution sports some goodies for NEX files: | The official distribution sports some goodies for NEX files: | ||
Line 8: | Line 10: | ||
* [https://github.com/Threetwosevensixseven/NexCreator/tree/master/nexload SevenFFF's fork of NexCreator and nexload] | * [https://github.com/Threetwosevensixseven/NexCreator/tree/master/nexload SevenFFF's fork of NexCreator and nexload] | ||
* [https://github.com/varmfskii/zxnext_tools Varmfskii's ZX Next tools] | * [https://github.com/varmfskii/zxnext_tools Varmfskii's ZX Next tools] | ||
− | |||
* [https://github.com/z00m128/sjasmplus/releases Z00m's sjasmplus] has support for [http://z00m128.github.io/sjasmplus/documentation.html#c_savenex NEX saving] since v1.13.0 | * [https://github.com/z00m128/sjasmplus/releases Z00m's sjasmplus] has support for [http://z00m128.github.io/sjasmplus/documentation.html#c_savenex NEX saving] since v1.13.0 | ||
Line 20: | Line 21: | ||
| style="text-align:right;" | 512 || || "Next" string followed by file header, containing also map of memory banks stored in the file | | style="text-align:right;" | 512 || || "Next" string followed by file header, containing also map of memory banks stored in the file | ||
|- | |- | ||
− | | style="text-align:right;" | 512 || * || optional palette (for Layer2 or | + | | style="text-align:right;" | 512 || * || optional palette (for Layer2, LoRes or Tilemap screen) |
|- | |- | ||
| style="text-align:right;" | 49152 || * || Layer2 loading screen | | style="text-align:right;" | 49152 || * || Layer2 loading screen | ||
Line 31: | Line 32: | ||
|- | |- | ||
| style="text-align:right;" | 12288 || * || Timex HiCol (8x1) loading screen | | style="text-align:right;" | 12288 || * || Timex HiCol (8x1) loading screen | ||
+ | |- | ||
+ | | style="text-align:right;" | 81920 || * || Layer 2 320x256x8 or 640x256x4 loading screen | ||
+ | |- | ||
+ | | style="text-align:right;" | 2048 || * || Copper code for copper loading-effects | ||
|- | |- | ||
| style="text-align:right;" | n * 16384 || * || 16kiB raw memory bank data in predefined order: 5,2,0,1,3,4,6,7,8,9,10,...,111 (particular bank may be omitted completely) | | style="text-align:right;" | n * 16384 || * || 16kiB raw memory bank data in predefined order: 5,2,0,1,3,4,6,7,8,9,10,...,111 (particular bank may be omitted completely) | ||
Line 44: | Line 49: | ||
| 0 || 4 || "Next" string | | 0 || 4 || "Next" string | ||
|- | |- | ||
− | | 4 || 4 || string with NEX file version, currently "V1.0", "V1.1", "V1.2 | + | | 4 || 4 || string with NEX file version, currently "V1.0", "V1.1", or "V1.2" |
|- | |- | ||
| 8 || 1 || RAM required: 0 = 768k, 1 = 1792k | | 8 || 1 || RAM required: 0 = 768k, 1 = 1792k | ||
Line 52: | Line 57: | ||
| 10 || 1 || Loading-screen blocks in file (bit-flags): | | 10 || 1 || Loading-screen blocks in file (bit-flags): | ||
128 = no palette block, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2 | 128 = no palette block, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2 | ||
− | The loader does use common banks to load the graphics into, and show it from, i.e. bank5 for all ULA related modes and banks 9,10 and 11 for Layer2 graphics (loading these banks afterwards as regular bank will thus replace the shown data on screen). Only Layer2 and Lo-Res screens expect the palette block (unless +128 flag set). While one can include multiple screen data in single file (setting up all relevant bits), the recommended/expected usage is to have only one type of screen in NEX file. | + | |
+ | The loader does use common banks to load the graphics into, and show it from, i.e. bank5 for all ULA related modes and banks 9,10 and 11 for Layer2 graphics (loading these banks afterwards as regular bank will thus replace the shown data on screen). | ||
+ | |||
+ | Only Layer2, Tilemap and Lo-Res screens expect the palette block (unless +128 flag set). While one can include multiple screen data in single file (setting up all relevant bits), the recommended/expected usage is to have only one type of screen in NEX file. | ||
|- | |- | ||
| 11 || 1 || Border Colour: 0-7 | | 11 || 1 || Border Colour: 0-7 | ||
Line 66: | Line 74: | ||
| 130 || 1 || Layer2 "loading bar" 0 = OFF, 1 = ON (works only in combination with Layer2 screen data) | | 130 || 1 || Layer2 "loading bar" 0 = OFF, 1 = ON (works only in combination with Layer2 screen data) | ||
|- | |- | ||
− | | 131 || 1 || "Loading bar" colour (0..255) | + | | 131 || 1 || "Loading bar" colour (0..255) (for 640x256x4 mode the byte defines pixels pair) |
|- | |- | ||
| 132 || 1 || Loading delay per bank (0..255 amount of frames), 0 = no delay | | 132 || 1 || Loading delay per bank (0..255 amount of frames), 0 = no delay | ||
Line 72: | Line 80: | ||
| 133 || 1 || Start delay (0..255 amount of frames), 0 = no delay | | 133 || 1 || Start delay (0..255 amount of frames), 0 = no delay | ||
|- | |- | ||
− | | 134 || 1 || Preserve current Next-Registers values (0 = reset, 1 = preserve) | + | | 134 || 1 || Preserve current Next-Registers values (0 = reset machine state, 1 = preserve) |
|- | |- | ||
| 135 || 3 || Required core version, three bytes 0..15 "major", 0..15 "minor", 0..255 "subminor" version numbers. (core version is checked only when reported machine-ID is 10 = "Next", on other machine or emulator=8 the latest loaders will skip the check) | | 135 || 3 || Required core version, three bytes 0..15 "major", 0..15 "minor", 0..255 "subminor" version numbers. (core version is checked only when reported machine-ID is 10 = "Next", on other machine or emulator=8 the latest loaders will skip the check) | ||
|- | |- | ||
| 138 || 1 || Timex HiRes 512x192 mode colour, encoded as for port 255 = bits 5-3. I.e. values 0, 8, 16, .., 56 (0..7 * 8) | | 138 || 1 || Timex HiRes 512x192 mode colour, encoded as for port 255 = bits 5-3. I.e. values 0, 8, 16, .., 56 (0..7 * 8) | ||
+ | |||
+ | When screens 320x256x8 or 640x256x4 are used, this byte is re-used as palette offset for Layer 2 mode, values 0..15 | ||
|- | |- | ||
| 139 || 1 || Entry bank = bank to be mapped into slot 3 (0xC000..0xFFFF address space), the "Program Counter" (header offset +14) and "File handle address" (header offset +140) are used by NEX loader after the mapping is set (The default ZX128 has bank 0 mapped after reset, which makes zero value nice default). | | 139 || 1 || Entry bank = bank to be mapped into slot 3 (0xC000..0xFFFF address space), the "Program Counter" (header offset +14) and "File handle address" (header offset +140) are used by NEX loader after the mapping is set (The default ZX128 has bank 0 mapped after reset, which makes zero value nice default). | ||
|- | |- | ||
| 140 || 2 || File handle address: 0 = NEX file is closed by the loader, 1..0x3FFF values (1 recommended) = NEX loader keeps NEX file open and does pass the file handle in BC register, 0x4000..0xFFFF values (for 0xC000..0xFFFF see also "Entry bank") = NEX loader keeps NEX file open and the file handle is written into memory at the desired address. | | 140 || 2 || File handle address: 0 = NEX file is closed by the loader, 1..0x3FFF values (1 recommended) = NEX loader keeps NEX file open and does pass the file handle in BC register, 0x4000..0xFFFF values (for 0xC000..0xFFFF see also "Entry bank") = NEX loader keeps NEX file open and the file handle is written into memory at the desired address. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
− | |||
− | |||
------------------------------ | ------------------------------ | ||
− | + | Alternative file formats, and possible extensions to this fileformat are noted on the [[Alternative_NEX_file_formats|Alternative NEX file formats]] page, to prevent confusion with supported features in the shipping distribtion and the licensed "Retail SD Card" distribution. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Latest revision as of 15:27, 1 December 2023
The NEX file format was designed as very simple and straightforward format to load self-contained applications into memory and start them.
At this time the official Distro supported version is the V1.2 of the specification.
The official distribution sports some goodies for NEX files:
Additional resources:
- SevenFFF's fork of NexCreator and nexload
- Varmfskii's ZX Next tools
- Z00m's sjasmplus has support for NEX saving since v1.13.0
The basic structure of the file is:
block size | optional | description |
---|---|---|
512 | "Next" string followed by file header, containing also map of memory banks stored in the file | |
512 | * | optional palette (for Layer2, LoRes or Tilemap screen) |
49152 | * | Layer2 loading screen |
6912 | * | classic ULA loading screen |
12288 | * | LoRes loading screen |
12288 | * | Timex HiRes (512x192) loading screen |
12288 | * | Timex HiCol (8x1) loading screen |
81920 | * | Layer 2 320x256x8 or 640x256x4 loading screen |
2048 | * | Copper code for copper loading-effects |
n * 16384 | * | 16kiB raw memory bank data in predefined order: 5,2,0,1,3,4,6,7,8,9,10,...,111 (particular bank may be omitted completely) |
m | * | Optional binary data appended after "regular" NEX file content - custom format |
Structure of the header block:
offset | size | description |
---|---|---|
0 | 4 | "Next" string |
4 | 4 | string with NEX file version, currently "V1.0", "V1.1", or "V1.2" |
8 | 1 | RAM required: 0 = 768k, 1 = 1792k |
9 | 1 | Number of 16k Banks to Load: 0-112 (see also the byte array at offset 18, which must yield this count) |
10 | 1 | Loading-screen blocks in file (bit-flags):
128 = no palette block, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2 The loader does use common banks to load the graphics into, and show it from, i.e. bank5 for all ULA related modes and banks 9,10 and 11 for Layer2 graphics (loading these banks afterwards as regular bank will thus replace the shown data on screen). Only Layer2, Tilemap and Lo-Res screens expect the palette block (unless +128 flag set). While one can include multiple screen data in single file (setting up all relevant bits), the recommended/expected usage is to have only one type of screen in NEX file. |
11 | 1 | Border Colour: 0-7 |
12 | 2 | Stack pointer |
14 | 2 | Program counter (0 = don't run, just load) |
16 | 2 | "Number of extra files" (currently not used by anything/anyone?) |
18 | 112 | byte flag (0/1) of 16k banks included in the file - this array is in regular order 0..111, i.e. bank5 in file will set 1 to header byte at offset 18+5 = 23, but the 16kiB of data for bank 5 are first in the file (order of bank data in file is: 5,2,0,1,3,4,6,7,8,9,10,...,111) |
130 | 1 | Layer2 "loading bar" 0 = OFF, 1 = ON (works only in combination with Layer2 screen data) |
131 | 1 | "Loading bar" colour (0..255) (for 640x256x4 mode the byte defines pixels pair) |
132 | 1 | Loading delay per bank (0..255 amount of frames), 0 = no delay |
133 | 1 | Start delay (0..255 amount of frames), 0 = no delay |
134 | 1 | Preserve current Next-Registers values (0 = reset machine state, 1 = preserve) |
135 | 3 | Required core version, three bytes 0..15 "major", 0..15 "minor", 0..255 "subminor" version numbers. (core version is checked only when reported machine-ID is 10 = "Next", on other machine or emulator=8 the latest loaders will skip the check) |
138 | 1 | Timex HiRes 512x192 mode colour, encoded as for port 255 = bits 5-3. I.e. values 0, 8, 16, .., 56 (0..7 * 8)
When screens 320x256x8 or 640x256x4 are used, this byte is re-used as palette offset for Layer 2 mode, values 0..15 |
139 | 1 | Entry bank = bank to be mapped into slot 3 (0xC000..0xFFFF address space), the "Program Counter" (header offset +14) and "File handle address" (header offset +140) are used by NEX loader after the mapping is set (The default ZX128 has bank 0 mapped after reset, which makes zero value nice default). |
140 | 2 | File handle address: 0 = NEX file is closed by the loader, 1..0x3FFF values (1 recommended) = NEX loader keeps NEX file open and does pass the file handle in BC register, 0x4000..0xFFFF values (for 0xC000..0xFFFF see also "Entry bank") = NEX loader keeps NEX file open and the file handle is written into memory at the desired address. |
Alternative file formats, and possible extensions to this fileformat are noted on the Alternative NEX file formats page, to prevent confusion with supported features in the shipping distribtion and the licensed "Retail SD Card" distribution.