1 /*
2  * Copyright (C) 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef CHRE_PLATFORM_PLATFORM_AUDIO_H_
18 #define CHRE_PLATFORM_PLATFORM_AUDIO_H_
19 
20 #include "chre/target_platform/platform_audio_base.h"
21 #include "chre/util/non_copyable.h"
22 #include "chre/util/time.h"
23 #include "chre_api/chre/audio.h"
24 
25 namespace chre {
26 
27 /**
28  * Defines the common interface to audio functionality.
29  */
30 class PlatformAudio : public PlatformAudioBase, public NonCopyable {
31  public:
32   /**
33    * Initializes the audio subsystem. This is invoked as part of the
34    * construction of the EventLoopManager.
35    */
36   PlatformAudio();
37 
38   /**
39    * Deinitializes the audio subsystem. This is invoked as part of the
40    * destruction of the EventLoopManager.
41    */
42   ~PlatformAudio();
43 
44   /**
45    * Initializes the platform-specific audio implementation. This is potentially
46    * called at a later stage of initialization than the constructor to allow the
47    * rest of CHRE to initialize. This permits use of deferCallback. This method
48    * must be invoked before methods of this class can be invoked.
49    */
50   void init();
51 
52   /*
53    * Allows the CHRE common code to notify the platform that the enabled state
54    * of a given audio handle has changed. This will only be invoked with true
55    * when the number of clients for the handle is greater than zero or false
56    * when it is equal to zero.
57    *
58    * @param handle The handle for which audio enabled state is changing.
59    * @param enabled true if an active request is open for this handle, false
60    *        otherwise.
61    */
62   void setHandleEnabled(uint32_t handle, bool enabled);
63 
64   /**
65    * Requests an audio data event from the platform for the provided handle. A
66    * call to this method must cancel any previous request.
67    *
68    * The event requested here may contain data from previously posted events.
69    * The concept is to allow the platform to manage its own buffers for audio
70    * data. If a request comes in for 8000 samples of data and the most recent
71    * request was for 4000 samples of data, the platform implementation may reuse
72    * the existing 4000 samples of data and append 4000 samples of new data
73    * (assuming that the arguments passed here allow that).
74    *
75    * Once a request for a given source has been made, the platform
76    * implementation must maintain a buffer of previously collected audio samples
77    * to provide when a request comes in for data in the past (up to the maximum
78    * buffer size for this source). This happens when numSamples at the source
79    * sample rate is a greater amount of time than eventDelay. This buffer can be
80    * released once cancelAudioDataEventRequest has been invoked for a given
81    * source.
82    *
83    * The event is provided to CHRE through the handleAudioDataEvent function of
84    * the AudioRequestManager.
85    *
86    * @param handle The handle for which an audio event is requested.
87    * @param numSamples The number of samples to send once the request has been
88    *        completed.
89    * @param eventDelay The amount of time that must pass before providing the
90    *        data event to CHRE.
91    */
92   bool requestAudioDataEvent(uint32_t handle, uint32_t numSamples,
93                              Nanoseconds eventDelay);
94 
95   /**
96    * Cancels the previous call to requestAudioDataEvent. No audio data is
97    * allowed to be posted to CHRE after this function has been called and before
98    * the next call to requestAudioDataEvent.
99    *
100    * @param handle The handle for which the most recent call to
101    *        requestAudioDataEvent will be cancelled.
102    */
103   void cancelAudioDataEventRequest(uint32_t handle);
104 
105   /**
106    * Releases a previously posted audio event. This will be invoked by CHRE to
107    * say that all nanoapps have processed the previously scheduled data event.
108    *
109    * @param event An audio data event that was previously provided to
110    *        CHRE as a result of a request for audio data.
111    */
112   void releaseAudioDataEvent(struct chreAudioDataEvent *event);
113 
114   /**
115    * @return the number of sources supported by the implementation. The returned
116    * value must be exactly one greater than the maximum supported audio handle.
117    */
118   size_t getSourceCount();
119 
120   /**
121    * Obtains the audio source description for a given handle.
122    *
123    * @param handle the handle for the requested audio source.
124    * @param audioSource the chreAudioSource to populate with details of the
125    *     audio source. This pointer must never be null.
126    */
127   bool getAudioSource(uint32_t handle, chreAudioSource *audioSource) const;
128 };
129 
130 }  // namespace chre
131 
132 #endif  // CHRE_PLATFORM_PLATFORM_AUDIO_H_
133