GraphicsContext
An immediate mode drawing destination, and its current state.
Declaration
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; };@frozen struct GraphicsContextProperties
blendMode*GraphicsContextBlendMode | GraphicsContextBlendModeThe blend mode used by drawing operations in the context.
clipBoundingRect*SymbolicRectThe bounding rectangle of the intersection of all current clip shapes in the current user space.
opacity*number | ScalarThe opacity of drawing operations in the context.
transform*CGAffineTransform | SymbolicTransformThe 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.
- AngleA geometric angle whose value you access in either radians or degrees.
- AngularGradientAn angular gradient.
- AnyGradientA color gradient.
- BlendModeModes for compositing a view with overlapping content.
- ButtonBorderShapeA shape used to draw a button's border.
- ColorMatrixA matrix to use in an RGBA color transformation.
- ConcentricRectangleAnimatableDataThe type defining the data to animate.
- ContainerRelativeShapeA shape that is replaced by an inset version of the current container shape. If no container shape was defined, is replaced by a rectangle.
- ContentShapeKindsA kind for the content shape of a view.
- CoordinateSpaceProtocolA frame of reference within the layout system.
- DefaultGlassEffectShapeThe default shape applied by glass effects, a capsule.
- EllipticalGradientA radial gradient that draws an ellipse.