Ticket #8341: output-freq.2.diff

README

@@ -34 +34 @@
  * 7.3 Native MIDI support
  * 7.4 UNIX native & ALSA sequencer support
  * 7.5 Using compressed audiofiles (MP3, Ogg Vorbis, Flac)
+ * 7.6 Output sample rate
 8.0) Configuration Files
 9.0) Compiling
 X.X) Credits
@@ -330 +331 @@
                            atari, fmtowns, mac, pc)
   --multi-midi             Enable combination of Adlib and native MIDI
   --native-mt32            True Roland MT-32 (disable GM emulation)
+  --output-rate=RATE       Select output sample rate in Hz (e.g. 22050)
   --aspect-ratio           Enable aspect ratio correction
 
   --alt-intro              Use alternative intro for CD versions of Beneath a
@@ -861 +863 @@
 Eventually you will have a much smaller *.mp3, *.ogg or *.fla file, copy this
 file to your game dir. You can safely remove the old file.
 
+7.6) Output sample rate:
+---- -------------------
+
+The output sample rate tells ScummVM how many sound samples to play per channel
+per second. There is much that could be said on this subject, but most of it
+would be irrelevant here. The short version is that for most games 22050 Hz is
+fine, but in some cases 44100 Hz is preferable. On extremely low-end systems
+you may want to use 11025 Hz, but it's unlikely that you have to worry about
+that.
+
+To elaborate, most of the sounds ScummVM has to play were sampled at either
+22050 Hz or 11025 Hz. Using a higher sample rate will not magically improve the
+quality of these sounds. Hence, 22050 Hz is fine.
+
+Some games use CD audio. If you use compressed files for this, they are
+probably sampled at 44100 Hz, so for these games that may be a better choice of
+sample rate.
+
+When using the Adlib, FM Towns, PC Speaker or IBM PCjr music drivers, ScummVM
+is responsible for generating the samples. Usually 22050 Hz will be plenty for
+these, but there is at least one piece of Adlib music in Beneath a Steeel Sky
+that will sound a lot better at 44100 Hz.
+
+Using frequencies in between is not recommended. For one thing, your sound card
+may not support it. In theory, ScummVM should fall back on a sensible frequency
+in that case, but don't count on it. More importantly, ScummVM has to resample
+all sounds to its output frequency. This is much easier to do well if the
+output frequency is a multiple of the original frequency.
+
 
 8.0) Configuration file:
 ---- -------------------
@@ -944 +975 @@
         joystick_num    number   Number of joystick device to use for input
         master_volume   number   The master volume setting (0-255)
         music_driver    string   The music engine to use.
+        output_rate     number   The output sample rate to use, in Hz. Sensible
+                                 values are 11025, 22050 and 44100.
         alsa_port       string   Port to use for output when using the
                                  ALSA music driver.
         music_volume    number   The music volume setting (0-255)

backends/sdl/sdl-common.h

@@ -133 +133 @@
         
         virtual void setWindowCaption(const char *caption);
         virtual bool openCD(int drive);
+        virtual void setOutputSampleRate(int rate);
         virtual int getOutputSampleRate() const;
 
         virtual bool hasFeature(Feature f);
@@ -169 +170 @@
         SDL_Surface *_tmpscreen;
         bool _overlayVisible;
 
+        // Audio
+        int _samplesPerSec;
+
         // CD Audio
         SDL_CD *_cdrom;
         int cd_track, cd_num_loops, cd_start_frame, cd_duration;

backends/sdl/sdl.cpp

@@ -95 +95 @@
 #endif
         _hwscreen(0), _screen(0), _screenWidth(0), _screenHeight(0),
         _tmpscreen(0), _overlayVisible(false),
+        _samplesPerSec(SAMPLES_PER_SEC),
         _cdrom(0), _scaler_proc(0), _modeChanged(false), _dirty_checksums(0),
         _mouseVisible(false), _mouseDrawn(false), _mouseData(0),
         _mouseHotspotX(0), _mouseHotspotY(0),
@@ -289 +290 @@
 
 bool OSystem_SDL::setSoundCallback(SoundProc proc, void *param) {
         SDL_AudioSpec desired;
+        SDL_AudioSpec obtained;
 
         memset(&desired, 0, sizeof(desired));
 
-        desired.freq = SAMPLES_PER_SEC;
+        // Originally, we always used 2048 samples. This loop will produce the
+        // same result at 22050 Hz, and should hopefully produce something
+        // sensible for other frequencies. Note that it must be a power of two.
+
+        uint16 samples = 0x8000;
+
+        for (;;) {
+                if (samples / (_samplesPerSec / 1000) < 100)
+                        break;
+                samples >>= 1;
+        }
+
+        desired.freq = _samplesPerSec;
         desired.format = AUDIO_S16SYS;
         desired.channels = 2;
-        desired.samples = 2048;
+        desired.samples = samples;
         desired.callback = proc;
         desired.userdata = param;
-        if (SDL_OpenAudio(&desired, NULL) != 0) {
+        if (SDL_OpenAudio(&desired, &obtained) != 0) {
                 return false;
         }
+        // Note: This should be the obtained output rate, but it seems that at
+        // least on some platforms SDL will lie and claim it did get the rate
+        // even if it didn't. Probably only happens for "weird" rates, though.
+        _samplesPerSec = obtained.freq;
         SDL_PauseAudio(0);
         return true;
 }
@@ -309 +327 @@
         SDL_CloseAudio();
 }
 
+void OSystem_SDL::setOutputSampleRate(int rate) {
+        // The function can't be called after the audio device has been opened
+        if (SDL_GetAudioStatus() == SDL_AUDIO_STOPPED)
+                _samplesPerSec = rate;
+}
+
 int OSystem_SDL::getOutputSampleRate() const {
-        return SAMPLES_PER_SEC;
+        return _samplesPerSec;
 }
 
 #pragma mark -

base/gameDetector.cpp

@@ -78 +78 @@
         "                           atari, fmtowns, mac, pc)\n"
         "  --multi-midi             Enable combination Adlib and native MIDI\n"
         "  --native-mt32            True Roland MT-32 (disable GM emulation)\n"
+        "  --output-rate=RATE       Select output sample rate in Hz (e.g. 22050)\n"
         "  --aspect-ratio           Enable aspect ratio correction\n"
         "\n"
 #if !defined(DISABLE_SKY) || !defined(DISABLE_QUEEN)
@@ -312 +313 @@
                                 ConfMan.set("music_driver", option, kTransientDomain);
                         END_OPTION
 
+                        DO_LONG_OPTION("output-rate")
+                                ConfMan.set("output_rate", (int)strtol(option, 0, 10), kTransientDomain);
+                        END_OPTION
+
                         DO_OPTION_BOOL('f', "fullscreen")
                                 ConfMan.set("fullscreen", cmdValue, kTransientDomain);
                         END_OPTION

common/system.h

@@ -546 +546 @@
         virtual void clearSoundCallback() = 0;
 
         /**
+         * Set the desired output sample rate. It has to be called before
+         * setSoundCallback(), and it's not certain that we actually get it.
+         * Use getOutputSampleRate() to find out.
+         */
+        virtual void setOutputSampleRate(int rate) = 0;
+
+        /**
          * Determine the output sample rate. Audio data provided by the sound
          * callback will be played using this rate.
          * @return the output sample rate

doc/05_01.tex

@@ -37 +37 @@
                           &atari, fmtowns, mac, pc)\\
   --multi-midi            &Enable combination of Adlib and native MIDI\\
   --native-mt32           &True Roland MT-32 (disable GM emulation)\\
+  --output-rate=RATE      &Select output sample rate in Hz (e.g. 22050)\\
   --aspect-ratio          &Enable aspect ratio correction\\
 \\
   --alt-intro             &Use alternative intro for CD versions of Beneath a\\

doc/07.tex

@@ -34 +34 @@
 \input {07_02.tex}
 \input {07_03.tex}
 \input {07_04.tex}
-\input {07_05.tex}
- No newline at end of file
+\input {07_05.tex}
+\input {07_06.tex}

doc/07_06.tex

@@ +1 @@
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "readme"
+%%% End: 
+
+\subsection{Output sample rate}
+
+The output sample rate tells ScummVM how many sound samples to play per channel
+per second. There is much that could be said on this subject, but most of it
+would be irrelevant here. The short version is that for most games 22050 Hz is
+fine, but in some cases 44100 Hz is preferable. On extremely low-end systems
+you may want to use 11025 Hz, but it's unlikely that you have to worry about
+that.
+
+To elaborate, most of the sounds ScummVM has to play were sampled at either
+22050 Hz or 11025 Hz. Using a higher sample rate will not magically improve the
+quality of these sounds. Hence, 22050 Hz is fine.
+
+Some games use CD audio. If you use compressed files for this, they are
+probably sampled at 44100 Hz, so for these games that may be a better choice of
+sample rate.
+
+When using the Adlib, FM Towns, PC Speaker or IBM PCjr music drivers, ScummVM
+is responsible for generating the samples. Usually 22050 Hz will be plenty for
+these, but there is at least one piece of Adlib music in Beneath a Steeel Sky
+that will sound a lot better at 44100 Hz.
+
+Using frequencies in between is not recommended. For one thing, your sound card
+may not support it. In theory, ScummVM should fall back on a sensible frequency
+in that case, but don't count on it. More importantly, ScummVM has to resample
+all sounds to its output frequency. This is much easier to do well if the
+output frequency is a multiple of the original frequency.

doc/08.tex

@@ -92 +92 @@
         joystick\_num   &number   Number of joystick device to use for input\\
         master\_volume  &number   The master volume setting (0-255)\\
         music\_driver   &string   The music engine to use.\\
+        output\_rate    &number   The output sample rate to use, in Hz. Sensible\\
+                        &         values are 11025, 22050 and 44100.\\
         alsa\_port      &string   Port to use for output when using the\\
                         &         ALSA music driver.\\
         music\_volume   &number   The music volume setting (0-255)\\

sound/mixer.cpp

@@ -21 +21 @@
  */
 
 #include "stdafx.h"
+#include "common/config-manager.h"
 #include "common/file.h"
 #include "common/util.h"
 
@@ -111 +112 @@
         _premixProc = 0;
         int i = 0;
 
-        _outputRate = (uint) _syst->getOutputSampleRate();
-
-        if (_outputRate == 0)
-                error("OSystem returned invalid sample rate");
+        if (ConfMan.hasKey("output_rate"))
+                _syst->setOutputSampleRate(ConfMan.getInt("output_rate"));
 
         _globalVolume = 0;
         _musicVolume = 0;
@@ -125 +124 @@
                 _channels[i] = 0;
 
         _mixerReady = _syst->setSoundCallback(mixCallback, this);
+        _outputRate = (uint) _syst->getOutputSampleRate();
+
+        if (_outputRate == 0)
+                error("OSystem returned invalid sample rate");
+
+        debug(1, "Output sample rate: %d Hz", _outputRate);
 }
 
 SoundMixer::~SoundMixer() {