commit d308176

Move documentation of UUID-based extensions to a separate file, including those which are not currently implemented.

 1@@ -316,14 +316,9 @@ This section lists the UUID-based extensions that are implemented in
 2 this emulator (the -x switch is required, since they use nonstandard
 3 expansion commands to activate them).
 4 
 5-80175132-e263-11ed-b8c9-002618745416
 6-  Allows setting separate foreground and background colours. The device
 7-  number must be zero, and the version will be 1. The data is eight 16-bit
 8-  numbers, for the colours in order background 0 to 3 and then foreground 0
 9-  to 3 (although note that foreground 0 is not normally meaningful), with
10-  the high to low nybble of each being red, green, blue, unused (zero).
11-  What happens if you then try to change colours using the colour ports
12-  after doing this, is not specified.
13+See the file extension.doc for the definition of the extensions.
14+
15+* 80175132-e263-11ed-b8c9-002618745416
16 
17 
18 === Memory/device scripts ===

 1@@ -0,0 +1,87 @@
 2+This document describes the UUID-based extensions. Not all of these are
 3+currently implemented, and some are currently a draft.
 4+
 5+I do not have any intention that any of these should be a part of the
 6+standard uxn/varvara, although some other emulator authors may choose to
 7+implement none, some, or all of them in their own emulators, as well as
 8+their own extensions.
 9+
10+Most programs should not need these extensions, although some might be
11+able to use then optionally. (More rarely, some programs might require
12+one or more of these extensions, but this is generally discouraged.)
13+
14+
15+=== 80175132-e263-11ed-b8c9-002618745416 (Colours) ===
16+
17+Allows setting separate foreground and background colours. The device
18+number must be zero, and the version will be 1. The data is eight 16-bit
19+numbers, for the colours in order background 0 to 3 and then foreground 0
20+to 3 (although note that foreground 0 is not normally meaningful), with the
21+high to low nybble of each being red, green, blue, unused (zero). What
22+happens if you then try to change colours using the colour ports after
23+doing this, is not specified.
24+
25+
26+=== c7e5d57e-1201-11ee-bee4-002618745416 (Sequencer) ===
27+
28+(DRAFT)
29+
30+This will make available a audio sequencer device, which can be used for
31+music playback with precise timing. The current version number is 1.
32+
33+The ports are:
34+
35+x0 - Vector *
36+x2 - Sequencer channels / reset
37+x3 - Override channels
38+
39+The sequencer channels/reset port has the low four bits for the channels
40+that are used by the sequencer, where bit0 is the first channel; the high
41+four bits should be clear. Writing anything to this port will clear the
42+sequencer buffer and reset the sequencer.
43+
44+The override channels port has the same format as the sequencer channels
45+port, although in this case the bits are set to temporarily suppress the
46+sequencer for these channels. The sequencer will still run and those
47+channels can still be written by the sequencer vector and will fill up
48+the sequencer buffer, but the audio from those channels will not be played
49+from the sequencer buffer, instead acting like the sequencer is disabled
50+for the purpose of the audio output. Clearing those bits in this port will
51+then allow playback of those channels from the sequencer buffer. This does
52+not block timing; the corresponding channels in the sequencer buffer are
53+still "played" but will be muted.
54+
55+The vector will be called at unpredictable times, and the number of times
56+it will be called is also unpredictable (and may even be zero, e.g. if
57+the audio is disabled by the user). However, the contents of the audio
58+registers which the sequencer is enabled for will then be played back, at
59+a rate of one frame for each time this vector is called.
60+
61+The timing of the sequencer vector will be guaranteed to not interrupt any
62+other vectors and to be called as many times as necessary to fill up the
63+sequencer buffer for the amount of time that the music will be played.
64+
65+If the sequencer is enabled, then those channels should not be touched
66+outside of the sequencer vector unless the override bits are set.
67+
68+Also note that since the sequencer vector timing is unpredictable, you
69+should not use it to store stuff used by other parts of the program nor
70+read other timing-sensitive things, including the date/time device (which
71+will return the current date/time and not necessarily the time that the
72+music will be audible).
73+
74+An implementation should ensure that the values for the audio channels
75+which are assigned to the sequencer are retained for sequencer callbacks
76+independently from their access by code outside of sequencer callbacks,
77+so that channel overrides will work correctly. However, the initial values
78+after the sequencer has been reset might be either zero or the previously
79+set values by the sequencer or the values that have been set before the
80+sequencer was enabled.
81+
82+The sequencer callback itself should never touch the sequencer channels
83+port or the override channels port, although it is allowed to change the
84+vector so that the next call will be at a different address.
85+
86+If this extension is not available, then programs should use the screen
87+vector for audio timing.
88+