Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8f62489d authored by Phil Burk's avatar Phil Burk
Browse files

aaudio: make openStream behavior more specific 



Change API specification to state that if sampleRate, channelCount
or dataFormat are specified, then the open stream will use those values.

This change does not break the original API, which stated that the actual
values might or might not match the requested values.

The documented API now matches the actual code behavior.

Bug: 38236303
Test: unit test, test_open_params.cpp
Change-Id: Ida15546f0ee2a8cc888158f564492363a700f9ea
Signed-off-by: default avatarPhil Burk <philburk@google.com>
parent 8dd7fedb

media/libaaudio/include/aaudio/AAudio.h

+17 −14
Original line number Original line Diff line number Diff line
@@ -209,14 +209,13 @@ AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 
/**

/**

 * Request a sample rate in Hertz.

 * Request a sample rate in Hertz.

 *

 *

 * The stream may be opened with a different sample rate.

 * So the application should query for the actual rate after the stream is opened.

 *

 * Technically, this should be called the "frame rate" or "frames per second",

 * because it refers to the number of complete frames transferred per second.

 * But it is traditionally called "sample rate". So we use that term.

 *

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * An optimal value will then be chosen when the stream is opened.

 * After opening a stream with an unspecified value, the application must

 * query for the actual value, which may vary by device.

 *

 * If an exact value is specified then an opened stream will use that value.

 * If a stream cannot be opened with the specified value then the open will fail.

 *

 *

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz.

 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz.
@@ -227,12 +226,13 @@ AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 
/**

/**

 * Request a number of channels for the stream.

 * Request a number of channels for the stream.

 *

 *

 * The stream may be opened with a different value.

 * So the application should query for the actual value after the stream is opened.

 *

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * An optimal value will then be chosen when the stream is opened.

 * After opening a stream with an unspecified value, the application must

 * query for the actual value, which may vary by device.

 *

 *

 * Note, this quantity is sometimes referred to as "samples per frame".

 * If an exact value is specified then an opened stream will use that value.

 * If a stream cannot be opened with the specified value then the open will fail.

 *

 *

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param channelCount Number of channels desired.

 * @param channelCount Number of channels desired.
@@ -252,12 +252,15 @@ AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* buil 
 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.

 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.

 *

 *

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

 * An optimal value will then be chosen when the stream is opened.

 * After opening a stream with an unspecified value, the application must

 * query for the actual value, which may vary by device.

 *

 *

 * The stream may be opened with a different value.

 * If an exact value is specified then an opened stream will use that value.

 * So the application should query for the actual value after the stream is opened.

 * If a stream cannot be opened with the specified value then the open will fail.

 *

 *

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param builder reference provided by AAudio_createStreamBuilder()

 * @param format Most common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16.

 * @param format common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16.

 */

 */

AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder,

AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder,

                                                   aaudio_audio_format_t format);

                                                   aaudio_audio_format_t format);