Swift Testing での画像添付（Windows）

Windows 上でも、テスト中に得た画像をそのまま Attachment.record(...) に渡して添付できるようにします。エンコードには Windows 標準の Windows Imaging Component（WIC）を利用します。Apple プラットフォームの ST-0014 と同じ構造を採り、画像型を表すプロトコルと Attachment のオーバーロード、そして画像形式を表す AttachableImageFormat の Windows 向けの拡張という 3 点で構成されます。

AttachableAsIWICBitmapSource プロトコル

Windows 上で画像として添付できる型を表すプロトコルとして AttachableAsIWICBitmapSource が追加されます。Apple プラットフォームの AttachableAsCGImage に対応するプロトコルで、要求は WIC のビットマップソース（IWICBitmapSource）を生成することです。

public protocol AttachableAsIWICBitmapSource: SendableMetatype {
  /// Create a WIC bitmap source representing an instance of this type.
  ///
  /// - Returns: A pointer to a new WIC bitmap source representing this image.
  ///   The caller is responsible for releasing this image when done with it.
  func copyAttachableIWICBitmapSource() throws -> UnsafeMutablePointer<IWICBitmapSource>
}

このプロトコルには、Windows 標準の次の画像型があらかじめ適合しています。

• HBITMAP（GDI のビットマップハンドル）
• HICON（GDI のアイコンハンドル）
• IWICBitmapSource（および WIC が定義するそのサブクラス）

Swift では同じ型に対して、異なる制約で同じプロトコルへの適合を複数回与えることはできません。UnsafeMutablePointer を上記の Pointee ごとに条件付きで適合させるため、補助プロトコル _AttachableByAddressAsIWICBitmapSource を経由する形で適合が定義されています。

public protocol _AttachableByAddressAsIWICBitmapSource {}

extension HBITMAP.Pointee: _AttachableByAddressAsIWICBitmapSource {}
extension HICON.Pointee: _AttachableByAddressAsIWICBitmapSource {}
extension IWICBitmapSource: _AttachableByAddressAsIWICBitmapSource {}

extension UnsafeMutablePointer: AttachableAsIWICBitmapSource
  where Pointee: _AttachableByAddressAsIWICBitmapSource {}

_AttachableByAddressAsIWICBitmapSource は API としては public ですが実装の詳細であり、本 Proposal の範囲外として扱われます。Swift に COM 相互運用が入れば、この補助プロトコル自体が不要になる見込みです（「今後の見通し」を参照）。

テスト作者が自分で AttachableAsIWICBitmapSource への適合を追加する必要は通常ありません。別形式の画像を扱いたい場合は、上記の標準型のいずれかに変換してから渡します。なお、適合する型は将来追加される可能性があり、その判断は Testing Workgroup が行います。

画像を添付する

Attachment に、AttachableAsIWICBitmapSource に適合する値を直接渡せる初期化子と record(...) のオーバーロードが追加されます。

extension Attachment {
  public init<T>(
    _ image: T,
    named preferredName: String? = nil,
    as imageFormat: AttachableImageFormat? = nil,
    sourceLocation: SourceLocation = #_sourceLocation
  ) where T: AttachableAsIWICBitmapSource, AttachableValue == _AttachableImageWrapper<T>

  public static func record<T>(
    _ image: T,
    named preferredName: String? = nil,
    as imageFormat: AttachableImageFormat? = nil,
    sourceLocation: SourceLocation = #_sourceLocation
  ) where T: AttachableAsIWICBitmapSource, AttachableValue == _AttachableImageWrapper<T>
}

_AttachableImageWrapper は ST-0014 で導入された内部のラッパー型で、Windows でも同じ型が利用されます。Apple プラットフォームとの違いは、関連型 Image が AttachableAsCGImage ではなく AttachableAsIWICBitmapSource で制約されている点だけです。

imageFormat の挙動も ST-0014 と同様で、nil を渡したときはまず preferredName の拡張子から形式を推測し、それでも決まらなければライブラリが適切な形式を選びます。

Windows 向けの AttachableImageFormat

画像形式を抽象化する AttachableImageFormat 型自体は ST-0014 で導入済みですが、Windows は Uniform Type Identifiers を持たないため、UTType を受け取る Apple 用の API は Windows では使えません。代わりに、WIC のエンコーダ COM クラスを識別する CLSID を直接扱う API が用意されます。

extension AttachableImageFormat {
  /// The `CLSID` value of the Windows Imaging Component (WIC) encoder class
  /// that corresponds to this image format.
  public var encoderCLSID: CLSID { get }

  public init(encoderCLSID: CLSID, encodingQuality: Float = 1.0)
}

たとえば .png の encoderCLSID は CLSID_WICPngEncoder と等しくなります。encodingQuality は 0.0（最低品質）から 1.0（最高品質）までで、可変品質エンコーディングをサポートしないエンコーダでは無視されます。encoderCLSID が WIC のエンコーダクラスでない場合の挙動は未定義です。

加えて、拡張子から対応するエンコーダの CLSID を解決するための初期化子も追加されます。

extension AttachableImageFormat {
  public init?(pathExtension: String, encodingQuality: Float = 1.0)
}

pathExtension が認識できる画像形式に対応していない場合、この初期化子は nil を返します。Windows では「対応する IWICBitmapEncoder のサブクラスが WIC に登録されていること」が条件です。一貫性のため、この init(pathExtension:encodingQuality:) は Apple プラットフォームにも提供されます（Apple では pathExtension から得られるコンテンツタイプが UTType.image に適合していることが条件です）。これが本 Proposal で唯一、Windows 以外のプラットフォームに影響する変更です。

利用例

WIC を介して、HICON を PNG として添付する例を示します。

import Testing
import WinSDK

@MainActor @Test func `attaching an icon`() throws {
  let hIcon: HICON = ...
  defer {
    DestroyIcon(hIcon)
  }
  Attachment.record(hIcon, named: "my icon", as: .png)
  // OR: Attachment.record(hIcon, named: "my icon.png")
}

as: .png を明示する代わりに、preferredName の拡張子（my icon.png）から PNG を選ばせることもできます。