Merge branch 'main' into gsoc-development

Author: stmontgomery

Package.swift

@@ -254,7 +254,7 @@ let package = Package(
         "Testing",
       ],
       path: "Sources/Overlays/_Testing_WinSDK",
-      swiftSettings: .packageSettings + .enableLibraryEvolution() + [.interoperabilityMode(.Cxx)]
+      swiftSettings: .packageSettings + .enableLibraryEvolution()
     ),
 
     // Utility targets: These are utilities intended for use when developing

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

@@ -17,12 +17,11 @@ extension Attachment {
   /// Initialize an instance of this type that encloses the given image.
   ///
   /// - Parameters:
-  ///   - attachableValue: The value that will be attached to the output of
-  ///     the test run.
+  ///   - image: The value that will be attached to the output of the test run.
   ///   - preferredName: The preferred name of the attachment when writing it
   ///     to a test report or to disk. If `nil`, the testing library attempts
   ///     to derive a reasonable filename for the attached value.
-  ///   - imageFormat: The image format with which to encode `attachableValue`.
+  ///   - imageFormat: The image format with which to encode `image`.
   ///   - sourceLocation: The source location of the call to this initializer.
   ///     This value is used when recording issues associated with the
   ///     attachment.
@@ -45,12 +44,12 @@ extension Attachment {
   /// correspond to an image format the operating system knows how to write, the
   /// testing library selects an appropriate image format for you.
   public init<T>(
-    _ attachableValue: T,
+    _ image: T,
     named preferredName: String? = nil,
     as imageFormat: AttachableImageFormat? = nil,
     sourceLocation: SourceLocation = #_sourceLocation
   ) where AttachableValue == _AttachableImageWrapper<T> {
-    let imageWrapper = _AttachableImageWrapper(image: attachableValue, imageFormat: imageFormat)
+    let imageWrapper = _AttachableImageWrapper(image: image, imageFormat: imageFormat)
     self.init(imageWrapper, named: preferredName, sourceLocation: sourceLocation)
   }
 
@@ -61,7 +60,7 @@ extension Attachment {
   ///   - preferredName: The preferred name of the attachment when writing it to
   ///     a test report or to disk. If `nil`, the testing library attempts to
   ///     derive a reasonable filename for the attached value.
-  ///   - imageFormat: The image format with which to encode `attachableValue`.
+  ///   - imageFormat: The image format with which to encode `image`.
   ///   - sourceLocation: The source location of the call to this function.
   ///
   /// This function creates a new instance of ``Attachment`` wrapping `image`
@@ -94,4 +93,15 @@ extension Attachment {
     Self.record(attachment, sourceLocation: sourceLocation)
   }
 }
+
+@_spi(Experimental) // STOP: not part of ST-0014
+@available(_uttypesAPI, *)
+extension Attachment where AttachableValue: AttachableWrapper, AttachableValue.Wrapped: AttachableAsCGImage {
+  /// The image format to use when encoding the represented image.
+  @_disfavoredOverload
+  public var imageFormat: AttachableImageFormat? {
+    // FIXME: no way to express `where AttachableValue == _AttachableImageWrapper<???>` on a property
+    (attachableValue as? _AttachableImageWrapper<AttachableValue.Wrapped>)?.imageFormat
+  }
+}
 #endif

Sources/Overlays/_Testing_WinSDK/Attachments/AttachableAsGDIPlusImage.swift

@@ -0,0 +1,197 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+#if os(Windows)
+@_spi(Experimental) import Testing
+
+public import WinSDK
+
+/// A protocol describing images that can be converted to instances of
+/// ``Testing/Attachment``.
+///
+/// Instances of types conforming to this protocol do not themselves conform to
+/// ``Testing/Attachable``. Instead, the testing library provides additional
+/// initializers on ``Testing/Attachment`` that take instances of such types and
+/// handle converting them to image data when needed.
+///
+/// The following system-provided image types conform to this protocol and can
+/// be attached to a test:
+///
+/// - [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps)
+/// - [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons)
+/// - [`IWICBitmap`](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmap)
+///
+/// You do not generally need to add your own conformances to this protocol. If
+/// you have an image in another format that needs to be attached to a test,
+/// first convert it to an instance of one of the types above.
+@_spi(Experimental)
+public protocol _AttachableByAddressAsIWICBitmap {
+  /// Create a WIC bitmap representing an instance of this type at the given
+  /// address.
+  ///
+  /// - Parameters:
+  ///   - imageAddress: The address of the instance of this type.
+  ///   - factory: A WIC imaging factory that can be used to create additional
+  ///     WIC objects.
+  ///
+  /// - Returns: A pointer to a new WIC bitmap representing this image. The
+  ///   caller is responsible for releasing this image when done with it.
+  ///
+  /// - Throws: Any error that prevented the creation of the WIC bitmap.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  static func _copyAttachableIWICBitmap(
+    from imageAddress: UnsafeMutablePointer<Self>,
+    using factory: UnsafeMutablePointer<IWICImagingFactory>
+  ) throws -> UnsafeMutablePointer<IWICBitmap>
+
+  /// Make a copy of the instance of this type at the given address.
+  ///
+  /// - Parameters:
+  ///   - imageAddress: The address of the instance of this type that should be
+  ///     copied.
+  ///
+  /// - Returns: A copy of `imageAddress`, or `imageAddress` if this type does
+  ///   not support a copying operation.
+  ///
+  /// - Throws: Any error that prevented copying the value at `imageAddress`.
+  ///
+  /// The testing library uses this function to take ownership of image
+  /// resources that test authors pass to it. If possible, make a copy of or add
+  /// a reference to the value at `imageAddress`. If this type does not support
+  /// making copies, return `imageAddress` verbatim.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  static func _copyAttachableValue(at imageAddress: UnsafeMutablePointer<Self>) throws -> UnsafeMutablePointer<Self>
+
+  /// Manually deinitialize any resources at the given address.
+  ///
+  /// - Parameters:
+  ///   - imageAddress: The address of the instance of this type.
+  ///
+  /// The implementation of this function is responsible for balancing a
+  /// previous call to `_copyAttachableValue(at:)` by cleaning up any resources
+  /// (such as handles or COM objects) associated with the value at
+  /// `imageAddress`. The testing library automatically invokes this function as
+  /// needed. If `_copyAttachableValue(at:)` threw an error, the testing library
+  /// does not call this function.
+  ///
+  /// This function is not responsible for releasing the image returned from
+  /// `_copyAttachableIWICBitmap(from:using:)`.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  static func _deinitializeAttachableValue(at imageAddress: UnsafeMutablePointer<Self>)
+}
+
+/// A protocol describing images that can be converted to instances of
+/// ``Testing/Attachment``.
+///
+/// Instances of types conforming to this protocol do not themselves conform to
+/// ``Testing/Attachable``. Instead, the testing library provides additional
+/// initializers on ``Testing/Attachment`` that take instances of such types and
+/// handle converting them to image data when needed.
+///
+/// The following system-provided image types conform to this protocol and can
+/// be attached to a test:
+///
+/// - [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps)
+/// - [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons)
+/// - [`IWICBitmap`](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmap)
+///
+/// You do not generally need to add your own conformances to this protocol. If
+/// you have an image in another format that needs to be attached to a test,
+/// first convert it to an instance of one of the types above.
+@_spi(Experimental)
+public protocol AttachableAsIWICBitmap {
+  /// Create a WIC bitmap representing an instance of this type.
+  ///
+  /// - Parameters:
+  ///   - factory: A WIC imaging factory that can be used to create additional
+  ///     WIC objects.
+  ///
+  /// - Returns: A pointer to a new WIC bitmap representing this image. The
+  ///   caller is responsible for releasing this image when done with it.
+  ///
+  /// - Throws: Any error that prevented the creation of the WIC bitmap.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  borrowing func _copyAttachableIWICBitmap(
+    using factory: UnsafeMutablePointer<IWICImagingFactory>
+  ) throws -> UnsafeMutablePointer<IWICBitmap>
+
+  /// Make a copy of this instance.
+  ///
+  /// - Returns: A copy of `self`, or `self` if this type does not support a
+  ///   copying operation.
+  ///
+  /// - Throws: Any error that prevented copying this value.
+  ///
+  /// The testing library uses this function to take ownership of image
+  /// resources that test authors pass to it. If possible, make a copy of or add
+  /// a reference to `self`. If this type does not support making copies, return
+  /// `self` verbatim.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  func _copyAttachableValue() throws -> Self
+
+  /// Manually deinitialize any resources associated with this image.
+  ///
+  /// The implementation of this function cleans up any resources (such as
+  /// handles or COM objects) associated with this image. The testing library
+  /// automatically invokes this function as needed.
+  ///
+  /// This function is not responsible for releasing the image returned from
+  /// `_copyAttachableIWICBitmap(using:)`.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  func _deinitializeAttachableValue()
+}
+
+extension AttachableAsIWICBitmap {
+  /// Create a WIC bitmap representing an instance of this type and return it as
+  /// an instance of `IWICBitmapSource`.
+  ///
+  /// - Parameters:
+  ///   - factory: A WIC imaging factory that can be used to create additional
+  ///     WIC objects.
+  ///
+  /// - Returns: A pointer to a new WIC bitmap representing this image. The
+  ///   caller is responsible for releasing this image when done with it.
+  ///
+  /// - Throws: Any error that prevented the creation of the WIC bitmap.
+  ///
+  /// This function is a convenience over `_copyAttachableIWICBitmap(using:)`
+  /// that casts the result of that function to `IWICBitmapSource` (as needed
+  /// by WIC when it encodes the image.)
+  borrowing func copyAttachableIWICBitmapSource(
+    using factory: UnsafeMutablePointer<IWICImagingFactory>
+  ) throws -> UnsafeMutablePointer<IWICBitmapSource> {
+    let bitmap = try _copyAttachableIWICBitmap(using: factory)
+    defer {
+      _ = bitmap.pointee.lpVtbl.pointee.Release(bitmap)
+    }
+
+    return try withUnsafePointer(to: IID_IWICBitmapSource) { IID_IWICBitmapSource in
+      var bitmapSource: UnsafeMutableRawPointer?
+      let rQuery = bitmap.pointee.lpVtbl.pointee.QueryInterface(bitmap, IID_IWICBitmapSource, &bitmapSource)
+      guard rQuery == S_OK, let bitmapSource else {
+        throw ImageAttachmentError.queryInterfaceFailed(IWICBitmapSource.self, rQuery)
+      }
+      return bitmapSource.assumingMemoryBound(to: IWICBitmapSource.self)
+    }
+  }
+}
+#endif