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