[Core] makes 'SDLObject' public (temporarily)

Author: KevinVitale

Samples/SwiftSDL-TestBench/Sources/Games/Sandbox.swift

@@ -15,7 +15,6 @@ extension SDL.Games {
     private var scene: Scene!
 
     func onReady(window: any SwiftSDL.Window) throws(SwiftSDL.SDL_Error) {
-      try SDL_Init(.gamepad)
       scene = Scene(size: try window.size(as: Float.self), bgColor: .gray)
     }
 

Sources/SwiftSDL/GPUDevice.swift

@@ -46,7 +46,7 @@ extension GPUDevice {
   }
 
   public func render(_ commandBuffer: some CommandBuffer, pass: (OpaquePointer) throws -> Void) throws(SDL_Error) -> some GPUDevice {
-      SDL_BeginGPURenderPass(commandBuffer.pointer, nil , 0 , nil )
+    SDL_BeginGPURenderPass(commandBuffer.pointer, nil , 0 , nil )
     return self
   }
 }
@@ -82,7 +82,7 @@ public enum SDL_GPUShaderFormat: RawRepresentable, Decodable, CaseIterable {
       default: self = .invalid
     }
   }
-
+  
   public var rawValue: UInt32 {
     switch self {
       case .invalid: return UInt32(SDL_GPU_SHADERFORMAT_INVALID)

Sources/SwiftSDL/ObjectProtocol.swift

@@ -3,28 +3,41 @@ public protocol SDLObjectProtocol: AnyObject {
   var pointer: Pointer { get }
 }
 
-/*
- Explore this
- https://github.com/swiftlang/swift/blob/main/docs/OptimizationTips.rst#advice-use-unmanaged-references-to-avoid-reference-counting-overhead
- */
 
 public final class SDLObject<Pointer: Hashable>: SDLObjectProtocol, @unchecked Sendable {
-  enum Tag {
+  /// Used for associating a tag with an SDLObject instance, primarily for debugging and memory-allocation tracking.
+  @available(*, deprecated, message: "Will be removed in a future release")
+  public enum Tag {
+    /// A user-defined string for debugging purposes.
     case custom(String)
+    
+    /// A default, no-tag state.
+    case empty
   }
 
+  /// The underlying resource reference managed by this object.
   public let pointer: Pointer
 
+  /// A callback invoked during deinitialization to clean up the resource.
   private let destroy: (Pointer) -> Void
+  
+  /// A debugging or tracking tag for the instance.
   private let tag: Tag
 
-  required init(_ pointer: Pointer, tag: Tag, destroy: @escaping (Pointer) -> Void = { _ in }) {
+  
+  /// Creates an instance of an SDL object from an underlying pointer reference.
+  /// - Parameters:
+  ///   - pointer: The resource pointer being managed.
+  ///   - tag: A debugging or memory-allocation tag (default: .empty).
+  ///   - destroy: A closure invoked during deinitialization to clean up the resource (default: a no-op closure).
+  public required init(_ pointer: Pointer, tag: Tag = .empty, destroy: @escaping (Pointer) -> Void = { _ in }) {
     // print("\(type(of: Pointer.self)): \(#function), \(tag)")
     self.destroy = destroy
     self.pointer = pointer
     self.tag = tag
   }
 
+  /// Ensures the destroy callback is called with the managed pointer when the SDLObject instance is deallocated.
   deinit {
     /*
     #if DEBUG
@@ -35,16 +48,6 @@ public final class SDLObject<Pointer: Hashable>: SDLObjectProtocol, @unchecked S
   }
 }
 
-public func SDL_BufferPointer<Value>(_ allocate: (UnsafeMutablePointer<Int32>) -> UnsafeMutablePointer<Value>?) throws(SDL_Error) -> [Value] {
-  var count: Int32 = 0
-  guard let pointer = allocate(&count) else {
-    throw .error
-  }
-  defer { SDL_free(pointer) }
-  let bufferPtr = UnsafeMutableBufferPointer.init(start: pointer, count: Int(count))
-  return Array(bufferPtr)
-}
-
 extension SDLObjectProtocol {
   @discardableResult
   @inlinable
@@ -82,3 +85,31 @@ extension SDLObjectProtocol {
     return .success(self)
   }
 }
+
+/**
+ This function facilitates the allocation and conversion of a buffer pointer
+ to an array of values, handling resource cleanup and error management seamlessly.
+ 
+ **Example:**
+ 
+ ```
+ let joysticks = try SDL_BufferPointer(SDL_GetJoysticks)
+ ```
+ 
+ The closure is responsible for:
+ - Modifying the Int32 pointer to indicate the number of elements allocated.
+ - Returning a pointer to the allocated buffer or nil on failure.
+ 
+ - parameter allocate: A closure that takes an `UnsafeMutablePointer<Int32>` and returns an optional `UnsafeMutablePointer<Value>`.
+ - returns: A Swift array containing the elements of the allocated buffer.
+ - throws: Throw `SDL_Error.error` when the allocate closure fails to return a valid pointer.
+ */
+public func SDL_BufferPointer<Value>(_ allocate: (UnsafeMutablePointer<Int32>) -> UnsafeMutablePointer<Value>?) throws(SDL_Error) -> [Value] {
+  var count: Int32 = 0
+  guard let pointer = allocate(&count) else {
+    throw .error
+  }
+  defer { SDL_free(pointer) }
+  let bufferPtr = UnsafeMutableBufferPointer.init(start: pointer, count: Int(count))
+  return Array(bufferPtr)
+}

Sources/SwiftSDL/Renderer.swift

@@ -4,11 +4,11 @@ public protocol Renderer: SDLObjectProtocol, Sendable where Pointer == OpaquePoi
 extension SDLObject<OpaquePointer>: Renderer { }
 
 // MARK: - Create Renderer
-public func SDL_CreateRenderer<P: PropertyValue>(with properties: (String, value: P)..., window: (any Window)? = nil) throws(SDL_Error) -> some Renderer {
+public func SDL_CreateRenderer<P: PropertyValue>(with properties: (String, value: P)..., window: (some Window)? = nil) throws(SDL_Error) -> some Renderer {
   try SDL_CreateRenderer(with: properties, window: window)
 }
 
-public func SDL_CreateRenderer<P: PropertyValue>(with properties: [(String, value: P)], window: (any Window)? = nil) throws(SDL_Error) -> some Renderer {
+public func SDL_CreateRenderer<P: PropertyValue>(with properties: [(String, value: P)], window: (some Window)? = nil) throws(SDL_Error) -> some Renderer {
   let rendererProperties = SDL_CreateProperties()
   defer { rendererProperties.destroy() }
 
@@ -155,7 +155,7 @@ extension Renderer {
   }
 
   @discardableResult
-  public func pass(to callback: ((_ renderer: Self) throws -> Void)?) throws(SDL_Error) -> any Renderer {
+  public func pass(to callback: ((_ renderer: Self) throws -> Void)?) throws(SDL_Error) -> Self {
     do {
       try callback?(self)
       return self
@@ -169,7 +169,7 @@ extension Renderer {
   }
 
   @discardableResult
-  public func pass<each Argument>(to callback: (_ renderer: Self, repeat each Argument) throws(SDL_Error) -> Void, _ argument: repeat each Argument) throws(SDL_Error) -> any Renderer {
+  public func pass<each Argument>(to callback: (_ renderer: Self, repeat each Argument) throws(SDL_Error) -> Void, _ argument: repeat each Argument) throws(SDL_Error) -> Self {
     try callback(self, repeat each argument)
     return self
   }

Sources/SwiftSDL/Surface.swift

@@ -79,7 +79,7 @@ extension Surface {
 
 // MARK: - Load Bitmaps
 @discardableResult
-public func SDL_Load(bitmap file: String, relativePath: String? = nil) throws(SDL_Error) -> any Surface {
+public func SDL_Load(bitmap file: String, relativePath: String? = nil) throws(SDL_Error) -> some Surface {
   guard let pointer = SDL_LoadBMP(file) else {
     throw .error
   }
@@ -91,7 +91,7 @@ public func SDL_Load(bitmap file: String, relativePath: String? = nil) throws(SD
 public func SDL_Load(
   bitmap file: String,
   searchingBundles bundles: [Bundle] = Bundle.resourceBundles(),
-  inDirectory directory: String? = nil) throws(SDL_Error) -> any Surface
+  inDirectory directory: String? = nil) throws(SDL_Error) -> some Surface
 {
   guard let filePath = bundles.compactMap({ bundle in
     bundle.path(

Sources/SwiftSDL/Window.swift

@@ -221,19 +221,7 @@ public func SDL_CreateWindow(_ title: String, size: Size<Int32>, flags: SDL_Wind
 
 @discardableResult
 public func SDL_GetWindows() throws(SDL_Error) -> [any Window] {
-  var count: UInt32 = 0
-  guard let windows = SDL_GetWindows(&count) else {
-    throw .error
-  }
-  
-  defer { SDL_free(windows) }
-  
-  return Array<OpaquePointer?>.init(unsafeUninitializedCapacity: Int(count)) { buffer, initializedCount in
-    initializedCount = Int(count)
-    for i in 0..<initializedCount {
-      buffer[i] = windows[i]
-    }
-  }
+  try SDL_BufferPointer(SDL_GetWindows)
     .compactMap(\.self)
-    .map({ SDLObject($0, tag: .custom("tag"), destroy: SDL_DestroyWindow) })
+    .map({ SDLObject($0) as! (any Window) })
 }