sound/fmopl.h

   1 /* ScummVM - Graphic Adventure Engine
   2  *
   3  * ScummVM is the legal property of its developers, whose names
   4  * are too numerous to list here. Please refer to the COPYRIGHT
   5  * file distributed with this source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  *
  21  * $URL$
  22  * $Id$
  23  */
  24
  25 #ifndef SOUND_FMOPL_H
  26 #define SOUND_FMOPL_H
  27
  28 #include "common/scummsys.h"
  29 #include "common/str.h"
  30
  31 namespace OPL {
  32
  33 class OPL;
  34
  35 class Config {
  36 public:
  37         enum OplFlags {
  38                 kFlagOpl2               = (1 << 0),
  39                 kFlagDualOpl2   = (1 << 1),
  40                 kFlagOpl3               = (1 << 2)
  41         };
  42
  43         /**
  44          * OPL type to emulate.
  45          */
  46         enum OplType {
  47                 kOpl2,
  48                 kDualOpl2,
  49                 kOpl3
  50         };
  51
  52         typedef int8 DriverId;
  53         struct EmulatorDescription {
  54                 const char *name;
  55                 const char *description;
  56
  57                 DriverId id;    // A unique ID for each driver
  58                 uint32 flags;   // Capabilities of this driver
  59         };
  60
  61         /**
  62          * Get a list of all available OPL emulators.
  63          * @return list of all available OPL emulators, terminated by a zero entry
  64          */
  65         static const EmulatorDescription *getAvailable() { return _drivers; }
  66
  67         /**
  68          * Returns the driver id of a given name.
  69          */
  70         static DriverId parse(const Common::String &name);
  71
  72         /**
  73          * Detects a driver for the specific type.
  74          */
  75         static DriverId detect(OplType type);
  76
  77         /**
  78          * Creates the specific driver with a specific type setup.
  79          */
  80         static OPL *create(DriverId driver, OplType type);
  81
  82         /**
  83          * Wrapper to easily init an OPL chip, without specifing an emulator.
  84          * By default it will try to initialize an OPL2 emulator, thus an AdLib card.
  85          */
  86         static OPL *create(OplType type = kOpl2) { return create(detect(type), type); }
  87
  88 private:
  89         static const EmulatorDescription _drivers[];
  90 };
  91
  92 class OPL {
  93 private:
  94         // TODO: This is part of a temporary HACK to allow only 1 instance
  95         static bool _hasInstance;
  96 public:
  97         OPL() { assert(!_hasInstance); _hasInstance = true; }
  98         virtual ~OPL() { _hasInstance = false; }
  99
 100         /**
 101          * Initializes the OPL emulator.
 102          *
 103          * @param rate  output sample rate
 104          * @return              true on success, false on failure
 105          */
 106         virtual bool init(int rate) = 0;
 107
 108         /**
 109          * Reinitializes the OPL emulator
 110          */
 111         virtual void reset() = 0;
 112
 113         /**
 114          * Writes a byte to the given I/O port.
 115          *
 116          * @param a             port address
 117          * @param v             value, which will be written
 118          */
 119         virtual void write(int a, int v) = 0;
 120
 121         /**
 122          * Reads a byte from the given I/O port.
 123          *
 124          * @param a             port address
 125          * @return              value read
 126          */
 127         virtual byte read(int a) = 0;
 128
 129         /**
 130          * Function to directly write to a specific OPL register.
 131          * This writes to *both* chips for a Dual OPL2.
 132          *
 133          * @param r             hardware register number to write to
 134          * @param v             value, which will be written
 135          */
 136         virtual void writeReg(int r, int v) = 0;
 137
 138         /**
 139          * Read up to 'length' samples.
 140          *
 141          * Data will be in native endianess, 16 bit per sample, signed.
 142          * For stereo OPL, buffer will be filled with interleaved
 143          * left and right channel samples, starting with a left sample.
 144          * Furthermore, the samples in the left and right are summed up.
 145          * So if you request 4 samples from a stereo OPL, you will get
 146          * a total of two left channel and two right channel samples.
 147          */
 148         virtual void readBuffer(int16 *buffer, int length) = 0;
 149
 150         /**
 151          * Returns whether the setup OPL mode is stereo or not
 152          */
 153         virtual bool isStereo() const = 0;
 154 };
 155
 156 } // end of namespace OPL
 157
 158 // Legacy API
 159 // !You should not write any new code using the legacy API!
 160 typedef OPL::OPL FM_OPL;
 161
 162 void OPLDestroy(FM_OPL *OPL);
 163
 164 void OPLResetChip(FM_OPL *OPL);
 165 void OPLWrite(FM_OPL *OPL, int a, int v);
 166 unsigned char OPLRead(FM_OPL *OPL, int a);
 167 void OPLWriteReg(FM_OPL *OPL, int r, int v);
 168 void YM3812UpdateOne(FM_OPL *OPL, int16 *buffer, int length);
 169
 170 /**
 171  * Legacy factory to create an AdLib (OPL2) chip.
 172  *
 173  * !You should not write any new code using the legacy API!
 174  */
 175 FM_OPL *makeAdlibOPL(int rate);
 176
 177 #endif
 178