1# @ohos.graphics.uiEffect (Cascading Effect) (System API) 2 3The uiEffect 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. 4 5- [Filter](#filter): applies a filter to a component. 6- [VisualEffect](#visualeffect): applies a visual effect to a component. 7 8> **NOTE** 9> 10> - 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. 11> - This topic describes only system APIs provided by the module. For details about its public APIs, see [ohos.graphics.uiEffect (Cascading Effect)](js-apis-uiEffect.md). 12 13## Modules to Import 14 15```ts 16import { uiEffect } from "@kit.ArkGraphics2D"; 17``` 18## uiEffect.createBrightnessBlender 19createBrightnessBlender(param: BrightnessBlenderParam): BrightnessBlender 20 21Creates a **BrightnessBlender** instance, which can be used to apply the brightness effect to a component. 22 23**System capability**: SystemCapability.Graphics.Drawing 24 25**System API**: This is a system API. 26 27**Parameters** 28| Name | Type | Mandatory| Description | 29| ------ | ------------------------------------------------- | ---- | --------------------------- | 30| param | [BrightnessBlenderParam](#brightnessblenderparam) | Yes | Parameters that implement the brightness effect.| 31 32**Return value** 33 34| Type | Description | 35| ---------------------------------------- | ----------------------- | 36| [BrightnessBlender ](#brightnessblender) | **BrightnessBlender** instance with the brightness effect.| 37 38**Example** 39 40```ts 41let blender : uiEffect.BrightnessBlender = 42 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 43 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 44``` 45 46## Filter 47A class that can apply a filter to a component. Before calling any API in **Filter**, you must use [createFilter](js-apis-uiEffect.md#uieffectcreatefilter) to create a **Filter** instance. 48 49### pixelStretch 50pixelStretch(stretchSizes: Array\<number\>, tileMode: TileMode): Filter 51 52Applies the pixel stretch effect to the component. 53 54**System capability**: SystemCapability.Graphics.Drawing 55 56**System API**: This is a system API. 57 58**Parameters** 59| Name | Type | Mandatory| Description | 60| ------------- | --------------------- | ---- | ------------------------- | 61| 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].<br>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:<br>The values for the four directions must be all positive or all negative.| 62| tileMode | [TileMode](#tilemode) | Yes | Pixel tiling mode for pixel stretch.| 63 64 65**Return value** 66 67| Type | Description | 68| ----------------- | --------------------------------- | 69| [Filter](#filter) | **Filter** instance with the pixel stretch effect.| 70 71**Example** 72 73```ts 74filter.pixelStretch([0.2, 0.2, 0.2, 0.2], uiEffect.TileMode.CLAMP) 75``` 76 77### waterRipple 78waterRipple(progress: number, waveCount: number, x: number, y: number, rippleMode: WaterRippleMode): Filter 79 80Applies the ripple effect to the component. 81 82**System capability**: SystemCapability.Graphics.Drawing 83 84**System API**: This is a system API. 85 86**Parameters** 87| Name | Type | Mandatory| Description | 88| ------------- | --------------------- | ---- | ------------------------- | 89| progress | number | Yes | Progress of the ripple. The value range is [0, 1].<br>The closer the value is to 1, the more fully the ripple effect is displayed.<br>If a value outside this range is provided, no ripple effect will be displayed.| 90| waveCount | number | Yes | Number of ripples that form when the ripple effect. The value range is [1, 3].<br>The value must be an integer. Ripples will not be displayed if a floating point number or a value outside this range is provided.| 91| x | number | Yes | X coordinate on the screen that marks the center of the ripple when the ripple effect is initially triggered.<br>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).<br>A negative number indicates that the center of the ripple is located to the left of the screen's center.| 92| y | number | Yes | Y coordinate on the screen that marks the center of the ripple when the ripple effect is initially triggered.<br>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).<br>A negative number indicates that the center of the ripple is located above the screen's center.| 93| rippleMode | [WaterRippleMode](#waterripplemode) | Yes | Scene mode of the ripple effect.| 94 95 96**Return value** 97 98| Type | Description | 99| ----------------- | --------------------------------- | 100| [Filter](#filter) | **Filter** instance with the ripple effect.| 101 102**Example** 103 104```ts 105filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL) 106``` 107 108### flyInFlyOutEffect 109flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter 110 111Adds fly-in and fly-out animations to the component. 112 113**System capability**: SystemCapability.Graphics.Drawing 114 115**System API**: This is a system API. 116 117**Parameters** 118| Name | Type | Mandatory| Description | 119| ------------- | --------------------- | ---- | ------------------------- | 120| degree | number | Yes | Degree of control over deformation of the fly-in and fly-out animations. The value range is [0, 1].<br>A value closer to 1 results in more obvious deformation.<br>If a value outside this range is provided, no fly-in and fly-out animations will be displayed.| 121| flyMode | [FlyMode](#flymode) | Yes | Scene mode of the fly-in and fly-out animations.<br>**BOTTOM** means that the fly-in and fly-out animations occur from the bottom of the screen,<br>and **TOP** means that the fly-in and fly-out animations occur from the top of the screen.| 122 123 124**Return value** 125 126| Type | Description | 127| ----------------- | --------------------------------- | 128| [Filter](#filter) | **Filter** instance with the fly-in and fly-out animations.| 129 130**Example** 131 132```ts 133filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP) 134``` 135 136## TileMode 137Enumerates the pixel tiling modes. 138 139**System capability**: SystemCapability.Graphics.Drawing 140 141**System API**: This is a system API. 142 143| Name | Value| Description| 144| ------ | - | ---- | 145| CLAMP | 0 | Clamp.| 146| REPEAT | 1 | Repeat.| 147| MIRROR | 2 | Mirror.| 148| DECAL | 3 | Decal.| 149 150## WaterRippleMode 151Enumerates the scene modes of the ripple effect. 152 153**System capability**: SystemCapability.Graphics.Drawing 154 155**System API**: This is a system API. 156 157| Name | Value| Description| 158| ------ | - | ---- | 159| SMALL2MEDIUM_RECV | 0 | A phone taps against a 2-in-1 device (receiver).| 160| SMALL2MEDIUM_SEND | 1 | A phone taps against a 2-in-1 device (sender).| 161| SMALL2SMALL | 2 | A phone taps against another phone.| 162 163## FlyMode 164Enumerates the scene modes of fly-in and fly-out animations. 165 166**System capability**: SystemCapability.Graphics.Drawing 167 168**System API**: This is a system API. 169 170| Name | Value| Description| 171| ------ | - | ---- | 172| BOTTOM | 0 | Fly-in and fly-out animations occur from the bottom of the screen.| 173| TOP | 1 | Fly-in and fly-out animations occur from the top of the screen.| 174 175## VisualEffect 176A class that can apply a visual effect to a component. Before calling any API in **VisualEffect**, you must use [createEffect](js-apis-uiEffect.md#uieffectcreateeffect) to create a **VisualEffect** instance. 177 178### backgroundColorBlender 179backgroundColorBlender(blender: BrightnessBlender): VisualEffect 180 181Applies 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. 182 183**System capability**: SystemCapability.Graphics.Drawing 184 185**System API**: This is a system API. 186 187**Parameters** 188| Name | Type | Mandatory| Description | 189| ------- | ---------------------------------------- | ---- | ------------------------- | 190| blender | [BrightnessBlender](#brightnessblender) | Yes | Blender used to change the background color.| 191 192**Return value** 193 194| Type | Description | 195| ----------------------------- | ------------------------------------------------- | 196| [VisualEffect](#visualeffect) | **VisualEffect** instance with the background color change effect.| 197 198**Example** 199 200```ts 201let blender : uiEffect.BrightnessBlender = 202 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 203 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 204visualEffect.backgroundColorBlender(blender) 205``` 206 207## Blender<sup>13+</sup> 208 209type Blender = BrightnessBlender 210 211Defines the blender type, which is used to describe blending effects. 212 213**System capability**: SystemCapability.Graphics.Drawing 214 215**System API**: This is a system API. 216 217| Type | Description | 218| ----------------------------- | ------------------------------------------------- | 219| [BrightnessBlender](#brightnessblender) | Blender with a brightening effect.| 220 221## BrightnessBlender 222A blender that can apply the brightness effect to a component. Before calling any API in **BrightnessBlender**, you must use [createBrightnessBlender](#uieffectcreatebrightnessblender) to create a **BrightnessBlender** instance. 223 224**System capability**: SystemCapability.Graphics.Drawing 225 226**System API**: This is a system API. 227 228| Name | Type | Read Only| Optional| Description | 229| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 230| cubicRate | number | No | No | Third-order coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 231| quadraticRate | number | No | No | Second-order coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 232| linearRate | number | No | No | Linear coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 233| degree | number | No | No | Grayscale adjustment ratio.<br>The value range is [-20, 20]. | 234| saturation | number | No | No | Reference saturation for the brightness effect.<br>The value range is [0, 20]. | 235| positiveCoefficient | [number, number, number] | No | No | RGB positive adjustment parameter based on the reference saturation.<br>The value range of each number is [-20, 20].| 236| negativeCoefficient | [number, number, number] | No | No | RGB negative adjustment parameter based on the reference saturation.<br>The value range of each number is [-20, 20].| 237| fraction | number | No | No | Blending ratio of the brightness effect.<br>The value range is [0, 1]. A value beyond the boundary will be automatically truncated during implementation. | 238 239## BrightnessBlenderParam 240Describes the parameters used for the brightness blender. 241 242**System capability**: SystemCapability.Graphics.Drawing 243 244**System API**: This is a system API. 245 246| Name | Type | Read Only| Optional| Description | 247| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 248| cubicRate | number | No | No | Third-order coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 249| quadraticRate | number | No | No | Second-order coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 250| linearRate | number | No | No | Linear coefficient for grayscale adjustment.<br>The value range is [-20, 20]. | 251| degree | number | No | No | Grayscale adjustment ratio.<br>The value range is [-20, 20]. | 252| saturation | number | No | No | Reference saturation for the brightness effect.<br>The value range is [0, 20]. | 253| positiveCoefficient | [number, number, number] | No | No | RGB positive adjustment parameter based on the reference saturation.<br>The value range of each number is [-20, 20].| 254| negativeCoefficient | [number, number, number] | No | No | RGB negative adjustment parameter based on the reference saturation.<br>The value range of each number is [-20, 20].| 255| fraction | number | No | No | Blending ratio of the brightness effect.<br>The value range is [0, 1]. A value beyond the boundary will be automatically truncated during implementation. | 256