Information for Plus/4 users
----------------------------

(I think I should have written this doc a bit earlier - I mean 'several
years ago', to give it real practical use :-(. I seriously doubt that even
despite the advantages of this editor, it could count on more than a few
users. But after all, it is here. It is here, it is powerful, and it is free.
Be it late or not... )

Here you can find infos on the use of the editor on Plus/4. You'll also find
this 'chapter' useful if you want your SIDwinder V01.2x musics (composed on
C64) be played on this platform.

Also a quick note for Plus/4 users: because of this whole lot of ASCII junk,
there was no space on the disk for including the GNU General Public License.
Please also obtain either the C64 or the source distribution.


Table of contents
------------------

- The platform
- The SID card
- SIDwinder for Plus/4
- When you finished composing a song...
- Some short notes
- And finally: how to redirect a player to a new base address?
- When moving a C64 tune to Plus/4...
- When moving a tune created on Plus/4 to C64 platform...


The platform
-------------

Before going deep into the editor and the player related things, we should
take the _reason of all differences, the hardware itselves. If you're a
Plus/4 programmer, you should know these properties I'll speak about - but
it's still neccessary to talk these out, to know the reasons of all.

First of all, a stock Plus/4 doesn't have such a good synthesizer chip that
the SID is. The built-in sound generators (included by the 8360 TED) are
rather cripple, and are rather similar to the soundgenerators of the old
VIC-20.

To play SID-originate musics on the black dustbin, you must either emulate
the properties of the SID chip by software (--> music converter routines) or
you should have a real SID chip interfaced to the Plus/4 (--> SID cards).
Both methods are possible - but the real hardware is definitely better than
any software based solutions, if the subject is the SID, and the emulating
computer is the Plus/4. (Emulating the SID correctly by software is a very
hard task indeed, just see _any SID music players on the PC).

Here I'll rather deal with the SID card, since I considered implementing a
music converter routine to the editor both hard and inappropriate.
(Implementing one would have costed me a lot of work, since it implied to
reorganize the IRQ routines and some of the memory map - and it would have
caused a lot of trouble, since no music converter routines emulate the SID
correctly. This latter is just annoying if you try to get a demopart to
work, but it becomes something more serious if you're using your computer
for composing music - a music that may thus fail to play correctly on a real
SID).

As speaking of SID cards, I know of three attempts, of which two were really
useable and just one that was spread 'widely'. The editor code assumes this
latter, the Synergy SID card (by Solder) to be present (at $fd40).

O.K. now we have a SID chip interfaced to the computer, what's next?

The another thing you should be aware of, that the processor clock of the
C64 and the Plus/4 are different. This should not be significant in such a
subject, but it turns out to be so if the subject is the SID chip and this
card. Unfortunately, the counters inside the SID are based on the same
processor clock the one the chip is synced to the processor bus. The C64 runs
at 17.734472Mhz / 18, whereas the Plus/4 single clock is 17.734472Mhz / 20
(PAL machines). A SID, running at the Plus/4 single clock runs at 9/10 times
the C64 clock, resulting in everything you should suspect: lower frq of the
voices (about one note) and longer Attack / Decay / Release times (ADSR).

I think these were the two main reasons of all problems you may experience
when you're composing something.

There are some less important differences between the computers, at least,
in the scope of this program. I could mention the keyboard, the memory
mapping and so on, but they're not significant (at least not from the users
point of view).


The SID card
------------

Since this is the 'base' of all music composing in this editor, I thought I
should write some words regarding this device. In short, the card is a
clear, compact design; for example, the address decoding is based on a GAL.


 - The card contains a 8580 SID (Solder told me, the 5v to 9v DC-DC
   transverter is not able to supply the 12v Vdd to the 6581 SID. I know
   this chip, since I also used it for my design (thanks Christian!), and it
   can for sure generate 12 volts from a single 5v supply, but maybe not that
   current the 6581 SID would need at its Vdd input).

 - The clock of the SID, as I mentioned, is the single clock of the Plus/4.
   Regardless of the actual processor clock, the card always supplies this
   frequency to the SID (thus making it possible to run your programs with
   twiee clock enabled. Not an obvious feature as you'd expect - the card
   has a dedicated chip (the 4520) for the task).

 - The card has both an audio input and an audio output 3.5 jack connector.
   The input is fed to the audio input of the SID, the same way it is seen
   in the C64. The output can go directly to your stereo amplifier system
   :-). The SID output can be also fed to the computers audio input, thus
   mixing the SID voices to the TED sounds (can be selected by a switch).

 - The audio output level can be adjusted by a trimmer on the card.

 - There is a full featured joystick port on the card, including the SID
   paddle (A/D) inputs.

 - All SID registers are accessible, even the read-only registers of voice
   3 and the paddle registers.

 - Somehow, the SID on the card plays digis back correctly. This issue is
   also not obvious, since C64s equipped with 8580 SIDs tend not to play
   digi sounds at all. Something must be around the audio in circuit. I
   haven't checked it, but one thing is for sure - the digis work O.K.


Now, some disadvantages (or rather disappointing things):

 - The most serious one is, the output analog signal amplifier stage has
   strong DC distortion. The higher output level you set on the trimmer, the
   stronger clipping distortion you get. Obviously, you hear the effect more
   if the output level is higher, e.g. all channels are on, the volume is
   set to $0f and you use (resonant) filtered bass. Once I asked Solder
   about the reason and the solution, and he answered that it is due to the
   needed high level on the Plus/4 analog input.

   Unfortunately, there is just one way to step this problem over: connect
   the SID card directly to your hi-fi equipment and turn the trimmer on the
   card lower (middle position will do). You'll hear much less distortion
   from the card, however, this is still not enough to get rid of the strange
   effect completely. Even after turning the trimmer down, you'll still
   experience fall-out and distorted waves if a strong sound comes in. I know
   no correct solution for the problem, the card's audio amplifier part should
   be modified but I didn't want to modify Solder's design.

 - The card's filters sound a bit different than the original, even the
   C64-II that BTW has the same SID. The reason: the SID is mostly an
   analog design; at least its filters are. Because of the nature of these
   circuits, even the slightest differences in the used parts can result in
   different sound. The SID filters use two external capacitors, that mostly
   determine their response. Now, the SID-card has exactly the same
   capacitor value as the C64 SID has. ...But the manufacturing is
   different: Solder used new small 'micro' ceramic capacitors, whereas
   Commodore used 'standard', round-type capacitors. I replaced the
   capacitors by two originals I picked out from an old C64 board and now it
   sounds the same :-)

   Another reason is: people used to play C64 tunes with simply redirecting
   the original C64 tune to the new baseaddress (sometimes with a copying
   loop that is even worse, but it's an other issue), without correcting
   the SID frequency values to the 'slower' SID. This results in playing all
   notes at about one note lower frequency than the original, but with the
   same filter settings - the filter cutoff remains the same, since this
   analog part is not affected by the oscillator frequency in any ways. This
   can cause different sound - but not because of the filter in particular,
   rather the 'wrong' oscillator settings.

   IMO the sound caused by the different filter caps is not so much serious
   that you should, like me, also replace them - the strange sound is rather
   caused by the wrong (not corrected) original C64 music replay and the
   card DC distortion together.

 - After few minutes of operation, the SID on the card gets very hot. I
   won't mention this one, since I know Commodore's chips and I know that a
   lot of them get hot while in operation, but I certainly haven't
   experienced this in the subject of the 8580 SID. Should this be because of
   wrong analog interfacing or bad syncing, I don't know, but I hope it won't
   kill the SID (haven't done that so far BTW).


SIDwinder for Plus/4
--------------------

Now a few words about the way SIDwinder operates on Plus/4.

First of all, there is no significant difference between the C64 and the
Plus/4 code. The editors are very same to each other, to the point of all
possibly equal code parts. Some constant values and some I/O register
references are replaced by their equivalents on the Plus/4 (color values,
TED registermap and so on).

The keys are mapped to their respective equivalents - as you'll see, I
decided to map the F-keys to the ones at the same _place, not name. Also,
the <- key was mapped to the ESC key (...but you can also use the left arrow
pressing Shift + '=' :-) ).

The editors include the very same music player routine, of course with the
above differences: the player in the editor assumes the SID at $fd40, and
includes a note-to-frequency-value-table generated for the nominal clock of
the Plus/4 SID card.

Well... that's all.

As speaking of the other utilities, the packer and the ASCII viewer, they
needed even less efforts to behave the same on both machines.


When you finished composing a song...
-------------------------------------

Well, you should decide what you want to do with the song.

 - If you want the song to be included to your product as native SID-card
music, in the packer select $fd40 as SID-baseaddress and Plus/4 frequency
table.

 - If you rather want it to be like a native C64 music, pack the song like
   the above but select $d400 as SID base-address and C64 frequency table.

You should also decide with this latter option if you want your song to be
distributed in a collection together with native C64 musics (the HVSID
collection is a good example). But at this point, I'd suggest to read the
appropriate section later in this document before submitting the entry ;-).

Important note for the packing process. The default zeropage word assigned
to the SIDwinder player is $fb-$fc. On the Plus/4, $fb stores the actual
ROM configuration. If your product has to co-operate with the Kernal ROM and
the Kernal IRQ, you should rather select for example, $fc in the packing
process, to avoid unexpected crashes (it also made me spend a few hours in
hunting for bugs, when the Plus/4 version of the packer hanged with no
understandable reason :-\ ).


BTW, I'm sure, a lot of Plus/4 coders want their product to be
'configurable' in the subject of the sounds. This is a clever thought, since
even if the SID card was spread quite 'widely' and can still be ordered from
Solder, the majority of Plus/4 people doesn't have this pretty sound device
- some even never heard of it :-(. So, no doubt - if it's possible, your
program should also play music and/or sound fx through the TED sound output.

The theory is quite simple: there is the packed SID music linked into your
program (at this point, this is no matter if it was composed in SIDwinder or
not). Somehow, either by auto detecting the SID card or asking the user, you
should determine the used sound output (TED or SID card). And when it's
done, something has to be done in order to redirect the music to one or
another sound source.

This 'something' could be the following

 - By default, you generate the packed music file with the above mentioned
   parameters (base=$fd40 and Plus/4 frq table) and link this file into your
   program. If the determined playing is 'SID card', you don't touch
   anything in your programs init, you simply call the player each frame and
   it plays as it's expected.
   If the user selected 'TED', or your auto-detect routine detected no SID
   cards, the player must be redirected to a 'phantom' SID address and you
   also have to use a music converter routine (using the same 'phantom' SID
   base address) to make the music play. The phantom SID address used to be
   $d400 by default (since all C64 musics write to this address, and most
   music converter routines read SID data from this address).

You can also do the opposite (have a music with $d400 SID base address,
don't touch it if the TED was selected, and redirect it to $fd40 if SID was
requested).


Some short notes
----------------

 - If you play a music through the SID card, you're strongly suggested to
   use a native 885Khz based frequency table (that one note difference seem
   to cause the music to sound _awful, especially if filters were used). The
   frq table type is not serious in the subject of the music converter
   routines - they tend to f*** up the exact frq values anyway, and also
   don't provide SID filter emulation. So you can also play the native
   Plus/4 frq table music through a music converter routine with no
   problems.

   If you use a music _not created in SIDwinder, but also want to correct
   its note frequency values, you'll most probably find a similar frq table
   in the original C64 player as you can find in the SIDwinder player from
   $1040 to $10ff. So, it should be easy to replace the original frq value
   tables by one you simply picked out from a SIDwinder player that was
   generated with the Plus/4 frq table ;-).

 - If, and _only if TED was assumed, you must also call the music converter
   routine.

 - NEVER NEVER NEVER NEVER do such lame work I've seen in many early
   SID-card 'compatible' demos and games: the original C64 music player is
   called, then the resulting values are simply copied to $fd40 with a loop.
   This causes all bad things to happen together - since the original music
   player can write - and you can be sure, does write! - the SID registers
   more than once in a run, the copying loop, and finally the SID will miss
   all except the very last register changes. If you did such try, and you
   heard the music to sound suspicious (missing notes, chaotic ADSR of the
   sounds and such things), you found the answer here, right now :-).

   Not to mention that this is the _only correct solution, redirecting the
   player runs also much faster than running a copying loop each frame, after
   each call of the player...

 - You could ask, and you should be right - if this is true, then _all music
   converter routines should suffer from the same problem. This is true. I
   used to step over this problem with a little modification in the player.
   But this needs the presence of one of _my music converter routines.
   Mostly, the ADSR - and especially, the KEY bit of the SID control
   register(s) in particular - causes problems. So, I used to replace _every
   $d404 reference in the player by a call to a short routine:

        sta $d404,x                  ;store the value, as expected
        and #$01
        bne end
        sta $0204,x                  ;Internal variable of my music converter
   end  rts

   (One thing to note: most players address the SID registers with indexed
   addressing mode, either x or y is used (in SIDwinder, it is x).

 - As speaking of the phantom SID base address, it doesn't have to be $d400,
   it may certainly be anything you want - just make sure, the music and the
   music converter routine assumes the same base address. Sometimes, using
   $d400 is inappropriate - it is well in the anyway useable memory area,
   well inside everything. I've seen in many converted games that $0400,
   $ff40 and similar addresses were used (so does my Leonardo game ;-) ).
   You can anyway use my SID base relocator routine to also redirect your
   favourite music converter routine to a new base address, instead of
   going through the code in monitor and replace every occurences by hand.


And finally: how to redirect a player to a new base address?
------------------------------------------------------------

This is simpler than you'd expect. I've written a small routine back in
1992 to do the task. I revised the code a bit, to make it simpler. You find
it in the distribution in ASCII source format, and you should also find a
compiled version. You can fiddle with both, I hope the routine is obvious.
You can relocate the routine to anywhere in the memory (since it consists of
no absolute jumps and references), just set the appropriate constants and
call it if it is neccessary.

(In short: you must set the start and end addresses of the code to be
redirected, ie. the start and end address of the player code. You must also
set the old (present) SID base address and the new base address. The code
goes through the whole code, and whenever it finds an absolute, or indexed
absolute reference to the old SID address area, it replaces the address by
the appropriate equivalent in the new area.)


When moving a C64 tune to Plus/4...
-----------------------------------

If you have a tune composed in the C64 version of the editor, and you want
it to be used in a Plus/4 program (with SID card), you should do a few final
steps before assuming everything to be O.K.

(Regardless to say, this final precaution is not caused by the programs, but
rather the little-bit-incompatible SID card hardware).

There are two points your tunes can go mad when playing on a Plus/4, and
both come from the different SID clock.

  - Since the SID is slower, one needs higher values to achieve the same
    output frequency (~ the same note). This is not a problem - the frq
    table is the right one to address this one. But there is still a problem.
    The SIDwinder player uses absolute frequency values for the glide/slide
    instructions. If your tune uses glide/slide, the speeds can be slow
    occassionally. (Theoretically, you can fix the problem if you multiple
    all glide speeds in the glide table by 10/9).

    The difference can also cause problems in the slide/vibrato table. The
    solution is the same: if you experience problems, just multiple all
    absolute values by 10/9.

  - Since the SID is slower, also all ADSR speeds are slower. This causes
    further problems in your instruments. Unfortunately, you have almost no
    chance to make everything sound perfect, because of the raw resolution
    of the SID ADR time settings (Sustain is not involved, of course). Just
    check the instruments by ear; if you notice that something is wrong, go
    and correct the appropriate ADSR value in the sound editor.


When moving a tune created on Plus/4 to C64 platform...
-------------------------------------------------------

You should do simply the opposite of the previous section. You can simply
assume that all speeds are faster by a factor of 10/9 and modify your song
- however nothing makes it sure that everything will sound correct, so it's
best to take the C64 editor and make the needed corrections if any (or
listen to the tune in a PC SID emulator, after you packed it - all in all,
check your tune before releasing it, to avoid surprises).
