ndk/native_window: Add missing function wrappers (#425)

* ndk/native_window: Add `set_buffers_transform()` API

This was added to the NDK with API level 26 but never made it to Rust.
Allows the user to apply mirror and rotation effects.

* ndk/native_window: Add `try_allocate_buffers()` API

* ndk/native_window: Add `set_frame_rate*()` APIs since level 30/31

Author: MarijnS95

ndk/CHANGELOG.md

@@ -5,7 +5,7 @@
 - event: Add `tool_type` getter for `Pointer`. (#323)
 - input_queue: Allow any non-zero return code from `pre_dispatch()` again, as per documentation. (#325)
 - asset: Use entire asset length when mapping buffer. (#387)
-- Bump MSRV to 1.66 for `raw-window-handle 0.5.1`, `num_enum`'s `catch_all` with arbitrary enum discriminants. (#388,#431)
+- Bump MSRV to 1.66 for `raw-window-handle 0.5.1`, `num_enum`'s `catch_all` with arbitrary enum discriminants. (#388, #431)
 - Bump optional `jni` dependency for doctest example from `0.19` to `0.21`. (#390)
 - **Breaking:** Upgrade to [`ndk-sys 0.5.0`](../ndk-sys/CHANGELOG.md#050-TODO). (#370)
 - **Breaking:** Upgrade `bitflags` crate from `1` to `2`. (#394)
@@ -25,6 +25,7 @@
 - **Breaking:** Use `BorrowedFd` and `OwnedFd` to clarify possible ownership transitions. (#417)
 - **Breaking:** Upgrade to [`ndk-sys 0.5.0`](../ndk-sys/CHANGELOG.md#050-beta0-2023-08-15). (#420)
 - **Breaking:** bitmap: Provide detailed implementation for `AndroidBitmapInfoFlags`. (#424)
+- ndk/native_window: Add `set_buffers_transform()`, `try_allocate_buffers()` and `set_frame_rate*()`. (#425)
 - hardware_buffer: Add `id()` to retrieve a system-wide unique identifier for a `HardwareBuffer`. (#428)
 
 # 0.7.0 (2022-07-24)

ndk/Cargo.toml

@@ -13,7 +13,7 @@ repository = "https://github.com/rust-mobile/ndk"
 rust-version = "1.66"
 
 [features]
-all = ["audio", "bitmap","media", "api-level-30"]
+all = ["audio", "bitmap","media", "api-level-31"]
 
 audio = ["ffi/audio", "api-level-26"]
 bitmap = ["ffi/bitmap"]

ndk/src/audio.rs

@@ -451,9 +451,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 29.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `policy` - the desired level of opt-out from being captured.
+    /// - `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")]
@@ -474,9 +474,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `num_frames` - the desired buffer capacity in frames or 0 for unspecified
+    /// - `num_frames`: the desired buffer capacity in frames or 0 for unspecified
     pub fn buffer_capacity_in_frames(self, num_frames: i32) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setBufferCapacityInFrames(self.as_ptr(), num_frames) };
         self
@@ -494,9 +494,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `channel_count` - Number of channels desired.
+    /// - `channel_count`: Number of channels desired.
     pub fn channel_count(self, channel_count: i32) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setChannelCount(self.as_ptr(), channel_count) };
         self
@@ -512,9 +512,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 28.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `content_type` - the type of audio data, eg. [`AudioContentType::Speech`]
+    /// - `content_type`: the type of audio data, eg. [`AudioContentType::Speech`]
     #[cfg(feature = "api-level-28")]
     pub fn content_type(self, content_type: AudioContentType) -> Self {
         unsafe {
@@ -605,9 +605,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `device_id` - device identifier or 0 for unspecified
+    /// - `device_id`: device identifier or 0 for unspecified
     pub fn device_id(self, device_id: i32) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setDeviceId(self.as_ptr(), device_id) };
         self
@@ -619,9 +619,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `direction` - [`Output`][AudioDirection::Output] or [`Input`][AudioDirection::Input]
+    /// - `direction`: [`Output`][AudioDirection::Output] or [`Input`][AudioDirection::Input]
     pub fn direction(self, direction: AudioDirection) -> Self {
         unsafe {
             ffi::AAudioStreamBuilder_setDirection(
@@ -695,9 +695,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `format` - the sample data format.
+    /// - `format`: the sample data format.
     pub fn format(self, format: AudioFormat) -> Self {
         unsafe {
             ffi::AAudioStreamBuilder_setFormat(self.as_ptr(), format as ffi::aaudio_format_t)
@@ -727,7 +727,7 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// * `num_frames` - the desired buffer size in frames or 0 for unspecified
+    /// - `num_frames`: the desired buffer size in frames or 0 for unspecified
     pub fn frames_per_data_callback(self, num_frames: i32) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setFramesPerDataCallback(self.as_ptr(), num_frames) };
         self
@@ -745,9 +745,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 28.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `input_preset` - the desired configuration for recording
+    /// - `input_preset`: the desired configuration for recording
     #[cfg(feature = "api-level-28")]
     pub fn input_preset(self, input_preset: AudioInputPreset) -> Self {
         unsafe {
@@ -771,9 +771,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `mode` - the desired performance mode, eg. LowLatency
+    /// - `mode`: the desired performance mode, eg. LowLatency
     pub fn performance_mode(self, mode: AudioPerformanceMode) -> Self {
         unsafe {
             ffi::AAudioStreamBuilder_setPerformanceMode(
@@ -796,9 +796,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `sample_rate` - frames per second. Common rates include 44100 and 48000 Hz.
+    /// - `sample_rate`: frames per second. Common rates include 44100 and 48000 Hz.
     pub fn sample_rate(self, sample_rate: i32) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setSampleRate(self.as_ptr(), sample_rate) };
         self
@@ -830,9 +830,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 28.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `session_id` - an allocated sessionID or [`Option::None`] to allocate a new sessionID
+    /// - `session_id`: an allocated sessionID or [`Option::None`] to allocate a new sessionID
     #[cfg(feature = "api-level-28")]
     pub fn session_id(self, session_id_or_allocate: Option<SessionId>) -> Self {
         let session_id = match session_id_or_allocate {
@@ -854,9 +854,9 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `sharing_mode` - [`AudioSharingMode::Shared`] or [`AudioSharingMode::Exclusive`]
+    /// - `sharing_mode`: [`AudioSharingMode::Shared`] or [`AudioSharingMode::Exclusive`]
     pub fn sharing_mode(self, sharing_mode: AudioSharingMode) -> Self {
         unsafe {
             ffi::AAudioStreamBuilder_setSharingMode(
@@ -877,7 +877,7 @@ impl AudioStreamBuilder {
     ///
     /// Available since API level 28.
     ///
-    /// * `usage` - the desired usage, eg. [`AudioUsage::Game`]
+    /// - `usage`: the desired usage, eg. [`AudioUsage::Game`]
     #[cfg(feature = "api-level-28")]
     pub fn usage(self, usage: AudioUsage) -> Self {
         unsafe { ffi::AAudioStreamBuilder_setUsage(self.as_ptr(), usage as ffi::aaudio_usage_t) };
@@ -1207,11 +1207,11 @@ impl AudioStream {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `buffer` - The slice with the samples.
-    /// * `num_frames` - Number of frames to read. Only complete frames will be written.
-    /// * `timeout_nanoseconds` - Maximum number of nanoseconds to wait for completion.
+    /// - `buffer`: The slice with the samples.
+    /// - `num_frames`: Number of frames to read. Only complete frames will be written.
+    /// - `timeout_nanoseconds`: Maximum number of nanoseconds to wait for completion.
     ///
     /// # Safety
     /// `buffer` must be a valid pointer to at least `num_frames` samples.
@@ -1295,9 +1295,9 @@ impl AudioStream {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `num_frames` - requested number of frames that can be filled without blocking
+    /// - `num_frames`: requested number of frames that can be filled without blocking
     pub fn set_buffer_size_in_frames(&self, num_frames: i32) -> Result<i32> {
         let result = unsafe { ffi::AAudioStream_setBufferSizeInFrames(self.as_ptr(), num_frames) };
         AudioError::from_result(result, || result)
@@ -1342,11 +1342,11 @@ impl AudioStream {
     ///
     /// Available since API level 26.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `buffer` - The address of the first sample.
-    /// * `num_frames` - Number of frames to write. Only complete frames will be written.
-    /// * `timeout_nanoseconds` - Maximum number of nanoseconds to wait for completion.
+    /// - `buffer`: The address of the first sample.
+    /// - `num_frames`: Number of frames to write. Only complete frames will be written.
+    /// - `timeout_nanoseconds`: Maximum number of nanoseconds to wait for completion.
     ///
     /// # Safety
     /// `buffer` must be a valid pointer to at least `num_frames` samples.

ndk/src/font.rs

@@ -442,12 +442,12 @@ impl FontMatcher {
     /// Even if no font can render the given text, this function will return a non-null result for
     /// drawing Tofu character.
     ///
-    /// # Arguments
+    /// # Parameters
     ///
-    /// * `family_name`: A font family name.
-    /// * `text`: A UTF-16 encoded text buffer to be rendered. If an empty string is given, this
+    /// - `family_name`: A font family name.
+    /// - `text`: A UTF-16 encoded text buffer to be rendered. If an empty string is given, this
     ///   function will panic.
-    /// * `run_length_out`: Set this to [`Some`] if you want to get the length of the text run with
+    /// - `run_length_out`: Set this to [`Some`] if you want to get the length of the text run with
     ///   the font returned.
     pub fn match_font(
         &mut self,
@@ -483,8 +483,9 @@ impl FontMatcher {
     ///
     /// If this function is not called, the match is performed with an empty locale list.
     ///
-    /// # Arguments
-    /// * `language_tags`: comma separated IETF BCP47 compliant language tags.
+    /// # Parameters
+    ///
+    /// - `language_tags`: comma separated IETF BCP47 compliant language tags.
     pub fn set_locales(&mut self, language_tags: &CStr) {
         unsafe { ffi::AFontMatcher_setLocales(self.ptr.as_ptr(), language_tags.as_ptr()) }
     }