home *** CD-ROM | disk | FTP | other *** search
/ Large Pack of OldSkool DOS MOD Trackers / goattracker_2.69.diz < prev    next >
Text File  |  1996-01-01  |  81KB  |  1,902 lines

  1. Goatcompo examplesongs & commandline parameters
  2. -----------------------------------------------
  3.  
  4. Randall: I'll Be A Pimp In Cabrini Green.. (cabrinigreen.sng)  /e1 /s1 /a0ff0
  5. Richard Bayliss: Everlasting Annoyance     (everlasting.sng)   /e0 /s1 /a0f00
  6. Hein: GhostTrackers                           (ghosttrackers.sng) /e0 /s1 /a0f00
  7. Jammer: My Own Hyperspace                  (hyperspace.sng)    /e1 /s1 /a0ff0
  8. Cadaver: On A Sanction From CIA            (sanction.sng)      /e0 /s1 /a0f00
  9. No-XS: Sixpack Of Cola *                   (sixpack.sng)       /e0 /s1 /a0f00
  10.  
  11. * = based on an original song by beek
  12. GoatTracker v2.69
  13. -----------------
  14.  
  15. Editor by Lasse ╓÷rni (loorni@gmail.com)
  16. HardSID 4U support by TΘli Sßndor.
  17. Uses reSID engine by Dag Lem.
  18. Uses reSID distortion / nonlinearity by Antti Lankila.
  19. Uses 6510 crossassembler from Exomizer2 beta by Magnus Lind.
  20. Uses the SDL library.
  21. GoatTracker icon by Antonio Vera.
  22. Command quick reference by Simon Bennett.
  23. MorphOS patch by Stefan A. Haubenthal.
  24.  
  25. Distributed under GNU General Public License
  26. (see the file COPYING for details)
  27.  
  28. Covert BitOps homepage:
  29. http://covertbitops.c64.org
  30.  
  31. GoatTracker 2 SourceForge.net page:
  32. http://sourceforge.net/projects/goattracker2
  33.  
  34.  
  35. Table of contents
  36. -----------------
  37.  
  38. 1. General information
  39. 1.1 Warnings
  40. 1.2 Compatibility with v1.xx
  41.  
  42. 2. Using GoatTracker
  43. 2.1 Command line options
  44. 2.2 Hardware support
  45. 2.3 Keyboard commands
  46. 2.3.1 General keys
  47. 2.3.2 Pattern edit mode
  48. 2.3.2.1 Protracker note-entry mode
  49. 2.3.2.2 DMC note-entry mode
  50. 2.3.3 Song edit mode
  51. 2.3.4 Instrument edit mode
  52. 2.3.5 Table edit mode
  53. 2.3.6 Songname edit mode
  54. 2.4 Mouse control
  55.  
  56. 3. Song data
  57. 3.1 Orderlist data
  58. 3.2 Pattern data
  59. 3.3 Instrument data
  60. 3.4 Table data
  61. 3.4.1 Wavetable
  62. 3.4.2 Pulsetable
  63. 3.4.3 Filtertable
  64. 3.4.4 Speedtable
  65. 3.5 Playback details
  66. 3.6 Miscellaneous tips
  67. 3.6.1 Limit-based modulation steps
  68. 3.6.2 Precalculated note-independent "hifi player" portamento/vibrato
  69. 3.7 Multispeed tips
  70.  
  71. 4. Using the included utilities
  72. 4.1 INS2SND2.EXE
  73. 4.2 SNGSPLI2.EXE
  74. 4.3 MOD2SNG.EXE
  75. 4.4 BETACONV.EXE
  76.  
  77. 5. Using the songs outside the editor
  78. 5.1 Playroutine options
  79.  
  80. 6. File/data formats description
  81. 6.1 GoatTracker v2 song (.SNG) format
  82. 6.1.1 Song header
  83. 6.1.2 Song orderlists
  84. 6.1.3 Instruments
  85. 6.1.4 Tables
  86. 6.1.5 Patterns header
  87. 6.1.6 Patterns
  88. 6.2 GoatTracker v2 instrument (.INS) format
  89. 6.3 Sound effect data format
  90.  
  91. 7. Recompiling
  92.  
  93. 8. Version history
  94.  
  95.  
  96. 1. General information
  97. ----------------------
  98.  
  99. This program is a tracker-like C64 music editor running on Win32 or Linux
  100. platforms (using the SDL library, see http://www.libsdl.org)
  101.  
  102. GoatTracker v2 adds more commands and uniform step programming tables for
  103. waveform/arpeggio, pulse effects, and filter effects. It is likely much more
  104. complex to learn & master than v1.xx.
  105.  
  106. Familiarity with tracker programs in general, hexadecimal notation, and the
  107. C64's SID chip are required. Consult the C64 Programmer's Reference Guide
  108. (http://project64.c64.org) or AAY64 (http://www.the-dreams.de/aay.html) for
  109. SID chip reference.
  110.  
  111. For filesize & library compatibility reasons, precompiled binaries exist only
  112. for Win32 platform.
  113.  
  114. 1.1 Warnings
  115. ------------
  116.  
  117. 1. Always look at the end of this file for changes! Sometimes keyboard commands
  118.    change etc.
  119.  
  120. 2. Always save your songs in the .SNG-format with F11 key if you plan to
  121.    continue editing! Packed & relocated songs (PRG/BIN/SID) can not be loaded
  122.    back into the editor.
  123.  
  124. 3. Even the reSID emulation is in some cases quite far from the output of a
  125.    real SID. Especially if filters are in use, consider strongly testing your
  126.    tune on a C64 or on a HardSID card. (Using filters has always been
  127.    complicated because every SID tends to sound different.)
  128.  
  129. 4. The editor will stop playing if:
  130.    - The song restart position is illegal (beyond end of song)
  131.    - The sequence of orderlist commands is incorrect
  132.      * In a sequence of both TRANSPOSE & REPEAT, TRANSPOSE must come first
  133.      * The last thing before a RST-endmark should be a pattern number
  134.    - Gateoff timer value is too high compared to song tempo.
  135.    - The song tries to jump directly onto a table row containing a jump (FF xx),
  136.      either with instrument pointers or 8XY, 9XY, AXY commands.
  137.    - The song tries to execute pattern commands 0XY, 8XY or EXY from the
  138.      wavetable.
  139.    These all are error conditions, and trying to pack/relocate such song should
  140.    give an error message.
  141.  
  142. 5. Using delayed wavetable or no wavechange (0x 00, where x is 0-F) in the
  143.    first step of instrument wavetable is unsupported and may result in missing
  144.    notes.
  145.  
  146. 6. When using a playroutine with unbuffered SID-writes (Standard /w unbuffered
  147.    or Minimal) and encountering ADSR-bugs after packing/relocating, you can try
  148.    either:
  149.    1) Set pulse-startpos to nonzero value in the troublesome instruments and
  150.       change the 1stFrame Wave parameter of some instrument slightly, for
  151.       example from $09 to $0B, to disable a playroutine optimization. The
  152.       idea in this is to make the noteinit routine take more CPU cycles.
  153.    2) Use a playroutine with buffered writes to pack/relocate.
  154.    3) Try hardrestart attack parameter $F for alternative SID register write
  155.       order.
  156.  
  157. 7. From v2.18 onwards, wavetable left side values have changed. Delay can
  158.    now be maximum 16 frames (values $00-$0F), and waveform register values
  159.    $00-$0F (inaudible) have been mapped to table values $E0-$EF. For example,
  160.    testbit + gate would be $E9. You need to manually convert values $08-$0F
  161.    from your old songs!
  162.  
  163. 8. From v2.2 onwards, a new table (speedtable) has been added. The portamento,
  164.    vibrato and funktempo commands use it. Old songs will be converted upon
  165.    loading to use the speedtable. Note the keyboard command SHIFT+RETURN
  166.    to convert the old style parameters.
  167.  
  168. 9. From v2.4 onwards, pulse modulation speed has 1 bit added accuracy, so
  169.    you need to double pulsespeeds when composing new songs. Old songs will
  170.    be converted automatically.
  171.  
  172. 10. From v2.59 onwards, gateoff timer parameter high bit disables hardrestart
  173.    and bit $40 disables gateoff. Old songs & instruments will be converted
  174.    automatically.
  175.  
  176. 11. From v2.62 onwards, realtime calculated portamento/vibrato speeds are
  177.    supported. This is activated by having the high bit ($80) set in the speed-
  178.    table left side. Naturally, this means that very high portamento speeds (>=
  179.    $8000) or vibrato speeds (>= $80) become unavailable, but these should not 
  180.    be very useful anyway.
  181.    
  182. 12. From v2.68 onwards, SID write order has been tweaked for better stability
  183.    regarding badlines. This has the consequence, however, that notes with 
  184.    attack 0 & release 1 may ADSR-bug. In this case, try hardrestart attack 
  185.    parameter $F for alternative SID register write order.
  186.  
  187. 1.2 Compatibility with v1.xx
  188. ----------------------------
  189.  
  190. GoatTracker v2 can load v1.xx songs and instruments, but it saves only in v2
  191. format. Some subtleties (like tricks involving instrument changes) will not
  192. play back exactly like in v1.xx.
  193.  
  194. The only major feature removal is that of the arpeggio command in v2.
  195. Everything that this command does can also be done with wavetables, and the
  196. import feature converts all arpeggio commands to corresponding wavetable
  197. programs.
  198.  
  199.  
  200. 2. Using GoatTracker
  201. --------------------
  202.  
  203. 2.1 Command line options
  204. ------------------------
  205.  
  206. Start Goattracker V2 by typing GOATTRK2 in the command prompt, followed by the
  207. songname to be loaded at startup (optional) and any command line options you
  208. may want. For example "goattrk2 dojo.sng /s1 /e1" to set 1x-speed mode and SID
  209. model 8580 and to load "dojo.sng" on startup.
  210.  
  211. /Axx Set hard restart ADSR parameter in hex. DEFAULT=0F00
  212. /Bxx Set sound buffer length in milliseconds DEFAULT=100
  213. /Cxx Use CatWeasel MK3 PCI SID (0 = off, 1 = on)
  214. /Dxx Pattern row display (0 = decimal, 1 = hexadecimal)
  215. /Exx Set emulated SID model (0 = 6581 1 = 8580) DEFAULT=6581
  216. /Fxx Set custom SID clock cycles per second (0 = use PAL/NTSC default)
  217. /Hxx Use HardSID (0 = off, 1 = HardSID ID0 2 = HardSID ID1 etc.)
  218. /Ixx Set reSID interpolation (0 = off, 1 = on, 2 = distortion, 3 = distortion & on) DEFAULT=off
  219. /Kxx Note-entry mode (0 = PROTRACKER 1 = DMC) DEFAULT=PROTRK.
  220. /Lxx SID memory location in hex. DEFAULT=D400
  221. /Mxx Set sound mixing rate DEFAULT=44100
  222. /Oxx Set pulse optimization/skipping (0 = off, 1 = on) DEFAULT=on
  223. /Rxx Set realtime command optimization/skipping (0 = off, 1 = on) DEFAULT=on
  224. /Sxx Set speed multiplier (0 for 25Hz, 1 for 1x, 2 for 2x etc.)
  225. /Txx Set HardSID interactive mode sound buffer length in milliseconds
  226.      DEFAULT=20, max.buffering=0
  227. /Uxx Set HardSID playback mode sound buffer length in milliseconds
  228.      DEFAULT=400, max.buffering=0
  229. /Vxx Set finevibrato conversion (0 = off, 1 = on) DEFAULT=on
  230. /Zxx Set random reSID write delay in cycles (0 = off) DEFAULT=off
  231. /N   Use NTSC timing
  232. /P   Use PAL timing (DEFAULT)
  233. /W   Write emulated sound output to a file SIDAUDIO.RAW
  234. /?   Show command line options
  235.  
  236. Try the command line options if there are any problems. For example, if you
  237. experience choppy audio you can increase audio buffering with /B option. SDL
  238. seems to have trouble with some soundcards under Windows; you might want to
  239. try even a 500ms buffer, or tweak the hardware acceleration level of the
  240. soundcard (from Control Panel). Also, reSID interpolation will take remarkably
  241. more CPU time and could cause the sound and/or editing to get choppy.
  242.  
  243. Finevibrato mode is on by default. You can change this behaviour with /V
  244. option. Note that finevibrato mode only affects the conversion of old style
  245. vibrato parameters to speedtable format.
  246.  
  247. Pulse optimization /O determines if pulsetable execution will be skipped when
  248. getting new notes or a new pattern. By default it is on. Be warned that
  249. turning it off will increase the rastertime requirements of packed/relocated
  250. songs greatly!
  251.  
  252. Realtime command optimization /R determines if portamento, vibrato & instrument
  253. vibrato will be skipped on tick 0 of each pattern row. By default it is on, as
  254. this is how tracker programs have operated traditionally. Turning it off makes
  255. the commands sound same regardless of tempo but will increase rastertime use.
  256.  
  257. The hard restart ADSR parameter will especially affect how rapid passages of
  258. notes will sound like. 0000 is probably too hard to be useful, except perhaps
  259. with gateoff timer value 1. 0F00 (default) is a lot softer, and 0F01 adds also
  260. a little bit of release to the gateoff phase for even softer sound. 000F makes
  261. the note start very pronounced.
  262.  
  263. Hard restart parameter with attack at maximum (F) enables the use of an
  264. alternative playroutine, where waveform is written before ADSR. This can give
  265. more reliable note triggering, especially for very fast releases 0 & 1, but 
  266. may change the characteristics of the note's decay & release.
  267.  
  268. 2.2 Hardware support
  269. --------------------
  270.  
  271. HardSID support is available with the /H option (use first HardSID = /H1,
  272. second = /H2 etc., return to emulated output = /H0). You must have the HardSID
  273. drivers installed to use this feature.
  274.  
  275. CatWeasel MK3 PCI SID support is available with /C option (/C1 to turn on).
  276.  
  277. To use the PC64 cable, you need Daniel Illgen's HardSID-DLL-Clone. Available at
  278. http://dawork.synchronus.de/
  279.  
  280. To enable better support of multispeeds and cycle-exact timing on HardSID
  281. (currently Win32 only), download an enhanced HardSID.dll:
  282.  
  283. For HardSID ISA/PCI cards -
  284. http://sourceforge.net/project/showfiles.php?group_id=9266&release_id=61843
  285.  
  286. For HardSID 4U -
  287. http://www.hardsid.com
  288.  
  289. Cycle-exact HardSID buffer length is separately configurable for interactive
  290. mode (/T option) & playback mode (/U option).
  291.  
  292. HardSID interactive mode:
  293. Low latency mode for jamming and accurate GUI display. Interactive mode can
  294. be activated during song/pattern playback by enabling jamming (space key).
  295.  
  296. HardSID playback mode:
  297. High stability mode to avoid interruptions caused by other applications/poor
  298. drivers/weaker CPU. GUI display is less accurate in this mode. Set the /U
  299. parameter to zero to achieve the maximum stability (less accurate GUI).
  300.  
  301. 2.3 Keyboard commands
  302. ---------------------
  303.  
  304. This program is mainly operated on keyboard. For a list of keyboard commands
  305. press F12 (online help) in the tracker or see the table below:
  306.  
  307. NOTE: SHIFT & CTRL are interchangeable in the commands. You can also use [ ]
  308. or ( ) instead of < >.
  309.  
  310. 2.3.1 General keys
  311. ------------------
  312.  
  313. F1        Play from beginning
  314. F2        Play from current pos.
  315. F3        Play one pattern from current pos.
  316. F4        Stop playing & silence all sounds
  317. F5        Go to pattern editor
  318. F6        Go to song editor
  319. F7        Go to instrument/table editor
  320. F8        Go to songname editor
  321. F9        Pack, relocate & save PRG,SID etc.
  322. F10       Load song (Pattern/Song/Songname mode) or instrument (Instrument mode)
  323. F11       Save song (Pattern/Song/Songname mode) or instrument (Instrument mode)
  324. F12       Online help screen
  325. SHIFT+F1  Play from beginning /w follow play
  326. SHIFT+F2  Play from current pos. /w follow play
  327. SHIFT+F3  Play one pattern from current pos. /w follow play
  328. SHIFT+F4  Mute current channel
  329. SHIFT+F5  Decrease speed multiplier
  330. SHIFT+F6  Increase speed multiplier
  331. SHIFT+F7  Edit hardrestart ADSR parameter
  332. SHIFT+F8  Switch between 6581 and 8580 SID models
  333. SHIFT+,.  Move song startposition on all channels and restart last playmode
  334. TAB       Cycle between editing modes (forwards)
  335. SHIFT+TAB Cycle between editing modes (backwards)
  336. INS       Insert row (Press INS/DEL on endmark to change pattern/song length)
  337. DEL       Delete row
  338. SHIFT+ESC Optimize musicdata, or clear musicdata & set default pattern length
  339. ESC       Exit program
  340.  
  341. 2.3.2 Pattern edit mode
  342. -----------------------
  343.  
  344. - +         Select instrument
  345. / *         Select octave
  346. < >         Select pattern
  347. BACKQUOTE   Select channel
  348. 0-9 & A-F   Enter parameters
  349. SPACE       Switch between jam/editmode
  350. RETURN      (also CAPSLOCK) Insert keyoff
  351.             Enter table (when cursor is over a table-utilizing command)
  352.             Enter instrument (when cursor is over a nonzero instrument number)
  353. SHIFT+RET.  Insert keyon
  354.             Convert portamento/vibrato/funktempo old style parameter to a
  355.             speedtable entry (when cursor is over the command)
  356.             Go into an empty table entry (when parameter is zero on a
  357.             table-utilizing command)
  358. BACKSPACE   Insert rest
  359. SHIFT+BKSP. Insert rest and clear commands
  360. SHIFT+SPACE Play from cursor position
  361. SHIFT+Q     Transpose halfstep up
  362. SHIFT+A     Transpose halfstep down
  363. SHIFT+W     Transpose octave up
  364. SHIFT+S     Transpose octave down
  365. SHIFT+O     Shrink pattern (divide size by 2)
  366. SHIFT+P     Expand pattern (multiply size by 2)
  367. SHIFT+J     Join pattern with next pattern in orderlist
  368. SHIFT+K     Split pattern from edit position
  369. SHIFT+H     Calculate "hifi" left/right shifted speedtable entry for
  370.             portamento or vibrato
  371. SHIFT+I     Invert selection / whole pattern if no selection
  372. SHIFT+CRSR UP,DOWN Mark pattern
  373. SHIFT+CRSR LEFT,RIGHT Select pattern
  374. SHIFT+L     Mark/unmark entire pattern
  375. SHIFT+M,N   Choose highlighting step size
  376. SHIFT+X,C,V Cut,copy,paste pattern
  377. SHIFT+E,R   Copy,paste commands
  378. SHIFT+Z     Cycle autoadvance-mode
  379.  
  380. For pattern joining to work properly, select the pattern you want to join with
  381. the next from the orderlist first (by pressing RETURN on it). Both joining and
  382. splitting will rearrange pattern numbers (for example if you split pattern 00,
  383. pattern 01 will be created and old patterns 01-xx will be shifted forward in
  384. the pattern order)
  385.  
  386. SHIFT+SPACE will play from the pattern onwards if playback was previously
  387. stopped, but if it is pressed while in pattern play mode, it will stay in
  388. the current pattern.
  389.  
  390. There are 2 modes for note entering:
  391.  
  392. 2.3.2.1 Protracker note-entry mode
  393. ----------------------------------
  394.  
  395. This is the default or activated with command line option /K0. There are two
  396. rows of a piano keyboard:
  397.  
  398.   Lower octave     Higher octave
  399.  S D  G H  K L    2 3  5 6 7  9 0
  400. Z X CV B NM , .  Q W ER T Y UI O P
  401.  
  402. Octave (0-7) is selected with / and * keys on the numeric keypad.
  403.  
  404. In this mode there are 2 different autoadvance-modes (the mode can be seen from
  405. the color of the jam/editmode indicator)
  406.  
  407. GREEN - Advance when entering notes & command-databytes
  408. RED - Do not advance automatically
  409.  
  410. 2.3.2.2 DMC note-entry mode
  411. ---------------------------
  412.  
  413. Activated with command line option /K1, there is one row of piano keyboard
  414.  
  415.  W E  T Y U  O P
  416. A S DF G H JK L
  417.  
  418. and octave of a note (sets default octave at the same time) is changed with
  419. number keys 0-7.
  420.  
  421. In this mode there are 3 different autoadvance-modes:
  422.  
  423. GREEN - Advance when entering notes, octaves or command-databytes
  424. YELLOW - Advance when entering notes or command-databytes, not octaves
  425. RED - Do not advance automatically
  426.  
  427. 2.3.3 Song edit mode
  428. --------------------
  429.  
  430. < >         Select subtune
  431. - +         Insert Transpose down/up command (shown as -/+ in the orderlist)
  432. 0-9 & A-F   Enter pattern numbers
  433. SPACE       Set start position for F2 key
  434. BACKSPACE   Set end position for F2 key
  435. RETURN      Go to pattern
  436. SHIFT+R     Insert Repeat command (shown as "R" in the order-list)
  437. SHIFT+CRSR LEFT/RIGHT Mark orderlist
  438. SHIFT+1,2,3 Swap current channel orderlist with channel 1,2,3
  439. SHIFT+X,C,V Cut,copy,paste channel orderlist
  440. SHIFT+L     Mark/unmark entire orderlist
  441. SHIFT+SPACE Set start position on all channels
  442. SHIFT+RET.  Go to pattern on all channels
  443.  
  444. SHIFT+SPACE or SHIFT+BACKSPACE set the start/end mark on all channels to
  445. the same position. To clear the endmark, press BACKSPACE again on it or
  446. at/before the startmark.
  447.  
  448. 2.3.4 Instrument edit mode
  449. --------------------------
  450.  
  451. < >         Select instrument
  452. - +         Select instrument
  453. / *         Select octave
  454. F7          Go to table editor
  455. 0-9 & A-F   Enter parameters
  456. SPACE       Play test note
  457. SHIFT+SPACE Silence test note
  458. RETURN      Go to table position indicated by wave/pulse/filter/vibratopos.
  459. SHIFT+N     Edit instrument name
  460. SHIFT+S     Smart paste an instrument
  461. SHIFT+U     Unlock/lock table scrolling
  462. SHIFT+X,C,V Cut,copy,paste instrument
  463. SHIFT+DEL   (also SHIFT+BACKSPACE) Delete instrument & tabledata
  464. SHIFT+RET.  Set tablepointer to empty position or convert old style vibrato
  465.             parameter
  466.  
  467. The test note will be played on the channel you last were on in the pattern
  468. editor. To hear filtering as intended, be sure to play it on a channel that has
  469. been selected for filtering in the filter parameters.
  470.  
  471. Note that cut,copy,paste instrument do not touch the tabledata, just for the
  472. case you need it in another instrument. If you want to completely get rid of
  473. an instrument + its associated tabledata, press SHIFT+DEL.
  474.  
  475. If wave/pulse/filter/vibrato param. is zero and you press RETURN over
  476. it, you will move to the first free location in the corresponding table. If
  477. you press SHIFT+RETURN, also the instrument parameter will be set accordingly.
  478.  
  479. If vibrato parameter is nonzero and you press SHIFT+RETURN over it, it will
  480. be interpreted as an old style vibrato parameter (left nybble speed, right
  481. nybble depth) and converted to a speedtable entry.
  482.  
  483. "Smart paste" will convert instrument numbers in all patterns if you "move" an
  484. instrument by cut/pasting it.
  485.  
  486. 2.3.5 Table edit mode
  487. ---------------------
  488.  
  489. < >         Select instrument
  490. - +         Select instrument
  491. / *         Select octave
  492. BACKQUOTE   Select table
  493. F7          Go to instrument editor
  494. 0-9 & A-F   Enter parameters
  495. SPACE       Play test note
  496. SHIFT+SPACE Silence test note
  497. RETURN      Go back to wave/pulse/filterpos. parameter
  498. SHIFT+Q,A   Transpose speedtable portamento speed halfstep up/down
  499. SHIFT+W,S   Transpose speedtable portamento speed octave up/down,
  500.             or multiply/divide pulse/filterspeed by 2
  501. SHIFT+L     Convert <limit,speed> modulation step to <time,speed>
  502. SHIFT+N     Negate speed parameter (pulse/filtertable) or relative note
  503.             (wavetable)
  504. SHIFT+O     Optimize current table (remove unused entries)
  505. SHIFT+R     Convert note between absolute/relative in wavetable
  506. SHIFT+U     Unlock/lock table scrolling
  507.  
  508. If you need to insert rows in the beginning of an instrument's wave/pulse/
  509. filtertable, press SHIFT+INS instead of just INS: this way table pointers
  510. pointing to the table first row will not move.
  511.  
  512. For easier programming of negative modulation speeds in pulse/filtertables, you
  513. can first enter a positive speed positive value ($00-$7F) and then press
  514. SHIFT+N to negate it.
  515.  
  516. Conversion between relative and absolute notes will use the basenote C-0 if
  517. octave is 0, C-1 if octave is 1 and so on.
  518.  
  519. When table scrolling is unlocked, each table maintains its separate view
  520. position. To indicate this mode, a "U" letter is visible in the bottom right
  521. part of the screen. By default table scrolling is locked.
  522.  
  523. 2.3.6 Songname edit mode
  524. ------------------------
  525.  
  526. Use cursor UP/DOWN to move between song, author & copyright strings, and
  527. other keys to edit them.
  528.  
  529. 2.4 Mouse control
  530. -----------------
  531.  
  532. By clicking with the left mouse button, you can select the data to edit.
  533.  
  534. By dragging with middle or right mouse button, you can mark orderlist/pattern/
  535. tabledata.
  536.  
  537. Some values like octave or subtune/pattern numbers can be incremented with
  538. the left mouse button and decremented with the right.
  539.  
  540. By holding the middle/right mouse button in the status bar, a menu becomes
  541. active. Continue to hold and click with left button to select options.
  542.  
  543. In the fileselector, confirm loading or entering a directory by double-
  544. clicking. Doubleclick outside the selector to cancel.
  545.  
  546.  
  547. 3. Song data
  548. ------------
  549.  
  550. 3.1 Orderlist data
  551. ------------------
  552.  
  553. A song can consist of up to 32 subtunes. For each subtune's each channel, there
  554. is an orderlist which determines in what order patterns are to be played. In
  555. addition to pattern numbers, there can be TRANSPOSE & REPEAT commands and
  556. finally there is a RST (RESTART) endmark followed by restart position. The
  557. maximum length of an orderlist is 254 pattern numbers/commands + the endmark.
  558.  
  559. TRANSPOSE is measured in halftones. Transpose up (shown as +X) can be 0-14
  560. halftones and transpose down (shown as -X) can be 1-15. Transpose is
  561. automatically reset only when starting the song, not when looping.
  562.  
  563. A REPEAT command (shown as RX) will repeat the pattern following it 1-16 times.
  564. "Repeat 16 times" is displayed as R0.
  565.  
  566. There are some rules for orderlist command order:
  567.  
  568. - If there are both TRANSPOSE and REPEAT commands before a pattern number,
  569.   TRANSPOSE must come first.
  570.  
  571. - The last thing before the RST-endmark must be a pattern number. If you need
  572.   to reset transpose on song repeat, do it in the beginning of the repeat loop.
  573.  
  574. In case of wrong order, the editor will halt playback. This tells that the
  575. resulting packed/relocated song would play incorrectly.
  576.  
  577. 3.2 Pattern data
  578. ----------------
  579.  
  580. Patterns are single-channel only for flexibility & low memory use. They contain
  581. the actual notes, instrument changes & sound commands. A pattern can have
  582. variable length, up to 128 rows. There can be 208 different patterns in a song.
  583.  
  584. The explanation of a pattern row:
  585.  
  586.  Note name
  587.  |
  588.  | Octave
  589.  | |
  590.  | | Instrument number ($01 - $3F, or $00 for no change)
  591.  | | |
  592.  | | |  Command ($0 - $F)
  593.  | | |  |
  594.  | | |  | Databyte
  595.  | | |  | |
  596.  C-1 00 0 00
  597.  
  598. The highest note available in a pattern is G#7. To reach the top three notes
  599. (A-7 to B-7), you can use transpose.
  600.  
  601. In place of a normal note, there can also be one of these special "notes":
  602.  
  603.  ... Rest
  604.  --- Key off (clear gatebit mask)
  605.  +++ Key on (set gatebit mask)
  606.  
  607. The actual state of the gatebit will be the gatebit mask ANDed with data from
  608. the wavetable. A key on cannot set the gatebit if it was explicitly cleared
  609. at the wavetable.
  610.  
  611. Commands 1XY-4XY and FXY bear some resemblance to Soundtracker/Protracker/
  612. Fasttracker effect commands. However, they are different in some ways, so
  613. read their descriptions! Note that there is no "databyte $00 uses the last
  614. databyte"-action in the commands.
  615.  
  616. Command 0XY: Do nothing. Databyte will always be $00.
  617.  
  618. Command 1XY: Portamento up. XY is an index to a 16-bit speed value in the
  619.              speedtable.
  620.  
  621. Command 2XY: Portamento down. XY is an index to a 16-bit speed value in the
  622.              speedtable.
  623.  
  624. Command 3XY: Toneportamento. Raise or lower pitch until target note has been
  625.              reached. XY is an index to a 16-bit speed value in the
  626.              speedtable, or $00 for "tie-note" effect (move pitch instantly to
  627.              target note)
  628.  
  629. Command 4XY: Vibrato. XY is an index to the speed table, where left side
  630.              determines how long until the direction changes (speed)
  631.              and right side determines the amount of pitch change on each tick
  632.              (depth).
  633.  
  634. Command 5XY: Set attack/decay register to value XY.
  635.  
  636. Command 6XY: Set sustain/release register to value XY.
  637.  
  638. Command 7XY: Set waveform register to value XY. If a wavetable is actively
  639.              changing the channel's waveform at the same time, will be
  640.              ineffective.
  641.  
  642. Command 8XY: Set wavetable pointer. $00 stops wavetable execution.
  643.  
  644. Command 9XY: Set pulsetable pointer. $00 stops pulsetable execution.
  645.  
  646. Command AXY: Set filtertable pointer. $00 stops filtertable execution.
  647.  
  648. Command BXY: Set filter control. X is resonance and Y is channel bitmask.
  649.              $00 turns filter off and also stops filtertable execution.
  650.  
  651. Command CXY: Set filter cutoff to XY. Can be ineffective if the filtertable is
  652.              active and also changing the cutoff.
  653.  
  654. Command DXY: Set mastervolume to Y, if X is $0. If X is not $0, value XY is
  655.              copied to the timing mark location, which is playeraddress+$3F.
  656.  
  657. Command EXY: Funktempo. XY is an index to the speedtable, tempo will alternate
  658.              between left side value and right side value on subsequent pattern
  659.              steps. Sets the funktempo active on all channels, but you can use
  660.              the next command to override this per-channel.
  661.  
  662. Command FXY: Set tempo. Values $03-$7F set tempo on all channels, values $83-
  663.              $FF only on current channel (subtract $80 to get actual tempo).
  664.              Tempos $00-$01 recall the funktempo values set by EXY command.
  665.  
  666. Master volume is by default the maximum ($F), but it is only reset when loading
  667. a new song or clearing songdata in the editor, not every time playback starts.
  668. If you change mastervolume, you have to reset it manually in the beginning of
  669. your song.
  670.  
  671. If the command is not 1XY-4XY, instrument vibrato will be active.
  672.  
  673. Note that the one-shot commands 5XY-FXY allow the previous 1XY-4XY command or
  674. instrument vibrato to continue "underneath" them. In section 3.6 (hints & tips)
  675. there is an example of this.
  676.  
  677. 3.3 Instrument data
  678. -------------------
  679.  
  680. You can use up to 63 different instruments in a song. Each instrument is
  681. defined by 9 parameters:
  682.  
  683. Attack/Decay          $0 is fastest attack or decay, $F is slowest
  684.  
  685. Sustain/Release       Sustain level $0 is silent and $F is the loudest. Release
  686.                       behaves like Attack & Decay (F slowest).
  687.  
  688. Wavetable Pos         Wavetable startposition. Value $00 stops the wavetable
  689.                       execution and is not very useful.
  690.  
  691. Pulsetable Pos        Pulsetable startposition. Value $00 will leave pulse
  692.                       execution untouched.
  693.  
  694. Filtertable Pos       Filtertable startposition. Value $00 will leave filter
  695.                       execution untouched. In most cases it makes sense to have
  696.                       a filter-controlling instrument only on one channel at a
  697.                       time.
  698.  
  699. Vibrato Param         Instrument vibrato parameter. An index to the speedtable,
  700.                       see command 4XY.
  701.  
  702. Vibrato Delay         How many ticks until instrument vibrato starts. Value $00
  703.                       turns instrument vibrato off.
  704.  
  705. HR/Gate Timer         How many ticks before note start note fetch, gateoff and
  706.                       hard restart happen. Can be at most tempo-1. So on tempo 4
  707.                       highest acceptable value is 3. Bitvalue $80 disables hard
  708.                       restart and bitvalue $40 disables gateoff.
  709.  
  710. 1stFrame Wave         Waveform used on init frame of the note, usually $09 (gate
  711.                       + testbit). Values $00, $FE and $FF have special meaning:
  712.                       leave waveform unchanged and additionally set gate off
  713.                       ($FE), gate on ($FF), or gate unchanged ($00).
  714.  
  715. In case of illegal (too high) gateoff timer values, the song playback is
  716. stopped.
  717.  
  718. ADSR settings are crucial to getting any sound at all. If all of them are zero
  719. just a very short "click" will be heard. Here is a diagram to help you
  720. visualize the Attack, Decay, Sustain & Release phases:
  721.  
  722.      V      /\            |<- gatebit reset (key-off) at this point
  723.      O     /  \           |
  724.      L    /    \__________|
  725.      U   /                |\
  726.      M  /                 | \
  727.      E /                  |  \
  728. TIME ---------------------------->
  729.          A   D      S       R
  730.  
  731. Some ADSR examples:
  732.  
  733.   A/D 09 Will produce a sound that starts from full volume right away and fades
  734.   S/R 00 to silence automatically. By increasing the Decay value, the fade will
  735.          last longer.
  736.  
  737.   A/D 00 A sound that goes very fast from full volume to sustain level 8.
  738.   S/R 8A If you increase the Decay value, it will go to the sustain level
  739.          slower. After key-off, starts fading out with speed A.
  740.  
  741.   A/D CC A sound that rises slowly to maximum volume, then decays slowly to the
  742.   S/R AF sustain level A and after key-off, fades out to silence very slowly.
  743.  
  744. Instrument legato works as following: When HR/Gate Timer parameter has bit $40
  745. set, no hard restart or gateoff will be performed. When 1st Frame Wave is also
  746. $00, no 1st frame waveform will be set and gate flag is untouched. However wave/
  747. pulse/filterpointers and ADSR are initialized normally. You can also use this in
  748. conjunction with command 8XY to set another wavetable pointer for the note.
  749.  
  750. 3.4 Table data
  751. --------------
  752.  
  753. Tables control the execution of instruments' waveform/arpeggio changes, pulse
  754. modulation, and filter modulation. All the tables are controlled by the left
  755. side bytes, while the right side byte specifies additional parameters.
  756.  
  757. Note that you should never jump directly onto a table jump command (FF) either
  758. with instrument parameters or pattern commands 8XY, 9XY, AXY. Otherwise,
  759. results are undefined.
  760.  
  761. 3.4.1 Wavetable
  762. ---------------
  763.  
  764. Wavetable left side:   00    Leave waveform unchanged
  765.                        01-0F Delay this step by 1-15 frames
  766.                        10-DF Waveform values
  767.                        E0-EF Inaudible waveform values $00-$0F
  768.                        F0-FE Execute command 0XY-EXY. Right side is parameter.
  769.                        FF    Jump. Right side tells position ($00 = stop)
  770.  
  771. Wavetable right side:  00-5F Relative notes
  772.                        60-7F Negative relative notes (lower pitch)
  773.                        80    Keep frequency unchanged
  774.                        81-DF Absolute notes C#0 - B-7
  775.  
  776. Short explanation of waveform bitvalues:
  777. 01 = Gatebit. When on, initiates attack/decay/sustain phase. When off,
  778.      initiates the release phase.
  779. 02 = Synchronize. Creates weird effects using output of another channel
  780. 04 = Ring modulation. Creates weird effects using output of another channel.
  781.      Most effective with the triangle waveform.
  782. 08 = Testbit. Silences sound and resets the oscillator.
  783. 10 = Triangle waveform.
  784. 20 = Sawtooth waveform.
  785. 40 = Pulse waveform.
  786. 80 = Noise waveform.
  787.  
  788. All waveforms except noise can be combined (for example triangle+pulse), but
  789. the effect will be different on 6581 and 8580 SID chips, so use caution.
  790.  
  791. The way how the channels work with synchronize/ringmod:
  792. - When used on channel 1, channel 3's output modulates the sound.
  793. - When used on channel 2, channel 1's output modulates the sound.
  794. - When used on channel 3, channel 2's output modulates the sound.
  795.  
  796. Wavetable delay or no wavechange should not be used in the first step of
  797. instrument wavetable. Otherwise, missing notes may be caused. On the other
  798. hand, if you use 8XY command to jump into a wavetable program, those are
  799. allowed.
  800.  
  801. Using wavetable delay or a wavetable step with no frequency change allows
  802. realtime commands & instrument vibrato to be executed together with wave-
  803. table. Be warned that this has the potential for large rastertime usage!
  804.  
  805. You can execute pattern commands from the wavetable. Right side
  806. is the command parameter. Note that commands 0XY (do nothing), 8XY (set
  807. wavetable pointer) and EXY (funktempo) are illegal and should not be used.
  808. When executing a command, no wave/note will be changed on the same frame.
  809.  
  810. Some examples of wave tables (all examples start on table step 1)
  811.  
  812.   01: 21 00 Sawtooth waveform on note's original pitch.
  813.   02: FF 00
  814.  
  815.   01: 41 00 A flute sound with pulse on the first tick and triangle on all
  816.   02: 11 00 the rest.
  817.   03: FF 00
  818.  
  819.   01: 41 01 A "koto" sound that is one halfstep higher on the first tick and
  820.   02: 40 00 on original pitch the next. Gatebit is also cleared on the second
  821.   03: FF 00 tick.
  822.  
  823.   01: 81 D0 A snaredrum sound, using all absolute notes so it does not depend
  824.   02: 41 AA on which note it's played. Use pulsewidth 800 for best result.
  825.   03: 41 A4
  826.   04: 80 D4
  827.   05: 80 D1
  828.   06: FF 00
  829.  
  830.   01: 81 DF A pulse sound on original pitch, preceded with a short noise (like
  831.   02: 41 00 a hi-hat or something) that has always an absolute pitch of B-7.
  832.   03: FF 00
  833.  
  834.   01: 41 00 A 4-note looping arpeggio sound with pulse waveform. Note that
  835.   02: 00 04 waveform does not change in the looping part.
  836.   03: 00 07
  837.   04: 00 0C
  838.   05: 00 00
  839.   06: FF 02
  840.  
  841.   01: 21 00 A delayed minor chord arpeggio with sawtooth waveform. Each step
  842.   02: 02 03 takes 3 ticks.
  843.   03: 02 07
  844.   04: 02 00
  845.   05: FF 02
  846.  
  847.   01: 41 00 Use pulse first, but then switch between pulse & triangle every 5
  848.   02: 03 80 ticks while frequency remains unchanged (allowing for vibrato &
  849.   03: 11 80 slides).
  850.   04: 03 80
  851.   05: 41 80
  852.   06: FF 02
  853.  
  854.   01: 81 CF Short noise in the beginning, sawtooth, after a short delay change
  855.   02: 21 00 sustain/release (via pattern command 6XY) to $2A.
  856.   03: 08 00
  857.   04: F6 2A
  858.   05: FF 00
  859.  
  860.  
  861. 3.4.2 Pulsetable
  862. ----------------
  863.  
  864. Pulsetable left side:  01-7F Pulse modulation step. Left side indicates time
  865.                              and right side the speed (signed 8-bit value).
  866.                        8X-FX Set pulse width. X is the high 4 bits, right
  867.                              side tells the 8 low bits.
  868.                        FF    Jump. Right side tells position ($00 = stop)
  869.  
  870. Some examples of pulse tables (all examples start on table step 1)
  871.  
  872.   01: 88 00 Set pulse value $800 (middle)
  873.   02: FF 00 Stop pulse execution
  874.  
  875.   01: 80 10 Set pulse value $010 (very thin)
  876.   02: 20 40 For 32 ticks, increase pulse with speed $0040 (64)
  877.   03: 40 E0 For 64 ticks, decrease pulse with speed $FFE0 (-32)
  878.   04: 40 20 For 64 ticks, increase pulse with speed $0020 (32)
  879.   05: FF 03 Jump back to step 03 for a nice loop
  880.  
  881. 3.4.3 Filtertable
  882. -----------------
  883.  
  884. Filtertable left side: 00    Set cutoff, indicated by right side
  885.                        01-7F Filter modulation step. Left side indicates time
  886.                              and right side the speed (signed 8-bit value)
  887.                        80-F0 Set filter parameters. Left side high nybble
  888.                              tells the passband ($90 = lowpass, $A0 = bandpass
  889.                              etc.) and right side tells resonance/channel
  890.                              bitmask, as in command BXY.
  891.                        FF    Jump. Right side tells position ($00 = stop)
  892.  
  893. If "Set filter parameters" is followed by "Set cutoff" directly below, both
  894. will be executed on the same frame.
  895.  
  896. Some examples of filter tables (all examples start on table step 1)
  897.  
  898.   01: 90 F1 Set lowpass, resonance F, channel bitmask 1 (filter channel 1 only)
  899.   02: 00 40 Set cutoff to $40
  900.   03: FF 00 Stop filter execution
  901.  
  902.   01: 80 00 No passband selected, resonance 0, bitmask 0 (no filtered channels)
  903.   02: FF 00 Stop filter execution
  904.  
  905.   01: A0 87 Set bandpass, resonance 8, channel bitmask 7 (filter all channels)
  906.   02: 00 00 Set cutoff to $00
  907.   03: 7F 01 Increase cutoff with speed $01 for 127 ticks
  908.   04: 7F 01 Continue cutoff increase
  909.   05: 7F FF Then decrease back to starting position (speed $FF = -1)...
  910.   06: 7F FF
  911.   07: FF 03 ...and loop back to step 03
  912.  
  913.   01: C0 F2 Set highpass, resonance F, channel bitmask 2 (filter channel 2)
  914.   02: 00 F0 Set cutoff to $F0
  915.   03: 90 F2 On the next frame, change to lowpass...
  916.   04: 00 50 ...and set cutoff $50
  917.   05: FF 00 Stop filter execution
  918.  
  919. Note that the second example could also be achieved simply with pattern command
  920. B00 (set filter control, and stop filter execution, because parameter was $00)
  921.  
  922. 3.4.4 Speedtable
  923. ----------------
  924.  
  925. The speedtable is shared by vibrato, portamento and funktempo. No jump commands
  926. exist.
  927.  
  928. For vibrato:          XX YY Left side tells how long until vibrato direction
  929.                             changes (speed), right side is the value added to
  930.                             pitch each tick (depth).
  931.  
  932. For portamento:       XX YY A 16-bit value added to pitch each tick. Left side
  933.                             is the MSB and the right side the LSB.
  934.  
  935. For funktempo:        XX YY Two 8-bit tempo values that are alternated on each
  936.                             pattern row, starting from the left side.
  937.  
  938. For both vibrato and portamento, if XX has the high bit ($80) set, note 
  939. independent vibrato depth / portamento speed calculation is enabled, and YY
  940. specifies the divisor (higher value -> lower result and more rastertime taken).
  941.  
  942. Vibrato examples:
  943.  
  944.   01: 03 40 Vibrato with speed $03 and depth $40. Corresponds to old vibrato
  945.             parameter $34
  946.   01: 05 04 Speed $05 and depth $04. Slow shallow vibrato, suitable for bass
  947.             notes. Not possible to achieve with old parameters.
  948.   01: 83 04 Speed $03, note-independent depth enabled, depth divisor 4 right-
  949.             shifts (division by 16).
  950.  
  951. Portamento examples:
  952.  
  953.   01: 00 20 Portamento with speed $0020, corresponds to old parameter $08
  954.             (4 * $08 = $0020).
  955.   01: 01 00 Portamento with speed $0100, corresponds to old parameter $40
  956.             (4 * $40 = $0100).
  957.   01: 4F FF Portamento with speed $4fff, loops the pitch highbyte very fast
  958.             so that a SEUCK-like "space" effect is heard. Not possible to
  959.             achieve with old parameters.
  960.   01: 80 01 Note-independent speed enabled, speed divisor 1 rightshift
  961.             (division by 2).
  962.  
  963. Funktempo examples:
  964.  
  965.   01: 09 06 Play tempo $09 on even pattern steps and $06 on odd steps,
  966.             corresponds to old parameter $96.
  967.  
  968.   01: 24 18 The same funktempo adjusted for 4x-multispeed. Not possible to
  969.             achieve with old parameters.
  970.  
  971. Note that you can enter old style vibrato parameters, portamento speeds and
  972. funktempo to patterns & instruments, and when cursor is over the parameter,
  973. press SHIFT+RETURN to create a new speedtable entry corresponding to that
  974. parameter. The parameter will now be overwritten by a speedtable pointer.
  975.  
  976.  
  977. 3.5 Playback details
  978. --------------------
  979.  
  980. Each pattern row is divided into as many 50Hz/60Hz "ticks" as the tempo
  981. indicates. Some ticks are reserved for special actions, and to conserve raster-
  982. time, certain realtime effects/commands (pulse, vibrato, portamento) are
  983. skipped at the same time. Let's assume a tempo of 6 and gateoff timer value 2
  984. and look at what happens on each tick:
  985.  
  986. Tick    Actions
  987. 0       - Initialization of new notes (no audible sound yet)
  988.         - Orderlist advance if necessary
  989.         - Pulsetable execution only if no orderlist advance
  990.         - Wavetable execution
  991.         - "One-shot" commands 5XY-FXY
  992.  
  993. 1       - New notes become audible
  994.         - Pulsetable execution
  995.         - Wavetable or realtime pattern commands 1XY-4XY
  996.  
  997. 2,3     - Pulsetable execution
  998.         - Wavetable or realtime pattern commands 1XY-4XY
  999.  
  1000. 4       - New notes fetched from the pattern
  1001.         - Gateoff and hard restart for new notes
  1002.           (2 ticks before first frame, as gateoff timer indicates)
  1003.         - No pulsetable execution
  1004.         - Wavetable or realtime pattern commands 1XY-4XY
  1005.  
  1006. 5       - Pulsetable execution
  1007.         - Wavetable or realtime pattern commands 1XY-4XY
  1008.  
  1009. Filtertable is executed on each tick regardless of what the channels are doing.
  1010. Wavetable is never skipped, so arpeggios/drumsounds should always play OK.
  1011.  
  1012. With the commandline parameter /O0 (or by clicking the "PO" text on the status
  1013. bar) you can disable pulse skipping. This leads to increased rastertime use but
  1014. can be good for example with tempo 3 tunes.
  1015.  
  1016. Likewise, with the commandline parameter /R0 (or by clicking the "RO" text on
  1017. the status bar) you can disable realtime pattern command skipping on tick 0.
  1018.  
  1019. 3.6 Miscellaneous tips
  1020. ----------------------
  1021.  
  1022. - Patterns will take less memory the less there are command changes. When the
  1023.   song is packed/relocated, for example a long vibrato or portamento command
  1024.   needs to be stored only once as long as the parameter stays the same on
  1025.   subsequent pattern rows.
  1026.  
  1027. - Using instrument vibrato can make 4XY commands unnecessary and save even
  1028.   more memory. Use realtime calculated note-independent speed (see speedtable
  1029.   section) if you want the vibrato to have the same magnitude regardless of 
  1030.   the note.
  1031.  
  1032. - In the instrument parameters, there is no option to stop pulse execution
  1033.   directly. So if you have for example a sawtooth instrument, there might be
  1034.   an "unnecessary" pulsemodulation going on underneath and wasting rastertime.
  1035.   There are two ways you can stop this:
  1036.   1) Make a short pulseprogram like this and use it in the instrument:
  1037.      01: 80 00 Set pulse $000
  1038.      02: FF 00 Stop pulse execution
  1039.   2) Use pattern command 900 to stop pulse execution
  1040.  
  1041. - If you have a realtime command (vibrato/portamento), you can put "one-shot"
  1042.   commands 5XY-FXY inbetween and the realtime command will be unaffected. An
  1043.   example:
  1044.  
  1045.   C-4 01000
  1046.   --- 00401 Begin vibrato with speedtable index $01
  1047.   --- 00401
  1048.   --- 00401
  1049.   --- 0065A Set sustain/release to $5A. Vibrato executes also on this step!
  1050.   --- 00401 Continue vibrato normally
  1051.   --- 00401
  1052.  
  1053.   However, the vibrato would stop immediately if command 0 was encountered.
  1054.  
  1055. - Normally tempo 3 is the fastest you can use. However, by using the funktempo
  1056.   command you can get tempo 2. To do this, create a following speedtable entry:
  1057.   02 02, and point your funktempo command to it. You also need to use gateoff
  1058.   timer 1 in all instruments and disable the pulse-optimization skipping.
  1059.  
  1060. - For very optimized songdata & player you can refrain from using any pattern
  1061.   commands and rely on the instruments' step-programming. Even in this case, you
  1062.   can set song startup default tempo with the Attack/Decay parameter of the last
  1063.   instrument (63), if you otherwise leave this instrument unused.
  1064.  
  1065. 3.6.1 Limit-based modulation steps
  1066. ----------------------------------
  1067.  
  1068. You can enter pulse/filter modulation steps in limit-based format, and convert
  1069. them to time-based with SHIFT+L. For example, you could enter the following in
  1070. the pulsetable:
  1071.  
  1072.   01: 84 00 Set initial pulse to $400
  1073.   02: C0 10 Modulate pulse to $C00 with speed $0010
  1074.   03: 40 10 Modulate pulse back to $400 with speed $0010
  1075.  
  1076. Now position the cursor on step 02 and press SHIFT+L twice, to convert both of
  1077. the modulation steps to usual time-based steps. If necessary, the steps will
  1078. be expanded to several (if the resulting time parameter is over $7F.)
  1079.  
  1080. Remember that the player only understands time-based steps and you always have
  1081. to convert limit-based steps before they play correctly!
  1082.  
  1083. 3.6.2 Precalculated note-independent "hifi player" portamento/vibrato
  1084. ---------------------------------------------------------------------
  1085.  
  1086. From v2.62 onwards, GoatTracker actually supports realtime calculated note 
  1087. independent portamento and vibrato speeds, see speedtable section for this. 
  1088. However, this makes the player bigger and much slower. You can still also use 
  1089. the old method of manually precalculating needed note-independent speeds with 
  1090. the SHIFT+H function, which this section is about.
  1091.  
  1092. The idea is to take the frequency difference between 2 adjacent notes in
  1093. the frequency table and manipulate it by bit shifting left (multiply) or
  1094. right (divide).
  1095.  
  1096. To use, you need a portamento or vibrato command in the pattern, and the note
  1097. you wish to base the calculation on on the current pattern step or before it
  1098. (before it only for toneportamento) The amount of shift is determined by the
  1099. command parameter. A number in the left nybble means shift left and right
  1100. nybble right shift. When you press Shift+H while the cursor is on the command,
  1101. a speedtable entry is created, and the parameter is replaced with a speedtable
  1102. index.
  1103.  
  1104. Some examples:
  1105.  
  1106.   C-3 00110 Take the frequency difference between C-3 & C#3 and shift it left
  1107.             1 times (multiply by 2.)
  1108.  
  1109.   E-4 00000
  1110.   ... 00000
  1111.   G-4 00302 Take the frequency difference between E-4 & F-4 and shift it right
  1112.             2 times (divide by 4.)
  1113.  
  1114. 3.7 Multispeed tips
  1115. -------------------
  1116.  
  1117. - When making multispeed songs, remember to multiply your tempos and also the
  1118.   gateoff timer values! For example, gateoff timer is normally 2, but in a 2X-
  1119.   speed tune the same gateoff length would be achieved with value 4.
  1120.  
  1121. - If you want to keep vibrato the same compared to 1X-speed, you must multiply
  1122.   vibrato speed by the speed multiplier, and divide vibrato depth by the
  1123.   multiplier. Remember also to divide portamento and pulse/filter modulation
  1124.   speeds as necessary.
  1125.  
  1126. - When importing a v1.xx multispeed song, you also need to multiply the
  1127.   gateoff timers.
  1128.  
  1129. - In the instruments, using Attack 0 might result in a very silent first row of
  1130.   the wavetable. You could try increasing the attack, or adding one or more
  1131.   rows of E9 00 (testbit+gate) to the beginning of the wavetable.
  1132.  
  1133.  
  1134. 4. Using the included utilities
  1135. -------------------------------
  1136.  
  1137. 4.1 INS2SND2.EXE
  1138. ---------------
  1139.  
  1140. INS2SND2.EXE converts GoatTracker v1.xx or v2 instruments (.INS-files) into
  1141. sound effects, outputting the data as source code or binary.
  1142.  
  1143. Usage: INS2SND <instrumentfile> <sourcecodefile> <options>
  1144. Options:
  1145. -b output in binary
  1146. -c output in CovertScript format (deprecated)
  1147.  
  1148. Default output is C64 assembler (DASM) style source code
  1149.  
  1150. Look at section 6.3 or run the program without parameters to see the
  1151. limitations of the sound effect system.
  1152.  
  1153. 4.2 SNGSPLI2.EXE
  1154. ----------------
  1155.  
  1156. SNGSPLI2.EXE splits the patterns of a GoatTracker v2 song into smaller pieces
  1157. for memory use optimization. It is comfortable to compose with large patterns
  1158. but usually more efficient memory-wise to use small patterns. Remember! Always
  1159. keep the original song because a pattern-splitted song is much harder to edit
  1160. further.
  1161.  
  1162. Usage: SNGSPLI2 <source> <destination> [target len]
  1163.  
  1164. For example, if a pattern is 64 rows long and the target length is 16, it will
  1165. be split into 4 pieces. A pattern that falls below 2 x target length, will not
  1166. be split at all.
  1167.  
  1168. 4.3 MOD2SNG.EXE
  1169. ---------------
  1170.  
  1171. Dedicated exclusively to T.M.R, this program converts the pattern & orderlist
  1172. data of 4-channel, 31-instrument MOD-files into GoatTracker .SNG files. You
  1173. must choose one channel to leave out, and obviously instruments are not
  1174. converted, except for their names. You can also specify a transpose in
  1175. halfsteps.
  1176.  
  1177. Usage: MOD2SNG <mod> <sng> [channel] [transpose]
  1178.        [channel] is the channel to leave out (1-4), default 4
  1179.        [transpose] is the halfstep transpose added to notes, default 0
  1180.  
  1181. 4.4 BETACONV.EXE
  1182. ----------------
  1183.  
  1184. Converts GT v2 beta songs to new format used by GT v2 RC1 onwards. Old format
  1185. had 47 instruments max. and new has 63 max. Additionally, depending on what
  1186. beta version you used, you can choose to halve vibrato depths and pulse speeds
  1187. to make them play correct in the current version. Warning: the conversion is
  1188. irreversible, so have backups if you overwrite the old versions.
  1189.  
  1190. Usage: BETACONV <source> <destination> [vibdepth] [pulse]
  1191.        [vibdepth] decides whether to halve vibdepth (1=yes 0=no), default 0
  1192.        [pulse] decides whether to halve pulse speed (1=yes 0=no), default 0
  1193.  
  1194.  
  1195. 5. Using the songs outside the editor
  1196. -------------------------------------
  1197.  
  1198. Press F9 in the editor to enter the packer/relocator. Choose playroutine
  1199. options, startaddress, zeropage address (need 2 consecutive locations) and file
  1200. format (PRG/BIN/SID), then type the filename.
  1201.  
  1202. If you use patterns longer than 64 rows, there is the possibility that
  1203. relocation fails because of too complex patterns. Each pattern row can be 0-4
  1204. bytes packed, and the total amount of bytes per one pattern may not exceed 256.
  1205.  
  1206. If wave/pulse/filtertables overflow past row 255 without a jump command or there
  1207. are other serious errors, you get a warning screen and have to fix the error.
  1208.  
  1209. The relocator optimizes & removes when saving:
  1210. - Unused patterns
  1211. - Unused instruments
  1212. - Unused table-entries
  1213. - Selfcontained (ie. no jumps to/from outside) duplicate parts of tables
  1214. - Player code not needed in the playback of the song
  1215.  
  1216. Look at /examples/example1.prg - example4.prg to get an idea how much these
  1217. playroutines take rastertime. No promises!
  1218.  
  1219. The basic functions independent of playroutine options are:
  1220.  
  1221. Init music:
  1222.  
  1223.         LDA #subtunenumber       ;Starting from 0
  1224.         JSR startaddress
  1225.  
  1226. Play one frame of music:
  1227.  
  1228.         JSR startaddress+3
  1229.  
  1230. 5.1 Playroutine options
  1231. -----------------------
  1232.  
  1233. BUFFERED SID-WRITES - Instead of writing each SID value as soon as possible,
  1234. waits for the end of the channel's execution on each frame and then writes the
  1235. registers in one go. Improves sound stability but takes more memory & raster-
  1236. time.
  1237.  
  1238. SOUND EFFECT SUPPORT - Adds a sound effect engine for use in games. Implies
  1239. buffered writes. To use, call in the following way:
  1240.  
  1241.         LDA #<effect        ;Start address of sound effect data
  1242.         LDY #>effect
  1243.         LDX #channel        ;0, 7 or 14 for channels 1-3
  1244.         JSR startaddress+6
  1245.  
  1246. The sound effects have a hardcoded priority system based on their start
  1247. addresses. A sound higher up in memory (bigger address) will never be
  1248. interrupted with a sound lower in memory.
  1249.  
  1250. VOLUME CHANGE SUPPORT - Adds a routine in the player's jumptable to change the
  1251. master volume level. To use, call in the following way:
  1252.  
  1253.         LDA #volume        ;0-15
  1254.         JSR startaddress+6 ;(startaddress+9 with sound effect support)
  1255.  
  1256. Note that the master volume command (DXY) also modifies this same location,
  1257. so it will clash if you also change the volume manually.
  1258.  
  1259. STORE AUTHOR-INFO - Writes the "AUTHOR" string from songname editor to the
  1260. location range (startaddress+$20 - startaddress+$3F). Also enables timing mark
  1261. support. A timing mark is a mastervolume command (DXY) with parameter $10-$FF.
  1262. This parameter will be copied into startaddress+$3F when the command is
  1263. encountered in playback.
  1264.  
  1265. USE ZEROPAGE GHOSTREGS - Instead of writing to the SID, a memory range in the
  1266. zeropage is used for holding the SID register data. This can then be copied
  1267. in the main program to the SID, for example to enable the playroutine & music
  1268. data to reside under the I/O area. Implies buffered writes. A reverse copy loop
  1269. should be used after each call to the playroutine:
  1270.  
  1271.         LDX #$18
  1272. copy:   LDA ghostregs,x
  1273.         STA $D400,x
  1274.         DEX
  1275.         BPL copy
  1276.  
  1277. The copy loop can also be unrolled for more speed.
  1278.  
  1279. Note that when you use the alternative hardrestart method & playroutine (hard-
  1280. restart attack parameter F) the copy loop should not be in reverse order but
  1281. should be for each channel: wave, frequency, pulsewidth, and ADSR last.
  1282.  
  1283. If you are using both sound effect support and ghostregisters, there exists
  1284. a possibility of sound errors in the case that a sound effect has finished,
  1285. and the same channel starts a new pulse-waveform note without setting an
  1286. initial pulsewidth value (for example, like in the beginning of Sanxion loader
  1287. tune). This is because the ghostregisters are shared between music & sound
  1288. effect playback, and the sound effect has already overwritten the previous
  1289. pulse width.
  1290.  
  1291. DISABLE OPTIMIZATIONS - The relocator removes saved playroutine code based on
  1292. what effects & commands the song uses, resulting in a smaller playroutine
  1293. accordingly. If you encounter anomalies in the sound (such as ADSR bugs caused
  1294. by unpredictable timing variation) you can try disabling the optimizations.
  1295. Normally this is not necessary, but is included just in case.
  1296.  
  1297.  
  1298. 6. File/data formats description
  1299. --------------------------------
  1300.  
  1301. The sections in the files appear in the sequential order in which they are
  1302. described.
  1303.  
  1304. 6.1 GoatTracker v2 song (.SNG) format
  1305. -------------------------------------
  1306.  
  1307. 6.1.1 Song header
  1308. -----------------
  1309.  
  1310. Offset  Size    Description
  1311. +0      4       Identification string GTS5
  1312. +4      32      Song name, padded with zeros
  1313. +36     32      Author name, padded with zeros
  1314. +68     32      Copyright string, padded with zeros
  1315. +100    byte    Number of subtunes
  1316.  
  1317. 6.1.2 Song orderlists
  1318. ---------------------
  1319.  
  1320. The orderlist structure repeats first for channels 1,2,3 of first subtune,
  1321. then for channels 1,2,3 of second subtune etc., until all subtunes
  1322. have been gone thru.
  1323.  
  1324. Offset  Size    Description
  1325. +0      byte    Length of this channel's orderlist n, not counting restart pos.
  1326. +1      n+1     The orderlist data:
  1327.                 Values $00-$CF are pattern numbers
  1328.                 Values $D0-$DF are repeat commands
  1329.                 Values $E0-$FE are transpose commands
  1330.                 Value $FF is the RST endmark, followed by a byte that indicates
  1331.                 the restart position
  1332.  
  1333. 6.1.3 Instruments
  1334. -----------------
  1335.  
  1336. Offset  Size    Description
  1337. +0      byte    Amount of instruments n
  1338.  
  1339. Then, this structure repeats n times for each instrument. Instrument 0 (the
  1340. empty instrument) is not stored.
  1341.  
  1342. Offset  Size    Description
  1343. +0      byte    Attack/Decay
  1344. +1      byte    Sustain/Release
  1345. +2      byte    Wavepointer
  1346. +3      byte    Pulsepointer
  1347. +4      byte    Filterpointer
  1348. +5      byte    Vibrato param. (speedtable pointer)
  1349. +6      byte    Vibraro delay
  1350. +7      byte    Gateoff timer
  1351. +8      byte    Hard restart/1st frame waveform
  1352. +9      16      Instrument name
  1353.  
  1354. 6.1.4 Tables
  1355. ------------
  1356.  
  1357. This structure repeats for each of the 4 tables (wavetable, pulsetable,
  1358. filtertable, speedtable).
  1359.  
  1360. Offset  Size    Description
  1361. +0      byte    Amount n of rows in the table
  1362. +1      n       Left side of the table
  1363. +1+n    n       Right side of the table
  1364.  
  1365. 6.1.5 Patterns header
  1366. ---------------------
  1367.  
  1368. Offset  Size    Description
  1369. +0      byte    Number of patterns n
  1370.  
  1371. 6.1.6 Patterns
  1372. --------------
  1373.  
  1374. Repeat n times, starting from pattern number 0.
  1375.  
  1376. Offset  Size    Description
  1377. +0      byte    Length of pattern in rows m
  1378. +1      m*4     Groups of 4 bytes for each row of the pattern:
  1379.                 1st byte: Notenumber
  1380.                           Values $60-$BC are the notes C-0 - G#7
  1381.                           Value $BD is rest
  1382.                           Value $BE is keyoff
  1383.                           Value $BF is keyon
  1384.                           Value $FF is pattern end
  1385.                 2nd byte: Instrument number ($00-$3F)
  1386.                 3rd byte: Command ($00-$0F)
  1387.                 4th byte: Command databyte
  1388.  
  1389. 6.2 GoatTracker v2 instrument (.INS) format
  1390. -------------------------------------------
  1391.  
  1392. Offset  Size    Description
  1393. +0      4       Identification string GTI5
  1394. +4      byte    Attack/Decay
  1395. +5      byte    Sustain/Release
  1396. +6      byte    Wavepointer
  1397. +7      byte    Pulsepointer
  1398. +8      byte    Filterpointer
  1399. +9      byte    Vibrato param. (speedtable pointer)
  1400. +10     byte    Vibrato delay
  1401. +11     byte    Gateoff timer
  1402. +12     byte    Hard restart/1st frame waveform
  1403. +13     16      Instrument name
  1404.  
  1405. After the instrument data, this structure repeats for each of the 4 tables
  1406. (wavetable, pulsetable, filtertable, speedtable).
  1407.  
  1408. Offset  Size    Description
  1409. +0      byte    Amount n of rows in the table
  1410. +1      n       Left side of the table
  1411. +1+n    n       Right side of the table
  1412.  
  1413. Note that the tables are a partial snapshot of the current song the instrument
  1414. was saved from, so upon loading they have to be relocated to the current free
  1415. table locations.
  1416.  
  1417. 6.3 Sound effect data format
  1418. ----------------------------
  1419.  
  1420. Offset  Size    Description
  1421. +0      byte    Attack/Decay
  1422. +1      byte    Sustain/Release
  1423. +2      byte    Pulse width. This value has nybbles reversed from what it looks
  1424.                 like in the editor so a middle pulse $800 will be stored as $08,
  1425.                 and the sound effect routine will put this value to both $D402
  1426.                 and $D403 registers.
  1427. +3      ?       Wavetable. Contains note/waveform pairs (different order than
  1428.                 in instrument wavetable), from which the waveform can be
  1429.                 omitted if unchanged, as the value ranges do not overlap:
  1430.                         Value $00 ends the sound effect
  1431.                         Values $01-$81 are waveforms
  1432.                         Values $82-$DF are absolute notes D-0 - B-7
  1433.                 Note that a note cannot be omitted to store only waveform
  1434.                 changes!
  1435.  
  1436. As you can see, the sound effect format is very simplistic. When converting an
  1437. instrument to a sound effect with INS2SND2, following things cause an error
  1438. message:
  1439.  
  1440. - If the resulting sound effect is more than 128 bytes
  1441. - If the instrument's wavetable contains relative notes, absolute notes C-0 or
  1442.   C#0, or waveforms > 129 ($81)
  1443.  
  1444. The instrument's pulsewidth modulation & filter settings will be completely
  1445. discarded.
  1446.  
  1447.  
  1448. 7. Recompiling
  1449. --------------
  1450.  
  1451. To recompile for Win32, you need the MinGW development enviroment, use the
  1452. file src/makefile.win as makefile.
  1453.  
  1454. To recompile for Linux, use src/makefile.
  1455.  
  1456. In both cases you need the SDL development libraries in addition to the SDL
  1457. runtime, see http://www.libsdl.org.
  1458.  
  1459. Compile first the utilities (datafile & dat2inc) from the src/bme directory,
  1460. and place them to your path.
  1461.  
  1462.  
  1463. 8. Version history
  1464. ------------------
  1465.  
  1466. v2.0Beta  - Original public release
  1467.  
  1468. v2.0      - Fixed crash in DMC-note entry mode.
  1469.           - Fixed v1.xx import pulse conversion, a case where pulse startpos
  1470.             was lower than the pulse low limit was not converted right.
  1471.           - Fixed instrument gatetimer becoming zero (can lead to tempo bugs)
  1472.             when cutting an instrument (SHIFT+X)
  1473.           - Fixed order of SID writes to make editor & C64 playroutine behave
  1474.             as similarly as possible.
  1475.           - Fixed removal of table-entries (when loading an instrument) in
  1476.             case another instrument uses them too.
  1477.           - Fixed toneportamento (3XY) with wavetable delays.
  1478.           - Fixed funktempo in packed/relocated songs.
  1479.           - Fixed behaviour of + & - keys while editing instrument name.
  1480.           - Fixed pattern editor transpose functions.
  1481.           - Added SHIFT+DEL to delete an instrument + its tabledata.
  1482.           - Added SHIFT+INS to insert rows on table first row without having to
  1483.             adjust tablepointers afterwards.
  1484.           - Added SHIFT+W,S for octave transpose.
  1485.           - Added SHIFT+1,2,3 to swap orderlists between channels.
  1486.           - Added SHIFT+BACKSPACE to clear a whole pattern row.
  1487.           - Added optimized playroutines, that will be used if all instruments
  1488.             have the same gateoff timer & 1st wave parameters.
  1489.           - Added duplicate check for v1.xx pulse conversion.
  1490.           - Added BETACONV-utility for conversion from beta format.
  1491.           - Added reSID interpolation option /I.
  1492.           - Added hexadecimal pattern row display option /D.
  1493.           - Added SID memory location parameter /L.
  1494.           - reSID interpolation is on by default.
  1495.           - Changed appearance of pattern special notes (rest, keyoff/on)
  1496.           - Increased amount of instruments to 63 and changed song dataformat.
  1497.           - v1.xx import converts arpeggios to instruments as long as there is
  1498.             room.
  1499.           - Vibrato depth changed back to same as in v1.xx.
  1500.           - Pulse modulation speeds are doubled.
  1501.           - Upon startup, songdata erase, or importing v1.xx data, gatetimer
  1502.             will be set to 2 * multiplier as opposed to just 2.
  1503.           - Optimized size & speed of all playroutines (initialization,
  1504.             checking for new note fetch, pulsetable execution).
  1505.           - Wavetable delay or no-wavechange on first step of instrument is
  1506.             definitely unsupported now! Protection to allow this conflicted
  1507.             with 3XY command.
  1508.  
  1509. v2.01     - Added under-IO gamemusic playroutine.
  1510.  
  1511. v2.02     - Added RETURN when instrument tableparameter (wave/pulse/filter) is
  1512.             0 to get you to the first free table location. SHIFT+RETURN will
  1513.             additionally also set the instrument tableparameter.
  1514.           - Added "set mastervolume"-jump to gamemusic routines.
  1515.           - Improved sound effect handling, when an effect is interrupted by
  1516.             another (less silence between sounds).
  1517.  
  1518. v2.03     - Added execution of realtime commands & instrument vibrato during
  1519.             wavetable delay.
  1520.           - Added wavetable right side value $80 to keep frequency unchanged
  1521.             (as a consequence, the note C-0 will cause the same effect).
  1522.           - Added relocator optimizations: all unnecessary data is stripped
  1523.             when packing/relocating.
  1524.           - Playroutines size-optimized.
  1525.           - Explanation of how different gatetimer values can lead to playback
  1526.             going out of sync (section 3.3).
  1527.           - reSID interpolation is no longer on by default :)
  1528.  
  1529. v2.04     - Added a questionable 25Hz mode (/S0)
  1530.           - Execution of commands on wavetable delay is completely reworked
  1531.             and more consistent now.
  1532.           - Note C-0 is usable again.
  1533.  
  1534. v2.05     - Added instrument legato feature (Hardres/1stwave parameter $00).
  1535.           - ADSR writes moved farther away from wave writes in the standard
  1536.             playroutine noteinit, lessening possibility of ADSR bugs.
  1537.           - Song initialization and pulsetable execution speed/sizeoptimized.
  1538.  
  1539. v2.06     - Packer/relocator tolerates up to 256 bytes long patterns now.
  1540.           - Optimized playroutine sizes.
  1541.  
  1542. v2.07     - Fixed transpose reset with F2/F3 song start (should not happen).
  1543.           - Fixed varying tempo on channels with F2/F3 song start.
  1544.           - Added warning screen to packer/relocator if table execution
  1545.             overflows.
  1546.           - Added writing of PAL/NTSC and 6581/8580 flags according to PSID V2
  1547.             NG specification.
  1548.           - -mwindows added to linker options for no displaying of DOS prompt
  1549.             window (in win32 version).
  1550.  
  1551. v2.08     - Added finevibrato mode (/V command line option).
  1552.           - Optimized playroutine sizes & speed.
  1553.  
  1554. v2.09     - Fixed max.pattern length in Clear Musicdata operation.
  1555.           - Added Minimal playroutine.
  1556.           - First wave value $80 also acts as a proper legato instrument now.
  1557.           - Optimized playroutine sizes & speed.
  1558.           - SID chip type & timing (PAL/NTSC) displayed on top row.
  1559.  
  1560. v2.1      - Added SHIFT+N for negating pulse/filter modulation speeds.
  1561.           - Added no-funktempo & no-octave0 optimizations to playroutines (a
  1562.             total of 8 sub-types for each playroutine).
  1563.           - Maximum speed is 16X now.
  1564.           - Separate song/instrument/packed song directories are remembered
  1565.             during session.
  1566.           - Pathname is displayed in the fileselector.
  1567.           - Filters ** and *.* display all files in the fileselector.
  1568.           - Song entered on commandline will be loaded at startup.
  1569.           - Song filename currently being edited is shown in the titlebar.
  1570.           - Currently edited song filename will be used as default in the
  1571.             "SAVE SONG" and "SAVE MUSIC+PLAYROUTINE" dialogs.
  1572.           - Instrument name will also be used as instrument filename as default
  1573.             in the "SAVE INSTRUMENT" dialog.
  1574.           - UPX used for compression of win32 executables.
  1575.           - Included a short reference of waveform bits (manual only).
  1576.           - Configuration file has clearer structure.
  1577.  
  1578. v2.11     - Added SHIFT+S for smart instrument paste (converts instrument
  1579.             numbers in all patterns, after cut/pasting an instrument).
  1580.           - Added SHIFT+L which allows to write <limit,speed> pulse/filter
  1581.             modulation steps and then convert them to the proper <time,speed>
  1582.             format.
  1583.  
  1584. v2.12     - Playroutine 1 has buffered SID-writes.
  1585.           - Octave 0 is not disabled in routines with sound FX (no matter what
  1586.             the relocator says...)
  1587.  
  1588. v2.13     - Standard playroutine now both in unbuffered and buffered flavors.
  1589.  
  1590. v2.15     - Added SHIFT+I for inverting current pattern selection / whole
  1591.             pattern.
  1592.  
  1593. v2.16     - Fixed octave selection with / * for laptop keyboards.
  1594.           - Empty patterns referenced in the orderlist will be saved when
  1595.             saving a song.
  1596.           - Save dialog will reappear if writing the song/instrument/executable
  1597.             music failed.
  1598.           - Optimized handling of "packed rests" in the playroutines.
  1599.           - Added < > for instrument selection in instrument/table edit modes.
  1600.  
  1601. v2.17     - Fixed initialization of instrument vibrato.
  1602.           - Playroutines size-optimized.
  1603.  
  1604. v2.18     - Wavetable left side values changed. Delay is now $01-$0F and
  1605.             inaudible waveforms (register values $00-$0F) have been mapped to
  1606.             table values $E0-$EF. Old songs using values $08-$0F have to be
  1607.             manually converted!
  1608.  
  1609. v2.2      - Added the speedtable for more precise control of vibrato,
  1610.             portamento and funktempo.
  1611.           - Added SHIFT+O to optimize the speedtable (remove unused entries).
  1612.           - Added SHIFT+R to convert between absolute/relative notes in
  1613.             the wavetable.
  1614.           - Added SHIFT+RETURN in pattern/instrument editor to convert old
  1615.             style portamento, vibrato and funktempo parameters to speedtable
  1616.             entries.
  1617.           - SHIFT+R will paste several effect rows if there is data in pattern
  1618.             copybuffer.
  1619.           - Editing during Follow Play is possible.
  1620.           - Song and instrument format modified for 4 tables. Old 3-table
  1621.             data will be loaded but not saved anymore.
  1622.  
  1623. v2.21     - Fixed NTSC CIA timer value for SID files.
  1624.           - Shift+E will copy several effect rows if pattern has been marked.
  1625.  
  1626. v2.22     - Shift+N will also negate relative wavetable notes.
  1627.           - When converting oldstyle parameters to speedtable entries with
  1628.             SHIFT+RETURN, the speedtable view will shift to the new entry if
  1629.             one was created.
  1630.  
  1631. v2.23     - Fixed SHIFT+INS in wavetable (inserts $E9 $00 now as it should).
  1632.           - Added SHIFT+U to unlock table scrolling.
  1633.           - Added SHIFT+F5/F6 to change speed multiplier.
  1634.  
  1635. v2.24     - Added SHIFT+F7 to edit the hardrestart ADSR parameter.
  1636.           - Added SHIFT+F8 to switch between 6581 and 8580 SID models.
  1637.  
  1638. v2.25     - Added detail to table overflow error message in relocator.
  1639.           - Added stop of playback if a tablepointer gets pointed directly to a
  1640.             jump (would bug in packed/relocated tune).
  1641.           - Added relocator error message for the above case.
  1642.           - Added relocator error message for illegal song restart position.
  1643.           - Not possible to save erroneous packed/relocated songs anymore
  1644.             (now that there is adequate error location).
  1645.           - Added SHIFT+,. to move song startposition on all channels and
  1646.             restart last playmode.
  1647.  
  1648. v2.26     - Fixed relocator complaining of FF parameter in speedtable.
  1649.           - To increase stability, in multispeed mode relocator does not use the
  1650.             "same gatetimer/1st wave" optimization.
  1651.           - Changed Shift+O to optimize the currently edited table, not just
  1652.             speedtable.
  1653.           - Added an option to optimize everything with the SHIFT+ESC clear
  1654.             function. This clears unused patterns, instruments and table-entries.
  1655.  
  1656. v2.27     - Fixed optimize function with different pattern lengths.
  1657.           - Added marking & copy/pasting orderlist data like patterns & tables.
  1658.  
  1659. v2.28     - Added sort of mouse control.
  1660.           - Sound reinitialization when changing multiplier or other parameters
  1661.             is now faster.
  1662.  
  1663. v2.29Beta - Internal reorganization.
  1664.           - New assembler-based relocator that leaves out unused portions of
  1665.             player code.
  1666.           - Instead of choosing a player version, one can choose combinations
  1667.             of player features.
  1668.           - Relocator does not save selfcontained duplicate parts of tables.
  1669.           - Added keys 0-9 & A-Z in the fileselector to move to the
  1670.             corresponding part of the filelist (if found).
  1671.           - Added SHIFT+H to calculate left/right shifted "hifi" speedtable
  1672.             values, according to the frequency of a note.
  1673.  
  1674. v2.3      - Fixed songdata optimize function.
  1675.           - Fixed relocator with no-hardrestart instrument in slot 1.
  1676.           - Fixed relocator handling of effect C (Set cutoff).
  1677.  
  1678. v2.31     - Fixed effect copy/paste.
  1679.           - Added possibility to disable pulseskipping with /O command line
  1680.             option. Warning: causes huge rastertime increase.
  1681.           - Tempo 2 is allowed. See the tips section (3.6) for details.
  1682.  
  1683. v2.32     - Maximum pattern length increased to 128. Do not complain of
  1684.             "pattern too complex" errors :)
  1685.           - Optimized playroutine init in case of only 1 subtune.
  1686.  
  1687. v2.33     - Fixed a bug where relocator was checking pattern 208 (illegal).
  1688.           - Optimized playroutine in case there is no keyoff/keyon used.
  1689.           - Optimized playroutine in case there are no pattern effects used.
  1690.           - Optimized playroutine channel variables in case there is no
  1691.             transpose, repeat, wavedelay and pattern effects.
  1692.           - If not using the last instrument (63), you can control song
  1693.             startup default tempo by using its Attack/Decay parameter.
  1694.  
  1695. v2.34     - Added relocator optimization for using 1 or 2 channels only. To
  1696.             enable, you must use only channels 1 or 1,2 and not be using sound
  1697.             effect support or zeropage ghostregs.
  1698.           - Turning off buffered writes in relocator options works now even
  1699.             if sound effects or zeropage ghostregs are selected (they will be
  1700.             turned off too).
  1701.  
  1702. v2.35     - Auto-creation of speedtable entries will always generate a new
  1703.             entry (except for song loading), duplicate values will be optimized
  1704.             by the relocator.
  1705.           - Pressing SHIFT+RETURN over a speedtable-using pattern command while
  1706.             the parameter is zero, goes to the next empty speedtable entry and
  1707.             sets the command parameter to point to that entry.
  1708.  
  1709. v2.4      - Added one bit of accuracy to pulse modulation speed. A new song-
  1710.             format (identifier GTS4) reflects this, old songs will be converted
  1711.             upon loading.
  1712.           - Added possibility to execute pattern commands from the wavetable.
  1713.  
  1714. v2.41     - Fixed player code assembly errors when using some pattern commands
  1715.             only from the wavetable.
  1716.           - Fixed player code bug with command B when command A is not used.
  1717.           - Fixed SHIFT+O removing table entries pointed to from wavetable
  1718.             pattern commands.
  1719.  
  1720. v2.42     - Fixed frequency table size determination.
  1721.           - Changed behaviour of keyoff in pattern editing changed to use
  1722.             releasenote() like the instrument editor.
  1723.           - Added SHIFT+RETURN when parameter is zero to get you into an empty
  1724.             table entry for 8, 9 and A pattern commands as well.
  1725.           - Added adjustment of table views when changing instrument number
  1726.             in unlocked table scrolling mode.
  1727.           - Added RETURN over nonzero instrument number (in patterns) to go
  1728.             editing that instrument.
  1729.  
  1730. v2.43     - Added duplicate pattern detection/removal to song optimize.
  1731.           - Added pattern shrink/expand (SHIFT+O,P).
  1732.           - Added pattern join/split (SHIFT+J,K).
  1733.  
  1734. v2.44     - Fixed editor playroutine to not execute tick n commands, when a
  1735.             command has already been executed through the wavetable.
  1736.  
  1737. v2.45     - Added possibility to disable realtime pattern command optimization
  1738.             at tick 0 (/Rxx command line option or click the "RO" text on the
  1739.             statusbar) for tempo-independent portamento & vibrato.
  1740.           - To make room on the status bar for the realtime optimization
  1741.             status indicator, finevibrato & pulse optimization indicators have
  1742.             been shortened to "FV" and "PO".
  1743.  
  1744. v2.46     - Added transpose of speedtable portamento speeds (SHIFT+Q,A,W,S)
  1745.             SHIFT+W,S (octave transpose, multiply/divide by 2) also work in
  1746.             pulse & filtertable.
  1747.           - When editing the wavetable, RETURN & SHIFT+RETURN work for wave-
  1748.             table executed commands as in patterns (go to table position
  1749.             pointed by command, create new speedtable entries)
  1750.  
  1751. v2.47     - Added experimental random delay to write of reSID registers, in
  1752.             order to make potential ADSR-bugging on C64 audible. The
  1753.             amount of delay in cycles can be adjusted with /Z command line
  1754.             option.
  1755.           - SHIFT+L in pulsetable creates repeated "set tempo" commands if
  1756.             speed is greater than 127.
  1757.  
  1758. v2.48     - Fixed playroutine to use configurable baseaddress again.
  1759.  
  1760. v2.49     - Added /G command line option, guard 1stwave/gatetimer parameters.
  1761.             When this is on (default), only silent waveforms can be entered
  1762.             as firstwave (only thing that makes sense) and editing gatetimer
  1763.             of one instrument affects all of them, as otherwise bugs in
  1764.             playback result easily. Use /G0 to turn off.
  1765.  
  1766. v2.5      - Fixed "optimize everything" removing the tempo setting in
  1767.             instrument 63.
  1768.           - Fixed default tempo of multispeed tunes in packer/relocator.
  1769.  
  1770. v2.51     - Fixed packing of empty patterns when not using any effects.
  1771.           - Fixed differing gatetimer value in instruments causing playback
  1772.             going out of sync.
  1773.           - /G command line option no longer has to keep gatetimer values the
  1774.             same.
  1775.           - Added high bit of gatetimer value to control whether wavetable
  1776.             execution starts right on the note init frame. If used, will cause
  1777.             significant rastertime increase.
  1778.  
  1779. v2.52     - SHIFT+ENTER in orderlist view takes the next available pattern
  1780.             if pressed on a repeat or transpose command.
  1781.           - Added SHIFT+SPACE in pattern editor to start playback on a specific
  1782.             pattern row.
  1783.  
  1784. v2.53     - Fixed F3 to always play the currently visible patterns.
  1785.           - Added BACKSPACE in the orderlist editor to set playback end position.
  1786.             Only effective when starting playback from position, not beginning.
  1787.  
  1788. v2.54     - Fixed SHIFT+F3.
  1789.           - Changed SHIFT+, . to update the pattern view.
  1790.           - Changed SHIFT+SPACE to remain in pattern playback mode, if it was
  1791.             active.
  1792.  
  1793. v2.55     - Added BACKSPACE in the fileselector to go to the parent dir.
  1794.  
  1795. v2.56     - Song filename cleared on songdata erase.
  1796.           - Added /F to set custom SID clock frequency.
  1797.           - Graphics output routines no longer compare text screen buffer to 
  1798.             previous to find out if it should be updated.
  1799.             
  1800. v2.57     - Added alternative hardrestart method & playroutine that is used when
  1801.             HR attack parameter is at maximum (FF00 or F800 for example) - this 
  1802.             can in theory give better reliability.
  1803.             
  1804. v2.58     - Cleanup, removal of a few questionable features:
  1805.             * Gatetimer high bit to start wavetable immediately
  1806.             * Guard 1stwave parameter
  1807.             
  1808. v2.59     - Songformat version update (GTS5/GTI5)
  1809.           - Gateoff timer parameter bits control now hardrestart disable ($80)
  1810.             & gateoff disable ($40).
  1811.           - 1stFrame Wave can be any from $01-$8F, $00 to leave both waveform
  1812.             & gateflag unchanged, or $FE / $FF to control gateflag but leave
  1813.             waveform unchanged.
  1814.  
  1815. v2.6      - Fixed pattern default length selection display when decrementing
  1816.             from a length of 100 or higher.
  1817.           - Fixed mouse selection of pattern when adjusting an adjacent channel.
  1818.           - Fixed help screen instructions.
  1819.           - Changed resolution to 800x600.
  1820.           - Changed all songname rows to be displayed at the same time.
  1821.           - Changed mouse control to allow pattern column selection even when
  1822.             left mouse button is held down.
  1823.           - Changed speed of PageUp/PageDown scrolling to be faster.
  1824.           - Optimized graphics output.
  1825.           - BME library is no longer needed.
  1826.  
  1827. v2.61     - Added the backquote key (top-left on keyboard) to select channel
  1828.             in pattern edit mode, and to select table in table edit mode. Use 
  1829.             with SHIFT to go backwards.
  1830.           - Added SHIFT+channel number to mute channels in pattern edit mode.
  1831.           
  1832. v2.62     - Added possibility for realtime calculated note independent (hifi)
  1833.             portamento & vibrato. Warning: has potential for huge rastertime
  1834.             increase.
  1835.             
  1836. v2.63     - Fixed note independent portamento & vibrato to use the last note
  1837.             set in wavetable for calculations, instead of the last note in
  1838.             patterndata.
  1839.             
  1840. v2.64     - Fixed paste in table (SHIFT+V) working also without SHIFT pressed. 
  1841.  
  1842. v2.65     - Fixed raw keycodes over 511 interpreted as some other keys in the
  1843.             0-511 range.
  1844.  
  1845. v2.66Beta - Initial cycle-exact HardSID support (Win32 only)
  1846.           - Permit running without sound.
  1847.           
  1848. v2.67     - Configurable cycle-exact HardSID buffer length (separate for inter-
  1849.             active and playback mode, see /T and /U command line options)  
  1850.             
  1851. v2.68     - Fixed set tempo -command overwriting frequencytable in 1 or 2
  1852.             channel modes.
  1853.           - Fixed sound uninit crash with multicore processors (?)
  1854.           - SID register write order tweaked to resemble JCH NewPlayer 21.
  1855.           - Unbuffered playroutine optimized & modified to resemble buffered
  1856.             mode timing more.
  1857.           - New reSID-fp engine (with distortion & nonlinearity) from Antti
  1858.             Lankila integrated. Activated with /I command line option parameters
  1859.             2 & 3.
  1860.           - Command quick reference by Simon Bennett included.
  1861.           
  1862. v2.69     - Fixed click bug in reSID audio output.
  1863.           - Newest reSID-fp code integrated.
  1864.           - reSID-fp filter parameters adjustable from the configuration file.This is reSID, a reverse engineered software emulation of the MOS6581 SID
  1865. (Sound Interface Device). This chip was used in the Commodore 64 computer.
  1866.  
  1867. reSID is free software. See the file COPYING for copying permission.
  1868.  
  1869. reSID is a C++ library containing a complete emulation of the SID chip.
  1870. This library can be linked into programs emulating the MOS6510 MPU to
  1871. play music made for the Commodore 64 computer. reSID has been successfully
  1872. linked into VICE, a full-fledged Commodore 64 emulator, and SIDPLAY, a
  1873. popular SID tune player. The VICE home page is:
  1874. http://www.cs.cmu.edu/~dsladic/vice/
  1875. A patch for SIDPLAY can be found on the SIDPLAY home page:
  1876. http://www.geocities.com/SiliconValley/Lakes/5147/
  1877.  
  1878. Various SID emulators exist, however reSID should still be of great
  1879. interest to Commodore 64 nostalgics. The emulator engine is cycle-based,
  1880. emulating the internal operations of the SID chip. SID's audio filter is
  1881. modeled as an actual two-integrator-loop biquadratic filter circuit.
  1882. The engine has been developed based on available information on SID, sampling
  1883. of the OSC3 and ENV3 registers, filter theory, and meticulous testing.
  1884. In short, a scientific approach has been taken to model the SID chip as
  1885. accurately as possible.
  1886.  
  1887. To our knowledge reSID is by far the most accurate SID emulator ever created.
  1888. This comes at a price; what is considered a fairly fast CPU at the time of
  1889. this writing is needed to run the emulator.
  1890. Please distribute this file with the SDL runtime environment:
  1891.  
  1892. The Simple DirectMedia Layer (SDL for short) is a cross-platfrom library
  1893. designed to make it easy to write multi-media software, such as games and
  1894. emulators.
  1895.  
  1896. The Simple DirectMedia Layer library source code is available from:
  1897. http://www.libsdl.org/
  1898.  
  1899. This library is distributed under the terms of the GNU LGPL license:
  1900. http://www.gnu.org/copyleft/lesser.html
  1901.  
  1902.