0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
li-zhen166li-zhen166修改图片名称
443f4845创建于 3 天前历史提交

@ohos.graphics.uiEffect (Cascading Effect) (System API)

This module provides basic capabilities to apply an effect, for example, blur, pixel stretch, and brightness, to a component. Effects are classified into filters and visual effects. Effects of the same category can be cascaded in an effect instance of the corresponding category. In actual development, the blur effect can be used for background blurring, and the brightness effect can be used for screen-on display.

  • Filter: applies a filter to a component.
  • VisualEffect: applies a visual effect to a component.

NOTE

  • The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
  • This topic describes only system APIs provided by the module. For details about its public APIs, see ohos.graphics.uiEffect (Cascading Effect).

Modules to Import

import { uiEffect } from "@kit.ArkGraphics2D";

uiEffect.createBrightnessBlender

createBrightnessBlender(param: BrightnessBlenderParam): BrightnessBlender

Creates a BrightnessBlender instance, which can be used to apply the brightness effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
param BrightnessBlenderParam Yes Parameters that implement the brightness effect.

Return value

Type Description
BrightnessBlender BrightnessBlender instance with the brightness effect.

Example

let blender : uiEffect.BrightnessBlender =
  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})

uiEffect.createHdrBrightnessBlender20+

createHdrBrightnessBlender(param: BrightnessBlenderParam): HdrBrightnessBlender

Creates an HdrBrightnessBlender instance to add the HDR brightness effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
param BrightnessBlenderParam Yes Parameters that implement the brightness effect.

Return value

Type Description
HdrBrightnessBlender Returns a blender with the brightness effect (HDR supported).

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D"

let blender : uiEffect.HdrBrightnessBlender =
  uiEffect.createHdrBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})

@Entry
@Component
struct example {
  build() {
    RelativeContainer() {
      Image($r("app.media.screenshot"))
        .width("100%")
        .height("100%")
        .advancedBlendMode(blender)
    }
  }
}

Filter

A class that can apply a filter to a component. Before calling any API in Filter, you must use createFilter to create a Filter instance.

pixelStretch

pixelStretch(stretchSizes: Array<number>, tileMode: TileMode): Filter

Applies the pixel stretch effect onto the component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
stretchSizes Array<number> Yes Ratio based on which the pixels grow towards the top, bottom, left, and right edges. The value range is [-1, 1].
A positive value indicates outward stretching, and the upper, lower, left, and right edges are filled with edge pixels of the specified original image ratio. A negative value indicates inward stretching, but the image size remains unchanged:
The values for the four directions must be all positive or all negative.
tileMode TileMode Yes Pixel tiling mode for pixel stretch.

Return value

Type Description
Filter Filter instance with the pixel stretch effect.

Example

filter.pixelStretch([0.2, 0.2, 0.2, 0.2], uiEffect.TileMode.CLAMP)

waterRipple

waterRipple(progress: number, waveCount: number, x: number, y: number, rippleMode: WaterRippleMode): Filter

Applies the ripple effect onto the component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
progress number Yes Progress of the ripple. The value range is [0, 1].
The closer the value is to 1, the more fully the ripple effect is displayed.
If a value outside this range is provided, no ripple effect will be displayed.
waveCount number Yes Number of ripples that form when the ripple effect. The value range is [1, 3].
The value must be an integer. Ripples will not be displayed if a floating point number or a value outside this range is provided.
x number Yes X coordinate on the screen that marks the center of the ripple when the ripple effect is initially triggered.
The ripples are normalized across the screen, with the coordinates of the upper left corner set to (0, 0) and the upper right corner set to (1, 0).
A negative number indicates that the center of the ripple is located to the left of the screen's center.
y number Yes Y coordinate on the screen that marks the center of the ripple when the ripple effect is initially triggered.
The ripples are normalized across the screen, with the coordinates of the upper left corner set to (0, 0) and the lower left corner set to (0, 1).
A negative number indicates that the center of the ripple is located above the screen's center.
rippleMode WaterRippleMode Yes Scene mode of the ripple effect.

Return value

Type Description
Filter Filter instance with the ripple effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL)

flyInFlyOutEffect

flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter

Applies fly-in and fly-out animations onto the component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
degree number Yes Degree of control over deformation of the fly-in and fly-out animations. The value range is [0, 1].
A value closer to 1 results in more obvious deformation.
If a value outside this range is provided, no fly-in and fly-out animations will be displayed.
flyMode FlyMode Yes Scene mode of the fly-in and fly-out animations.
BOTTOM means that the fly-in and fly-out animations occur from the bottom of the screen, and TOP means that the fly-in and fly-out animations occur from the top of the screen.

Return value

Type Description
Filter Returns a filter with the fly-in and fly-out animations.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP)

distort13+

distort(distortionK: number): Filter

Applies the lens distortion effect onto the component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
distortionK number Yes Distortion coefficient, indicating the degree of lens distortion. The value range is [-1, 1]. A value less than -1 evaluates to the value -1. A value greater than 1 evaluates to the value 1.

Add-Distort.png

The preceding figure shows the rendering results when different distortion coefficients (-1, 0, 0.5, and 1) are applied onto an Image component. A negative distortion value results in a barrel distortion, whereas a positive value results in a pincushion distortion. As the distortion value approaches 0, the intensity of the distortion decreases, and at exactly 0, there is no distortion effect.

Return value

Type Description
Filter Returns a filter with the lens distortion effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

filter.distort(-0.5)

radiusGradientBlur19+

radiusGradientBlur(value: number, options: LinearGradientBlurOptions): Filter

Applies a radial linear gradient blur effect to the component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
value number Yes Blur radius. A larger value indicates a higher blur degree. The value range is [0, 128]. A zero blur radius disables the blur effect. Negative values default to 0, while values above 128 cap at 128.
options LinearGradientBlurOptions Yes Linear gradient parameters, which include fractionStops and direction.

Return value

Type Description
Filter Returns a filter with the radial linear gradient blur effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct RadiusGradientBlurExample {
  @State blurRadiusExample: number = 64
  @State linearGradientBlurOptionsExample: LinearGradientBlurOptions =
    {fractionStops: [[0.0, 0.0], [1.0, 1.0]], direction: GradientDirection.Bottom}

  build() {
    Column() {
      Image($rawfile('test.png'))
        .compositingFilter(uiEffect.createFilter().radiusGradientBlur(this.blurRadiusExample,
          this.linearGradientBlurOptionsExample))
    }
  }
}

bezierWarp20+

bezierWarp(controlPoints: Array<common2D.Point>): Filter

Applies the Bézier curve deformation effect onto a component. This effect applies a closed Bézier curve to the layer boundary to precisely distort and adjust the shape of an image. A Bézier curve consists of four segments that are connected in sequence. Each segment contains one vertex and two tangents.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
controlPoints Array<common2D.Point> Yes 12 Bézier deformation control points. Changing the positions of these control points modifies the shape of the curve forming the edges, thus distorting the image. The control point coordinates are in the 0-1 coordinate system, and the coordinate values can be greater than 1 or less than 0.

Return value

Type Description
Filter Returns a filter with the Bézier curve deformation effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct BezierWarpExample {
  @State valueBezier: Array<common2D.Point> = [
    { x: 0, y: 0 }, { x: 1 / 3, y: 0 }, { x: 2 / 3, y: 0 }, // top edge
    { x: 0.5, y: 0 }, { x: 0.5, y: 1 / 3 }, { x: 1, y: 2 / 3 }, // right edge
    { x: 1, y: 1 }, { x: 2 / 3, y: 1 }, { x: 1 / 3, y: 1 }, // bottom edge
    { x: 0, y: 1 }, { x: 0, y: 2 / 3 }, { x: 0, y: 1 / 3 }] // left edge

  build() {
    Column() {
      Image($rawfile('test.jpg'))
        .foregroundFilter(uiEffect.createFilter().bezierWarp(this.valueBezier))
    }
  }
}

colorGradient20+

colorGradient(colors: Array<Color>, positions: Array<common2D.Point>, strengths: Array<number>, alphaMask?: Mask): Filter

Applies a color gradient effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
colors Array<Color> Yes Color array, which is a gradient of multiple colors. The array length ranges from 0 to 12. The value of each color must be greater than or equal to 0. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
positions Array<common2D.Point> Yes Position array, which is the positions of colors. The array length ranges from 0 to 12. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
strengths Array<number> Yes Strength array, which is the diffusion strengths of colors. The array length ranges from 0 to 12. The value of each strength must be greater than or equal to 0. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
alphaMask Mask No Mask alpha, which is the alpha display mask of colors. If this parameter is not set, the color gradient effect is applied to all component content by default.

Return value

Type Description
Filter Returns a filter with the color gradient effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { common2D, uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct ColorGradientExample {
  @State colorsExample: Array<uiEffect.Color> = [
    {red: 1.0, green: 0.8, blue: 0.5, alpha: 0.8},
    {red: 1.0, green: 1.5, blue: 0.5, alpha: 1.0}
  ]

  @State positionsExample: Array<common2D.Point> = [
    {x: 0.2, y: 0.2},
    {x: 0.8, y: 0.6}]

  @State strengthsExample: Array<number> = [0.3, 0.3]

  build() {
    Column() {
      Row()
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().colorGradient(this.colorsExample, this.positionsExample, this.strengthsExample))
    }
  }
}

contentLight20+

contentLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, displacementMap?: Mask): Filter

Applies a 3D lighting effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
lightPosition common2D.Point3d Yes Position of the light in the component space. [-1, -1, 0] indicates the upper left corner of the component, and [1, 1, 0] indicates the lower right corner of the component. The larger the z-axis component, the farther the light source is from the component plane and the larger the illumination area.
The value range of the x component is [–10, 10], the value range of the y component is [–10, 10], and the value range of the z component is [0, 10]. If the value is out of the range, it will be automatically truncated.
lightColor common2D.Color Yes Light color. The value range of each element is [0, 1]. If the value is out of the range, it will be automatically truncated.
lightIntensity number Yes Light strength. The value range is [0, 1]. A larger value indicates a brighter light source. If the value is out of the range, it will be automatically truncated.
displacementMap Mask No This parameter is reserved for future use.

Return value

Type Description
filter Returns a filter with the light effect on the content.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct Index {
  @State point2: common2D.Point3d = {
    x: 0, y: 0, z: 2
  }
  @State color2: common2D.Color = {
    red: 1,
    green: 1,
    blue: 1,
    alpha: 1
  }
  @State lightIntensity2: number = 1

  build() {
    Column() {
      Stack() {
        Image($r('app.media.man'))
          .width('646px')
          .height('900px')
          .borderRadius(10)
          .foregroundFilter(uiEffect.createFilter().contentLight(this.point2, this.color2, this.lightIntensity2))
      }
      .width('100%')
      .height('55%')
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#555')
  }
}

edgeLight20+

edgeLight(alpha: number, color?: Color, mask?: Mask, bloom?: boolean): Filter

Detects the edge of the component content and adds an edge highlight effect.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
alpha number Yes Specifies the highlight alpha value of the edge. A larger value indicates more obvious edges. The value range is [0, 1]. The value 0 disables the edge highlight effect. Negative values default to 0, while values above 1 cap at 1.
color Color No Highlight color of the edge. If this parameter is not set, the original color of the component content is used by default. If there is a value, the specified color is used. If this parameter is set to a value other than NULL, the alpha value in Color does not take effect, and only the RGB value takes effect.
mask Mask No Specifies the highlight strength of the edge. If this parameter is not set, the edge highlight effect is applied to all component content by default.
bloom boolean No Specifies whether the edge glows. true (default): both the edge highlight and glow effects are applied; false: only the edge highlight effect is applied. If the image size is less than 16 x 16, the edge highlight effect is applied by default, and the glow effect is not applied. In this case, this parameter does not take effect.

Return value

Type Description
Filter Returns a filter with the edge highlight and glow effects.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct EdgeLightExample {
  @State colorExample: uiEffect.Color = {red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0}
  
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.5, 0.5)
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, this.colorExample, this.maskExample, false))
    }
  }
}

displacementDistort20+

displacementDistort(displacementMap: Mask, factor?: [number, number]): Filter

Applies a distortion effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
displacementMap Mask Yes Distortion degree. It is determined by the product of this parameter and factor.
factor [number, number] No Horizontal and vertical distortion degree factors. A larger absolute value indicates a more obvious distortion degree. The recommended value range is [–10.0, 10.0]. If this parameter is not set, the default value 1.0 is used. If this parameter is set to 0, no distortion effect is applied. It is determined by the product of this parameter and mask.

Return value

Type Description
Filter Returns a filter with the distortion effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct DisplacementDistortExample {
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.3, 0.0)
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().displacementDistort(this.maskExample, [5.0, 5.0]))
    }
  }
}

maskDispersion20+

maskDispersion(dispersionMask: Mask, alpha: number, rFactor?: [number, number], gFactor?: [number, number], bFactor?: [number, number]): Filter

Applies a dispersion effect to a component, which is controlled by the displacement map.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
dispersionMask Mask Yes Displacement map, which is used to control the dispersion strength, direction, and alpha value. You are advised to use the displacement map of the PixelMapMask type.
alpha number Yes Alpha value of dispersion. A smaller value makes the object more transparent. The value range is [0, 1.0]. The value 0 means the dispersion effect does not take effect. Negative values default to 0, while values above 1.0 cap at 1.0.
rFactor [number, number] No Basic dispersion offset of the R channel in the X/Y direction. A larger value indicates a more obvious red dispersion effect. The value range in each direction is [-1.0, 1.0]. An offset less than -1.0 evaluates to the value -1.0. A value greater than 1.0 evaluates to the value 1.0.
gFactor [number, number] No Basic dispersion offset of the G channel in the X/Y direction. A larger value indicates a more obvious green dispersion effect. The value range is the same as that of rFactor.
bFactor [number, number] No Basic dispersion offset of the B channel in the X/Y direction. A larger value indicates a more obvious blue dispersion effect. The value range is the same as that of rFactor.

Return value

Type Description
Filter Returns the filter that mounts the dispersion effect controlled by the displacement map.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import {image} from '@kit.ImageKit'
import {common2D, uiEffect} from '@kit.ArkGraphics2D'
import {common} from '@kit.AbilityKit'

@Entry
@Component
struct MaskDispersion {
  @State pixelMap_: PixelMap | null = null
  @State src: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 }
  @State dst: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 }
  @State fillColor: uiEffect.Color = { red: 0, green: 0, blue: 0, alpha: 0 }

  onPageShow(): void {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext
    context.resourceManager.getMediaByName("mask_alpha").then(val => {
      let buffer = val.buffer.slice(0, val.buffer.byteLength)
      let imageSource = image.createImageSource(buffer);
      imageSource.createPixelMap().then(pixelMap => {
        this.pixelMap_ = pixelMap
      })
    })
  }
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().maskDispersion(
          uiEffect.Mask.createPixelMapMask(this.pixelMap_, this.src, this.dst, this.fillColor),
          1.0,
          [0.5, -0.5],
          [0.0, 0.0],
          [-0.5, 0.5]))
    }
  }
}

hdrBrightnessRatio20+

hdrBrightnessRatio(ratio: number): Filter

Applies an HDR brightness effect to a component. Nesting is not recommended. Forcible nesting may cause overexposure.

The brightness effect takes effect only when the HDR rendering pipeline is enabled. In some scenarios, HDR cannot be enabled even if the HDR rendering pipeline is triggered. For example, the device hardware does not support HDR.

The maximum brightness ratio allowed is the value obtained by dividing the maximum brightness of the device by the SDR reference brightness of the device.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
ratio number Yes Brightness ratio. The value range is [1.0, maximum brightness allowed]. Values less than 1.0 default to 1.0. Values equal to 1.0 trigger no processing. Values greater than 1.0 trigger the HDR rendering pipeline. Values above the maximum brightness allowed cap at the maximum.

Return value

Type Description
Filter Returns a filter with the HDR brightness effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

filter.hdrBrightnessRatio(2.0)

maskTransition20+

maskTransition(alphaMask: Mask, factor?: number, inverse?: boolean): Filter

Provides a transition effect based on Mask for the component content.

You are not advised to use this effect when the screen size changes, for example, rotating the screen or opening and closing the foldable screen.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
alphaMask Mask Yes Transition effect area specified by the mask.
factor number No Transition coefficient. The value range is [0.0, 1.0] and defaults to 1.0. A larger value of factor indicates that the image is closer to the page after transition. If the value is out of the range, the value is automatically truncated to [0.0, 1.0].
inverse boolean No Whether to enable reverse transition. true means yes and false (default) means no.

Return value

Type Description
Filter Returns a filter with the transition effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect, common2D } from "@kit.ArkGraphics2D";

@Entry
@Component
struct Index {
  context = this.getUIContext()
  @State alpha: number = 0
  @State enterNewPage:boolean = false
  @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5}
  @State rippleMaskRadius: number = 0.1
  build() {
    Stack() {
      // Page before transition
      Image($r("app.media.before")).width("100%").height("100%")
        if (this.enterNewPage){
          // Page after transition
          Column().width("100%").height("100%").backgroundImage($r("app.media.after"))
            .backgroundFilter(uiEffect.createFilter()
              .maskTransition(
                uiEffect.Mask.createRadialGradientMask(this.rippleMaskCenter, this.rippleMaskRadius,this.rippleMaskRadius, [[1, 0], [1, 1]]),
                this.alpha))
            .onAppear(() => {
              this.context.animateTo({ duration: 1000 }, () => {
                this.rippleMaskRadius = 1.3
              })
              this.context.animateTo({ duration: 800 }, () => {
                this.alpha = 1
              })
            })
        }
    }.borderWidth(2)
    .onClick(()=>{
      this.enterNewPage=!this.enterNewPage;
      if (this.enterNewPage) {
        this.alpha=0;
        this.rippleMaskRadius=0.1;
      }
    })
  }
}

directionLight20+

directionLight(direction: common2D.Point3d, color: Color, intensity: number, mask?: Mask, factor?: number): Filter

Provides a lighting effect based on Mask and parallel light for the component content.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
direction common2D.Point3d Yes Direction of the directional light.
color Color Yes Light color.
intensity number Yes Light intensity. The value must be a non-negative number.
mask Mask No Displacement map, which is used to describe the three-dimensional details of the two-dimensional image surface. The normal map or height map is used to enhance the local details and lighting reflection effect. If the input is a height map, the factor parameter must be used together. By default, this parameter is left empty, and the lighting effect of a plane without details is displayed globally.
factor number No Sampling scaling coefficient. The default value is null, indicating that mask is set to the normal map for sampling. If the value is not null, mask is set to the height map for sampling. The actual height value is the product of the sampling value of mask and factor.

Return value

Type Description
Filter Returns the filter that mounts the lighting effect controlled by the displacement map.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect, common2D } from "@kit.ArkGraphics2D";

@Entry
@Component
struct Index {
  @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5}
  @State rippleMaskRadius: number = 0.0
  @State rippleMaskWidth: number = 0.0
  @State color: Color = Color.Transparent

  build() {
    Column() {
      RelativeContainer() {
        Image($r("app.media.back")).width("100%").height("100%")
        Stack()
          .width("100%")
          .height("100%")
          .backgroundColor(this.color)
          .backgroundFilter(uiEffect.createFilter()
            .directionLight(
              {x:0, y:0, z:-1}, {red:2.0, green:2.0, blue:2.0, alpha:1.0}, 0.5,
              uiEffect.Mask.createRippleMask(this.rippleMaskCenter, this.rippleMaskRadius, this.rippleMaskWidth, 0.0)
              ))
          .onClick(() => {
            this.getUIContext().animateTo({duration: 1000}, () => {
              this.rippleMaskWidth = 1.0;
            })
          })
      }
    }.alignItems(HorizontalAlign.Center).borderWidth(2)
  }
}

variableRadiusBlur20+

variableRadiusBlur(radius: number, radiusMap: Mask): Filter

Provides a gradient blur effect based on Mask for the component content.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
radius number Yes Maximum blur radius. A larger value indicates a higher blur degree. The value range is [0, 128]. A zero blur radius disables the blur effect. Negative values default to 0, while values above 128 cap at 128.
radiusMap Mask Yes Mask object that indicates the blur degree.

Return value

Type Description
Filter Returns the filter object of the current effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D";

@Entry
@Component
struct VariableRadiusBlurExample {
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.1)

  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().variableRadiusBlur(64, this.maskExample))
    }
  }
}

TileMode

Enumerates the pixel tiling modes.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Name Value Description
CLAMP 0 Clamp.
REPEAT 1 Repeat.
MIRROR 2 Mirror.
DECAL 3 Decal.

WaterRippleMode

Enumerates the scene modes of the ripple effect.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Name Value Description
SMALL2MEDIUM_RECV 0 A phone taps against a 2-in-1 device (receiver).
SMALL2MEDIUM_SEND 1 A phone taps against a 2-in-1 device (sender).
SMALL2SMALL 2 A phone taps against another phone.
MINI_RECV17+ 3 A 2-in-1 device shares data (keyboard and mouse) with other devices.

FlyMode

Enumerates the scene modes of fly-in and fly-out animations.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Name Value Description
BOTTOM 0 Fly-in and fly-out animations occur from the bottom of the screen.
TOP 1 Fly-in and fly-out animations occur from the top of the screen.

VisualEffect

A class that can apply a visual effect to a component. Before calling any API in VisualEffect, you must use createEffect to create a VisualEffect instance.

backgroundColorBlender

backgroundColorBlender(blender: BrightnessBlender): VisualEffect

Applies a blender to the component to change the background color of the component. The change effect is determined by the input. Currently, only the brightness blender is supported.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
blender BrightnessBlender Yes Blender used to change the background color.

Return value

Type Description
VisualEffect Returns a VisualEffect object with the background color change effect.

Example

let blender : uiEffect.BrightnessBlender =
  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})
visualEffect.backgroundColorBlender(blender)

borderLight20+

borderLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, borderWidth: number): VisualEffect

Adds a 3D lighting effect to the border of a rounded rectangle component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
lightPosition common2D.Point3d Yes 3D position of the light in the component space. [-1, -1, 0] indicates the upper left corner of the component, and [1, 1, 0] indicates the lower right corner of the component. The larger the z-axis component, the farther the light source is from the component plane and the larger the illumination area.
The value range of the x component is [–10, 10], the value range of the y component is [–10, 10], and the value range of the z component is [0, 10]. If the value is out of the range, it will be automatically truncated.
lightColor common2D.Color Yes Light color. The value range of each element is [0, 1]. If the value is out of the range, it will be automatically truncated.
lightIntensity number Yes Light strength. The value range is [0, 1]. A larger value indicates a brighter light source. If the value is out of the range, it will be automatically truncated.
borderWidth number Yes Lighting width of the component border. The value range is [0.0, 30.0]. If the value is out of the range, it will be automatically truncated. The value 0.0 means that the component border is not lightened. A larger value indicates a wider lightened area.

Return value

Type Description
VisualEffect Returns a VisualEffect object with the lighting effect on the border.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct Index {
  @State point1:common2D.Point3d = {
    x:0,y:0,z:2
  }
  @State color1:common2D.Color = {
    red:1,green:1,blue:1,alpha:1
  }
  @State lightIntensity1:number = 1
  @State borderWidth:number = 20

  build() {
    Column() {
      Stack() {
        Image($r('app.media.man'))
          .width('646px')
          .height('900px')
          .borderRadius(10)
        Column()
          .width('646px')
          .height('900px')
          .borderRadius(10)
          .visualEffect(uiEffect.createEffect().borderLight(this.point1, this.color1, this.lightIntensity1,
            this.borderWidth))
      }
      .width('100%')
      .height('55%')
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#555')
  }
}

colorGradient20+

colorGradient(colors: Array<Color>, positions: Array<common2D.Point>, strengths: Array<number>, alphaMask?: Mask): VisualEffect

Applies a color gradient effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
colors Array<Color> Yes Color array, which is used to implement multi-color gradient. The array length ranges from 0 to 12. Each color value is greater than or equal to 0. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
positions Array<common2D.Point> Yes Position array, which is the positions of colors. The array length ranges from 0 to 12. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
strengths Array<number> Yes Strength array, which is the strengths of colors. The array length ranges from 0 to 12. Each strength value is greater than or equal to 0. If the array length is 0 or greater than 12, or the lengths of the colors, positions, and strengths arrays are inconsistent, no color gradient effect is displayed.
alphaMask Mask No Alpha of the mask corresponding to each color. If this parameter is not set, the alpha of the color gradient effect is determined only by the colors parameter.

Return value

Type Description
VisualEffect Returns a VisualEffect object with the color gradient effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { common2D, uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct ColorGradientExample {
  build() {
    Stack() {
      Stack() {}
      .visualEffect(uiEffect.createEffect()
        .colorGradient(
          [
            {red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0},
            {red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0},
            {red: 0.0, green: 0.0, blue: 1.0, alpha: 1.0},
            {red: 1.0, green: 1.0, blue: 1.0, alpha: 1.0},
          ],
          [
            {x: 0.1, y: 0.1},
            {x: 0.1, y: 0.9},
            {x: 0.9, y: 0.1},
            {x: 0.9, y: 0.9},
          ],
          [12.4, 7.8, 7.8, 10.0],
          uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.1)
        )
      )
      .width("1024px")
      .height("1024px")
    }
    .width("100%")
    .height("100%")
  }
}

liquidMaterial22+

liquidMaterial(param: LiquidMaterialEffectParam, useEffectMask: Mask, distortMask?: Mask, brightnessParam?: BrightnessParam): VisualEffect

Applies a material effect to a component.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
param LiquidMaterialEffectParam Yes Relevant variables required for the material, which are used to control material display. This parameter includes material toggle, refraction coefficient, reflection coefficient, and distortion coefficient.
useEffectMask Mask Yes Whether to use the blur cache. A Mask instance created with createUseEffectMask(true) enables the blur cache; a Mask instance created with createUseEffectMask(false) disables the blur cache.
distortMask Mask No Distortion texture required for the material distortion effect, which is determined by the image texture used for creating the Mask instance with pixelMap.
When the distortion coefficient of the material is not 0, a texture must be preset for material distortion; otherwise, no distortion effect is applied.
When the distortion coefficient of the material is 0 or this parameter is not specified, no distortion effect is applied.
brightnessParam BrightnessParam No Adds a brightness effect to the material. The brightness effect is disabled by default.

Return value

Type Description
VisualEffect Returns a VisualEffect object with the material effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from '@kit.ArkGraphics2D';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
      enable: true,
      distortProgress : this.distortProgress,
      rippleProgress: this.rippleProgress,
      distortFactor: this.distortFactor,
      materialFactor : this.materialFactor,
      refractionFactor : this.refractionFactor,
      reflectionFactor: this.reflectionFactor,
      tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
      ripplePosition: undefined,
    },
      uiEffect.Mask.createUseEffectMask(true),
      );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat)
    .width("100%").height("100%").align(Alignment.Center)
  }
}

Blender13+

type Blender = BrightnessBlender | HdrBrightnessBlender

Defines the blender type, which is used to describe blending effects.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Type Description
BrightnessBlender Blender with a brightening effect.
HdrBrightnessBlender20+ Blender with the brightness effect (HDR supported).

BrightnessBlender

A blender that can apply the brightness effect to a component. Before calling any API in BrightnessBlender, you must use createBrightnessBlender to create a BrightnessBlender instance.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Name Type Read Only Optional Description
cubicRate number No No Cubic coefficient for grayscale adjustment.
The value range is [-20, 20].
quadraticRate number No No Quadratic coefficient for grayscale adjustment.
The value range is [-20, 20].
linearRate number No No Linear coefficient for grayscale adjustment.
The value range is [-20, 20].
degree number No No Grayscale adjustment ratio.
The value range is [-20, 20].
saturation number No No Reference saturation for the brightness effect.
The value range is [0, 20].
positiveCoefficient [number, number, number] No No RGB positive adjustment parameter based on the reference saturation.
The value range of each number is [-20, 20].
negativeCoefficient [number, number, number] No No RGB negative adjustment parameter based on the reference saturation.
The value range of each number is [-20, 20].
fraction number No No Blending ratio of the brightness effect.
The value range is [0, 1]. A value beyond the boundary will be automatically truncated during implementation.

HdrBrightnessBlender20+

HDR brightness blender (inherited from BrightnessBlender), which is used to add the brightness effect to a specified component. Before calling any API in HdrBrightnessBlender, you must use createHdrBrightnessBlender to create a HdrBrightnessBlender instance.

For details about the parameters of this blender, see BrightnessBlender.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Color20+

Describes a color in RGBA format.

System capability: SystemCapability.Graphics.Drawing

Name Type Read Only Optional Description
red number Yes Yes R component (red) of the color. The value must be greater than or equal to 0. Negative values are invalid.
green number Yes Yes G component (green) of the color. The value must be greater than or equal to 0. Negative values are invalid.
blue number Yes Yes B component (blue) of the color. The value must be greater than or equal to 0. Negative values are invalid.
alpha number Yes Yes A component (alpha) of the color. The value must be greater than or equal to 0. Negative values are invalid.

LiquidMaterialEffectParam22+

Describes the parameters of the material and their respective purposes.

System capability: SystemCapability.Graphics.Drawing

Name Type Read Only Optional Description
enable boolean No No Whether to enable the material effect. true means yes; false otherwise.
distortProgress number No No Distortion effect progress. The value range is [0, 1]. Values less than 0 are clamped to 0, and values greater than 1 are clamped to 1. A value of 0 indicates the start of distortion, while 1 indicates the end of distortion.
distortFactor number No No Distortion effect coefficient. The value is greater than or equal to 0. A value less than 0 indicates no distortion effect.
rippleProgress number No No Ripple effect progress. The value is greater than or equal to 0. A value less than 0 indicates no ripple effect.
ripplePosition Array<[number, number]> No Yes Positions where the ripple effect takes effect. Each position in the array contains the x and y dimensions. A maximum of 10 position coordinates are supported. If more than 10 position coordinates are passed in, this parameter becomes invalid.
refractionFactor number No No Refraction effect coefficient. The value range is [0, 10]. Values less than 0 are clamped to 0, and values greater than 10 are clamped to 10. A value of 0 indicates no refraction effect; the higher the value, the stronger the refraction intensity.
reflectionFactor number No No Reflection coefficient. The value range is [0, 10]. Values less than 0 are clamped to 0, and values greater than 10 are clamped to 10. A value of 0 indicates no reflection effect; the higher the value, the stronger the reflection intensity.
materialFactor number No No Material coefficient. The value range is [0, 1]. Values less than 0 are clamped to 0, and values greater than 1 are clamped to 1. A value of 0 indicates no material effect, with the area filled with the tint color; the higher the value, the more prominent the material effect.
tintColor [number, number, number, number] No No Tint color overlaid on the material, where the four numbers correspond to RGBA respectively. The value range is [0, 1]. Values less than 0 are clamped to 0, and values greater than 1 are clamped to 1.

BrightnessParam22+

Describes the material brightness parameters.

System capability: SystemCapability.Graphics.Drawing

Name Type Read Only Optional Description
rate number No No Linear coefficient for gray adjustment. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the stronger the grayscale adjustment effect.
lightUpDegree number No No Grayscale adjustment ratio. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the stronger the grayscale adjustment effect.
cubicCoeff number No No Cubic coefficient for grayscale adjustment. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the stronger the grayscale adjustment effect.
quadCoeff number No No Quadratic coefficient for grayscale adjustment. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the stronger the grayscale adjustment effect.
saturation number No No Reference saturation for the brightness effect. The value range is [0, 1]. Values less than 0 are clamped to 0, and values greater than 1 are clamped to 1. The higher the value, the higher the reference saturation.
posRgb [number, number, number] No No Positive adjustment coefficient based on the reference saturation. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the higher the saturation.
negRgb [number, number, number] No No Negative adjustment coefficient based on the reference saturation. The value range is [-1, 1]. Values less than -1 are clamped to -1, and values greater than 1 are clamped to 1. The higher the value, the lower the saturation.
fraction number No No Blending ratio of the brightness effect. The value range is [0, 1]. Values less than 0 are clamped to 0, and values greater than 1 are clamped to 1. The higher the value, the weaker the brightness effect.

Mask20+

Mask effect class, which is used as the input of Filter and VisualEffect.

createRippleMask20+

static createRippleMask(center: common2D.Point, radius: number, width: number, offset?: number): Mask

Creates a Mask instance of the ripple effect by specifying the center position, radius, and width of the ripple. The effect is determined by the input parameters.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
center common2D.Point Yes Sets the position of the ripple center on the component. [0, 0] indicates the upper left corner of the component, and [1, 1] indicates the lower right corner of the component.
The value range is [-10, 10]. A value beyond the boundary will be automatically truncated during implementation.
radius number Yes Sets the ripple radius. The radius of 1 is equal to the component height.
The value range is [0, 10]. A value beyond the boundary will be automatically truncated during implementation.
width number Yes Sets the ripple width.
The value range is [0, 10]. A value beyond the boundary will be automatically truncated during implementation.
offset number No Sets the offset of the ripple peak position.
The default value is 0, indicating that the ripple peak is in the center of the ripple ring.
The value -1.0 indicates that the ripple peak is at the innermost of the ripple ring.
The value 1.0 indicates that the ripple peak is at the outermost of the ripple ring.
The value range is [-1, 1]. A value beyond the boundary will be automatically truncated during implementation.

Return value

Type Description
Mask Returns a mask with the ripple mask effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

  let mask = uiEffect.Mask.createRippleMask({x:0.5, y:1.0}, 0.5, 0.3, 0.0);

createPixelMapMask20+

static createPixelMapMask(pixelMap: image.PixelMap, srcRect: common2D.Rect, dstRect: common2D.Rect, fillColor?: Color): Mask

Creates a Mask instance with the scaling effect based on the drawing area of the pixelMap, drawing area of the mount node, and color of the area outside the drawing area. The effect is determined by the input parameters.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
pixelMap image.PixelMap Yes PixelMap instance created by the image module. It can be obtained through image decoding or direct creation. For details, see Image Overview.
srcRect common2D.Rect Yes Area to be drawn on the pixelMap. The leftmost and topmost positions of the image correspond to position 0, and the rightmost and bottommost positions correspond to position 1. The value of a right position must be greater than that of a left position, and the value of a bottom position must be greater than that of a top position.
dstRect common2D.Rect Yes Area to be drawn on the node where the mask is mounted on the pixelMap. The leftmost and topmost positions of the node correspond to position 0, and the rightmost and bottommost positions correspond to position 1. The value of a right position must be greater than that of a left position, and the value of a bottom position must be greater than that of a top position.
fillColor Color No Color of the area outside the pixelMap drawing area on the node. The value range of each element is [0, 1]. The default value is transparent. Negative values default to 0 and values above 1 cap at 1.

Return value

Type Description
Mask Returns a mask with the pixelMap scaling effect.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { image } from "@kit.ImageKit";
import { uiEffect, common2D } from "@kit.ArkGraphics2D";
import { BusinessError } from '@kit.BasicServicesKit'

const color = new ArrayBuffer(96);
let opts : image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  let srcRect : common2D.Rect = {
    left: 0,
    top: 0,
    right: 1,
    bottom: 1
  }
  let dstRect : common2D.Rect = {
    left: 0,
    top: 0,
    right: 1,
    bottom: 1
  }
  let fillColor : uiEffect.Color = {
    red: 0,
    green: 0,
    blue: 0,
    alpha: 1
  }
  let mask = uiEffect.Mask.createPixelMapMask(pixelMap, srcRect, dstRect, fillColor);
}).catch((error: BusinessError)=>{
  console.error('Failed to create pixelmap. code is ${error.code}, message is ${error.message}');
})

createPixelMapMask22+

static createPixelMapMask(pixelMap: image.PixelMap): Mask

Creates a Mask instance using the input pixelMap. This API does not perform scaling on the passed pixelMap.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
pixelMap image.PixelMap Yes PixelMap instance created by the image module. It can be obtained through image decoding or direct creation. For details, see Image Overview.

Return value

Type Description
Mask Returns a mask with pixelMap.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;
  @State pixelMapDistort: image.PixelMap | undefined = this.getPixelMap();

  private getPixelMap(): image.PixelMap | undefined {
    try {
      let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
      // this path should be created in local
      const path: string = context.resourceDir + "/perlin_worley_noise_3d_64.bmp";
      const imageSource: image.ImageSource = image.createImageSource(path);
      if (!imageSource) {
        return undefined;
      }
      const pixelMap: image.PixelMap = imageSource.createPixelMapSync();
      imageSource.release();
      return pixelMap;
    } catch (err) {
      return undefined;
    }
  }

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
      enable: true,
      distortProgress : this.distortProgress,
      rippleProgress: this.rippleProgress,
      distortFactor: this.distortFactor,
      materialFactor : this.materialFactor,
      refractionFactor : this.refractionFactor,
      reflectionFactor: this.reflectionFactor,
      tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
      ripplePosition: undefined,
    },
      uiEffect.Mask.createUseEffectMask(true),
      uiEffect.Mask.createPixelMapMask (this.pixelMapDistort), // Example of using createImageMask.
      );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat) // the image should be created in local
    .width("100%").height("100%").align(Alignment.Center)
  }
}

createRadialGradientMask20+

static createRadialGradientMask(center: common2D.Point, radiusX: number, radiusY: number, values: Array<[number, number]>): Mask

Creates a Mask instance of the ellipse effect by specifying the center position, major axis, minor axis, and shape parameters. The effect is determined by the input parameters.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
center common2D.Point Yes Center of the ellipse. [0, 0] indicates the upper left corner of the component, and [1, 1] indicates the lower right corner of the component.
The value range is [-10, 10]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
radiusX number Yes Major axis of the ellipse. The radius of 1 equals the height of the component.
The value range is [0, 10]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
radiusY number Yes Minor axis of the ellipse. The radius of 1 equals the height of the component.
The value range is [0, 10]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
values Array<[number, number]> Yes A binary array stored in the array, representing a gradient: [RGBA color, position]. The four channels of the RGBA color use the same value, which can be considered as a grayscale value. The position indicates the distribution position of the RGBA color when the position is outward along the radial direction. The value range of the RGBA color and position is [0, 1]. The value can be a floating point number. Negative values default to 0 and values above 1 cap at 1.
The position parameter values must be strictly increasing. The number of binary arrays in the array must be greater than or equal to 2. The elements in the binary array cannot be empty. Otherwise, the ellipse distribution effect does not take effect.

Return value

Type Description
Mask Returns the grayscale mask of the radial distribution effect of the ellipse shape.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from '@kit.ArkGraphics2D'
// values: [[1.0, 0.5], [1.0, 1.0]] => color0: 1.0; color1: 1.0; position0: 0.5; position1: 1.0
let mask = uiEffect.Mask.createRadialGradientMask({x: 0.0, y: 0.0}, 0.5, 0.5, [[1.0, 0.5], [1.0, 1.0]]);
@Entry
@Component
struct RadialGradientMaskExample {
  build() {
    Stack() {
      Image($rawfile('test.jpg'))
      Column()
        .width('100%')
        .height('100%')
        // Use the mask as the input parameter of the filter to implement the corresponding effect. The mask is a quarter circle ring in the upper left corner of the screen.
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask))
    }
  }
}

createWaveGradientMask20+

static createWaveGradientMask(center: common2D.Point, width: number, propagationRadius: number, blurRadius: number, turbulenceStrength?: number): Mask

Creates a Mask instance of the single-wavelength effect by specifying the center position and single-wavelength parameters.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
center common2D.Point Yes Center of the single-wavelength source. [0, 0] indicates the upper left corner of the component, and [1, 1] indicates the lower right corner of the component.
The value range is [-10, 10]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
width number Yes Width of a single-wavelength ring.
The value range is [0, 5]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
propagationRadius number Yes Outer diameter of the diffusion of a single-wavelength ring.
The value range is [0, 10]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
blurRadius number Yes Outer diameter of the blur of a single-wavelength ring. If the blur radius is 0, the ring is solid. Otherwise, the ring is dotted.
The value range is [0, 5]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.
turbulenceStrength number No Turbulence strength of a single-wavelength ring. The default value is 0. If the strength is 0, the ring is regular. Otherwise, the ring edge is distorted due to turbulence.
The value range is [-1, 1]. The value can be a floating point number. A value beyond the boundary will be automatically truncated during implementation.

Return value

Type Description
Mask Returns the grayscale mask of the single ripple shape.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from "@kit.ArkGraphics2D";
// center: [0.5, 0.5]; width: 0.01; propagationRadius: 0.5; blurRadius: 0.1; turbulenceStrength: 0.1
let mask = uiEffect.Mask.createWaveGradientMask({x: 0.5, y: 0.5}, 0.01, 0.5, 0.1, 0.1);
@Entry
@Component
struct WaveGradientMaskExample {
  build() {
    Stack() {
      Image($rawfile('test.jpg'))
      Column()
        .width('100%')
        .height('100%')
        // Use the mask as the filter parameter to implement the ripple effect that spreads from the center of the screen.
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask))
    }
  }
}

createUseEffectMask22+

static createUseEffectMask(useEffect: boolean): Mask

Creates a use effect Mask instance and sets whether it enables the blur cache.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Parameters

Name Type Mandatory Description
useEffect boolean Yes Whether to enable the blur cache. true means the blur cache is enabled and the blur effect is displayed normally; false means the opposite.

Return value

Type Description
Mask Returns a mask indicating whether to enable the blur cache.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed. A non-system application calls a system API.

Example

import { uiEffect } from '@kit.ArkGraphics2D';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
        enable: true,
        distortProgress : this.distortProgress,
        rippleProgress: this.rippleProgress,
        distortFactor: this.distortFactor,
        materialFactor : this.materialFactor,
        refractionFactor : this.refractionFactor,
        reflectionFactor: this.reflectionFactor,
        tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
        ripplePosition: undefined,
      },
      uiEffect.Mask.createUseEffectMask(true), // Example of using useEffectMask.
    );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat)
    .width("100%").height("100%").align(Alignment.Center)
  }
}

BrightnessBlenderParam

Describes the parameters used for the brightness blender.

System capability: SystemCapability.Graphics.Drawing

System API: This is a system API.

Name Type Read Only Optional Description
cubicRate number No No Cubic coefficient for grayscale adjustment.
The value range is [-20, 20].
quadraticRate number No No Quadratic coefficient for grayscale adjustment.
The value range is [-20, 20].
linearRate number No No Linear coefficient for grayscale adjustment.
The value range is [-20, 20].
degree number No No Grayscale adjustment ratio.
The value range is [-20, 20].
saturation number No No Reference saturation for the brightness effect.
The value range is [0, 20].
positiveCoefficient [number, number, number] No No RGB positive adjustment parameter based on the reference saturation.
The value range of each number is [-20, 20].
negativeCoefficient [number, number, number] No No RGB negative adjustment parameter based on the reference saturation.
The value range of each number is [-20, 20].
fraction number No No Blending ratio of the brightness effect.
The value range is [0, 1]. A value beyond the boundary will be automatically truncated during implementation.