Visual Effects change the visual appearance of a view without changing its
ancestors or descendents.
Because effects do not impact layout, they are safe to use in situations
where layout modification is not allowed. For example, effects may be
applied as a function of position, accessed through a geometry proxy:
```swift
var body: some View {
ContentRow()
.visualEffect { content, geometryProxy in
content.offset(x: geometryProxy.frame(in: .global).origin.y)
}
}
```
You don't conform to this protocol yourself. Instead, visual effects are
created by calling modifier functions (such as `.offset(x:y:)` on other
effects, as seen in the example above.
Returns a new visual effect that applies `shader` to `self` as
a geometric distortion effect on the location of each pixel.
For a shader function to act as a distortion effect it must
have a function signature matching:
[[ stitchable ]] float2 name(float2 position, args...)
where `position` is the user-space coordinates of the
destination pixel applied to the shader. `args...` should be
compatible with the uniform arguments bound to `shader`. The
function should return the user-space coordinates of the
corresponding source pixel.
> Important: Views backed by AppKit or UIKit views may not
render into the filtered layer. Instead, they log a warning
and display a placeholder image to highlight the error.
- Parameters:
- shader: The shader to apply as a distortion effect.
- maxSampleOffset: The maximum distance in each axis between
the returned source pixel position and the destination pixel
position, for all source pixels.
- isEnabled: Whether the effect is enabled or not.
- Returns: A new view that renders `self` with the shader
applied as a distortion effect.
Returns a new visual effect that applies `shader` to `self` as
a filter effect on the color of each pixel.
For a shader function to act as a color filter it must have a
function signature matching:
[[ stitchable ]] half4 name(float2 position, half4 color, args...)
where `position` is the user-space coordinates of the pixel
applied to the shader and `color` its source color, as a
pre-multiplied color in the destination color space. `args...`
should be compatible with the uniform arguments bound to
`shader`. The function should return the modified color value.
> Important: Views backed by AppKit or UIKit views may not
render into the filtered layer. Instead, they log a warning
and display a placeholder image to highlight the error.
- Parameters:
- shader: The shader to apply to `self` as a color filter.
- isEnabled: Whether the effect is enabled or not.
- Returns: A new view that renders `self` with the shader
applied as a color filter.
Returns a new visual effect that applies `shader` to `self` as
a filter on the raster layer created from `self`.
For a shader function to act as a layer effect it must
have a function signature matching:
[[ stitchable ]] half4 name(float2 position,
SwiftUI::Layer layer, args...)
where `position` is the user-space coordinates of the
destination pixel applied to the shader, and `layer` is a
subregion of the rasterized contents of `self`. `args...`
should be compatible with the uniform arguments bound to
`shader`.
The `SwiftUI::Layer` type is defined in the
`<SwiftUI/SwiftUI.h>` header file. It exports a single
`sample()` function that returns a linearly-filtered pixel
value from a position in the source content, as a premultiplied
RGBA pixel value:
namespace SwiftUI {
struct Layer {
half4 sample(float2 position) const;
};
};
The function should return the color mapping to the destination
pixel, typically by sampling one or more pixels from `layer` at
location(s) derived from `position` and them applying some kind
of transformation to produce a new color.
> Important: Views backed by AppKit or UIKit views may not
render into the filtered layer. Instead, they log a warning
and display a placeholder image to highlight the error.
- Parameters:
- shader: The shader to apply as a layer effect.
- maxSampleOffset: If the shader function samples from the
layer at locations not equal to the destination position,
this value must specify the maximum sampling distance in
each axis, for all source pixels.
- isEnabled: Whether the effect is enabled or not.
- Returns: A new view that renders `self` with the shader
applied as a distortion effect.
Scales the view's rendered output by the given horizontal and vertical
amounts, relative to an anchor point.
- Parameters:
- x: An amount that represents the horizontal amount to scale the
view. The default value is `1.0`.
- y: An amount that represents the vertical amount to scale the view.
The default value is `1.0`.
- anchor: The point with a default of ``UnitPoint/center`` that
defines the location within the view from which to apply the
transformation.
- Returns: An effect that scales the view's rendered output.
Scales the view's rendered output by the given amount in both the
horizontal and vertical directions, relative to an anchor point.
- Parameters:
- scale: The amount to scale the view in the view in both the horizontal
and vertical directions.
- anchor: The point with a default of ``UnitPoint/center`` that
defines the location within the view from which to apply the
transformation.
- Returns: An effect that scales the view's rendered output.
Scales the view's rendered output by the given vertical and horizontal
size amounts, relative to an anchor point.
- Parameters:
- scale: A <doc://com.apple.documentation/documentation/CoreFoundation/CGSize> that
represents the horizontal and vertical amount to scale the view.
- anchor: The point with a default of ``UnitPoint/center`` that
defines the location within the view from which to apply the
transformation.
- Returns: An effect that scales the view's rendered output.
Rotates content in two dimensions around the specified point.
This effect rotates the content around the axis that points
out of the xy-plane. It has no effect on the content's frame.
The following code rotates text by 22˚ and then draws a border around
the modified view to show that the frame remains unchanged by the
rotation:
Text("Rotation by passing an angle in degrees")
.visualEffect { content, geometryProxy in
content
.rotationEffect(.degrees(22))
}
.border(Color.gray)
- Parameters:
- angle: The angle by which to rotate the content.
- anchor: A unit point within the content about which to
perform the rotation. The default value is ``UnitPoint/center``.
- Returns: A rotation effect.
method · iOS 17.0+
transformEffect
Swift declaration
func transformEffect(_ transform: ProjectionTransform) -> some VisualEffect
Applies a projection transformation to the view's rendered output.
Use `transformEffect(_:)` to rotate, scale, translate, or skew the
output of the view according to the provided
<doc://com.apple.documentation/documentation/SwiftUI/ProjectionTransform>.
- Parameter transform: A
<doc://com.apple.documentation/documentation/SwiftUI/ProjectionTransform> to
apply to the view.
- Returns: An effect that applies a projection transformation to the
view's rendered output.
method · iOS 17.0+
transformEffect
Swift declaration
func transformEffect(_ transform: CGAffineTransform) -> some VisualEffect
Applies an affine transformation to the view's rendered output.
Use `transformEffect(_:)` to rotate, scale, translate, or skew the
output of the view according to the provided
<doc://com.apple.documentation/documentation/CoreFoundation/CGAffineTransform>.
- Parameter transform: A
<doc://com.apple.documentation/documentation/CoreFoundation/CGAffineTransform> to
apply to the view.
- Returns: An effect that applies an affine transformation to the
view's rendered output.
method · iOS 17.0+
brightness
Swift declaration
func brightness(_ amount: Double) -> some VisualEffect
Brightens the view by the specified amount.
- Parameter amount: A value between 0 (no effect) and 1 (full white
brightening) that represents the intensity of the brightness effect.
- Returns: An effect that brightens the view by the specified amount.
method · iOS 17.0+
saturation
Swift declaration
func saturation(_ amount: Double) -> some VisualEffect
Adjusts the color saturation of the view.
Use color saturation to increase or decrease the intensity of colors in
a view.
- SeeAlso: `contrast(_:)`
- Parameter amount: The amount of saturation to apply to the view.
- Returns: An effect that adjusts the saturation of the view.
method · iOS 17.0+
hueRotation
Swift declaration
func hueRotation(_ angle: Angle) -> some VisualEffect
Applies a hue rotation effect to the view.
Use hue rotation effect to shift all of the colors in a view according
to the angle you specify.
- Parameter angle: The hue rotation angle to apply to the colors in the
view.
- Returns: An effect that shifts all of the colors in the view.
Renders content as if it's rotated in three dimensions around
the specified axis.
Use this method to create the effect of rotating a two dimensional view
in three dimensions around a specified axis of rotation. The effect
projects the rotated content onto the original content's plane. Use the
`perspective` input to control the renderer's vanishing point.
The following example creates the appearance of rotating
text 45˚ about the y-axis:
Text("Rotation by passing an angle in degrees")
.visualEffect { content, geometryProxy in
content
.rotation3DEffect(
.degrees(45),
axis: (x: 0.0, y: 1.0, z: 0.0),
anchor: .center,
anchorZ: 0,
perspective: 1)
}
.border(Color.gray)
> Important: In visionOS, create this effect with
``perspectiveRotationEffect(_:axis:anchor:perspective:)``
instead. To truly rotate a view in three dimensions,
use a 3D rotation effect without a perspective input like
``rotation3DEffect(_:axis:anchor:)``.
- Parameters:
- angle: The angle by which to rotate the content.
- axis: The axis of rotation, specified as a tuple with named
elements for each of the three spatial dimensions.
- anchor: A two dimensional unit point within the content about which
to perform the rotation. The default value is ``UnitPoint/center``.
- anchorZ: The location on the z-axis around which to rotate the
content. The default is `0`.
- perspective: The relative vanishing point for the rotation. The
default is `1`.
- Returns: A rotation effect.
method · iOS 17.0+
blur
Swift declaration
func blur(radius: CGFloat, opaque: Bool = false) -> some VisualEffect
Applies a Gaussian blur to the view.
Use `blur(radius:opaque:)` to apply a gaussian blur effect to the
rendering of the view.
- Parameters:
- radius: The radial size of the blur. A blur is more diffuse when its
radius is large.
- opaque: A Boolean value that indicates whether the blur renderer
permits transparency in the blur output. Set to `true` to create an
opaque blur, or set to `false` to permit transparency.
- Returns: An effect that blurs the view.
Offsets the view by the specified horizontal and vertical distances.
- Parameters:
- x: The horizontal distance to offset the view.
- y: The vertical distance to offset the view.
- Returns: An effect that offsets the view by `x` and `y`.
method · iOS 17.0+
offset
Swift declaration
func offset(_ offset: CGSize) -> some VisualEffect
Offsets the view by the horizontal and vertical amount specified in the
offset parameter.
- Parameter offset: The distance to offset the view.
- Returns: An effect that offsets the view by `offset`.
method · iOS 17.0+
opacity
Swift declaration
func opacity(_ opacity: Double) -> some VisualEffect
Sets the transparency of the view.
When applying the `opacity(_:)` effect to a view that has already had
its opacity transformed, the effect of the underlying opacity
transformation is multiplied.
- Parameter opacity: A value between 0 (fully transparent) and 1 (fully
opaque).
- Returns: An effect that sets the transparency of the view.
method · iOS 17.0+
contrast
Swift declaration
func contrast(_ amount: Double) -> some VisualEffect
Sets the contrast and separation between similar colors in the view.
Apply contrast to a view to increase or decrease the separation between
similar colors in the view.
- Parameter amount: The intensity of color contrast to apply. negative
values invert colors in addition to applying contrast.
- Returns: An effect that applies color contrast to the view.
method · iOS 18.0+
blendMode
Swift declaration
func blendMode(_ blendMode: BlendMode) -> some VisualEffect
Sets the blend mode for compositing this view with overlapping views.
Use `blendMode(_:)` to combine overlapping views and use a different
visual effect to produce the result. The ``BlendMode`` enumeration
defines many possible effects.
- Parameter blendMode: The ``BlendMode`` for compositing.
- Returns: An effect that applies `blendMode` to this view.
method · iOS 17.0+
grayscale
Swift declaration
func grayscale(_ amount: Double) -> some VisualEffect
Adds a grayscale effect to the view.
A grayscale effect reduces the intensity of colors in the view.
- Parameter amount: The intensity of grayscale to apply from 0.0 to less
than 1.0. Values closer to 0.0 are more colorful, and values closer to
1.0 are less colorful.
- Returns: An effect that reduces the intensity of colors in the view.
