Brightroom Documentation

Brightroom v4 is a major release that shifts the public UI surface from UIKit-first controllers to SwiftUI-first views. It replaces the Verge dependency with swift-state-graph and raises the minimum deployment target to iOS 17.

Migration Checklist

1. Update Platform: Raise deployment target to iOS 17 or later.
2. Update Dependencies: Remove Verge and BrightroomUIPhotosCrop. Add swift-state-graph and use BrightroomUI instead.
3. Update State Access: Replace .store access on EditingStack and ImageProvider with direct property access.
4. Replace UI Components:
   • Replace ClassicImageEditViewController with SwiftUIPixelEditorView.
   • Replace PhotosCropViewController with SwiftUIPhotosCropView.
   • Replace direct UIKit views (like CropView) with their SwiftUI wrappers (like SwiftUICropView).
5. Update Presets: Move colorCubeStorage setup to PresetStorage.
6. Verify Flows: Re-test image loading, cropping, masking, filtering, undo, and rendering.

To measure performance, use one of the following two methods. Note that simulator wall-clock GPU time is not device-representative; for accurate GPU profiling, use a real device with Instruments or xctrace.

1. Deterministic per-path numbers

Run the EnginePerformanceWorkloadTests using xcodebuild. This uses XCTClockMetric and XCTCPUMetric. The CPU Instructions Retired metric is the most reliable for cross-device comparison.

2. Call-tree / flame graph

Use the Instruments GUI (CPU Profiler) to profile the Simulator process:

1. Open Instruments.
2. Select the Device dropdown.
3. Choose Running Simulators.
4. Attach to the SwiftUIDemo process.
5. Record while driving PhotosCrop.
6. Stop recording and select Invert Call Tree to view the heaviest self-cycles.

cd Dev && xcodebuild test \
  -scheme BrightroomEngineTests \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.5' \
  -only-testing:BrightroomEngineTests/EnginePerformanceWorkloadTests

Persistence is handled by the ParametricDocumentCodec. You must register your feature types with the codec before encoding or decoding to ensure the registry can resolve type keys to concrete Swift types.

1. Initialize a ParametricDocumentCodec.
2. Register each feature type using .register(Type.self).
3. Use .encode(document) to produce data.
4. Use .decode(data) to reconstruct the typed document.

public protocol PersistableFeature: Feature, Codable {
  static var featureTypeKey: FeatureTypeKey { get }
  static var schemaVersion: Int { get }
  // Default implementations decode the current version via Codable.
  static func decodeParameters(from decoder: Decoder, version: Int) throws -> Self
}

var codec = ParametricDocumentCodec()
codec.register(Posterize.self)                  // UICollectionView-style
let data = try codec.encode(document)
let document = try codec.decode(data)           // one pass, typed values out

The current interactive preview architecture uses a viewport-sized MTKView path rather than a tiled grid. This mode aims to bound interactive costs by the drawable size instead of the original image size.

Expected Behavior:

• Pan/Zoom: Changes invalidate the viewport source texture.
• Filter/Blur Sliders: Changes reuse the existing viewport-sized source texture.
• Global Filters: Run against a small CIImage(mtlTexture:) source rather than the original large image graph.
• Local Adjustments: Effects and mask composites stay within viewport-sized work.
• Radius Effects: Scale their radius into viewport pixel space.
• Composition: Local Exposure and Blur compose through CIBlendWithAlphaMask rather than a custom Metal shader.
• Drawing: Active strokes are rasterized into the same viewport mask texture as committed strokes, making drawing visible before commitment.