| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UIImage.h |
| Related sample code |
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. In some cases, however, the UIImage class provides convenience methods for obtaining a copy of the image that uses custom values for a property.
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.
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.
Table 1 lists the file formats that can be read by the UIImage class.
Format | Filename extensions |
|---|---|
| |
| |
| |
| |
| |
| |
| |
|
+ imageWithContentsOfFile:
+ imageWithData:
+ imageWithCGImage:
– stretchableImageWithLeftCapWidth:topCapHeight:
imageOrientation property
size property
CGImage property
leftCapWidth property
topCapHeight property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The underlying Quartz image data. (read-only)
@property(nonatomic, readonly) CGImageRef CGImage
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.
UIImage.hThe orientation of the receiver’s image. (read-only)
@property(nonatomic, readonly) UIImageOrientation imageOrientation
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.”
UIImage.hThe horizontal end-cap size. (read-only)
@property(nonatomic, readonly) NSInteger leftCapWidth
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:
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.
UIImage.hThe dimensions of the image, taking orientation into account (read-only)
@property(nonatomic, readonly) CGSize size
UIImage.hThe vertical end-cap size. (read-only)
@property(nonatomic, readonly) NSInteger topCapHeight
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:
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.
UIImage.hReturns the image object associated with the specified filename.
+ (UIImage *)imageNamed:(NSString *)name
The name of the file, including its filename extension. 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.
The image object for the specified file, or nil if the method could not find the specified image.
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 loads the image data from the specified file, caches it, and then returns the resulting object.
UIImage.hCreates and returns an image object representing the specified Quartz image.
+ (UIImage *)imageWithCGImage:(CGImageRef)cgImage
The Quartz image object.
A new image object for the specified Quartz image, or nil if the method could not initialize the image from the specified image reference.
This method does not cache the image object. You can use the methods of the Core Graphics framework to create a Quartz image reference.
UIImage.hCreates and returns an image object by loading the image data from the file at the specified path.
+ (UIImage *)imageWithContentsOfFile:(NSString *)path
The full or partial path to the file.
A new image object for the specified file, or nil if the method could not initialize the image from the specified file.
This method does not cache the image object.
UIImage.hCreates and returns an image object that uses the specified image data.
+ (UIImage *)imageWithData:(NSData *)data
The image data. This can be data from a file or data you create programmatically.
A new image object for the specified data, or nil if the method could not initialize the image from the specified data.
This method does not cache the image object.
UIImage.hDraws a tiled Quartz pattern using the receiver’s contents as the tile pattern.
- (void)drawAsPatternInRect:(CGRect)rect
The rectangle (in the coordinate system of the graphics context) in which to draw the image.
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.
UIImage.hDraws the image at the specified point in the current context.
- (void)drawAtPoint:(CGPoint)point
The point at which to draw the top-left corner of the image.
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.
UIImage.hDraws the entire image at the specified point using the custom compositing options.
- (void)drawAtPoint:(CGPoint)point blendMode:(CGBlendMode)blendMode alpha:(CGFloat)alpha
The point at which to draw the top-left corner of the image.
The blend mode to use when compositing the image.
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.
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.
UIImage.hDraws the entire image in the specified rectangle, scaling it as needed to fit.
- (void)drawInRect:(CGRect)rect
The rectangle (in the coordinate system of the graphics context) in which to draw the image.
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.
UIImage.hDraws the entire image in the specified rectangle and using the specified compositing options.
- (void)drawInRect:(CGRect)rect blendMode:(CGBlendMode)blendMode alpha:(CGFloat)alpha
The rectangle (in the coordinate system of the graphics context) in which to draw the image.
The blend mode to use when compositing the image.
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.
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.
UIImage.hInitializes and returns the image object with the specified Quartz image reference.
- (id)initWithCGImage:(CGImageRef)CGImage
A Quartz image reference.
An initialized UIImage object, or nil if the method could not initialize the image from the specified data.
UIImage.hInitializes and returns the image object with the contents of the specified file.
- (id)initWithContentsOfFile:(NSString *)path
The path to the file. This path should include the filename extension that identifies the type of the image data.
An initialized UIImage object, or nil if the method could find the file or initialize the image from its contents.
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.
UIImage.hInitializes and returns the image object with the specified data.
- (id)initWithData:(NSData *)data
The data object containing the image data.
An initialized UIImage object, or nil if the method could not initialize the image from the specified data.
The data in the data parameter must be formatted to match the file format of one of the system’s supported image types.
UIImage.hCreates and returns a new image object with the specified cap values.
- (UIImage *)stretchableImageWithLeftCapWidth:(NSInteger)leftCapWidth topCapHeight:(NSInteger)topCapHeight
The value to use for the left cap width. Specify 0 if you do not want the image to be horizontally stretchable. For a discussion of how this value affects the image, see the leftCapWidth property.
The value to use for the top cap width. Specify 0 if you do not want the image to be vertically stretchable. For a discussion of how this value affects the image, see the topCapHeight property.
A new image object with the specified cap values.
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.
UIImage.hSpecifies the possible orientations of an image.
typedef enum {
UIImageOrientationUp,
UIImageOrientationDown, // 180 deg rotation
UIImageOrientationLeft, // 90 deg CCW
UIImageOrientationRight, // 90 deg CW
UIImageOrientationUpMirrored, // as above but image mirrored along
// other axis. horizontal flip
UIImageOrientationDownMirrored, // horizontal flip
UIImageOrientationLeftMirrored, // vertical flip
UIImageOrientationRightMirrored, // vertical flip
} UIImageOrientation;
UIImageOrientationUpThe default orientation of images. The image is drawn right-side up, as shown here. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationDownThe image is rotated 180 degrees, as shown here. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationLeftThe image is rotated 90 degrees counterclockwise, as shown here. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationRightThe image is rotated 90 degrees clockwise, as shown here. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationUpMirroredThe 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. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationDownMirroredThe 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. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationLeftMirroredThe 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. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImageOrientationRightMirroredThe 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. 
Available in iPhone OS 2.0 and later.
Declared in UIImage.h.
UIImage.hLast updated: 2009-07-14
iPhone OS Reference Library Graphics & Animation: 2D Drawing UIImage Class Reference