AAudioUtilities.h revision 9dca9824da74d50be02bc81f539cc77b7bde678a 
1/*
2 * Copyright 2016 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 UTILITY_AAUDIO_UTILITIES_H
18#define UTILITY_AAUDIO_UTILITIES_H
19
20#include <stdint.h>
21#include <sys/types.h>
22
23#include <utils/Errors.h>
24#include <hardware/audio.h>
25
26#include "aaudio/AAudio.h"
27
28/**
29 * Convert an AAudio result into the closest matching Android status.
30 */
31android::status_t AAudioConvert_aaudioToAndroidStatus(aaudio_result_t result);
32
33/**
34 * Convert an Android status into the closest matching AAudio result.
35 */
36aaudio_result_t AAudioConvert_androidToAAudioResult(android::status_t status);
37
38/**
39 * Convert an array of floats to an array of int16_t.
40 *
41 * @param source
42 * @param destination
43 * @param numSamples number of values in the array
44 * @param amplitude level between 0.0 and 1.0
45 */
46void AAudioConvert_floatToPcm16(const float *source,
47                                int16_t *destination,
48                                int32_t numSamples,
49                                float amplitude);
50
51/**
52 * Convert floats to int16_t and scale by a linear ramp.
53 *
54 * The ramp stops just short of reaching amplitude2 so that the next
55 * ramp can start at amplitude2 without causing a discontinuity.
56 *
57 * @param source
58 * @param destination
59 * @param numFrames
60 * @param samplesPerFrame AKA number of channels
61 * @param amplitude1 level at start of ramp, between 0.0 and 1.0
62 * @param amplitude2 level past end of ramp, between 0.0 and 1.0
63 */
64void AAudioConvert_floatToPcm16(const float *source,
65                                int16_t *destination,
66                                int32_t numFrames,
67                                int32_t samplesPerFrame,
68                                float amplitude1,
69                                float amplitude2);
70
71/**
72 * Convert int16_t array to float array ranging from -1.0 to +1.0.
73 * @param source
74 * @param destination
75 * @param numSamples
76 */
77//void AAudioConvert_pcm16ToFloat(const int16_t *source, int32_t numSamples,
78//                                float *destination);
79
80/**
81 *
82 * Convert int16_t array to float array ranging from +/- amplitude.
83 * @param source
84 * @param destination
85 * @param numSamples
86 * @param amplitude
87 */
88void AAudioConvert_pcm16ToFloat(const int16_t *source,
89                                float *destination,
90                                int32_t numSamples,
91                                float amplitude);
92
93/**
94 * Convert floats to int16_t and scale by a linear ramp.
95 *
96 * The ramp stops just short of reaching amplitude2 so that the next
97 * ramp can start at amplitude2 without causing a discontinuity.
98 *
99 * @param source
100 * @param destination
101 * @param numFrames
102 * @param samplesPerFrame AKA number of channels
103 * @param amplitude1 level at start of ramp, between 0.0 and 1.0
104 * @param amplitude2 level at end of ramp, between 0.0 and 1.0
105 */
106void AAudioConvert_pcm16ToFloat(const int16_t *source,
107                                float *destination,
108                                int32_t numFrames,
109                                int32_t samplesPerFrame,
110                                float amplitude1,
111                                float amplitude2);
112
113/**
114 * Scale floats by a linear ramp.
115 *
116 * The ramp stops just short of reaching amplitude2 so that the next
117 * ramp can start at amplitude2 without causing a discontinuity.
118 *
119 * @param source
120 * @param destination
121 * @param numFrames
122 * @param samplesPerFrame
123 * @param amplitude1
124 * @param amplitude2
125 */
126void AAudio_linearRamp(const float *source,
127                       float *destination,
128                       int32_t numFrames,
129                       int32_t samplesPerFrame,
130                       float amplitude1,
131                       float amplitude2);
132
133/**
134 * Scale int16_t's by a linear ramp.
135 *
136 * The ramp stops just short of reaching amplitude2 so that the next
137 * ramp can start at amplitude2 without causing a discontinuity.
138 *
139 * @param source
140 * @param destination
141 * @param numFrames
142 * @param samplesPerFrame
143 * @param amplitude1
144 * @param amplitude2
145 */
146void AAudio_linearRamp(const int16_t *source,
147                       int16_t *destination,
148                       int32_t numFrames,
149                       int32_t samplesPerFrame,
150                       float amplitude1,
151                       float amplitude2);
152
153/**
154 * Calculate the number of bytes and prevent numeric overflow.
155 * @param numFrames frame count
156 * @param bytesPerFrame size of a frame in bytes
157 * @param sizeInBytes total size in bytes
158 * @return AAUDIO_OK or negative error, eg. AAUDIO_ERROR_OUT_OF_RANGE
159 */
160int32_t AAudioConvert_framesToBytes(int32_t numFrames,
161                                            int32_t bytesPerFrame,
162                                            int32_t *sizeInBytes);
163
164audio_format_t AAudioConvert_aaudioToAndroidDataFormat(aaudio_format_t aaudio_format);
165
166aaudio_format_t AAudioConvert_androidToAAudioDataFormat(audio_format_t format);
167
168/**
169 * @return the size of a sample of the given format in bytes or AAUDIO_ERROR_ILLEGAL_ARGUMENT
170 */
171int32_t AAudioConvert_formatToSizeInBytes(aaudio_format_t format);
172
173
174// Note that this code may be replaced by Settings or by some other system configuration tool.
175
176enum : int32_t {
177    // Related feature is disabled
178    AAUDIO_USE_NEVER = 0,
179    // If related feature works then use it. Otherwise fall back to something else.
180    AAUDIO_USE_AUTO = 1,
181    // Related feature must be used. If not available then fail.
182    AAUDIO_USE_ALWAYS = 2
183};
184
185#define AAUDIO_PROP_MMAP_ENABLED           "aaudio.mmap_enabled"
186
187/**
188 * Read system property.
189 * @return AAUDIO_USE_NEVER or AAUDIO_USE_AUTO or AAUDIO_USE_ALWAYS
190 */
191int32_t AAudioProperty_getMMapEnabled();
192
193#define AAUDIO_PROP_MMAP_EXCLUSIVE_ENABLED "aaudio.mmap_exclusive_enabled"
194
195/**
196 * Read system property.
197 * @return AAUDIO_USE_NEVER or AAUDIO_USE_AUTO or AAUDIO_USE_ALWAYS
198 */
199int32_t AAudioProperty_getMMapExclusiveEnabled();
200
201#define AAUDIO_PROP_MIXER_BURSTS           "aaudio.mixer_bursts"
202
203/**
204 * Read system property.
205 * @return number of bursts per mixer cycle
206 */
207int32_t AAudioProperty_getMixerBursts();
208
209#define AAUDIO_PROP_HW_BURST_MIN_USEC      "aaudio.hw_burst_min_usec"
210
211/**
212 * Read system property.
213 * This is handy in case the DMA is bursting too quickly for the CPU to keep up.
214 * For example, there may be a DMA burst every 100 usec but you only
215 * want to feed the MMAP buffer every 2000 usec.
216 *
217 * This will affect the framesPerBurst for an MMAP stream.
218 *
219 * @return minimum number of microseconds for a MMAP HW burst
220 */
221int32_t AAudioProperty_getHardwareBurstMinMicros();
222
223#endif //UTILITY_AAUDIO_UTILITIES_H
224