Update to SDK 2.5.0 (#363)

🚨 SDK 2.5.0 with breaking changes:

* update `sound`

* fix `gfx::set_draw_mode`

* `sys`: fix min existing version (`SDK_VER_EXISTING`)

* CI: set missed `custom-url`

* update SDK version in README

* fix `set_draw_mode`

* add `get_pixel` & `set_pixel`

* add table `info` (`getBitmapTableInfo`)

* CI: update minimal SDK version for tests

* Automated build pre-built bindings for 2.5.0 on macOS-ARM64 with features: default

* Automated build pre-built bindings for 2.5.0 on macOS-ARM64 with features: full

* Automated build pre-built bindings for 2.5.0 on Linux-X64 with features: full

* Automated build pre-built bindings for 2.5.0 on Linux-X64 with features: default

* Automated build pre-built bindings for 2.5.0 on Windows-X64 with features: default

* Automated build pre-built bindings for 2.5.0 on Windows-X64 with features: full

* Automated bump sys crate version

* remove legacy bindings

* bump crate versions

.github/workflows/tests.yml

@@ -54,9 +54,9 @@ jobs:
           - ubuntu-latest
           - windows-latest
         sdk:
-          # - beta
           - latest
-          - 2.4.0
+          - 2.5.0
+          # - beta
 
     steps:
       - run: arch
@@ -159,6 +159,7 @@ jobs:
           - windows-latest
         sdk:
           - latest
+          # - beta
 
     steps:
       - uses: actions/checkout@v4
@@ -186,6 +187,7 @@ jobs:
         uses: pd-rs/get-playdate-sdk@main
         with:
           version: ${{ matrix.sdk }}
+          custom-url: ${{ matrix.sdk == 'beta' && ((runner.os == 'macOS' && secrets.SDK_BETA_MACOS) || (runner.os == 'Linux' && secrets.SDK_BETA_LINUX) || (runner.os == 'Windows' && secrets.SDK_BETA_WINDOWS)) || '' }}
 
       - name: SDK ${{ steps.sdk.outputs.version }} installed
         run: which pdc && pdc --version
@@ -212,9 +214,9 @@ jobs:
           - ubuntu-latest
           - windows-latest
         sdk:
-          # - beta
           - latest
-          - 2.4.0
+          - 2.5.0
+          # - beta
 
     steps:
       - uses: actions/checkout@v4
@@ -267,9 +269,9 @@ jobs:
           - ubuntu-latest
           - windows-latest
         sdk:
-          # - beta
           - latest
-          - 2.4.0
+          - 2.5.0
+          # - beta
 
     steps:
       - uses: actions/checkout@v4
@@ -325,9 +327,9 @@ jobs:
         os:
           - macos-14
         sdk:
-          # - beta
           - latest
-          - 2.4.0
+          - 2.5.0
+          # - beta
 
     steps:
       - uses: actions/checkout@v4
@@ -392,9 +394,9 @@ jobs:
           - ubuntu-latest
           - windows-latest
         sdk:
-          # - beta
           - latest
-          - 2.4.0
+          - 2.5.0
+          # - beta
 
     steps:
       - uses: actions/checkout@v4

Cargo.toml

@@ -18,14 +18,14 @@ color = { version = "0.2", path = "api/color", package = "playdate-color", defau
 ctrl = { version = "0.3", path = "api/ctrl", package = "playdate-controls", default-features = false }
 display = { version = "0.3", path = "api/display", package = "playdate-display", default-features = false }
 fs = { version = "0.2", path = "api/fs", package = "playdate-fs", default-features = false }
-gfx = { version = "0.3", path = "api/gfx", package = "playdate-graphics", default-features = false }
+gfx = { version = "0.4", path = "api/gfx", package = "playdate-graphics", default-features = false }
 lua = { version = "0.1", path = "api/lua", package = "playdate-lua", default-features = false }
 menu = { version = "0.2", path = "api/menu", package = "playdate-menu", default-features = false }
 scoreboards = { version = "0.1", path = "api/scoreboards", package = "playdate-scoreboards", default-features = false }
-sound = { version = "0.3", path = "api/sound", package = "playdate-sound", default-features = false }
+sound = { version = "0.4", path = "api/sound", package = "playdate-sound", default-features = false }
 sprite = { version = "0.2", path = "api/sprite", package = "playdate-sprite", default-features = false }
 system = { version = "0.3", path = "api/system", package = "playdate-system", default-features = false }
-sys = { version = "0.3", path = "api/sys", package = "playdate-sys", default-features = false }
+sys = { version = "0.4", path = "api/sys", package = "playdate-sys", default-features = false }
 
 tool = { version = "0.1", path = "support/tool", package = "playdate-tool" }
 build = { version = "0.3", path = "support/build", package = "playdate-build", default-features = false }

README.md

@@ -33,9 +33,7 @@ Follow the instructions for:
 
 ## Compatibility
 
-* __Minimal__ supported versions of Playdate SDK is `2.4.0` because of breaking changes in `2.4.0`.
-
-* __Latest__ version of SDK is `2.4.0`.
+* __Minimal__ supported versions of Playdate SDK is `2.5.0` because of breaking changes in `2.5.0`.
 
 
 

api/gfx/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "playdate-graphics"
-version = "0.3.14"
+version = "0.4.0"
 readme = "README.md"
 description = "High-level graphics API built on-top of Playdate API"
 keywords = ["playdate", "sdk", "api", "gamedev"]

api/gfx/src/api.rs

@@ -377,7 +377,7 @@ impl Api for Cache {
 	/// Equivalent to [`sys::ffi::playdate_graphics::setDrawMode`]
 	#[doc(alias = "sys::ffi::playdate_graphics::setDrawMode")]
 	#[inline(always)]
-	fn set_draw_mode(&self) -> unsafe extern "C" fn(mode: LCDBitmapDrawMode) {
+	fn set_draw_mode(&self) -> unsafe extern "C" fn(mode: LCDBitmapDrawMode) -> LCDBitmapDrawMode {
 		self.0.setDrawMode.expect("setDrawMode")
 	}
 
@@ -482,6 +482,13 @@ impl Api for Cache {
 		self.0.fillEllipse.expect("fillEllipse")
 	}
 
+	/// Equivalent to [`sys::ffi::playdate_graphics::setPixel`]
+	#[doc(alias = "sys::ffi::playdate_graphics::setPixel")]
+	#[inline(always)]
+	fn set_pixel(&self) -> unsafe extern "C" fn(x: c_int, y: c_int, c: LCDColor) {
+		self.0.setPixel.expect("setPixel")
+	}
+
 	/// Equivalent to [`sys::ffi::playdate_graphics::getFrame`]
 	#[doc(alias = "sys::ffi::playdate_graphics::getFrame")]
 	#[inline(always)]
@@ -578,7 +585,9 @@ pub trait Api: crate::bitmap::api::Api + crate::bitmap::table::api::Api + crate:
 	/// Equivalent to [`sys::ffi::playdate_graphics::setDrawMode`]
 	#[doc(alias = "sys::ffi::playdate_graphics::setDrawMode")]
 	#[inline(always)]
-	fn set_draw_mode(&self) -> unsafe extern "C" fn(mode: LCDBitmapDrawMode) { *sys::api!(graphics.setDrawMode) }
+	fn set_draw_mode(&self) -> unsafe extern "C" fn(mode: LCDBitmapDrawMode) -> LCDBitmapDrawMode {
+		*sys::api!(graphics.setDrawMode)
+	}
 
 	/// Equivalent to [`sys::ffi::playdate_graphics::setDrawOffset`]
 	#[doc(alias = "sys::ffi::playdate_graphics::setDrawOffset")]
@@ -677,6 +686,11 @@ pub trait Api: crate::bitmap::api::Api + crate::bitmap::table::api::Api + crate:
 		*sys::api!(graphics.fillEllipse)
 	}
 
+	/// Equivalent to [`sys::ffi::playdate_graphics::setPixel`]
+	#[doc(alias = "sys::ffi::playdate_graphics::setPixel")]
+	#[inline(always)]
+	fn set_pixel(&self) -> unsafe extern "C" fn(x: c_int, y: c_int, c: LCDColor) { *sys::api!(graphics.setPixel) }
+
 	/// Equivalent to [`sys::ffi::playdate_graphics::getFrame`]
 	#[doc(alias = "sys::ffi::playdate_graphics::getFrame")]
 	#[inline(always)]

api/gfx/src/bitmap/api.rs

@@ -6,6 +6,7 @@ use sys::ffi::LCDColor;
 use sys::ffi::LCDBitmap;
 use sys::ffi::LCDBitmapFlip;
 use sys::ffi::LCDRect;
+use sys::ffi::LCDSolidColor;
 
 
 /// Default graphics bitmap api end-point, ZST.
@@ -167,4 +168,12 @@ pub trait Api {
 		                        y: core::ffi::c_int) {
 		*sys::api!(graphics.setColorToPattern)
 	}
+
+
+	/// Equivalent to [`sys::ffi::playdate_graphics::getBitmapPixel`]
+	#[doc(alias = "sys::ffi::playdate_graphics::getBitmapPixel")]
+	#[inline(always)]
+	fn get_pixel(&self) -> unsafe extern "C" fn(bitmap: *mut LCDBitmap, x: c_int, y: c_int) -> LCDSolidColor {
+		*sys::api!(graphics.getBitmapPixel)
+	}
 }

api/gfx/src/bitmap/bitmap.rs

@@ -9,6 +9,7 @@ use alloc::boxed::Box;
 
 use sys::error::OkOrNullFnErr;
 use sys::ffi::LCDPattern;
+use sys::ffi::LCDSolidColor;
 use sys::traits::AsRaw;
 use sys::ffi::CString;
 use sys::ffi::LCDColor;
@@ -512,6 +513,20 @@ impl<Api: api::Api, const FOD: bool> Bitmap<Api, FOD> {
 		let f = self.1.set_color_to_pattern();
 		unsafe { f(color as _, self.0, x, y) }
 	}
+
+	/// Gets the color of the pixel at `(x,y)` in this bitmap.
+	/// If the coordinate is outside the bounds of the bitmap,
+	/// or if the bitmap has a mask and the pixel is marked transparent,
+	/// the function returns [`Clear`][LCDSolidColor::kColorClear];
+	/// otherwise the return value is [`White`][LCDSolidColor::kColorWhite] or [`Black`][LCDSolidColor::kColorBlack].
+	///
+	/// Calls [`sys::ffi::playdate_graphics::getBitmapPixel`].
+	#[doc(alias = "sys::ffi::playdate_graphics::getBitmapPixel")]
+	#[inline(always)]
+	pub fn pixel_at(&self, x: c_int, y: c_int) -> LCDSolidColor {
+		let f = self.1.get_pixel();
+		unsafe { f(self.0, x, y) }
+	}
 }
 
 
@@ -666,7 +681,7 @@ pub fn set_stencil(image: &impl AnyBitmap) { Graphics::Default().set_stencil(ima
 /// Equivalent to [`sys::ffi::playdate_graphics::setDrawMode`].
 #[doc(alias = "sys::ffi::playdate_graphics::setDrawMode")]
 #[inline(always)]
-pub fn set_draw_mode(mode: BitmapDrawMode) { Graphics::Default().set_draw_mode(mode) }
+pub fn set_draw_mode(mode: BitmapDrawMode) -> BitmapDrawMode { Graphics::Default().set_draw_mode(mode) }
 
 /// Push a new drawing context for drawing into the given bitmap.
 ///
@@ -785,13 +800,15 @@ impl<Api: crate::api::Api> Graphics<Api> {
 
 	/// Sets the mode used for drawing bitmaps.
 	///
+	/// Returns the previous draw mode.
+	///
 	/// Note that text drawing uses bitmaps, so this affects how fonts are displayed as well.
 	///
 	/// Equivalent to [`sys::ffi::playdate_graphics::setDrawMode`].
 	#[doc(alias = "sys::ffi::playdate_graphics::setDrawMode")]
-	pub fn set_draw_mode(&self, mode: BitmapDrawMode) {
+	pub fn set_draw_mode(&self, mode: BitmapDrawMode) -> BitmapDrawMode {
 		let f = self.0.set_draw_mode();
-		unsafe { f(mode) };
+		unsafe { f(mode) }
 	}
 
 	/// Push a new drawing context for drawing into the given bitmap.

api/gfx/src/bitmap/table.rs

@@ -150,6 +150,23 @@ impl<Api: api::Api, const FOD: bool> BitmapTable<Api, FOD> {
 			Some(Bitmap(ptr, api))
 		}
 	}
+
+	/// Returns the bitmap table’s image count in the `count` if not `None`
+	/// and number of cells across in the `width` (ditto) if not `None` .
+	///
+	/// Equivalent to [`sys::ffi::playdate_graphics::getTableBitmap`].
+	#[doc(alias = "sys::ffi::playdate_graphics::getTableBitmap")]
+	pub fn info<'table, BitApi: BitmapApi>(&'table self, count: Option<&mut c_int>, width: Option<&mut c_int>) {
+		let f = self.1.get_bitmap_table_info();
+		unsafe {
+			use core::ptr::null_mut;
+			f(
+			  self.0,
+			  count.map_or(null_mut() as _, |v| v as *mut _),
+			  width.map_or(null_mut() as _, |v| v as *mut _),
+			)
+		}
+	}
 }
 
 
@@ -213,5 +230,13 @@ pub mod api {
 		                    -> unsafe extern "C" fn(table: *mut LCDBitmapTable, idx: c_int) -> *mut LCDBitmap {
 			*sys::api!(graphics.getTableBitmap)
 		}
+
+		/// Equivalent to [`sys::ffi::playdate_graphics::getBitmapTableInfo`]
+		#[doc(alias = "sys::ffi::playdate_graphics::getBitmapTableInfo")]
+		fn get_bitmap_table_info(
+			&self)
+			-> unsafe extern "C" fn(table: *mut LCDBitmapTable, count: *mut c_int, width: *mut c_int) {
+			*sys::api!(graphics.getBitmapTableInfo)
+		}
 	}
 }

api/gfx/src/lib.rs

@@ -352,6 +352,26 @@ impl<Api: api::Api> Graphics<Api> {
 }
 
 impl<Api: api::Api> Graphics<Api> {
+	/// Sets the pixel at `(x,y)` in the current drawing context (by default the screen) to the given `color`.
+	/// Be aware that setting a pixel at a time is not very efficient:
+	/// In our testing, more than around 20,000 calls in a tight loop will drop the frame rate below 30 fps.
+	///
+	/// Equivalent to [`sys::ffi::playdate_graphics::setPixel`]
+	#[doc(alias = "sys::ffi::playdate_graphics::setPixel")]
+	#[inline(always)]
+	pub fn set_pixel(&self, x: c_int, y: c_int, color: color::Color) { self.set_pixel_raw(x, y, color.into()) }
+
+	/// Same as [`set_pixel`][Graphics::set_pixel], but without conversion [`Color`][color::Color] -> [`LCDColor`].
+	///
+	/// Equivalent to [`sys::ffi::playdate_graphics::setPixel`]
+	#[doc(alias = "sys::ffi::playdate_graphics::setPixel")]
+	#[inline(always)]
+	pub fn set_pixel_raw(&self, x: c_int, y: c_int, color: LCDColor) {
+		let f = self.0.set_pixel();
+		unsafe { f(x, y, color) }
+	}
+
+
 	/// Returns the current display frame buffer.
 	/// Rows are 32-bit aligned, so the row stride is 52 bytes, with the extra 2 bytes per row ignored.
 	/// Bytes are MSB-ordered; i.e., the pixel in column 0 is the 0x80 bit of the first byte of the row.

api/sound/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "playdate-sound"
-version = "0.3.0"
+version = "0.4.0"
 readme = "README.md"
 description = "High-level sound API built on-top of Playdate API"
 keywords = ["playdate", "sdk", "api", "gamedev"]

api/sound/src/sample.rs

@@ -140,7 +140,7 @@ impl<Api: api::Api> Sample<Api> {
 	                              sample_rate: u32)
 	                              -> Result<SampleWithData<'t, Api>, Error> {
 		let f = api.new_sample_from_data();
-		let ptr = unsafe { f(data.as_mut_ptr(), format, sample_rate, data.len() as _) };
+		let ptr = unsafe { f(data.as_mut_ptr(), format, sample_rate, data.len() as _, 0) };
 
 		if ptr.is_null() {
 			Err(Error::Alloc)
@@ -276,7 +276,8 @@ pub mod api {
 			-> unsafe extern "C" fn(data: *mut u8,
 			                        format: SoundFormat,
 			                        sampleRate: u32,
-			                        byteCount: c_int) -> *mut AudioSample {
+			                        byteCount: c_int,
+			                        shouldFreeData: c_int) -> *mut AudioSample {
 			self.0.newSampleFromData.expect("newSampleFromData")
 		}
 
@@ -329,7 +330,8 @@ pub mod api {
 			-> unsafe extern "C" fn(data: *mut u8,
 			                        format: SoundFormat,
 			                        sampleRate: u32,
-			                        byteCount: c_int) -> *mut AudioSample {
+			                        byteCount: c_int,
+			                        shouldFreeData: c_int) -> *mut AudioSample {
 			*sys::api!(sound.sample.newSampleFromData)
 		}
 

api/sys/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "playdate-sys"
-version = "0.3.7"
+version = "0.4.0"
 build = "src/build.rs"
 readme = "README.md"
 description = "Low-level Playdate API bindings"