A graphics renderer for creating Core Graphics-backed images.
- iOS 10.0+
- Mac Catalyst 13.0+
- tvOS 10.0+
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 of more of the drawing functions to render images that share these properties.
To render an image:
Optionally, create a
UIGraphicsobject to specify nondefault parameters the renderer should use to create its context.
Image Renderer Format
UIGraphicsobject, providing the dimensions of the output image and a format object. The renderer uses sensible defaults 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:
jpegreturns a JPEG-encoded
Data(with Compression Quality: actions:)
pngreturns a PNG-encoded
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.
Once an image renderer is initialized, 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
UIGraphics initializers to specify a renderer format (
UIGraphics) 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
default() format is used, which creates a context best suited for the current device.
Creating an Image with an Image Renderer
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 when the renderer was initialized, and sets this Core Graphics context to be the current context.
The drawing actions closure takes a single argument of type
UIGraphics. This provides access to some high-level drawing functions, such as
fill(_:), through the
The above code creates the image shown in Figure 1.
In addition to the
image(actions:) method that creates an
UIGraphics also has
png 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
Listing 3 draws a second square, using a blend mode of multiply. The result is shown in Figure 2.
Using Core Graphics Rendering Functions
UIGraphics available in the image closure has a
cg property, which allows you to use Core Graphics rendering functions directly. For example, Listing 4 demonstrates how to add a circle to the image: