UIGraphicsImageRenderer
A graphics renderer for creating Core Graphics-backed images.
Declaration
class UIGraphicsImageRendererMentioned in
Overview
You can use image renderers to accomplish drawing tasks, without having to handle configuration such as color depth and image scale, or manage Core Graphics contexts. You initialize an image renderer with parameters such as image output dimensions and format. You then use one or more of the drawing functions to render images that share these properties.
To render an image:
Optionally, create a UIGraphicsImageRendererFormat object to specify nondefault parameters the renderer should use to create its context.
Instantiate a UIGraphicsImageRenderer object, providing the dimensions of the output image and a format object. The renderer uses default values for the current device if you don’t provide format object, as demonstrated in Creating a graphics image renderer.
Choose one of the rendering methods depending on the output you desire: image(actions:) returns a UIImage object; jpegData(withCompressionQuality:actions:) returns a JPEG-encoded Data object; and pngData(actions:) returns a PNG-encoded Data object.
Execute your chosen method, providing Core Graphics drawing instructions as the closure argument, as shown in Creating an image with an image renderer. Using blend mode demonstrates some of the more advanced rendering features you can use in your drawing instructions.
Optionally, you can use Core Graphics drawing code within the drawing instructions you provide to the rendering method, as shown in Using Core Graphics rendering functions.
After initializing an image renderer, you can use it to draw multiple images with the same configuration. An image renderer keeps a cache of Core Graphics contexts, so reusing the same renderer can be more efficient than creating new renderers.
Creating a graphics image renderer
Create an image renderer, providing the size of the output image:
You can instead use one of the other UIGraphicsImageRenderer initializers to specify a renderer format (UIGraphicsImageRendererFormat) in addition to the size. This allows you to configure the underlying Core Graphics context for wide color and retina images.
If you don’t provide a format, the renderer uses the default() format, which creates a context best suited for the current device.
Creating an image with an image renderer
Use the image(actions:) method to create an image (UIImage object) with an image renderer. This method takes a closure that represents the drawing actions. Within this closure, the renderer creates a Core Graphics context using the parameters provided during renderer initialization, and sets this Core Graphics context to be the current context.
The drawing actions closure takes a single argument of type UIGraphicsImageRendererContext. This provides access to some high-level drawing functions, such as fill(_:), through the UIGraphicsRendererContext superclass.
The above code creates the following image:
[Image]
In addition to the image(actions:) method that creates an UIImage object, UIGraphicsImageRenderer also has jpegData(withCompressionQuality:actions:) and pngData(actions:) methods that create Data objects containing the image encoded as a JPEG or a PNG respectively. All three methods take the same approach as detailed here, accepting a block that represents the drawing actions.
Using blend mode
The utility methods on UIGraphicsImageRendererContext also offer a variant that accepts a CGBlendMode value. This value determines how to combine the pixel values when painting.
This code draws a second square, using a blend mode of multiply. The following image shows the result.
[Image]
Using Core Graphics rendering functions
The UIGraphicsImageRendererContext available in the image closure has a cgContext property, which allows you to use Core Graphics rendering functions directly. For example, the following code demonstrates how to add a circle to the image:
This code uses the fillEllipse(in:) method on CGContext to draw a green circle on the blue and turquoise squares image; the following image shows the result.
[Image]