View source for Alternative NEX file formats


== Ped's ".NEX Extensions" ==

[https://github.com/ped7g Ped] has proposed (and created) an extended format - this has been previously annecdotally referred to as v1.3, but '''IS NOT''' at all supported by the any existing NEX tools, except those Ped developed)

Resources:
* [https://github.com/ped7g/ZXSpectrumNextMisc/tree/master/nexload2 Ped's nexload2.asm] (rewritten from scratch, supports V1.3 NEX files)
* [https://github.com/z00m128/sjasmplus/releases Z00m's sjasmplus] supports this alternative format NEX file since v1.14.4

The file format follows on from the distro's default supported version with the following changes:
------------------------------

{| class="wikitable"
|-
! offset !! size !! description
|+ Differences in the default V1.2 header block: 
|-
| 4 || 4 || string with NEX file version, currently "V1.0", "V1.1", "V1.2" or "V1.3"
|-
| 10 || 1 || Loading-screen blocks in file (bit-flags):
128 = no palette block, 64 = "flags 2" in V1.3 part of header define screen, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2
|}

{| class="wikitable"
|-
! offset !! size !! description
|+ Additions to the default V1.2 header block: 
|-
| 142 || 1 || 0 = disable Expansion Bus by setting top four bits of {{NextRegNo|$80}} to 0, 1 = do nothing (does apply only to cores 3.0.5+)
|-
| 143 || 1 || 1 = Has checksum value, checksum algorithm is CRC-32C (Castagnoli), value itself is at the very end of the header block
|-
| 144 || 4 || File offset of first bank data (when loader is parsing known version, it should know where the banks start without this value, but it may use it for extra check whether the parsing of optional blocks between header and first bank was done correctly for files V1.3+, or it may even try to partially-load unknown future versions of NEX files by skipping unknown blocks between header and banks data, although that may lead to unexpected state for the app)
|-
| 148 || 2 || CLI buffer address (after "Entry bank" is paged in), 0 = no buffer
|-
| 150 || 2 || CLI buffer size - when address and size are provided, the original argument line passed to NEX loader will be copied to defined buffer (and truncated to "size", shorter string may be zero/colon/enter terminated as any other BASIC line) and register DE is set to the buffer address. The maximum size is 2048 bytes (longer lines can be probably salvaged from Bank 5 memory if the NEX file is not loading that bank and the app code search for the original line on its own).
|-
| 152 || 1 || Loading screen flags 2 - when first flag has bit6 +64 set (+128 no-palette is valid for new cases too, other old bits should be NOT mixed with new modes):
 1 = Layer 2 320x256x8bpp, blocks: [512B palette +] 81920B data
 2 = Layer 2 640x256x4bpp, blocks: [512B palette +] 81920B data
  (HiRes color value 0..15 is used as L2 palette offset - does apply to two new Layer 2 modes)
  For Layer 2 banks 9,10,11,12,13 are used to display the loading screen.
 3 = Tilemode screen, block: [512B palette] (plus four configuration bytes in header at offset 154)
  Tilemap data are stored in regular (!) bank 5 - no specialized data block is used.
|-
| 153 || 1 || 1 = Has copper code block, extra 2048B block after last screen data block, which will be set to Copper and the copper will be started with %01 control code (reset CPC to 0, and start). This can be used for example as "loading screen animation" feature (be aware the timing of load may vary greatly).
|-
| 154 || 4 || When Tilemode screen: four bytes array, values to set NextRegs: $6B, $6C, $6E, $6F
|-
| 158 || 1 || When Layer 2 320x256 or 640x256 screen + loading bar: loading bar Y position (bar is 2px tall, so 254 is very bottom)
|-
| 159 || 349 || reserved for future extensions, set to zero in older versions of file format.
|-
| 508 || 4 || optional CRC-32C (Castagnoli) - is calculated by checksumming (initial value is zero) file content from offset 512 (after this field) till end of file, including the optional custom binary appended after regular NEX file. And then continuing with checksumming the first 508 bytes of the header (stopping ahead of this field). This is intended for PC tools working with NEX files, or extra check tool running on Next, but not for regular loading of NEX files (value is stored as "uint32_t" in little-endian way).
|}

== Future Extensions / Other Additions / File Format Features ==

=== Compatible with existing file formats ===
** checking machine memory and use the RAMREQ to report low memory
** having entry bank dynamically allocated by NextZXOS (entrybank = 255?)
** changing working directory if path with directories was provided (adjust that also when passing command line in V1.3 to make file-only like) (can be extra option of loader, not stored in the file itself)
=== Format Extensions ===
** preserving original NextZXOS stack SP value (stack pointer = 2?) (0 is valid SP starting from very "top" of RAM) (preserving is risky, as there is always possibility of ramtop being set in such unfortunate manner, that preserved sp will cause destruction of the loaded code, so the SP should be set up by the header every time, but maybe there can be extra flag to put old value into the new stack by loader, so the code can eventually get to the content of old stack - if the NEX file doesn't overwrite the banks 5/2/0)
** custom palettes also for ULA/HiRes/HiCol screens (maybe +64 flag?) (or invert the +128 in V1.3 for those three modes, i.e. 0 = no pal / 128 = has pal)
** return multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).
** With a flag (bit 7 of number of handles?) to force close all existing open handles first.
** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.