From 2492580f86703fee9478b366bddbc74b3aacaa9b Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Sat, 7 Oct 2023 23:36:04 +0200 Subject: [PATCH] Drop `get_` prefix from `fn`s According to [Rust's C-GETTER convention] function names should not have a `get_` prefix, and we maintain this standard in some but not all parts of the `ndk`. Consistenize that by dropping it everywhere, and add `doc(alias)`es to at least these functions (as I have been doing to new API wrappers added over the past few months too) to make it easier for users to find by the original NDK C symbol name. In addition the `audio` module received some extra doc cleanup to get rid of redundant `Available since API level xx.` doc-comments (these are already provided via `feature`s and `doc_cfg`) as well as vague statements about integer return values when the return type has been translated to a `Return<()>`. [Rust's C-GETTER convention]: https://rust-lang.github.io/api-guidelines/naming.html#getter-names-follow-rust-convention-c-getter --- ndk/CHANGELOG.md | 1 + ndk/src/asset.rs | 22 ++- ndk/src/audio.rs | 289 +++++++++++++++++++++------------- ndk/src/bitmap.rs | 6 +- ndk/src/input_queue.rs | 10 +- ndk/src/media/image_reader.rs | 58 +++++-- 6 files changed, 249 insertions(+), 137 deletions(-) diff --git a/ndk/CHANGELOG.md b/ndk/CHANGELOG.md index b3e03a47..58fb39a2 100644 --- a/ndk/CHANGELOG.md +++ b/ndk/CHANGELOG.md @@ -31,6 +31,7 @@ - **Breaking:** `raw-window-handle 0.5` support is now behind an _optional_ `rwh_05` crate feature and `raw-window-handle` `0.4` and `0.6` support is provided via the new `rwh_04` and (default-enabled) `rwh_06` crate features. (#434) - **Breaking:** looper: Provide `event` value to file descriptor poll callback. (#435) - **Breaking:** `HardwareBufferFormat` is no longer exported from `hardware_buffer` and `native_window`, and can only be reached through the `hardware_buffer_format` module. (#436) +- **Breaking:** `get_` prefixes have been removed from all public functions in light of the [C-GETTER](https://rust-lang.github.io/api-guidelines/naming.html#getter-names-follow-rust-convention-c-getter) convention. (#437) # 0.7.0 (2022-07-24) diff --git a/ndk/src/asset.rs b/ndk/src/asset.rs index 4ba319f4..4ae0c200 100644 --- a/ndk/src/asset.rs +++ b/ndk/src/asset.rs @@ -15,6 +15,7 @@ use std::{ /// /// [`AAssetManager *`]: https://developer.android.com/ndk/reference/group/asset#aassetmanager #[derive(Debug)] +#[doc(alias = "AAssetManager")] pub struct AssetManager { ptr: NonNull, } @@ -42,6 +43,7 @@ impl AssetManager { /// Open the asset. Returns [`None`] if opening the asset fails. /// /// This currently always opens the asset in the streaming mode. + #[doc(alias = "AAssetManager_open")] pub fn open(&self, filename: &CStr) -> Option { unsafe { let ptr = ffi::AAssetManager_open( @@ -54,6 +56,7 @@ impl AssetManager { } /// Open an asset directory. Returns [`None`] if opening the directory fails. + #[doc(alias = "AAssetManager_openDir")] pub fn open_dir(&self, filename: &CStr) -> Option { unsafe { let ptr = ffi::AAssetManager_openDir(self.ptr.as_ptr(), filename.as_ptr()); @@ -90,6 +93,7 @@ impl AssetManager { /// /// [`AAssetDir *`]: https://developer.android.com/ndk/reference/group/asset#aassetdir #[derive(Debug)] +#[doc(alias = "AAssetDir")] pub struct AssetDir { ptr: NonNull, } @@ -98,6 +102,7 @@ pub struct AssetDir { // However, AAsset is not, so there's a good chance that AAssetDir is not either. impl Drop for AssetDir { + #[doc(alias = "AAssetDir_close")] fn drop(&mut self) { unsafe { ffi::AAssetDir_close(self.ptr.as_ptr()) } } @@ -123,6 +128,7 @@ impl AssetDir { /// no additional allocation. /// /// The filenames are in the correct format to be passed to [`AssetManager::open()`]. + #[doc(alias = "AAssetDir_getNextFileName")] pub fn with_next(&mut self, f: impl for<'a> FnOnce(&'a CStr) -> T) -> Option { unsafe { let next_name = ffi::AAssetDir_getNextFileName(self.ptr.as_ptr()); @@ -135,6 +141,7 @@ impl AssetDir { } /// Reset the iteration state + #[doc(alias = "AAssetDir_rewind")] pub fn rewind(&mut self) { unsafe { ffi::AAssetDir_rewind(self.ptr.as_ptr()); @@ -169,6 +176,7 @@ impl Iterator for AssetDir { /// /// [`AAsset *`]: https://developer.android.com/ndk/reference/group/asset#aasset #[derive(Debug)] +#[doc(alias = "AAsset")] pub struct Asset { ptr: NonNull, } @@ -177,6 +185,7 @@ pub struct Asset { // See https://developer.android.com/ndk/reference/group/asset#aasset impl Drop for Asset { + #[doc(alias = "AAsset_close")] fn drop(&mut self) { unsafe { ffi::AAsset_close(self.ptr.as_ptr()) } } @@ -200,17 +209,20 @@ impl Asset { } /// Returns the total length of the asset, in bytes - pub fn get_length(&self) -> usize { + #[doc(alias = "AAsset_getLength64")] + pub fn length(&self) -> usize { unsafe { ffi::AAsset_getLength64(self.ptr.as_ptr()) as usize } } /// Returns the remaining length of the asset, in bytes - pub fn get_remaining_length(&self) -> usize { + #[doc(alias = "AAsset_getRemainingLength64")] + pub fn remaining_length(&self) -> usize { unsafe { ffi::AAsset_getRemainingLength64(self.ptr.as_ptr()) as usize } } /// Maps all data into a buffer and returns it - pub fn get_buffer(&mut self) -> io::Result<&[u8]> { + #[doc(alias = "AAsset_getBuffer")] + pub fn buffer(&mut self) -> io::Result<&[u8]> { unsafe { let buf_ptr = ffi::AAsset_getBuffer(self.ptr.as_ptr()); if buf_ptr.is_null() { @@ -221,7 +233,7 @@ impl Asset { } else { Ok(std::slice::from_raw_parts( buf_ptr as *const u8, - self.get_length(), + self.length(), )) } } @@ -258,6 +270,7 @@ impl Asset { } impl io::Read for Asset { + #[doc(alias = "AAsset_read")] fn read(&mut self, buf: &mut [u8]) -> io::Result { unsafe { let res = ffi::AAsset_read(self.ptr.as_ptr(), buf.as_mut_ptr() as *mut _, buf.len()); @@ -274,6 +287,7 @@ impl io::Read for Asset { } impl io::Seek for Asset { + #[doc(alias = "AAsset_seek64")] fn seek(&mut self, seek: io::SeekFrom) -> io::Result { unsafe { let res = match seek { diff --git a/ndk/src/audio.rs b/ndk/src/audio.rs index 1ff6c2e2..4ed9efb0 100644 --- a/ndk/src/audio.rs +++ b/ndk/src/audio.rs @@ -8,8 +8,6 @@ //! [`AAudioStreamBuilder`]: https://developer.android.com/ndk/reference/group/audio#aaudiostreambuilder #![cfg(feature = "audio")] -use crate::utils::abort_on_panic; -use num_enum::{IntoPrimitive, TryFromPrimitive}; use std::{ borrow::Cow, ffi::{c_void, CStr}, @@ -18,8 +16,12 @@ use std::{ num::NonZeroI32, ptr::NonNull, }; + +use num_enum::{IntoPrimitive, TryFromPrimitive}; use thiserror::Error; +use crate::utils::abort_on_panic; + /// Specifying if audio may or may not be captured by other apps or the system. /// /// Note that these match the equivalent values in [`android.media.AudioAttributes`] @@ -29,6 +31,7 @@ use thiserror::Error; #[cfg(feature = "api-level-29")] #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_allowed_capture_policy_t")] pub enum AudioAllowedCapturePolicy { /// Indicates that the audio may be captured by any app. /// @@ -40,6 +43,7 @@ pub enum AudioAllowedCapturePolicy { /// See [`MediaProjection`] and [`AudioStreamBuilder::allowed_capture_policy()`]. /// /// [`MediaProjection`]: https://developer.android.com/reference/android/media/projection/MediaProjection + #[doc(alias = "AAUDIO_ALLOW_CAPTURE_BY_ALL")] AllowCaptureByAll = ffi::AAUDIO_ALLOW_CAPTURE_BY_ALL, /// Indicates that the audio may only be captured by system apps. /// @@ -50,12 +54,14 @@ pub enum AudioAllowedCapturePolicy { /// - the audio cannot be recorded at a higher quality than 16kHz 16bit mono. /// /// See [`AudioStreamBuilder::allowed_capture_policy()`]. + #[doc(alias = "AAUDIO_ALLOW_CAPTURE_BY_SYSTEM")] AllowCaptureBySystem = ffi::AAUDIO_ALLOW_CAPTURE_BY_SYSTEM, /// Indicates that the audio may not be recorded by any app, even if it is a system app. /// /// It is encouraged to use [`AllowCaptureBySystem`][Self::AllowCaptureBySystem] instead of /// this value as system apps provide significant and useful features for the user (such as /// live captioning and accessibility). + #[doc(alias = "AAUDIO_ALLOW_CAPTURE_BY_NONE")] AllowCaptureByNone = ffi::AAUDIO_ALLOW_CAPTURE_BY_NONE, } @@ -73,30 +79,39 @@ pub enum AudioAllowedCapturePolicy { #[cfg(feature = "api-level-28")] #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_content_type_t")] pub enum AudioContentType { /// Use this for spoken voice, audio books, etcetera. + #[doc(alias = "AAUDIO_CONTENT_TYPE_SPEECH")] Speech = ffi::AAUDIO_CONTENT_TYPE_SPEECH, /// Use this for pre-recorded or live music. + #[doc(alias = "AAUDIO_CONTENT_TYPE_MUSIC")] Music = ffi::AAUDIO_CONTENT_TYPE_MUSIC, /// Use this for a movie or video soundtrack. + #[doc(alias = "AAUDIO_CONTENT_TYPE_MOVIE")] Movie = ffi::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. + #[doc(alias = "AAUDIO_CONTENT_TYPE_SONIFICATION")] Sonification = ffi::AAUDIO_CONTENT_TYPE_SONIFICATION, } #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_direction_t")] pub enum AudioDirection { /// Audio data will travel out of the device, for example through a speaker. + #[doc(alias = "AAUDIO_DIRECTION_INPUT")] Input = ffi::AAUDIO_DIRECTION_INPUT, /// Audio data will travel into the device, for example from a microphone. + #[doc(alias = "AAUDIO_DIRECTION_OUTPUT")] Output = ffi::AAUDIO_DIRECTION_OUTPUT, } #[repr(i32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] #[allow(non_camel_case_types)] +#[doc(alias = "aaudio_format_t")] pub enum AudioFormat { /// This format uses the float data type. /// The nominal range of the data is [-1.0f32, 1.0f32). @@ -104,11 +119,15 @@ pub enum AudioFormat { /// /// See also `audioData` at /// AudioTrack#write(float[], int, int, int). + #[doc(alias = "AAUDIO_FORMAT_PCM_FLOAT")] PCM_Float = ffi::AAUDIO_FORMAT_PCM_FLOAT, /// This format uses the i16 data type. /// The maximum range of the data is -32768 to 32767. + #[doc(alias = "AAUDIO_FORMAT_PCM_I16")] PCM_I16 = ffi::AAUDIO_FORMAT_PCM_I16, + #[doc(alias = "AAUDIO_FORMAT_INVALID")] Invalid = ffi::AAUDIO_FORMAT_INVALID, + #[doc(alias = "AAUDIO_FORMAT_UNSPECIFIED")] Unspecified = ffi::AAUDIO_FORMAT_UNSPECIFIED, } @@ -120,49 +139,63 @@ pub enum AudioFormat { #[cfg(feature = "api-level-28")] #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_input_preset_t")] pub enum AudioInputPreset { /// Use this preset when other presets do not apply. + #[doc(alias = "AAUDIO_INPUT_PRESET_GENERIC")] Generic = ffi::AAUDIO_INPUT_PRESET_GENERIC, /// Use this preset when recording video. + #[doc(alias = "AAUDIO_INPUT_PRESET_CAMCORDER")] Camcorder = ffi::AAUDIO_INPUT_PRESET_CAMCORDER, /// Use this preset when doing speech recognition. + #[doc(alias = "AAUDIO_INPUT_PRESET_VOICE_RECOGNITION")] VoiceRecognition = ffi::AAUDIO_INPUT_PRESET_VOICE_RECOGNITION, /// Use this preset when doing telephony or voice messaging. + #[doc(alias = "AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION")] VoiceCommunication = ffi::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. + #[doc(alias = "AAUDIO_INPUT_PRESET_UNPROCESSED")] Unprocessed = ffi::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. #[cfg(feature = "api-level-29")] + #[doc(alias = "AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE")] VoicePerformance = ffi::AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE, } #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_performance_mode_t")] pub enum AudioPerformanceMode { /// No particular performance needs. Default. + #[doc(alias = "AAUDIO_PERFORMANCE_MODE_NONE")] None = ffi::AAUDIO_PERFORMANCE_MODE_NONE, /// Extending battery life is more important than low latency. /// /// This mode is not supported in input streams. /// For input, mode NONE will be used if this is requested. + #[doc(alias = "AAUDIO_PERFORMANCE_MODE_POWER_SAVING")] PowerSaving = ffi::AAUDIO_PERFORMANCE_MODE_POWER_SAVING, /// Reducing latency is more important than battery life. + #[doc(alias = "AAUDIO_PERFORMANCE_MODE_LOW_LATENCY")] LowLatency = ffi::AAUDIO_PERFORMANCE_MODE_LOW_LATENCY, } #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_sharing_mode_t")] pub enum AudioSharingMode { /// 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. + #[doc(alias = "AAUDIO_SHARING_MODE_EXCLUSIVE")] Exclusive = ffi::AAUDIO_SHARING_MODE_EXCLUSIVE, /// Multiple applications will be mixed by the AAudio Server. /// This will have higher latency than the Exclusive mode. + #[doc(alias = "AAUDIO_SHARING_MODE_SHARED")] Shared = ffi::AAUDIO_SHARING_MODE_SHARED, } @@ -177,66 +210,100 @@ pub enum AudioSharingMode { #[cfg(feature = "api-level-28")] #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_usage_t")] pub enum AudioUsage { /// Use this for streaming media, music performance, video, podcasts, etcetera. + #[doc(alias = "AAUDIO_USAGE_MEDIA")] Media = ffi::AAUDIO_USAGE_MEDIA, /// Use this for voice over IP, telephony, etcetera. + #[doc(alias = "AAUDIO_USAGE_VOICE_COMMUNICATION")] VoiceCommunication = ffi::AAUDIO_USAGE_VOICE_COMMUNICATION, /// Use this for sounds associated with telephony such as busy tones, DTMF, etcetera. + #[doc(alias = "AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING")] VoiceCommunicationSignalling = ffi::AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING, /// Use this to demand the users attention. + #[doc(alias = "AAUDIO_USAGE_ALARM")] Alarm = ffi::AAUDIO_USAGE_ALARM, /// Use this for notifying the user when a message has arrived or some /// other background event has occured. + #[doc(alias = "AAUDIO_USAGE_NOTIFICATION")] Notification = ffi::AAUDIO_USAGE_NOTIFICATION, /// Use this when the phone rings. + #[doc(alias = "AAUDIO_USAGE_NOTIFICATION_RINGTONE")] NotificationRingtone = ffi::AAUDIO_USAGE_NOTIFICATION_RINGTONE, /// Use this to attract the users attention when, for example, the battery is low. + #[doc(alias = "AAUDIO_USAGE_NOTIFICATION_EVENT")] NotificationEvent = ffi::AAUDIO_USAGE_NOTIFICATION_EVENT, /// Use this for screen readers, etcetera. + #[doc(alias = "AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY")] AssistanceAccessibility = ffi::AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY, /// Use this for driving or navigation directions. + #[doc(alias = "AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE")] AssistanceNavigationGuidance = ffi::AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, /// Use this for user interface sounds, beeps, etcetera. + #[doc(alias = "AAUDIO_USAGE_ASSISTANCE_SONIFICATION")] AssistanceSonification = ffi::AAUDIO_USAGE_ASSISTANCE_SONIFICATION, /// Use this for game audio and sound effects. + #[doc(alias = "AAUDIO_USAGE_GAME")] Game = ffi::AAUDIO_USAGE_GAME, /// Use this for audio responses to user queries, audio instructions or help utterances. + #[doc(alias = "AAUDIO_USAGE_ASSISTANT")] Assistant = ffi::AAUDIO_USAGE_ASSISTANT, /// Use this in case of playing sounds in an emergency. /// Privileged MODIFY_AUDIO_ROUTING permission required. + #[doc(alias = "AAUDIO_SYSTEM_USAGE_EMERGENCY")] SystemEmergency = ffi::AAUDIO_SYSTEM_USAGE_EMERGENCY, /// Use this for safety sounds and alerts, for example backup camera obstacle detection. /// Privileged MODIFY_AUDIO_ROUTING permission required. + #[doc(alias = "AAUDIO_SYSTEM_USAGE_SAFETY")] SystemSafety = ffi::AAUDIO_SYSTEM_USAGE_SAFETY, /// Use this for vehicle status alerts and information, for example the check engine light. /// Privileged MODIFY_AUDIO_ROUTING permission required. + #[doc(alias = "AAUDIO_SYSTEM_USAGE_VEHICLE_STATUS")] SystemVehicleStatus = ffi::AAUDIO_SYSTEM_USAGE_VEHICLE_STATUS, + #[doc(alias = "announcements")] /// Use this for traffic announcements, etc. /// Privileged MODIFY_AUDIO_ROUTING permission required. + #[doc(alias = "AAUDIO_SYSTEM_USAGE_ANNOUNCEMENT")] SystemAnnouncement = ffi::AAUDIO_SYSTEM_USAGE_ANNOUNCEMENT, } #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)] +#[doc(alias = "aaudio_stream_state_t")] pub enum AudioStreamState { + #[doc(alias = "AAUDIO_STREAM_STATE_UNINITIALIZED")] Uninitialized = ffi::AAUDIO_STREAM_STATE_UNINITIALIZED, + #[doc(alias = "AAUDIO_STREAM_STATE_UNKNOWN")] Unknown = ffi::AAUDIO_STREAM_STATE_UNKNOWN, + #[doc(alias = "AAUDIO_STREAM_STATE_OPEN")] Open = ffi::AAUDIO_STREAM_STATE_OPEN, + #[doc(alias = "AAUDIO_STREAM_STATE_STARTING")] Starting = ffi::AAUDIO_STREAM_STATE_STARTING, + #[doc(alias = "AAUDIO_STREAM_STATE_STARTED")] Started = ffi::AAUDIO_STREAM_STATE_STARTED, + #[doc(alias = "AAUDIO_STREAM_STATE_PAUSING")] Pausing = ffi::AAUDIO_STREAM_STATE_PAUSING, + #[doc(alias = "AAUDIO_STREAM_STATE_PAUSED")] Paused = ffi::AAUDIO_STREAM_STATE_PAUSED, + #[doc(alias = "AAUDIO_STREAM_STATE_FLUSHING")] Flushing = ffi::AAUDIO_STREAM_STATE_FLUSHING, + #[doc(alias = "AAUDIO_STREAM_STATE_FLUSHED")] Flushed = ffi::AAUDIO_STREAM_STATE_FLUSHED, + #[doc(alias = "AAUDIO_STREAM_STATE_STOPPING")] Stopping = ffi::AAUDIO_STREAM_STATE_STOPPING, + #[doc(alias = "AAUDIO_STREAM_STATE_STOPPED")] Stopped = ffi::AAUDIO_STREAM_STATE_STOPPED, + #[doc(alias = "AAUDIO_STREAM_STATE_CLOSING")] Closing = ffi::AAUDIO_STREAM_STATE_CLOSING, + #[doc(alias = "AAUDIO_STREAM_STATE_CLOSED")] Closed = ffi::AAUDIO_STREAM_STATE_CLOSED, + #[doc(alias = "AAUDIO_STREAM_STATE_DISCONNECTED")] Disconnected = ffi::AAUDIO_STREAM_STATE_DISCONNECTED, } impl AudioStreamState { + #[doc(alias = "AAudio_convertStreamStateToText")] pub fn to_text(self) -> Cow<'static, str> { let ptr = unsafe { CStr::from_ptr(ffi::AAudio_convertStreamStateToText( @@ -248,6 +315,7 @@ impl AudioStreamState { } #[derive(Copy, Clone, Debug, PartialEq, Eq)] +#[doc(alias = "aaudio_session_id_t")] pub enum SessionId { None, Allocated(NonZeroI32), @@ -262,65 +330,89 @@ pub struct Timestamp { #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum Clockid { + #[doc(alias = "CLOCK_MONOTONIC")] Monotonic = ffi::CLOCK_MONOTONIC, + #[doc(alias = "CLOCK_BOOTTIME")] Boottime = ffi::CLOCK_BOOTTIME, } /// Value returned the data callback function. #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq)] +#[doc(alias = "aaudio_data_callback_result_t")] pub enum AudioCallbackResult { /// Continue calling the callback. + #[doc(alias = "AAUDIO_CALLBACK_RESULT_CONTINUE")] Continue = ffi::AAUDIO_CALLBACK_RESULT_CONTINUE, /// Stop calling the callback. /// /// The application will still need to call [`AudioStream::request_pause()`] /// or [`AudioStream::request_stop()`]. + #[doc(alias = "AAUDIO_CALLBACK_RESULT_STOP")] Stop = ffi::AAUDIO_CALLBACK_RESULT_STOP, } #[repr(i32)] #[derive(Copy, Clone, Debug, PartialEq, Eq)] +#[doc(alias = "aaudio_result_t")] pub enum AudioErrorResult { + #[doc(alias = "AAUDIO_ERROR_BASE")] Base = ffi::AAUDIO_ERROR_BASE, /// The audio device was disconnected. This could occur, for example, when headphones /// are plugged in or unplugged. The stream cannot be used after the device is disconnected. /// Applications should stop and close the stream. /// If this error is received in an error callback then another thread should be /// used to stop and close the stream. + #[doc(alias = "AAUDIO_ERROR_DISCONNECTED")] Disconnected = ffi::AAUDIO_ERROR_DISCONNECTED, /// An invalid parameter was passed to AAudio. + #[doc(alias = "AAUDIO_ERROR_ILLEGAL_ARGUMENT")] IllegalArgument = ffi::AAUDIO_ERROR_ILLEGAL_ARGUMENT, /// The requested operation is not appropriate for the current state of AAudio. + #[doc(alias = "AAUDIO_ERROR_INTERNAL")] Internal = ffi::AAUDIO_ERROR_INTERNAL, /// The requested operation is not appropriate for the current state of AAudio. + #[doc(alias = "AAUDIO_ERROR_INVALID_STATE")] InvalidState = ffi::AAUDIO_ERROR_INVALID_STATE, /// The server rejected the handle used to identify the stream. + #[doc(alias = "AAUDIO_ERROR_INVALID_HANDLE")] InvalidHandle = ffi::AAUDIO_ERROR_INVALID_HANDLE, /// The function is not implemented for this stream. + #[doc(alias = "AAUDIO_ERROR_UNIMPLEMENTED")] Unimplemented = ffi::AAUDIO_ERROR_UNIMPLEMENTED, /// A resource or information is unavailable. /// This could occur when an application tries to open too many streams, /// or a timestamp is not available. + #[doc(alias = "AAUDIO_ERROR_UNAVAILABLE")] Unavailable = ffi::AAUDIO_ERROR_UNAVAILABLE, /// Memory could not be allocated. + #[doc(alias = "AAUDIO_ERROR_NO_FREE_HANDLES")] NoFreeHandles = ffi::AAUDIO_ERROR_NO_FREE_HANDLES, /// Memory could not be allocated. + #[doc(alias = "AAUDIO_ERROR_NO_MEMORY")] NoMemory = ffi::AAUDIO_ERROR_NO_MEMORY, + #[doc(alias = "AAUDIO_ERROR_NULL")] Null = ffi::AAUDIO_ERROR_NULL, + #[doc(alias = "AAUDIO_ERROR_TIMEOUT")] Timeout = ffi::AAUDIO_ERROR_TIMEOUT, + #[doc(alias = "AAUDIO_ERROR_WOULD_BLOCK")] WouldBlock = ffi::AAUDIO_ERROR_WOULD_BLOCK, /// The requested data format is not supported. + #[doc(alias = "AAUDIO_ERROR_INVALID_FORMAT")] InvalidFormat = ffi::AAUDIO_ERROR_INVALID_FORMAT, /// A requested was out of range. + #[doc(alias = "AAUDIO_ERROR_OUT_OF_RANGE")] OutOfRange = ffi::AAUDIO_ERROR_OUT_OF_RANGE, /// The audio service was not available. + #[doc(alias = "AAUDIO_ERROR_NO_SERVICE")] NoService = ffi::AAUDIO_ERROR_NO_SERVICE, /// The requested sample rate was not supported. + #[doc(alias = "AAUDIO_ERROR_INVALID_RATE")] InvalidRate = ffi::AAUDIO_ERROR_INVALID_RATE, } impl AudioErrorResult { + #[doc(alias = "AAudio_convertStreamStateToText")] pub fn to_text(self) -> Cow<'static, str> { let ptr = unsafe { CStr::from_ptr(ffi::AAudio_convertStreamStateToText( @@ -390,6 +482,7 @@ fn enum_return_value>(return_value: i32) -> Result { /// A native [`AAudioStreamBuilder *`] /// /// [`AAudioStreamBuilder *`]: https://developer.android.com/ndk/reference/group/audio#aaudiostreambuilder +#[doc(alias = "AAudioStreamBuilder")] pub struct AudioStreamBuilder { inner: NonNull, data_callback: Option, @@ -418,8 +511,10 @@ impl fmt::Debug for AudioStreamBuilder { } } +#[doc(alias = "AAudioStream_dataCallback")] pub type AudioStreamDataCallback = Box AudioCallbackResult>; +#[doc(alias = "AAudioStream_errorCallback")] pub type AudioStreamErrorCallback = Box; impl AudioStreamBuilder { @@ -435,6 +530,7 @@ impl AudioStreamBuilder { self.inner.as_ptr() } + #[doc(alias = "AAudio_createStreamBuilder")] pub fn new() -> Result { unsafe { let ptr = construct(|res| ffi::AAudio_createStreamBuilder(res))?; @@ -449,14 +545,13 @@ impl AudioStreamBuilder { /// Note that an application can also set its global policy, in which case the most restrictive /// policy is always applied. See [`android.media.AudioAttributes#setAllowedCapturePolicy(int)`]. /// - /// Available since API level 29. - /// /// # Parameters /// /// - `policy`: the desired level of opt-out from being captured. /// /// [`android.media.AudioAttributes#setAllowedCapturePolicy(int)`]: https://developer.android.com/reference/android/media/AudioAttributes.Builder#setAllowedCapturePolicy(int) #[cfg(feature = "api-level-29")] + #[doc(alias = "AAudioStreamBuilder_setAllowedCapturePolicy")] pub fn allowed_capture_policy(self, capture_policy: AudioAllowedCapturePolicy) -> Self { unsafe { ffi::AAudioStreamBuilder_setAllowedCapturePolicy( @@ -472,11 +567,10 @@ impl AudioStreamBuilder { /// /// The default, if you do not call this function, is unspecified. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `num_frames`: the desired buffer capacity in frames or 0 for unspecified + #[doc(alias = "AAudioStreamBuilder_setBufferCapacityInFrames")] pub fn buffer_capacity_in_frames(self, num_frames: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setBufferCapacityInFrames(self.as_ptr(), num_frames) }; self @@ -492,11 +586,10 @@ impl AudioStreamBuilder { /// 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. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `channel_count`: Number of channels desired. + #[doc(alias = "AAudioStreamBuilder_setChannelCount")] pub fn channel_count(self, channel_count: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setChannelCount(self.as_ptr(), channel_count) }; self @@ -510,12 +603,11 @@ impl AudioStreamBuilder { /// /// The default, if you do not call this function, is [`AudioContentType::Music`]. /// - /// Available since API level 28. - /// /// # Parameters /// /// - `content_type`: the type of audio data, eg. [`AudioContentType::Speech`] #[cfg(feature = "api-level-28")] + #[doc(alias = "AAudioStreamBuilder_setContentType")] pub fn content_type(self, content_type: AudioContentType) -> Self { unsafe { ffi::AAudioStreamBuilder_setContentType( @@ -560,8 +652,7 @@ impl AudioStreamBuilder { /// we recommend the use of non-blocking techniques such as an atomic FIFO. /// /// Note that the AAudio callbacks will never be called simultaneously from multiple threads. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStreamBuilder_setDataCallback")] pub fn data_callback(mut self, callback: AudioStreamDataCallback) -> Self { let mut boxed = Box::new(callback); let ptr: *mut AudioStreamDataCallback = &mut *boxed; @@ -603,11 +694,10 @@ impl AudioStreamBuilder { /// The default, if you do not call this function, is 0, /// in which case the primary device will be used. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `device_id`: device identifier or 0 for unspecified + #[doc(alias = "AAudioStreamBuilder_setDeviceId")] pub fn device_id(self, device_id: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setDeviceId(self.as_ptr(), device_id) }; self @@ -617,11 +707,10 @@ impl AudioStreamBuilder { /// /// The default, if you do not call this function, is [`Output`][AudioDirection::Output]. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `direction`: [`Output`][AudioDirection::Output] or [`Input`][AudioDirection::Input] + #[doc(alias = "AAudioStreamBuilder_setDirection")] pub fn direction(self, direction: AudioDirection) -> Self { unsafe { ffi::AAudioStreamBuilder_setDirection( @@ -647,8 +736,7 @@ impl AudioStreamBuilder { /// or closing a stream. /// /// Note that the AAudio callbacks will never be called simultaneously from multiple threads. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStreamBuilder_setErrorCallback")] pub fn error_callback(mut self, callback: AudioStreamErrorCallback) -> Self { let mut boxed = Box::new(callback); let ptr: *mut AudioStreamErrorCallback = &mut *boxed; @@ -693,11 +781,10 @@ impl AudioStreamBuilder { /// 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. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `format`: the sample data format. + #[doc(alias = "AAudioStreamBuilder_setFormat")] pub fn format(self, format: AudioFormat) -> Self { unsafe { ffi::AAudioStreamBuilder_setFormat(self.as_ptr(), format as ffi::aaudio_format_t) @@ -725,9 +812,8 @@ impl AudioStreamBuilder { /// If you do call this function then the requested size should be less than /// half the buffer capacity, to allow double buffering. /// - /// Available since API level 26. - /// /// - `num_frames`: the desired buffer size in frames or 0 for unspecified + #[doc(alias = "AAudioStreamBuilder_setFramesPerDataCallback")] pub fn frames_per_data_callback(self, num_frames: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setFramesPerDataCallback(self.as_ptr(), num_frames) }; self @@ -743,12 +829,11 @@ impl AudioStreamBuilder { /// The default, if you do not call this function, is [`VoiceRecognition`][AudioInputPreset::VoiceRecognition] /// which is the preset with the lowest latency on many platforms. /// - /// Available since API level 28. - /// /// # Parameters /// /// - `input_preset`: the desired configuration for recording #[cfg(feature = "api-level-28")] + #[doc(alias = "AAudioStreamBuilder_setInputPreset")] pub fn input_preset(self, input_preset: AudioInputPreset) -> Self { unsafe { ffi::AAudioStreamBuilder_setInputPreset( @@ -766,14 +851,13 @@ impl AudioStreamBuilder { /// The default, if you do not call this function, is None. /// /// You may not get the mode you requested. - /// You can call [`AudioStream::get_performance_mode()`] + /// You can call [`AudioStream::performance_mode()`] /// to find out the final mode for the stream. /// - /// Available since API level 26. - /// /// # Parameters /// - /// - `mode`: the desired performance mode, eg. LowLatency + /// - `mode`: the desired performance mode, eg. [`AudioPerformanceMode::LowLatency`] + #[doc(alias = "AAudioStreamBuilder_setPerformanceMode")] pub fn performance_mode(self, mode: AudioPerformanceMode) -> Self { unsafe { ffi::AAudioStreamBuilder_setPerformanceMode( @@ -794,16 +878,16 @@ impl AudioStreamBuilder { /// 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. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `sample_rate`: frames per second. Common rates include 44100 and 48000 Hz. + #[doc(alias = "AAudioStreamBuilder_setSampleRate")] pub fn sample_rate(self, sample_rate: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setSampleRate(self.as_ptr(), sample_rate) }; self } + #[doc(alias = "AAudioStreamBuilder_setSamplesPerFrame")] pub fn samples_per_frame(self, samples_per_frame: i32) -> Self { unsafe { ffi::AAudioStreamBuilder_setSamplesPerFrame(self.as_ptr(), samples_per_frame) }; self @@ -816,7 +900,7 @@ impl AudioStreamBuilder { /// /// If set to [`Option::None`] then a session ID will be allocated when the stream is opened. /// - /// The allocated session ID can be obtained by calling [`AudioStream::get_session_id()`] + /// The allocated session ID can be obtained by calling [`AudioStream::session_id()`] /// and then used with this function when opening another stream. /// This allows effects to be shared between streams. /// @@ -828,12 +912,11 @@ impl AudioStreamBuilder { /// /// Allocated session IDs will always be positive and nonzero. /// - /// Available since API level 28. - /// /// # Parameters /// /// - `session_id`: an allocated sessionID or [`Option::None`] to allocate a new sessionID #[cfg(feature = "api-level-28")] + #[doc(alias = "AAudioStreamBuilder_setSessionId")] pub fn session_id(self, session_id_or_allocate: Option) -> Self { let session_id = match session_id_or_allocate { None => ffi::AAUDIO_SESSION_ID_ALLOCATE, @@ -852,11 +935,10 @@ impl AudioStreamBuilder { /// The requested sharing mode may not be available. /// The application can query for the actual mode after the stream is opened. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `sharing_mode`: [`AudioSharingMode::Shared`] or [`AudioSharingMode::Exclusive`] + #[doc(alias = "AAudioStreamBuilder_setSharingMode")] pub fn sharing_mode(self, sharing_mode: AudioSharingMode) -> Self { unsafe { ffi::AAudioStreamBuilder_setSharingMode( @@ -875,16 +957,16 @@ impl AudioStreamBuilder { /// /// The default, if you do not call this function, is [`AudioUsage::Media`]. /// - /// Available since API level 28. - /// /// - `usage`: the desired usage, eg. [`AudioUsage::Game`] #[cfg(feature = "api-level-28")] + #[doc(alias = "AAudioStreamBuilder_setUsage")] pub fn usage(self, usage: AudioUsage) -> Self { unsafe { ffi::AAudioStreamBuilder_setUsage(self.as_ptr(), usage as ffi::aaudio_usage_t) }; self } /// Open a stream based on the options in the AAudioStreamBuilder. + #[doc(alias = "AAudioStreamBuilder_openStream")] pub fn open_stream(mut self) -> Result { unsafe { let ptr = construct(|res| ffi::AAudioStreamBuilder_openStream(self.as_ptr(), res))?; @@ -899,6 +981,7 @@ impl AudioStreamBuilder { } impl Drop for AudioStreamBuilder { + #[doc(alias = "AAudioStreamBuilder_delete")] fn drop(&mut self) { let status = unsafe { ffi::AAudioStreamBuilder_delete(self.as_ptr()) }; AudioError::from_result(status, || ()).unwrap(); @@ -908,6 +991,7 @@ impl Drop for AudioStreamBuilder { /// A native [`AAudioStream *`] /// /// [`AAudioStream *`]: https://developer.android.com/ndk/reference/group/audio#aaudiostream +#[doc(alias = "AAudioStream")] pub struct AudioStream { inner: NonNull, data_callback: Option, @@ -944,55 +1028,53 @@ impl AudioStream { /// Returns the policy that determines whether the audio may or /// may not be captured by other apps or the system. #[cfg(feature = "api-level-29")] - pub fn get_allowed_capture_policy(self) -> Result { + #[doc(alias = "AAudioStream_getAllowedCapturePolicy")] + pub fn allowed_capture_policy(self) -> Result { enum_return_value(unsafe { ffi::AAudioStream_getAllowedCapturePolicy(self.as_ptr()) }) } /// Query maximum buffer capacity in frames. - /// - /// Available since API level 26. - pub fn get_buffer_capacity_in_frames(&self) -> i32 { + #[doc(alias = "AAudioStream_getBufferCapacityInFrames")] + pub fn buffer_capacity_in_frames(&self) -> i32 { unsafe { ffi::AAudioStream_getBufferCapacityInFrames(self.as_ptr()) } } /// Query the maximum number of frames that can be filled without blocking. - /// - /// Available since API level 26. - pub fn get_buffer_size_in_frames(&self) -> i32 { + #[doc(alias = "AAudioStream_getBufferSizeInFrames")] + pub fn buffer_size_in_frames(&self) -> i32 { unsafe { ffi::AAudioStream_getBufferSizeInFrames(self.as_ptr()) } } /// A stream has one or more channels of data. /// A frame will contain one sample for each channel. - /// - /// Available since API level 26. - pub fn get_channel_count(&self) -> i32 { + #[doc(alias = "AAudioStream_getChannelCount")] + pub fn channel_count(&self) -> i32 { unsafe { ffi::AAudioStream_getChannelCount(self.as_ptr()) } } #[cfg(feature = "api-level-28")] - pub fn get_content_type(&self) -> Result { + #[doc(alias = "AAudioStream_getContentType")] + pub fn content_type(&self) -> Result { let value = unsafe { ffi::AAudioStream_getContentType(self.as_ptr()) }; enum_return_value(value) } /// Returns the actual device ID. - /// - /// Available since API level 26. - pub fn get_device_id(&self) -> i32 { + #[doc(alias = "AAudioStream_getDeviceId")] + pub fn device_id(&self) -> i32 { unsafe { ffi::AAudioStream_getDeviceId(self.as_ptr()) } } /// Available since API level 26. - pub fn get_direction(&self) -> Result { + #[doc(alias = "AAudioStream_getDirection")] + pub fn direction(&self) -> Result { let value = unsafe { ffi::AAudioStream_getDirection(self.as_ptr()) }; enum_return_value(value) } /// Returns the actual data format. - /// - /// Available since API level 26. - pub fn get_format(&self) -> Result { + #[doc(alias = "AAudioStream_getFormat")] + pub fn format(&self) -> Result { let value = unsafe { ffi::AAudioStream_getFormat(self.as_ptr()) }; AudioFormat::try_from(value).map_err(|_| AudioError::UnsupportedValue(value)) } @@ -1005,9 +1087,8 @@ impl AudioStream { /// Note that this may or may not match the actual device burst size. /// For some endpoints, the burst size can vary dynamically. /// But these tend to be devices with high latency. - /// - /// Available since API level 26. - pub fn get_frames_per_burst(&self) -> i32 { + #[doc(alias = "AAudioStream_getFramesPerBurst")] + pub fn frames_per_burst(&self) -> i32 { unsafe { ffi::AAudioStream_getFramesPerBurst(self.as_ptr()) } } @@ -1022,9 +1103,8 @@ impl AudioStream { /// return the size chosen by AAudio, or 0. /// /// `None` indicates that the callback buffer size for this stream may vary from one dataProc callback to the next. - /// - /// Available since API level 26. - pub fn get_frames_per_data_callback(&self) -> Option { + #[doc(alias = "AAudioStream_getFramesPerDataCallback")] + pub fn frames_per_data_callback(&self) -> Option { let value = unsafe { ffi::AAudioStream_getFramesPerDataCallback(self.as_ptr()) }; const AAUDIO_UNSPECIFIED: i32 = ffi::AAUDIO_UNSPECIFIED as i32; match value { @@ -1039,9 +1119,8 @@ impl AudioStream { /// or by a data callback. /// /// The frame position is monotonically increasing. - /// - /// Available since API level 26. - pub fn get_frames_read(&self) -> i64 { + #[doc(alias = "AAudioStream_getFramesRead")] + pub fn frames_read(&self) -> i64 { unsafe { ffi::AAudioStream_getFramesRead(self.as_ptr()) } } @@ -1051,34 +1130,33 @@ impl AudioStream { /// For an input stream, this will be advanced by the endpoint. /// /// The frame position is monotonically increasing. - /// - /// Available since API level 26. - pub fn get_frames_written(&self) -> i64 { + #[doc(alias = "AAudioStream_getFramesWritten")] + pub fn frames_written(&self) -> i64 { unsafe { ffi::AAudioStream_getFramesWritten(self.as_ptr()) } } #[cfg(feature = "api-level-28")] - pub fn get_input_preset(&self) -> Result { + #[doc(alias = "AAudioStream_getInputPreset")] + pub fn input_preset(&self) -> Result { let value = unsafe { ffi::AAudioStream_getInputPreset(self.as_ptr()) }; enum_return_value(value) } /// Get the performance mode used by the stream. - /// - /// Available since API level 26. - pub fn get_performance_mode(&self) -> Result { + #[doc(alias = "AAudioStream_getPerformanceMode")] + pub fn performance_mode(&self) -> Result { let value = unsafe { ffi::AAudioStream_getPerformanceMode(self.as_ptr()) }; enum_return_value(value) } /// Returns the actual sample rate. - /// - /// Available since API level 26. - pub fn get_sample_rate(&self) -> i32 { + #[doc(alias = "AAudioStream_getSampleRate")] + pub fn sample_rate(&self) -> i32 { unsafe { ffi::AAudioStream_getSampleRate(self.as_ptr()) } } - pub fn get_samples_per_frame(&self) -> i32 { + #[doc(alias = "AAudioStream_getSamplesPerFrame")] + pub fn samples_per_frame(&self) -> i32 { unsafe { ffi::AAudioStream_getSamplesPerFrame(self.as_ptr()) } } @@ -1097,10 +1175,9 @@ impl AudioStream { /// return `-1`. /// /// The sessionID for a stream should not change once the stream has been opened. - /// - /// Available since API level 28. #[cfg(feature = "api-level-28")] - pub fn get_session_id(&self) -> SessionId { + #[doc(alias = "AAudioStream_getSessionId")] + pub fn session_id(&self) -> SessionId { let value = unsafe { ffi::AAudioStream_getSessionId(self.as_ptr()) }; match value { ffi::AAUDIO_SESSION_ID_NONE => SessionId::None, @@ -1109,9 +1186,8 @@ impl AudioStream { } /// Provide actual sharing mode. - /// - /// Available since API level 26. - pub fn get_sharing_mode(&self) -> Result { + #[doc(alias = "AAudioStream_getSharingMode")] + pub fn sharing_mode(&self) -> Result { let value = unsafe { ffi::AAudioStream_getSharingMode(self.as_ptr()) }; enum_return_value(value) } @@ -1122,9 +1198,8 @@ impl AudioStream { /// If you want to update the client state based on the server state then /// call [`AudioStream::wait_for_state_change()`] with currentState /// set to [`Unknown`][AudioStreamState::Unknown] and a zero timeout. - /// - /// Available since API level 26. - pub fn get_state(&self) -> Result { + #[doc(alias = "AAudioStream_getState")] + pub fn state(&self) -> Result { let value = unsafe { ffi::AAudioStream_getState(self.as_ptr()) }; enum_return_value(value) } @@ -1146,9 +1221,8 @@ impl AudioStream { /// If an error occurs, then the position and time will not be modified. /// /// The position and time passed back are monotonically increasing. - /// - /// Available since API level 26. - pub fn get_timestamp(&self, clockid: Clockid) -> Result { + #[doc(alias = "AAudioStream_getTimestamp")] + pub fn timestamp(&self, clockid: Clockid) -> Result { let frame_position; let time_nanoseconds = unsafe { let mut nanoseconds = MaybeUninit::uninit(); @@ -1170,7 +1244,8 @@ impl AudioStream { } #[cfg(feature = "api-level-28")] - pub fn get_usage(&self) -> Result { + #[doc(alias = "AAudioStream_getUsage")] + pub fn usage(&self) -> Result { let value = unsafe { ffi::AAudioStream_getUsage(self.as_ptr()) }; enum_return_value(value) } @@ -1185,9 +1260,8 @@ impl AudioStream { /// /// Note that some INPUT devices may not support this function. /// In that case a 0 will always be returned. - /// - /// Available since API level 26. - pub fn get_x_run_count(&self) -> i32 { + #[doc(alias = "AAudioStream_getXRunCount")] + pub fn x_run_count(&self) -> i32 { unsafe { ffi::AAudioStream_getXRunCount(self.as_ptr()) } } @@ -1205,8 +1279,6 @@ impl AudioStream { /// /// If the call times out then zero or a partial frame count will be returned. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `buffer`: The slice with the samples. @@ -1215,6 +1287,7 @@ impl AudioStream { /// /// # Safety /// `buffer` must be a valid pointer to at least `num_frames` samples. + #[doc(alias = "AAudioStream_read")] pub unsafe fn read( &self, buffer: *mut c_void, @@ -1234,8 +1307,7 @@ impl AudioStream { /// [`Flushed`][AudioStreamState::Flushed]. /// /// This will return [`Unimplemented`][AudioErrorResult::Unimplemented] for input streams. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStream_requestFlush")] pub fn request_flush(&self) -> Result<()> { let result = unsafe { ffi::AAudioStream_requestFlush(self.as_ptr()) }; AudioError::from_result(result, || ()) @@ -1249,8 +1321,7 @@ impl AudioStream { /// /// This will return [`Unimplemented`][AudioErrorResult::Unimplemented] for input streams. /// For input streams use [`AudioStream::request_stop()`]. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStream_requestPause")] pub fn request_pause(&self) -> Result<()> { let result = unsafe { ffi::AAudioStream_requestPause(self.as_ptr()) }; AudioError::from_result(result, || ()) @@ -1261,10 +1332,7 @@ impl AudioStream { /// Otherwise it will underflow. /// After this call the state will be in [`Starting`][AudioStreamState::Starting] or /// [`Started`][AudioStreamState::Started]. - /// - /// Returns 0 for OK or a negative error. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStream_requestStart")] pub fn request_start(&self) -> Result<()> { let result = unsafe { ffi::AAudioStream_requestStart(self.as_ptr()) }; AudioError::from_result(result, || ()) @@ -1274,8 +1342,7 @@ impl AudioStream { /// The stream will stop after all of the data currently buffered has been played. /// After this call the state will be in [`Stopping`][AudioStreamState::Stopping] or /// [`Stopped`][AudioStreamState::Stopped]. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStream_requestStop")] pub fn request_stop(&self) -> Result<()> { let result = unsafe { ffi::AAudioStream_requestStop(self.as_ptr()) }; AudioError::from_result(result, || ()) @@ -1283,21 +1350,20 @@ impl AudioStream { /// This can be used to adjust the latency of the buffer by changing /// the threshold where blocking will occur. - /// By combining this with [`AudioStream::get_x_run_count()`], the latency can be tuned + /// By combining this with [`AudioStream::x_run_count()`], the latency can be tuned /// at run-time for each device. /// Returns actual buffer size in frames or a negative error. /// - /// This cannot be set higher than [`AudioStream::get_buffer_capacity_in_frames()`]. + /// This cannot be set higher than [`AudioStream::buffer_capacity_in_frames()`]. /// /// Note that you will probably not get the exact size you request. - /// You can check the return value or call [`AudioStream::get_buffer_size_in_frames()`] + /// You can check the return value or call [`AudioStream::buffer_size_in_frames()`] /// to see what the actual final size is. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `num_frames`: requested number of frames that can be filled without blocking + #[doc(alias = "AAudioStream_setBufferSizeInFrames")] pub fn set_buffer_size_in_frames(&self, num_frames: i32) -> Result { let result = unsafe { ffi::AAudioStream_setBufferSizeInFrames(self.as_ptr(), num_frames) }; AudioError::from_result(result, || result) @@ -1308,8 +1374,7 @@ impl AudioStream { /// This will update the current client state. /// /// Returns the new state. - /// - /// Available since API level 26. + #[doc(alias = "AAudioStream_waitForStateChange")] pub fn wait_for_state_change( &self, input_state: AudioStreamState, @@ -1340,8 +1405,6 @@ impl AudioStream { /// /// If the call times out then zero or a partial frame count will be returned. /// - /// Available since API level 26. - /// /// # Parameters /// /// - `buffer`: The address of the first sample. @@ -1350,6 +1413,7 @@ impl AudioStream { /// /// # Safety /// `buffer` must be a valid pointer to at least `num_frames` samples. + #[doc(alias = "AAudioStream_write")] pub unsafe fn write( &self, buffer: *const c_void, @@ -1364,6 +1428,7 @@ impl AudioStream { } impl Drop for AudioStream { + #[doc(alias = "AAudioStream_close")] fn drop(&mut self) { let status = unsafe { ffi::AAudioStream_close(self.as_ptr()) }; AudioError::from_result(status, || ()).unwrap(); diff --git a/ndk/src/bitmap.rs b/ndk/src/bitmap.rs index 1e906b7d..6919f1d3 100644 --- a/ndk/src/bitmap.rs +++ b/ndk/src/bitmap.rs @@ -90,7 +90,7 @@ impl Bitmap { /// Fills out and returns the [`BitmapInfo`] struct for the given Java bitmap object. #[doc(alias = "AndroidBitmap_getInfo")] - pub fn get_info(&self) -> Result { + pub fn info(&self) -> Result { let inner = construct(|res| unsafe { ffi::AndroidBitmap_getInfo(self.env, self.inner, res) })?; @@ -124,7 +124,7 @@ impl Bitmap { /// Client must not modify it while a [`Bitmap`] is wrapping it. #[cfg(feature = "api-level-30")] #[doc(alias = "AndroidBitmap_getHardwareBuffer")] - pub fn get_hardware_buffer(&self) -> Result { + pub fn hardware_buffer(&self) -> Result { unsafe { let result = construct(|res| ffi::AndroidBitmap_getHardwareBuffer(self.env, self.inner, res))?; @@ -190,7 +190,7 @@ impl BitmapInfoFlags { /// Returns [`true`] when [`ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE`] is set, meaning this /// [`Bitmap`] uses "HARDWARE Config" and its [`HardwareBufferRef`] can be retrieved via - /// [`Bitmap::get_hardware_buffer()`]. + /// [`Bitmap::hardware_buffer()`]. #[doc(alias = "ANDROID_BITMAP_FLAGS_IS_HARDWARE")] pub fn is_hardware(self) -> bool { // This constant is defined in a separate anonymous enum which bindgen treats as i32. diff --git a/ndk/src/input_queue.rs b/ndk/src/input_queue.rs index 55192e77..91d2f01f 100644 --- a/ndk/src/input_queue.rs +++ b/ndk/src/input_queue.rs @@ -42,7 +42,8 @@ impl InputQueue { /// Returns the next available [`InputEvent`] from the queue. /// /// Returns [`None`] if no event is available. - pub fn get_event(&self) -> Result> { + #[doc(alias = "AInputQueue_getEvent")] + pub fn event(&self) -> Result> { let mut out_event = ptr::null_mut(); let status = unsafe { ffi::AInputQueue_getEvent(self.ptr.as_ptr(), &mut out_event) }; match status_to_io_result(status) { @@ -58,6 +59,7 @@ impl InputQueue { } /// Returns [`true`] if there are one or more events available in the input queue. + #[doc(alias = "AInputQueue_hasEvents")] pub fn has_events(&self) -> bool { match unsafe { ffi::AInputQueue_hasEvents(self.ptr.as_ptr()) } { 0 => false, @@ -74,6 +76,7 @@ impl InputQueue { /// appear again in the event queue (if it does not get consumed during pre-dispatching). /// /// Also returns [`None`] if `event` is not a [`KeyEvent`]. + #[doc(alias = "AInputQueue_preDispatchEvent")] pub fn pre_dispatch(&self, event: InputEvent) -> Option { match unsafe { ffi::AInputQueue_preDispatchEvent(self.ptr.as_ptr(), event.ptr().as_ptr()) } { @@ -84,7 +87,8 @@ impl InputQueue { /// Report that dispatching has finished with the given [`InputEvent`]. /// - /// This must be called after receiving an event with [`InputQueue::get_event()`]. + /// This must be called after receiving an event with [`InputQueue::event()`]. + #[doc(alias = "AInputQueue_finishEvent")] pub fn finish_event(&self, event: InputEvent, handled: bool) { unsafe { ffi::AInputQueue_finishEvent(self.ptr.as_ptr(), event.ptr().as_ptr(), handled as c_int) @@ -94,6 +98,7 @@ impl InputQueue { /// Add this input queue to a [`ForeignLooper`] for processing. /// /// See [`ForeignLooper::add_fd()`] for information on the `ident`, `callback`, and `data` params. + #[doc(alias = "AInputQueue_attachLooper")] pub fn attach_looper(&self, looper: &ForeignLooper, id: i32) { unsafe { ffi::AInputQueue_attachLooper( @@ -107,6 +112,7 @@ impl InputQueue { } /// Remove this input queue from the [`ForeignLooper`] it is currently attached to. + #[doc(alias = "AInputQueue_detachLooper")] pub fn detach_looper(&self) { unsafe { ffi::AInputQueue_detachLooper(self.ptr.as_ptr()) } } diff --git a/ndk/src/media/image_reader.rs b/ndk/src/media/image_reader.rs index 6b2f4960..5c611c0d 100644 --- a/ndk/src/media/image_reader.rs +++ b/ndk/src/media/image_reader.rs @@ -118,6 +118,7 @@ impl ImageReader { Ok(Self::from_ptr(inner)) } + #[doc(alias = "AImageReader_setImageListener")] pub fn set_image_listener(&mut self, listener: ImageListener) -> Result<()> { let mut boxed = Box::new(listener); let ptr: *mut ImageListener = &mut *boxed; @@ -145,6 +146,7 @@ impl ImageReader { } #[cfg(feature = "api-level-26")] + #[doc(alias = "AImageReader_setBufferRemovedListener")] pub fn set_buffer_removed_listener(&mut self, listener: BufferRemovedListener) -> Result<()> { let mut boxed = Box::new(listener); let ptr: *mut BufferRemovedListener = &mut *boxed; @@ -177,30 +179,36 @@ impl ImageReader { /// Get a [`NativeWindow`] that can be used to produce [`Image`]s for this [`ImageReader`]. /// /// - pub fn get_window(&self) -> Result { + #[doc(alias = "AImageReader_getWindow")] + pub fn window(&self) -> Result { unsafe { let ptr = construct_never_null(|res| ffi::AImageReader_getWindow(self.as_ptr(), res))?; Ok(NativeWindow::clone_from_ptr(ptr)) } } - pub fn get_width(&self) -> Result { + #[doc(alias = "AImageReader_getWidth")] + pub fn width(&self) -> Result { construct(|res| unsafe { ffi::AImageReader_getWidth(self.as_ptr(), res) }) } - pub fn get_height(&self) -> Result { + #[doc(alias = "AImageReader_getHeight")] + pub fn height(&self) -> Result { construct(|res| unsafe { ffi::AImageReader_getHeight(self.as_ptr(), res) }) } - pub fn get_format(&self) -> Result { + #[doc(alias = "AImageReader_getFormat")] + pub fn format(&self) -> Result { let format = construct(|res| unsafe { ffi::AImageReader_getFormat(self.as_ptr(), res) })?; Ok((format as u32).try_into().unwrap()) } - pub fn get_max_images(&self) -> Result { + #[doc(alias = "AImageReader_getMaxImages")] + pub fn max_images(&self) -> Result { construct(|res| unsafe { ffi::AImageReader_getMaxImages(self.as_ptr(), res) }) } + #[doc(alias = "AImageReader_acquireNextImage")] pub fn acquire_next_image(&self) -> Result> { let res = construct_never_null(|res| unsafe { ffi::AImageReader_acquireNextImage(self.as_ptr(), res) @@ -221,6 +229,7 @@ impl ImageReader { /// /// #[cfg(feature = "api-level-26")] + #[doc(alias = "AImageReader_acquireNextImageAsync")] pub unsafe fn acquire_next_image_async(&self) -> Result<(Image, Option)> { let mut fence = MaybeUninit::uninit(); let inner = construct_never_null(|res| { @@ -235,6 +244,7 @@ impl ImageReader { }) } + #[doc(alias = "AImageReader_acquireLatestImage")] pub fn acquire_latest_image(&self) -> Result> { let res = construct_never_null(|res| unsafe { ffi::AImageReader_acquireLatestImage(self.as_ptr(), res) @@ -255,6 +265,7 @@ impl ImageReader { /// /// #[cfg(feature = "api-level-26")] + #[doc(alias = "AImageReader_acquireLatestImageAsync")] pub fn acquire_latest_image_async(&self) -> Result<(Image, Option)> { let mut fence = MaybeUninit::uninit(); let inner = construct_never_null(|res| unsafe { @@ -271,6 +282,7 @@ impl ImageReader { } impl Drop for ImageReader { + #[doc(alias = "AImageReader_delete")] fn drop(&mut self) { unsafe { ffi::AImageReader_delete(self.as_ptr()) }; } @@ -280,10 +292,12 @@ impl Drop for ImageReader { /// /// [`AImage *`]: https://developer.android.com/ndk/reference/group/media#aimage #[derive(Debug)] +#[doc(alias = "AImage")] pub struct Image { inner: NonNull, } +#[doc(alias = "AImageCropRect")] pub type CropRect = ffi::AImageCropRect; impl Image { @@ -291,7 +305,8 @@ impl Image { self.inner.as_ptr() } - pub fn get_plane_data(&self, plane_idx: i32) -> Result<&[u8]> { + #[doc(alias = "AImage_getPlaneData")] + pub fn plane_data(&self, plane_idx: i32) -> Result<&[u8]> { let mut result_ptr = MaybeUninit::uninit(); let mut result_len = MaybeUninit::uninit(); let status = unsafe { @@ -308,36 +323,44 @@ impl Image { }) } - pub fn get_plane_pixel_stride(&self, plane_idx: i32) -> Result { + #[doc(alias = "AImage_getPlanePixelStride")] + pub fn plane_pixel_stride(&self, plane_idx: i32) -> Result { construct(|res| unsafe { ffi::AImage_getPlanePixelStride(self.as_ptr(), plane_idx, res) }) } - pub fn get_plane_row_stride(&self, plane_idx: i32) -> Result { + #[doc(alias = "AImage_getPlaneRowStride")] + pub fn plane_row_stride(&self, plane_idx: i32) -> Result { construct(|res| unsafe { ffi::AImage_getPlaneRowStride(self.as_ptr(), plane_idx, res) }) } - pub fn get_crop_rect(&self) -> Result { + #[doc(alias = "AImage_getCropRect")] + pub fn crop_rect(&self) -> Result { construct(|res| unsafe { ffi::AImage_getCropRect(self.as_ptr(), res) }) } - pub fn get_width(&self) -> Result { + #[doc(alias = "AImage_getWidth")] + pub fn width(&self) -> Result { construct(|res| unsafe { ffi::AImage_getWidth(self.as_ptr(), res) }) } - pub fn get_height(&self) -> Result { + #[doc(alias = "AImage_getHeight")] + pub fn height(&self) -> Result { construct(|res| unsafe { ffi::AImage_getHeight(self.as_ptr(), res) }) } - pub fn get_format(&self) -> Result { + #[doc(alias = "AImage_getFormat")] + pub fn format(&self) -> Result { let format = construct(|res| unsafe { ffi::AImage_getFormat(self.as_ptr(), res) })?; Ok((format as u32).try_into().unwrap()) } - pub fn get_timestamp(&self) -> Result { + #[doc(alias = "AImage_getTimestamp")] + pub fn timestamp(&self) -> Result { construct(|res| unsafe { ffi::AImage_getTimestamp(self.as_ptr(), res) }) } - pub fn get_number_of_planes(&self) -> Result { + #[doc(alias = "AImage_getNumberOfPlanes")] + pub fn number_of_planes(&self) -> Result { construct(|res| unsafe { ffi::AImage_getNumberOfPlanes(self.as_ptr(), res) }) } @@ -345,7 +368,7 @@ impl Image { /// /// Note that no reference on the returned [`HardwareBuffer`] handle is acquired automatically. /// Once the [`Image`] or the parent [`ImageReader`] is deleted, the [`HardwareBuffer`] handle - /// from previous [`Image::get_hardware_buffer()`] becomes invalid. + /// from previous [`Image::hardware_buffer()`] becomes invalid. /// /// If the caller ever needs to hold on a reference to the [`HardwareBuffer`] handle after the /// [`Image`] or the parent [`ImageReader`] is deleted, it must call @@ -356,7 +379,8 @@ impl Image { /// [`ImageReader::set_buffer_removed_listener()`] to be notified when the buffer is no longer /// used by [`ImageReader`]. #[cfg(feature = "api-level-26")] - pub fn get_hardware_buffer(&self) -> Result { + #[doc(alias = "AImage_getHardwareBuffer")] + pub fn hardware_buffer(&self) -> Result { unsafe { let ptr = construct_never_null(|res| ffi::AImage_getHardwareBuffer(self.as_ptr(), res))?; @@ -365,6 +389,7 @@ impl Image { } #[cfg(feature = "api-level-26")] + #[doc(alias = "AImage_deleteAsync")] pub fn delete_async(self, release_fence_fd: OwnedFd) { unsafe { ffi::AImage_deleteAsync(self.as_ptr(), release_fence_fd.into_raw_fd()) }; std::mem::forget(self); @@ -372,6 +397,7 @@ impl Image { } impl Drop for Image { + #[doc(alias = "AImage_delete")] fn drop(&mut self) { unsafe { ffi::AImage_delete(self.as_ptr()) }; }