1# Class (ShaderEffect) 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphics--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10> **说明：** 11> 12> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> 14> - 本Class首批接口从API version 12开始支持。 15> 16> - 本模块使用屏幕物理像素单位px。 17> 18> - 本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。 19 20着色器。画刷和画笔设置着色器后，会使用着色器效果而不是颜色属性去绘制，但此时画笔和画刷的透明度属性仍然生效。 21 22## 导入模块 23 24```ts 25import { drawing } from '@kit.ArkGraphics2D'; 26``` 27 28## createComposeShader<sup>20+</sup> 29 30static createComposeShader(dstShaderEffect: ShaderEffect, srcShaderEffect: ShaderEffect, blendMode: BlendMode): ShaderEffect 31 32按照指定的混合模式对两个着色器进行叠加，生成一个新的着色器。 33 34**系统能力：** SystemCapability.Graphics.Drawing 35 36**参数：** 37 38| 参数名 | 类型 | 必填 | 说明 | 39| ------ | -------------------------------------------------- | ---- | -------------- | 40| dstShaderEffect | [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 是 | 在混合模式中作为目标色的着色器。 | 41| srcShaderEffect | [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 是 | 在混合模式中作为源色的着色器。 | 42| blendMode | [BlendMode](arkts-apis-graphics-drawing-e.md#blendmode) | 是 | 混合模式。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ------- | ------------------------- | 48| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 49 50**错误码：** 51 52以下错误码的详细介绍请参见[图形绘制与显示错误码](../apis-arkgraphics2d/errorcode-drawing.md)。 53 54| 错误码ID | 错误信息 | 55| ------- | --------------------------------------------| 56| 25900001 | Parameter error.Possible causes: Incorrect parameter range. | 57 58**示例：** 59 60```ts 61import { drawing } from '@kit.ArkGraphics2D'; 62 63let dstShader = drawing.ShaderEffect.createColorShader(0xFF0000FF); 64let srcShader = drawing.ShaderEffect.createColorShader(0xFFFF0000); 65let shader = drawing.ShaderEffect.createComposeShader(dstShader, srcShader, drawing.BlendMode.SRC); 66``` 67 68## createImageShader<sup>20+</sup> 69 70static createImageShader(pixelmap: image.PixelMap, tileX: TileMode, tileY: TileMode, samplingOptions: SamplingOptions, matrix?: Matrix | null): ShaderEffect 71 72基于图片创建一个着色器。此接口不建议用于录制类型的画布，会影响性能。 73 74**系统能力：** SystemCapability.Graphics.Drawing 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | -------------------------------------------------- | ---- | -------------- | 80| pixelmap | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 进行采样的图片对象。 | 81| tileX | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 水平方向的平铺模式。 | 82| tileY | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 竖直方向的平铺模式。 | 83| samplingOptions | [SamplingOptions](arkts-apis-graphics-drawing-SamplingOptions.md) | 是 | 图片采样参数。 | 84| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) \| null | 否 | 可选参数，对图片施加的矩阵变换，如果为空，则不施加任何变换。 | 85 86**返回值：** 87 88| 类型 | 说明 | 89| ------- | ------------------------- | 90| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[图形绘制与显示错误码](../apis-arkgraphics2d/errorcode-drawing.md)。 95 96| 错误码ID | 错误信息 | 97| ------- | --------------------------------------------| 98| 25900001 | Parameter error.Possible causes: Incorrect parameter range. | 99 100**示例：** 101 102```ts 103import { RenderNode } from '@kit.ArkUI'; 104import { image } from '@kit.ImageKit'; 105import { drawing } from '@kit.ArkGraphics2D'; 106class DrawingRenderNode extends RenderNode { 107 draw(context : DrawContext) { 108 const width = 1000; 109 const height = 1000; 110 const bufferSize = width * height * 4; 111 const color: ArrayBuffer = new ArrayBuffer(bufferSize); 112 113 const colorData = new Uint8Array(color); 114 for (let i = 0; i < colorData.length; i += 4) { 115 colorData[i] = 255; 116 colorData[i+1] = 156; 117 colorData[i+2] = 0; 118 colorData[i+3] = 255; 119 } 120 121 let opts : image.InitializationOptions = { 122 editable: true, 123 pixelFormat: 3, 124 size: { height, width } 125 } 126 127 let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 128 let matrix = new drawing.Matrix(); 129 let options = new drawing.SamplingOptions(drawing.FilterMode.FILTER_MODE_NEAREST); 130 if (pixelMap != null) { 131 let imageShader = drawing.ShaderEffect.createImageShader(pixelMap, drawing.TileMode.REPEAT, drawing.TileMode.MIRROR, options, matrix); 132 } 133 } 134} 135``` 136 137## createColorShader<sup>12+</sup> 138 139static createColorShader(color: number): ShaderEffect 140 141创建具有单一颜色的着色器。 142 143**系统能力：** SystemCapability.Graphics.Drawing 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ------ | -------------------------------------------------- | ---- | -------------- | 149| color | number | 是 | 表示着色器的ARGB格式颜色，该参数为32位无符号整数。 | 150 151**返回值：** 152 153| 类型 | 说明 | 154| ------- | ------------------------- | 155| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回具有单一颜色的着色器对象。 | 156 157**错误码：** 158 159以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 160 161| 错误码ID | 错误信息 | 162| ------- | --------------------------------------------| 163| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 164 165**示例：** 166 167```ts 168import { drawing } from '@kit.ArkGraphics2D'; 169 170let shaderEffect = drawing.ShaderEffect.createColorShader(0xFFFF0000); 171``` 172 173## createLinearGradient<sup>12+</sup> 174 175static createLinearGradient(startPt: common2D.Point, endPt: common2D.Point, colors: Array\<number>, mode: TileMode, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect 176 177创建着色器，在两个指定点之间生成线性渐变。 178 179**系统能力：** SystemCapability.Graphics.Drawing 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| ------ | -------------------------------------------------- | ---- | -------------- | 185| startPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 表示渐变的起点。 | 186| endPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 表示渐变的终点。 | 187| colors | Array\<number> | 是 | 表示在两个点之间分布的颜色数组，数组中的值为32位（ARGB）无符号整数。 | 188| mode | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 着色器效果平铺模式。 | 189| pos | Array\<number> \|null| 否 | 表示每种对应颜色在颜色数组中的相对位置。数组长度需和colors保持一致，数组的首个元素应当是0.0，末尾元素应当是1.0，中间的元素应当在0与1之间并且逐下标递增，表示colors中每个对应颜色的相对位置。默认为null，表示颜色均匀分布在起点和终点之间。 | 190| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) \| null | 否 | 矩阵对象，用于对着色器做矩阵变换。默认为null，表示单位矩阵。 | 191 192 193 194如上图所示，设置颜色数组为红绿蓝，位置数组为0.0、0.75和1.0后的显示效果。三角下标表示对应颜色的起始点和终点之间的相对位置，颜色之间使用渐变填充。 195 196**返回值：** 197 198| 类型 | 说明 | 199| ------- | ------------------------- | 200| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 201 202**错误码：** 203 204以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 205 206| 错误码ID | 错误信息 | 207| ------- | --------------------------------------------| 208| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 209 210**示例：** 211 212```ts 213import { common2D,drawing } from '@kit.ArkGraphics2D'; 214 215let startPt: common2D.Point = { x: 100, y: 100 }; 216let endPt: common2D.Point = { x: 300, y: 300 }; 217let shaderEffect = drawing.ShaderEffect.createLinearGradient(startPt, endPt, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 218``` 219 220## createRadialGradient<sup>12+</sup> 221 222static createRadialGradient(centerPt: common2D.Point, radius: number, colors: Array\<number>, mode: TileMode, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect 223 224创建着色器，使用给定的圆心和半径生成径向渐变。径向渐变是指颜色从圆心逐渐向外扩散形成的渐变。 225 226**系统能力：** SystemCapability.Graphics.Drawing 227 228**参数：** 229 230| 参数名 | 类型 | 必填 | 说明 | 231| ------ | -------------------------------------------------- | ---- | -------------- | 232| centerPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 表示渐变的圆心。 | 233| radius | number | 是 | 表示渐变的半径，小于等于0时无效，该参数为浮点数。 | 234| colors | Array\<number> | 是 | 表示在圆心和圆边界之间分布的颜色数组，数组中的值为32位（ARGB）无符号整数。 | 235| mode | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 着色器效果平铺模式。 | 236| pos | Array\<number> \| null | 否 | 表示每种对应颜色在颜色数组中的相对位置。数组长度需和colors保持一致，数组的首个元素应当是0.0，末尾元素应当是1.0，中间的元素应当在0与1之间并且逐下标递增，表示colors中每个对应颜色的相对位置。默认为null，表示颜色均匀分布在圆心和圆边界之间。 | 237| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) \| null | 否 | 矩阵对象，用于对着色器做矩阵变换。默认为null，表示单位矩阵。 | 238 239 240 241如上图所示，设置颜色数组为红绿蓝，位置数组为0.0、0.75和1.0后的显示效果。三角下标表示对应颜色所在圆心和圆边界之间的相对位置，颜色之间使用渐变填充。 242 243**返回值：** 244 245| 类型 | 说明 | 246| ------- | ------------------------- | 247| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 248 249**错误码：** 250 251以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 252 253| 错误码ID | 错误信息 | 254| ------- | --------------------------------------------| 255| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 256 257**示例：** 258 259```ts 260import { common2D,drawing } from '@kit.ArkGraphics2D'; 261 262let centerPt: common2D.Point = { x: 100, y: 100 }; 263let shaderEffect = drawing.ShaderEffect.createRadialGradient(centerPt, 100, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 264``` 265 266## createSweepGradient<sup>12+</sup> 267 268static createSweepGradient(centerPt: common2D.Point, colors: Array\<number>, mode: TileMode, startAngle: number, endAngle: number, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect 269 270创建着色器。该着色器以给定中心点为圆心，在顺时针或逆时针方向上生成颜色扫描渐变。 271 272**系统能力：** SystemCapability.Graphics.Drawing 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ------ | -------------------------------------------------- | ---- | -------------- | 278| centerPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 表示渐变的圆心。 | 279| colors | Array\<number> | 是 | 表示在起始角度和结束角度之间分布的颜色数组，数组中的值为32位（ARGB）无符号整数。 | 280| mode | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 着色器效果平铺模式。 | 281| startAngle | number | 是 | 表示扇形渐变的起始角度，单位为度。0度时为x轴正方向，正数往顺时针方向偏移，负数往逆时针方向偏移。该参数为浮点数。 | 282| endAngle | number | 是 | 表示扇形渐变的结束角度，单位为度。0度时为x轴正方向，正数往顺时针方向偏移，负数往逆时针方向偏移。小于起始角度时无效。该参数为浮点数。 | 283| pos | Array\<number> \| null | 否 | 表示每种对应颜色在颜色数组中的相对位置。数组长度需和colors保持一致，数组的首个元素应当是0.0，末尾元素应当是1.0，中间的元素应当在0与1之间并且逐下标递增，表示colors中每个对应颜色的相对位置。默认为null，表示颜色均匀分布在起始角度和结束角度之间。 | 284| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) \| null | 否 |矩阵对象，用于对着色器做矩阵变换。默认为null，表示单位矩阵。 | 285 286 287 288如上图所示，设置颜色数组为红绿蓝，位置数组为0.0、0.75和1.0，起始角度设置为0度，结束角度设置为180度后的显示效果。0.0对应0度的位置，0.75对应135度的位置，1.0对应180度的位置，颜色之间使用渐变填充。 289 290**返回值：** 291 292| 类型 | 说明 | 293| ------- | ------------------------- | 294| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 295 296**错误码：** 297 298以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 299 300| 错误码ID | 错误信息 | 301| ------- | --------------------------------------------| 302| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 303 304**示例：** 305 306```ts 307import { common2D,drawing } from '@kit.ArkGraphics2D'; 308 309let centerPt: common2D.Point = { x: 100, y: 100 }; 310let shaderEffect = drawing.ShaderEffect.createSweepGradient(centerPt, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT, 100, 200); 311``` 312 313## createConicalGradient<sup>12+</sup> 314 315static createConicalGradient(startPt: common2D.Point, startRadius: number, endPt: common2D.Point, endRadius: number, colors: Array\<number>, mode: TileMode, pos?: Array\<number> | null, matrix?: Matrix | null): ShaderEffect 316 317创建着色器，在给定两个圆之间生成径向渐变。 318 319**系统能力：** SystemCapability.Graphics.Drawing 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| ------ | -------------------------------------------------- | ---- | -------------- | 325| startPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 |表示渐变的起始圆的圆心。 | 326| startRadius | number | 是 | 表示渐变的起始圆的半径，小于0时无效。该参数为浮点数。 | 327| endPt | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 表示渐变的结束圆的圆心。 | 328| endRadius | number | 是 | 表示渐变的结束圆的半径，小于0时无效。该参数为浮点数。 | 329| colors | Array\<number> | 是 | 表示在起始圆和结束圆之间分布的颜色数组，数组中的值为32位（ARGB）无符号整数。 | 330| mode | [TileMode](arkts-apis-graphics-drawing-e.md#tilemode12) | 是 | 着色器效果平铺模式。 | 331| pos | Array\<number> \| null | 否 | 表示每种对应颜色在颜色数组中的相对位置。数组长度需和colors保持一致，数组的首个元素应当是0.0，末尾元素应当是1.0，中间的元素应当在0与1之间并且逐下标递增，表示colors中每个对应颜色的相对位置。默认为null，表示颜色均匀分布在起始圆和结束圆之间。| 332| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) \| null | 否 | 矩阵对象，用于对着色器做矩阵变换。默认为null，表示单位矩阵。 | 333 334 335 336如上图所示，设置颜色数组为红绿蓝，位置数组为0.0、0.5和1.0的绘制结果。左侧为起始圆不在结束圆内的绘制结果，右侧为起始圆在结束圆内的绘制结果。 337 338**返回值：** 339 340| 类型 | 说明 | 341| ------- | ------------------------- | 342| [ShaderEffect](arkts-apis-graphics-drawing-ShaderEffect.md) | 返回创建的着色器对象。 | 343 344**错误码：** 345 346以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 347 348| 错误码ID | 错误信息 | 349| ------- | --------------------------------------------| 350| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 351 352**示例：** 353 354```ts 355import { common2D,drawing } from '@kit.ArkGraphics2D'; 356 357let startPt: common2D.Point = { x: 100, y: 100 }; 358let endPt: common2D.Point = {x: 200, y: 200}; 359let shaderEffect = drawing.ShaderEffect.createConicalGradient(startPt, 100, endPt, 50, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT); 360```
