1# @ohos.graphics.colorSpaceManager (色彩管理) 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphic--> 5<!--Owner: @xubo85--> 6<!--Designer: @comicchang; @wang-luyu4--> 7<!--Tester: @zhaoxiaoguang2--> 8<!--Adviser: @ge-yafang--> 9 10本模块提供管理抽象化色域对象的一些基础能力，包括色域对象的创建与色域基础属性的获取等。 11 12> **说明：** 13> 14> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import { colorSpaceManager } from '@kit.ArkGraphics2D'; 20``` 21 22## ColorSpace 23 24色域类型枚举。 25 26**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 27 28| 名称 | 值 | 说明 | 29| --------------------------- | ------ | ----------------------- | 30| UNKNOWN | 0 | 未知的色域类型。| 31| ADOBE_RGB_1998 | 1 | RGB色域为Adobe RGB(1998)类型。<br>转换函数为Adobe RGB(1998)类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 32| DCI_P3 | 2 | RGB色域为DCI-P3类型。<br>转换函数为Gamma 2.6类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 33| DISPLAY_P3 | 3 | RGB色域为Display P3类型。<br>转换函数为SRGB类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 34| SRGB | 4 | RGB色域为SRGB类型。<br>转换函数为SRGB类型。<br>编码范围为Full类型。<br>系统默认色域类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 35| CUSTOM | 5 | 用户自定义色域类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 36| BT709<sup>11+</sup> | 6 | RGB色域为BT709类型。<br>转换函数为BT709类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 37| BT601_EBU<sup>11+</sup> | 7 | RGB色域为BT601_P类型。<br>转换函数为BT709类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 38| BT601_SMPTE_C<sup>11+</sup> | 8 | RGB色域为BT601_N类型。<br>转换函数为BT709类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 39| BT2020_HLG<sup>11+</sup> | 9 | RGB色域为BT2020类型。<br>转换函数为HLG类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 40| BT2020_PQ<sup>11+</sup> | 10 | RGB色域为BT2020类型。<br>转换函数为PQ类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 41| P3_HLG<sup>11+</sup> | 11 | RGB色域为Display P3类型。<br>转换函数为HLG类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 42| P3_PQ<sup>11+</sup> | 12 | RGB色域为Display P3类型。<br>转换函数为PQ类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 43| ADOBE_RGB_1998_LIMIT<sup>11+</sup> | 13 | RGB色域为Adobe RGB(1998)类型。<br>转换函数为Adobe RGB(1998)类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 44| DISPLAY_P3_LIMIT<sup>11+</sup> | 14 | RGB色域为Display P3类型。<br>转换函数为SRGB类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 45| SRGB_LIMIT<sup>11+</sup> | 15 | RGB色域为SRGB类型。<br>转换函数为SRGB类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 46| BT709_LIMIT<sup>11+</sup> | 16 | RGB色域为BT709类型。<br>转换函数为BT709类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 47| BT601_EBU_LIMIT<sup>11+</sup> | 17 | RGB色域为BT601_P类型。<br>转换函数为BT709类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| BT601_SMPTE_C_LIMIT<sup>11+</sup> | 18 | RGB色域为BT601_N类型。<br>转换函数为BT709类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 49| BT2020_HLG_LIMIT<sup>11+</sup> | 19 | RGB色域为BT2020类型。<br>转换函数为HLG类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| BT2020_PQ_LIMIT<sup>11+</sup> | 20 | RGB色域为BT2020类型。<br>转换函数为PQ类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 51| P3_HLG_LIMIT<sup>11+</sup> | 21 | RGB色域为Display P3类型。<br>转换函数为HLG类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52| P3_PQ_LIMIT<sup>11+</sup> | 22 | RGB色域为Display P3类型。<br>转换函数为PQ类型。<br>编码范围为Limit类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 53| LINEAR_P3<sup>11+</sup> | 23 | RGB色域为Display P3类型。<br>转换函数为Linear类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 54| LINEAR_SRGB<sup>11+</sup> | 24 | RGB色域为SRGB类型。<br>转换函数为Linear类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 55| LINEAR_BT709<sup>11+</sup> | 24 | 与LINEAR_SRGB相同。<br>RGB色域为BT709类型。<br>转换函数为Linear类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| LINEAR_BT2020<sup>11+</sup> | 25 | RGB色域为BT2020类型。<br>转换函数为Linear类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 57| H_LOG<sup>18+</sup> | 26 | RGB色域为BT2020类型。<br>转换函数为LOG类型。 | 58| DISPLAY_BT2020_SRGB<sup>20+</sup> | 27 | RGB色域为DISPLAY BT2020类型。<br>转换函数为SRGB类型。<br>编码范围为Full类型。| 59| DISPLAY_SRGB<sup>11+</sup> | 4 | 与SRGB相同。<br>RGB色域为SRGB类型。<br>转换函数为SRGB类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 60| DISPLAY_P3_SRGB<sup>11+</sup> | 3 | 与DISPLAY_P3相同。<br>RGB色域为Display P3类型。<br>转换函数为SRGB类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 61| DISPLAY_P3_HLG<sup>11+</sup> | 11 | 与P3_HLG相同。<br>RGB色域为Display P3类型。<br>转换函数为HLG类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 62| DISPLAY_P3_PQ<sup>11+</sup> | 12 | 与P3_PQ相同。<br>RGB色域为Display P3类型。<br>转换函数为PQ类型。<br>编码范围为Full类型。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 63 64## ColorSpacePrimaries 65 66色域标准三原色（红、绿、蓝）和白色，使用(x, y)表示其在色彩空间中的位置。 67 68**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 69 70| 名称 | 类型 | 只读 | 可选 | 说明 | 71| ---------------------------- | -------- | ---- | ---- | ----------------------------------------------------- | 72| redX | number | 否 | 否 | 标准红色在色彩空间的x坐标值。 | 73| redY | number | 否 | 否 | 标准红色在色彩空间的y坐标值。 | 74| greenX | number | 否 | 否 | 标准绿色在色彩空间的x坐标值。 | 75| greenY | number | 否 | 否 | 标准绿色在色彩空间的y坐标值。 | 76| blueX | number | 否 | 否 | 标准蓝色在色彩空间的x坐标值。 | 77| blueY | number | 否 | 否 | 标准蓝色在色彩空间的y坐标值。 | 78| whitePointX | number | 否 | 否 | 标准白色在色彩空间的x坐标值。 | 79| whitePointY | number | 否 | 否 | 标准白色在色彩空间的y坐标值。 | 80 81## colorSpaceManager.create 82 83create(colorSpaceName: ColorSpace): ColorSpaceManager 84 85创建标准色域对象。 86 87**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| --------------- | ------------------------ | ---- | -----------------------------| 93| colorSpaceName | [ColorSpace](#colorspace)| 是 | 标准色域类型枚举值。<br>UNKNOWN与CUSTOM不可用于直接创建色域对象。 | 94 95**返回值：** 96 97| 类型 | 说明 | 98| ------------------ | ------------------------ | 99| [ColorSpaceManager](#colorspacemanager) | 返回当前创建的色域对象实例。 | 100 101**错误码：** 102 103以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[色彩管理错误码](errorcode-colorspace-manager.md)。 104 105| 错误码ID | 错误信息 | 106| ------- | ----------------------- | 107| 401 | Parameter error. Possible cause: 1.Incorrect parameter type. 2.Parameter verification failed.| 108| 18600001 | The parameter value is abnormal. | 109 110**示例：** 111 112```ts 113let colorSpace: colorSpaceManager.ColorSpaceManager; 114try { 115 colorSpace = colorSpaceManager.create(colorSpaceManager.ColorSpace.SRGB); 116} catch (err) { 117 console.error(`Failed to create SRGB colorSpace. Cause: ` + JSON.stringify(err)); 118} 119``` 120 121## colorSpaceManager.create 122 123create(primaries: ColorSpacePrimaries, gamma: number): ColorSpaceManager 124 125创建用户自定义色域对象。 126 127**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| --------------- | ------------------------------------------ | ---- | -----------------------------| 133| primaries | [ColorSpacePrimaries](#colorspaceprimaries)| 是 | 色域标准三原色。 | 134| gamma | number | 是 | 色域gamma值，取值为大于0的浮点数。| 135 136**返回值：** 137 138| 类型 | 说明 | 139| ------------------ | ------------------------ | 140| [ColorSpaceManager](#colorspacemanager) | 返回当前创建的色域对象实例。<br>色域类型定义为[ColorSpace](#colorspace)枚举值`CUSTOM`。 | 141 142**错误码：** 143 144以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[色彩管理错误码](errorcode-colorspace-manager.md)。 145 146| 错误码ID | 错误信息 | 147| ------- | ----------------------- | 148| 401 | Parameter error. Possible cause: 1.Incorrect parameter type. 2.Parameter verification failed.| 149| 18600001 | Invalid parameter value. Possible cause: Used UNKNOWN or CUSTOM color space type enum values to directly create a colorSpaceManager object. | 150 151**示例：** 152 153```ts 154let colorSpace: colorSpaceManager.ColorSpaceManager; 155try { 156 let primaries: colorSpaceManager.ColorSpacePrimaries = { 157 redX: 0.1, 158 redY: 0.1, 159 greenX: 0.2, 160 greenY: 0.2, 161 blueX: 0.3, 162 blueY: 0.3, 163 whitePointX: 0.4, 164 whitePointY: 0.4 165 }; 166 let gamma = 2.2; 167 colorSpace = colorSpaceManager.create(primaries, gamma); 168} catch (err) { 169 console.error(`Failed to create colorSpace with customized primaries and gamma. Cause: ` + JSON.stringify(err)); 170} 171``` 172 173## ColorSpaceManager 174 175当前色域对象实例。 176 177下列API示例中都需先使用[create()](#colorspacemanagercreate)获取到ColorSpaceManager实例，再通过此实例调用对应方法。 178 179### getColorSpaceName 180 181getColorSpaceName(): ColorSpace 182 183获取色域类型。 184 185**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 186 187**返回值：** 188 189| 类型 | 说明 | 190| ------------------ | ------------------------ | 191| [ColorSpace](#colorspace) | 返回色域类型枚举值。 | 192 193**错误码：** 194 195以下错误码的详细介绍请参见[色彩管理错误码](errorcode-colorspace-manager.md)。 196 197| 错误码ID | 错误信息 | 198| ------- | ----------------------- | 199| 18600001 | The parameter value is abnormal. | 200 201**示例：** 202 203```ts 204try { 205 let spaceName = colorSpace.getColorSpaceName(); 206} catch (err) { 207 console.error(`Fail to get colorSpace's name. Cause: ` + JSON.stringify(err)); 208} 209``` 210 211### getWhitePoint 212 213getWhitePoint(): Array\<number\> 214 215获取色域白点值。 216 217**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 218 219**返回值：** 220 221| 类型 | 说明 | 222| ------------------ | ------------------------ | 223| Array\<number\> | 返回色域白点值[x, y]。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[色彩管理错误码](errorcode-colorspace-manager.md)。 228 229| 错误码ID | 错误信息 | 230| ------- | ----------------------- | 231| 18600001 | Invalid parameter value. Possible cause: Used UNKNOWN or CUSTOM color space type enum values to directly create a colorSpaceManager object. | 232 233**示例：** 234 235```ts 236try { 237 let point = colorSpace.getWhitePoint(); 238} catch (err) { 239 console.error(`Failed to get white point. Cause: ` + JSON.stringify(err)); 240} 241``` 242 243### getGamma 244 245getGamma(): number 246 247获取色域gamma值。 248 249**系统能力：** SystemCapability.Graphic.Graphic2D.ColorManager.Core 250 251**返回值：** 252 253| 类型 | 说明 | 254| ------------------ | ------------------------ | 255| number | 返回色域gamma值。 | 256 257**错误码：** 258 259以下错误码的详细介绍请参见[色彩管理错误码](errorcode-colorspace-manager.md)。 260 261| 错误码ID | 错误信息 | 262| ------- | ----------------------- | 263| 18600001 | Invalid parameter value. Possible cause: Used UNKNOWN or CUSTOM color space type enum values to directly create a colorSpaceManager object. | 264 265**示例：** 266 267```ts 268try { 269 let gamma = colorSpace.getGamma(); 270} catch (err) { 271 console.error(`Failed to get gamma. Cause: ` + JSON.stringify(err)); 272} 273```