********************************************************************************
QED68 v0.1
by utz 04'2016 * www.irrlichtproject.de
********************************************************************************


About
=====

QED68 is a music player for the Texas Instruments TI-92 Plus graphing 
calculator. It mixes four channels of PCM samples in realtime, and outputs them
on the calculator's link port. Sound is played at around 24 KHz, with a total of
24 volume levels. Sound can be overdriven to ~170%.

QED68 runs best on real hardware. Tiemu produces heavy stutter on my PC, while 
VTI (which runs nowhere near the actual CPU speed of a TI-92 Plus) will fail to 
produce any sound whatsoever.

In theory, QED68 should also run on TI-89 and V200, but this has not been tested
and might require some adjustments to the code.


Composing Music
===============

QED68 comes with an utility that will convert standard eXtended Modules (.xm) to
the player's native format. The following restrictions apply:

- The module must contain exactly 4 channels.
- The global BPM must be greater than 77, and Spd must be 8.
  Sound quality degrades with increasing BPM values.
- All samples must be 8-bit, 44100 Hz.
- Samples must use forward looping or no looping.
- Instrument settings and sample pitch offsets will be ignored.
- Volume/panning and all fx commands are ignored, except E5x (finetune) and Bxx
  (jump to order).
  
Beware that sample quality will decrease significantly in the conversion 
process. The converter also boosts sample volumes beyond the maximum QED68 will 
handle without overdrive. In order to avoid overdrive, keep sample volumes 
below 75%.

The amount of sample data you can use is limited by the calculator's RAM.
xm2qed68 downsamples to 11025 Hz, so you should still be able get away with an 
.xm sized around 300-400 Kb.


Converting and Compiling
========================

You must have GCC4TI/TIGCC and tprbuilder (or the TIGCC IDE) installed to 
compile your tunes. In order to create a TI-92 Plus executable from your .xm, 
do the following:

1. Rename your .xm to "music.xm".
2. Run the xm2qed68 utility without any arguments.
3. Compile qed68.tpr, either with "tprbuilder qed68.tpr" or with TIGCC IDE.
4. Load the resulting "digiplayer.9xz" and "digi1.9xy" on your calculator.

Provided you're on *nix, have GCC4TI set up, and your .xm is already named 
"music.xm", you can simply run compile.sh to take care of the conversion 
process.


Music Data Format
=================

QED68's music data consists of four sections.

The first section is a single word-length definition of the module's speed.
Only the lower byte is actually used, the high byte must be 0. The value is 
calculated as

speed = 255-(19760/bpm)

The second section contains the song sequence. It consists of one or more 
longword pointers to the song's subsections (aka patterns), and is terminated
by a 0-longword.

A mandatory label named "sloop" must be present somewhere in the sequence.
Hence, the simplest sequence possible would be

sloop
   dc.l pattern1
   dc.l 0
   
The third section contains one or more patterns (subsections) with the actual
note and instrument data.

Note data is organized in rows, with each row consisting of a control word, 
followed by 0-4 note frequency definitions and instrument pointers.

The control word signifies how many definitions will follow. This is 
evaluated as follows:

If bit 0 is reset, channel 4 note frequency and sample pointer will be updated.
If bit 1 is reset, channel 3 note frequency and sample pointer will be updated.
If bit 2 is reset, channel 2 note frequency and sample pointer will be updated.
If bit 3 is reset, channel 1 note frequency and sample pointer will be updated.

The control word is then followed accordingly by 0-4 frequency and sample
definitions. The order is inverse, ie. starting with channel 4 and ending with
channel 1. Frequencies are word-length, sample definitions are longwords. 

At the beginning of a pattern, all 4 channels must be reloaded (so the first
control word is always 0).

If the control word is 0xFFFF, it signals the end of the pattern, ie. each
pattern must end with "dc.w $FFFF".

So, a simple pattern could look like this:

pattern1
   dc.w $0      ;ctrl word, reload all channels
   dc.w $0      ;channel 4 frequency (0 = silence)
   dc.l smp0    ;ch4 sample pointer
   dc.w $0      ;ch3 frequency
   dc.l smp0    ;ch3 sample pointer
   dc.w $1000   ;ch2 frequency
   dc.l smp3    ;ch2 sample pointer
   dc.w $2ff2   ;ch1 frequency
   dc.l smp1    ;ch1 sample pointer
   dc.w $f      ;ctrl word, don't reload anything for the next row
   dc.w $ffff   ;end of pattern


The pattern data is followed by a mandatory "blank" sample definition, to be
done as follows

   even
samples
smp0
   dc.b 0,$ff
   dc.l smp0

This is followed by one or more regular sample definitions. The following
sections discusses the sample data layout in further detail.



Sample Format
=============

- Samples are defined as unsigned, headerless, raw PCM WAVs.

- All sample volumes must be multiples of 4 (so only 0xn0, 0xn4, 0xn8, 0xnC
  are legal). Levels are divided by 4 internally.
  
- Keep in mind that only the first 24 volume levels are rendered correctly, so
  combined volume of the samples in all 4 channels should not significantly 
  exceed this limit unless you want heavy metal overdrive. In no case should
  the combined volume exceed 252. So ideally, a given sample would use a 
  maximum volume level of 6*4 = 0x18.

- Samples must be terminated with 0xFF. This acts as a stop byte, so the player
  can determine the sample's end.

- The stop byte is followed by a longword loop pointer definition. Loop points
  can be defined anywhere in the sample data (that means you can even loop to
  another sample if you like). If no looping is required, point to the blank
  sample (smp0).
  
- All samples must have an even number of bytes (including the stop byte!).


Greetings
=========

Many thanks to

- 1ng for donating his TI-92 Plus to the good cause
- Lionel Debroux for his help and advice
- Lionel Debroux again, for his work with gcc4ti, TiLP, and TI Link Guide
- all the people who've been documenting the 68k hardware over the years.