An immediate mode drawing destination, and its current state.
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.
Adds a clip shape that you define in a new layer to the context's array
of clip shapes.
Call this method to add a shape to the array of clip shapes that
the context uses to define a clipping mask. Shapes that you add
affect only subsequent drawing operations.
- Parameters:
- opacity: A value that SwiftUI uses to multiply the alpha channel of
the rasterized layer that you define in the `content` closure. The
alpha values that result define the clip shape.
- options: A set of options that tell SwiftUI how to interpret the
clip shape. For example, you can invert the clip
shape by setting the ``ClipOptions/inverse`` option.
- content: A closure that receives as input a new ``GraphicsContext``,
which represents a new transparency layer. The alpha channel of
content that you draw into this context, multiplied by the `opacity`
parameter, defines the clip shape.
Appends the given transform to the context's existing transform.
Calling this method is equivalent to updating the context's
``transform`` directly using the `matrix` parameter:
transform = matrix.concatenating(transform)
- Parameter matrix: A transform to append to the existing transform.
get · iOS 15.0+
environment
TypeScript
get environment(): EnvironmentValues
Swift declaration
var environment: EnvironmentValues { get set }
The environment associated with the graphics context.
SwiftUI initially sets this to the environment of the context's
enclosing view. The context uses values like display
resolution and the color scheme from the environment to resolve types
like ``Image`` and ``Color``. You can also access values stored in the
environment for your own purposes.
method · iOS 15.0+
translateBy
TypeScript
translateBy(x: number, y: number): void
Swift declaration
mutating func translateBy(x: CGFloat, y: CGFloat)
Moves subsequent drawing operations by an amount in each dimension.
Calling this method is equivalent to updating the context's
``transform`` directly using the given translation amount:
transform = transform.translatedBy(x: x, y: y)
- Parameters:
- x: The amount to move in the horizontal direction.
- y: The amount to move in the vertical direction.
func resolveSymbol<ID>(id: ID) -> GraphicsContext.ResolvedSymbol? where ID : Hashable
Gets the identified child view as a resolved symbol, if the view exists.
- Parameter id: The value that you used to tag the view when you
define it in the `symbols` parameter of the ``Canvas`` initializer
``Canvas/init(opaque:colorMode:rendersAsynchronously:renderer:symbols:)``.
- Returns: The resolved symbol, or `nil` if SwiftUI can't find a child
view with the given `id`.
Provides a Core Graphics context that you can use as a proxy to draw
into this context.
Use this method to use existing drawing code that relies on
Core Graphics primitives.
- Parameter content: A closure that receives a
<doc://com.apple.documentation/documentation/CoreGraphics/CGContext>
that you use to perform drawing operations, just like you draw into a
``GraphicsContext`` instance. Any filters, blend mode settings, clip
masks, and other state set before calling `withCGContext(content:)`
apply to drawing operations in the Core Graphics context as well. Any
state you set on the Core Graphics context is lost when the closure
returns. Accessing the Core Graphics context after the closure
returns produces undefined behavior.
get · iOS 15.0+
clipBoundingRect
TypeScript
get clipBoundingRect(): { x: number; y: number; width: number; height: number }
Swift declaration
var clipBoundingRect: CGRect { get }
The bounding rectangle of the intersection of all current clip
shapes in the current user space.
Adds a path to the context's array of clip shapes.
Call this method to add a shape to the array of clip shapes that
the context uses to define a clipping mask. Shapes that you add
affect only subsequent drawing operations.
- Parameters:
- path: A ``Path`` that defines the shape of the clipping mask.
- style: A ``FillStyle`` that defines how to rasterize the shape.
- options: Clip options that tell SwiftUI how to interpret the `path`
as a clip shape. For example, you can invert the clip
shape by setting the ``ClipOptions/inverse`` option.
Draws text into the context, aligning an anchor within the ideal size
of the rendered text to a point in the context.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the text.
- Parameters:
- text: The ``Text`` view to draw. Before drawing, the method converts
the view to ``ResolvedText`` by calling ``resolve(_:)-4dx65``.
- point: A point within the rectangle of the resolved text to anchor
to a point in the context.
- anchor: A ``UnitPoint`` within the context to align the text with.
The default is ``UnitPoint/center``.
Draws an image into the context, aligning an anchor within the image
to a point in the context.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the image.
- Parameters:
- image: The ``Image`` to draw. Before drawing, the method converts
the image to a ``ResolvedImage`` by calling ``resolve(_:)-898z6``.
- point: A point within the rectangle of the resolved image to anchor
to a point in the context.
- anchor: A ``UnitPoint`` within the context to align the image with.
The default is ``UnitPoint/center``.
Draws resolved text into the context, aligning an anchor within the
ideal size of the text to a point in the context.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the text.
- Parameters:
- text: The ``ResolvedText`` to draw. Get resolved text from a
``Text`` view by calling ``resolve(_:)-4dx65``. Alternatively, you
can call ``draw(_:at:anchor:)-5dgmd`` with a ``Text`` view, and that
method performs the resolution automatically.
- point: A point within the rectangle of the ideal size of the
resolved text to anchor to a point in the context.
- anchor: A ``UnitPoint`` within the context to align the text with.
The default is ``UnitPoint/center``.
Draws a resolved image into the context, aligning an anchor within the
image to a point in the context.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the image.
- Parameters:
- image: The ``ResolvedImage`` to draw. Get a resolved image from an
``Image`` by calling ``resolve(_:)-898z6``. Alternatively, you can
call ``draw(_:at:anchor:)-7l217`` with an ``Image``, and that method
performs the resolution automatically.
- point: A point within the rectangle of the resolved image to anchor
to a point in the context.
- anchor: A ``UnitPoint`` within the context to align the image with.
The default is ``UnitPoint/center``.
Draws a resolved symbol into the context, aligning an anchor within the
symbol to a point in the context.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the symbol.
- Parameters:
- symbol: The ``ResolvedSymbol`` view to draw. Get a resolved symbol
by calling ``resolveSymbol(id:)`` with the identifier that you
use to tag the corresponding child view during ``Canvas``
initialization.
- point: A point within the rectangle of the resolved symbol to anchor
to a point in the context.
- anchor: A ``UnitPoint`` within the context to align the symbol with.
The default is ``UnitPoint/center``.
Draws an image into the context, using the specified rectangle
as a layout frame.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the image.
- Parameters:
- image: The ``Image`` to draw. Before drawing, the method converts
the image to a ``ResolvedImage`` by calling ``resolve(_:)-898z6``.
- rect: The rectangle in the current user space to draw the image in.
- style: A fill style to use when rasterizing the image.
Draws a resolved image into the context, using the specified rectangle
as a layout frame.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the image.
- Parameters:
- image: The ``ResolvedImage`` to draw. Get a resolved image from an
``Image`` by calling ``resolve(_:)-898z6``. Alternatively, you can
call ``draw(_:in:style:)-blhz`` with an ``Image``, and that method
performs the resolution automatically.
- rect: The rectangle in the current user space to draw the image in.
- style: A fill style to use when rasterizing the image.
Draws text into the context using the specified rectangle
as a layout frame.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the text.
- Parameters:
- text: The ``Text`` view to draw. Before drawing, the method converts
the view to ``ResolvedText`` by calling ``resolve(_:)-4dx65``.
- rect: The rectangle in the current user space to draw the text in.
func draw(_ text: GraphicsContext.ResolvedText, in rect: CGRect)
Draws resolved text into the context using the specified rectangle
as a layout frame.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the text.
- Parameters:
- text: The ``ResolvedText`` to draw. Get resolved text from a
``Text`` view by calling ``resolve(_:)-4dx65``. Alternatively, you
can call ``draw(_:in:)-5opqf`` with a ``Text`` view, and that
method performs the resolution automatically.
- rect: The rectangle in the current user space to draw the text in.
func draw(_ symbol: GraphicsContext.ResolvedSymbol, in rect: CGRect)
Draws a resolved symbol into the context, using the specified rectangle
as a layout frame.
The current context state defines the full drawing operation. For
example, the current transformation and clip shapes affect how SwiftUI
draws the symbol.
- Parameters:
- symbol: The ``ResolvedSymbol`` to draw. Get a resolved symbol
by calling ``resolveSymbol(id:)`` with the identifier that you
use to tag the corresponding child view during ``Canvas``
initialization.
- rect: The rectangle in the current user space to draw the symbol in.
Draws a path into the context and fills the outlined region.
The current drawing state of the context defines the
full drawing operation. For example, the current transformation and
clip shapes, and any styles applied to the result, affect the final
result.
- Parameters:
- path: The outline of the region to fill.
- shading: The color or pattern to use when filling the region
bounded by `path`.
- style: A style that indicates how to rasterize the path.
method · iOS 15.0+
rotate
TypeScript
rotate(angle: Angle): void
Swift declaration
mutating func rotate(by angle: Angle)
Rotates subsequent drawing operations by an angle.
Calling this method is equivalent to updating the context's
``transform`` directly using the `angle` parameter:
transform = transform.rotated(by: angle.radians)
- Parameters:
- angle: The amount to rotate.
func stroke(_ path: Path, with shading: GraphicsContext.Shading, style: StrokeStyle)
Draws a path into the context with a specified stroke style.
If you only need to control the style's ``StrokeStyle/lineWidth``
property, use ``stroke(_:with:lineWidth:)`` instead.
- Parameters:
- path: The path to outline.
- shading: The color or pattern to use when outlining the `path`.
- style: A style that indicates how to outline the path.
Draws a path into the context with a specified line width.
When you call this method, all ``StrokeStyle`` properties other than
``StrokeStyle/lineWidth`` take their default values. To control other
style properties, use ``stroke(_:with:style:)`` instead.
- Parameters:
- path: The path to outline.
- shading: The color or pattern to use when outlining the `path`.
- lineWidth: The width of the stroke, which defaults to `1`.
get · iOS 15.0+
opacity
TypeScript
get opacity(): number
Swift declaration
var opacity: Double { get set }
The opacity of drawing operations in the context.
Set this value to affect the opacity of content that you subsequently
draw into the context. Changing this value has no impact on the
content you previously drew into the context.
set · iOS 15.0+
opacity
TypeScript
set opacity(value: number)
Swift declaration
var opacity: Double { get set }
The opacity of drawing operations in the context.
Set this value to affect the opacity of content that you subsequently
draw into the context. Changing this value has no impact on the
content you previously drew into the context.
Gets a version of a text view that's fixed with the current values of
the graphics context's environment.
You can measure the resolved text by calling its
``ResolvedText/measure(in:)`` method.
You can draw the resolved text with the context's
``draw(_:in:)-69ad8`` or ``draw(_:at:anchor:)-6xr87`` method.
- Parameter text: The ``Text`` view to resolve.
- Returns: A text view that's resolved into the current context's
environment, taking into account environment values like the
display resolution and current color scheme.
Gets a version of an image that's fixed with the current values of
the graphics context's environment.
You can measure the resolved image by looking at its
``ResolvedImage/size`` and ``ResolvedImage/baseline`` properties.
You can draw the resolved image with the context's
``draw(_:in:style:)-7rvee`` or ``draw(_:at:anchor:)-1z5wt`` method.
- Parameter image: The ``Image`` to resolve.
- Returns: An image that's resolved into the current context's
environment, taking into account environment values like the
display resolution and current color scheme.
Returns a version of a shading resolved with the current values
of the graphics context's environment.
Calling this function once and then drawing multiple times with
the result will often have less overhead than drawing with the
original shading multiple times.
method · iOS 15.0+
scaleBy
TypeScript
scaleBy(x: number, y: number): void
Swift declaration
mutating func scaleBy(x: CGFloat, y: CGFloat)
Scales subsequent drawing operations by an amount in each dimension.
Calling this method is equivalent to updating the context's
``transform`` directly using the given scale factors:
transform = transform.scaledBy(x: x, y: y)
- Parameters:
- x: The amount to scale in the horizontal direction.
- y: The amount to scale in the vertical direction.
Adds a filter that applies to subsequent drawing operations.
To draw with filtering, SwiftUI:
- Rasterizes the drawing operation to an implicit transparency layer
without blending, adjusting opacity, or applying any clipping.
- Applies the filter to the layer containing the rasterized image.
- Composites the layer onto the background, using the context's
current blend mode, opacity setting, and clip shapes.
When SwiftUI draws with a filter, the blend mode might apply to regions
outside the drawing operation's intrinsic shape, but inside its clip
shape. That might result in unexpected behavior for certain blend
modes like ``GraphicsContext/BlendMode-swift.struct/copy``, where
the drawing operation completely overwrites the background even if
the source alpha is zero.
- Parameters:
- filter: A graphics context filter that you create by calling one
of the ``Filter`` factory methods.
- options: A set of options from ``FilterOptions`` that you can use to
configure filter operations.
get · iOS 15.0+
blendMode
TypeScript
get blendMode(): GraphicsContext_BlendMode
Swift declaration
var blendMode: GraphicsContext.BlendMode { get set }
The blend mode used by drawing operations in the context.
Set this value to affect how any content that you subsequently draw
into the context blends with content that's already in the context.
Use one of the ``GraphicsContext/BlendMode-swift.struct`` values.
set · iOS 15.0+
blendMode
TypeScript
set blendMode(value: GraphicsContext_BlendMode)
Swift declaration
var blendMode: GraphicsContext.BlendMode { get set }
The blend mode used by drawing operations in the context.
Set this value to affect how any content that you subsequently draw
into the context blends with content that's already in the context.
Use one of the ``GraphicsContext/BlendMode-swift.struct`` values.
Draws a new layer, created by drawing code that you provide, into the
context.
- Parameter content: A closure that receives a new ``GraphicsContext``
as input. This context represents a new transparency layer that you
can draw into. When the closure returns, SwiftUI draws the new layer
into the current context.
get · iOS 15.0+
transform
TypeScript
get transform(): _CoreFoundation_CGAffineTransform
Swift declaration
var transform: CGAffineTransform { get set }
The current transform matrix, defining user space coordinates.
Modify this matrix to transform content that you subsequently
draw into the context. Changes that you make don't affect
existing content.
set · iOS 15.0+
transform
TypeScript
set transform(value: _CoreFoundation_CGAffineTransform)
Swift declaration
var transform: CGAffineTransform { get set }
The current transform matrix, defining user space coordinates.
Modify this matrix to transform content that you subsequently
draw into the context. Changes that you make don't affect
existing content.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
GraphicsContext.environment
The iOS SDK compiler rejected this binding: setter for 'environment' is only available in iOS 18.2 or newer
