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..a3136a9c271eccf358b235fd642bfb0d0f5e68f6 100644
--- a/media/audio/win/audio_low_latency_output_win.h
+++ b/media/audio/win/audio_low_latency_output_win.h
@@ -112,6 +112,29 @@
 // - 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.

[scherkus (not reviewing), 2012/07/25 23:44:44]

ditch ""s on the flag

[henrika (OOO until Aug 14), 2012/07/26 08:31:11]

Done.

+// - 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 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 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_
 
@@ -163,11 +186,16 @@ 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_; }
 
  private:
+  // Returns AUDCLNT_SHAREMODE_EXCLUSIVE if "enable-exclusive-mode" is used

[scherkus (not reviewing), 2012/07/25 23:44:44]

ditch ""s and just use --enable-exclusive-mode

[henrika (OOO until Aug 14), 2012/07/26 08:31:11]

Done.

+  // as command-line flag and AUDCLNT_SHAREMODE_SHARED otherwise (default).
+  static AUDCLNT_SHAREMODE GetShareMode();
+
   // 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()
@@ -206,12 +234,20 @@ 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();
   HRESULT InitializeAudioEngine();
 
+  // Called when the device will be opened in shared mode and use the WAS

[scherkus (not reviewing), 2012/07/25 23:44:44]

WAS?

[henrika (OOO until Aug 14), 2012/07/26 08:31:11]

Modified.

+  // format.
+  HRESULT SharedModeInitialization();
+
+  // Called when the device will be opened in exclusive mode and use the
+  // application specified format.
+  HRESULT ExclusiveModeInitialization();
+
   // Converts unique endpoint ID to user-friendly device name.
   std::string GetDeviceName(LPCWSTR device_id) const;
 
@@ -222,6 +258,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 +314,11 @@ 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.
+  AUDCLNT_SHAREMODE share_mode_;
+
   // Counts the number of audio frames written to the endpoint buffer.
   UINT64 num_written_frames_;