From 50c01261d042ee1ff9a29b4d418f820d90da0684 Mon Sep 17 00:00:00 2001 From: Alexander Koz Date: Sun, 24 Sep 2023 18:26:57 +0400 Subject: [PATCH] improve docs including [missed `getDisplayBufferBitmap`][link] [link]: https://devforum.play.date/t/mistake-in-c-documentation-getdisplaybufferbitmap/6722/5 --- Cargo.lock | 2 +- api/gfx/Cargo.toml | 2 +- api/gfx/src/bitmap/bitmap.rs | 95 +++++++++++++++++++++++++++++++++--- api/gfx/src/bitmap/table.rs | 33 +++++++++++++ api/gfx/src/lib.rs | 2 +- api/gfx/src/text.rs | 2 +- 6 files changed, 124 insertions(+), 12 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9f69bf5c..d3adf4c4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2593,7 +2593,7 @@ dependencies = [ [[package]] name = "playdate-graphics" -version = "0.2.1" +version = "0.2.2" dependencies = [ "playdate-color", "playdate-fs", diff --git a/api/gfx/Cargo.toml b/api/gfx/Cargo.toml index 359880bb..e3ec485e 100644 --- a/api/gfx/Cargo.toml +++ b/api/gfx/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "playdate-graphics" -version = "0.2.1" +version = "0.2.2" readme = "README.md" description = "High-level graphics API built on-top of Playdate API" keywords = ["playdate", "sdk", "api", "gamedev"] diff --git a/api/gfx/src/bitmap/bitmap.rs b/api/gfx/src/bitmap/bitmap.rs index 6e7b7e00..593c617e 100644 --- a/api/gfx/src/bitmap/bitmap.rs +++ b/api/gfx/src/bitmap/bitmap.rs @@ -1,4 +1,4 @@ -//! Playdate Bitmap API +//! Playdate bitmap API use core::ffi::c_char; use core::ffi::c_float; @@ -117,14 +117,22 @@ impl<'owner> BitmapRef<'owner> { } -// TODO: Properly document methods of `Bitmap`. impl Bitmap { + /// Allocates and returns a new `width` by `height` Bitmap filled with `bg` color. + /// + /// Calls [`sys::ffi::playdate_graphics::newBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::newBitmap")] pub fn new(width: c_int, height: c_int, bg: Color) -> Result where Api: Default { let api = Api::default(); Self::new_with(api, width, height, bg) } + /// Allocates and returns a new `width` by `height` Bitmap filled with `bg` color, + /// using the given `api`. + /// + /// Calls [`sys::ffi::playdate_graphics::newBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::newBitmap")] pub fn new_with(api: Api, width: c_int, height: c_int, bg: Color) -> Result { let f = api.new_bitmap(); let ptr = unsafe { f(width, height, bg.into()) }; @@ -137,6 +145,9 @@ impl Bitmap { /// Load a bitmap from a file. + /// + /// Calls [`sys::ffi::playdate_graphics::loadBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadBitmap")] pub fn load>(path: P) -> Result where Api: Default { let api = Api::default(); @@ -144,7 +155,10 @@ impl Bitmap { } /// Load a bitmap from a file, - /// create new bitmap with given api-access-point. + /// create new bitmap with given `api`. + /// + /// Calls [`sys::ffi::playdate_graphics::loadBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadBitmap")] pub fn load_with>(api: Api, path: P) -> Result { let mut err = Box::new(core::ptr::null() as *const c_char); let out_err = Box::into_raw(err); @@ -168,6 +182,10 @@ impl Bitmap { impl Bitmap { + /// Load a bitmap from a file into `self`. + /// + /// Calls [`sys::ffi::playdate_graphics::loadIntoBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadIntoBitmap")] pub fn load_into>(&mut self, path: P) -> Result<(), ApiError> { let mut err = Box::new(core::ptr::null() as *const c_char); let out_err = Box::into_raw(err); @@ -197,6 +215,11 @@ impl Drop for Bitmap { } impl Clone for Bitmap { + /// Allocates and returns a new `Bitmap` that is an exact copy of `self`, + /// __not a reference__. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::copyBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::copyBitmap")] fn clone(&self) -> Self { let f = self.1.copy_bitmap(); let ptr = unsafe { f(self.0) }; @@ -210,12 +233,20 @@ impl Clone for Bitmap { impl Bitmap { + /// Clears bitmap, filling with the given `bg` color. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::clearBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::clearBitmap")] pub fn clear(&self, bg: Color) { let f = self.1.clear_bitmap(); unsafe { f(self.0, bg.into()) }; } + /// Returns mutable borrow of bitmap-data by this bitmap. + /// + /// Calls [`sys::ffi::playdate_graphics::getBitmapData`]. + #[doc(alias = "sys::ffi::playdate_graphics::getBitmapData")] pub fn bitmap_data<'bitmap>(&'bitmap mut self) -> Result, Error> { let mut width: c_int = 0; let mut height: c_int = 0; @@ -262,7 +293,11 @@ impl Bitmap { } - /// Sets a mask image for the given bitmap. The set mask must be the same size as the target bitmap. + /// Sets a mask image for the bitmap. + /// The set mask must be the same size as the `self` bitmap. + /// + /// Calls [`sys::ffi::playdate_graphics::setBitmapMask`]. + #[doc(alias = "sys::ffi::playdate_graphics::setBitmapMask")] pub fn set_mask(&self, mask: &mut Bitmap) -> Result<(), Error> { // TODO: investigate is it correct "res == 0 => Ok" let f = self.1.set_bitmap_mask(); @@ -278,6 +313,9 @@ impl Bitmap { /// If the image doesn’t have a mask, returns None. /// /// Clones inner api-access. + /// + /// Calls [`sys::ffi::playdate_graphics::getBitmapMask`]. + #[doc(alias = "sys::ffi::playdate_graphics::getBitmapMask")] #[inline(always)] pub fn mask(&self) -> Option> where Api: Clone { @@ -288,6 +326,9 @@ impl Bitmap { /// If the image doesn’t have a mask, returns None. /// /// Produced `Bitmap` uses passed `api` api-access. + /// + /// Calls [`sys::ffi::playdate_graphics::getBitmapMask`]. + #[doc(alias = "sys::ffi::playdate_graphics::getBitmapMask")] // XXX: investigate is it should be free-on-drop? pub fn mask_with(&self, api: NewApi) -> Option> { let f = self.1.get_bitmap_mask(); @@ -299,7 +340,10 @@ impl Bitmap { } } - /// Returns a new, rotated and scaled Bitmap based on the given bitmap. + /// Returns a new, rotated and scaled Bitmap based on the bitmap. + /// + /// Calls [`sys::ffi::playdate_graphics::rotatedBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::rotatedBitmap")] #[inline(always)] pub fn rotated_clone(&self, rotation: c_float, @@ -311,6 +355,10 @@ impl Bitmap { self.rotated_clone_with(self.1.clone(), rotation, x_scale, y_scale) } + /// Returns a new, rotated and scaled Bitmap based on the bitmap using given `api`. + /// + /// Calls [`sys::ffi::playdate_graphics::rotatedBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::rotatedBitmap")] pub fn rotated_clone_with(&self, api: NewApi, rotation: c_float, @@ -332,12 +380,22 @@ impl Bitmap { } + /// Draws `self` with its upper-left corner at location `x`, `y`, + /// using the given `flip` orientation. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::drawBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::drawBitmap")] #[inline(always)] pub fn draw(&self, x: c_int, y: c_int, flip: BitmapFlip) { let f = self.1.draw_bitmap(); unsafe { f(self.0, x, y, flip) } } + /// Draws `self` with its upper-left corner at location `x`, `y` + /// __tiled inside a `width` by `height` rectangle__. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::tileBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::tileBitmap")] #[inline(always)] pub fn draw_tiled(&self, x: c_int, y: c_int, width: c_int, height: c_int, flip: BitmapFlip) { let f = self.1.tile_bitmap(); @@ -352,6 +410,7 @@ impl Bitmap { /// * if `center_x` and `center_y` are both 0 the top left corner of the image (before rotation) is at (`x`,`y`), etc. /// /// Equivalent to [`sys::ffi::playdate_graphics::drawRotatedBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::drawRotatedBitmap")] #[inline(always)] pub fn draw_rotated(&self, x: c_int, @@ -365,6 +424,12 @@ impl Bitmap { unsafe { f(self.0, x, y, degrees, center_x, center_y, x_scale, y_scale) } } + /// Draws this bitmap scaled to `x_scale` and `y_scale` with its upper-left corner at location `x`, `y`. + /// + /// Note that flip is not available when drawing scaled bitmaps but negative scale values will achieve the same effect. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::drawScaledBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::drawScaledBitmap")] #[inline(always)] pub fn draw_scaled(&self, x: c_int, y: c_int, x_scale: c_float, y_scale: c_float) { let f = self.1.draw_scaled_bitmap(); @@ -372,8 +437,13 @@ impl Bitmap { } - /// Returns `true` if any of the opaque pixels in this bitmap when positioned at `x, y` with `flip` overlap any of the opaque pixels in `other` bitmap at `x_other`, `y_other` with `flip_other` within the non-empty `rect`, + /// Returns `true` if any of the opaque pixels in this bitmap when positioned at `x, y` with `flip` + /// overlap any of the opaque pixels in `other` bitmap at `x_other`, `y_other` with `flip_other` + /// within the non-empty `rect`, /// or `false` if no pixels overlap or if one or both fall completely outside of `rect`. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::checkMaskCollision`]. + #[doc(alias = "sys::ffi::playdate_graphics::checkMaskCollision")] #[inline(always)] pub fn check_mask_collision(&self, x: c_int, @@ -390,8 +460,11 @@ impl Bitmap { } - /// Sets `color` to an 8 x 8 pattern using this bitmap. + /// Sets `color` to an `8 x 8` pattern using this bitmap. /// `x, y` indicates the top left corner of the 8 x 8 pattern. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::setColorToPattern`]. + #[doc(alias = "sys::ffi::playdate_graphics::setColorToPattern")] pub fn set_color_to_pattern(&self, color: &mut LCDColor, x: c_int, y: c_int) { let f = self.1.set_color_to_pattern(); unsafe { f(color as _, self.0, x, y) } @@ -399,7 +472,9 @@ impl Bitmap { } -/// The data is 1 bit per pixel packed format, in MSB order; in other words, the high bit of the first byte in data is the top left pixel of the image. +/// The data is 1 bit per pixel packed format, in MSB order; in other words, +/// the high bit of the first byte in data is the top left pixel of the image. +/// /// The `mask` data is in same format but means transparency. pub struct BitmapData<'bitmap> { pub width: c_int, @@ -441,6 +516,10 @@ pub fn debug_bitmap() -> Result, ApiError> { } } +/// Returns a bitmap containing the contents of the display buffer. +/// +/// __The system owns this bitmap—​do not free it.__ +/// /// Equivalent to [`sys::ffi::playdate_graphics::getDisplayBufferBitmap`]. #[doc(alias = "sys::ffi::playdate_graphics::getDisplayBufferBitmap")] pub fn display_buffer_bitmap() -> Result, Error> { diff --git a/api/gfx/src/bitmap/table.rs b/api/gfx/src/bitmap/table.rs index 45ab3d80..25411e37 100644 --- a/api/gfx/src/bitmap/table.rs +++ b/api/gfx/src/bitmap/table.rs @@ -1,3 +1,5 @@ +//! Playdate bitmap-table API + use alloc::boxed::Box; use core::ffi::c_char; use core::ffi::c_int; @@ -27,12 +29,21 @@ impl Drop for BitmapTable { impl BitmapTable { + /// Allocates and returns a new [`BitmapTable`] that can hold count `width` by `height` [`Bitmap`]s. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::newBitmapTable`]. + #[doc(alias = "sys::ffi::playdate_graphics::newBitmapTable")] pub fn new(count: c_int, width: c_int, height: c_int) -> Result where Api: Default { let api = Api::default(); Self::new_with(api, count, width, height) } + /// Allocates and returns a new [`BitmapTable`] that can hold count `width` by `height` [`Bitmap`]s, + /// using the given `api`. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::newBitmapTable`]. + #[doc(alias = "sys::ffi::playdate_graphics::newBitmapTable")] pub fn new_with(api: Api, count: c_int, width: c_int, height: c_int) -> Result { let f = api.new_bitmap_table(); let ptr = unsafe { f(count, width, height) }; @@ -44,12 +55,24 @@ impl BitmapTable { } + /// Allocates and returns a new [`Bitmap`] from the file at `path`. + /// + /// If there is no file at `path`, the function returns error. + /// + /// Calls [`sys::ffi::playdate_graphics::loadBitmapTable`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadBitmapTable")] pub fn load>(path: P) -> Result where Api: Default { let api = Api::default(); Self::load_with(api, path) } + /// Allocates and returns a new [`Bitmap`] from the file at `path`. + /// + /// If there is no file at `path`, the function returns error. + /// + /// Calls [`sys::ffi::playdate_graphics::loadBitmapTable`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadBitmapTable")] pub fn load_with>(api: Api, path: P) -> Result { let mut err = Box::new(core::ptr::null() as *const c_char); let out_err = Box::into_raw(err); @@ -72,6 +95,10 @@ impl BitmapTable { } impl BitmapTable { + /// Loads the image-table at `path` into the previously allocated this table. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::loadIntoBitmapTable`]. + #[doc(alias = "sys::ffi::playdate_graphics::loadIntoBitmapTable")] pub fn load_into>(&mut self, path: P) -> Result<(), ApiError> { let mut err = Box::new(core::ptr::null() as *const c_char); let out_err = Box::into_raw(err); @@ -93,6 +120,9 @@ impl BitmapTable { /// if `index` is out of bounds, the function returns `None`. /// /// Creates new default api access-point. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::getTableBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::getTableBitmap")] pub fn get<'table, BitApi: BitmapApi>(&'table self, index: c_int) -> Option> where Bitmap: 'table, BitApi: Default { @@ -103,6 +133,9 @@ impl BitmapTable { /// if `index` is out of bounds, the function returns `None`. /// /// Produced `Bitmap` uses passed `api` access-point. + /// + /// Equivalent to [`sys::ffi::playdate_graphics::getTableBitmap`]. + #[doc(alias = "sys::ffi::playdate_graphics::getTableBitmap")] pub fn get_with<'table, BitApi: BitmapApi>(&'table self, api: BitApi, index: c_int) diff --git a/api/gfx/src/lib.rs b/api/gfx/src/lib.rs index e3c80451..6f5535dc 100644 --- a/api/gfx/src/lib.rs +++ b/api/gfx/src/lib.rs @@ -1,4 +1,4 @@ -//! Playdate Graphics API +//! Playdate graphics API #![cfg_attr(not(test), no_std)] #![feature(error_in_core)] diff --git a/api/gfx/src/text.rs b/api/gfx/src/text.rs index 42015737..7fdae419 100644 --- a/api/gfx/src/text.rs +++ b/api/gfx/src/text.rs @@ -1,4 +1,4 @@ -//! Playdate Text API +//! Playdate text API use core::ffi::{c_int, c_char};