Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | **************************** | |
4 | Defining Colorspaces in V4L2 | |
5 | **************************** | |
6 | ||
7 | In V4L2 colorspaces are defined by four values. The first is the | |
56683d7d | 8 | colorspace identifier (enum :c:type:`v4l2_colorspace`) |
5377d91f MH |
9 | which defines the chromaticities, the default transfer function, the |
10 | default Y'CbCr encoding and the default quantization method. The second | |
11 | is the transfer function identifier (enum | |
56683d7d | 12 | :c:type:`v4l2_xfer_func`) to specify non-standard |
5377d91f | 13 | transfer functions. The third is the Y'CbCr encoding identifier (enum |
56683d7d | 14 | :c:type:`v4l2_ycbcr_encoding`) to specify |
5377d91f | 15 | non-standard Y'CbCr encodings and the fourth is the quantization |
56683d7d | 16 | identifier (enum :c:type:`v4l2_quantization`) to |
5377d91f | 17 | specify non-standard quantization methods. Most of the time only the |
e8be7e97 MCC |
18 | colorspace field of struct :c:type:`v4l2_pix_format` |
19 | or struct :c:type:`v4l2_pix_format_mplane` | |
706f8a99 MCC |
20 | needs to be filled in. |
21 | ||
b6b6e678 MCC |
22 | .. note:: |
23 | ||
24 | The default R'G'B' quantization is full range for all | |
706f8a99 MCC |
25 | colorspaces except for BT.2020 which uses limited range R'G'B' |
26 | quantization. | |
5377d91f | 27 | |
83eaeb85 | 28 | .. tabularcolumns:: |p{6.0cm}|p{11.5cm}| |
5377d91f | 29 | |
56683d7d | 30 | .. c:type:: v4l2_colorspace |
5377d91f MH |
31 | |
32 | .. flat-table:: V4L2 Colorspaces | |
33 | :header-rows: 1 | |
34 | :stub-columns: 0 | |
35 | ||
36 | ||
37 | - .. row 1 | |
38 | ||
39 | - Identifier | |
40 | ||
41 | - Details | |
42 | ||
43 | - .. row 2 | |
44 | ||
45 | - ``V4L2_COLORSPACE_DEFAULT`` | |
46 | ||
47 | - The default colorspace. This can be used by applications to let | |
0579e6e3 | 48 | the driver fill in the colorspace. |
5377d91f MH |
49 | |
50 | - .. row 3 | |
51 | ||
52 | - ``V4L2_COLORSPACE_SMPTE170M`` | |
53 | ||
54 | - See :ref:`col-smpte-170m`. | |
55 | ||
56 | - .. row 4 | |
57 | ||
58 | - ``V4L2_COLORSPACE_REC709`` | |
59 | ||
60 | - See :ref:`col-rec709`. | |
61 | ||
62 | - .. row 5 | |
63 | ||
64 | - ``V4L2_COLORSPACE_SRGB`` | |
65 | ||
66 | - See :ref:`col-srgb`. | |
67 | ||
68 | - .. row 6 | |
69 | ||
70 | - ``V4L2_COLORSPACE_ADOBERGB`` | |
71 | ||
72 | - See :ref:`col-adobergb`. | |
73 | ||
74 | - .. row 7 | |
75 | ||
76 | - ``V4L2_COLORSPACE_BT2020`` | |
77 | ||
78 | - See :ref:`col-bt2020`. | |
79 | ||
80 | - .. row 8 | |
81 | ||
82 | - ``V4L2_COLORSPACE_DCI_P3`` | |
83 | ||
84 | - See :ref:`col-dcip3`. | |
85 | ||
86 | - .. row 9 | |
87 | ||
88 | - ``V4L2_COLORSPACE_SMPTE240M`` | |
89 | ||
90 | - See :ref:`col-smpte-240m`. | |
91 | ||
92 | - .. row 10 | |
93 | ||
94 | - ``V4L2_COLORSPACE_470_SYSTEM_M`` | |
95 | ||
96 | - See :ref:`col-sysm`. | |
97 | ||
98 | - .. row 11 | |
99 | ||
100 | - ``V4L2_COLORSPACE_470_SYSTEM_BG`` | |
101 | ||
102 | - See :ref:`col-sysbg`. | |
103 | ||
104 | - .. row 12 | |
105 | ||
106 | - ``V4L2_COLORSPACE_JPEG`` | |
107 | ||
108 | - See :ref:`col-jpeg`. | |
109 | ||
110 | - .. row 13 | |
111 | ||
112 | - ``V4L2_COLORSPACE_RAW`` | |
113 | ||
114 | - The raw colorspace. This is used for raw image capture where the | |
0579e6e3 MCC |
115 | image is minimally processed and is using the internal colorspace |
116 | of the device. The software that processes an image using this | |
117 | 'colorspace' will have to know the internals of the capture | |
118 | device. | |
5377d91f MH |
119 | |
120 | ||
121 | ||
56683d7d | 122 | .. c:type:: v4l2_xfer_func |
5377d91f MH |
123 | |
124 | .. flat-table:: V4L2 Transfer Function | |
125 | :header-rows: 1 | |
126 | :stub-columns: 0 | |
127 | ||
128 | ||
129 | - .. row 1 | |
130 | ||
131 | - Identifier | |
132 | ||
133 | - Details | |
134 | ||
135 | - .. row 2 | |
136 | ||
137 | - ``V4L2_XFER_FUNC_DEFAULT`` | |
138 | ||
139 | - Use the default transfer function as defined by the colorspace. | |
140 | ||
141 | - .. row 3 | |
142 | ||
143 | - ``V4L2_XFER_FUNC_709`` | |
144 | ||
145 | - Use the Rec. 709 transfer function. | |
146 | ||
147 | - .. row 4 | |
148 | ||
149 | - ``V4L2_XFER_FUNC_SRGB`` | |
150 | ||
151 | - Use the sRGB transfer function. | |
152 | ||
153 | - .. row 5 | |
154 | ||
155 | - ``V4L2_XFER_FUNC_ADOBERGB`` | |
156 | ||
157 | - Use the AdobeRGB transfer function. | |
158 | ||
159 | - .. row 6 | |
160 | ||
161 | - ``V4L2_XFER_FUNC_SMPTE240M`` | |
162 | ||
163 | - Use the SMPTE 240M transfer function. | |
164 | ||
165 | - .. row 7 | |
166 | ||
167 | - ``V4L2_XFER_FUNC_NONE`` | |
168 | ||
169 | - Do not use a transfer function (i.e. use linear RGB values). | |
170 | ||
171 | - .. row 8 | |
172 | ||
173 | - ``V4L2_XFER_FUNC_DCI_P3`` | |
174 | ||
175 | - Use the DCI-P3 transfer function. | |
176 | ||
177 | - .. row 9 | |
178 | ||
179 | - ``V4L2_XFER_FUNC_SMPTE2084`` | |
180 | ||
181 | - Use the SMPTE 2084 transfer function. | |
182 | ||
183 | ||
184 | ||
56683d7d | 185 | .. c:type:: v4l2_ycbcr_encoding |
5377d91f | 186 | |
83eaeb85 MCC |
187 | .. tabularcolumns:: |p{6.5cm}|p{11.0cm}| |
188 | ||
5377d91f MH |
189 | .. flat-table:: V4L2 Y'CbCr Encodings |
190 | :header-rows: 1 | |
191 | :stub-columns: 0 | |
192 | ||
193 | ||
194 | - .. row 1 | |
195 | ||
196 | - Identifier | |
197 | ||
198 | - Details | |
199 | ||
200 | - .. row 2 | |
201 | ||
202 | - ``V4L2_YCBCR_ENC_DEFAULT`` | |
203 | ||
204 | - Use the default Y'CbCr encoding as defined by the colorspace. | |
205 | ||
206 | - .. row 3 | |
207 | ||
208 | - ``V4L2_YCBCR_ENC_601`` | |
209 | ||
210 | - Use the BT.601 Y'CbCr encoding. | |
211 | ||
212 | - .. row 4 | |
213 | ||
214 | - ``V4L2_YCBCR_ENC_709`` | |
215 | ||
216 | - Use the Rec. 709 Y'CbCr encoding. | |
217 | ||
218 | - .. row 5 | |
219 | ||
220 | - ``V4L2_YCBCR_ENC_XV601`` | |
221 | ||
222 | - Use the extended gamut xvYCC BT.601 encoding. | |
223 | ||
224 | - .. row 6 | |
225 | ||
226 | - ``V4L2_YCBCR_ENC_XV709`` | |
227 | ||
228 | - Use the extended gamut xvYCC Rec. 709 encoding. | |
229 | ||
230 | - .. row 7 | |
231 | ||
5377d91f MH |
232 | - ``V4L2_YCBCR_ENC_BT2020`` |
233 | ||
234 | - Use the default non-constant luminance BT.2020 Y'CbCr encoding. | |
235 | ||
dda3aeaa | 236 | - .. row 8 |
5377d91f MH |
237 | |
238 | - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` | |
239 | ||
240 | - Use the constant luminance BT.2020 Yc'CbcCrc encoding. | |
0a07ab9a | 241 | |
dda3aeaa | 242 | - .. row 9 |
0a07ab9a HV |
243 | |
244 | - ``V4L2_YCBCR_ENC_SMPTE_240M`` | |
245 | ||
246 | - Use the SMPTE 240M Y'CbCr encoding. | |
5377d91f MH |
247 | |
248 | ||
249 | ||
56683d7d | 250 | .. c:type:: v4l2_quantization |
5377d91f | 251 | |
83eaeb85 MCC |
252 | .. tabularcolumns:: |p{6.5cm}|p{11.0cm}| |
253 | ||
5377d91f MH |
254 | .. flat-table:: V4L2 Quantization Methods |
255 | :header-rows: 1 | |
256 | :stub-columns: 0 | |
257 | ||
258 | ||
259 | - .. row 1 | |
260 | ||
261 | - Identifier | |
262 | ||
263 | - Details | |
264 | ||
265 | - .. row 2 | |
266 | ||
267 | - ``V4L2_QUANTIZATION_DEFAULT`` | |
268 | ||
269 | - Use the default quantization encoding as defined by the | |
0579e6e3 MCC |
270 | colorspace. This is always full range for R'G'B' (except for the |
271 | BT.2020 colorspace) and usually limited range for Y'CbCr. | |
5377d91f MH |
272 | |
273 | - .. row 3 | |
274 | ||
275 | - ``V4L2_QUANTIZATION_FULL_RANGE`` | |
276 | ||
277 | - Use the full range quantization encoding. I.e. the range [0…1] is | |
0579e6e3 MCC |
278 | mapped to [0…255] (with possible clipping to [1…254] to avoid the |
279 | 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to | |
280 | [0…255] (with possible clipping to [1…254] to avoid the 0x00 and | |
281 | 0xff values). | |
5377d91f MH |
282 | |
283 | - .. row 4 | |
284 | ||
285 | - ``V4L2_QUANTIZATION_LIM_RANGE`` | |
286 | ||
287 | - Use the limited range quantization encoding. I.e. the range [0…1] | |
0579e6e3 MCC |
288 | is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to |
289 | [16…240]. |