8비트 거울

    /// The lower layer's new tiles after `upperID` is merged into it with the
    /// upper layer's blend mode, opacity, clipping and mask; the lower
    /// layer's own mask is applied too, so the result needs no mask (an
    /// enabled mask is baked, a disabled one let everything through). The
    /// lower layer keeps its other properties; only its pixels change.
    ///
    /// The layers are uploaded at 16 bits per channel and composited in
    /// 32-bit float over just the region they cover, so a merge never drops
    /// the lower layer to the display mirror's 8 bits (soft, faint paint
    /// would lose its color).
    public func mergedTiles(of artwork: Artwork, upper upperID: UUID) throws -> [TileKey: TileBuffer] {
        guard let upperIndex = artwork.index(of: upperID), upperIndex > 0 else { return [:] }
        let upper = artwork.layers[upperIndex]
        let lower = artwork.layers[upperIndex - 1]
        let size = artwork.size
        let keys = Set(lower.tiles.keys).union(upper.tiles.keys).filter { PixelRect(tile: $0).clipped(to: size) != nil }
        guard !keys.isEmpty else { return [:] }
        let region = keys.map { PixelRect(tile: $0) }.reduce(PixelRect(tile: keys.first!)) { $0.union($1) }

        // Slices: 0 lower, 1 upper, then each enabled mask's paint.
        // ... the tile stores of the lower layer, the upper layer and any enabled masks go into `sources` ...

        let arrayDescriptor = MTLTextureDescriptor()
        arrayDescriptor.textureType = .type2DArray
        arrayDescriptor.pixelFormat = .rgba16Unorm
        arrayDescriptor.width = region.width
        arrayDescriptor.height = region.height
        arrayDescriptor.arrayLength = sources.count
        arrayDescriptor.usage = [.shaderRead]
        arrayDescriptor.storageMode = .shared
        let targetDescriptor = MTLTextureDescriptor.texture2DDescriptor(pixelFormat: .rgba32Float, width: region.width,
                                                                        height: region.height, mipmapped: false)
        targetDescriptor.usage = [.shaderRead, .shaderWrite]
        targetDescriptor.storageMode = .shared
        guard let array = device.makeTexture(descriptor: arrayDescriptor),
              let target = device.makeTexture(descriptor: targetDescriptor),
              let commandBuffer = queue.makeCommandBuffer() else {
            throw RendererError.outOfMemory("merge \(region.width)×\(region.height)")
        }
        var tile16 = [UInt16](repeating: 0, count: Tile.valueCount)
        let zero = [UInt16](repeating: 0, count: Tile.valueCount)
        for (slice, store) in sources.enumerated() {
            for key in keys {
                let origin = key.pixelOrigin
                // Every tile of the region is written, empty ones as zeros, so no slice reads stale memory.
                if let tile = store.tile(at: key) {
                    tile16.withUnsafeMutableBufferPointer { buffer in
                        ard_fix15_to_rgba16_premultiplied(tile.pixels, buffer.baseAddress!, Tile.pixelCount)
                    }
                    tile16.withUnsafeBytes { bytes in
                        array.replace(region: MTLRegionMake2D(origin.x - region.x, origin.y - region.y, Tile.size, Tile.size),
                                      mipmapLevel: 0, slice: slice, withBytes: bytes.baseAddress!,
                                      bytesPerRow: Tile.size * 8, bytesPerImage: Tile.size * Tile.size * 8)
                    }
                } else {
                    zero.withUnsafeBytes { bytes in
                        array.replace(region: MTLRegionMake2D(origin.x - region.x, origin.y - region.y, Tile.size, Tile.size),
                                      mipmapLevel: 0, slice: slice, withBytes: bytes.baseAddress!,
                                      bytesPerRow: Tile.size * 8, bytesPerImage: Tile.size * Tile.size * 8)
                    }
                }
            }
        }
        // ... the stack: the lower layer at opacity 1, then the upper layer with its blend, opacity, clip and mask ...
        compose(stack: stack, background: nil, region: PixelRect(x: 0, y: 0, width: region.width, height: region.height),
                layers: array, into: target, commandBuffer: commandBuffer)
        commandBuffer.commit()
        commandBuffer.waitUntilCompleted()

        var tiles: [TileKey: TileBuffer] = [:]
        var row = [Float](repeating: 0, count: Tile.size * 4)
        for key in keys {
            guard let rect = PixelRect(tile: key).clipped(to: size) else { continue }
            let tile = TileBuffer()
            let origin = key.pixelOrigin
            for y in rect.y..<(rect.y + rect.height) {
                row.withUnsafeMutableBytes { bytes in
                    target.getBytes(bytes.baseAddress!, bytesPerRow: Tile.size * 16,
                                    from: MTLRegionMake2D(rect.x - region.x, y - region.y, rect.width, 1), mipmapLevel: 0)
                }
                let base = ((y - origin.y) * Tile.size + (rect.x - origin.x)) * 4
                for i in 0..<(rect.width * 4) {
                    let value = row[i] * Float(Tile.fix15One)
                    tile.pixels[base + i] = UInt16(min(Float(Tile.fix15One), max(0, value.rounded())))
                }
            }
            if !tile.isTransparent {
                tiles[key] = tile
            }
        }
        return tiles
    }

    @Test func mergingKeepsTheColorOfFaintPaint() throws {
        // At alpha 2/255 the display mirror's premultiplied 8 bits hold almost
        // no color; a merge must not go through it.
        let renderer = try CanvasRenderer()
        let artwork = Artwork(size: CanvasSize(width: 64, height: 64), background: nil)
        artwork.fillLayer(artwork.activeLayerID, with: RGBAColor(red: 0.3, green: 0.6, blue: 0.9, alpha: 0.008))
        let upper = artwork.addLayer()
        artwork.fillLayer(upper.id, with: RGBAColor(red: 1, green: 1, blue: 1, alpha: 0.0))
        let merged = try renderer.mergedTiles(of: artwork, upper: upper.id)
        artwork.mergeDown(upper.id, merged: merged)
        let p = artwork.activeLayer.tiles.tile(at: TileKey(x: 0, y: 0))!.color(atX: 5, y: 5)
        #expect(abs(p.r / p.a - 0.3) < 0.02 && abs(p.g / p.a - 0.6) < 0.02 && abs(p.b / p.a - 0.9) < 0.02,
                "straight color survives: \(p.r / p.a), \(p.g / p.a), \(p.b / p.a)")
    }

// A minimal sketch of why merge down must not read the 8-bit display mirror.
// Tiles hold premultiplied fix15 (1.0 = 32768). A merge reads both layers at
// some precision, composites in float, and writes fix15 back into the lower layer.
// Build and run: swiftc -swift-version 6 mirror.swift -o mirror && ./mirror
typealias Pixel = SIMD4<Double>                 // premultiplied r, g, b, a in 0...1

let one = 32768.0                                // fix15's 1.0

func toFix15(_ p: Pixel) -> SIMD4<UInt32> {      // what a layer stores
    func c(_ v: Double) -> UInt32 { UInt32(min(one, max(0, (v * one).rounded()))) }
    return SIMD4(c(p.x), c(p.y), c(p.z), c(p.w))
}

// Upload at `bits` per channel, rounding as ard_fix15_to_rgba8/16_premultiplied do.
func read(_ v: SIMD4<UInt32>, bits: UInt32) -> Pixel {
    let maximum = (UInt32(1) << bits) - 1
    func q(_ c: UInt32) -> Double { Double((c * maximum + 16384) >> 15) / Double(maximum) }
    return Pixel(q(v.x), q(v.y), q(v.z), q(v.w))
}

func over(_ dst: Pixel, _ src: Pixel) -> Pixel { src + dst * (1 - src.w) }   // Normal, premultiplied

func straight(_ v: SIMD4<UInt32>) -> String {
    guard v.w > 0 else { return "transparent" }
    let a = Double(v.w)
    func f(_ c: UInt32) -> String { String(Int((Double(c) / a * 1000).rounded())) }
    return "rgb/1000 = (\(f(v.x)), \(f(v.y)), \(f(v.z)))  alpha/32768 = \(v.w)"
}

let blue = SIMD3<Double>(0.3, 0.6, 0.9)
func glaze(_ alpha: Double) -> Pixel { Pixel(blue.x * alpha, blue.y * alpha, blue.z * alpha, alpha) }

// 1. One faint layer (alpha 0.008, the engine test's value) merged with an empty one.
let faint = toFix15(glaze(0.008))
print("truth           ", straight(faint))
for bits: UInt32 in [8, 16] {
    let merged = toFix15(over(read(faint, bits: bits), read(SIMD4(0, 0, 0, 0), bits: bits)))
    print("merge at \(bits) bits".padding(16), straight(merged))
}

// 2. Forty glazes of alpha 0.01, merged down one at a time: every merge re-reads
//    the growing lower layer at the mirror's precision, so the error compounds.
var exact = Pixel(0, 0, 0, 0)
var lower8 = SIMD4<UInt32>(0, 0, 0, 0), lower16 = SIMD4<UInt32>(0, 0, 0, 0)
for _ in 0..<40 {
    let upper = toFix15(glaze(0.01))
    exact = over(exact, glaze(0.01))
    lower8 = toFix15(over(read(lower8, bits: 8), read(upper, bits: 8)))
    lower16 = toFix15(over(read(lower16, bits: 16), read(upper, bits: 16)))
}
print("40 glazes, float ", straight(toFix15(exact)))
print("40 glazes, 8-bit ", straight(lower8))
print("40 glazes, 16-bit", straight(lower16))

extension String {
    func padding(_ width: Int) -> String { self + String(repeating: " ", count: max(0, width - count)) }
}

// Prints:
// truth            rgb/1000 = (302, 599, 901)  alpha/32768 = 262
// merge at 8 bits  rgb/1000 = (502, 502, 1000)  alpha/32768 = 257
// merge at 16 bits rgb/1000 = (302, 599, 901)  alpha/32768 = 262
// 40 glazes, float  rgb/1000 = (300, 600, 900)  alpha/32768 = 10847
// 40 glazes, 8-bit  rgb/1000 = (417, 656, 656)  alpha/32768 = 12196
// 40 glazes, 16-bit rgb/1000 = (299, 600, 899)  alpha/32768 = 10861