Skip to content

Commit 543ca3a

Browse files
boozookboozook
authored
Merge pull request #113 from boozook/api/gfx-docs
Improve docs in graphics crate
2 parents bfc9a28 + 50c0126 commit 543ca3a

File tree

6 files changed

+124
-12
lines changed

6 files changed

+124
-12
lines changed

‎Cargo.lock

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/gfx/Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "playdate-graphics"
3-
version = "0.2.1"
3+
version = "0.2.2"
44
readme = "README.md"
55
description = "High-level graphics API built on-top of Playdate API"
66
keywords = ["playdate", "sdk", "api", "gamedev"]

‎api/gfx/src/bitmap/bitmap.rs

Lines changed: 87 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! Playdate Bitmap API
1+
//! Playdate bitmap API
22
33
use core::ffi::c_char;
44
use core::ffi::c_float;
@@ -117,14 +117,22 @@ impl<'owner> BitmapRef<'owner> {
117117
}
118118

119119

120-
// TODO: Properly document methods of `Bitmap`.
121120
impl<Api: api::Api> Bitmap<Api, true> {
121+
/// Allocates and returns a new `width` by `height` Bitmap filled with `bg` color.
122+
///
123+
/// Calls [`sys::ffi::playdate_graphics::newBitmap`].
124+
#[doc(alias = "sys::ffi::playdate_graphics::newBitmap")]
122125
pub fn new(width: c_int, height: c_int, bg: Color) -> Result<Self, Error>
123126
where Api: Default {
124127
let api = Api::default();
125128
Self::new_with(api, width, height, bg)
126129
}
127130

131+
/// Allocates and returns a new `width` by `height` Bitmap filled with `bg` color,
132+
/// using the given `api`.
133+
///
134+
/// Calls [`sys::ffi::playdate_graphics::newBitmap`].
135+
#[doc(alias = "sys::ffi::playdate_graphics::newBitmap")]
128136
pub fn new_with(api: Api, width: c_int, height: c_int, bg: Color) -> Result<Self, Error> {
129137
let f = api.new_bitmap();
130138
let ptr = unsafe { f(width, height, bg.into()) };
@@ -137,14 +145,20 @@ impl<Api: api::Api> Bitmap<Api, true> {
137145

138146

139147
/// Load a bitmap from a file.
148+
///
149+
/// Calls [`sys::ffi::playdate_graphics::loadBitmap`].
150+
#[doc(alias = "sys::ffi::playdate_graphics::loadBitmap")]
140151
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, ApiError>
141152
where Api: Default {
142153
let api = Api::default();
143154
Self::load_with(api, path)
144155
}
145156

146157
/// Load a bitmap from a file,
147-
/// create new bitmap with given api-access-point.
158+
/// create new bitmap with given `api`.
159+
///
160+
/// Calls [`sys::ffi::playdate_graphics::loadBitmap`].
161+
#[doc(alias = "sys::ffi::playdate_graphics::loadBitmap")]
148162
pub fn load_with<P: AsRef<Path>>(api: Api, path: P) -> Result<Self, ApiError> {
149163
let mut err = Box::new(core::ptr::null() as *const c_char);
150164
let out_err = Box::into_raw(err);
@@ -168,6 +182,10 @@ impl<Api: api::Api> Bitmap<Api, true> {
168182

169183

170184
impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
185+
/// Load a bitmap from a file into `self`.
186+
///
187+
/// Calls [`sys::ffi::playdate_graphics::loadIntoBitmap`].
188+
#[doc(alias = "sys::ffi::playdate_graphics::loadIntoBitmap")]
171189
pub fn load_into<P: AsRef<Path>>(&mut self, path: P) -> Result<(), ApiError> {
172190
let mut err = Box::new(core::ptr::null() as *const c_char);
173191
let out_err = Box::into_raw(err);
@@ -197,6 +215,11 @@ impl<Api: api::Api, const FOD: bool> Drop for Bitmap<Api, FOD> {
197215
}
198216

199217
impl<Api: api::Api + Clone> Clone for Bitmap<Api, true> {
218+
/// Allocates and returns a new `Bitmap` that is an exact copy of `self`,
219+
/// __not a reference__.
220+
///
221+
/// Equivalent to [`sys::ffi::playdate_graphics::copyBitmap`].
222+
#[doc(alias = "sys::ffi::playdate_graphics::copyBitmap")]
200223
fn clone(&self) -> Self {
201224
let f = self.1.copy_bitmap();
202225
let ptr = unsafe { f(self.0) };
@@ -210,12 +233,20 @@ impl<Api: api::Api + Clone> Clone for Bitmap<Api, true> {
210233

211234

212235
impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
236+
/// Clears bitmap, filling with the given `bg` color.
237+
///
238+
/// Equivalent to [`sys::ffi::playdate_graphics::clearBitmap`].
239+
#[doc(alias = "sys::ffi::playdate_graphics::clearBitmap")]
213240
pub fn clear(&self, bg: Color) {
214241
let f = self.1.clear_bitmap();
215242
unsafe { f(self.0, bg.into()) };
216243
}
217244

218245

246+
/// Returns mutable borrow of bitmap-data by this bitmap.
247+
///
248+
/// Calls [`sys::ffi::playdate_graphics::getBitmapData`].
249+
#[doc(alias = "sys::ffi::playdate_graphics::getBitmapData")]
219250
pub fn bitmap_data<'bitmap>(&'bitmap mut self) -> Result<BitmapData<'bitmap>, Error> {
220251
let mut width: c_int = 0;
221252
let mut height: c_int = 0;
@@ -262,7 +293,11 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
262293
}
263294

264295

265-
/// Sets a mask image for the given bitmap. The set mask must be the same size as the target bitmap.
296+
/// Sets a mask image for the bitmap.
297+
/// The set mask must be the same size as the `self` bitmap.
298+
///
299+
/// Calls [`sys::ffi::playdate_graphics::setBitmapMask`].
300+
#[doc(alias = "sys::ffi::playdate_graphics::setBitmapMask")]
266301
pub fn set_mask<Api2: api::Api, const FREE: bool>(&self, mask: &mut Bitmap<Api2, FREE>) -> Result<(), Error> {
267302
// TODO: investigate is it correct "res == 0 => Ok"
268303
let f = self.1.set_bitmap_mask();
@@ -278,6 +313,9 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
278313
/// If the image doesn’t have a mask, returns None.
279314
///
280315
/// Clones inner api-access.
316+
///
317+
/// Calls [`sys::ffi::playdate_graphics::getBitmapMask`].
318+
#[doc(alias = "sys::ffi::playdate_graphics::getBitmapMask")]
281319
#[inline(always)]
282320
pub fn mask(&self) -> Option<Bitmap<Api, false>>
283321
where Api: Clone {
@@ -288,6 +326,9 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
288326
/// If the image doesn’t have a mask, returns None.
289327
///
290328
/// Produced `Bitmap` uses passed `api` api-access.
329+
///
330+
/// Calls [`sys::ffi::playdate_graphics::getBitmapMask`].
331+
#[doc(alias = "sys::ffi::playdate_graphics::getBitmapMask")]
291332
// XXX: investigate is it should be free-on-drop?
292333
pub fn mask_with<NewApi: api::Api>(&self, api: NewApi) -> Option<Bitmap<NewApi, false>> {
293334
let f = self.1.get_bitmap_mask();
@@ -299,7 +340,10 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
299340
}
300341
}
301342

302-
/// Returns a new, rotated and scaled Bitmap based on the given bitmap.
343+
/// Returns a new, rotated and scaled Bitmap based on the bitmap.
344+
///
345+
/// Calls [`sys::ffi::playdate_graphics::rotatedBitmap`].
346+
#[doc(alias = "sys::ffi::playdate_graphics::rotatedBitmap")]
303347
#[inline(always)]
304348
pub fn rotated_clone(&self,
305349
rotation: c_float,
@@ -311,6 +355,10 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
311355
self.rotated_clone_with(self.1.clone(), rotation, x_scale, y_scale)
312356
}
313357

358+
/// Returns a new, rotated and scaled Bitmap based on the bitmap using given `api`.
359+
///
360+
/// Calls [`sys::ffi::playdate_graphics::rotatedBitmap`].
361+
#[doc(alias = "sys::ffi::playdate_graphics::rotatedBitmap")]
314362
pub fn rotated_clone_with<NewApi: api::Api>(&self,
315363
api: NewApi,
316364
rotation: c_float,
@@ -332,12 +380,22 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
332380
}
333381

334382

383+
/// Draws `self` with its upper-left corner at location `x`, `y`,
384+
/// using the given `flip` orientation.
385+
///
386+
/// Equivalent to [`sys::ffi::playdate_graphics::drawBitmap`].
387+
#[doc(alias = "sys::ffi::playdate_graphics::drawBitmap")]
335388
#[inline(always)]
336389
pub fn draw(&self, x: c_int, y: c_int, flip: BitmapFlip) {
337390
let f = self.1.draw_bitmap();
338391
unsafe { f(self.0, x, y, flip) }
339392
}
340393

394+
/// Draws `self` with its upper-left corner at location `x`, `y`
395+
/// __tiled inside a `width` by `height` rectangle__.
396+
///
397+
/// Equivalent to [`sys::ffi::playdate_graphics::tileBitmap`].
398+
#[doc(alias = "sys::ffi::playdate_graphics::tileBitmap")]
341399
#[inline(always)]
342400
pub fn draw_tiled(&self, x: c_int, y: c_int, width: c_int, height: c_int, flip: BitmapFlip) {
343401
let f = self.1.tile_bitmap();
@@ -352,6 +410,7 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
352410
/// * if `center_x` and `center_y` are both 0 the top left corner of the image (before rotation) is at (`x`,`y`), etc.
353411
///
354412
/// Equivalent to [`sys::ffi::playdate_graphics::drawRotatedBitmap`].
413+
#[doc(alias = "sys::ffi::playdate_graphics::drawRotatedBitmap")]
355414
#[inline(always)]
356415
pub fn draw_rotated(&self,
357416
x: c_int,
@@ -365,15 +424,26 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
365424
unsafe { f(self.0, x, y, degrees, center_x, center_y, x_scale, y_scale) }
366425
}
367426

427+
/// Draws this bitmap scaled to `x_scale` and `y_scale` with its upper-left corner at location `x`, `y`.
428+
///
429+
/// Note that flip is not available when drawing scaled bitmaps but negative scale values will achieve the same effect.
430+
///
431+
/// Equivalent to [`sys::ffi::playdate_graphics::drawScaledBitmap`].
432+
#[doc(alias = "sys::ffi::playdate_graphics::drawScaledBitmap")]
368433
#[inline(always)]
369434
pub fn draw_scaled(&self, x: c_int, y: c_int, x_scale: c_float, y_scale: c_float) {
370435
let f = self.1.draw_scaled_bitmap();
371436
unsafe { f(self.0, x, y, x_scale, y_scale) }
372437
}
373438

374439

375-
/// 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`,
440+
/// Returns `true` if any of the opaque pixels in this bitmap when positioned at `x, y` with `flip`
441+
/// overlap any of the opaque pixels in `other` bitmap at `x_other`, `y_other` with `flip_other`
442+
/// within the non-empty `rect`,
376443
/// or `false` if no pixels overlap or if one or both fall completely outside of `rect`.
444+
///
445+
/// Equivalent to [`sys::ffi::playdate_graphics::checkMaskCollision`].
446+
#[doc(alias = "sys::ffi::playdate_graphics::checkMaskCollision")]
377447
#[inline(always)]
378448
pub fn check_mask_collision<OApi: api::Api, const OFOD: bool>(&self,
379449
x: c_int,
@@ -390,16 +460,21 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
390460
}
391461

392462

393-
/// Sets `color` to an 8 x 8 pattern using this bitmap.
463+
/// Sets `color` to an `8 x 8` pattern using this bitmap.
394464
/// `x, y` indicates the top left corner of the 8 x 8 pattern.
465+
///
466+
/// Equivalent to [`sys::ffi::playdate_graphics::setColorToPattern`].
467+
#[doc(alias = "sys::ffi::playdate_graphics::setColorToPattern")]
395468
pub fn set_color_to_pattern(&self, color: &mut LCDColor, x: c_int, y: c_int) {
396469
let f = self.1.set_color_to_pattern();
397470
unsafe { f(color as _, self.0, x, y) }
398471
}
399472
}
400473

401474

402-
/// 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.
475+
/// The data is 1 bit per pixel packed format, in MSB order; in other words,
476+
/// the high bit of the first byte in data is the top left pixel of the image.
477+
///
403478
/// The `mask` data is in same format but means transparency.
404479
pub struct BitmapData<'bitmap> {
405480
pub width: c_int,
@@ -441,6 +516,10 @@ pub fn debug_bitmap() -> Result<Bitmap<api::Default, false>, ApiError> {
441516
}
442517
}
443518

519+
/// Returns a bitmap containing the contents of the display buffer.
520+
///
521+
/// __The system owns this bitmap—​do not free it.__
522+
///
444523
/// Equivalent to [`sys::ffi::playdate_graphics::getDisplayBufferBitmap`].
445524
#[doc(alias = "sys::ffi::playdate_graphics::getDisplayBufferBitmap")]
446525
pub fn display_buffer_bitmap() -> Result<Bitmap<api::Default, false>, Error> {

‎api/gfx/src/bitmap/table.rs

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! Playdate bitmap-table API
2+
13
use alloc::boxed::Box;
24
use core::ffi::c_char;
35
use core::ffi::c_int;
@@ -27,12 +29,21 @@ impl<Api: api::Api, const FOD: bool> Drop for BitmapTable<Api, FOD> {
2729

2830

2931
impl<Api: api::Api> BitmapTable<Api, true> {
32+
/// Allocates and returns a new [`BitmapTable`] that can hold count `width` by `height` [`Bitmap`]s.
33+
///
34+
/// Equivalent to [`sys::ffi::playdate_graphics::newBitmapTable`].
35+
#[doc(alias = "sys::ffi::playdate_graphics::newBitmapTable")]
3036
pub fn new(count: c_int, width: c_int, height: c_int) -> Result<Self, Error>
3137
where Api: Default {
3238
let api = Api::default();
3339
Self::new_with(api, count, width, height)
3440
}
3541

42+
/// Allocates and returns a new [`BitmapTable`] that can hold count `width` by `height` [`Bitmap`]s,
43+
/// using the given `api`.
44+
///
45+
/// Equivalent to [`sys::ffi::playdate_graphics::newBitmapTable`].
46+
#[doc(alias = "sys::ffi::playdate_graphics::newBitmapTable")]
3647
pub fn new_with(api: Api, count: c_int, width: c_int, height: c_int) -> Result<Self, Error> {
3748
let f = api.new_bitmap_table();
3849
let ptr = unsafe { f(count, width, height) };
@@ -44,12 +55,24 @@ impl<Api: api::Api> BitmapTable<Api, true> {
4455
}
4556

4657

58+
/// Allocates and returns a new [`Bitmap`] from the file at `path`.
59+
///
60+
/// If there is no file at `path`, the function returns error.
61+
///
62+
/// Calls [`sys::ffi::playdate_graphics::loadBitmapTable`].
63+
#[doc(alias = "sys::ffi::playdate_graphics::loadBitmapTable")]
4764
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, ApiError>
4865
where Api: Default {
4966
let api = Api::default();
5067
Self::load_with(api, path)
5168
}
5269

70+
/// Allocates and returns a new [`Bitmap`] from the file at `path`.
71+
///
72+
/// If there is no file at `path`, the function returns error.
73+
///
74+
/// Calls [`sys::ffi::playdate_graphics::loadBitmapTable`].
75+
#[doc(alias = "sys::ffi::playdate_graphics::loadBitmapTable")]
5376
pub fn load_with<P: AsRef<Path>>(api: Api, path: P) -> Result<Self, ApiError> {
5477
let mut err = Box::new(core::ptr::null() as *const c_char);
5578
let out_err = Box::into_raw(err);
@@ -72,6 +95,10 @@ impl<Api: api::Api> BitmapTable<Api, true> {
7295
}
7396

7497
impl<Api: api::Api, const FOD: bool> BitmapTable<Api, FOD> {
98+
/// Loads the image-table at `path` into the previously allocated this table.
99+
///
100+
/// Equivalent to [`sys::ffi::playdate_graphics::loadIntoBitmapTable`].
101+
#[doc(alias = "sys::ffi::playdate_graphics::loadIntoBitmapTable")]
75102
pub fn load_into<P: AsRef<Path>>(&mut self, path: P) -> Result<(), ApiError> {
76103
let mut err = Box::new(core::ptr::null() as *const c_char);
77104
let out_err = Box::into_raw(err);
@@ -93,6 +120,9 @@ impl<Api: api::Api, const FOD: bool> BitmapTable<Api, FOD> {
93120
/// if `index` is out of bounds, the function returns `None`.
94121
///
95122
/// Creates new default api access-point.
123+
///
124+
/// Equivalent to [`sys::ffi::playdate_graphics::getTableBitmap`].
125+
#[doc(alias = "sys::ffi::playdate_graphics::getTableBitmap")]
96126
pub fn get<'table, BitApi: BitmapApi>(&'table self, index: c_int) -> Option<Bitmap<BitApi, true>>
97127
where Bitmap<BitApi, true>: 'table,
98128
BitApi: Default {
@@ -103,6 +133,9 @@ impl<Api: api::Api, const FOD: bool> BitmapTable<Api, FOD> {
103133
/// if `index` is out of bounds, the function returns `None`.
104134
///
105135
/// Produced `Bitmap` uses passed `api` access-point.
136+
///
137+
/// Equivalent to [`sys::ffi::playdate_graphics::getTableBitmap`].
138+
#[doc(alias = "sys::ffi::playdate_graphics::getTableBitmap")]
106139
pub fn get_with<'table, BitApi: BitmapApi>(&'table self,
107140
api: BitApi,
108141
index: c_int)

‎api/gfx/src/lib.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! Playdate Graphics API
1+
//! Playdate graphics API
22
#![cfg_attr(not(test), no_std)]
33
#![feature(error_in_core)]
44

‎api/gfx/src/text.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! Playdate Text API
1+
//! Playdate text API
22
33
use core::ffi::{c_int, c_char};
44

0 commit comments

Comments
 (0)