Simplified AudioOutputStream interface.

media/audio/audio_io.h

 // Copyright (c) 2010 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.
 
 #ifndef MEDIA_AUDIO_AUDIO_IO_H_
 #define MEDIA_AUDIO_AUDIO_IO_H_
 
 #include "base/basictypes.h"
 #include "media/audio/audio_buffers_state.h"
 
@@ skipping 22 matching lines @@
 // - Extra features if a specific hardware is installed (EAX, X-fi)
 //
 // The primary client of this facility is audio coming from several tabs.
 // Specifically for this case we avoid supporting complex formats such as MP3
 // or WMA. Complex format decoding should be done by the renderers.
 
 
 // Models an audio stream that gets rendered to the audio hardware output.
 // Because we support more audio streams than physically available channels
 // a given AudioOutputStream might or might not talk directly to hardware.
+// An audio stream allocates several buffers for audio data and calls
+// AudioSourceCallback::OnModeData() periodically to fill these buffers,
+// as the data is written to the audio device. Size of each packet is determined
+// by |samples_per_packet| specified in AudioParameters  when the stream is
+// created.
 class AudioOutputStream {
  public:
   // Audio sources must implement AudioSourceCallback. This interface will be
   // called in a random thread which very likely is a high priority thread. Do
   // not rely on using this thread TLS or make calls that alter the thread
   // itself such as creating Windows or initializing COM.
   class AudioSourceCallback {
    public:
     virtual ~AudioSourceCallback() {}
 
     // Provide more data by filling |dest| up to |max_size| bytes. The provided
-    // buffer size is usually what is specified in Open(). The source
-    // will return the number of bytes it filled. The expected structure of
-    // |dest| is platform and format specific.
-    // |pending_bytes| is the number of bytes will be played before the
-    // requested data is played.
+    // buffer size is determined by the |samples_per_packet| specified in
+    // AudioParameters when the stream is created. The source will return
+    // the number of bytes it filled. The expected structure of |dest| is
+    // platform and format specific.
+    // |buffers_state| contains current state of the buffers, and can be used
+    // by the source to calculate delay.
     virtual uint32 OnMoreData(
         AudioOutputStream* stream, uint8* dest, uint32 max_size,
         AudioBuffersState buffers_state) = 0;
 
-    // The stream is done with this callback. After this call the audio source
-    // can go away or be destroyed.
-    virtual void OnClose(AudioOutputStream* stream) = 0;
-
     // There was an error while playing a buffer. Audio source cannot be
     // destroyed yet. No direct action needed by the AudioStream, but it is
     // a good place to stop accumulating sound data since is is likely that
     // playback will not continue. |code| is an error code that is platform
     // specific.
     virtual void OnError(AudioOutputStream* stream, int code) = 0;
   };
 
-  // Open the stream. |packet_size| is the requested buffer allocation which
-  // the audio source thinks it can usually fill without blocking. Internally
-  // two or three buffers of |packet_size| size are created, one will be
-  // locked for playback and one will be ready to be filled in the call to
-  // AudioSourceCallback::OnMoreData().
-  // The number of buffers is controlled by AUDIO_PCM_LOW_LATENCY. See more
-  // information below.
-  //
-  // TODO(ajwong): Streams are not reusable, so try to move packet_size into the
-  // constructor.
-  virtual bool Open(uint32 packet_size) = 0;
+  // Open the stream. false is returned if the stream cannot be opened.
+  virtual bool Open() = 0;
 
   // Starts playing audio and generating AudioSourceCallback::OnMoreData().
   // Since implementor of AudioOutputStream may have internal buffers, right
   // after calling this method initial buffers are fetched.
   //
   // The output stream does not take ownership of this callback.
   virtual void Start(AudioSourceCallback* callback) = 0;
 
   // Stops playing audio. Effect might not be instantaneous as the hardware
   // might have locked audio data that is processing.
@@ skipping 53 matching lines @@
 
   // Close the stream. This also generates AudioInputCallback::OnClose(). This
   // should be the last call made on this object.
   virtual void Close() = 0;
 
  protected:
   virtual ~AudioInputStream() {}
 };
 
 #endif  // MEDIA_AUDIO_AUDIO_IO_H_