1# @ohos.graphics.colorSpaceManager (Color Space Management)
2
3The **colorSpaceManager** module provides APIs for creating and managing color space objects and obtaining basic color space attributes.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { colorSpaceManager } from '@kit.ArkGraphics2D';
13```
14
15## ColorSpace
16
17Enumerates the color space types.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
22
23| Name                        | Value    | Description                   |
24| --------------------------- | ------ | ----------------------- |
25| UNKNOWN                           | 0      | Unknown type.|
26| ADOBE_RGB_1998                    | 1      | Adobe RGB (1998).<br>The conversion function is of the Adobe RGB (1998) type.<br>The encoding range is of the Full type. |
27| DCI_P3                            | 2      | DCI-P3.<br>The conversion function is of the Gamma 2.6 type.<br>The encoding range is of the Full type.|
28| DISPLAY_P3                        | 3      | Display P3.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Full type. |
29| SRGB                              | 4      | SRGB.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Full type.<br>This is the default color space type. |
30| CUSTOM                            | 5      | Custom type.|
31| BT709<sup>11+</sup>                | 6      | BT709.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Full type. |
32| BT601_EBU<sup>11+</sup>            | 7      | BT601_P.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Full type. |
33| BT601_SMPTE_C<sup>11+</sup>        | 8      | BT601_N.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Full type. |
34| BT2020_HLG<sup>11+</sup>           | 9      | BT2020.<br>The conversion function is of the HLG type.<br>The encoding range is of the Full type. |
35| BT2020_PQ<sup>11+</sup>            | 10     | BT2020.<br>The conversion function is of the PQ type.<br>The encoding range is of the Full type. |
36| P3_HLG<sup>11+</sup>               | 11     | Display P3.<br>The conversion function is of the HLG type.<br>The encoding range is of the Full type. |
37| P3_PQ<sup>11+</sup>                | 12     | Display P3.<br>The conversion function is of the PQ type.<br>The encoding range is of the Full type. |
38| ADOBE_RGB_1998_LIMIT<sup>11+</sup> | 13     | Adobe RGB (1998).<br>The conversion function is of the Adobe RGB (1998) type.<br>The encoding range is of the Limit type. |
39| DISPLAY_P3_LIMIT<sup>11+</sup>     | 14     | Display P3.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Limit type. |
40| SRGB_LIMIT<sup>11+</sup>           | 15     | SRGB.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Limit type. |
41| BT709_LIMIT<sup>11+</sup>          | 16     | BT709.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Limit type. |
42| BT601_EBU_LIMIT<sup>11+</sup>      | 17     | BT601_P.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Limit type. |
43| BT601_SMPTE_C_LIMIT<sup>11+</sup>  | 18     | BT601_N.<br>The conversion function is of the BT709 type.<br>The encoding range is of the Limit type. |
44| BT2020_HLG_LIMIT<sup>11+</sup>     | 19     | BT2020.<br>The conversion function is of the HLG type.<br>The encoding range is of the Limit type. |
45| BT2020_PQ_LIMIT<sup>11+</sup>      | 20     | BT2020.<br>The conversion function is of the PQ type.<br>The encoding range is of the Limit type. |
46| P3_HLG_LIMIT<sup>11+</sup>         | 21     | Display P3.<br>The conversion function is of the HLG type.<br>The encoding range is of the Limit type. |
47| P3_PQ_LIMIT<sup>11+</sup>          | 22     | Display P3.<br>The conversion function is of the PQ type.<br>The encoding range is of the Limit type. |
48| LINEAR_P3<sup>11+</sup>            | 23     | Display P3.<br>The conversion function is of the Linear type. |
49| LINEAR_SRGB<sup>11+</sup>          | 24     | SRGB.<br>The conversion function is of the Linear type. |
50| LINEAR_BT709<sup>11+</sup>         | 24     | Same as that of LINEAR_SRGB.<br>BT709.<br>The conversion function is of the Linear type. |
51| LINEAR_BT2020<sup>11+</sup>        | 25     | BT2020.<br>The conversion function is of the Linear type. |
52| DISPLAY_SRGB<sup>11+</sup>         | 4      | Same as that of SRGB.<br>SRGB.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Full type. |
53| DISPLAY_P3_SRGB<sup>11+</sup>      | 3      | Same as that of DISPLAY_P3.<br>Display P3.<br>The conversion function is of the SRGB type.<br>The encoding range is of the Full type. |
54| DISPLAY_P3_HLG<sup>11+</sup>       | 11     | Same as that of P3_HLG.<br>Display P3.<br>The conversion function is of the HLG type.<br>The encoding range is of the Full type. |
55| DISPLAY_P3_PQ<sup>11+</sup>        | 12     | Same as that of P3_PQ.<br>Display P3.<br>The conversion function is of the PQ type.<br>The encoding range is of the Full type. |
56
57## ColorSpacePrimaries
58
59Defines the color space primaries. A color space is defined by chromaticity coordinates of the red, green, and blue additive primaries, the white point, and the gamma.
60
61**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
62
63| Name                         | Type | Readable | Writable | Description                                                        |
64| ---------------------------- | -------- | ---- | ---- | ----------------------------------------------------- |
65| redX                         | number   | Yes  | Yes  | X coordinate of the red color in the color space. |
66| redY                         | number   | Yes  | Yes  | Y coordinate of the red color in the color space. |
67| greenX                       | number   | Yes  | Yes  | X coordinate of the green color in the color space. |
68| greenY                       | number   | Yes  | Yes  | Y coordinate of the green color in the color space. |
69| blueX                        | number   | Yes  | Yes  | X coordinate of the blue color in the color space. |
70| blueY                        | number   | Yes  | Yes  | Y coordinate of the blue color in the color space. |
71| whitePointX                  | number   | Yes  | Yes  | X coordinate of the white point in the color space. |
72| whitePointY                  | number   | Yes  | Yes  | Y coordinate of the white point in the color space. |
73
74## colorSpaceManager.create
75
76create(colorSpaceName: ColorSpace): ColorSpaceManager
77
78Creates a standard color space object.
79
80**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
81
82**Parameters**
83
84| Parameter          | Type                    | Mandatory | Description                         |
85| --------------- | ------------------------ | ---- | -----------------------------|
86| colorSpaceName  | [ColorSpace](#colorspace)| Yes  | Type of the color space.<br>**UNKNOWN** and **CUSTOM** cannot be used when creating standard color space objects.         |
87
88**Return value**
89
90| Type               | Description                    |
91| ------------------ | ------------------------ |
92| [ColorSpaceManager](#colorspacemanager)  | Color space object created.              |
93
94**Error codes**
95
96For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [colorSpaceManager Error Codes](errorcode-colorspace-manager.md).
97
98| ID | Error Message |
99| ------- | ----------------------- |
100| 401 | Parameter error. Possible cause: 1.Incorrect parameter type. 2.Parameter verification failed.|
101| 18600001 | The parameter value is abnormal. |
102
103**Example**
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
118Creates a custom color space object.
119
120**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
121
122**Parameters**
123
124| Parameter          | Type                                      | Mandatory | Description                         |
125| --------------- | ------------------------------------------ | ---- | -----------------------------|
126| primaries       | [ColorSpacePrimaries](#colorspaceprimaries)| Yes  | Primaries of the color space.              |
127| gamma           | number                                     | Yes  | Gamma of the color space.                |
128
129**Return value**
130
131| Type               | Description                    |
132| ------------------ | ------------------------ |
133| [ColorSpaceManager](#colorspacemanager)  | Color space object created.<br>The color space type is **CUSTOM** of [ColorSpace](#colorspace). |
134
135**Error codes**
136
137For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [colorSpaceManager Error Codes](errorcode-colorspace-manager.md).
138
139| ID | Error Message |
140| ------- | ----------------------- |
141| 401 | Parameter error. Possible cause: 1.Incorrect parameter type. 2.Parameter verification failed.|
142| 18600001 | The parameter value is abnormal. |
143
144**Example**
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
168Implements management of color space objects.
169
170Before calling any of the following APIs, you must use [create()](#colorspacemanagercreate) to create a color space manager.
171
172### getColorSpaceName
173
174getColorSpaceName(): ColorSpace
175
176Obtains the color space type.
177
178**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
179
180**Return value**
181
182| Type               | Description                    |
183| ------------------ | ------------------------ |
184| [ColorSpace](#colorspace)  | Color space type. |
185
186**Error codes**
187
188For details about the error codes, see [colorSpaceManager Error Codes](errorcode-colorspace-manager.md).
189
190| ID | Error Message |
191| ------- | ----------------------- |
192| 18600001 | The parameter value is abnormal. |
193
194**Example**
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
208Obtains the coordinates of the white point in the color space.
209
210**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
211
212**Return value**
213
214| Type               | Description                    |
215| ------------------ | ------------------------ |
216| Array\<number\>  | Coordinates [x, y] of the white point. |
217
218**Error codes**
219
220For details about the error codes, see [colorSpaceManager Error Codes](errorcode-colorspace-manager.md).
221
222| ID | Error Message |
223| ------- | ----------------------- |
224| 18600001 | The parameter value is abnormal. |
225
226**Example**
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
240Obtains the gamma of the color space.
241
242**System capability**: SystemCapability.Graphic.Graphic2D.ColorManager.Core
243
244**Return value**
245
246| Type               | Description                    |
247| ------------------ | ------------------------ |
248| number  | Gamma of the color space. |
249
250**Error codes**
251
252For details about the error codes, see [colorSpaceManager Error Codes](errorcode-colorspace-manager.md).
253
254| ID | Error Message |
255| ------- | ----------------------- |
256| 18600001 | The parameter value is abnormal. |
257
258**Example**
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```
267