Adds support for multi-channel output audio for the low-latency path in Windows.

media/audio/win/audio_low_latency_output_win.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // Implementation of AudioOutputStream for Windows using Windows Core Audio
 // WASAPI for low latency rendering.
 //
 // Overview of operation and performance:
 //
 // - An object of WASAPIAudioOutputStream is created by the AudioManager
@@ skipping 54 matching lines @@
 // - It is recommended to first acquire the native sample rate of the default
 //   input device and then use the same rate when creating this object. Use
 //   WASAPIAudioOutputStream::HardwareSampleRate() to retrieve the sample rate.
 // - Calling Close() also leads to self destruction.
 // - Stream switching is not supported if the user shifts the audio device
 //   after Open() is called but before Start() has been called.
 // - Stream switching can fail if streaming starts on one device with a
 //   supported format (X) and the new default device - to which we would like
 //   to switch - uses another format (Y), which is not supported given the
 //   configured audio parameters.
+// - The audio device is always opened with the same number of channels as
+//   it supports natively (see HardwareChannelCount()). Channel up-mixing will
+//   take place if the |params| parameter in the constructor contains a lower
+//   number of channels than the number of native channels. As an example: if
+//   the clients provides a channel count of 2 and a 7.1 headset is detected,
+//   then 2 -> 7.1 up-mixing will take place for each OnMoreData() callback.
+// - Channel down-mixing is currently not supported. It is possible to create
+//   an instance for this case but calls to Open() will fail.
+// - Support for 8-bit audio has not yet been verified and tested.
+// - Open() will fail if channel up-mixing is done for 8-bit audio.
+// - Supported channel up-mixing cases (client config -> endpoint config):
+//    o 1 -> 2
+//    o 1 -> 7.1
+//    o 2 -> 5.1
+//    o 2 -> 7.1
 //
 // Core Audio API details:
 //
 // - CoInitializeEx() is called on the creating thread and on the internal
 //   capture thread. Each thread's concurrency model and apartment is set
 //   to multi-threaded (MTA). CHECK() is called to ensure that we crash if
 //   CoInitializeEx(MTA) fails.
 // - The public API methods (Open(), Start(), Stop() and Close()) must be
 //   called on constructing thread. The reason is that we want to ensure that
 //   the COM environment is the same for all API implementations.
@@ skipping 23 matching lines @@
 // - Audio rendering is performed on the audio render thread, owned by this
 //   class, and the AudioSourceCallback::OnMoreData() method will be called
 //   from this thread. Stream switching also takes place on the audio-render
 //   thread.
 // - All callback methods from the IMMNotificationClient interface will be
 //   called on a Windows-internal MMDevice thread.
 //
 // Experimental exclusive mode:
 //
 // - It is possible to open up a stream in exclusive mode by using the
-//   --enable-exclusive-mode command line flag.
+//   --enable-exclusive-audio command line flag.
 // - The internal buffering scheme is less flexible for exclusive streams.
 //   Hence, some manual tuning will be required before deciding what frame
 //   size to use. See the WinAudioOutputTest unit test for more details.
 // - If an application opens a stream in exclusive mode, the application has
 //   exclusive use of the audio endpoint device that plays the stream.
 // - Exclusive-mode should only be utilized when the lowest possible latency
 //   is important.
 // - In exclusive mode, the client can choose to open the stream in any audio
 //   format that the endpoint device supports, i.e. not limited to the device's
 //   current (default) configuration.
 // - Initial measurements on Windows 7 (HP Z600 workstation) have shown that
 //   the lowest possible latencies we can achieve on this machine are:
 //     o ~3.3333ms @ 48kHz <=> 160 audio frames per buffer.
 //     o ~3.6281ms @ 44.1kHz <=> 160 audio frames per buffer.
 // - See http://msdn.microsoft.com/en-us/library/windows/desktop/dd370844(v=vs.85).aspx
 //   for more details.
 
 #ifndef MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_
 #define MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_
 
 #include <Audioclient.h>
 #include <audiopolicy.h>
 #include <MMDeviceAPI.h>
 
 #include <string>
 
 #include "base/compiler_specific.h"
+#include "base/gtest_prod_util.h"
 #include "base/threading/platform_thread.h"
 #include "base/threading/simple_thread.h"
 #include "base/win/scoped_co_mem.h"
 #include "base/win/scoped_com_initializer.h"
 #include "base/win/scoped_comptr.h"
 #include "base/win/scoped_handle.h"
 #include "media/audio/audio_io.h"
 #include "media/audio/audio_parameters.h"
 #include "media/base/media_export.h"
 
@@ skipping 19 matching lines @@
   virtual ~WASAPIAudioOutputStream();
 
   // Implementation of AudioOutputStream.
   virtual bool Open() OVERRIDE;
   virtual void Start(AudioSourceCallback* callback) OVERRIDE;
   virtual void Stop() OVERRIDE;
   virtual void Close() OVERRIDE;
   virtual void SetVolume(double volume) OVERRIDE;
   virtual void GetVolume(double* volume) OVERRIDE;
 
-  // Retrieves the stream format that the audio engine uses for its internal
-  // processing/mixing of shared-mode streams.
-  // This method should not be used in combination with exclusive-mode streams.
+  // Retrieves the number of channels the audio engine uses for its internal
+  // processing/mixing of shared-mode streams for the default endpoint device.
+  static int HardwareChannelCount();
+
+  // Retrieves the channel layout the audio engine uses for its internal
+  // processing/mixing of shared-mode streams for the default endpoint device.
+  // Note that we convert an internal channel layout mask (see ChannelMask())
+  // into a Chrome-specific channel layout enumerator in this method, hence
+  // the match might not be perfect.
+  static ChannelLayout HardwareChannelLayout();
+
+  // Retrieves the sample rate the audio engine uses for its internal
+  // processing/mixing of shared-mode streams for the default endpoint device.
   static int HardwareSampleRate(ERole device_role);
 
   // Returns AUDCLNT_SHAREMODE_EXCLUSIVE if --enable-exclusive-mode is used
   // as command-line flag and AUDCLNT_SHAREMODE_SHARED otherwise (default).
   static AUDCLNT_SHAREMODE GetShareMode();
 
   bool started() const { return started_; }
 
  private:
+  FRIEND_TEST_ALL_PREFIXES(WASAPIAudioOutputStreamTest, HardwareChannelCount);
+
   // Implementation of IUnknown (trivial in this case). See
   // msdn.microsoft.com/en-us/library/windows/desktop/dd371403(v=vs.85).aspx
   // for details regarding why proper implementations of AddRef(), Release()
   // and QueryInterface() are not needed here.
   STDMETHOD_(ULONG, AddRef)();
   STDMETHOD_(ULONG, Release)();
   STDMETHOD(QueryInterface)(REFIID iid, void** object);
 
   // Implementation of the abstract interface IMMNotificationClient.
   // Provides notifications when an audio endpoint device is added or removed,
@@ skipping 41 matching lines @@
   // Converts unique endpoint ID to user-friendly device name.
   std::string GetDeviceName(LPCWSTR device_id) const;
 
   // Called on the audio render thread when the current audio stream must
   // be re-initialized because the default audio device has changed. This
   // method: stops the current renderer, releases and re-creates all WASAPI
   // interfaces, creates a new IMMDevice and re-starts rendering using the
   // new default audio device.
   bool RestartRenderingUsingNewDefaultDevice();
 
-  AUDCLNT_SHAREMODE share_mode() const { return share_mode_; }
+  // Returns the number of channels the audio engine uses for its internal
+  // processing/mixing of shared-mode streams for the default endpoint device.
+  int endpoint_channel_count() { return format_.Format.nChannels; }
+
+  // The ratio between the the number of native audio channels used by the
+  // audio device and the number of audio channels from the client.
+  // TODO(henrika): using int as indicator of the required type of channel
+  // mixing is not a perfect solution. E.g. 2->2.1 will result in a ratio of
+  // 2/3 which is truncated to 1 and 1 means "no mixing is required".
+  int channel_factor() const {
+    return (format_.Format.nChannels / client_channel_count_);
+  }
 
   // Initializes the COM library for use by the calling thread and sets the
   // thread's concurrency model to multi-threaded.
   base::win::ScopedCOMInitializer com_init_;
 
   // Contains the thread ID of the creating thread.
   base::PlatformThreadId creating_thread_id_;
 
   // Our creator, the audio manager needs to be notified when we close.
   AudioManagerWin* manager_;
 
   // Rendering is driven by this thread (which has no message loop).
   // All OnMoreData() callbacks will be called from this thread.
   base::DelegateSimpleThread* render_thread_;
 
   // Contains the desired audio format which is set up at construction.
-  WAVEFORMATEX format_;
+  // Extended PCM waveform format structure based on WAVEFORMATEXTENSIBLE.
+  // Use this for multiple channel and hi-resolution PCM data.
+  WAVEFORMATPCMEX format_;
 
   // Copy of the audio format which we know the audio engine supports.
   // It is recommended to ensure that the sample rate in |format_| is identical
   // to the sample rate in |audio_engine_mix_format_|.
-  base::win::ScopedCoMem<WAVEFORMATEX> audio_engine_mix_format_;
+  base::win::ScopedCoMem<WAVEFORMATPCMEX> audio_engine_mix_format_;
 
   bool opened_;
   bool started_;
 
   // Set to true as soon as a new default device is detected, and cleared when
   // the streaming has switched from using the old device to the new device.
   // All additional device detections during an active state are ignored to
   // ensure that the ongoing switch can finalize without disruptions.
   bool restart_rendering_mode_;
 
@@ skipping 18 matching lines @@
   size_t endpoint_buffer_size_frames_;
 
   // Defines the role that the system has assigned to an audio endpoint device.
   ERole device_role_;
 
   // The sharing mode for the connection.
   // Valid values are AUDCLNT_SHAREMODE_SHARED and AUDCLNT_SHAREMODE_EXCLUSIVE
   // where AUDCLNT_SHAREMODE_SHARED is the default.
   AUDCLNT_SHAREMODE share_mode_;
 
+  // The channel count set by the client in |params| which is provided to the
+  // constructor. The client must feed the AudioSourceCallback::OnMoreData()
+  // callback with PCM-data that contains this number of channels.
+  int client_channel_count_;
+
   // Counts the number of audio frames written to the endpoint buffer.
   UINT64 num_written_frames_;
 
   // Pointer to the client that will deliver audio samples to be played out.
   AudioSourceCallback* source_;
 
   // An IMMDeviceEnumerator interface which represents a device enumerator.
   base::win::ScopedComPtr<IMMDeviceEnumerator> device_enumerator_;
 
   // An IMMDevice interface which represents an audio endpoint device.
@@ skipping 16 matching lines @@
 
   // This event will be signaled when stream switching shall take place.
   base::win::ScopedHandle stream_switch_event_;
 
   DISALLOW_COPY_AND_ASSIGN(WASAPIAudioOutputStream);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_