GraphicsContext

An immediate mode drawing destination, and its current state.

StructureiOS 15.0+macOS 12.0+tvOS 15.0+watchOS 8.0+GraphicsContext in SwiftUI

Declaration

React
type GraphicsContext = { addFilter(filter: Symbolic<GraphicsContextFilter>, options?: { options?: Symbolic<GraphicsContextFilterOptions>; }): void; clip(options: { to: Symbolic<Path>; style?: Symbolic<FillStyle>; options?: Symbolic<GraphicsContextClipOptions>; }): void; clipToLayer(options: { opacity?: Symbolic<number>; options?: Symbolic<GraphicsContextClipOptions>; content: Symbolic<(context: GraphicsContext) => void>; }): void; concatenate(matrix: Symbolic<CGAffineTransform>): void; draw(text: Symbolic<string>, options: { at: Symbolic<CGPoint>; anchor?: Symbolic<UnitPoint>; }): void; draw(image: Symbolic<Image>, options: { at: Symbolic<CGPoint>; anchor?: Symbolic<UnitPoint>; }): void; draw(text: Symbolic<GraphicsContextResolvedText>, options: { at: Symbolic<CGPoint>; anchor?: Symbolic<UnitPoint>; }): void; draw(image: Symbolic<GraphicsContextResolvedImage>, options: { at: Symbolic<CGPoint>; anchor?: Symbolic<UnitPoint>; }): void; draw(symbol: Symbolic<GraphicsContextResolvedSymbol>, options: { at: Symbolic<CGPoint>; anchor?: Symbolic<UnitPoint>; }): void; draw(text: Symbolic<string>, options: { in: Symbolic<CGRect>; }): void; draw(text: Symbolic<GraphicsContextResolvedText>, options: { in: Symbolic<CGRect>; }): void; draw(symbol: Symbolic<GraphicsContextResolvedSymbol>, options: { in: Symbolic<CGRect>; }): void; draw(image: Symbolic<Image>, options: { in: Symbolic<CGRect>; style?: Symbolic<FillStyle>; }): void; draw(image: Symbolic<GraphicsContextResolvedImage>, options: { in: Symbolic<CGRect>; style?: Symbolic<FillStyle>; }): void; drawLayer(options: { content: Symbolic<(context: GraphicsContext) => void>; }): void; fill(path: Symbolic<Path>, options: { with: Symbolic<GraphicsContextShading>; style?: Symbolic<FillStyle>; }): void; resolve(text: Symbolic<string>): GraphicsContextResolvedText; resolve(image: Symbolic<Image>): GraphicsContextResolvedImage; resolve(shading: Symbolic<GraphicsContextShading>): GraphicsContextShading; resolveSymbol(options: { id: Symbolic<unknown>; }): GraphicsContextResolvedSymbol; rotate(options: { by: Symbolic<Angle>; }): void; scaleBy(options: { x: Symbolic<number>; y: Symbolic<number>; }): void; stroke(path: Symbolic<Path>, options: { with: Symbolic<GraphicsContextShading>; lineWidth?: Symbolic<number>; }): void; stroke(path: Symbolic<Path>, options: { with: Symbolic<GraphicsContextShading>; style: Symbolic<StrokeStyle>; }): void; translateBy(options: { x: Symbolic<number>; y: Symbolic<number>; }): void; blendMode: GraphicsContextBlendMode | GraphicsContextBlendMode; readonly clipBoundingRect: SymbolicRect; opacity: number | Scalar; transform: CGAffineTransform | SymbolicTransform; copy(): GraphicsContext; };
Swift
@frozen struct GraphicsContext

Properties

  • The blend mode used by drawing operations in the context.

  • clipBoundingRect*SymbolicRect

    The bounding rectangle of the intersection of all current clip shapes in the current user space.

  • opacity*number | Scalar

    The opacity of drawing operations in the context.

  • transform*CGAffineTransform | SymbolicTransform

    The current transform matrix, defining user space coordinates.

Overview

Use a context to execute 2D drawing primitives. For example, you can draw filled shapes using the fill(_:with:style:) method inside a Canvas view:

Canvas { context, size in
    context.fill(
        Path(ellipseIn: CGRect(origin: .zero, size: size)),
        with: .color(.green))
}
.frame(width: 300, height: 200)

The example above draws an ellipse that just fits inside a canvas that's constrained to 300 points wide and 200 points tall:

In addition to outlining or filling paths, you can draw images, text, and SwiftUI views. You can also use the context to perform many common graphical operations, like adding masks, applying filters and transforms, and setting a blend mode. For example you can add a mask using the clip(to:style:options:) method:

let halfSize = size.applying(CGAffineTransform(scaleX: 0.5, y: 0.5))
context.clip(to: Path(CGRect(origin: .zero, size: halfSize)))
context.fill(
    Path(ellipseIn: CGRect(origin: .zero, size: size)),
    with: .color(.green))

The rectangular mask hides all but one quadrant of the ellipse:

The order of operations matters. Changes that you make to the state of the context, like adding a mask or a filter, apply to later drawing operations. If you reverse the fill and clip operations in the example above, so that the fill comes first, the mask doesn't affect the ellipse.

Each context references a particular layer in a tree of transparency layers, and also contains a full copy of the drawing state. You can modify the state of one context without affecting the state of any other, even if they refer to the same layer. For example you can draw the masked ellipse from the previous example into a copy of the main context, and then add a rectangle into the main context:

// Create a copy of the context to draw a clipped ellipse.
var maskedContext = context
let halfSize = size.applying(CGAffineTransform(scaleX: 0.5, y: 0.5))
maskedContext.clip(to: Path(CGRect(origin: .zero, size: halfSize)))
maskedContext.fill(
    Path(ellipseIn: CGRect(origin: .zero, size: size)),
    with: .color(.green))

// Go back to the original context to draw the rectangle.
let origin = CGPoint(x: size.width / 4, y: size.height / 4)
context.fill(
    Path(CGRect(origin: origin, size: halfSize)),
    with: .color(.blue))

The mask doesn't clip the rectangle because the mask isn't part of the main context. However, both contexts draw into the same view because you created one context as a copy of the other:

The context has access to an EnvironmentValues instance called environment that's initially copied from the environment of its enclosing view. SwiftUI uses environment values --- like the display resolution and color scheme --- to resolve types like Image and Color that appear in the context. You can also access values stored in the environment for your own purposes.

From Apple’s SwiftUI documentation. Code samples there are Swift.

Used by

See also

More in Drawing and shapes.