rock-n-code/playdate-kit
1
0
Fork 0
Code Issues Pull Requests Actions Releases 3 Activity

Tightened the source code and README documentations in the library.

Browse Source
This commit is contained in:
javier
2026-09-18 12:45:39 +02:00
parent c9f887bacb
commit 9ae10590cc
97 changed files with 854 additions and 1142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/PlaydateKit/Graphics/Graphics.swift
+47 -65
View File
@@ -3,102 +3,95 @@ internal import CPlaydate
/// The graphics API: drawing, bitmaps, fonts, tilemaps, and video.
public enum Graphics {}
/// The cached `playdate->graphics` C API table.
/// `playdate->graphics`.
var gfx: UnsafePointer<playdate_graphics> { Playdate.graphicsAPI.unsafelyUnwrapped }
extension Graphics {
// MARK: - Screen constants
/// The width of the screen in pixels (`LCD_COLUMNS`).
/// Screen width, in pixels (`LCD_COLUMNS`).
public static let columns = 400
/// The height of the screen in pixels (`LCD_ROWS`).
/// Screen height, in pixels (`LCD_ROWS`).
public static let rows = 240
/// The stride of a framebuffer row in bytes (`LCD_ROWSIZE`).
/// Framebuffer row stride, in bytes (`LCD_ROWSIZE`).
public static let rowSize = 52
// MARK: - Drawing state
/// Clears the entire display, filling it with `color`.
public static func clear(color: Color = .white) {
color.withLCDColor { gfx.pointee.clear.unsafelyUnwrapped($0) }
}
/// Sets the background color shown when the display is offset or for
/// clear pixels in drawn images.
/// Shown where the display is offset; clears dirty areas in the sprite system.
public static func setBackgroundColor(_ color: SolidColor) {
gfx.pointee.setBackgroundColor.unsafelyUnwrapped(color.cValue)
}
/// Sets the mode that determines how source pixels combine with the
/// destination. Returns the previous mode.
/// Applies to bitmaps, and so text. Returns the previous mode.
@discardableResult
public static func setDrawMode(_ mode: DrawMode) -> DrawMode {
DrawMode(gfx.pointee.setDrawMode.unsafelyUnwrapped(mode.cValue))
}
/// Offsets all subsequent drawing by (dx, dy).
/// Offsets subsequent drawing by (`dx`, `dy`) pixels; may be negative.
public static func setDrawOffset(dx: Int, dy: Int) {
gfx.pointee.setDrawOffset.unsafelyUnwrapped(Int32(dx), Int32(dy))
}
/// Sets the clip rect in world coordinates (affected by the draw offset).
/// In world coordinates (translated by the draw offset). Cleared each update.
public static func setClipRect(x: Int, y: Int, width: Int, height: Int) {
gfx.pointee.setClipRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height))
}
/// Sets the clip rect in world coordinates (affected by the draw offset).
/// In world coordinates (translated by the draw offset). Cleared each update.
public static func setClipRect(_ rect: Rect) {
setClipRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height)
}
/// Sets the clip rect in screen coordinates (unaffected by the draw offset).
/// In screen coordinates (ignoring the draw offset).
public static func setScreenClipRect(x: Int, y: Int, width: Int, height: Int) {
gfx.pointee.setScreenClipRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height))
}
/// Sets the clip rect in screen coordinates (unaffected by the draw offset).
/// In screen coordinates (ignoring the draw offset).
public static func setScreenClipRect(_ rect: Rect) {
setScreenClipRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height)
}
/// Clears the current clip rect.
public static func clearClipRect() {
gfx.pointee.clearClipRect.unsafelyUnwrapped()
}
/// Sets the end cap style used by subsequent line drawing.
public static func setLineCapStyle(_ style: LineCapStyle) {
gfx.pointee.setLineCapStyle.unsafelyUnwrapped(style.cValue)
}
/// Sets the stencil applied to subsequent drawing. If `tile` is `true`
/// the stencil image is tiled, and its width must be a multiple of 32.
/// Pass `nil` to clear the stencil.
/// Pixels draw only where the stencil is white; `nil` clears it. A tiled stencil's
/// width must be a multiple of 32. Not retained; keep it alive while set.
public static func setStencil(_ image: Bitmap?, tile: Bool = false) {
gfx.pointee.setStencilImage.unsafelyUnwrapped(image?.pointer, tile ? 1 : 0)
}
/// Pushes a new drawing context targeting `target`, or the display if
/// `target` is `nil`.
/// `nil` targets the display framebuffer. Not retained; keep `target` alive until
/// the matching `popContext()`.
public static func pushContext(_ target: Bitmap? = nil) {
gfx.pointee.pushContext.unsafelyUnwrapped(target?.pointer)
}
/// Pops the top drawing context off the stack.
/// Restores the previous context's drawing settings. No-op if none.
public static func popContext() {
gfx.pointee.popContext.unsafelyUnwrapped()
}
// MARK: - Shapes
/// Draws a line from (x1, y1) to (x2, y2) with the given stroke width.
/// `width` is in pixels.
public static func drawLine(x1: Int, y1: Int, x2: Int, y2: Int, width: Int, color: Color) {
color.withLCDColor {
gfx.pointee.drawLine.unsafelyUnwrapped(Int32(x1), Int32(y1), Int32(x2), Int32(y2), Int32(width), $0)
}
}
/// Fills the triangle with vertices (x1, y1), (x2, y2), and (x3, y3).
public static func fillTriangle(x1: Int, y1: Int, x2: Int, y2: Int, x3: Int, y3: Int, color: Color) {
color.withLCDColor {
gfx.pointee.fillTriangle.unsafelyUnwrapped(Int32(x1), Int32(y1), Int32(x2), Int32(y2),
@@ -106,32 +99,29 @@ extension Graphics {
}
}
/// Draws the outline of a rectangle, stroked inside its frame.
/// Stroked inside its frame.
public static func drawRect(x: Int, y: Int, width: Int, height: Int, color: Color) {
color.withLCDColor {
gfx.pointee.drawRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height), $0)
}
}
/// Draws the outline of a rectangle, stroked inside its frame.
/// Stroked inside its frame.
public static func drawRect(_ rect: Rect, color: Color) {
drawRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height, color: color)
}
/// Fills the rectangle with `color`.
public static func fillRect(x: Int, y: Int, width: Int, height: Int, color: Color) {
color.withLCDColor {
gfx.pointee.fillRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height), $0)
}
}
/// Fills the rectangle with `color`.
public static func fillRect(_ rect: Rect, color: Color) {
fillRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height, color: color)
}
/// Draws the outline of a rectangle with rounded corners, stroked with
/// `lineWidth`.
/// Stroked inside the rect. `radius` and `lineWidth` are in pixels.
public static func drawRoundRect(x: Int, y: Int, width: Int, height: Int, radius: Int,
lineWidth: Int, color: Color) {
color.withLCDColor {
@@ -140,14 +130,13 @@ extension Graphics {
}
}
/// Draws the outline of a rectangle with rounded corners, stroked with
/// `lineWidth`.
/// Stroked inside the rect. `radius` and `lineWidth` are in pixels.
public static func drawRoundRect(_ rect: Rect, radius: Int, lineWidth: Int, color: Color) {
drawRoundRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height,
radius: radius, lineWidth: lineWidth, color: color)
}
/// Fills a rectangle with rounded corners.
/// `radius` is in pixels.
public static func fillRoundRect(x: Int, y: Int, width: Int, height: Int, radius: Int, color: Color) {
color.withLCDColor {
gfx.pointee.fillRoundRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height),
@@ -155,14 +144,14 @@ extension Graphics {
}
}
/// Fills a rectangle with rounded corners.
/// `radius` is in pixels.
public static func fillRoundRect(_ rect: Rect, radius: Int, color: Color) {
fillRoundRect(x: rect.left, y: rect.top, width: rect.width, height: rect.height,
radius: radius, color: color)
}
/// Draws an ellipse stroked inside the rect. If the angles differ, draws
/// an arc from `startAngle` to `endAngle` (clockwise degrees, 0 at top).
/// Stroked inside the rect. Differing angles draw only that arc (degrees clockwise
/// from the top).
public static func drawEllipse(x: Int, y: Int, width: Int, height: Int, lineWidth: Int,
startAngle: Float = 0, endAngle: Float = 0, color: Color) {
color.withLCDColor {
@@ -171,8 +160,7 @@ extension Graphics {
}
}
/// Fills an ellipse inside the rect. If the angles differ, fills the
/// wedge from `startAngle` to `endAngle` (clockwise degrees, 0 at top).
/// Differing angles fill only that wedge (degrees clockwise from the top).
public static func fillEllipse(x: Int, y: Int, width: Int, height: Int,
startAngle: Float = 0, endAngle: Float = 0, color: Color) {
color.withLCDColor {
@@ -181,24 +169,22 @@ extension Graphics {
}
}
/// Draws an ellipse stroked inside the rect. If the angles differ, draws
/// an arc from `startAngle` to `endAngle` (clockwise degrees, 0 at top).
/// Stroked inside the rect. Differing angles draw only that arc (degrees clockwise
/// from the top).
public static func drawEllipse(in rect: Rect, lineWidth: Int,
startAngle: Float = 0, endAngle: Float = 0, color: Color) {
drawEllipse(x: rect.left, y: rect.top, width: rect.width, height: rect.height,
lineWidth: lineWidth, startAngle: startAngle, endAngle: endAngle, color: color)
}
/// Fills an ellipse inside the rect. If the angles differ, fills the
/// wedge from `startAngle` to `endAngle` (clockwise degrees, 0 at top).
/// Differing angles fill only that wedge (degrees clockwise from the top).
public static func fillEllipse(in rect: Rect,
startAngle: Float = 0, endAngle: Float = 0, color: Color) {
fillEllipse(x: rect.left, y: rect.top, width: rect.width, height: rect.height,
startAngle: startAngle, endAngle: endAngle, color: color)
}
/// Fills the polygon described by the points, connecting the last point
/// back to the first.
/// The last point connects back to the first.
public static func fillPolygon(points: [(x: Int, y: Int)], color: Color,
fillRule: PolygonFillRule = .nonZero) {
withUnsafeTemporaryAllocation(of: Int32.self, capacity: points.count * 2) { coordinates in
@@ -215,12 +201,12 @@ extension Graphics {
}
}
/// Sets the pixel at (x, y) in the current drawing context.
/// Slow in bulk; prefer bitmaps or framebuffer writes for many pixels.
public static func setPixel(x: Int, y: Int, color: Color) {
color.withLCDColor { gfx.pointee.setPixel.unsafelyUnwrapped(Int32(x), Int32(y), $0) }
}
/// Reads an 8×8 pattern from the bitmap starting at (x, y).
/// The 8×8 pattern whose upper-left corner is (x, y) in `bitmap`.
public static func colorToPattern(from bitmap: Bitmap, x: Int, y: Int) -> Pattern {
var color: LCDColor = 0
gfx.pointee.setColorToPattern.unsafelyUnwrapped(&color, bitmap.pointer, Int32(x), Int32(y))
@@ -235,7 +221,7 @@ extension Graphics {
// MARK: - Text
/// Draws `text` at (x, y) using the current font. Returns the drawn width.
/// Uses the current font, or the system font if none is set. Returns the drawn width.
@discardableResult
public static func drawText(_ text: String, x: Int, y: Int) -> Int {
text.withCString { cString in
@@ -244,7 +230,7 @@ extension Graphics {
}
}
/// Draws `text` wrapped and aligned inside the given rectangle.
/// Wrapped and aligned inside the rect, with the current font.
public static func drawText(_ text: String, x: Int, y: Int, width: Int, height: Int,
wrap: TextWrappingMode = .word, align: TextAlignment = .left) {
text.withCString { cString in
@@ -254,34 +240,34 @@ extension Graphics {
}
}
/// Draws `text` wrapped and aligned inside the given rectangle.
/// Wrapped and aligned inside the rect, with the current font.
public static func drawText(_ text: String, in rect: Rect,
wrap: TextWrappingMode = .word, align: TextAlignment = .left) {
drawText(text, x: rect.left, y: rect.top, width: rect.width, height: rect.height,
wrap: wrap, align: align)
}
/// Sets the font used by subsequent text drawing.
/// Not retained; keep `font` alive while set.
public static func setFont(_ font: Font) {
gfx.pointee.setFont.unsafelyUnwrapped(font.pointer)
}
/// Extra space added between letters, in pixels.
/// Extra space between letters, in pixels.
public static var textTracking: Int {
get { Int(gfx.pointee.getTextTracking.unsafelyUnwrapped()) }
set { gfx.pointee.setTextTracking.unsafelyUnwrapped(Int32(newValue)) }
}
/// Adjusts the line height used when drawing multi-line text.
/// Pixels added to the font's own leading for multi-line text.
public static func setTextLeading(_ lineHeightAdjustment: Int) {
gfx.pointee.setTextLeading.unsafelyUnwrapped(Int32(lineHeightAdjustment))
}
// MARK: - Framebuffer
/// Calls `body` with the current working framebuffer: `rows` rows of
/// `rowSize` bytes each. Returns `nil` if there is no framebuffer.
/// Call `markUpdatedRows(from:to:)` after writing directly.
/// The working framebuffer: `rows` rows of `rowSize` bytes, 1 bit per pixel, MSB first,
/// last 2 bytes of each row unused. The span is valid only inside `body`; `nil` if
/// there is no framebuffer. Call `markUpdatedRows(from:to:)` after writing.
public static func withFrame<Result, Failure: Error>(
_ body: (inout MutableSpan<UInt8>) throws(Failure) -> Result
) throws(Failure) -> Result? {
@@ -290,9 +276,8 @@ extension Graphics {
return try body(&span)
}
/// Calls `body` with the framebuffer currently shown on the display:
/// `rows` rows of `rowSize` bytes each. Returns `nil` if there is no
/// framebuffer.
/// The last frame shown, laid out like `withFrame(_:)`. The span is valid only inside
/// `body`; `nil` if there is no framebuffer.
public static func withDisplayFrame<Result, Failure: Error>(
_ body: (Span<UInt8>) throws(Failure) -> Result
) throws(Failure) -> Result? {
@@ -300,33 +285,30 @@ extension Graphics {
return try body(UnsafeBufferPointer(start: frame, count: rows * rowSize).span)
}
/// A bitmap view of the display framebuffer. Simulator only; `nil` on device.
/// Simulator only: white pixels overlay the display in translucent red. `nil` on device.
public static var debugBitmap: Bitmap? {
guard let getDebugBitmap = gfx.pointee.getDebugBitmap,
let pointer = getDebugBitmap() else { return nil }
return Bitmap(pointer: pointer, isOwned: false)
}
/// A bitmap referencing the display framebuffer (not a copy).
/// Not a copy; owned by the system.
public static var displayBufferBitmap: Bitmap? {
guard let pointer = gfx.pointee.getDisplayBufferBitmap.unsafelyUnwrapped() else { return nil }
return Bitmap(pointer: pointer, isOwned: false)
}
/// A copy of the working framebuffer as a new bitmap.
public static func copyFrameBufferBitmap() -> Bitmap? {
guard let pointer = gfx.pointee.copyFrameBufferBitmap.unsafelyUnwrapped() else { return nil }
return Bitmap(pointer: pointer, isOwned: true)
}
/// Tells the system which rows (inclusive) were changed by direct
/// framebuffer writes and need redisplay.
/// Marks rows `start`...`end` (inclusive) as changed by direct framebuffer writes.
public static func markUpdatedRows(from start: Int, to end: Int) {
gfx.pointee.markUpdatedRows.unsafelyUnwrapped(Int32(start), Int32(end))
}
/// Manually flushes the framebuffer to the display. Only needed when
/// drawing outside the normal update cycle.
/// Flushes the framebuffer. The system does this after each update.
public static func display() {
gfx.pointee.display.unsafelyUnwrapped()
}