iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIImage Class Reference

Options
Deployment Target:

On This Page
Language:

UIImage

A UIImage object is a high-level way to display image data. You can create images from files, from Quartz image objects, or from raw image data you receive. The UIImage class also offers several options for drawing images to the current graphics context using different blend modes and opacity values.

Image objects are immutable, so you cannot change their properties after creation. This means that you generally specify an image’s properties at initialization time or rely on the image’s metadata to provide the property value. It also means that image objects are themselves safe to use from any thread. The way you change the properties of an existing image object is to use one of the available convenience methods to create a copy of the image but with the custom value you want.

Because image objects are immutable, they also do not provide direct access to their underlying image data. However, you can get an NSData object containing either a PNG or JPEG representation of the image data using the UIImagePNGRepresentation and UIImageJPEGRepresentation functions.

The system uses image objects to represent still pictures taken with the camera on supported devices. To take a picture, use the UIImagePickerController class. To save a picture to the Saved Photos album, use the UIImageWriteToSavedPhotosAlbum function.

Images and Memory Management

In low-memory situations, image data may be purged from a UIImage object to free up memory on the system. This purging behavior affects only the image data stored internally by the UIImage object and not the object itself. When you attempt to draw an image whose data has been purged, the image object automatically reloads the data from its original file. This extra load step, however, may incur a small performance penalty.

You should avoid creating UIImage objects that are greater than 1024 x 1024 in size. Besides the large amount of memory such an image would consume, you may run into problems when using the image as a texture in OpenGL ES or when drawing the image to a view or layer. This size restriction does not apply if you are performing code-based manipulations, such as resizing an image larger than 1024 x 1024 pixels by drawing it to a bitmap-backed graphics context. In fact, you may need to resize an image in this manner (or break it into several smaller images) in order to draw it to one of your views.

Comparing Images in iOS 8

The bulk of what an image is lies in its CGImageRef and not in the UIImage object it is wrapped in. As of iOS 8, you can no longer rely on pointer equality to compare cached UIImage objects as the caching mechanism may not return the same UIImage object, but will have cached image data separately. You must use isEqual: to correctly test for equality.

Image Assets and Trait Collections

You can assign an image to a UIImageAsset object through the use of trait collections. Registering an image to an image asset provides a way to group images together. Through the use of trait collections, you can retrieve an image that best fits your current layout. For example, you can retrieve a different image depending on whether your view has a compact or regular size class.

Supported Image Formats

Table 1 lists the file formats that can be read by the UIImage class.

Table 1Supported file formats

Format

Filename extensions

Tagged Image File Format (TIFF)

.tiff, .tif

Joint Photographic Experts Group (JPEG)

.jpg, .jpeg

Graphic Interchange Format (GIF)

.gif

Portable Network Graphic (PNG)

.png

Windows Bitmap Format (DIB)

.bmp, .BMPf

Windows Icon Format

.ico

Windows Cursor

.cur

X Window System bitmap

.xbm

  • Returns an image in the bundle that is compatible with the trait collection.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    name

    The name of the image.

    bundle

    The bundle the image file or asset catalog is located in, pass nil to use the main bundle.

    traitCollection

    Traits that describe the desired image to retrieve, pass nil to use traits that describe the main screen.

    Return Value

    An image that exactly or 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 trait collection and returns that object if it exists. If a matching image object is not already in the cache, this method locates and loads the image data from disk or asset catalog, and then returns the resulting object. You can not assume that 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 * _Nullable)imageNamed:(NSString * _Nonnull)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.

    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 that object if it exists. If a matching image object is not already in the cache, this method locates and loads the image data from disk or asset catalog, and then returns the resulting object. You can not assume that this method is thread safe.

    On a device running iOS 4 or later, the behavior is identical if the device’s screen has a scale of 1.0. If the screen has a scale of 2.0, this method first searches for an image file with the same filename with an @2x suffix appended to it. For example, if the file’s name is button, it first searches for button@2x. If it finds a 2x, it loads that image and sets the scale property of the returned UIImage object to 2.0. Otherwise, it loads the unmodified filename and sets the scale property to 1.0. See App Programming Guide for iOS for more information on supporting images with different scale factors.

    Special Considerations

    On iOS 4 and later, if the file is in PNG format, it is not necessary to specify the .PNG filename extension. Prior to iOS 4, you must specify the filename extension.

    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 * _Nullable)imageWithContentsOfFile:(NSString * _Nonnull)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 * _Nullable)imageWithData:(NSData * _Nonnull)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 * _Nullable)imageWithData:(NSData * _Nonnull)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 * _Nonnull)imageWithCGImage:(CGImageRef _Nonnull)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 * _Nonnull)imageWithCGImage:(CGImageRef _Nonnull)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 * _Nonnull)imageWithCIImage:(CIImage * _Nonnull)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 * _Nonnull)imageWithCIImage:(CIImage * _Nonnull)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.

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

    Declaration

    Swift

    func imageWithAlignmentRectInsets(_ alignmentInsets: UIEdgeInsets) -> UIImage

    Objective-C

    - (UIImage * _Nonnull)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 an animated image.

    Declaration

    Swift

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

    Objective-C

    + (UIImage * _Nullable)animatedImageNamed:(NSString * _Nonnull)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 * _Nullable)animatedImageWithImages:(NSArray<UIImage *> * _Nonnull)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 * _Nullable)animatedResizableImageNamed:(NSString * _Nonnull)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 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 * _Nonnull)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 width. 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.

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

    Declaration

    Swift

    func resizableImageWithCapInsets(_ capInsets: UIEdgeInsets) -> UIImage

    Objective-C

    - (UIImage * _Nonnull)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 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 * _Nullable)animatedResizableImageNamed:(NSString * _Nonnull)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.

  • 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 * _Nonnull)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 rendering mode.

    Declaration

    Swift

    func imageWithRenderingMode(_ renderingMode: UIImageRenderingMode) -> UIImage

    Objective-C

    - (UIImage * _Nonnull)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 the current image, flipped horizontally.

    Declaration

    Swift

    func imageFlippedForRightToLeftLayoutDirection() -> UIImage

    Objective-C

    - (UIImage * _Nonnull)imageFlippedForRightToLeftLayoutDirection

    Return Value

    The flipped version of the image.

    Discussion

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

    Availability

    Available in iOS 9.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 _Nullable)initWithContentsOfFile:(NSString * _Nonnull)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 _Nullable)initWithData:(NSData * _Nonnull)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 _Nullable)initWithData:(NSData * _Nonnull)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 _Nonnull)initWithCGImage:(CGImageRef _Nonnull)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 _Nonnull)initWithCGImage:(CGImageRef _Nonnull)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 _Nonnull)initWithCIImage:(CIImage * _Nonnull)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 _Nonnull)initWithCIImage:(CIImage * _Nonnull)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.

  • 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 dimensions of the image, taking orientation into account. (read-only)

    Declaration

    Swift

    var size: CGSize { get }

    Objective-C

    @property(nonatomic, readonly) CGSize size

    Discussion

    In iOS 4.0 and later, this value reflects the logical size of the image and is measured in points. In iOS 3.x and earlier, this value always reflects the dimensions of the image measured in pixels.

    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 _Nullable 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 * _Nullable 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 *> * _Nullable 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 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.

  • 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 the image is associated with. (read-only)

    Declaration

    Swift

    var imageAsset: UIImageAsset? { get }

    Objective-C

    @property(nonatomic, readonly) UIImageAsset * _Nullable imageAsset

    Discussion

    If you create the image from a file reference, data, CGImageRef or if the image is animated, then imageAsset will be nil. CIImage based images will always return nil.

    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 * _Nonnull 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.

  • 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, information } 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.