bitmap: Strip off repeated Android prefix from structs and enums (#430)

This convention is already applied to `(Android)BitmapError` and
`(Android)BitmapFormat`, and to many other `A`-prefixed structs
elsewhere in the `ndk` crate: there is no need to repeat the Android
prefix or letter when describing strucures and enumerations.

Also strip off the `Bitmap` prefix in a `Result` alias, which isn't
common either when only filling in a default for the generic `Error`
argument.

Author: MarijnS95

ndk/CHANGELOG.md

@@ -18,15 +18,16 @@
 - native_window: Add `lock()` to blit raw pixel data. (#404)
 - hardware_buffer_format: Add `YCbCr_P010` and `R8_UNORM` variants. (#405)
 - **Breaking:** hardware_buffer_format: Add catch-all variant. (#407)
-- ndk/asset: Add missing `is_allocated()` and `open_file_descriptor()` methods. (#409)
+- asset: Add missing `is_allocated()` and `open_file_descriptor()` methods. (#409)
 - **Breaking:** media_codec: Add support for asynchronous notification callbacks. (#410)
 - Add panic guards to callbacks. (#412)
 - looper: Add `remove_fd()` to unregister events/callbacks for a file descriptor. (#416)
 - **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)
+- 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)
+- **Breaking:** bitmap: Strip `Android` prefix from structs and enums, and `Bitmap` from `Result`. (#430)
 
 # 0.7.0 (2022-07-24)
 

ndk/src/bitmap.rs

@@ -25,10 +25,10 @@ pub enum BitmapError {
     JniException = ffi::ANDROID_BITMAP_RESULT_JNI_EXCEPTION,
 }
 
-pub type BitmapResult<T, E = BitmapError> = Result<T, E>;
+pub type Result<T, E = BitmapError> = std::result::Result<T, E>;
 
 impl BitmapError {
-    pub(crate) fn from_status(status: i32) -> BitmapResult<()> {
+    pub(crate) fn from_status(status: i32) -> Result<()> {
         Err(match status {
             ffi::ANDROID_BITMAP_RESULT_SUCCESS => return Ok(()),
             ffi::ANDROID_BITMAP_RESULT_ALLOCATION_FAILED => BitmapError::AllocationFailed,
@@ -39,7 +39,7 @@ impl BitmapError {
     }
 }
 
-fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> BitmapResult<T> {
+fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> Result<T> {
     let mut result = MaybeUninit::uninit();
     let status = with_ptr(result.as_mut_ptr());
     BitmapError::from_status(status).map(|()| unsafe { result.assume_init() })
@@ -48,6 +48,7 @@ fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> BitmapResult<T> {
 #[repr(u32)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, IntoPrimitive, TryFromPrimitive)]
 #[allow(non_camel_case_types)]
+#[doc(alias = "AndroidBitmapFormat")]
 pub enum BitmapFormat {
     #[doc(alias = "ANDROID_BITMAP_FORMAT_NONE")]
     NONE = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_NONE.0,
@@ -70,13 +71,13 @@ pub enum BitmapFormat {
 ///
 /// [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
 #[derive(Debug)]
-pub struct AndroidBitmap {
+pub struct Bitmap {
     env: *mut JNIEnv,
     inner: jobject,
 }
 
-impl AndroidBitmap {
-    /// Create an [`AndroidBitmap`] wrapper from JNI pointers
+impl Bitmap {
+    /// Create a [`Bitmap`] wrapper from JNI pointers
     ///
     /// # Safety
     /// This function should be called with a healthy JVM pointer and with a non-null
@@ -87,43 +88,43 @@ impl AndroidBitmap {
         Self { env, inner: bitmap }
     }
 
-    /// Fills out and returns the [`AndroidBitmapInfo`] struct for the given Java bitmap object.
+    /// Fills out and returns the [`BitmapInfo`] struct for the given Java bitmap object.
     #[doc(alias = "AndroidBitmap_getInfo")]
-    pub fn get_info(&self) -> BitmapResult<AndroidBitmapInfo> {
+    pub fn get_info(&self) -> Result<BitmapInfo> {
         let inner =
             construct(|res| unsafe { ffi::AndroidBitmap_getInfo(self.env, self.inner, res) })?;
 
-        Ok(AndroidBitmapInfo { inner })
+        Ok(BitmapInfo { inner })
     }
 
     /// Attempt to lock the pixel address.
     ///
     /// Locking will ensure that the memory for the pixels will not move until the
-    /// [`AndroidBitmap::unlock_pixels()`] call, and ensure that, if the pixels had been previously
-    /// purged, they will have been restored.
+    /// [`Bitmap::unlock_pixels()`] call, and ensure that, if the pixels had been previously purged,
+    /// they will have been restored.
     ///
-    /// If this call succeeds, it must be balanced by a call to [`AndroidBitmap::unlock_pixels()`],
-    /// after which time the address of the pixels should no longer be used.
+    /// If this call succeeds, it must be balanced by a call to [`Bitmap::unlock_pixels()`], after
+    /// which time the address of the pixels should no longer be used.
     #[doc(alias = "AndroidBitmap_lockPixels")]
-    pub fn lock_pixels(&self) -> BitmapResult<*mut std::os::raw::c_void> {
+    pub fn lock_pixels(&self) -> Result<*mut std::os::raw::c_void> {
         construct(|res| unsafe { ffi::AndroidBitmap_lockPixels(self.env, self.inner, res) })
     }
 
-    /// Call this to balance a successful call to [`AndroidBitmap::lock_pixels()`].
+    /// Call this to balance a successful call to [`Bitmap::lock_pixels()`].
     #[doc(alias = "AndroidBitmap_unlockPixels")]
-    pub fn unlock_pixels(&self) -> BitmapResult<()> {
+    pub fn unlock_pixels(&self) -> Result<()> {
         let status = unsafe { ffi::AndroidBitmap_unlockPixels(self.env, self.inner) };
         BitmapError::from_status(status)
     }
 
     /// Retrieve the native object associated with an [`ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE`]
-    /// [`AndroidBitmap`] (requires [`AndroidBitmapInfoFlags::is_hardware()`] on
-    /// [`AndroidBitmapInfo::flags()`] to return [`true`]).
+    /// [`Bitmap`] (requires [`BitmapInfoFlags::is_hardware()`] on [`BitmapInfo::flags()`] to return
+    /// [`true`]).
     ///
-    /// Client must not modify it while an [`AndroidBitmap`] is wrapping it.
+    /// 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) -> BitmapResult<HardwareBufferRef> {
+    pub fn get_hardware_buffer(&self) -> Result<HardwareBufferRef> {
         unsafe {
             let result =
                 construct(|res| ffi::AndroidBitmap_getHardwareBuffer(self.env, self.inner, res))?;
@@ -137,10 +138,11 @@ impl AndroidBitmap {
     }
 }
 
-/// Possible values for [`ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK`] within [`AndroidBitmapInfoFlags`]
+/// Possible values for [`ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK`] within [`BitmapInfoFlags`]
 #[cfg(feature = "api-level-30")]
 #[derive(Clone, Copy, Debug)]
-pub enum AndroidBitmapInfoFlagsAlpha {
+#[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_MASK")]
+pub enum BitmapInfoFlagsAlpha {
     /// Pixel components are premultiplied by alpha.
     #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_PREMUL")]
     Premultiplied,
@@ -154,16 +156,16 @@ pub enum AndroidBitmapInfoFlagsAlpha {
 
 /// Bitfield containing information about the bitmap.
 #[cfg(feature = "api-level-30")]
-#[derive(Clone, Copy, Hash, PartialEq, Eq)]
 #[repr(transparent)]
-pub struct AndroidBitmapInfoFlags(u32);
+#[derive(Clone, Copy, Hash, PartialEq, Eq)]
+pub struct BitmapInfoFlags(u32);
 
 #[cfg(feature = "api-level-30")]
-impl std::fmt::Debug for AndroidBitmapInfoFlags {
+impl std::fmt::Debug for BitmapInfoFlags {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
             f,
-            "AndroidBitmapInfoFlags({:#x}, alpha: {:?}, is_hardware: {})",
+            "BitmapInfoFlags({:#x}, alpha: {:?}, is_hardware: {})",
             self.0,
             self.alpha(),
             self.is_hardware()
@@ -172,25 +174,23 @@ impl std::fmt::Debug for AndroidBitmapInfoFlags {
 }
 
 #[cfg(feature = "api-level-30")]
-impl AndroidBitmapInfoFlags {
+impl BitmapInfoFlags {
     /// Returns the alpha value contained in the [`ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK`] bit range
     #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_MASK")]
-    pub fn alpha(self) -> AndroidBitmapInfoFlagsAlpha {
+    pub fn alpha(self) -> BitmapInfoFlagsAlpha {
         // Note that ffi::ANDROID_BITMAP_FLAGS_ALPHA_SHIFT is 0 and hence irrelevant.
         match self.0 & ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK {
-            ffi::ANDROID_BITMAP_FLAGS_ALPHA_PREMUL => AndroidBitmapInfoFlagsAlpha::Premultiplied,
-            ffi::ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE => AndroidBitmapInfoFlagsAlpha::Opaque,
-            ffi::ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL => {
-                AndroidBitmapInfoFlagsAlpha::Unpremultiplied
-            }
+            ffi::ANDROID_BITMAP_FLAGS_ALPHA_PREMUL => BitmapInfoFlagsAlpha::Premultiplied,
+            ffi::ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE => BitmapInfoFlagsAlpha::Opaque,
+            ffi::ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL => BitmapInfoFlagsAlpha::Unpremultiplied,
             3 => todo!("ALPHA_MASK value 3"),
             _ => unreachable!(),
         }
     }
 
     /// Returns [`true`] when [`ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE`] is set, meaning this
-    /// [`AndroidBitmap`] uses "HARDWARE Config" and its [`HardwareBufferRef`] can be retrieved via
-    /// [`AndroidBitmap::get_hardware_buffer()`].
+    /// [`Bitmap`] uses "HARDWARE Config" and its [`HardwareBufferRef`] can be retrieved via
+    /// [`Bitmap::get_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.
@@ -202,13 +202,14 @@ impl AndroidBitmapInfoFlags {
 ///
 /// [`AndroidBitmapInfo`]: https://developer.android.com/ndk/reference/struct/android-bitmap-info#struct_android_bitmap_info
 #[derive(Clone, Copy)]
-pub struct AndroidBitmapInfo {
+#[doc(alias = "AndroidBitmapInfo")]
+pub struct BitmapInfo {
     inner: ffi::AndroidBitmapInfo,
 }
 
-impl std::fmt::Debug for AndroidBitmapInfo {
+impl std::fmt::Debug for BitmapInfo {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        let mut f = f.debug_struct("AndroidBitmapInfo");
+        let mut f = f.debug_struct("BitmapInfo");
         f.field("width", &self.width())
             .field("height", &self.height())
             .field("stride", &self.stride())
@@ -221,7 +222,7 @@ impl std::fmt::Debug for AndroidBitmapInfo {
     }
 }
 
-impl AndroidBitmapInfo {
+impl BitmapInfo {
     /// The bitmap width in pixels.
     pub fn width(&self) -> u32 {
         self.inner.width
@@ -242,8 +243,8 @@ impl AndroidBitmapInfo {
     /// # Panics
     ///
     /// This function panics if the underlying value does not have a corresponding variant in
-    /// [`BitmapFormat`]. Use [`try_format()`][AndroidBitmapInfo::try_format()] for an infallible
-    /// version of this function.
+    /// [`BitmapFormat`]. Use [`try_format()`][BitmapInfo::try_format()] for an infallible version
+    /// of this function.
     pub fn format(&self) -> BitmapFormat {
         self.try_format().unwrap()
     }
@@ -258,7 +259,7 @@ impl AndroidBitmapInfo {
 
     /// Bitfield containing information about the bitmap.
     #[cfg(feature = "api-level-30")]
-    pub fn flags(&self) -> AndroidBitmapInfoFlags {
-        AndroidBitmapInfoFlags(self.inner.flags)
+    pub fn flags(&self) -> BitmapInfoFlags {
+        BitmapInfoFlags(self.inner.flags)
     }
 }