 Help for Hermit's 1 rasterline Tracker 
 ======================================

I. INTRODUCTION:
----------------
 This little project was inspired by the
CSDB music release 'Air on a Rasterline'
by Lft http://csdb.dk/release/?id=115688
 In the forum came as a competition idea 
to tweak as much as possible out of the 
SID in 1 rasterline (around 63 cycles).
 The problem was the lack of a standard
player for non-coder musicians so I try
to help them by coding this tracker...
 To fit into one rasterline, there are
quite some restrictions, but clever use
of the routine may lead to good results.

The player's knowhow from editor view:
--------------------------------------
 You can set the default SID values for 
the beginning of the tune at the left
side of the interface. These values can
be modified in the tune later by pattern
commands calling table-entries.

 Track 1 and track 2 can only play notes
as a main restriction, on top of that
the consequent notes are played legato.
So you need to leave space between notes
which are to be played normal/staccato.
 Additionally, there's a fine-detune FX
column for these channels where you can
make vibratos/slides/chorus-effects,etc.

 The strength of the player is coming
from the 3rd track's workings. This is a
track without notes, but numbers which
represent an index to the Program-table
on the right side of the user interface.
 Value 0 seen as '..' in track 3 does no
operation but every other value jumps to
the program table's given position. You
can press 'RETURN' key on a value to go 
directly into its Programtable position.
The same will go to the first free index
of the table if pressed on '..' value.

 The Program-table is a waveform-pitch
table if its first column has non-zero
value, so the left-side value is the 
waveform and the right side is the note.
The notes are absolute, no possibility
for relative arpeggios in this player...
 If the value is zero ('..') in the 1st
column the 2nd column contains a command
and the 3rd column holds a value for it.
 If the command is under $1F, it's a SID
register to be modified by the value. If
it's bigger than $f8, it's an effect to
control the player's operation, like $ff
which jumps to the given table-position.

 To optimize into 1 rastertime sometimes
the program-table execution is skipped.
The 2nd frames of patternrows are always
skipped, the 1st frames are only skipped
if no program is called at Track3 there.
 When a pattern comes in the orderlist,
the last frame of the played pattern-row 
is skipped once as well. The table-jumps
are performed in 2 steps. You must keep
these in mind when making your programs.
 When a table-program is called from 3rd
track, only the hi-byte of pitch is set
in the 1st frame, so avoid notes there.

 In the 'SLIDE' portion of the interface 
the default start-value, the speed and 
target SID-register can be set for the 
only applicable slide. The slide is only
performed once per pattern-row.

 The Orderlist works a bit different
than in other editors: You have separate
patterns for each channel. The pattern
lengths are adjustable now, and they're
arranged diffently in 2 editor-versions:
ORM: 8 of max. 32-row patterns per track
ORB: 32 patterns/track, more mem.hungry
(The optimal use of ORB is to use nearly
the same amount of 48-row patterns on
all tracks.)

 As note-pitches are fetched directly,
you can fine-detune every note up/down
in the patterns. Pressing the detune-
buttons more times makes detune bigger,
or you can type hexa-values directly.
($00..$1x-positive, $FF..$Ex-negative,
 but range is smaller for many notes.)

II. Keys to use in the editor:
------------------------------
a.playback: F1: play tune from beginning
----------- F2: play tune from marker
            F3: play selected patterns
            F4: stop / continue playback
   C= + F1..F4: same, following playback
    Back-Arrow: fast-forward at 4x speed
 Shift+B.Arrow: toggle follow-play mode
 Shift + 1/2/3: mute/unmute channel 1..3

b.navigate: F5: go to Pattern-editor
----------- F6: go to Orderlist-editor
            F7: go to Program-table
            F8: go to Menu
       C= + F5: go to SID-settings 
       C= + F7: go to Slide-settings
        C= + H: go to Help instantly
   Cursor keys: go to anywhere on screen
 Slash/UpArrow: Page-Down, with Shift:Up
       Restore: Page-Up (4 or 8 rows)

c.editing:  SPACE: toggle jam/edit modes
---------- Delete: delete in cursor-pos.
           Insert: insert in cursor-pos.
      C= + Delete: erase cur.pos,advance
        hexa keys: type numeric values
 +,- /  C= + 1..7: select octave 1..8
         C= + O/P: dec/inc patternlength
         C= + F/G: dec/inc frame-speed

d.Pattern-editor specific keys:
-------------------------------
  Cursor/TAB: navigate between tracks
      RETURN: go to Table from Track3
 Shift+SPACE: play from cursor position
  Z..M, Q..P: white piano keys, 2 octave
  S..L, 2..0: black piano keys, 2 octave
        A, 1: empty note (...) keys
      C= + C: copy pattern from cursor
      C= + V: paste buffer to cursorpos. 
   Shift+Q/W: transpose dn/up from cursr
    C= + Q/W: detune down/up from cursor
Shift/C= + D: detune note under cursor
   Shift + V: vibrato till an empty row

e.Program-table specific keys:
------------------------------
          = : toggle note/numeric views 
      RETURN: audition program (held)
  Shift+RET.: audition from cursor-pos.
 C= + RETURN: audition from table-top
 Shift+SPACE: set index to audition from

f.Orderlist-editor specific keys:
---------------------------------
      RETURN: go to pattern to edit it
 Shift+SPACE: set marker for F2-playback


III. Summary of Program-table commands:
---------------------------------------
 Column1 Column2 Column3
 01..FF  PitchHi PitchLo-> waveform,note
   ..    00..1F  00..FF -> set SID reg.
   ..      F7    00..7F -> set tempo
   ..      F8    00..FF -> slide value
   ..      F9    00..FF -> slide speed
   ..      FA    00..FF -> slide target
   ..      FB    01..7F -> stop tune
   ..      FC    00..FF -> patt.position
   ..      FD    00..FF -> orderlist pos
   ..      FE    00..FF -> NOP (nothing)
   ..      FF    00..FF -> Jump command

 *More of the SID-register settings and 
  table-commands can be put in a program
 *FD orderlist-position command is only
  executed when pattern's end is reached
  (And if you use it in the last row you
   should add 1 to the position-value.)

IV. The Menu
-------------
 From the menu you can save your tune as
it is in the memory (containing player).
The 'Exec.' version will be a startable
program while the 'SID' export will be
playable by SID-players. (.S00 can be
converted to a .sid via ORMconvert.exe )
 You can set the relocation address for
your tune, as well as the SID-model and
video-system (PAL/NTSC) for SID-exports.
 When you launch the Help it will be 
possible to return to the editor, and
then back to the Help directly, so you 
can read while learning to use the app.
 What's more, the playback will not stop
during reading the help...
 If the help wouldn't be enough to get
the idea, you might check out the inclu-
ded demo-tunes to learn some practical
tricks from them.

  file-dialog keys:
  -----------------
          F1: re-read directory
          F3: next page of directory
         TAB: switch selector/type field
              to type author-information
      RETURN: load selected/typed file


V.Summary of controllable SID-registers:
----------------------------------------
 00-01 07-08 0E-0F :Pitch low&high bytes   
                    (low byte;high byte)
 02-03 09-0A 10-11 :Pulsewidth registers
                    (low byte;hi-nybble) 
  $04   $0B   $12  :Waveform+control reg
                   (test,ring,sync,gate)
 05-06 0C-0D 13-14 :ADSR envelope reg.
                    (Att,Decay;Sust,Rel)
      $15-$16 :Filter cutoff frequency
               (low 3 bits; high 8 bits)
        $17   :Filter Resonance & Switch
               (Reso.nybble,Ch3,Ch2,Ch1)
        $18   :Filter Band / Volume reg.
               (Band nybble, Vol.nybble)


VI. Closing words
-----------------
 The player with the musicdata can be
included in programs by the usual way:
call $1000 to initialize the tune and 
call $1003 in every frame to play it.
(Relocation changes these addresses.)
 There are some zeropage-locations that
are used by code/data:  $DA..$FF
ORM: size of the player-code & tune-data
together is fix $09E8 (10 disk blocks).
ORB: size of player-code & tune-data is
determined by the biggest pattern-number

 Some tips: You might be able to create
fast filter-cutoff controlling for the
bass channel. It will come at a price
though, track3 will be occupied for that
time. But you might find out solutions,
like combing various effects....

Last, but not least, in case you'd have
an unfortunate freeze, reset & SYS 2061!

Wish you a good experience with this 
tool despite the player's simplicity...

========================================
2013 Hermit Soft.   hermit-at-upcmail.hu
========================================
