@swiftbrowser/native 0.18.3 → 0.21.0

package/swift/Packages/SwiftBrowserShader/README.md

@@ -0,0 +1,45 @@
+# SwiftBrowserShader
+
+The native side of [@swiftbrowser/shader](../../../packages/shader): a
+shader written in the shader language, compiled by the package's TypeScript
+compiler to the Metal Shading Language (beside GLSL and JavaScript for a
+page), drawn by an `MTKView` over a `ShaderView`'s box. The JavaScript only
+sends the shader, its uniforms and its textures; nothing per pixel runs
+there.
+
+It is a package of its own, as SwiftBrowserDSP is, so only an app that
+draws with shaders links it. @swiftbrowser/native ships it beside the core
+(`node_modules/@swiftbrowser/native/swift/Packages/SwiftBrowserShader`; it
+depends on `SwiftBrowserNative` at `../..`, here and there). Link it into
+the app's Xcode project with `npx swiftbrowser native add shader` (or
+`native init --with shader`) and install it at launch:
+
+```swift
+import SwiftBrowserShader
+
+init() {
+    SwiftBrowserShader.install()
+}
+```
+
+That registers `ShaderView`'s view (`SwiftBrowserShader.view`) with
+SwiftBrowserNative's `ViewRegistry`. Without it, a `ShaderView` shows its
+name, as any registered view nothing registered does.
+
+- **SwiftBrowserShaderCore** is the view's props alone: the shader's layout
+  (`ShaderLayout`, every uniform inside the floats a draw reads), its
+  textures, and the floats packed as the JavaScript packs them on a page
+  (`packedUniforms`). No Apple framework, so it builds and tests on Linux.
+- **SwiftBrowserShader** is the view: `ShaderRenderer` compiles a shader's
+  Metal when a view first draws it (`makeLibrary(source:)`, kept for every
+  view that draws the same source), uploads its textures as `r32Float`, and
+  draws one triangle over the view with the uniforms in a fragment buffer.
+  The `MTKView` draws when its props or its size change, or every display
+  frame when the view is `animated`. A shader its device does not compile
+  draws nothing and sends the compiler's message to `onError`, once.
+
+The tests (`swift test`) read @swiftbrowser/shader's render fixtures
+(packages/shader/test/fixtures/render.json) and, on a Mac, compile each
+case's Metal, draw it into a texture and hold its pixels to the ones the
+package's JavaScript backend drew (printed as `[shader render]`), as the
+page's tests hold WebGL2's.

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShader/ShaderRenderer.swift

@@ -0,0 +1,103 @@
+#if canImport(Metal)
+import Metal
+@_exported import SwiftBrowserShaderCore
+
+/// What draws a shader with Metal: its pipeline (the library compiled once
+/// for a source, kept for every view that draws it), its textures, and a
+/// draw into a render pass. `ShaderView`'s `MTKView` draws through it, and
+/// the tests draw into a texture of their own.
+@MainActor
+public final class ShaderRenderer {
+    public let device: MTLDevice
+    public let pixelFormat: MTLPixelFormat
+    private var pipeline: MTLRenderPipelineState?
+    private var source = ""
+    private var textures: [MTLTexture] = []
+    private var uploaded: [ShaderTextureData?] = []
+    /// A texture of one zero for a slot the view was given nothing for: a draw reads every slot it declares.
+    private lazy var blank: MTLTexture? = Self.texture(device: device, width: 1, height: 1, data: [0])
+
+    /// Pipelines by source and pixel format, for every view: a library compiles in tens of milliseconds.
+    private static var pipelines: [String: MTLRenderPipelineState] = [:]
+
+    public init(device: MTLDevice, pixelFormat: MTLPixelFormat = .bgra8Unorm) {
+        self.device = device
+        self.pixelFormat = pixelFormat
+    }
+
+    public enum Failure: Error, CustomStringConvertible {
+        case compile(String)
+        case missing(String)
+
+        public var description: String {
+            switch self {
+            case .compile(let message): return message
+            case .missing(let name): return "the library has no function \(name)"
+            }
+        }
+    }
+
+    /// Makes ready to draw `props`: its pipeline compiled (or found) and its textures uploaded when they changed.
+    /// Throws the compiler's message when its Metal does not compile.
+    public func prepare(_ props: ShaderProps) throws {
+        guard let shader = props.shader else {
+            pipeline = nil
+            return
+        }
+        if shader.msl != source {
+            source = shader.msl
+            pipeline = nil
+            pipeline = try Self.pipeline(device: device, source: shader.msl, pixelFormat: pixelFormat)
+        }
+        if props.textures != uploaded || textures.count != shader.textures.count {
+            uploaded = props.textures
+            textures = shader.textures.indices.compactMap { slot in
+                let data = slot < props.textures.count ? props.textures[slot] : nil
+                return data.flatMap { Self.texture(device: device, width: $0.width, height: $0.height, data: $0.data) } ?? blank
+            }
+        }
+    }
+
+    /// Draws into `encoder`'s pass (which `prepare` made ready), the view `width` × `height` points at `scale` pixels
+    /// a point, `time` seconds in.
+    public func draw(_ props: ShaderProps, into encoder: MTLRenderCommandEncoder, width: Double, height: Double, scale: Double, time: Double) {
+        guard let pipeline, let shader = props.shader, textures.count == shader.textures.count else { return }
+        var floats = props.packedUniforms(width: width, height: height, scale: scale, time: time)
+        encoder.setRenderPipelineState(pipeline)
+        encoder.setFragmentBytes(&floats, length: MemoryLayout<Float>.stride * floats.count, index: 0)
+        for (slot, texture) in textures.enumerated() { encoder.setFragmentTexture(texture, index: slot) }
+        encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
+    }
+
+    static func pipeline(device: MTLDevice, source: String, pixelFormat: MTLPixelFormat) throws -> MTLRenderPipelineState {
+        let key = "\(pixelFormat.rawValue)\n\(source)"
+        if let found = pipelines[key] { return found }
+        let library: MTLLibrary
+        do {
+            library = try device.makeLibrary(source: source, options: nil)
+        } catch {
+            throw Failure.compile(String(describing: error))
+        }
+        guard let vertex = library.makeFunction(name: "sb_vertex") else { throw Failure.missing("sb_vertex") }
+        guard let fragment = library.makeFunction(name: "sb_fragment") else { throw Failure.missing("sb_fragment") }
+        let descriptor = MTLRenderPipelineDescriptor()
+        descriptor.vertexFunction = vertex
+        descriptor.fragmentFunction = fragment
+        descriptor.colorAttachments[0].pixelFormat = pixelFormat
+        let made = try device.makeRenderPipelineState(descriptor: descriptor)
+        pipelines[key] = made
+        return made
+    }
+
+    /// A texture of one float a texel, read with `read` (no filtering: the shader's `sample` interpolates).
+    static func texture(device: MTLDevice, width: Int, height: Int, data: [Float]) -> MTLTexture? {
+        let descriptor = MTLTextureDescriptor.texture2DDescriptor(pixelFormat: .r32Float, width: width, height: height, mipmapped: false)
+        descriptor.usage = .shaderRead
+        guard let texture = device.makeTexture(descriptor: descriptor), data.count >= width * height else { return nil }
+        data.withUnsafeBytes { bytes in
+            texture.replace(region: MTLRegionMake2D(0, 0, width, height), mipmapLevel: 0, withBytes: bytes.baseAddress!, bytesPerRow: width * MemoryLayout<Float>.stride)
+        }
+        return texture
+    }
+}
+#endif

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShader/ShaderView.swift

@@ -0,0 +1,168 @@
+#if canImport(MetalKit) && canImport(SwiftUI)
+import MetalKit
+import SwiftBrowserNative
+import SwiftBrowserProtocol
+import SwiftUI
+
+/// The native side of @swiftbrowser/shader: installs `ShaderView`'s view, an
+/// `MTKView` that draws the shader's Metal over its box.
+///
+/// ```swift
+/// import SwiftBrowserShader
+///
+/// init() {
+///     SwiftBrowserShader.install()
+/// }
+/// ```
+@MainActor
+public enum SwiftBrowserShader {
+    /// The name `ShaderView` is registered under, on both platforms (view.ts `SHADER_VIEW`).
+    public static let viewName = "SwiftBrowserShader.view"
+
+    /// Registers `ShaderView`'s SwiftUI view; call at launch, before the bundle loads.
+    public static func install() {
+        ViewRegistry.register(viewName) { context in
+            ShaderSurface(props: ShaderProps(props: context.props), send: context.send)
+        }
+    }
+}
+
+/// `ShaderView` (@swiftbrowser/shader): the shader drawn when its props or its size change, or every display frame
+/// when `animated`. A shader its device does not compile draws nothing and says why (`onError`), once.
+struct ShaderSurface: View {
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    var body: some View {
+        if let device = SharedDevice.device {
+            MetalShaderView(device: device, props: props, send: send)
+        } else {
+            Color.clear
+        }
+    }
+}
+
+@MainActor
+private enum SharedDevice {
+    static let device: MTLDevice? = MTLCreateSystemDefaultDevice()
+}
+
+/// Draws for an `MTKView`: on demand (`setNeedsDisplay`) unless animated.
+@MainActor
+final class ShaderDrawing: NSObject, MTKViewDelegate {
+    let renderer: ShaderRenderer
+    let queue: MTLCommandQueue?
+    var props: ShaderProps
+    var send: (JSONValue) -> Void
+    private var reported = ""
+    private var started = Date()
+
+    init(device: MTLDevice, props: ShaderProps, send: @escaping (JSONValue) -> Void) {
+        renderer = ShaderRenderer(device: device)
+        queue = device.makeCommandQueue()
+        self.props = props
+        self.send = send
+    }
+
+    func configure(_ view: MTKView) {
+        view.device = renderer.device
+        view.colorPixelFormat = renderer.pixelFormat
+        view.clearColor = MTLClearColor(red: 0, green: 0, blue: 0, alpha: 0)
+        view.framebufferOnly = true
+        view.delegate = self
+        #if os(macOS)
+        view.layer?.isOpaque = false
+        #else
+        view.isOpaque = false
+        view.backgroundColor = .clear
+        #endif
+        update(view)
+    }
+
+    /// New props: drawn at once, or from now on every frame when animated.
+    func update(_ view: MTKView) {
+        if !props.animated { started = Date() }
+        view.isPaused = !props.animated
+        view.enableSetNeedsDisplay = !props.animated
+        view.preferredFramesPerSecond = 60
+        redraw(view)
+    }
+
+    private func redraw(_ view: MTKView) {
+        #if os(macOS)
+        view.needsDisplay = true
+        #else
+        view.setNeedsDisplay()
+        #endif
+    }
+
+    func mtkView(_ view: MTKView, drawableSizeWillChange size: CGSize) {
+        redraw(view)
+    }
+
+    func draw(in view: MTKView) {
+        do {
+            try renderer.prepare(props)
+        } catch {
+            let message = String(describing: error)
+            if message != reported {
+                reported = message
+                send(.object(["error": .string(message)]))
+            }
+        }
+        let bounds = view.bounds.size
+        guard bounds.width > 0, bounds.height > 0, let pass = view.currentRenderPassDescriptor, let drawable = view.currentDrawable,
+              let buffer = queue?.makeCommandBuffer(), let encoder = buffer.makeRenderCommandEncoder(descriptor: pass) else { return }
+        // The scale the drawable has, so that a point's rows and its pixels line up.
+        let scale = view.drawableSize.height / bounds.height
+        renderer.draw(props, into: encoder, width: bounds.width, height: bounds.height, scale: scale, time: Date().timeIntervalSince(started))
+        encoder.endEncoding()
+        buffer.present(drawable)
+        buffer.commit()
+    }
+}
+
+#if os(macOS)
+private struct MetalShaderView: NSViewRepresentable {
+    let device: MTLDevice
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    func makeCoordinator() -> ShaderDrawing { ShaderDrawing(device: device, props: props, send: send) }
+
+    func makeNSView(context: Context) -> MTKView {
+        let view = MTKView(frame: .zero, device: device)
+        context.coordinator.configure(view)
+        return view
+    }
+
+    func updateNSView(_ view: MTKView, context: Context) {
+        context.coordinator.send = send
+        guard context.coordinator.props != props else { return }
+        context.coordinator.props = props
+        context.coordinator.update(view)
+    }
+}
+#else
+private struct MetalShaderView: UIViewRepresentable {
+    let device: MTLDevice
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    func makeCoordinator() -> ShaderDrawing { ShaderDrawing(device: device, props: props, send: send) }
+
+    func makeUIView(context: Context) -> MTKView {
+        let view = MTKView(frame: .zero, device: device)
+        context.coordinator.configure(view)
+        return view
+    }
+
+    func updateUIView(_ view: MTKView, context: Context) {
+        context.coordinator.send = send
+        guard context.coordinator.props != props else { return }
+        context.coordinator.props = props
+        context.coordinator.update(view)
+    }
+}
+#endif
+#endif

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShaderCore/ShaderProps.swift

@@ -0,0 +1,120 @@
+import SwiftBrowserProtocol
+
+/// A compiled shader as `ShaderView` sends it natively (@swiftbrowser/shader's
+/// `CompiledShader` with only its Metal): where each uniform's floats are,
+/// how many floats a draw reads, its textures' names in slot order, and the
+/// Metal library (`sb_vertex`, `sb_fragment`).
+public struct ShaderLayout: Equatable, Sendable {
+    public struct Uniform: Equatable, Sendable {
+        public let name: String
+        public let offset: Int
+        public let size: Int
+        public let value: [Float]
+    }
+
+    public let uniforms: [Uniform]
+    public let floats: Int
+    public let textures: [String]
+    public let msl: String
+
+    /// The floats every shader starts with (shader.ts `BUILTIN_UNIFORMS`): width, height, scale, time.
+    public static let builtins = 4
+
+    public init?(json: JSONValue) {
+        guard let msl = json["msl"].string, let floats = json["floats"].int, floats >= Self.builtins, floats <= 1024 else { return nil }
+        var uniforms: [Uniform] = []
+        for entry in json["uniforms"].array ?? [] {
+            guard let name = entry["name"].string, let offset = entry["offset"].int, let size = entry["size"].int,
+                  (1...4).contains(size), offset >= Self.builtins, offset + size <= floats else { return nil }
+            let value = (entry["value"].array ?? []).map { Float($0.double ?? 0) }
+            uniforms.append(Uniform(name: name, offset: offset, size: size, value: value))
+        }
+        self.uniforms = uniforms
+        self.floats = floats
+        self.textures = (json["textures"].array ?? []).compactMap(\.string)
+        self.msl = msl
+    }
+}
+
+/// A float texture: `width` × `height` values, row by row (row 0 at the top).
+public struct ShaderTextureData: Equatable, Sendable {
+    public let width: Int
+    public let height: Int
+    public let data: [Float]
+
+    public init?(json: JSONValue) {
+        guard let width = json["width"].int, let height = json["height"].int, width > 0, height > 0,
+              let values = json["data"].array, values.count >= width * height else { return nil }
+        self.width = width
+        self.height = height
+        self.data = values.prefix(width * height).map { Float($0.double ?? 0) }
+    }
+}
+
+/// `ShaderView`'s props (packages/shader/src/view.ts): the shader, its uniforms by name, its textures by slot, and
+/// whether it draws every frame.
+public struct ShaderProps: Equatable, Sendable {
+    public let shader: ShaderLayout?
+    public let uniforms: JSONObject
+    public let textures: [ShaderTextureData?]
+    public let animated: Bool
+
+    public init(props: JSONValue) {
+        shader = ShaderLayout(json: props["shader"])
+        uniforms = props["uniforms"].object ?? [:]
+        textures = (props["textures"].array ?? []).map(ShaderTextureData.init(json:))
+        animated = props["animated"].bool ?? false
+    }
+
+    /**
+     * The floats a draw reads (shader.ts `packUniforms`): the view's size in points, its pixels a point and the
+     * seconds it has run, then each uniform as given (a number, a vector, or a `#rrggbb` color), its default when
+     * absent or of another size, a color of three components taking alpha 1 where four are wanted.
+     */
+    public func packedUniforms(width: Double, height: Double, scale: Double, time: Double) -> [Float] {
+        guard let shader else { return [] }
+        var floats = [Float](repeating: 0, count: shader.floats)
+        floats[0] = Float(width)
+        floats[1] = Float(height)
+        floats[2] = Float(scale)
+        floats[3] = Float(time)
+        for uniform in shader.uniforms {
+            var given = uniforms[uniform.name].flatMap(Self.floats(of:))
+            if let three = given, three.count == 3, uniform.size == 4 { given = three + [1] }
+            let value = given.flatMap { $0.count == uniform.size ? $0 : nil } ?? uniform.value
+            for i in 0..<uniform.size { floats[uniform.offset + i] = i < value.count ? value[i] : 0 }
+        }
+        return floats
+    }
+
+    /// A uniform's value as floats: a number, an array of numbers, or a color.
+    static func floats(of value: JSONValue) -> [Float]? {
+        switch value {
+        case .number(let number): return number.isFinite ? [Float(number)] : nil
+        case .string(let text): return parseColor(text)
+        case .array(let items):
+            let numbers = items.compactMap(\.double)
+            return numbers.count == items.count ? numbers.map { Float($0) } : nil
+        default: return nil
+        }
+    }
+}
+
+/// A `#rrggbb` or `#rrggbbaa` color as 0 … 1 components (shader.ts `parseColor`).
+public func parseColor(_ text: String) -> [Float]? {
+    var digits = Substring(text)
+    while let first = digits.first, first.isWhitespace { digits = digits.dropFirst() }
+    while let last = digits.last, last.isWhitespace { digits = digits.dropLast() }
+    guard digits.first == "#" else { return nil }
+    digits = digits.dropFirst()
+    guard digits.count == 6 || digits.count == 8 else { return nil }
+    var components: [Float] = []
+    var index = digits.startIndex
+    while index < digits.endIndex {
+        let next = digits.index(index, offsetBy: 2)
+        guard let byte = UInt8(digits[index..<next], radix: 16) else { return nil }
+        components.append(Float(byte) / 255)
+        index = next
+    }
+    return components
+}