Returns a new version of the image that contains the specified cap insets.
- iOS 5.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
The values to use for the cap insets.
A new image object with the specified cap insets.
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
zero—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