SportsBallEngine/Sources/RendererAPI/RendererProtocol.swift

/// RendererAPI - Protocol Definitions for Platform Abstraction
/// This module contains ONLY protocol definitions with no platform-specific imports

import Foundation

// MARK: - Core Rendering Types

/// Represents a 3D scene to be rendered
public struct Scene {
    public var entities: [Entity]
    public var camera: Camera
    public var lights: [Light]
    
    public init(entities: [Entity] = [], camera: Camera, lights: [Light] = []) {
        self.entities = entities
        self.camera = camera
        self.lights = lights
    }
}

/// Represents a renderable entity in the scene
public struct Entity {
    public var id: UUID
    public var transform: Transform
    public var mesh: MeshHandle
    public var material: MaterialHandle
    
    public init(id: UUID = UUID(), transform: Transform, mesh: MeshHandle, material: MaterialHandle) {
        self.id = id
        self.transform = transform
        self.mesh = mesh
        self.material = material
    }
}

/// Camera configuration
public struct Camera {
    public var position: SIMD3<Float>
    public var rotation: SIMD4<Float> // Quaternion
    public var fieldOfView: Float
    public var nearPlane: Float
    public var farPlane: Float
    
    public init(position: SIMD3<Float> = .zero, rotation: SIMD4<Float> = SIMD4<Float>(0, 0, 0, 1),
                fieldOfView: Float = 60.0, nearPlane: Float = 0.1, farPlane: Float = 1000.0) {
        self.position = position
        self.rotation = rotation
        self.fieldOfView = fieldOfView
        self.nearPlane = nearPlane
        self.farPlane = farPlane
    }
}

/// Transform component
public struct Transform {
    public var position: SIMD3<Float>
    public var rotation: SIMD4<Float> // Quaternion
    public var scale: SIMD3<Float>
    
    public init(position: SIMD3<Float> = .zero, rotation: SIMD4<Float> = SIMD4<Float>(0, 0, 0, 1),
                scale: SIMD3<Float> = SIMD3<Float>(1, 1, 1)) {
        self.position = position
        self.rotation = rotation
        self.scale = scale
    }
}

/// Light source
public struct Light {
    public enum LightType {
        case directional
        case point
        case spot
    }
    
    public var type: LightType
    public var position: SIMD3<Float>
    public var direction: SIMD3<Float>
    public var color: SIMD3<Float>
    public var intensity: Float
    
    public init(type: LightType, position: SIMD3<Float> = .zero, direction: SIMD3<Float> = SIMD3<Float>(0, -1, 0),
                color: SIMD3<Float> = SIMD3<Float>(1, 1, 1), intensity: Float = 1.0) {
        self.type = type
        self.position = position
        self.direction = direction
        self.color = color
        self.intensity = intensity
    }
}

/// Opaque handle for mesh resources
public struct MeshHandle: Hashable {
    public let id: UUID
    public init(id: UUID = UUID()) { self.id = id }
}

/// Opaque handle for material resources
public struct MaterialHandle: Hashable {
    public let id: UUID
    public init(id: UUID = UUID()) { self.id = id }
}

/// Opaque handle for texture resources
public struct TextureHandle: Hashable {
    public let id: UUID
    public init(id: UUID = UUID()) { self.id = id }
}

// MARK: - Renderer Protocol

/// Primary rendering abstraction - all rendering backends must conform to this
public protocol Renderer: Sendable {
    /// Initialize the renderer with the given configuration
    func initialize(config: RendererConfig) async throws
    
    /// Begin a new frame
    func beginFrame() throws
    
    /// Draw the current scene
    func draw(scene: Scene) throws
    
    /// End the current frame and present
    func endFrame() throws
    
    /// Shutdown and cleanup resources
    func shutdown() async
    
    /// Load a mesh into GPU memory
    func loadMesh(vertices: [Vertex], indices: [UInt32]) async throws -> MeshHandle
    
    /// Load a texture into GPU memory
    func loadTexture(data: Data, width: Int, height: Int, format: TextureFormat) async throws -> TextureHandle
    
    /// Create a material
    func createMaterial(albedoTexture: TextureHandle?, normalTexture: TextureHandle?) async throws -> MaterialHandle
    
    /// Get renderer capabilities and information
    var info: RendererInfo { get }
}

/// Renderer configuration
public struct RendererConfig: Sendable {
    public var windowHandle: UnsafeMutableRawPointer?
    public var width: Int
    public var height: Int
    public var vsyncEnabled: Bool
    public var msaaSamples: Int
    
    public init(windowHandle: UnsafeMutableRawPointer? = nil, width: Int = 1920, height: Int = 1080,
                vsyncEnabled: Bool = true, msaaSamples: Int = 4) {
        self.windowHandle = windowHandle
        self.width = width
        self.height = height
        self.vsyncEnabled = vsyncEnabled
        self.msaaSamples = msaaSamples
    }
}

/// Renderer information
public struct RendererInfo: Sendable {
    public var apiName: String
    public var apiVersion: String
    public var deviceName: String
    public var maxTextureSize: Int
    
    public init(apiName: String, apiVersion: String, deviceName: String, maxTextureSize: Int) {
        self.apiName = apiName
        self.apiVersion = apiVersion
        self.deviceName = deviceName
        self.maxTextureSize = maxTextureSize
    }
}

/// Vertex data structure
public struct Vertex: Sendable {
    public var position: SIMD3<Float>
    public var normal: SIMD3<Float>
    public var uv: SIMD2<Float>
    public var tangent: SIMD3<Float>
    
    public init(position: SIMD3<Float>, normal: SIMD3<Float>, uv: SIMD2<Float>, tangent: SIMD3<Float> = .zero) {
        self.position = position
        self.normal = normal
        self.uv = uv
        self.tangent = tangent
    }
}

/// Texture format enumeration
public enum TextureFormat: Sendable {
    case rgba8
    case rgba16f
    case rgba32f
    case depth24stencil8
}