The standard esxdos api is a subset of the esx-compatible api in nextzxos so you will be able to make the same calls to load data and whatnot from sd card. The most immediately noticeable difference is that nextzxos will accept long filenames.
Nextzxos's esxdos api is documented here:
https://gitlab.com/thesmog358/tbblue/tr ... s/nextzxos
in file "NextZXOS_and_esxDOS_APIs.pdf". The description of the esxdos api starts on page 25 and documentation for all the esxdos calls starts on page 30. You can compare with the calls you are using already.
ROM3, the standard 48k rom, that is always present when programs are started has a hook at address $08 so that esxdos calls will work from inside your program. The next launches programs with ROM3 in the bottom 16k and banks 5,2,0 in the top 48k of ram.
The esxdos api is effectively separate from the operating system and it does not use any system variables or place any restrictions on what you can or cannot overwrite in memory. It lies entirely in divmmc memory which is separate from normal memory. The next has 128k of divmmc memory and either 768k ram (the unexpanded nexts) or 1792k ram (the 2MB nexts). The roms are also in a separate memory space so that 768k is real ram covering 16k banks 0-47 of which banks 0-7 correspond to the 128k's ram. Nextzxos also takes 16k bank 8 for itself although that is not important if your program only uses esxdos (and not special nextzxos calls) and doesn't use rom routines.
The memory space has two different names, one divided it into 16k blocks as described already - 16k banks 0-47 on the unexpanded next. It can also be divided into 8k pages named 8k page 0-95. 16k bank 5 corresponds to 8k pages 10,11 (*2 and *2+1). The reason there are two names for memory is that 16k banking is what is inherited from the 128k spectrum. You can bank like normal through port 0x7ffd. There are only 3-bits there for bank number so this port alone can only place banks 0-7 in the top 16k. There is another port 0xdffd that adds four more bits to the bank number. So by using port 0xdffd for the top 4 bits of the bank number and port 0x7ffd for the bottom 3 bits of the bank number you can reach 7-bit 16k bank numbers banked into the top 16k like on regular spectrums.
However, the memory is also divided into 8k pages. This is because the next can place an page of memory into any 8k of the z80's 64k address space. The address space 0-8k is known as mmu0, 8k-16k as mmu1, ..., 56k-64k as mmu7. The screen is normally located in 16k bank 5 (8k page 10) and you can make it appear at address 0 by setting mmu0=10. This is done via nextreg 0x50. Some assemblers have a special instruction "mmu0 10" that will do it but more commonly the special z80n instruction is used "nextreg 0x50,10". There is an equivalent OUT that does it with the regular z80 instruction set. "OUT 0x243B,0x50 ; OUT 0x253B,10". The first out selects a nextreg and the second out writes data there. The mmu0-mmu7 are mapped to nextreg registers 0x50-0x57. You can overlay the rom with ram and map whatever memory pages you want in those 8k slots. When you do write to legacy ports 0x7ffd, 0xdffd, 0x1ffd, those port writes will change mmu6 and mmu7 as well as restore the rom in the bottom 16k mmu0 and mmu1.
I went through all that explanation because layer 2 can be placed anywhere in ram and to read/write it you just have to map it into memory. You can do that with ports 0x7ffd, 0xdffd or with mmu. The special mapping by port 0x123B is another method that you have found - it allows the mapping of layer 2 to be write only and/or read only. If write only, eg, you could read bytes underneath layer 2 and write them into layer 2 at the same address.
Anyway, the wiki is always a bit behind so I will give some information here. Layer 2 is 256x192 one byte per pixel. This byte is passed through a palette lookup that returns a 9-bit RRRGGGBBB colour. So layer 2 is 256 simultaneous colours from a palette of 512 colours. The default palette just has colours 0-256 in the palette so that a pixel 0-256 maps to a colour 0-256 RRRGGGBB (the palette can be written as RRRGGGBB or RRRGGGBBB; if the former the third blue bit is the logical OR of the other two blue bits). This means the default has the layer 2 pixels looking like RRRGGGBB pixels.
There is a catch - after the final colour is looked up in the palette, it is compared against a global transparency colour using the top 8-bits only of the 9-bit colour. If there is a match, that colour is transparent and layers underneath layer 2 will be visible. So of the 256 colours a layer 2 picture uses, one is always reserved for transparent.
Layer 2 is 256x192 one byte per pixel arranged so that +1 moves right one pixel and +256 moves down one pixel. This makes it 48k in size. I will mention that it is highly likely that layer 2 will have 320x256 and 640x256 modes in the future but if you are using the ula screen as well, 256x192 is a good fit anyway.
The location of layer 2 in memory is pointed at by nextreg 0x12 (the nextreg, which is machine state, is documented here https://www.specnext.com/tbblue-io-port-system/
. The machine state is accessed via io ports 0x243b, 0x253b and special nextreg instructions added to the z80n as mentioned above). The value in nextreg 0x12 indicates the starting 16k bank of the actively displayed layer 2. You have 16k banks 0-47 in an unexpanded next, 0-8 is normally taken by nextzxos (which doesn't matter if you take over the machine and only use esxdos functions). If you place layer 2 at bank 9 by writing a 9 to nextreg 0x12, then layer 2 occupies 16k banks 9,10,11 (16k*3=48k). How do you write to that? Map it into memory and write to it. The mapping can be done the legacy 128k way with ports 0x7ffd,0xdffd into the top 16k or it can be done with mmu into an 8k slot in the 64k space. The third way is the special layer 2 mapping using port 0x123B. This is how the port works now (core 3.00.00, cspect will emulate this very soon):
* Port $123B is changed somewhat: MM00SREW
E = 1 to enable layer 2 display
W = 1 to enable write only mapping of layer 2 memory over the bottom 16k
R = 1 to enable read ony mapping of layer 2 memory over the bottom 16k
S = 1 to map the shadow layer 2 memory instead of the active layer 2 memory
MM = 00 to map the first 16k of layer 2 over the bottom 16k
01 to map the second 16k of layer 2 over the bottom 16k
10 to map the last 16k of layer 2 over the bottom 16k
11 to map all 48k of layer 2 over the bottom 48k of memory
E=1 to turn on layer 2 to make it visible
W=1 to enable write-only mapping of layer 2
R=1 to enable read-only mapping of layer 2
MM = 00,01,10 to map the three 16k segments of layer 2 over the bottom 16k only
MM = 11 to map the entire 48k of layer 2 over 0-48k of memory.
If you use the mapping modes, keep in mind where your interrupts are going and make sure the mapping is off (R,W=0) before using esxdos. esxdos needs r/w access in the bottom 16k to its own memory.
The layer priority on screen is controlled by nextreg 0x15:
(R/W) 0x15 (21) => Sprite and Layers system
bit 7 = LoRes mode, 128 x 96 x 256 colours (1 = enabled)
bit 6 = Sprite priority (1 = sprite 0 on top, 0 = sprite 127 on top)
bit 5 = Enable sprite clipping in over border mode (1 = enabled)
bits 4-2 = set layers priorities:
Reset default is 000, sprites over the Layer 2, over the ULA graphics
000 - S L U
001 - L S U
010 - S U L
011 - L U S
100 - U S L
101 - U L S
110 - S(U+L) ULA and Layer 2 combined, colours clamped to 7
111 - S(U+L-5) ULA and Layer 2 combined, colours clamped to [0,7]
bit 1 = Over border (1 = yes)(Back to 0 after a reset)
bit 0 = Sprites visible (1 = visible)(Back to 0 after a reset)
For example, "SLU" means sprites over layer 2 over ula.
In addition, all layers including layer 2 can hardware scroll and can be clipped. See nextreg 0x16, 0x17, 0x18
The magnetic scrolls games for the next (jinxter linked here) use layer 2 and optiionally timex hi-res in the same way you are considering for daad:
The layer 2 screen is the picture and this can be scrolled up by mouse to reveal more ula text underneath.