Add a CoreGraphics cross-import overlay with support for attaching `CGImage`s. #827

grynspan · 2024-11-16T18:45:41Z

This PR adds a new cross-import overlay target with Apple's Core Graphics framework that allows attaching a CGImage as an attachment in an arbitrary image format (PNG, JPEG, etc.)

Because CGImage is imported into Swift as a non-final class, it cannot conform directly to Attachable, so an AttachableContainer type acts as a proxy. This type is not meant to be used directly, so its name is underscored. Initializers on Attachment are provided so that this abstraction is almost entirely transparent to test authors.

A new protocol, AttachableAsCGImage, is introduced that abstracts away the relationship between the attached image and Core Graphics; in the future, I intend to make additional image types like NSImage and UIImage conform to this protocol too.

Example usage:

let sparklyDiamonds: CGImage = ...
let attachment = Attachment(image, named: "sparkly-diamonds", as: .tiff, encodingQuality: 0.75)
...
attachment.attach()

The code in this PR is, by definition, specific to Apple's platforms. In the future, I'd be interested in adding Windows/Linux equivalents (HBITMAP? Whatever Gnome/KDE/Qt use?) but that's beyond the scope of this PR.

Checklist:

Code and documentation should follow the style of the Style Guide.
If public symbols are renamed or modified, DocC references should be updated.

grynspan · 2024-11-16T18:45:48Z

@swift-ci test

Package.swift

Sources/Overlays/_Testing_CoreGraphics/Attachments/ImageAttachmentError.swift

Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageContainer.swift

Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift

…GImage`s. This PR adds a new cross-import overlay target with Apple's Core Graphics framework that allows attaching a `CGImage` as an attachment in an arbitrary image format (PNG, JPEG, etc.) Because `CGImage` is imported into Swift as a non-final class, it cannot conform directly to `Attachable`, so an `AttachableContainer` type acts as a proxy. This type is not meant to be used directly, so its name is underscored. Initializers on `Attachment` are provided so that this abstraction is almost entirely transparent to test authors. A new protocol, `AttachableAsCGImage`, is introduced that abstracts away the relationship between the attached image and Core Graphics; in the future, I intend to make additional image types like `NSImage and `UIImage` conform to this protocol too. The code in this PR is, by definition, specific to Apple's platforms. In the future, I'd be interested in adding Windows/Linux equivalents (`HBITMAP`? Whatever Gnome/KDE/Qt use?) but that's beyond the scope of this PR.

grynspan · 2024-12-06T00:41:31Z

@swift-ci test

Sources/Overlays/_Testing_CoreGraphics/Attachments/ImageAttachmentError.swift

grynspan · 2024-12-09T16:50:11Z

@swift-ci test

Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift

This PR adds on to the Core Graphics cross-import overlay added in #827 to allow attaching instances of `NSImage` to a test. `NSImage` is a more complicated animal because it is not `Sendable`, but we don't want to make a (potentially very expensive) deep copy of its data until absolutely necessary. So we check inside the image to see if its contained representations are known to be safely copyable (i.e. copies made with `NSCopying` do not share any mutable state with their originals.) If it looks safe to make a copy of the image by calling `copy()`, we do so; otherwise, we try to make a deep copy of the image. Due to how Swift implements polymorphism in protocol requirements, and because we don't really know what they're doing, subclasses of `NSImage` just get a call to `copy()` instead of deep introspection. `UIImage` support will be implemented in a separate PR. > [!NOTE] > Attachments remain an experimental feature.

grynspan added enhancement New feature or request darwin 🍎 macOS, iOS, watchOS, tvOS, and visionOS support public-api Affects public API attachments/activities 🖇️ Work related to attachments and/or activities labels Nov 16, 2024

grynspan self-assigned this Nov 16, 2024

grynspan requested review from stmontgomery, dennisweissmann, briancroom, SeanROlszewski and suzannaratcliff as code owners November 16, 2024 18:45

grynspan force-pushed the jgrynspan/coregraphics-overlay branch from 753920d to 0e9b551 Compare November 16, 2024 19:06