Merge pull request #92 from samdze/release/0.21.0

Release/0.21.0

Author: ninovanhooff

README.md

@@ -178,4 +178,3 @@ This project is a work in progress, here's what is missing right now:
 - various playdate.sound funcionalities (but FilePlayer, SamplePlayer and SoundSequence are available)
 - playdate.json, but you can use Nim std/json, which is very convenient
 - advanced playdate.lua features, but basic Lua interop is available
-- playdate.scoreboards, undocumented even in the official C API docs

playdate.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "0.20.0"
+version       = "0.21.0"
 author        = "Samuele Zolfanelli"
 description   = "Playdate Nim bindings with extra features."
 license       = "MIT"

playdate_example/src/playdate_example.nim

@@ -3,6 +3,10 @@ import playdate/api
 const FONT_PATH = "/System/Fonts/Asheville-Sans-14-Bold.pft"
 const NIM_IMAGE_PATH = "/images/nim_logo"
 const PLAYDATE_NIM_IMAGE_PATH = "/images/playdate_nim"
+const BACKGROUND_MUSIC_PATH = "/audio/finally_see_the_light"
+const BACKGROUND_MUSIC_SAMPLE_RATE = 48_000
+const BACKGROUND_MUSIC_FADE_IN_SECONDS = 4.0
+const BACKGROUND_MUSIC_FADE_IN_SAMPLES = (BACKGROUND_MUSIC_SAMPLE_RATE * BACKGROUND_MUSIC_FADE_IN_SECONDS).int32
 
 var font: LCDFont
 
@@ -80,9 +84,11 @@ proc handler(event: PDSystemEvent, keycode: uint) {.raises: [].} =
         except:
             playdate.system.logToConsole(getCurrentExceptionMsg())
         # Inline try/except
-        filePlayer = try: playdate.sound.newFilePlayer("/audio/finally_see_the_light") except: nil
+        filePlayer = try: playdate.sound.newFilePlayer(BACKGROUND_MUSIC_PATH) except: nil
 
         filePlayer.play(0)
+        fileplayer.volume = 0.0 # first set folume to 0%
+        filePlayer.fadeVolume(1.0, 1.0, BACKGROUND_MUSIC_FADE_IN_SAMPLES, nil) # then fade to 100%
 
         # Add a checkmark menu item that plays a sound when switched and unpaused
         discard playdate.system.addCheckmarkMenuItem("Checkmark", false,

src/playdate/api.nim

@@ -6,8 +6,8 @@ import std/importutils
 import bindings/api
 export api
 
-import graphics, system, file, sprite, display, sound, lua, json, utils, types, nineslice
-export graphics, system, file, sprite, display, sound, lua, json, utils, types, nineslice
+import graphics, system, file, sprite, display, sound, scoreboards, lua, json, utils, types, nineslice
+export graphics, system, file, sprite, display, sound, scoreboards, lua, json, utils, types, nineslice
 
 macro initSDK*() =
     return quote do:

src/playdate/bindings/api.nim

@@ -1,6 +1,6 @@
 {.push raises: [].}
 
-import graphics, system, file, display, sprite, sound, lua
+import graphics, system, file, display, sprite, sound, scoreboards, lua
 
 type PlaydateAPI* {.importc: "PlaydateAPI", header: "pd_api.h".} = object
     system* {.importc: "system".}: ptr PlaydateSys
@@ -9,6 +9,7 @@ type PlaydateAPI* {.importc: "PlaydateAPI", header: "pd_api.h".} = object
     sprite* {.importc: "sprite".}: ptr PlaydateSprite
     display* {.importc: "display".}: ptr PlaydateDisplay
     sound* {.importc: "sound".}: ptr PlaydateSound
+    scoreboards* {.importc: "scoreboards".}: ptr PlaydateScoreboards
     lua* {.importc: "lua".}: ptr PlaydateLua
     # json* {.importc: "json".}: ptr PlaydateJSON # Unavailable, use std/json
 

src/playdate/bindings/scoreboards.nim

@@ -2,45 +2,52 @@
 
 import utils
 
-type PDScore* {.importc: "PDScore", header: "pd_api_scoreboards.h", bycopy.} = object
-    rank* {.importc: "rank".}: uint32
-    value* {.importc: "value".}: uint32
-    player* {.importc: "player".}: cstring
-
-type PDScoresList* {.importc: "PDScoresList", header: "pd_api_scoreboards.h", bycopy.} = object
-    boardID* {.importc: "boardID".}: cstring
-    count* {.importc: "count".}: cuint
-    lastUpdated* {.importc: "lastUpdated".}: uint32
-    playerIncluded* {.importc: "playerIncluded".}: cint
-    limit* {.importc: "limit".}: cuint
-    scores* {.importc: "scores".}: ptr PDScore
-
-type PDBoard* {.importc: "PDBoard", header: "pd_api_scoreboards.h", bycopy.} = object
-    boardID* {.importc: "boardID".}: cstring
-    name* {.importc: "name".}: cstring
-
-type PDBoardsList* {.importc: "PDBoardsList", header: "pd_api_scoreboards.h", bycopy.} = object
-    count* {.importc: "count".}: cuint
-    lastUpdated* {.importc: "lastUpdated".}: uint32
-    boards* {.importc: "boards".}: ptr PDBoard
-
-type AddScoreCallback* = proc (score: ptr PDScore; errorMessage: cstring) {.cdecl.}
-type PersonalBestCallback* = proc (score: ptr PDScore; errorMessage: cstring) {.cdecl.}
-type BoardsListCallback* = proc (boards: ptr PDBoardsList; errorMessage: cstring) {.cdecl.}
-type ScoresCallback* = proc (scores: ptr PDScoresList; errorMessage: cstring) {.cdecl.}
+type
+    PDScoreRaw* {.importc: "PDScore", header: "pd_api.h", bycopy.} = object
+        rank* {.importc: "rank".}: cuint
+        value* {.importc: "value".}: cuint
+        player* {.importc: "player".}: cstring
+
+    PDScorePtr* = ptr PDScoreRaw
+
+    PDScoresListRaw* {.importc: "PDScoresList", header: "pd_api.h", bycopy.} = object
+        boardID* {.importc: "boardID".}: cstring
+        count* {.importc: "count".}: cuint
+        lastUpdated* {.importc: "lastUpdated".}: cuint
+        playerIncluded* {.importc: "playerIncluded".}: cuint
+        limit* {.importc: "limit".}: cuint
+        scores* {.importc: "scores".}: ptr UncheckedArray[PDScoreRaw]
+
+    PDScoresListPtr* = ptr PDScoresListRaw
+
+    PDBoardRaw* {.importc: "PDBoard", header: "pd_api.h", bycopy.} = object
+        boardID* {.importc: "boardID".}: cstring
+        name* {.importc: "name".}: cstring
+
+    PDBoardsListRaw* {.importc: "PDBoardsList", header: "pd_api.h", bycopy.} = object
+        count* {.importc: "count".}: cuint
+        lastUpdated* {.importc: "lastUpdated".}: cuint
+        boards* {.importc: "boards".}: ptr UncheckedArray[PDBoardRaw]
+
+    PDBoardsListPtr* = ptr PDBoardsListRaw
+
+    PersonalBestCallbackRaw* {.importc: "PersonalBestCallback", header: "pd_api.h".} = proc (score: PDScorePtr; errorMessage: cstring) {.cdecl.}
+    AddScoreCallbackRaw* {.importc: "AddScoreCallback", header: "pd_api.h".} = proc (score: PDScorePtr; errorMessage: cstring) {.cdecl.}
+    BoardsListCallbackRaw* = proc (boards: ptr PDBoardsListRaw; errorMessage: cstring) {.cdecl.}
+    ScoresCallbackRaw* = proc (scores: ptr PDScoresListRaw; errorMessage: cstring) {.cdecl.}
 
 sdktype:
     type PlaydateScoreboards* {.importc: "const struct playdate_scoreboards", header: "pd_api.h".} = object
-        addScore* {.importc: "addScore".}: proc (boardId: cstring; value: uint32;
-            callback: AddScoreCallback): cint {.cdecl.}
-        getPersonalBest* {.importc: "getPersonalBest".}: proc (boardId: cstring;
-            callback: PersonalBestCallback): cint {.cdecl.}
-        freeScore* {.importc: "freeScore".}: proc (score: ptr PDScore) {.cdecl.}
-        getScoreboards* {.importc: "getScoreboards".}: proc (
-            callback: BoardsListCallback): cint {.cdecl.}
+        getPersonalBestBinding* {.importc: "getPersonalBest".}: proc (boardId: cstring;
+            callback: PersonalBestCallbackRaw): cint {.cdecl, raises: [].}
+        addScoreBinding* {.importc: "addScore".}: proc (boardId: cstring; value: cuint;
+            callback: AddScoreCallbackRaw): cint {.cdecl, raises: [].}
+        freeScore* {.importc: "freeScore".}: proc (score: PDScorePtr) {.cdecl, raises: [].}
+        getScoreboardsBinding* {.importc: "getScoreboards".}: proc (
+            callback: BoardsListCallbackRaw): cint {.cdecl, raises: [].}
         freeBoardsList* {.importc: "freeBoardsList".}: proc (
-            boardsList: ptr PDBoardsList) {.cdecl.}
-        getScores* {.importc: "getScores".}: proc (boardId: cstring;
-            callback: ScoresCallback): cint {.cdecl.}
+            boardsList: PDBoardsListPtr) {.cdecl, raises: [].}
+        getScoresBinding* {.importc: "getScores".}: proc (boardId: cstring;
+            callback: ScoresCallbackRaw): cint {.cdecl, raises: [].}
         freeScoresList* {.importc: "freeScoresList".}: proc (
-            scoresList: ptr PDScoresList) {.cdecl.}
+            scoresList: PDScoresListPtr) {.cdecl, raises: [].}

src/playdate/bindings/sound.nim

@@ -38,15 +38,15 @@ type PlaydateSoundFileplayer {.importc: "const struct playdate_sound_fileplayer"
     #     start: cfloat; `end`: cfloat) {.cdecl.}
     # didUnderrun* {.importc: "didUnderrun".}: proc (player: ptr FilePlayer): cint {.cdecl.}
     setFinishCallback* {.importc: "setFinishCallback".}: proc (
-        player: FilePlayerPtr; callback: PDSndCallbackProcRaw, userData: pointer = nil) {.cdecl, raises: [].}
+        player: FilePlayerPtr; callback: PDSndCallbackProcRaw, userdata: pointer = nil) {.cdecl, raises: [].}
     # setLoopCallback* {.importc: "setLoopCallback".}: proc (player: ptr FilePlayer;
     #     callback: SndCallbackProc) {.cdecl.}
     getOffset {.importc: "getOffset".}: proc (player: FilePlayerPtr): cfloat {.cdecl, raises: [].}
     # getRate* {.importc: "getRate".}: proc (player: ptr FilePlayer): cfloat {.cdecl.}
     # setStopOnUnderrun* {.importc: "setStopOnUnderrun".}: proc (
     #     player: ptr FilePlayer; flag: cint) {.cdecl.}
-    # fadeVolume* {.importc: "fadeVolume".}: proc (player: ptr FilePlayer; left: cfloat;
-    #     right: cfloat; len: int32T; finishCallback: SndCallbackProc) {.cdecl.}
+    fadeVolume* {.importc: "fadeVolume".}: proc (player: FilePlayerPtr; left: cfloat;
+        right: cfloat; len: cint; finishCallback: PDSndCallbackProcRaw, userdata: pointer = nil) {.cdecl, raises:[].}
     # setMP3StreamSource* {.importc: "setMP3StreamSource".}: proc (
     #     player: ptr FilePlayer; dataSource: proc (data: ptr uint8T; bytes: cint;
     #     userdata: pointer): cint {.cdecl.}; userdata: pointer; bufferLen: cfloat) {.
@@ -90,7 +90,7 @@ type PlaydateSoundSampleplayer {.importc: "const struct playdate_sound_samplepla
     setPlayRange* {.importc: "setPlayRange".}: proc (player: SamplePlayerPtr;
         start: cint; `end`: cint) {.cdecl, raises: [].}
     setFinishCallback* {.importc: "setFinishCallback".}: proc (
-        player: SamplePlayerPtr; callback: PDSndCallbackProcRaw, userData: pointer = nil) {.cdecl, raises: [].}
+        player: SamplePlayerPtr; callback: PDSndCallbackProcRaw, userdata: pointer = nil) {.cdecl, raises: [].}
     # setLoopCallback* {.importc: "setLoopCallback".}: proc (player: ptr SamplePlayer;
     #     callback: SndCallbackProc) {.cdecl.}
     getOffset* {.importc: "getOffset".}: proc (player: SamplePlayerPtr): cfloat {.cdecl , raises: [].}

src/playdate/bindings/utils.nim

@@ -1,5 +1,12 @@
 import macros
 
+iterator items*[T](rawField: ptr UncheckedArray[T], len: Natural): T =
+    ## iterate through a C array
+    ## To convert to a Nim seq:
+    ## `cArray.items(count).toSeq`
+    for i in 0..<len:
+        yield rawField[i]
+
 func toNimSymbol(typeSymbol: string): string =
     case typeSymbol:
         of "cint":

src/playdate/build/config.nim

@@ -11,9 +11,13 @@ when not compiles(task):
     import system/nimscript
 
 const headlessTesting = defined(simulator) and declared(test)
-const nimbleTesting = not defined(simulator) and not defined(devide) and declared(test)
+const nimbleTesting = not defined(simulator) and not defined(device) and declared(test)
 const testing = headlessTesting or nimbleTesting
 
+# Use the host OS for compilation. This is useful when running supporting development tools that import the playdate SDK or where the os module needs to be available.
+# This does not make the playdate api callable, only the types (header files) are available.
+const useHostOS = defined(useHostOS)
+
 # Path to the playdate src directory when checked out locally
 const localPlaydatePath = currentSourcePath / "../../../../src"
 
@@ -24,7 +28,7 @@ let nimblePlaydatePath =
     else:
         gorgeEx("nimble path playdate").output.split("\n")[0]
 
-if not testing:
+if not testing and not useHostOS:
     switch("noMain", "on")
 switch("backend", "c")
 switch("mm", "arc")
@@ -45,7 +49,9 @@ switch("passC", "-Wno-unknown-pragmas")
 switch("passC", "-Wdouble-promotion")
 switch("passC", "-I" & sdkPath() / "C_API")
 
-switch("os", "any")
+if not useHostOS:
+    echo "Setting os to any"
+    switch("os", "any")
 switch("define", "useMalloc")
 switch("define", "standalone")
 switch("threads", "off")
@@ -133,8 +139,8 @@ when defined(simulator):
     switch("passC", "-DTARGET_SIMULATOR=1")
     switch("passC", "-Wstrict-prototypes")
 
-if nimbleTesting:
-    # Compiling for tests.
+if useHostOS or nimbleTesting:
+    # Compiling for host system environment.
     switch("define", "simulator")
     switch("nimcache", nimcacheDir() / "simulator")
 

src/playdate/graphics.nim

@@ -341,7 +341,7 @@ proc set*(view: var BitmapView, x, y: int, color: LCDSolidColor) =
 
 proc getDebugBitmap*(this: ptr PlaydateGraphics): LCDBitmap =
     privateAccess(PlaydateGraphics)
-    return LCDBitmap(resource: this.getDebugBitmap(), free: true) # Who should manage this memory? Not clear. Auto-managed.
+    return LCDBitmap(resource: this.getDebugBitmap(), free: false) # do not free: system owns this
 
 proc copyFrameBufferBitmap*(this: ptr PlaydateGraphics): LCDBitmap =
     privateAccess(PlaydateGraphics)
@@ -411,9 +411,12 @@ proc set*(this: var LCDBitmap, x, y: int, color: LCDSolidColor = kColorBlack) =
         var data = this.getData
         data.set(x, y, color)
 
-proc setStencilImage*(this: ptr PlaydateGraphics, bitmap: LCDBitmap, tile: bool) =
+proc setStencilImage*(this: ptr PlaydateGraphics, bitmap: LCDBitmap, tile: bool = false) =
     privateAccess(PlaydateGraphics)
-    this.setStencilImage(bitmap.resource, if tile: 1 else: 0)
+    if bitmap == nil:
+        this.setStencilImage(nil, if tile: 1 else: 0)
+    else:
+        this.setStencilImage(bitmap.resource, if tile: 1 else: 0)
 
 proc makeFont*(this: LCDFontData, wide: bool): LCDFont =
     privateAccess(PlaydateGraphics)