Class

UIGraphicsImageRenderer

A graphics renderer for creating Core Graphics-backed images.

Declaration

class UIGraphicsImageRenderer : UIGraphicsRenderer

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 of more of the drawing functions to render images that share these properties.

To render an image:

  1. Optionally, create a UIGraphicsImageRendererFormat object to specify nondefault parameters the renderer should use to create its context.

  2. Instantiate a UIGraphicsImageRenderer object, 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.

  3. 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.

  4. 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.

  5. 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:

Listing 1

Creating an image renderer

let renderer = UIGraphicsImageRenderer(size: CGSize(width: 200, height: 200))

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 default() format is used, 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 when the renderer was initialized, and sets this Core Graphics context to be the current context.

Listing 2

Drawing using an image renderer

let image = renderer.image { (context) in
  UIColor.darkGray.setStroke()
  context.stroke(renderer.format.bounds)
  UIColor(colorLiteralRed: 158/255, green: 215/255, blue: 245/255, alpha: 1).setFill()
  context.fill(CGRect(x: 1, y: 1, width: 140, height: 140))
}

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 image shown in Figure 1.

Figure 1

Drawing a light blue square with an image renderer

Image showing a blue square in the top left of a larger white squares

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 the pixel values are combined when painting.

Listing 3

Specifying blend mode for drawing operations

let image = renderer.image { (context) in
  UIColor.darkGray.setStroke()
  context.stroke(renderer.format.bounds)
  UIColor(colorLiteralRed: 158/255, green: 215/255, blue: 245/255, alpha: 1).setFill()
  context.fill(CGRect(x: 1, y: 1, width: 140, height: 140))
  UIColor(colorLiteralRed: 145/255, green: 211/255, blue: 205/255, alpha: 1).setFill()
  context.fill(CGRect(x: 60, y: 60, width: 140, height: 140), blendMode: .multiply)
}

Listing 3 draws a second square, using a blend mode of multiply. The result is shown in Figure 2.

Figure 2

Overlapping squares

Image showing two overlapping squares, one blue, the other turquoise, in the top-left and bottom-right of a white background square respectively.

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, Listing 4 demonstrates how to add a circle to the image:

Listing 4

Rendering a circle

let image = renderer.image { (context) in
  UIColor.darkGray.setStroke()
  context.stroke(renderer.format.bounds)
  UIColor(colorLiteralRed: 158/255, green: 215/255, blue: 245/255, alpha: 1).setFill()
  context.fill(CGRect(x: 1, y: 1, width: 140, height: 140))
  UIColor(colorLiteralRed: 145/255, green: 211/255, blue: 205/255, alpha: 1).setFill()
  context.fill(CGRect(x: 60, y: 60, width: 140, height: 140), blendMode: .multiply)
  
  UIColor(colorLiteralRed: 203/255, green: 222/255, blue: 116/255, alpha: 0.6).setFill()
  context.cgContext.fillEllipse(in: CGRect(x: 60, y: 60, width: 140, height: 140))
}

Listing 4 uses the fillEllipse(in:) method on CGContext to draw a green circle on the blue and turquoise squares image; Figure 3 shows the result.

Figure 3

Rendering using the Core Graphics context

An image showing two overlapping squares and an overlaid green circle.

Topics

Initializing an Image Renderer

init(bounds: CGRect, format: UIGraphicsImageRendererFormat)

Creates a new image renderer with a given bounds and format.

init(size: CGSize)

Creates an image renderer for drawing images of a given size.

init(size: CGSize, format: UIGraphicsImageRendererFormat)

Creates a new image renderer with a given size and format.

Creating Images

func image(actions: (UIGraphicsImageRendererContext) -> Void) -> UIImage

Creates an image by following a set of drawing instructions.

func jpegData(withCompressionQuality: CGFloat, actions: (UIGraphicsImageRendererContext) -> Void) -> Data

Creates a JPEG-encoded image by following a set of drawing instructions.

func pngData(actions: (UIGraphicsImageRendererContext) -> Void) -> Data

Creates a PNG-encoded image by following a set of drawing instructions.

Relationships

Inherits From

Conforms To

See Also

Drawing Contexts

class UIGraphicsRenderer

An abstract base class for creating graphics renderers.

class UIGraphicsRendererContext

The base class for the drawing environments associated with graphics renderers.

class UIGraphicsRendererFormat

A set of drawing attributes that represent the configuration of a graphics renderer context.

class UIGraphicsImageRendererContext

The drawing environment associated with an image renderer.

class UIGraphicsImageRendererFormat

A set of drawing attributes that represent the configuration of an image renderer context.

class UIGraphicsPDFRenderer

A graphics renderer for creating PDFs.

typealias UIGraphicsPDFRenderer.DrawingActions

A handler block that you use to draw PDF content.

class UIGraphicsPDFRendererContext

A drawing environment associated with a PDF renderer.

class UIGraphicsPDFRendererFormat

A set of drawing attributes that represents the configuration of a PDF renderer context.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software