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.
+  int channel_factor() const {
+    return (format_.Format.nChannels / client_channel_count_);

[scherkus (not reviewing), 2012/08/03 21:20:55]

OOC and something we can TODO for now, but do we always want integer truncation?

if nChannels (which is HardwareChannelCount()) is 3 (2.1) and
client_channel_count_ is 2, we end up with 1 and don't hit the up-mixing path 

will we do the right thing in that scenario? (only output to L+R channels?)

[henrika (OOO until Aug 14), 2012/08/04 16:42:23]

We only support the mixing modes listed in the "Overview of operation and
performance:" section. Your example will fail since it will not be detected as a
mixing case. If I changed to float, we would detect it but no support exists for
it in the mixing phase. Both these cases are bad and just removing int will not
be the optimal solution.

Given that I don't have access to hardware right now, I don't  dare to change
these parts. Will add a TODO and improve when I get back.

I have better ideas on how to detect mixing mode than a plain integer. This CL
has grown from "please make my G35 headset work with Chrome" to something larger
;-)

+  }
 
   // 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_