aboutsummaryrefslogtreecommitdiff
path: root/pokeytest/pokey11.txt
diff options
context:
space:
mode:
Diffstat (limited to 'pokeytest/pokey11.txt')
-rw-r--r--pokeytest/pokey11.txt277
1 files changed, 277 insertions, 0 deletions
diff --git a/pokeytest/pokey11.txt b/pokeytest/pokey11.txt
new file mode 100644
index 0000000..498d768
--- /dev/null
+++ b/pokeytest/pokey11.txt
@@ -0,0 +1,277 @@
+ 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.