ebiten/audio/internal/oboe/oboe_oboe_Definitions_android.h

520 lines
16 KiB
C++
Vendored

/*
* Copyright (C) 2016 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef OBOE_DEFINITIONS_H
#define OBOE_DEFINITIONS_H
#include <cstdint>
#include <type_traits>
// Oboe needs to be able to build on old NDKs so we use hard coded constants.
// The correctness of these constants is verified in "aaudio/AAudioLoader.cpp".
namespace oboe {
/**
* Represents any attribute, property or value which hasn't been specified.
*/
constexpr int32_t kUnspecified = 0;
// TODO: Investigate using std::chrono
/**
* The number of nanoseconds in a microsecond. 1,000.
*/
constexpr int64_t kNanosPerMicrosecond = 1000;
/**
* The number of nanoseconds in a millisecond. 1,000,000.
*/
constexpr int64_t kNanosPerMillisecond = kNanosPerMicrosecond * 1000;
/**
* The number of milliseconds in a second. 1,000.
*/
constexpr int64_t kMillisPerSecond = 1000;
/**
* The number of nanoseconds in a second. 1,000,000,000.
*/
constexpr int64_t kNanosPerSecond = kNanosPerMillisecond * kMillisPerSecond;
/**
* The state of the audio stream.
*/
enum class StreamState : int32_t { // aaudio_stream_state_t
Uninitialized = 0, // AAUDIO_STREAM_STATE_UNINITIALIZED,
Unknown = 1, // AAUDIO_STREAM_STATE_UNKNOWN,
Open = 2, // AAUDIO_STREAM_STATE_OPEN,
Starting = 3, // AAUDIO_STREAM_STATE_STARTING,
Started = 4, // AAUDIO_STREAM_STATE_STARTED,
Pausing = 5, // AAUDIO_STREAM_STATE_PAUSING,
Paused = 6, // AAUDIO_STREAM_STATE_PAUSED,
Flushing = 7, // AAUDIO_STREAM_STATE_FLUSHING,
Flushed = 8, // AAUDIO_STREAM_STATE_FLUSHED,
Stopping = 9, // AAUDIO_STREAM_STATE_STOPPING,
Stopped = 10, // AAUDIO_STREAM_STATE_STOPPED,
Closing = 11, // AAUDIO_STREAM_STATE_CLOSING,
Closed = 12, // AAUDIO_STREAM_STATE_CLOSED,
Disconnected = 13, // AAUDIO_STREAM_STATE_DISCONNECTED,
};
/**
* The direction of the stream.
*/
enum class Direction : int32_t { // aaudio_direction_t
/**
* Used for playback.
*/
Output = 0, // AAUDIO_DIRECTION_OUTPUT,
/**
* Used for recording.
*/
Input = 1, // AAUDIO_DIRECTION_INPUT,
};
/**
* The format of audio samples.
*/
enum class AudioFormat : int32_t { // aaudio_format_t
/**
* Invalid format.
*/
Invalid = -1, // AAUDIO_FORMAT_INVALID,
/**
* Unspecified format. Format will be decided by Oboe.
*/
Unspecified = 0, // AAUDIO_FORMAT_UNSPECIFIED,
/**
* Signed 16-bit integers.
*/
I16 = 1, // AAUDIO_FORMAT_PCM_I16,
/**
* Single precision floating points.
*/
Float = 2, // AAUDIO_FORMAT_PCM_FLOAT,
};
/**
* The result of an audio callback.
*/
enum class DataCallbackResult : int32_t { // aaudio_data_callback_result_t
// Indicates to the caller that the callbacks should continue.
Continue = 0, // AAUDIO_CALLBACK_RESULT_CONTINUE,
// Indicates to the caller that the callbacks should stop immediately.
Stop = 1, // AAUDIO_CALLBACK_RESULT_STOP,
};
/**
* The result of an operation. All except the `OK` result indicates that an error occurred.
* The `Result` can be converted into a human readable string using `convertToText`.
*/
enum class Result : int32_t { // aaudio_result_t
OK = 0, // AAUDIO_OK
ErrorBase = -900, // AAUDIO_ERROR_BASE,
ErrorDisconnected = -899, // AAUDIO_ERROR_DISCONNECTED,
ErrorIllegalArgument = -898, // AAUDIO_ERROR_ILLEGAL_ARGUMENT,
ErrorInternal = -896, // AAUDIO_ERROR_INTERNAL,
ErrorInvalidState = -895, // AAUDIO_ERROR_INVALID_STATE,
ErrorInvalidHandle = -892, // AAUDIO_ERROR_INVALID_HANDLE,
ErrorUnimplemented = -890, // AAUDIO_ERROR_UNIMPLEMENTED,
ErrorUnavailable = -889, // AAUDIO_ERROR_UNAVAILABLE,
ErrorNoFreeHandles = -888, // AAUDIO_ERROR_NO_FREE_HANDLES,
ErrorNoMemory = -887, // AAUDIO_ERROR_NO_MEMORY,
ErrorNull = -886, // AAUDIO_ERROR_NULL,
ErrorTimeout = -885, // AAUDIO_ERROR_TIMEOUT,
ErrorWouldBlock = -884, // AAUDIO_ERROR_WOULD_BLOCK,
ErrorInvalidFormat = -883, // AAUDIO_ERROR_INVALID_FORMAT,
ErrorOutOfRange = -882, // AAUDIO_ERROR_OUT_OF_RANGE,
ErrorNoService = -881, // AAUDIO_ERROR_NO_SERVICE,
ErrorInvalidRate = -880, // AAUDIO_ERROR_INVALID_RATE,
// Reserved for future AAudio result types
Reserved1,
Reserved2,
Reserved3,
Reserved4,
Reserved5,
Reserved6,
Reserved7,
Reserved8,
Reserved9,
Reserved10,
ErrorClosed,
};
/**
* The sharing mode of the audio stream.
*/
enum class SharingMode : int32_t { // aaudio_sharing_mode_t
/**
* This will be the only stream using a particular source or sink.
* This mode will provide the lowest possible latency.
* You should close EXCLUSIVE streams immediately when you are not using them.
*
* If you do not need the lowest possible latency then we recommend using Shared,
* which is the default.
*/
Exclusive = 0, // AAUDIO_SHARING_MODE_EXCLUSIVE,
/**
* Multiple applications can share the same device.
* The data from output streams will be mixed by the audio service.
* The data for input streams will be distributed by the audio service.
*
* This will have higher latency than the EXCLUSIVE mode.
*/
Shared = 1, // AAUDIO_SHARING_MODE_SHARED,
};
/**
* The performance mode of the audio stream.
*/
enum class PerformanceMode : int32_t { // aaudio_performance_mode_t
/**
* No particular performance needs. Default.
*/
None = 10, // AAUDIO_PERFORMANCE_MODE_NONE,
/**
* Extending battery life is most important.
*/
PowerSaving = 11, // AAUDIO_PERFORMANCE_MODE_POWER_SAVING,
/**
* Reducing latency is most important.
*/
LowLatency = 12, // AAUDIO_PERFORMANCE_MODE_LOW_LATENCY
};
/**
* The underlying audio API used by the audio stream.
*/
enum class AudioApi : int32_t {
/**
* Try to use AAudio. If not available then use OpenSL ES.
*/
Unspecified = kUnspecified,
/**
* Use OpenSL ES.
*/
OpenSLES,
/**
* Try to use AAudio. Fail if unavailable.
*/
AAudio
};
/**
* Specifies the quality of the sample rate conversion performed by Oboe.
* Higher quality will require more CPU load.
* Higher quality conversion will probably be implemented using a sinc based resampler.
*/
enum class SampleRateConversionQuality : int32_t {
/**
* No conversion by Oboe. Underlying APIs may still do conversion.
*/
None,
/**
* Fastest conversion but may not sound great.
* This may be implemented using bilinear interpolation.
*/
Fastest,
Low,
Medium,
High,
/**
* Highest quality conversion, which may be expensive in terms of CPU.
*/
Best,
};
/**
* The Usage attribute expresses *why* you are playing a sound, what is this sound used for.
* This information is used by certain platforms or routing policies
* to make more refined volume or routing decisions.
*
* Note that these match the equivalent values in AudioAttributes in the Android Java API.
*
* This attribute only has an effect on Android API 28+.
*/
enum class Usage : int32_t { // aaudio_usage_t
/**
* Use this for streaming media, music performance, video, podcasts, etcetera.
*/
Media = 1, // AAUDIO_USAGE_MEDIA
/**
* Use this for voice over IP, telephony, etcetera.
*/
VoiceCommunication = 2, // AAUDIO_USAGE_VOICE_COMMUNICATION
/**
* Use this for sounds associated with telephony such as busy tones, DTMF, etcetera.
*/
VoiceCommunicationSignalling = 3, // AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING
/**
* Use this to demand the users attention.
*/
Alarm = 4, // AAUDIO_USAGE_ALARM
/**
* Use this for notifying the user when a message has arrived or some
* other background event has occured.
*/
Notification = 5, // AAUDIO_USAGE_NOTIFICATION
/**
* Use this when the phone rings.
*/
NotificationRingtone = 6, // AAUDIO_USAGE_NOTIFICATION_RINGTONE
/**
* Use this to attract the users attention when, for example, the battery is low.
*/
NotificationEvent = 10, // AAUDIO_USAGE_NOTIFICATION_EVENT
/**
* Use this for screen readers, etcetera.
*/
AssistanceAccessibility = 11, // AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY
/**
* Use this for driving or navigation directions.
*/
AssistanceNavigationGuidance = 12, // AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE
/**
* Use this for user interface sounds, beeps, etcetera.
*/
AssistanceSonification = 13, // AAUDIO_USAGE_ASSISTANCE_SONIFICATION
/**
* Use this for game audio and sound effects.
*/
Game = 14, // AAUDIO_USAGE_GAME
/**
* Use this for audio responses to user queries, audio instructions or help utterances.
*/
Assistant = 16, // AAUDIO_USAGE_ASSISTANT
};
/**
* The ContentType attribute describes *what* you are playing.
* It expresses the general category of the content. This information is optional.
* But in case it is known (for instance {@link Movie} for a
* movie streaming service or {@link Speech} for
* an audio book application) this information might be used by the audio framework to
* enforce audio focus.
*
* Note that these match the equivalent values in AudioAttributes in the Android Java API.
*
* This attribute only has an effect on Android API 28+.
*/
enum ContentType : int32_t { // aaudio_content_type_t
/**
* Use this for spoken voice, audio books, etcetera.
*/
Speech = 1, // AAUDIO_CONTENT_TYPE_SPEECH
/**
* Use this for pre-recorded or live music.
*/
Music = 2, // AAUDIO_CONTENT_TYPE_MUSIC
/**
* Use this for a movie or video soundtrack.
*/
Movie = 3, // AAUDIO_CONTENT_TYPE_MOVIE
/**
* Use this for sound is designed to accompany a user action,
* such as a click or beep sound made when the user presses a button.
*/
Sonification = 4, // AAUDIO_CONTENT_TYPE_SONIFICATION
};
/**
* Defines the audio source.
* An audio source defines both a default physical source of audio signal, and a recording
* configuration.
*
* Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API.
*
* This attribute only has an effect on Android API 28+.
*/
enum InputPreset : int32_t { // aaudio_input_preset_t
/**
* Use this preset when other presets do not apply.
*/
Generic = 1, // AAUDIO_INPUT_PRESET_GENERIC
/**
* Use this preset when recording video.
*/
Camcorder = 5, // AAUDIO_INPUT_PRESET_CAMCORDER
/**
* Use this preset when doing speech recognition.
*/
VoiceRecognition = 6, // AAUDIO_INPUT_PRESET_VOICE_RECOGNITION
/**
* Use this preset when doing telephony or voice messaging.
*/
VoiceCommunication = 7, // AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION
/**
* Use this preset to obtain an input with no effects.
* Note that this input will not have automatic gain control
* so the recorded volume may be very low.
*/
Unprocessed = 9, // AAUDIO_INPUT_PRESET_UNPROCESSED
/**
* Use this preset for capturing audio meant to be processed in real time
* and played back for live performance (e.g karaoke).
* The capture path will minimize latency and coupling with playback path.
*/
VoicePerformance = 10, // AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE
};
/**
* This attribute can be used to allocate a session ID to the audio stream.
*
* This attribute only has an effect on Android API 28+.
*/
enum SessionId {
/**
* Do not allocate a session ID.
* Effects cannot be used with this stream.
* Default.
*/
None = -1, // AAUDIO_SESSION_ID_NONE
/**
* Allocate a session ID that can be used to attach and control
* effects using the Java AudioEffects API.
* Note that the use of this flag may result in higher latency.
*
* Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE.
*/
Allocate = 0, // AAUDIO_SESSION_ID_ALLOCATE
};
/**
* The channel count of the audio stream. The underlying type is `int32_t`.
* Use of this enum is convenient to avoid "magic"
* numbers when specifying the channel count.
*
* For example, you can write
* `builder.setChannelCount(ChannelCount::Stereo)`
* rather than `builder.setChannelCount(2)`
*
*/
enum ChannelCount : int32_t {
/**
* Audio channel count definition, use Mono or Stereo
*/
Unspecified = kUnspecified,
/**
* Use this for mono audio
*/
Mono = 1,
/**
* Use this for stereo audio.
*/
Stereo = 2,
};
/**
* On API 16 to 26 OpenSL ES will be used. When using OpenSL ES the optimal values for sampleRate and
* framesPerBurst are not known by the native code.
* On API 17+ these values should be obtained from the AudioManager using this code:
*
* <pre><code>
* // Note that this technique only works for built-in speakers and headphones.
* AudioManager myAudioMgr = (AudioManager) getSystemService(Context.AUDIO_SERVICE);
* String sampleRateStr = myAudioMgr.getProperty(AudioManager.PROPERTY_OUTPUT_SAMPLE_RATE);
* int defaultSampleRate = Integer.parseInt(sampleRateStr);
* String framesPerBurstStr = myAudioMgr.getProperty(AudioManager.PROPERTY_OUTPUT_FRAMES_PER_BUFFER);
* int defaultFramesPerBurst = Integer.parseInt(framesPerBurstStr);
* </code></pre>
*
* It can then be passed down to Oboe through JNI.
*
* AAudio will get the optimal framesPerBurst from the HAL and will ignore this value.
*/
class DefaultStreamValues {
public:
/** The default sample rate to use when opening new audio streams */
static int32_t SampleRate;
/** The default frames per burst to use when opening new audio streams */
static int32_t FramesPerBurst;
/** The default channel count to use when opening new audio streams */
static int32_t ChannelCount;
};
/**
* The time at which the frame at `position` was presented
*/
struct FrameTimestamp {
int64_t position; // in frames
int64_t timestamp; // in nanoseconds
};
class OboeGlobals {
public:
static bool areWorkaroundsEnabled() {
return mWorkaroundsEnabled;
}
/**
* Disable this when writing tests to reproduce bugs in AAudio or OpenSL ES
* that have workarounds in Oboe.
* @param enabled
*/
static void setWorkaroundsEnabled(bool enabled) {
mWorkaroundsEnabled = enabled;
}
private:
static bool mWorkaroundsEnabled;
};
} // namespace oboe
#endif // OBOE_DEFINITIONS_H