Adding experimental exclusive-mode streaming to WASAPIAudioOutputStream

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 94 matching lines @@
 //   by the AudioManager.
 // - It is a requirement to call the following methods on the same audio
 //   thread: Open(), Start(), Stop(), and Close().
 // - 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 (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_
 
 #include <Audioclient.h>
 #include <audiopolicy.h>
 #include <MMDeviceAPI.h>
 
 #include <string>
 
 #include "base/compiler_specific.h"
@@ skipping 14 matching lines @@
 // AudioOutputStream implementation using Windows Core Audio APIs.
 // The IMMNotificationClient interface enables device event notifications
 // related to changes in the status of an audio endpoint device.
 class MEDIA_EXPORT WASAPIAudioOutputStream
     : public IMMNotificationClient,
       public AudioOutputStream,
       public base::DelegateSimpleThread::Delegate {
  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();
 
   // 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.
   static int HardwareSampleRate(ERole device_role);
 
   bool started() const { return started_; }
 
  private:
   // 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)();
@@ skipping 23 matching lines @@
     return S_OK;
   }
 
   // DelegateSimpleThread::Delegate implementation.
   virtual void Run() OVERRIDE;
 
   // Issues the OnError() callback to the |sink_|.
   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();
 
   // 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_; }
+
   // 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_;
 
@@ skipping 34 matching lines @@
 
   // Size in milliseconds of each audio packet.
   float packet_size_ms_;
 
   // Length of the audio endpoint buffer.
   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.
+  // 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_;
 
   // 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_