Wipe Effects - Android

import android.util.Log
import ly.img.editor.defaultBaseUri
import ly.img.engine.AnimationEasingType
import ly.img.engine.DesignBlock
import ly.img.engine.DesignBlockType
import ly.img.engine.EffectType
import ly.img.engine.Engine
import ly.img.engine.FillType
import ly.img.engine.Keyframe
import ly.img.engine.KeyframeEasing
import ly.img.engine.KeyframeValue
import ly.img.engine.MimeType
import ly.img.engine.ShapeType
import java.nio.ByteBuffer

private const val TAG = "WipeEffects"

data class WipeEffects(
    val linearWipeEffectTypes: List<String>,
    val radialWipeEffectTypes: List<String>,
    val venetianBlindsEffectTypes: List<String>,
    val revealEffectTypes: List<String>,
    val linearWipeCompletion: Float,
    val revealKeyframes: List<Keyframe>,
    val radialWipeProperties: List<String>,
    // The frame of the reveal block on the page, in design units
    val revealX: Float,
    val revealY: Float,
    val revealWidth: Float,
    val revealHeight: Float,
    val earlyFramePng: ByteBuffer,
    val lateFramePng: ByteBuffer,
)

suspend fun wipeEffects(engine: Engine): WipeEffects {
    val scene = engine.scene.create()
    val page = engine.block.create(DesignBlockType.Page)
    engine.block.setWidth(block = page, value = 800F)
    engine.block.setHeight(block = page, value = 620F)
    engine.block.appendChild(parent = scene, child = page)

    // Adds a 360 x 270 image block to the page at a position
    val imageUri = defaultBaseUri.buildUpon()
        .appendPath("ly.img.image")
        .appendPath("images")
        .appendPath("sample_1.jpg")
        .build()

    fun addImageBlock(
        x: Float,
        y: Float,
    ): DesignBlock {
        val block = engine.block.create(DesignBlockType.Graphic)
        engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Rect))
        val fill = engine.block.createFill(FillType.Image)
        engine.block.setUri(block = fill, property = "fill/image/imageFileURI", value = imageUri)
        engine.block.setFill(block = block, fill = fill)
        engine.block.setWidth(block = block, value = 360F)
        engine.block.setHeight(block = block, value = 270F)
        engine.block.setPositionX(block = block, value = x)
        engine.block.setPositionY(block = block, value = y)
        engine.block.appendChild(parent = page, child = block)
        return block
    }

    val linearWipeBlock = addImageBlock(x = 30F, y = 30F)
    val radialWipeBlock = addImageBlock(x = 410F, y = 30F)
    val venetianBlindsBlock = addImageBlock(x = 30F, y = 320F)
    val revealBlock = addImageBlock(x = 410F, y = 320F)

    // Hide the left half of the block with a soft edge of 40 design units
    val linearWipe = engine.block.createEffect(EffectType.LinearWipe)
    engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/angle", value = 90F)
    engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/completion", value = 0.5F)
    engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/feather", value = 40F)
    engine.block.appendEffect(block = linearWipeBlock, effectBlock = linearWipe)

    // Hide 60% of the circle, sweeping clockwise from 12 o'clock around the block center
    val radialWipe = engine.block.createEffect(EffectType.RadialWipe)
    engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/completion", value = 0.6F)
    engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/startAngle", value = 0F)
    engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/centerX", value = 0.5F)
    engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/centerY", value = 0.5F)
    engine.block.setEnum(block = radialWipe, property = "effect/radial_wipe/direction", value = "Clockwise")
    engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/feather", value = 20F)
    engine.block.appendEffect(block = radialWipeBlock, effectBlock = radialWipe)

    // Hide half of each 60 design unit wide stripe, with the stripes at 45 degrees
    val venetianBlinds = engine.block.createEffect(EffectType.VenetianBlinds)
    engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/completion", value = 0.5F)
    engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/direction", value = 45F)
    engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/width", value = 60F)
    engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/feather", value = 2F)
    engine.block.appendEffect(block = venetianBlindsBlock, effectBlock = venetianBlinds)

    // Reveal the block over its 2 second duration: all hidden at the start, all shown at the end
    engine.block.setDuration(block = revealBlock, duration = 2.0)
    val reveal = engine.block.createEffect(EffectType.LinearWipe)
    engine.block.appendEffect(block = revealBlock, effectBlock = reveal)
    engine.block.setKeyframes(
        block = reveal,
        property = "effect/linear_wipe/completion",
        keyframes = listOf(
            Keyframe(
                time = 0F,
                value = KeyframeValue.Float(1F),
                easing = KeyframeEasing.Preset(AnimationEasingType.EASE_OUT),
            ),
            Keyframe(time = 1F, value = KeyframeValue.Float(0F)),
        ),
    )
    val revealKeyframes = engine.block.getKeyframes(block = reveal, property = "effect/linear_wipe/completion")
    Log.i(TAG, "Completion keyframes: $revealKeyframes")

    // Export the page at 0.5 and 1.5 seconds. The reveal block shows more of the image in the later frame.
    engine.block.setPlaybackTime(block = page, time = 0.5)
    val earlyFramePng = engine.block.export(block = page, mimeType = MimeType.PNG)
    engine.block.setPlaybackTime(block = page, time = 1.5)
    val lateFramePng = engine.block.export(block = page, mimeType = MimeType.PNG)

    val effectTypes = { block: DesignBlock ->
        engine.block.getEffects(block).map { engine.block.getType(it) }
    }
    return WipeEffects(
        linearWipeEffectTypes = effectTypes(linearWipeBlock),
        radialWipeEffectTypes = effectTypes(radialWipeBlock),
        venetianBlindsEffectTypes = effectTypes(venetianBlindsBlock),
        revealEffectTypes = effectTypes(revealBlock),
        linearWipeCompletion = engine.block.getFloat(block = linearWipe, property = "effect/linear_wipe/completion"),
        revealKeyframes = revealKeyframes,
        radialWipeProperties = engine.block.findAllProperties(radialWipe),
        revealX = engine.block.getPositionX(revealBlock),
        revealY = engine.block.getPositionY(revealBlock),
        revealWidth = engine.block.getWidth(revealBlock),
        revealHeight = engine.block.getHeight(revealBlock),
        earlyFramePng = earlyFramePng,
        lateFramePng = lateFramePng,
    )
}

Hide parts of a block with the linear wipe, radial wipe and venetian blinds effects, and animate them to reveal it.

6 mins

estimated time

GitHub

A wipe effect hides a part of a block. completion sets the hidden part, from 0 (all shown) to 1 (all hidden). Wipe effects use the same effect API as all other effects: createEffect, the property setters and appendEffect. Scenes that use these effects do not open in earlier versions of CE.SDK. To insert, disable or remove effects, see Apply a Filter or Effect.

The Wipe Effects#

The Supported Filters and Effects guide lists the properties and default values of every type.

Type	What it hides	Properties
`EffectType.LinearWipe`	The block from one side, along a straight edge	`completion`, `angle`, `feather`
`EffectType.RadialWipe`	A wedge that sweeps around a center	`completion`, `startAngle`, `centerX`, `centerY`, `direction`, `feather`
`EffectType.VenetianBlinds`	A part of each repeating stripe	`completion`, `direction`, `width`, `feather`

Creating the Image Blocks#

We add four copies of one image to the page. Each section below adds its effect to one of these blocks.

// Adds a 360 x 270 image block to the page at a position
val imageUri = defaultBaseUri.buildUpon()
    .appendPath("ly.img.image")
    .appendPath("images")
    .appendPath("sample_1.jpg")
    .build()

fun addImageBlock(
    x: Float,
    y: Float,
): DesignBlock {
    val block = engine.block.create(DesignBlockType.Graphic)
    engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Rect))
    val fill = engine.block.createFill(FillType.Image)
    engine.block.setUri(block = fill, property = "fill/image/imageFileURI", value = imageUri)
    engine.block.setFill(block = block, fill = fill)
    engine.block.setWidth(block = block, value = 360F)
    engine.block.setHeight(block = block, value = 270F)
    engine.block.setPositionX(block = block, value = x)
    engine.block.setPositionY(block = block, value = y)
    engine.block.appendChild(parent = page, child = block)
    return block
}

val linearWipeBlock = addImageBlock(x = 30F, y = 30F)
val radialWipeBlock = addImageBlock(x = 410F, y = 30F)
val venetianBlindsBlock = addImageBlock(x = 30F, y = 320F)
val revealBlock = addImageBlock(x = 410F, y = 320F)

Linear Wipe#

An angle of 90 wipes from the left, and an angle of 0 wipes from the bottom. A completion of 0.5 hides half of the block. feather is the length of the soft edge in design units.

// Hide the left half of the block with a soft edge of 40 design units
val linearWipe = engine.block.createEffect(EffectType.LinearWipe)
engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/angle", value = 90F)
engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/completion", value = 0.5F)
engine.block.setFloat(block = linearWipe, property = "effect/linear_wipe/feather", value = 40F)
engine.block.appendEffect(block = linearWipeBlock, effectBlock = linearWipe)

Radial Wipe and Venetian Blinds#

RadialWipe hides a wedge of the full circle. startAngle is in degrees clockwise from 12 o’clock. centerX and centerY place the center relative to the block size, from 0 to 1. direction is Clockwise, Counterclockwise or Both. Both centers the hidden wedge on the start angle.

// Hide 60% of the circle, sweeping clockwise from 12 o'clock around the block center
val radialWipe = engine.block.createEffect(EffectType.RadialWipe)
engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/completion", value = 0.6F)
engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/startAngle", value = 0F)
engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/centerX", value = 0.5F)
engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/centerY", value = 0.5F)
engine.block.setEnum(block = radialWipe, property = "effect/radial_wipe/direction", value = "Clockwise")
engine.block.setFloat(block = radialWipe, property = "effect/radial_wipe/feather", value = 20F)
engine.block.appendEffect(block = radialWipeBlock, effectBlock = radialWipe)

VenetianBlinds hides a part of each stripe. width is the width of one stripe in design units. direction turns the stripes in degrees, and 0 gives vertical stripes.

// Hide half of each 60 design unit wide stripe, with the stripes at 45 degrees
val venetianBlinds = engine.block.createEffect(EffectType.VenetianBlinds)
engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/completion", value = 0.5F)
engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/direction", value = 45F)
engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/width", value = 60F)
engine.block.setFloat(block = venetianBlinds, property = "effect/venetian_blinds/feather", value = 2F)
engine.block.appendEffect(block = venetianBlindsBlock, effectBlock = venetianBlinds)

Revealing a Block over Time#

Effect properties accept keyframes. Here a linear wipe goes from completion 1 to 0 over the 2 second duration of the block, so the block appears from the right. Keyframe times are relative to the block duration, from 0 to 1. getKeyframes reads the track back. For more about keyframes, see Keyframes.

// Reveal the block over its 2 second duration: all hidden at the start, all shown at the end
engine.block.setDuration(block = revealBlock, duration = 2.0)
val reveal = engine.block.createEffect(EffectType.LinearWipe)
engine.block.appendEffect(block = revealBlock, effectBlock = reveal)
engine.block.setKeyframes(
    block = reveal,
    property = "effect/linear_wipe/completion",
    keyframes = listOf(
        Keyframe(
            time = 0F,
            value = KeyframeValue.Float(1F),
            easing = KeyframeEasing.Preset(AnimationEasingType.EASE_OUT),
        ),
        Keyframe(time = 1F, value = KeyframeValue.Float(0F)),
    ),
)
val revealKeyframes = engine.block.getKeyframes(block = reveal, property = "effect/linear_wipe/completion")
Log.i(TAG, "Completion keyframes: $revealKeyframes")

getFloat returns the static value of completion, not the animated value. To see the animation, set the playback time of the page and export a frame.

Exporting the Result#

We export the page at 0.5 and 1.5 seconds. The three static wipes look the same in both frames. The reveal eases out, so the later frame shows much more of the block than the first.

// Export the page at 0.5 and 1.5 seconds. The reveal block shows more of the image in the later frame.
engine.block.setPlaybackTime(block = page, time = 0.5)
val earlyFramePng = engine.block.export(block = page, mimeType = MimeType.PNG)
engine.block.setPlaybackTime(block = page, time = 1.5)
val lateFramePng = engine.block.export(block = page, mimeType = MimeType.PNG)

API Reference#

Method	Description
`engine.block.create(blockType=DesignBlockType.Graphic)`	Create the graphic block for an image
`engine.block.createShape(type=ShapeType.Rect)`	Create the rect shape of the block
`engine.block.setShape(block=_, shape=_)`	Give the block its shape
`engine.block.createFill(fillType=FillType.Image)`	Create an image fill
`engine.block.setUri(block=_, property="fill/image/imageFileURI", value=_)`	Set the image of the fill
`engine.block.setFill(block=_, fill=_)`	Attach the fill to the block
`engine.block.setWidth(block=_, value=_)`	Set the width of the block
`engine.block.setHeight(block=_, value=_)`	Set the height of the block
`engine.block.setPositionX(block=_, value=_)`	Set the horizontal position of the block
`engine.block.setPositionY(block=_, value=_)`	Set the vertical position of the block
`engine.block.appendChild(parent=_, child=_)`	Add the block to the page
`engine.block.createEffect(type=_)`	Create an effect, for example `EffectType.LinearWipe`
`engine.block.appendEffect(block=_, effectBlock=_)`	Add an effect to the end of the effect list of a block
`engine.block.setFloat(block=_, property="effect/linear_wipe/completion", value=_)`	Set a number property of an effect
`engine.block.setEnum(block=_, property="effect/radial_wipe/direction", value=_)`	Set an option property of an effect
`engine.block.setDuration(block=_, duration=_)`	Set the duration of the block in seconds
`engine.block.setKeyframes(block=_, property="effect/linear_wipe/completion", keyframes=_)`	Animate an effect property
`engine.block.getKeyframes(block=_, property="effect/linear_wipe/completion")`	Read the keyframes of an effect property
`engine.block.setPlaybackTime(block=_, time=_)`	Set the playback time of the page in seconds
`engine.block.export(block=_, mimeType=_)`	Export the page at the current playback time

Next Steps#

Keyframes: animate effect properties over time.
Apply a Filter or Effect: insert, disable and remove effects.
Supported Filters and Effects: look up the properties of every effect type.
Color Effects: remap the colors of a block.
Distortion Effects: move the pixels of a block.