iOS Developer Library

Developer

UIKit Framework Reference UIImage Class Reference

Options
Deployment Target:

On This Page
Language:

UIImage

A UIImage object manages image data in your app. 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 UIImageView object 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:

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 UIImagePickerController Class Reference.

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 resizableImageWithCapInsets: or resizableImageWithCapInsets: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 Figure 1.

Figure 1Using insets to define stretchable regions image: ../Art/image_insets_2x.png

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.

Figure 2Stretchable portions of a nine-part image image: ../Art/image_stretching_2x.png

Comparing Images

The 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.

Listing 1Comparing two images

Objective-C

  1. // Load the same image twice.
  2. UIImage* image1 = [UIImage imageNamed:@"MyImage"];
  3. UIImage* image2 = [UIImage imageNamed:@"MyImage"];
  4. // The image objects may be different, but the contents are still equal
  5. if ([image1 isEqual:image2]) {
  6. // Correct. This technique compares the image data correctly.
  7. }
  8. if (image1 == image2) {
  9. // Incorrect! Direct object comparisons may not work.
  10. }

Swift

  1. let image1 = UIImage.init(named: "MyImage")
  2. let image2 = UIImage.init(named: "MyImage")
  3. if image1 != nil && image1!.isEqual(image2) {
  4. // Correct. This technique compares the image data correctly.
  5. }
  6. if image1 == image2 {
  7. // Incorrect! Direct object comparisons may not work.
  8. }

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 CGImage and CIImage properties to retrieve versions of the image that are compatible with Core Graphics and Core Image, respectively. You can also use the UIImagePNGRepresentation and UIImageJPEGRepresentation functions to generate an NSData object containing the image data in either the PNG or JPEG format.

  • Returns the named image that is also compatible with the specified trait collection.

    Declaration

    Swift

    init?(named name: String, inBundle bundle: NSBundle?, compatibleWithTraitCollection traitCollection: UITraitCollection?)

    Objective-C

    + (UIImage *)imageNamed:(NSString *)name inBundle:(NSBundle *)bundle compatibleWithTraitCollection:(UITraitCollection *)traitCollection

    Parameters

    name

    The name of the image. For images in asset catalogs, specify the name of the image asset. For PNG image files, specify the filename without the filename extension. For all other image file formats, include the filename extension in the name.

    bundle

    The bundle containing the image file or asset catalog. Specify nil to search the app’s main bundle.

    traitCollection

    The traits associated with the intended environment for the image. Use this parameter to ensure that the correct variant of the image is loaded. If you specify nil, this method uses the traits associated with the main screen.

    Return Value

    The image object that best matches the desired traits with the given name, or nil if no suitable image was found.

    Discussion

    This method looks in the system caches for an image object with the specified name and returns the variant of that image that best matches the specified trait collection. If a matching image object is not already in the cache, this method locates and loads the image data from disk or from an available asset catalog, and then returns the resulting object.

    The system may purge cached image data at any time to free up memory. Purging occurs only for images that are in the cache but are not currently being used.

    In iOS 9 and later, this method is thread safe.

    Availability

    Available in iOS 8.0 and later.

  • Returns the image object associated with the specified filename.

    Declaration

    Swift

    init?(named name: String)

    Objective-C

    + (UIImage *)imageNamed:(NSString *)name

    Parameters

    name

    The name of the file. If this is the first time the image is being loaded, the method looks for an image with the specified name in the application’s main bundle. For PNG images, you may omit the filename extension. For all other file formats, always include the filename extension.

    Return Value

    The image object for the specified file, or nil if the method could not find the specified image.

    Discussion

    This method looks in the system caches for an image object with the specified name and returns the variant of that image that is best suited for the main screen. If a matching image object is not already in the cache, this method locates and loads the image data from disk or from an available asset catalog, and then returns the resulting object.

    The system may purge cached image data at any time to free up memory. Purging occurs only for images that are in the cache but are not currently being used.

    In iOS 9 and later, this method is thread safe.

    Special Considerations

    If you have an image file that will only be displayed once and wish to ensure that it does not get added to the system’s cache, you should instead create your image using imageWithContentsOfFile:. This will keep your single-use image out of the system image cache, potentially improving the memory use characteristics of your app.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an image object by loading the image data from the file at the specified path.

    Declaration

    Objective-C

    + (UIImage *)imageWithContentsOfFile:(NSString *)path

    Parameters

    path

    The full or partial path to the file.

    Return Value

    A new image object for the specified file, or nil if the method could not initialize the image from the specified file.

    Discussion

    This method does not cache the image object.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an image object that uses the specified image data.

    Declaration

    Objective-C

    + (UIImage *)imageWithData:(NSData *)data

    Parameters

    data

    The image data. This can be data from a file or data you create programmatically.

    Return Value

    A new image object for the specified data, or nil if the method could not initialize the image from the specified data.

    Discussion

    This method does not cache the image object.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an image object that uses the specified image data and scale factor.

    Declaration

    Objective-C

    + (UIImage *)imageWithData:(NSData *)data scale:(CGFloat)scale

    Parameters

    data

    The image data. This can be data from a file or data you create programmatically.

    scale

    The scale factor to use when interpreting the image data. Specifying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    Return Value

    A new image object for the specified data, or nil if the method could not initialize the image from the specified data.

    Discussion

    This method does not cache the image object.

    Availability

    Available in iOS 6.0 and later.

  • Creates and returns an image object representing the specified Quartz image.

    Declaration

    Objective-C

    + (UIImage *)imageWithCGImage:(CGImageRef)cgImage

    Parameters

    cgImage

    The Quartz image object.

    Return Value

    A new image object for the specified Quartz image, or nil if the method could not initialize the image from the specified image reference.

    Discussion

    This method does not cache the image object. You can use the methods of the Core Graphics framework to create a Quartz image reference.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an image object with the specified scale and orientation factors.

    Declaration

    Objective-C

    + (UIImage *)imageWithCGImage:(CGImageRef)imageRef scale:(CGFloat)scale orientation:(UIImageOrientation)orientation

    Parameters

    imageRef

    The Quartz image object.

    scale

    The scale factor to use when interpreting the image data. Specifying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    orientation

    The orientation of the image data. You can use this parameter to specify any rotation factors applied to the image.

    Return Value

    A new image object for the specified Quartz image, or nil if the method could not initialize the image from the specified image reference.

    Discussion

    This method does not cache the image object. You can use the methods of the Core Graphics framework to create a Quartz image reference.

    Availability

    Available in iOS 4.0 and later.

  • Creates and returns an image object that contains a Core Image object.

    Declaration

    Objective-C

    + (UIImage *)imageWithCIImage:(CIImage *)ciImage

    Parameters

    ciImage

    The Core Image object to encapsulate.

    Return Value

    A new image object.

    Availability

    Available in iOS 5.0 and later.

  • Creates and returns an image object based on a Core Image object and the specified attributes.

    Declaration

    Objective-C

    + (UIImage *)imageWithCIImage:(CIImage *)ciImage scale:(CGFloat)scale orientation:(UIImageOrientation)orientation

    Parameters

    ciImage

    The Core Image object to encapsulate.

    scale

    The scale factor to use when interpreting the image data. Specifying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    orientation

    The orientation of the image data. You can use this parameter to specify any rotation factors applied to the image.

    Return Value

    A new image object.

    Availability

    Available in iOS 6.0 and later.

  • Initializes and returns the image object with the contents of the specified file.

    Declaration

    Swift

    init?(contentsOfFile path: String)

    Objective-C

    - (instancetype)initWithContentsOfFile:(NSString *)path

    Parameters

    path

    The path to the file. This path should include the filename extension that identifies the type of the image data.

    Return Value

    An initialized UIImage object, or nil if the method could not find the file or initialize the image from its contents.

    Discussion

    This method loads the image data into memory and marks it as purgeable. If the data is purged and needs to be reloaded, the image object loads that data again from the specified path.

    Availability

    Available in iOS 2.0 and later.

  • Initializes and returns the image object with the specified data.

    Declaration

    Swift

    init?(data data: NSData)

    Objective-C

    - (instancetype)initWithData:(NSData *)data

    Parameters

    data

    The data object containing the image data.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Discussion

    The data in the data parameter must be formatted to match the file format of one of the system’s supported image types.

    Availability

    Available in iOS 2.0 and later.

  • Initializes and returns the image object with the specified data and scale factor.

    Declaration

    Swift

    init?(data data: NSData, scale scale: CGFloat)

    Objective-C

    - (instancetype)initWithData:(NSData *)data scale:(CGFloat)scale

    Parameters

    data

    The data object containing the image data.

    scale

    The scale factor to assume when interpreting the image data. Applying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Discussion

    The data in the data parameter must be formatted to match the file format of one of the system’s supported image types.

    Availability

    Available in iOS 6.0 and later.

  • Initializes and returns the image object with the specified Quartz image reference.

    Declaration

    Swift

    init(CGImage cgImage: CGImage)

    Objective-C

    - (instancetype)initWithCGImage:(CGImageRef)CGImage

    Parameters

    CGImage

    A Quartz image reference.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Availability

    Available in iOS 2.0 and later.

  • Initializes and returns an image object with the specified scale and orientation factors

    Declaration

    Swift

    init(CGImage cgImage: CGImage, scale scale: CGFloat, orientation orientation: UIImageOrientation)

    Objective-C

    - (instancetype)initWithCGImage:(CGImageRef)imageRef scale:(CGFloat)scale orientation:(UIImageOrientation)orientation

    Parameters

    imageRef

    The Quartz image object.

    scale

    The scale factor to assume when interpreting the image data. Applying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    orientation

    The orientation of the image data. You can use this parameter to specify any rotation factors applied to the image.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Availability

    Available in iOS 4.0 and later.

  • Initializes and returns an image object with the specified Core Image object.

    Declaration

    Swift

    init(CIImage ciImage: CIImage)

    Objective-C

    - (instancetype)initWithCIImage:(CIImage *)ciImage

    Parameters

    ciImage

    The Core Image object.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Availability

    Available in iOS 5.0 and later.

  • Initializes and returns an image object with the specified Core Image object and properties.

    Declaration

    Swift

    init(CIImage ciImage: CIImage, scale scale: CGFloat, orientation orientation: UIImageOrientation)

    Objective-C

    - (instancetype)initWithCIImage:(CIImage *)ciImage scale:(CGFloat)scale orientation:(UIImageOrientation)orientation

    Parameters

    ciImage

    The Core Image object.

    scale

    The scale factor to assume when interpreting the image data. Applying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property.

    orientation

    The orientation of the image data. You can use this parameter to specify any rotation factors applied to the image.

    Return Value

    An initialized UIImage object, or nil if the method could not initialize the image from the specified data.

    Availability

    Available in iOS 6.0 and later.

  • Creates and returns an animated image.

    Declaration

    Swift

    class func animatedImageNamed(_ name: String, duration duration: NSTimeInterval) -> UIImage?

    Objective-C

    + (UIImage *)animatedImageNamed:(NSString *)name duration:(NSTimeInterval)duration

    Parameters

    name

    The full or partial path to the file (sans suffix).

    duration

    The duration of the animation.

    Return Value

    A new image object.

    Discussion

    This method loads a series of files by appending a series of numbers to the base file name provided in the name parameter. For example, if the name parameter had ‘image’ as its contents, this method would attempt to load images from files with the names ‘image0’, ‘image1’ and so on all the way up to ‘image1024’. All images included in the animated image should share the same size and scale.

    Availability

    Available in iOS 5.0 and later.

  • Creates and returns an animated image from an existing set of images.

    Declaration

    Swift

    class func animatedImageWithImages(_ images: [UIImage], duration duration: NSTimeInterval) -> UIImage?

    Objective-C

    + (UIImage *)animatedImageWithImages:(NSArray<UIImage *> *)images duration:(NSTimeInterval)duration

    Parameters

    images

    An array of UIImage objects.

    duration

    The duration of the animation.

    Return Value

    A new image object.

    Discussion

    All images included in the animated image should share the same size and scale.

    Availability

    Available in iOS 5.0 and later.

  • Creates and returns an animated image with end caps.

    Declaration

    Swift

    class func animatedResizableImageNamed(_ name: String, capInsets capInsets: UIEdgeInsets, duration duration: NSTimeInterval) -> UIImage?

    Objective-C

    + (UIImage *)animatedResizableImageNamed:(NSString *)name capInsets:(UIEdgeInsets)capInsets duration:(NSTimeInterval)duration

    Parameters

    name

    The full or partial path to the file (sans suffix).

    capInsets

    The values to use for the cap insets.

    duration

    The duration of the animation.

    Return Value

    A new image object.

    Discussion

    This method loads a series of files by appending a series of numbers to the base file name provided in the name parameter. For example, if the name parameter had ‘image’ as its contents, this method would attempt to load images from files with the names ‘image0’, ‘image1’ and so on all the way up to ‘image1024’. All images included in the animated image should share the same size and scale.

    Each frame in the animation follows the rules for resizable images created by the resizableImageWithCapInsets: method.

    Availability

    Available in iOS 5.0 and later.

  • Creates and returns an animated image with end caps and a specific resizing mode.

    Declaration

    Swift

    class func animatedResizableImageNamed(_ name: String, capInsets capInsets: UIEdgeInsets, resizingMode resizingMode: UIImageResizingMode, duration duration: NSTimeInterval) -> UIImage?

    Objective-C

    + (UIImage *)animatedResizableImageNamed:(NSString *)name capInsets:(UIEdgeInsets)capInsets resizingMode:(UIImageResizingMode)resizingMode duration:(NSTimeInterval)duration

    Parameters

    name

    The full or partial path to the file (sans suffix).

    capInsets

    The values to use for the cap insets.

    resizingMode

    The mode with which the interior of the image is resized.

    duration

    The duration of the animation.

    Return Value

    A new animated image object with the specified cap insets and resizing mode.

    Discussion

    This method is exactly the same as its counterpart animatedResizableImageNamed:capInsets:duration: except that the resizing mode of the new image object can be explicitly declared. Since the resizing mode of an image is UIImageResizingModeTile by default, this method should only be used in place of its counterpart to create an animated image that needs to be resized with the UIImageResizingModeStretch resizing mode.

    Availability

    Available in iOS 6.0 and later.

  • Returns the current image, prepared to flip horizontally when it’s in a right-to-left layout.

    Declaration

    Swift

    func imageFlippedForRightToLeftLayoutDirection() -> UIImage

    Objective-C

    - (UIImage *)imageFlippedForRightToLeftLayoutDirection

    Return Value

    The current image, prepared to flip horizontally if it’s in a right-to-left layout.

    Discussion

    Use this method to specify an image that should flip in a right-to-left layout. Note that most images do not need to flip in a right-to-left layout.

    This method returns the current UIImage object with the flipsForRightToLeftLayoutDirection property set to YEStrue; it does not return a flipped image. When the returned image is displayed in a UIImageView object in a right-to-left layout direction (whether the layout direction is set by the system language, or because the image view’s semanticContentAttribute property is set to UISemanticContentAttributeForceRightToLeft), the image appears flipped. When the returned image is displayed in a left-to-right context, it appears unflipped.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns a new image object with the specified rendering mode.

    Declaration

    Swift

    func imageWithRenderingMode(_ renderingMode: UIImageRenderingMode) -> UIImage

    Objective-C

    - (UIImage *)imageWithRenderingMode:(UIImageRenderingMode)renderingMode

    Parameters

    renderingMode

    The rendering mode to use for the new image.

    Return Value

    A new image object with the specified rendering mode.

    Availability

    Available in iOS 7.0 and later.

    See Also

    renderingMode

  • Returns a new version of the image that uses the specified alignment insets.

    Declaration

    Swift

    func imageWithAlignmentRectInsets(_ alignmentInsets: UIEdgeInsets) -> UIImage

    Objective-C

    - (UIImage *)imageWithAlignmentRectInsets:(UIEdgeInsets)alignmentInsets

    Parameters

    alignmentInsets

    The alignment metadata to apply to the new image.

    Return Value

    A new image object.

    Availability

    Available in iOS 6.0 and later.

  • Creates and returns a new image object with the specified cap insets.

    Declaration

    Swift

    func resizableImageWithCapInsets(_ capInsets: UIEdgeInsets) -> UIImage

    Objective-C

    - (UIImage *)resizableImageWithCapInsets:(UIEdgeInsets)capInsets

    Parameters

    capInsets

    The values to use for the cap insets.

    Return Value

    A new image object with the specified cap insets.

    Discussion

    You use this method to add cap insets to an image or to change the existing cap insets of an image. In both cases, you get back a new image and the original image remains untouched. For example, you can use this method to create a background image for a button with borders and corners: when the button is resized, the corners of the image remain unchanged, but the borders and center of the image expand to cover the new size.

    iOS uses different rendering techniques, with different performance characteristics, depending on the size of each resizable area in the image:

    • If resizable areas have a width or height of 1 pixel—that is, a horizontally resizable area is 1 pixel wide, a vertically resizable area is 1 pixel tall, or the center region of the image is 1 x 1 pixel—iOS draws the image by stretching the 1-pixel region. This mode provides the fastest performance (for nonzero cap insets).

    • If resizable areas have a width or height greater than 1 pixel, iOS draws the image by tiling the region. This mode provides reduced performance, but can be useful for images with textured (rather than solid-color) content in their resizable areas.

    • If the entire image is resizable—that is, the capInsets parameter is UIEdgeInsetsZero—and its size is greater than 1 x 1 pixel, iOS draws the image by tiling the entire image. This mode is faster than the tiling mode for nonzero cap insets.

    To instead directly control the resizing mode, use the resizableImageWithCapInsets:resizingMode: method.

    Availability

    Available in iOS 5.0 and later.

  • Creates and returns a new image object with the specified cap insets and options.

    Declaration

    Swift

    func resizableImageWithCapInsets(_ capInsets: UIEdgeInsets, resizingMode resizingMode: UIImageResizingMode) -> UIImage

    Objective-C

    - (UIImage *)resizableImageWithCapInsets:(UIEdgeInsets)capInsets resizingMode:(UIImageResizingMode)resizingMode

    Parameters

    capInsets

    The values to use for the cap insets.

    resizingMode

    The mode with which the interior of the image is resized.

    Return Value

    A new image object with the specified cap insets and resizing mode.

    Discussion

    This method is exactly the same as its counterpart resizableImageWithCapInsets: except that the resizing mode of the new image object can be explicitly declared. You should only call this method in place of its counterpart if you specifically want your image to be resized with the UIImageResizingModeStretch resizing mode.

    Availability

    Available in iOS 6.0 and later.

  • Creates and returns a new image object with the specified cap values.

    Deprecation Statement

    Deprecated. Use the resizableImageWithCapInsets: instead, specifying cap insets such that the interior is a 1x1 area.

    Declaration

    Swift

    func stretchableImageWithLeftCapWidth(_ leftCapWidth: Int, topCapHeight topCapHeight: Int) -> UIImage

    Objective-C

    - (UIImage *)stretchableImageWithLeftCapWidth:(NSInteger)leftCapWidth topCapHeight:(NSInteger)topCapHeight

    Parameters

    leftCapWidth

    The value to use for the left cap width. Specify 0 if you want the entire image to be horizontally stretchable. For a discussion of how a non-zero value affects the image, see the leftCapWidth property.

    topCapHeight

    The value to use for the top cap height. Specify 0 if you want the entire image to be vertically stretchable. For a discussion of how a non-zero value affects the image, see the topCapHeight property.

    Return Value

    A new image object with the specified cap values.

    Discussion

    During scaling or resizing of the image, areas covered by a cap are not scaled or resized. Instead, the 1-pixel wide area not covered by the cap in each direction is what is scaled or resized. This technique is often used to create variable-width buttons, which retain the same rounded corners but whose center region grows or shrinks as needed.

    You use this method to add cap values to an image or to change the existing cap values of an image. In both cases, you get back a new image and the original image remains untouched.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 5.0.

  • The orientation of the receiver’s image. (read-only)

    Declaration

    Swift

    var imageOrientation: UIImageOrientation { get }

    Objective-C

    @property(nonatomic, readonly) UIImageOrientation imageOrientation

    Discussion

    Image orientation affects the way the image data is displayed when drawn. By default, images are displayed in the “up” orientation. If the image has associated metadata (such as EXIF information), however, this property contains the orientation indicated by that metadata. For a list of possible values for this property, see UIImageOrientation.

    Availability

    Available in iOS 2.0 and later.

  • size size Property

    The logical dimensions of the image, measured in points. (read-only)

    Declaration

    Swift

    var size: CGSize { get }

    Objective-C

    @property(nonatomic, readonly) CGSize size

    Discussion

    This value reflects the logical size of the image and takes the image’s current orientation into account. Multiply the size values by the value in the scale property to get the pixel dimensions of the image.

    Availability

    Available in iOS 2.0 and later.

  • The scale factor of the image. (read-only)

    Declaration

    Swift

    var scale: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat scale

    Discussion

    If you load an image from a file whose name includes the @2x modifier, the scale is set to 2.0. You can also specify an explicit scale factor when initializing an image from a Core Graphics image. All other images are assumed to have a scale factor of 1.0.

    If you multiply the logical size of the image (stored in the size property) by the value in this property, you get the dimensions of the image in pixels.

    Availability

    Available in iOS 4.0 and later.

  • A Boolean value that indicates whether the image should flip in a right-to-left layout. (read-only)

    Declaration

    Swift

    var flipsForRightToLeftLayoutDirection: Bool { get }

    Objective-C

    @property(nonatomic, readonly) BOOL flipsForRightToLeftLayoutDirection

    Availability

    Available in iOS 9.0 and later.

  • The resizing mode of the image. (read-only)

    Declaration

    Swift

    var resizingMode: UIImageResizingMode { get }

    Objective-C

    @property(nonatomic, readonly) UIImageResizingMode resizingMode

    Discussion

    The default value for this property is UIImageResizingModeTile. However, UIImage will implement the resizing mode the fastest way possible while still retaining the desired visual appearance. This means that if the region to be resized is a 1-pixel region and this property is set to UIImageResizingModeTile, the region will be stretched instead because the two are virtually indistinguishable for a region of that size and stretching is dramatically faster than tiling. To set the value of this property, you need to call either animatedResizableImageNamed:capInsets:resizingMode:duration: or resizableImageWithCapInsets:resizingMode: and specify the resizing mode using the resizingMode parameter. For a list of possible values for this property, see UIImageResizingMode.

    Availability

    Available in iOS 6.0 and later.

  • The underlying Quartz image data. (read-only)

    Declaration

    Swift

    var CGImage: CGImage? { get }

    Objective-C

    @property(nonatomic, readonly) CGImageRef CGImage

    Discussion

    If the image data has been purged because of memory constraints, invoking this method forces that data to be loaded back into memory. Reloading the image data may incur a performance penalty.

    If the UIImage object was initialized using a CIImage object, the value of the property is NULL.

    Availability

    Available in iOS 2.0 and later.

  • The underlying Core Image data. (read-only)

    Declaration

    Swift

    var CIImage: CIImage? { get }

    Objective-C

    @property(nonatomic, readonly) CIImage *CIImage

    Discussion

    If the UIImage object was initialized using a CGImageRef, the value of the property is nil.

    Availability

    Available in iOS 5.0 and later.

  • For an animated image, this property holds the complete array of UIImage objects that make up the animation. (read-only)

    Declaration

    Swift

    var images: [UIImage]? { get }

    Objective-C

    @property(nonatomic, readonly) NSArray <UIImage *> *images

    Discussion

    For a non-animated image, the value of this property is nil.

    Availability

    Available in iOS 5.0 and later.

  • Returns the time interval used to display an animated image. (read-only)

    Declaration

    Swift

    var duration: NSTimeInterval { get }

    Objective-C

    @property(nonatomic, readonly) NSTimeInterval duration

    Discussion

    For a non-animated image, the value of this property is 0.0.

    Availability

    Available in iOS 5.0 and later.

  • The end-cap insets. (read-only)

    Declaration

    Swift

    var capInsets: UIEdgeInsets { get }

    Objective-C

    @property(nonatomic, readonly) UIEdgeInsets capInsets

    Discussion

    End caps specify the portion of an image that should not be resized when an image is stretched. This technique is used to implement buttons and other resizable image-based interface elements. When a button with end caps is resized, the resizing occurs only in the middle of the button, in the region between the end caps. The end caps themselves keep their original size and appearance.

    This property specifies the sizes of all four end caps. The middle (stretchable) portion consists of all the pixels that are not included in the end caps. These pixels are tiled, left-to-right, top-to-bottom to fill the remaining space.

    On a non-resizable image, this property is set to UIEdgeInsetsZero; the image does not use end caps and the entire image is subject to stretching. To create a new image with a nonzero value for this property, use the resizableImageWithCapInsets: method. If your application specifies UIEdgeInsetsZero as the capInsets parameter, the entire image is tiled.

    Availability

    Available in iOS 5.0 and later.

  • The alignment metadata used to position the image during layout. (read-only)

    Declaration

    Swift

    var alignmentRectInsets: UIEdgeInsets { get }

    Objective-C

    @property(nonatomic, readonly) UIEdgeInsets alignmentRectInsets

    Discussion

    You can use the inset values as a hint for specifying the image contents more precisely. For example, if you have a 20 x 20 pixel icon that includes a glow effect, you might set the insets to {{2, 2}, {16, 16}} to indicate the position of the underlying icon without the glow effect.

    Objects that incorporate images can use these insets to place the image properly within their content.

    Availability

    Available in iOS 6.0 and later.

  • Returns a reference to the image asset (if any) associated with the image. (read-only)

    Declaration

    Swift

    var imageAsset: UIImageAsset? { get }

    Objective-C

    @property(nonatomic, readonly) UIImageAsset *imageAsset

    Discussion

    For images loaded from an image assets, this property contains an image asset object that you can use to fetch the other variants of the image. If you did not create the image object using an image asset, the value of this property is nil. This property is always nil for images created using a CIImage object.

    Availability

    Available in iOS 8.0 and later.

  • Returns the trait collection that describes the image. (read-only)

    Declaration

    Swift

    @NSCopying var traitCollection: UITraitCollection { get }

    Objective-C

    @property(nonatomic, readonly, copy) UITraitCollection *traitCollection

    Availability

    Available in iOS 8.0 and later.

  • Determines how an image is rendered. (read-only)

    Declaration

    Swift

    var renderingMode: UIImageRenderingMode { get }

    Objective-C

    @property(nonatomic, readonly) UIImageRenderingMode renderingMode

    Discussion

    The default rendering mode is UIImageRenderingModeAutomatic

    Availability

    Available in iOS 7.0 and later.

  • The horizontal end-cap size. (read-only)

    Deprecation Statement

    Use the capInsets property instead.

    Declaration

    Swift

    var leftCapWidth: Int { get }

    Objective-C

    @property(nonatomic, readonly) NSInteger leftCapWidth

    Discussion

    End caps specify the portion of an image that should not be resized when an image is stretched. This technique is used to implement buttons and other resizable image-based interface elements. When a button with end caps is resized, the resizing occurs only in the middle of the button, in the region between the end caps. The end caps themselves keep their original size and appearance.

    This property specifies the size of the left end cap. The middle (stretchable) portion is assumed to be 1 pixel wide. The right end cap is therefore computed by adding the size of the left end cap and the middle portion together and then subtracting that value from the width of the image:

    1. rightCapWidth = image.size.width - (image.leftCapWidth + 1);

    By default, this property is set to 0, which indicates that the image does not use end caps and the entire image is subject to stretching. To create a new image with a nonzero value for this property, use the stretchableImageWithLeftCapWidth:topCapHeight: method.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 5.0.

  • The vertical end-cap size. (read-only)

    Deprecation Statement

    Use the capInsets property instead.

    Declaration

    Swift

    var topCapHeight: Int { get }

    Objective-C

    @property(nonatomic, readonly) NSInteger topCapHeight

    Discussion

    End caps specify the portion of an image that should not be resized when an image is stretched. This technique is used to implement buttons and other resizable image-based interface elements. When a button with end caps is resized, the resizing occurs only in the middle of the button, in the region between the end caps. The end caps themselves keep their original size and appearance.

    This property specifies the size of the top end cap. The middle (stretchable) portion is assumed to be 1 pixel wide. The bottom end cap is therefore computed by adding the size of the top end cap and the middle portion together and then subtracting that value from the height of the image:

    1. bottomCapHeight = image.size.height - (image.topCapHeight + 1);

    By default, this property is set to 0, which indicates that the image does not use end caps and the entire image is subject to stretching. To create a new image with a nonzero value for this property, use the stretchableImageWithLeftCapWidth:topCapHeight: method.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 5.0.

  • Draws the image at the specified point in the current context.

    Declaration

    Swift

    func drawAtPoint(_ point: CGPoint)

    Objective-C

    - (void)drawAtPoint:(CGPoint)point

    Parameters

    point

    The point at which to draw the top-left corner of the image.

    Discussion

    This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the specified point. This method respects any transforms applied to the current graphics context, however.

    This method draws the image at full opacity using the kCGBlendModeNormal blend mode.

    Availability

    Available in iOS 2.0 and later.

  • Draws the entire image at the specified point using the custom compositing options.

    Declaration

    Swift

    func drawAtPoint(_ point: CGPoint, blendMode blendMode: CGBlendMode, alpha alpha: CGFloat)

    Objective-C

    - (void)drawAtPoint:(CGPoint)point blendMode:(CGBlendMode)blendMode alpha:(CGFloat)alpha

    Parameters

    point

    The point at which to draw the top-left corner of the image.

    blendMode

    The blend mode to use when compositing the image.

    alpha

    The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

    Discussion

    This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the specified point. This method respects any transforms applied to the current graphics context, however.

    Availability

    Available in iOS 2.0 and later.

  • Draws the entire image in the specified rectangle, scaling it as needed to fit.

    Declaration

    Swift

    func drawInRect(_ rect: CGRect)

    Objective-C

    - (void)drawInRect:(CGRect)rect

    Parameters

    rect

    The rectangle (in the coordinate system of the graphics context) in which to draw the image.

    Discussion

    This method draws the entire image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.

    This method draws the image at full opacity using the kCGBlendModeNormal blend mode.

    Availability

    Available in iOS 2.0 and later.

  • Draws the entire image in the specified rectangle and using the specified compositing options.

    Declaration

    Swift

    func drawInRect(_ rect: CGRect, blendMode blendMode: CGBlendMode, alpha alpha: CGFloat)

    Objective-C

    - (void)drawInRect:(CGRect)rect blendMode:(CGBlendMode)blendMode alpha:(CGFloat)alpha

    Parameters

    rect

    The rectangle (in the coordinate system of the graphics context) in which to draw the image.

    blendMode

    The blend mode to use when compositing the image.

    alpha

    The desired opacity of the image, specified as a value between 0.0 and 1.0. A value of 0.0 renders the image totally transparent while 1.0 renders it fully opaque. Values larger than 1.0 are interpreted as 1.0.

    Discussion

    This method scales the image as needed to make it fit in the specified rectangle. This method draws the image in the current graphics context, respecting the image’s orientation setting. In the default coordinate system, images are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.

    Availability

    Available in iOS 2.0 and later.

  • Draws a tiled Quartz pattern using the receiver’s contents as the tile pattern.

    Declaration

    Swift

    func drawAsPatternInRect(_ rect: CGRect)

    Objective-C

    - (void)drawAsPatternInRect:(CGRect)rect

    Parameters

    rect

    The rectangle (in the coordinate system of the graphics context) in which to draw the image.

    Discussion

    This method uses a Quartz pattern to tile the image in the specified rectangle. The image is tiled with no gaps and the fill color is ignored. In the default coordinate system, the image tiles are situated down and to the right of the origin of the specified rectangle. This method respects any transforms applied to the current graphics context, however.

    Availability

    Available in iOS 2.0 and later.

  • Specifies the possible orientations of an image.

    Declaration

    Swift

    enum UIImageOrientation : Int { case Up case Down case Left case Right case UpMirrored case DownMirrored case LeftMirrored case RightMirrored }

    Objective-C

    typedef enum { UIImageOrientationUp, UIImageOrientationDown , // 180 deg rotation UIImageOrientationLeft , // 90 deg CW UIImageOrientationRight , // 90 deg CCW UIImageOrientationUpMirrored , // as above but image mirrored along // other axis. horizontal flip UIImageOrientationDownMirrored , // horizontal flip UIImageOrientationLeftMirrored , // vertical flip UIImageOrientationRightMirrored , // vertical flip } UIImageOrientation;

    Constants

    • Up

      UIImageOrientationUp

      The default orientation of images. The image is drawn right-side up, as shown here. image: ../Art/UIImageOrientationUp.jpg

      Available in iOS 2.0 and later.

    • Down

      UIImageOrientationDown

      The image is rotated 180 degrees, as shown here. image: ../Art/UIImageOrientationDown.jpg

      Available in iOS 2.0 and later.

    • Left

      UIImageOrientationLeft

      The image is rotated 90 degrees clockwise, as shown here. image: ../Art/UIImageOrientationRight.jpg

      Available in iOS 2.0 and later.

    • Right

      UIImageOrientationRight

      The image is rotated 90 degrees counterclockwise, as shown here. image: ../Art/UIImageOrientationLeft.jpg

      Available in iOS 2.0 and later.

    • UpMirrored

      UIImageOrientationUpMirrored

      The image is drawn as a mirror version of an image drawn with the UIImageOrientationUp value. In other words, the image is flipped along its horizontal axis, as shown here. image: ../Art/UIImageOrientationUpMirrored.jpg

      Available in iOS 2.0 and later.

    • DownMirrored

      UIImageOrientationDownMirrored

      The image is drawn as a mirror version of an image drawn with the UIImageOrientationDown value. This is the equivalent to flipping an image in the “up” orientation along its horizontal axis and then rotating the image 180 degrees, as shown here. image: ../Art/UIImageOrientationDownMirrored.jpg

      Available in iOS 2.0 and later.

    • LeftMirrored

      UIImageOrientationLeftMirrored

      The image is drawn as a mirror version of an image drawn with the UIImageOrientationLeft value. This is the equivalent to flipping an image in the “up” orientation along its horizontal axis and then rotating the image 90 degrees counterclockwise, as shown here. image: ../Art/UIImageOrientationLeftMirrored.jpg

      Available in iOS 2.0 and later.

    • RightMirrored

      UIImageOrientationRightMirrored

      The image is drawn as a mirror version of an image drawn with the UIImageOrientationRight value. This is the equivalent to flipping an image in the “up” orientation along its horizontal axis and then rotating the image 90 degrees clockwise, as shown here. image: ../Art/UIImageOrientationRightMirrored.jpg

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Specifies the possible resizing modes for an image.

    Declaration

    Swift

    enum UIImageResizingMode : Int { case Tile case Stretch }

    Objective-C

    typedef enum { UIImageResizingModeTile, UIImageResizingModeStretch, } UIImageResizingMode;

    Constants

    • Tile

      UIImageResizingModeTile

      The image is tiled when it is resized. In other words, the interior region of the original image will be repeated to fill in the interior region of the newly resized image.

      Available in iOS 6.0 and later.

    • Stretch

      UIImageResizingModeStretch

      The image is stretched when it is resized. In other words, the interior region of the original image will be scaled to fill in the interior region of the newly resized imaged.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Specifies the possible rendering modes for an image.

    Declaration

    Swift

    enum UIImageRenderingMode : Int { case Automatic case AlwaysOriginal case AlwaysTemplate }

    Objective-C

    typedef enum : NSInteger { UIImageRenderingModeAutomatic, UIImageRenderingModeAlwaysOriginal, UIImageRenderingModeAlwaysTemplate, } UIImageRenderingMode;

    Constants

    • Automatic

      UIImageRenderingModeAutomatic

      Use the default rendering mode for the context where the image is used.

      Available in iOS 7.0 and later.

    • AlwaysOriginal

      UIImageRenderingModeAlwaysOriginal

      Always draw the original image, without treating it as a template.

      Available in iOS 7.0 and later.

    • AlwaysTemplate

      UIImageRenderingModeAlwaysTemplate

      Always draw the image as a template image, ignoring its color information.

      Available in iOS 7.0 and later.

    Discussion

    See Template Images in UIKit User Interface Catalog for a discussion of template images.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.