audio: Offer a hint for libsamplerate quality/speed tradeoff.

This defaults to the internal SDL resampler, since that's the likely default
without a system-wide install of libsamplerate, but those that need more can
tweak this.

include/SDL_hints.h

@@ -775,6 +775,42 @@ extern "C" {
  */
 #define SDL_HINT_OPENGL_ES_DRIVER   "SDL_OPENGL_ES_DRIVER"
 
+/**
+ *  \brief  A variable controlling speed/quality tradeoff of audio resampling.
+ *
+ *  If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
+ *  to handle audio resampling. There are different resampling modes available
+ *  that produce different levels of quality, possibly using more CPU.
+ *
+ *  If this hint isn't specified to a valid setting, or libsamplerate isn't
+ *  available, SDL will act as if this hint was set to "fast".
+ *
+ *  Note that this is currently only applicable to resampling audio that is
+ *  being written to a device for playback or audio being read from a device
+ *  for capture. SDL_AudioCVT always uses the "fast" resampler (although this
+ *  might change for SDL 2.1).
+ *
+ *  Most things can probably live with the "fast" resampler, but if quality
+ *  is important or you can spare some CPU cycles, the other options are
+ *  worth exploring!
+ *
+ *  libsamplerate's interpolators, that these hints map to, are explained here:
+ *     http://www.mega-nerd.com/SRC/api_misc.html#Converters
+ *
+ *  This hint is only checked at audio subsystem init time and changes to it
+ *  at other times are ignored.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "default"  - Use SDL's internal, resampler. (Default when not set. low quality, fast.)
+ *    "linear" - Use libsamplerate's Linear interpolator (low quality, fast).
+ *    "zero_order_hold" - Use libsamplerate's Zero Order Hold interpolator (low quality, fast).
+ *    "sinc_fastest" - Use libsamplerate's fastest (lowest quality) sinc interpolator.
+ *    "sinc_medium" - Use libsamplerate's medium quality sinc interpolator.
+ *    "sinc_best" - Use libsamplerate's best quality sinc interpolator.
+ */
+#define SDL_HINT_AUDIO_RESAMPLER_MODE   "SDL_AUDIO_RESAMPLER_MODE"
+
 /**
  *  \brief  An enumeration of hint priorities
  */