aboutsummaryrefslogtreecommitdiff
path: root/pokeytest/pokey11_readme.txt
blob: 31eac81b75cce6171d15ddf9b9febc28157d9922 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
                ATARI 800 - POKEY SOUND EMULATION LIBRARY V1.1 
                ==============================================
                              September 23, 1996
                              
The Pokey Sound Emulation Library consists of source code and example 
executables that are designed to emulate the sound output characteristics
of the Atari 800 Pokey chip.  Contained in this distribution, you should 
also have the following files:


README.TXT  - This file
FILE_ID.DIZ - A quick description of the release.
SOUND.C     - The SB Driver Source Code.
SOUND.H     - The SB Driver Header File which contains the function 
               prototypes.
SOUND.TXT   - A text file which explains the operation of the SB Driver 
               module.
               
POKEY11.C   - The Pokey Sound Emulation Source Code.
POKEY11.H   - The Pokey Sound Emulation Header File which contains the 
              function prototypes.
POKEY11.TXT - A text file which explains the operation of the Pokey Sound
              Emulation module.
SNDTEST.C   - The Main Test routine Source Code.  Provided as an example
              of how the routines can be used. 
SNDTEST.EXE - An pre-compiled executable based on the code provided.              


These routines are available for your use free of charge, provided you give 
me proper recognition, and also provided you don't make a profit off of my 
work.  See the GNU Library Public License for more information.

If the final product you are creating will be sold for a profit, please
contact me at rfries@frmail.frco.com so we can discuss terms.


THE LIBRARY
-----------

The Pokey Sound Emulation software consists of two main files.  The 
functions have been divided into these two files depending on your needs.  
If you only need the sound generation routines, the only file you'll need 
to compile and link is the POKEY11.C file.  If you need full SB drivers as 
well, then link both the POKEY11.C and the SOUND.C files into your 
application.

The POKEY11.C file was designed to be as portable as possible.  You should
be able to use the file with little or no modification on any 'C' compiler.
It is currently only available in 'C', though I'll be happy to convert the
file to Assembly Language if necessary.  For best results, this file should
be compiled in a 32-bit environment with the 'maximize speed' option.

The SOUND.C file was designed to work with the Borland 'C' compiler.  It
may also work directly with other compilers, though some modification may
be required.  The SB driver routines in this file have several limitations
which are described in detail in the SOUND.TXT file.  NOTE: The SB driver
routines are written in 16-bit.  

The POKEY11.C routines should be very stable, though I'm not as confident
with the SB routines.  They work correctly on my system, though I offer no
guarantees.

Depending on your needs, you will use one of the following algorithms:


1) POKEY11.C only - in this case, it is assumed you already have audio 
                    driver routines
   
   The general design is as follows:

   a) During startup, make a single call to Pokey_sound_init()
   b) Whenever an AUDC or AUDF value changes, call Update_pokey_sound()
   c) When a new buffer needs to be filled, call Pokey_process()


2) POKEY11.C and SOUND.C - using the SB driver routines I've provided
   (note: the SB driver routines are written for a 16-bit compiler)

   The general design is as follows:

   a) During startup, make a single call to OpenSB()
   b) During startup, make a single call to Pokey_sound_init()
   c) Whenever an AUDC or AUDF value changes, call Update_pokey_sound()
   d) Periodically call FillBuffer()
   e) During shutdown, make a single call to CloseSB()


Each function call has its own set of parameters.  Check with the 
POKEY11.TXT and SOUND.TXT files for more information.

The SNDTEST.C file has also been provided as an example.  I wrote it mainly
for my testing, but it should give you a little insight on how to correctly
use the routines.  You can also run the SNDTEST.EXE to play with the sounds.

Since the SNDTEST.EXE program uses my SOUND SB driver routines, it is subject 
to the same limitations.  It only supports IRQs 0-7 and DMAs 0-3.  It also 
only supports low-speed audio output (max freq is approx. 22KHz), and requires
that you have the BLASTER environment variable configured.
                        

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.