Interface

BlurRadiusSpec

Configures varying blur radius across a surface.

Source set: Common
public sealed interface BlurRadiusSpec

Configures varying blur radius across a surface.

Obtain instances from companion factories and pass them to androidx.compose.ui.draw.blur, or realize them into a RenderEffect with createRenderEffect.

Uniform radii (uniform) are supported on Android 12 (API 31)+. Spatially-varying radii require Android 13 (API 33)+. Unsupported configurations render the content unblurred.

Every length in the configuration, including gradient geometry, is expressed in Dp and resolves against the layer's size and density at draw time. The shader shader is the exception: it evaluates in layer pixel coordinates and returns a unitless 0..1 intensity. Spatially-varying radii cap at 150px once resolved; uniform radii are not capped.

Functions

createRenderEffect

Source set: Common
public fun createRenderEffect(
        size: Size,
        density: Density,
        edgeTreatment: TileMode = TileMode.Clamp,
    ): RenderEffect

Creates a RenderEffect that applies this blur configuration.

Assign the result to a graphics layer for low-level control, or prefer the block-based androidx.compose.ui.draw.blur overload, which manages the effect automatically.

The effect resolves this configuration against size and density at creation, so create a new effect whenever the configuration or the layer size changes — for example inside a androidx.compose.ui.graphics.graphicsLayer block where the layer size is known.

Platform support varies with the configuration; query availability at runtime with RenderEffect.isSupported. Unsupported platforms and zero radii render content unblurred.

Parameters
size size of the layer being blurred, in pixels
density density used to resolve Dp radii to pixels
edgeTreatment strategy used to sample pixels outside the content bounds

Return

RenderEffect applying the progressive blur

Members

Companion

Source set: Common
public companion object

Functions

uniform

Source set: Common
public fun uniform(radius: Dp): BlurRadiusSpec

Creates a uniform blur radius across the surface.

Supported on Android 12 (API 31) and above. Older platforms and unsupported configurations render the content unblurred.

Parameters
radius blur radius across the surface

Throws: IllegalArgumentException

if radius is negative

verticalGradient

Source set: Common
public fun verticalGradient(startRadius: Dp, endRadius: Dp): BlurRadiusSpec

Creates a vertical blur gradient from startRadius at top to endRadius at bottom.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Parameters
startRadius blur radius at the top
endRadius blur radius at the bottom

Throws: IllegalArgumentException

if either radius is negative

verticalGradient

Source set: Common
public fun verticalGradient(stops: List<BlurStop>): BlurRadiusSpec

Creates a vertical multi-stop blur gradient from top to bottom.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Accepts stops in any order and sorts them stably by BlurStop.fraction.

Parameters
stops list of blur stops defining the gradient

Throws: IllegalArgumentException

if the stop count is outside 2..16

horizontalGradient

Source set: Common
public fun horizontalGradient(startRadius: Dp, endRadius: Dp): BlurRadiusSpec

Creates a horizontal blur gradient from startRadius at left to endRadius at right.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Parameters
startRadius blur radius at the left
endRadius blur radius at the right

Throws: IllegalArgumentException

if either radius is negative

horizontalGradient

Source set: Common
public fun horizontalGradient(stops: List<BlurStop>): BlurRadiusSpec

Creates a horizontal multi-stop blur gradient from left to right.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Accepts stops in any order and sorts them stably by BlurStop.fraction.

Parameters
stops list of blur stops defining the gradient

Throws: IllegalArgumentException

if the stop count is outside 2..16

linearGradient

Source set: Common
public fun linearGradient(
            start: DpOffset,
            end: DpOffset,
            startRadius: Dp,
            endRadius: Dp,
        ): BlurRadiusSpec

Creates a linear blur gradient from startRadius at start to endRadius at end.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Parameters
start start position within the layer
end end position within the layer
startRadius blur radius at start
endRadius blur radius at end

Throws: IllegalArgumentException

if either radius is negative

linearGradient

Source set: Common
public fun linearGradient(
            start: DpOffset,
            end: DpOffset,
            stops: List<BlurStop>,
        ): BlurRadiusSpec

Creates a linear multi-stop blur gradient along the start to end line.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Accepts stops in any order and sorts them stably by BlurStop.fraction.

Parameters
start start position within the layer
end end position within the layer
stops list of blur stops defining the gradient

Throws: IllegalArgumentException

if the stop count is outside 2..16

radialGradient

Source set: Common
public fun radialGradient(
            startRadius: Dp,
            endRadius: Dp,
            center: DpOffset = DpOffset.Unspecified,
            fallOffRadius: Dp = Dp.Infinity,
        ): BlurRadiusSpec

Creates a radial blur gradient from startRadius at center to endRadius at fallOffRadius.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Parameters
startRadius blur radius at the center of the gradient
endRadius blur radius at the falloff distance
center center of the gradient within the layer, or DpOffset.Unspecified for the surface center
fallOffRadius distance from center at which endRadius is reached; defaults to half the surface's minimum dimension

Throws: IllegalArgumentException

if either radius is negative, or fallOffRadius is finite and not positive

radialGradient

Source set: Common
public fun radialGradient(
            stops: List<BlurStop>,
            center: DpOffset = DpOffset.Unspecified,
            fallOffRadius: Dp = Dp.Infinity,
        ): BlurRadiusSpec

Creates a radial multi-stop blur gradient from center to fallOffRadius.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Accepts stops in any order and sorts them stably by BlurStop.fraction.

Parameters
stops list of blur stops defining the gradient
center center of the gradient within the layer, or DpOffset.Unspecified for the surface center
fallOffRadius distance from center at which fraction 1 is reached; defaults to half the surface's minimum dimension

Throws: IllegalArgumentException

if the stop count is outside 2..16

Throws: IllegalArgumentException

if fallOffRadius is finite and not positive

shader

Source set: Common
public fun shader(maxRadius: Dp, block: Density.(sizePx: Size) -> Shader): BlurRadiusSpec

Creates a custom blur intensity mask driven by a Shader.

Supported on Android 13 (API 33) and above. Older platforms and unsupported configurations render the content unblurred.

Invokes block once per draw with the layer's Size and Density. Mutate the returned shader's uniforms between frames to animate the blur. The shader evaluates in layer pixel coordinates from the top-left origin. Its sampled alpha channel is a 0..1 intensity scaling maxRadius; values outside that range are clamped. Any Shader can serve as the mask, including gradients from androidx.compose.ui.graphics.ShaderBrush.

The Size passed to block is in pixels.

Create the shader once and reuse it across frames. Each call returns a new configuration that never compares equal, defeating downstream caching.

Parameters
maxRadius maximum blur radius scaled by the shader alpha
block builder producing a Shader given the layer size and density

Throws: IllegalArgumentException

if maxRadius is negative

Content updated: