path: root/pokeytest/pokey11.txt

                       Atari POKEY Chip Simulator V1.1
                       ===============================
                                by Ron Fries
                                  23 Sep 96

The POKEY Chip Simulator is designed to emulate the functionality of the
Atari POKEY Chip Hardware through 'C' Sourcecode.  I have seen very good
results.  The simulator is able to produce sounds which are essentially
identical to the original Atari, including the exact distortions and
pitches. 

The simulator is designed to run in a 32-bit environment.  Though it can
compiled and run in a 16-bit environment, it is slow.  


Features:
---------

Version 1.1 of the 'POKEY' simulator supports the following functions:

1) All polynomial sound generators: 
   a) 4-bit poly - actual bit pattern determined from sampled sound
   b) 5-bit poly - actual bit pattern determined from sampled sound
   c) 17-bit poly - simulated random bit pattern
   d) 9-bit poly - derived from simulated 17-bit poly
   
2) Full support of all 'Divide by N' counter clocks:
   a) 1.79 MHz (high limited to playback sample rate)
   b) 64 KHz (high limited to playback sample rate)
   c) 15 KHz

3) Full support of all 'Divide by N' resolutions:
   a) 8-bit - single channel
   b) 16-bit - double channel

4) Full support of all distortions 
   a) 5-bit poly, then 17-bit poly
   b) 5-bit poly only
   c) 5-bit poly, then 4-bit poly
   d) 17-bit poly only
   e) no poly counters (pure tone)
   f) 5-bit poly only

5) Full support of volume control 

6) Full support of all pitches - distortions will vary exactly as the
   original Atari based on different pitches

7) Accurate pitch generation

8) Support of any playback sample rate (e.g. 22050)


The 'POKEY' simulator does not currently support the following functions:

1) High pass filters


Though I don't believe adding support for the High-Pass filters is very
complicated, I decided not to add support right now because I don't
believe this feature is used much.  I'm also not sure how much impact it
would have on performance.

You'll notice in the code there are two separate versions.  The original
process function, now called Pokey_process_2(), is the non-optimized 
version.  I've left it in for reference.  The other function,
Pokey_process(), is optimized.  In my tests using the 'Maximize Speed' 
option of the compiler, I've seen very good performance.  On my 486DX2-66, 
it typically takes about 0.15 seconds to produce about 3 seconds of audio.  
These times were calculated under WIN95.

One of the unique features of the optimized version is that the processing
time will vary based on the frequency.  Since the routine only calculates
new output values when a change is sensed, the lower frequencies (which 
change less frequently) will require less processing time.


Differences Between the Simulator and the Actual POKEY Chip:
------------------------------------------------------------  

The biggest difference between the simulator and the original hardware is 
that the simulator emulates an 'ideal' POKEY chip.  All output from the 
simulator is a based on a precise square wave, whereas the output from the
original chip has decay.  Though the output is slightly different, I
don't believe this difference is easily discernible.

Another slight difference is the 17-bit/9-bit poly.  Since the polynomial
is large (2^17 bits), I choose to create the sample using a random number
generator rather than a table.  I don't believe this difference is 
significant.

There are also a few differences which are introduced by aliasing.  This is
a direct result of using an output sampling rate which is not identical to
the original sound rate.  It is most evident with high frequencies. 

A final difference is the lack of support for the High-Pass Filter 
functionality.  I plan to add this in a future release if necessary.


Sample/Test Application:
------------------------

The test program I've distributed is a 16-bit DOS application created with 
the Borland 'C' compiler.  The only reason I used 16-bit was because I 
already had a set of working SB drivers in 16-bit.  Since the test system
is dedicated to generating sounds, the performance in 16-bit is more than
adequate.


POKEY11.C
==========

The POKEY11.C file is the heart of the POKEY Sound Emulation program.  
Although the routines in the file must work together, no other files are
modules are required for operation.  A header file, 'POKEY11.H', has 
been included for use in other modules, and provides the necessary 
function prototypes.  I've attempted to make the routines as portable as
possible, so the file should compile on almost any compiler with little
or no modification.  

I have made some attempts at optimizing the routines, though I am sure
more optimization can be done.  They are currently only available in 'C'.
I'll be happy to convert them to assembly language if desired.  Please feel 
free to send me e-mail at rfries@tcmail.frco.com.

The routines are easy to use.  Detailed descriptions on the function calls   
are listed below.

The POKEY11.C module can be compiled in a 32-bit or 16-bit environment.
Since these routines are optimized for 32-bit use, the code will default
to 32-bit.  To compile in 16-bits, use a command line option to define
the variable COMP16.


GENERAL OVERVIEW
----------------

On start-up of the system, a single call should be made to Pokey_sound_init.  
This routine will prepare the structures for sound output.  This routine
can be called again if necessary during warm-start or other reset.

Once in the main loop, there are two other functions that will be used.  
Whenever the system needs to write to either the AUDC or AUDF values,
a call should be made to the Update_pokey_sound routine.  This routine will 
take care of updating the internal registers.  It will pre-calculate several
values to help with optimization.

The only other routine that is called is the Pokey_process function.  This 
function will fill a audio buffer with a specified number of bytes.  This
function should be called whenever a new audio buffer is required.

For best results, I recommend using at least two output buffers.  Using this
scheme, the sound card can be playing one buffer while the system is filling
the other.


DETAILED FUNCTION DESCRIPTIONS
------------------------------

Pokey_sound_init(uint32 freq17, uint16 playback_freq)
--------------------------------------------------------

This function initializes the structures used by the PokeySound routines.
This function takes two parameters: the main clock frequency and the 
playback frequency.  

The main clock frequency is the frequency of the 1.79MHz source clock.  
To provide exact results, freq17 should be set equal to 1789790 Hz.  As an 
alternative, freq17 can be set to an approximate frequency of 1787520 Hz.  
Using this approximate frequency will reduce aliasing and thus produce a 
clearer output signal.

A constant has been defined for both of these values for your convenience.
The names are FREQ_17_EXACT and FREQ_17_APPROX.

The playback frequency is the frequency of the sound playback (the frequency 
used by the sound card).  For best results, the playback frequency should 
be an even division of the main clock frequency.  Since most of the sounds
will be generated using the 64kHz clock, I also recommend making the 
playback frequency an even division of the 64kHz clock.

The 64kHz clock is exactly equal to the main clock divided by 28.  For
the playback frequency, I recommend one of the following values:

1) FREQ_17_APPROX / (28*1), which is equal to 63840.  Of course, most sound 
   cards can't reproduce this frequency.

2) FREQ_17_APPROX / (28*2), which is equal to 31920.  All of the newer cards
   will support this frequency.  

3) FREQ_17_APPROX / (28*3), which is equal to 21280.  All of the SB 
   compatibles should support this frequency.

4) FREQ_17_APPROX / (28*4), which is equal to 15960.  This may be the
   best choice, as it offers good sound reproduction with good performance.
  
Of course, these options also assume you are using the approximate
frequency for the main clock as well.  Any of these choices will offer the
best results when the main 64kHz clock is used, reasonable results when the
15kHz clock is selected, and marginal results when the 1.79MHz clock is
selected (the only way to produce good results in all cases is to set the
playback frequency to 1.79MHz!)

Feel free to experiment to find other alternatives as well.

This function has no return value (void).


Update_pokey_sound (uint16 addr, uint8 val)
-----------------------------------------

This function should be called each time an AUDC, AUDF or AUDCTL value
changes.  This function takes two parameters: the address to change and
the new value.  The address should be one of the following values:

                  Addr     Description
                 ------    -----------
                 0xd200       AUDF1
                 0xd201       AUDC1
                 0xd202       AUDF2
                 0xd203       AUDC2
                 0xd204       AUDF3
                 0xd205       AUDC3
                 0xd206       AUDF4
                 0xd207       AUDC4
                 0xd208       AUDCTL

Any values outside of this range will be ignored.

The routine pre-calculates several values that are needed by the 
processing function.  This is done to optimize performance.

This function has no return value (void).


Pokey_process (unsigned char *buffer, uint16 n)
---------------------------------------------

This function calculates and fills a buffer with unsigned 8-bit mono audio.
This function takes two parameters: a pointer to the buffer to fill and
the size of the buffer (limited to 65535).  This function fills the 
buffer based on the requested size and returns.  It automatically
updates the pointers for the next call, so subsequent calls to this function
will provide a continuous stream of data.

The size of the buffer that is needed depends on the playback frequency.
It is best to keep the buffer as small as possible to maximize response time
to changes in the sound.  Of course, the minimum size is dependent on
system and emulator performance.

Selecting the correct buffer size is a careful balance.  Selecting a buffer
size that is too small will produce noticeable clicks in the output, though
selecting a size that is too large will cause a poor response time and 
possible delays in the system when the new buffer is filled.

This function has no return value (void).


License Information and Copyright Notice
========================================

PokeySound is Copyright(c) 1996 by Ron Fries

This library is free software; you can redistribute it and/or modify it under 
the terms of version 2 of the GNU Library General Public License as published 
by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for more 
details.

To obtain a copy of the GNU Library General Public License, write to the Free 
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Any permitted reproduction of these routines, in whole or in part, must bear 
this legend.