• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 onto 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 onto 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**Error codes**
103
104For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
105
106| ID| Error Message|
107| ------- | -------------------------------- |
108| 202  | Permission verification failed. A non-system application calls a system API. |
109
110**Example**
111
112```ts
113filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL)
114```
115
116### flyInFlyOutEffect
117flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter
118
119Applies fly-in and fly-out animations onto the component.
120
121**System capability**: SystemCapability.Graphics.Drawing
122
123**System API**: This is a system API.
124
125**Parameters**
126| Name        | Type                 | Mandatory| Description                      |
127| ------------- | --------------------- | ---- | ------------------------- |
128| 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.|
129| 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.|
130
131
132**Return value**
133
134| Type             | Description                              |
135| ----------------- | --------------------------------- |
136| [Filter](#filter) | **Filter** instance with the fly-in and fly-out animations.|
137
138**Error codes**
139
140For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
141
142| ID| Error Message|
143| ------- | -------------------------------- |
144| 202  | Permission verification failed. A non-system application calls a system API. |
145
146**Example**
147
148```ts
149filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP)
150```
151
152### distort<sup>13+</sup>
153distort(distortionK: number): Filter
154
155Applies the lens distortion effect onto the component.
156
157**System capability**: SystemCapability.Graphics.Drawing
158
159**System API**: This is a system API.
160
161**Parameters**
162| Name        | Type                 | Mandatory| Description                      |
163| ------------- | --------------------- | ---- | ------------------------- |
164| 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**.|
165
166![image_Add_Distort.png](./figures/image_Add_Distort.png)
167
168The 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.
169
170**Return value**
171
172| Type             | Description                              |
173| ----------------- | --------------------------------- |
174| [Filter](#filter) | **Filter** instance with lens distortion effect.|
175
176**Error codes**
177
178For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
179
180| ID| Error Message|
181| ------- | --------------------------------------------|
182| 202 | Permission verification failed. A non-system application calls a system API. |
183
184**Example**
185
186```ts
187filter.distort(-0.5)
188```
189
190## TileMode
191Enumerates the pixel tiling modes.
192
193**System capability**: SystemCapability.Graphics.Drawing
194
195**System API**: This is a system API.
196
197| Name  | Value| Description|
198| ------ | - | ---- |
199| CLAMP  | 0 | Clamp.|
200| REPEAT | 1 | Repeat.|
201| MIRROR | 2 | Mirror.|
202| DECAL  | 3 | Decal.|
203
204## WaterRippleMode
205Enumerates the scene modes of the ripple effect.
206
207**System capability**: SystemCapability.Graphics.Drawing
208
209**System API**: This is a system API.
210
211| Name  | Value| Description|
212| ------ | - | ---- |
213| SMALL2MEDIUM_RECV  | 0 | A phone taps against a 2-in-1 device (receiver).|
214| SMALL2MEDIUM_SEND  | 1 | A phone taps against a 2-in-1 device (sender).|
215| SMALL2SMALL | 2 | A phone taps against another phone.|
216
217## FlyMode
218Enumerates the scene modes of fly-in and fly-out animations.
219
220**System capability**: SystemCapability.Graphics.Drawing
221
222**System API**: This is a system API.
223
224| Name  | Value| Description|
225| ------ | - | ---- |
226| BOTTOM  | 0 | Fly-in and fly-out animations occur from the bottom of the screen.|
227| TOP  | 1 | Fly-in and fly-out animations occur from the top of the screen.|
228
229## VisualEffect
230A 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.
231
232### backgroundColorBlender
233backgroundColorBlender(blender: BrightnessBlender): VisualEffect
234
235Applies 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.
236
237**System capability**: SystemCapability.Graphics.Drawing
238
239**System API**: This is a system API.
240
241**Parameters**
242| Name | Type                                     | Mandatory| Description                      |
243| ------- | ---------------------------------------- | ---- | ------------------------- |
244| blender | [BrightnessBlender](#brightnessblender) | Yes  | Blender used to change the background color.|
245
246**Return value**
247
248| Type                         | Description                                              |
249| ----------------------------- | ------------------------------------------------- |
250| [VisualEffect](#visualeffect) | **VisualEffect** instance with the background color change effect.|
251
252**Example**
253
254```ts
255let blender : uiEffect.BrightnessBlender =
256  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
257    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})
258visualEffect.backgroundColorBlender(blender)
259```
260
261## Blender<sup>13+</sup>
262
263type Blender = BrightnessBlender
264
265Defines the blender type, which is used to describe blending effects.
266
267**System capability**: SystemCapability.Graphics.Drawing
268
269**System API**: This is a system API.
270
271| Type                         | Description                                              |
272| ----------------------------- | ------------------------------------------------- |
273| [BrightnessBlender](#brightnessblender) | Blender with a brightening effect.|
274
275## BrightnessBlender
276A 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.
277
278**System capability**: SystemCapability.Graphics.Drawing
279
280**System API**: This is a system API.
281
282| Name               | Type                       | Read Only| Optional| Description                                                             |
283| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- |
284| cubicRate           | number                     | No  | No  | Third-order coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
285| quadraticRate       | number                     | No  | No  | Second-order coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
286| linearRate          | number                     | No  | No  | Linear coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
287| degree              | number                     | No  | No  | Grayscale adjustment ratio.<br>The value range is [-20, 20].                           |
288| saturation          | number                     | No  | No  | Reference saturation for the brightness effect.<br>The value range is [0, 20].                           |
289| 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].|
290| 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].|
291| 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. |
292
293## BrightnessBlenderParam
294Describes the parameters used for the brightness blender.
295
296**System capability**: SystemCapability.Graphics.Drawing
297
298**System API**: This is a system API.
299
300| Name               | Type                       | Read Only| Optional| Description                                                             |
301| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- |
302| cubicRate           | number                     | No  | No  | Third-order coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
303| quadraticRate       | number                     | No  | No  | Second-order coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
304| linearRate          | number                     | No  | No  | Linear coefficient for grayscale adjustment.<br>The value range is [-20, 20].                       |
305| degree              | number                     | No  | No  | Grayscale adjustment ratio.<br>The value range is [-20, 20].                           |
306| saturation          | number                     | No  | No  | Reference saturation for the brightness effect.<br>The value range is [0, 20].                           |
307| 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].|
308| 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].|
309| 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. |
310