Adding experimental exclusive-mode streaming to WASAPIAudioOutputStream

media/audio/win/audio_low_latency_output_win.h

Index: media/audio/win/audio_low_latency_output_win.h
diff --git a/media/audio/win/audio_low_latency_output_win.h b/media/audio/win/audio_low_latency_output_win.h
index 67a5d6c5f0a2c496c6e8828815110ac06f3ad202..c19177897bd5e8bfdc554a2d5a3820ece280e66e 100644
--- a/media/audio/win/audio_low_latency_output_win.h
+++ b/media/audio/win/audio_low_latency_output_win.h
@@ -112,6 +112,30 @@
 // - All callback methods from the IMMNotificationClient interface will be
 //   called on a Windows-internal MMDevice thread.
 //
+// Experimental exclusive mode (DO NOT USE IN PRODUCTION CODE):
+//
+// - It is possible to open up a stream in exclusive mode by using the
+//   |share_mode| flag in the constructor. To try it out, set this flag to
+//   AUDCLNT_SHAREMODE_EXCLUSIVE.
+// - The internal buffering scheme is less flexible for exclusive-mode 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 access to an audio device can block crucial system sounds,
+//   prevent interoperability with other applications, and otherwise degrade
+//   the user experience.
+// - 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.
+// - Initial measurements on Windows 7 have shown that the lowest possible
+//   latencies we can achieve are:
+//     o ~3.3333ms @ 48kHz <=> 160 audio frames per buffer.
+//     o ~3.6281ms @ 44.1kHz <=> 160 audio frames per buffer.
+// - See 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_
 
@@ -146,9 +170,13 @@ class MEDIA_EXPORT WASAPIAudioOutputStream
  public:
   // The ctor takes all the usual parameters, plus |manager| which is the
   // the audio manager who is creating this object.
+  // Note that, |share_mode| shall be set to AUDCLNT_SHAREMODE_SHARED in
+  // production code. AUDCLNT_SHAREMODE_EXCLUSIVE is also supported but must
+  // only be used behind a command-line flag.
   WASAPIAudioOutputStream(AudioManagerWin* manager,
                           const AudioParameters& params,
-                          ERole device_role);
+                          ERole device_role,
+                          AUDCLNT_SHAREMODE share_mode);
   // The dtor is typically called by the AudioManager only and it is usually
   // triggered by calling AudioOutputStream::Close().
   virtual ~WASAPIAudioOutputStream();
@@ -163,6 +191,7 @@ class MEDIA_EXPORT WASAPIAudioOutputStream
 
   // 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.
   static int HardwareSampleRate(ERole device_role);
 
   bool started() const { return started_; }
@@ -206,7 +235,7 @@ class MEDIA_EXPORT WASAPIAudioOutputStream
   void HandleError(HRESULT err);
 
   // The Open() method is divided into these sub methods.
-  HRESULT SetRenderDevice(ERole device_role);
+  HRESULT SetRenderDevice();
   HRESULT ActivateRenderDevice();
   HRESULT GetAudioEngineStreamFormat();
   bool DesiredFormatIsSupported();
@@ -222,6 +251,8 @@ class MEDIA_EXPORT WASAPIAudioOutputStream
   // new default audio device.
   bool RestartRenderingUsingNewDefaultDevice();
 
+  AUDCLNT_SHAREMODE share_mode() const { return share_mode_; }
+
   // 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_;
@@ -276,6 +307,13 @@ class MEDIA_EXPORT WASAPIAudioOutputStream
   // 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.
+  // This member is not modified (only read) after construction hence we don't
+  // have to pro
+  AUDCLNT_SHAREMODE share_mode_;
+
   // Counts the number of audio frames written to the endpoint buffer.
   UINT64 num_written_frames_;