An object that manages image data in your app.
- iOS 2.0+
- tvOS 2.0+
- watchOS 2.0+
You use image objects to represent image data of all kinds, and the
UIImage class is capable of managing data for all image formats supported by the underlying platform. Image objects are immutable, so you always create them from existing image data, such as an image file on disk or programmatically created image data. An image object may contain a single image or a sequence of images you intend to use in an animation.
You can use image objects in several different ways:
Assign an image to a
UIImageViewobject to display the image in your interface.
Use an image to customize system controls such as buttons, sliders, and segmented controls.
Draw an image directly into a view or other graphics context.
Pass an image to other APIs that might require image data.
Although image objects support all platform-native image formats, it is recommended that you use PNG or JPEG files for most images in your app. Image objects are optimized for reading and displaying both formats, and those formats offer better performance than most other image formats. Because the PNG format is lossless, it is especially recommended for the images you use in your app’s interface.
Creating Image Objects
When creating image objects using the methods of this class, you must have existing image data located in a file or data structure. You cannot create an empty image and draw content into it. There are many options for creating image objects, each of which is best for specific situations:
init(named:in:compatibleWith:)method (or the
init(named:)method) to create an image from an image asset or image file located in your app’s main bundle (or some other known bundle). Because these methods cache the image data automatically, they are especially recommended for images that you use frequently.
init(contentsOfFile:)method to create an image object where the initial data is not in a bundle. These methods load the image data from disk each time, so you should not use them to load the same image repeatedly.
animatedImageNamed(_:duration:)methods to create a single
UIImageobject comprised of multiple sequential images. Install the resulting image in a
UIImageViewobject to create animations in your interface.
Other methods of the
UIImage class let you create animations from specific types of data, such as Core Graphics images or image data that you create yourself. UIKit also provides the
UIGraphicsGetImageFromCurrentImageContext() function for creating images from content that you draw yourself. You use that function in conjunction with a bitmap-based graphics context, which you use to capture your drawing commands.
Image assets are the easiest way to manage the images that ship with your app. Each new Xcode project contains an assets library, to which you can add multiple image sets. An image set contains the variations of a single image that your app uses. A single image set can provide different versions of an image for different platforms, for different trait environments (compact or regular), and for different scale factors.
In addition to loading images from disk, you can ask the user to supply images from an available camera or photo library using a
UIImagePickerController object. An image picker displays a custom user interface for selecting images. Accessing user-supplied images requires explicit user permission. For more information about using an image picker, see
Defining a Stretchable Image
A stretchable image is one that defines regions where the underlying image data can be duplicated in an aesthetically pleasing way. Stretchable images are commonly used to create backgrounds that can grow or shrink to fill the available space.
You define a stretchable image by adding insets to an existing image using the
resizableImage(withCapInsets:resizingMode:) method. The insets subdivide the image into two or more parts. Specifying nonzero values for each inset yields an image divided into nine parts, as shown in
Each inset defines the potion of the image that does not stretch in the given dimension. The regions inside an image’s top and bottom insets maintain a fixed height, and the areas inside the left and right insets maintain a fixed width.
Figure 2 shows how each part of a nine-part image stretches as the image itself is stretched to fill the available space. The corners of the image do not change size because they are inside both a horizontal and vertical inset.
isEqual(_:) method is the only reliable way to determine whether two images contain the same image data. The image objects you create may be different from each other, even when you initialize them with the same cached image data. The only way to determine their equality is to use the
isEqual(_:) method, which compares the actual image data.
Listing 1 illustrates the correct and incorrect ways to compare images.
Accessing the Image Data
Image objects not provide direct access to their underlying image data. However, you can retrieve the image data in other formats for use in your app. Specifically, you can use the
ciImage properties to retrieve versions of the image that are compatible with Core Graphics and Core Image, respectively. You can also use the
UIImageJPEGRepresentation(_:_:) functions to generate an
NSData object containing the image data in either the PNG or JPEG format.