Instance Method

requestImage(for:targetSize:contentMode:options:resultHandler:)

Requests an image representation for the specified asset.

Declaration

iOS, Mac Catalyst, tvOS
func requestImage(for asset: PHAsset, targetSize: CGSize, contentMode: PHImageContentMode, options: PHImageRequestOptions?, resultHandler: @escaping (UIImage?, [AnyHashable : Any]?) -> Void) -> PHImageRequestID
macOS
func requestImage(for asset: PHAsset, targetSize: CGSize, contentMode: PHImageContentMode, options: PHImageRequestOptions?, resultHandler: @escaping (NSImage?, [AnyHashable : Any]?) -> Void) -> PHImageRequestID

Parameters

asset

The asset whose image data is to be loaded.

targetSize

The target size of image to be returned.

contentMode

An option for how to fit the image to the aspect ratio of the requested size. For details, see PHImageContentMode.

options

Options specifying how Photos should handle the request, format the requested image, and notify your app of progress or errors. For details, see PHImageRequestOptions.

resultHandler

A block to be called when image loading is complete, providing the requested image or information about the status of the request.

The block takes the following parameters:

result

The requested image.

info

A dictionary providing information about the status of the request. See Image Result Info Keys for possible keys and values.

Return Value

A numeric identifier for the request. If you need to cancel the request before it completes, pass this identifier to the cancelImageRequest(_:) method.

Discussion

When you call this method, Photos loads or generates an image of the asset at, or near, the size you specify. Next, it calls your resultHandler block to provide the requested image. To serve your request more quickly, Photos may provide an image that is slightly larger than the target size—either because such an image is already cached or because it can be generated more efficiently. Depending on the options you specify and the current state of the asset, Photos may download asset data from the network.

By default, this method executes asynchronously. If you call it from a background thread you may change the isSynchronous property of the options parameter to true to block the calling thread until either the requested image is ready or an error occurs, at which time Photos calls your result handler.

For an asynchronous request, Photos may call your result handler block more than once. Photos first calls the block to provide a low-quality image suitable for displaying temporarily while it prepares a high-quality image. (If low-quality image data is immediately available, the first call may occur before the method returns.) When the high-quality image is ready, Photos calls your result handler again to provide it. If the image manager has already cached the requested image at full quality, Photos calls your result handler only once. The PHImageResultIsDegradedKey key in the result handler’s info parameter indicates when Photos is providing a temporary low-quality image.

You can use this method for both photo and video assets—€”for a video asset, an image request provides a thumbnail image or poster frame.

See Also

Requesting Images

let PHImageManagerMaximumSize: CGSize

A special value for requesting original image data or the largest rendered image available. .

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software