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.

Summary

Public companion functions
BlurRadiusSpec

Creates a horizontal multi-stop blur gradient from left to right.
Cmn
BlurRadiusSpec
horizontalGradient(startRadius: Dp, endRadius: Dp)

Creates a horizontal blur gradient from startRadius at left to endRadius at right.
Cmn
BlurRadiusSpec
linearGradient(start: DpOffset, end: DpOffset, stops: List<BlurStop>)

Creates a linear multi-stop blur gradient along the start to end line.
Cmn
BlurRadiusSpec
linearGradient(
    start: DpOffset,
    end: DpOffset,
    startRadius: Dp,
    endRadius: Dp
)

Creates a linear blur gradient from startRadius at start to endRadius at end.
Cmn
BlurRadiusSpec
radialGradient(stops: List<BlurStop>, center: DpOffset, fallOffRadius: Dp)

Creates a radial multi-stop blur gradient from center to fallOffRadius.
Cmn
BlurRadiusSpec
radialGradient(
    startRadius: Dp,
    endRadius: Dp,
    center: DpOffset,
    fallOffRadius: Dp
)

Creates a radial blur gradient from startRadius at center to endRadius at fallOffRadius.
Cmn
BlurRadiusSpec
shader(maxRadius: Dp, block: Density.(sizePx: Size) -> Shader)

Creates a custom blur intensity mask driven by a Shader.
Cmn
BlurRadiusSpec
uniform(radius: Dp)

Creates a uniform blur radius across the surface.
Cmn
BlurRadiusSpec

Creates a vertical multi-stop blur gradient from top to bottom.
Cmn
BlurRadiusSpec
verticalGradient(startRadius: Dp, endRadius: Dp)

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

Public functions
RenderEffect
createRenderEffect(size: Size, density: Density, edgeTreatment: TileMode)

Creates a RenderEffect that applies this blur configuration.
Cmn

Public companion functions

horizontalGradient

Cmn 
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<BlurStop>

list of blur stops defining the gradient
Throws
IllegalArgumentException

if the stop count is outside 2..16

horizontalGradient

Cmn 
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: Dp

blur radius at the left
endRadius: Dp

blur radius at the right
Throws
IllegalArgumentException

if either radius is negative

linearGradient

Cmn 
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: DpOffset

start position within the layer
end: DpOffset

end position within the layer
stops: List<BlurStop>

list of blur stops defining the gradient
Throws
IllegalArgumentException

if the stop count is outside 2..16

linearGradient

Cmn 
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: DpOffset

start position within the layer
end: DpOffset

end position within the layer
startRadius: Dp

blur radius at start
endRadius: Dp

blur radius at end
Throws
IllegalArgumentException

if either radius is negative

radialGradient

Cmn 
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<BlurStop>

list of blur stops defining the gradient
center: DpOffset = DpOffset.Unspecified

center of the gradient within the layer, or DpOffset.Unspecified for the surface center
fallOffRadius: Dp = Dp.Infinity

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
IllegalArgumentException

if fallOffRadius is finite and not positive

radialGradient

Cmn 
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: Dp

blur radius at the center of the gradient
endRadius: Dp

blur radius at the falloff distance
center: DpOffset = DpOffset.Unspecified

center of the gradient within the layer, or DpOffset.Unspecified for the surface center
fallOffRadius: Dp = Dp.Infinity

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

shader

Cmn 
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: Dp

maximum blur radius scaled by the shader alpha
block: Density.(sizePx: Size) -> Shader

builder producing a Shader given the layer size and density
Throws
IllegalArgumentException

if maxRadius is negative

uniform

Cmn 
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: Dp

blur radius across the surface
Throws
IllegalArgumentException

if radius is negative

verticalGradient

Cmn 
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<BlurStop>

list of blur stops defining the gradient
Throws
IllegalArgumentException

if the stop count is outside 2..16

verticalGradient

Cmn 
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: Dp

blur radius at the top
endRadius: Dp

blur radius at the bottom
Throws
IllegalArgumentException

if either radius is negative

Public functions

createRenderEffect

Cmn 
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

size of the layer being blurred, in pixels
density: Density

density used to resolve Dp radii to pixels
edgeTreatment: TileMode = TileMode.Clamp

strategy used to sample pixels outside the content bounds
Returns
RenderEffect

RenderEffect applying the progressive blur