cc: Added inline to Tile::IsReadyToDraw
[chromium-blink-merge.git] / media / audio / audio_io.h
blob473af0d512fe9112a1e0cb4c016924a5b5a6a7ef
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef MEDIA_AUDIO_AUDIO_IO_H_
6 #define MEDIA_AUDIO_AUDIO_IO_H_
8 #include "base/basictypes.h"
9 #include "media/audio/audio_buffers_state.h"
10 #include "media/base/audio_bus.h"
12 // Low-level audio output support. To make sound there are 3 objects involved:
13 // - AudioSource : produces audio samples on a pull model. Implements
14 // the AudioSourceCallback interface.
15 // - AudioOutputStream : uses the AudioSource to render audio on a given
16 // channel, format and sample frequency configuration. Data from the
17 // AudioSource is delivered in a 'pull' model.
18 // - AudioManager : factory for the AudioOutputStream objects, manager
19 // of the hardware resources and mixer control.
21 // The number and configuration of AudioOutputStream does not need to match the
22 // physically available hardware resources. For example you can have:
24 // MonoPCMSource1 --> MonoPCMStream1 --> | | --> audio left channel
25 // StereoPCMSource -> StereoPCMStream -> | mixer |
26 // MonoPCMSource2 --> MonoPCMStream2 --> | | --> audio right channel
28 // This facility's objective is mix and render audio with low overhead using
29 // the OS basic audio support, abstracting as much as possible the
30 // idiosyncrasies of each platform. Non-goals:
31 // - Positional, 3d audio
32 // - Dependence on non-default libraries such as DirectX 9, 10, XAudio
33 // - Digital signal processing or effects
34 // - Extra features if a specific hardware is installed (EAX, X-fi)
36 // The primary client of this facility is audio coming from several tabs.
37 // Specifically for this case we avoid supporting complex formats such as MP3
38 // or WMA. Complex format decoding should be done by the renderers.
41 // Models an audio stream that gets rendered to the audio hardware output.
42 // Because we support more audio streams than physically available channels
43 // a given AudioOutputStream might or might not talk directly to hardware.
44 // An audio stream allocates several buffers for audio data and calls
45 // AudioSourceCallback::OnMoreData() periodically to fill these buffers,
46 // as the data is written to the audio device. Size of each packet is determined
47 // by |samples_per_packet| specified in AudioParameters when the stream is
48 // created.
50 namespace media {
52 class MEDIA_EXPORT AudioOutputStream {
53 public:
54 // Audio sources must implement AudioSourceCallback. This interface will be
55 // called in a random thread which very likely is a high priority thread. Do
56 // not rely on using this thread TLS or make calls that alter the thread
57 // itself such as creating Windows or initializing COM.
58 class MEDIA_EXPORT AudioSourceCallback {
59 public:
60 // Provide more data by fully filling |dest|. The source will return
61 // the number of frames it filled. |buffers_state| contains current state
62 // of the buffers, and can be used by the source to calculate delay.
63 virtual int OnMoreData(AudioBus* dest,
64 AudioBuffersState buffers_state) = 0;
66 virtual int OnMoreIOData(AudioBus* source,
67 AudioBus* dest,
68 AudioBuffersState buffers_state) = 0;
70 // There was an error while playing a buffer. Audio source cannot be
71 // destroyed yet. No direct action needed by the AudioStream, but it is
72 // a good place to stop accumulating sound data since is is likely that
73 // playback will not continue.
74 virtual void OnError(AudioOutputStream* stream) = 0;
76 protected:
77 virtual ~AudioSourceCallback() {}
80 virtual ~AudioOutputStream() {}
82 // Open the stream. false is returned if the stream cannot be opened. Open()
83 // must always be followed by a call to Close() even if Open() fails.
84 virtual bool Open() = 0;
86 // Starts playing audio and generating AudioSourceCallback::OnMoreData().
87 // Since implementor of AudioOutputStream may have internal buffers, right
88 // after calling this method initial buffers are fetched.
90 // The output stream does not take ownership of this callback.
91 virtual void Start(AudioSourceCallback* callback) = 0;
93 // Stops playing audio. Effect might not be instantaneous as the hardware
94 // might have locked audio data that is processing.
95 virtual void Stop() = 0;
97 // Sets the relative volume, with range [0.0, 1.0] inclusive.
98 virtual void SetVolume(double volume) = 0;
100 // Gets the relative volume, with range [0.0, 1.0] inclusive.
101 virtual void GetVolume(double* volume) = 0;
103 // Close the stream. This also generates AudioSourceCallback::OnClose().
104 // After calling this method, the object should not be used anymore.
105 virtual void Close() = 0;
108 // Models an audio sink receiving recorded audio from the audio driver.
109 class MEDIA_EXPORT AudioInputStream {
110 public:
111 class MEDIA_EXPORT AudioInputCallback {
112 public:
113 // Called by the audio recorder when a full packet of audio data is
114 // available. This is called from a special audio thread and the
115 // implementation should return as soon as possible.
116 virtual void OnData(AudioInputStream* stream, const uint8* src,
117 uint32 size, uint32 hardware_delay_bytes,
118 double volume) = 0;
120 // The stream is done with this callback, the last call received by this
121 // audio sink.
122 virtual void OnClose(AudioInputStream* stream) = 0;
124 // There was an error while recording audio. The audio sink cannot be
125 // destroyed yet. No direct action needed by the AudioInputStream, but it
126 // is a good place to stop accumulating sound data since is is likely that
127 // recording will not continue.
128 virtual void OnError(AudioInputStream* stream) = 0;
130 protected:
131 virtual ~AudioInputCallback() {}
134 virtual ~AudioInputStream() {}
136 // Open the stream and prepares it for recording. Call Start() to actually
137 // begin recording.
138 virtual bool Open() = 0;
140 // Starts recording audio and generating AudioInputCallback::OnData().
141 // The input stream does not take ownership of this callback.
142 virtual void Start(AudioInputCallback* callback) = 0;
144 // Stops recording audio. Effect might not be instantaneous as there could be
145 // pending audio callbacks in the queue which will be issued first before
146 // recording stops.
147 virtual void Stop() = 0;
149 // Close the stream. This also generates AudioInputCallback::OnClose(). This
150 // should be the last call made on this object.
151 virtual void Close() = 0;
153 // Returns the maximum microphone analog volume or 0.0 if device does not
154 // have volume control.
155 virtual double GetMaxVolume() = 0;
157 // Sets the microphone analog volume, with range [0, max_volume] inclusive.
158 virtual void SetVolume(double volume) = 0;
160 // Returns the microphone analog volume, with range [0, max_volume] inclusive.
161 virtual double GetVolume() = 0;
163 // Sets the Automatic Gain Control (AGC) state.
164 virtual void SetAutomaticGainControl(bool enabled) = 0;
166 // Returns the Automatic Gain Control (AGC) state.
167 virtual bool GetAutomaticGainControl() = 0;
170 } // namespace media
172 #endif // MEDIA_AUDIO_AUDIO_IO_H_