extension.doc

This document describes the UUID-based extensions. Not all of these are
currently implemented, and some are currently a draft.

I do not have any intention that any of these should be a part of the
standard uxn/varvara, although some other emulator authors may choose to
implement none, some, or all of them in their own emulators, as well as
their own extensions.

Most programs should not need these extensions, although some might be
able to use them optionally. (More rarely, some programs might require
one or more of these extensions, but this is generally discouraged.)


=== 01231250-d878-4462-bc41-d0927645a2fa (Uxn11 Console) ===

This is the uxn11 extensions to the console device. (Uxn11 itself
unconditionally enables these extensions, although an implementation
might only enable it when the program specifies this extension, in case
it conflicts with other extensions.)

See: https://git.phial.org/d6/uxn11/src/branch/d6/multiprocess/console.txt

(This extension may be obsolete; see 9c5f1356-6bc5-11ef-a6c9-002618745416)


=== 80175132-e263-11ed-b8c9-002618745416 (Colours) ===

Allows setting separate foreground and background colours. The device
number must be zero, and the version will be 1. The data is eight 16-bit
numbers, for the colours in order background 0 to 3 and then foreground 0
to 3 (although note that foreground 0 is not normally meaningful), with the
high to low nybble of each being red, green, blue, unused (zero). What
happens if you then try to change colours using the colour ports after
doing this, is not specified.


=== 970b5a0c-2c44-11ee-ac3b-002618745416 (Screen compatibility flags) ===

This extension defines compatibility flags for the screen device for use
with older varvara programs. It is not meant to be called by the uxn
program itself (although it can be); it is meant for use with the -mu flag.

The device number should be 0x20, although the screen device ports will
continue to work as they do (except for the changes by the flags).

There is one byte of data in this extension. It consists of a bit field,
where a bit which is clear means the older behaviour and a bit which is
set corresponds to newer behaviour, generally.

* bit0 = clear if drawing sprites with colour mode 0 is opaque, or set if
it is transparent.

* bit1 = set if flipping will reverse the direction of auto advancement
when drawing sprites.

Other bits are currently unused.


=== 9c5f1356-6bc5-11ef-a6c9-002618745416 (Subprocess) ===

This is an extension for handling subprocesses. The device number must
be 0x10 and the current version number is 1.

15 = Subprocess status
16 = Subprocess exit code
1C = Subprocess command line *
1E = Subprocess mode
1F = Start subprocess

(This documentation is incomplete)


=== b076ddca-db5a-11ee-bddb-002618745416 (Extended text input) ===

(DRAFT)

This extension is used for extended text input with TRON character codes
and/or extended IBM code pages. The current version number is 1.

(I am not sure how useful this actually is (since it is not needed for
output, nor to implement IME in ordinary uxn code), so it might be removed
in future, or might never end up being implemented.)

The ports are:

x0 - Vector *
x2 - TRON volume
x3 - TRON plane
x4 - TRON code *
x6 - Intended mode
x7 - Effective mode
x8 - Code page (hi) *
xA - Code page (lo) *

The vector and intended mode (and possibly the code page, if applicable)
should be set by the program, and the emulator will set the other fields
to be read by the program.

The mode flags are:

* bit0 = Normal keyboard input (with the standard keyboard device). If
this is set in the intended mode, then keyboard events will trigger the
standard input device. In the effective mode, it is set if this event will
(or did) trigger the standard input device.

* bit1 = Extended keyboard input. If this is set in the intended mode, then
it requests TRON character input, and will trigger this device's vector
when TRON character input is available; if this bit is clear then ASCII (or
extended ASCII) input is supported. In the effective mode, it is set if
this event will (or did) trigger this device, which it does if a TRON
character input is available.

* bit2 = Bracketed paste. Setting it in the intended mode enables this
feature. In the effective mode, this bit will be set if it is currently
doing a bracketed paste.

* bit3 = Code page. This means to use the specified code page with the
normal keyboard input. It is set in the effective mode if the keyboard
event is using the specified code page.

The initial value for the intended mode is 0x01. Note that bit0 and bit1
are not mutually exclusive; if both are set, then it is possible (but not
necessarily) that a keyboard event will trigger both devices. If neither
bit is set, then text input is not requested (some implementations might
use this to hide the on-screen keyboard). Also, the effective mode is set
for both kinds of input events, regardless of the intended mode.

The code page is an extended IBM code page number; an implementation may
have a default value (and if it does, might set the intended mode to 0x09).
It also might be limited as to what code pages it supports (possibly only
one or possibly none at all), in which case it only has those values; the
emulator may automatically change them to the supported values when setting
them to an unsupported values, so the program may wish to read them back.
(The code pages SHOULD be an extension of ASCII; you SHOULD NOT use EBCDIC
code pages, please. The emulator MUST NOT automatically set the code page
to any non-ASCII code page.)

Code page number 65535 is not normally a valid code page number in the IBM
code page numbers, so instead code page 65535 is used here to mean whatever
code page is used for file names (the emulator might select a different one
instead if you specify code page 65535, but this is not guaranteed).


=== c7e5d57e-1201-11ee-bee4-002618745416 (Sequencer) ===

(DRAFT)

This will make available a audio sequencer device, which can be used for
music playback with precise timing. The current version number is 1.

The ports are:

x0 - Vector *
x2 - Sequencer channels / reset
x3 - Override channels

The sequencer channels/reset port has the low four bits for the channels
that are used by the sequencer, where bit0 is the first channel; the high
four bits should be clear. Writing anything to this port will clear the
sequencer buffer and reset the sequencer.

The override channels port has the same format as the sequencer channels
port, although in this case the bits are set to temporarily suppress the
sequencer for these channels. The sequencer will still run and those
channels can still be written by the sequencer vector and will fill up
the sequencer buffer, but the audio from those channels will not be played
from the sequencer buffer, instead acting like the sequencer is disabled
for the purpose of the audio output. Clearing those bits in this port will
then allow playback of those channels from the sequencer buffer. This does
not block timing; the corresponding channels in the sequencer buffer are
still "played" but will be muted.

The vector will be called at unpredictable times, and the number of times
it will be called is also unpredictable (and may even be zero, e.g. if
the audio is disabled by the user). However, the contents of the audio
registers which the sequencer is enabled for will then be played back, at
a rate of one frame for each time this vector is called.

The timing of the sequencer vector will be guaranteed to not interrupt any
other vectors and to be called as many times as necessary to fill up the
sequencer buffer for the amount of time that the music will be played.

If the sequencer is enabled, then those channels should not be touched
outside of the sequencer vector unless the override bits are set.

Also note that since the sequencer vector timing is unpredictable, you
should not use it to store stuff used by other parts of the program nor
read other timing-sensitive things, including the date/time device (which
will return the current date/time and not necessarily the time that the
music will be audible).

An implementation should ensure that the values for the audio channels
which are assigned to the sequencer are retained for sequencer callbacks
independently from their access by code outside of sequencer callbacks,
so that channel overrides will work correctly. However, the initial values
after the sequencer has been reset might be either zero or the previously
set values by the sequencer or the values that have been set before the
sequencer was enabled.

The sequencer callback itself should never touch the sequencer channels
port or the override channels port, although it is allowed to change the
vector so that the next call will be at a different address.

If this extension is not available, then programs should use the screen
vector for audio timing.


=== d02b5508-db5d-11ee-bb94-002618745416 (Game Boy emulation) ===

(DRAFT)

This extension is only intended to be available for multi-system emulators
that includes varvara and Game Boy, although this is not required (it is
also possible to implement in an emulator that doesn't emulate the rest of
Game Boy). (This is not fully defined yet, and cannot be used at this time.
For example, there is currently no way to set colour/mono mode, and many
other things are also missing.)

The ports are:

x0 - Vector *
x2 - Register address
x3 - Register data
x4 - Display position X *
x6 - Display position Y *
x8 - VRAM bank 0 *
xA - VRAM bank 1 *
xF - Display flag

The register address corresponds to addresses 0xFF00 to 0xFFFF of Game Boy
memory, and then you can read/write the data by the register data port.

Display position is the top-left corner of the Game Boy display inside of
the varvara display.

The display flag bits can be:

* bit0 = Display Game Boy screen. The varvara foreground layer is displayed
in front of the Game Boy screen; the varvara background layer is suppressed
in the area where the Game Boy screen is displayed.

* bit1 = Display objects outside of Game Boy bounding box. (If not set, the
objects cannot be displayed outside of this bounding box.)

* bit2 = Use varvara palettes for Game Boy display.

Note that the varvara audio and Game Boy audio can be mixed together.