macOS 开发 - CGImageSource

---

官方文档描述

CGImageSource

CGImageSource objects abstract the data-reading task. An image source can read image data from a URL, a CFData object, or a data consumer.
After creating a CGImageSource object for the appropriate source, you can obtain images, thumbnails, image properties, and other image information using CGImageSource functions.

描述数据读取task。图片资源可以读取自 URL、CFData对象，或者 data 使用者。

从恰当资源创建 CGImageSource 对象后，你可以通过 CGImageSource 的方法获得图片、thumbnails 、 图片属性 和 其他图片信息。

---

数据类型：CGImageSourceRef

An opaque type that represents an image source.

不透明的方式展示图片资源。

---

枚举常量 - CGImageSourceStatus

typedef CF_ENUM(int32_t, CGImageSourceStatus) {
    kCGImageStatusUnexpectedEOF = -5,
    kCGImageStatusInvalidData = -4,
    kCGImageStatusUnknownType = -3,
    kCGImageStatusReadingHeader = -2,
    kCGImageStatusIncomplete = -1,
    kCGImageStatusComplete = 0
};

---

options keys

/*
 用于 CGImageSourceRef 的 key。
 指定最佳评估图片资源类型的格式类型id。
 这个值必须为CFStringRef 类型。
 可以通过查看 UTType.h 文件来了解具体类型id.
 */
CFStringRef kCGImageSourceTypeIdentifierHint;

/*
 用于 CGImageSourceCopyPropertiesAtIndex、CGImageSourceCreateImageAtIndex 方法中 options 的 key。描述图片在decoded 模式下，是否需要被缓存。这个key对应的值必须是CFBooleanRef 值。
kCFBooleanFalse 标识没有缓存，kCFBooleanTrue 标识于缓存。64位架构中，默认值为True；32位中默认为 false。
*/

CFStringRef kCGImageSourceShouldCache;


/*
 指定是否在图片创建的时候，就解码和缓存。
 这个key对于的值必须是 CFBooleanRef 类型，默认值为 kCFBooleanFalse。图片解码会发生在 渲染的时候。
 */
CFStringRef kCGImageSourceShouldCacheImmediately  IMAGEIO_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);

/*
 指定如果被文件类型支持的话，图片是否要作为一个 floating  point CGImageRef 返回。
 选择范围支出 CGImageRef 可能需要额外的浮点数返回处理来高兴地？渲染。
 值必须是CFBooleanRef，默认为kCFBooleanFalse。
 */
CFStringRef kCGImageSourceShouldAllowFloat;




/*
 指定如果 thumbnail 没有呈现在图片资源文件中时，thumbnail 是否会从完整的图片中创建。
 其余同上。
 */
CFStringRef kCGImageSourceCreateThumbnailFromImageAlways;

/*
 指定 thumbnail 像素中的最大宽高。
 如果这个值没有被指定，thumbnail 的宽高不会被限制，thumbnail 会是尽可能的大。
 如果展示，这个值是 CFNumberRef 类型。
 */
CFStringRef kCGImageSourceThumbnailMaxPixelSize;


/*
 指定 thumbnail 是否会根据完整图片的方向和像素比例，被旋转或缩放。
 这个值是一个CFBooleanRef，默认为 kCFBooleanFalse。
 */
CFStringRef kCGImageSourceCreateThumbnailWithTransform;



/*
 指定，图片在某些情况下，是否可以缩小后返回。
 结果图片会变小，质量会被减少，但和全尺寸图片的其他特征一致。
 如果不支持，全尺寸或者更大的图片会被返回。
 支持如下类型：JPEG, HEIF, TIFF, and PNG。
 这个返回值必须是CFNumberRef 类型，允许值为：2、4、8。
 */
CFStringRef kCGImageSourceSubsampleFactor  IMAGEIO_AVAILABLE_STARTING(__MAC_10_11,__IPHONE_9_0);

---

方法

1、创建图片资源

//返回读取data数据返回的image。 options 字典可以用于请求额外的创建选项。查看 keys 列表可以了解更多信息。
CGImageSourceRef __nullable CGImageSourceCreateWithDataProvider(CGDataProviderRef __nonnull provider, CFDictionaryRef __nullable options);

//通过读取data，创建图片资源。
CGImageSourceRef __nullable CGImageSourceCreateWithData(CFDataRef __nonnull data, CFDictionaryRef __nullable options);

//通过读取url创建图片资源。
CGImageSourceRef __nullable CGImageSourceCreateWithURL(CFURLRef __nonnull url, CFDictionaryRef __nullable options) IMAGEIO_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_4_0);

2、从图片资源创建图片

CGImageRef __nullable CGImageSourceCreateImageAtIndex(CGImageSourceRef __nonnull isrc, size_t index, CFDictionaryRef __nullable options);

/*
 用于 CGImageSourceCreateThumbnailAtIndex 使用的 options。
 指定如果 thumbnail 没有呈现在图片资源文件中时， thumbnail 是否在创建图片的时候生成。
 thumbnail 会从完整的图片中创建，遵循 kCGImageSourceThumbnailMaxPixelSize 的限制。
 如果没有限制最大像素，thumbnail 回事整个图片的尺寸，这可能不是你想要的。
 这个值是一个CFBooleanRef，默认为 kCFBooleanFalse。

 */
CFStringRef kCGImageSourceCreateThumbnailFromImageIfAbsent;

//返回图片的 incremental image source。没有数据会被提供，会假定 data 会被 CGImageSourceUpdateDataProvider 和 CGImageSourceUpdateData 提供。
CGImageSourceRef __nonnull CGImageSourceCreateIncremental(CFDictionaryRef __nullable options);

---

3、更新图片资源

//给数据源添加内容。新的数据中必须包含之前所有的数据，并加上新数据。当最后一组数据提供时，final 入参必须为true；否则为false。
void CGImageSourceUpdateData(CGImageSourceRef __nonnull isrc, CFDataRef __nonnull data, bool final);


//给数据源添加内容。新的数据提供者必须提供所有的增量数据。当最后一组数据提供时，final 入参必须为true。
void CGImageSourceUpdateDataProvider(CGImageSourceRef __nonnull isrc, CGDataProviderRef __nonnull provider, bool final);

---

4、从图片资源获取信息

//返回 CGImageSources 的 CFTypeID
CFTypeID CGImageSourceGetTypeID (void);

//返回支持类型的数组
CFArrayRef __nonnull CGImageSourceCopyTypeIdentifiers(void);




//返回图片资源`isrc' 的类型id.。
//这个类型是资源的container，container 中不一定是图片的类型。比如icns 格式支持嵌入式的JPEG2000，但是资源类型是 "com.apple.icns"。
CFStringRef __nullable CGImageSourceGetType(CGImageSourceRef __nonnull isrc);

//返回图片资源`isrc' 的图片个数。
size_t CGImageSourceGetCount(CGImageSourceRef __nonnull isrc);


/* Return the overall status of the image source `isrc'.  The status is
 * particularly informative for incremental image sources, but may be used
 * by clients providing non-incremental data as well. */

CGImageSourceStatus CGImageSourceGetStatus(CGImageSourceRef __nonnull isrc);


//返回在index 的图片的状态。
CGImageSourceStatus CGImageSourceGetStatusAtIndex(CGImageSourceRef __nonnull isrc, size_t index);

---

5、其他方法

//返回图片资源 isrc 的属性。这些属性通常用于容器，而非独立的图片。
CFDictionaryRef __nullable CGImageSourceCopyProperties(CGImageSourceRef __nonnull isrc, CFDictionaryRef __nullable options);


//返回图片资源isrc 在 index 的属性。index 从0开始。 options 可以用来请求额外的选项。
CFDictionaryRef __nullable CGImageSourceCopyPropertiesAtIndex(CGImageSourceRef __nonnull isrc, size_t index, CFDictionaryRef __nullable options);


//返回图片的元数据
CGImageMetadataRef __nullable CGImageSourceCopyMetadataAtIndex (CGImageSourceRef __nonnull isrc, size_t index, CFDictionaryRef __nullable options);


//移除缓存的decoded图片数据。
void CGImageSourceRemoveCacheAtIndex(CGImageSourceRef __nonnull isrc, size_t index) IMAGEIO_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);


//返回图片的 thumbnail
CGImageRef __nullable CGImageSourceCreateThumbnailAtIndex(CGImageSourceRef __nonnull isrc, size_t index, CFDictionaryRef __nullable options);



/*
 图片深度数据，支持 JPEG, HEIF,DNG 类型图片。
 返回额字典中包含：
 - kCGImageAuxiliaryDataInfoData，深度数据，CFDataRef类型
 - kCGImageAuxiliaryDataInfoDataDescription，深度数据描述（CFDictionary 类型）
 - kCGImageAuxiliaryDataInfoMetadata，元数据（CGImageMetadataRef 类型）

 如果图片不包含 auxiliaryImageDataType 数据，CGImageSourceCopyAuxiliaryDataInfoAtIndex 返回nil.
 */
CFDictionaryRef __nullable CGImageSourceCopyAuxiliaryDataInfoAtIndex(CGImageSourceRef __nonnull isrc, size_t index, CFStringRef __nonnull auxiliaryImageDataType ) IMAGEIO_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);

---

参考

• CGImageSource 官方文档
  https://developer.apple.com/documentation/imageio/cgimagesource?language=objc

• CGImageSourceRef 官方文档
  https://developer.apple.com/documentation/imageio/cgimagesourceref

• 图片处理：Image I/O 学习笔记
  https://www.jianshu.com/p/4dcd6e4bdbf0

---