1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qpixelformat.h"
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 \class QPixelFormat
10 \inmodule QtGui
11 \since 5.4
12 \brief QPixelFormat is a class for describing different pixel
13 layouts in graphics buffers.
14
15 In Qt there is a often a need to represent the layout of the pixels in a
16 graphics buffer. Internally QPixelFormat stores everything in a 64 bit
17 datastructure. This gives performance but also some limitations.
18
19 QPixelFormat can describe 5 color channels and 1 alpha channel, each can use
20 6 bits to describe the size of the color channel.
21
22 The position of the alpha channel is described with a separate enum. This is
23 to make it possible to describe QImage formats like ARGB32, and also
24 describe typical OpenGL formats like RBGA8888.
25
26 How pixels are suppose to be read is determined by the TypeInterpretation
27 enum. It describes if color values are suppose to be read byte per byte,
28 or if a pixel is suppose to be read as a complete int and then masked.
29 \sa TypeInterpretation
30
31 There is no support for describing YUV's macro pixels. Instead a list of YUV
32 formats has been made. When a QPixelFormat is describing a YUV format, the
33 bitsPerPixel value has been deduced by the YUV Layout enum. Also, the color
34 channels should all be set to zero except the fifth color channel that
35 should store the bitsPerPixel value.
36*/
37
38/*!
39 \enum QPixelFormat::ColorModel
40
41 This enum type is used to describe the color model of the pixelformat.
42 Alpha was added in 5.5.
43
44 \value RGB The color model is RGB.
45
46 \value BGR This is logically the opposite endian version of RGB. However,
47 for ease of use it has its own model.
48
49 \value Indexed The color model uses a color palette.
50
51 \value Grayscale The color model is Grayscale.
52
53 \value CMYK The color model is CMYK.
54
55 \value HSL The color model is HSL.
56
57 \value HSV The color model is HSV.
58
59 \value YUV The color model is YUV.
60
61 \value Alpha There is no color model, only alpha is used.
62*/
63
64/*!
65 \enum QPixelFormat::AlphaUsage
66
67 This enum describes if the alpha channel is used or not. Sometimes the
68 pixelformat will have a size for the alpha channel, but the pixel format
69 does actually not use the alpha channel. For example RGB32 is such a
70 format. The RGB channels are 8 bits each, and there is no alpha channel.
71 But the complete size for each pixel is 32. Therefore the alpha channel size
72 is 8, but the alpha channel is ignored. Its important to note that in such
73 situations the position of the alpha channel is significant.
74
75 \value IgnoresAlpha The alpha channel is not used.
76
77 \value UsesAlpha The alpha channel is used.
78*/
79
80/*!
81 \enum QPixelFormat::AlphaPosition
82
83 This enum type is used to describe the alpha channels position relative to the
84 color channels.
85
86 \value AtBeginning The alpha channel will be put in front of the color
87 channels . E.g. ARGB.
88
89 \value AtEnd The alpha channel will be put in the back of the color
90 channels. E.g. RGBA.
91*/
92
93/*!
94 \enum QPixelFormat::AlphaPremultiplied
95
96 This enum type describes the boolean state if the alpha channel is multiplied
97 into the color channels or not.
98
99 \value NotPremultiplied The alpha channel is not multiplied into the color channels.
100
101 \value Premultiplied The alpha channel is multiplied into the color channels.
102*/
103
104/*!
105 \enum QPixelFormat::TypeInterpretation
106
107 This enum describes how each pixel is interpreted. If a pixel is read as a
108 full 32 bit unsigned integer and then each channel is masked out, or if
109 each byte is read as unsigned char values. Typically QImage formats
110 interpret one pixel as an unsigned integer and then the color channels are
111 masked out. OpenGL on the other hand typically interpreted pixels "one byte
112 after the other", Ie. unsigned byte.
113
114 QImage also have the format Format_RGBA8888 (and its derivatives), where
115 the pixels are interpreted as unsigned bytes. OpenGL has extensions that makes it
116 possible to upload pixel buffers in an unsigned integer format.
117
118 \image qpixelformat-argb32buffer.png An unsigned integer ARGB32 pixel.
119
120 The image above shows a ARGB pixel in memory read as an unsigned integer.
121 However, if this pixel was read byte for byte on a little endian system the
122 first byte would be the byte containing the B-channel. The next byte would
123 be the G-channel, then the R-channel and finally the A-channel. This shows
124 that on little endian systems, how each pixel is interpreted is significant
125 for integer formats. This is not the case on big endian systems.
126
127 \value UnsignedInteger
128 \value UnsignedShort
129 \value UnsignedByte
130 \value FloatingPoint
131*/
132
133/*!
134 \enum QPixelFormat::ByteOrder
135
136 This enum describes the ByteOrder of the pixel format. This enum is mostly
137 ignored but have some use cases for YUV formats. BGR formats have their own
138 color model, and should not be described by using the opposite endianness
139 on an RGB format.
140
141 \value LittleEndian The byte order is little endian.
142 \value BigEndian The byte order is big endian.
143 \value CurrentSystemEndian This enum will not be stored, but is converted in
144 the constructor to the endian enum that matches
145 the enum of the current system.
146
147*/
148
149/*!
150 \enum QPixelFormat::YUVLayout
151
152 YUV is not represented by describing the size of the color channels. This is
153 because YUV often use macro pixels, making the concept of separate color channels
154 invalid. Instead the different YUV layouts are described with this enum.
155
156 \value YUV444
157 \value YUV422
158 \value YUV411
159 \value YUV420P
160 \value YUV420SP
161 \value YV12
162 \value UYVY
163 \value YUYV
164 \value NV12
165 \value NV21
166 \value IMC1
167 \value IMC2
168 \value IMC3
169 \value IMC4
170 \value Y8
171 \value Y16
172*/
173
174/*!
175 \fn QPixelFormat::QPixelFormat()
176
177 Creates a null pixelformat. This format maps to QImage::Format_Invalid.
178*/
179
180/*!
181 \fn QPixelFormat::QPixelFormat(ColorModel colorModel,
182 uchar firstSize,
183 uchar secondSize,
184 uchar thirdSize,
185 uchar fourthSize,
186 uchar fifthSize,
187 uchar alphaSize,
188 AlphaUsage alphaUsage,
189 AlphaPosition alphaPosition,
190 AlphaPremultiplied premultiplied,
191 TypeInterpretation typeInterpretation,
192 ByteOrder byteOrder = CurrentSystemEndian,
193 uchar subEnum = 0)
194
195 Creates a QPixelFormat which assigns its data to the attributes.
196 \a colorModel will be put into a buffer which is 4 bits long.
197
198 \a firstSize \a secondSize \a thirdSize \a fourthSize \a fifthSize \a
199 alphaSize are all meant to represent the size of a channel. The channels will
200 be used for different uses dependent on the \a colorModel. For RGB the
201 firstSize will represent the Red channel. On CMYK it will represent the
202 value of the Cyan channel.
203
204 \a alphaUsage represents if the alpha channel is used or not.
205
206 \a alphaPosition is the position of the alpha channel.
207
208 \a premultiplied represents if the alpha channel is already multiplied with
209 the color channels.
210
211 \a typeInterpretation is how the pixel is interpreted.
212
213 \a byteOrder represents the endianness of the pixelformat. This defaults to
214 CurrentSystemEndian.
215
216 \a subEnum is used for colorModels that have to store some extra
217 information with supplying an extra enum. This is used by YUV to store the
218 YUV type The default value is 0.
219*/
220
221/*!
222 \fn QPixelFormat qPixelFormatRgba(uchar redSize,
223 uchar greenSize,
224 uchar blueSize,
225 uchar alphaSize,
226 QPixelFormat::AlphaUsage alphaUsage,
227 QPixelFormat::AlphaPosition alphaPosition,
228 QPixelFormat::AlphaPremultiplied premultiplied = QPixelFormat::NotPremultiplied,
229 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
230 \relates QPixelFormat
231
232 Constructor function making an RGB pixelformat. \a redSize \a greenSize \a
233 blueSize represent the size of each color channel. \a alphaSize describes
234 the alpha channel size and its position is described with \a alphaPosition.
235 \a alphaUsage is used to determine if the alpha channel is used or not.
236 Setting the alpha channel size to 8 and alphaUsage to IgnoresAlpha is how
237 it is possible to create a 32 bit format where the rgb channels only use 24
238 bits combined. \a premultiplied \a typeInterpretation are
239 accessible with accessors with the same name.
240
241 \sa QPixelFormat::TypeInterpretation
242*/
243
244/*!
245 \fn QPixelFormat qPixelFormatGrayscale(uchar channelSize,
246 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
247 \relates QPixelFormat
248
249 Constructor function for creating a Grayscale format. Monochrome formats can be
250 described by passing 1 to \a channelSize. Its also possible to define very
251 accurate grayscale formats using doubles to describe each pixel by passing 8
252 as \a channelSize and FloatingPoint as \a typeInterpretation.
253
254 \sa QPixelFormat::TypeInterpretation
255*/
256
257/*!
258 \fn QPixelFormat qPixelFormatAlpha(uchar channelSize,
259 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
260 \relates QPixelFormat
261 \since 5.5
262
263 Constructor function for creating an Alpha format. A mask format can be
264 described by passing 1 to \a channelSize. Its also possible to define very
265 accurate alpha formats using doubles to describe each pixel by passing 8
266 as \a channelSize and FloatingPoint as \a typeInterpretation.
267
268 \sa QPixelFormat::TypeInterpretation
269*/
270
271
272/*!
273 \fn QPixelFormat qPixelFormatCmyk(uchar channelSize,
274 uchar alphaSize = 0,
275 QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
276 QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
277 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
278 \relates QPixelFormat
279
280 Constructor function for creating CMYK formats. The channel count will be 4 or
281 5 depending on if \a alphaSize is bigger than zero or not. The CMYK color
282 channels will all be set to the value of \a channelSize.
283
284 \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
285 the accessors with the same name.
286
287 \sa QPixelFormat::TypeInterpretation
288*/
289
290/*!
291 \fn QPixelFormat qPixelFormatHsl(uchar channelSize,
292 uchar alphaSize = 0,
293 QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
294 QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
295 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
296 \relates QPixelFormat
297
298 Constructor function for creating HSL formats. The channel count will be 3 or 4
299 depending on if \a alphaSize is bigger than 0.
300
301 \a channelSize will set the hueSize saturationSize and lightnessSize to the same value.
302
303 \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
304 the accessors with the same name.
305*/
306
307/*!
308 \fn QPixelFormat qPixelFormatHsv(uchar channelSize,
309 uchar alphaSize = 0,
310 QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
311 QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
312 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
313 \relates QPixelFormat
314
315 Constructor function for creating HSV formats. The channel count will be 3 or 4
316 depending on if \a alphaSize is bigger than 0.
317
318 \a channelSize will set the hueSize saturationSize and brightnessSize to the same value.
319
320 \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
321 the accessors with the same name.
322*/
323
324/*!
325 \fn QPixelFormat qPixelFormatYuv(QPixelFormat::YUVLayout yuvLayout,
326 uchar alphaSize = 0,
327 QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
328 QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
329 QPixelFormat::AlphaPremultiplied premultiplied = QPixelFormat::NotPremultiplied,
330 QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedByte,
331 QPixelFormat::ByteOrder byteOrder = QPixelFormat::LittleEndian)
332 \relates QPixelFormat
333
334 Constructor function for creating a QPixelFormat describing a YUV format with
335 \a yuvLayout. \a alphaSize describes the size of a potential alpha channel
336 and is position is described with \a alphaPosition. The "first" "second" ..
337 "fifth" channels are all set to 0. \a alphaUsage \a premultiplied \a
338 typeInterpretation and \a byteOrder will work as with other formats.
339*/
340
341/*!
342 \fn ColorModel QPixelFormat::colorModel() const
343
344 Accessor function for getting the colorModel.
345*/
346
347/*!
348 \fn uchar QPixelFormat::channelCount() const
349
350 Accessor function for getting the channelCount. Channel Count is deduced
351 by color channels with a size > 0 and if the size of the alpha channel is > 0.
352*/
353
354/*!
355 \fn uchar QPixelFormat::redSize() const
356
357 Accessor function for the size of the red color channel.
358*/
359
360/*!
361 \fn uchar QPixelFormat::greenSize() const
362
363 Accessor function for the size of the green color channel.
364*/
365
366/*!
367 \fn uchar QPixelFormat::blueSize() const
368
369 Accessor function for the size of the blue color channel.
370*/
371
372/*!
373 \fn uchar QPixelFormat::cyanSize() const
374
375 Accessor function for the cyan color channel.
376*/
377
378/*!
379 \fn uchar QPixelFormat::magentaSize() const
380
381 Accessor function for the megenta color channel.
382*/
383
384/*!
385 \fn uchar QPixelFormat::yellowSize() const
386
387 Accessor function for the yellow color channel.
388*/
389
390/*!
391 \fn uchar QPixelFormat::blackSize() const
392
393 Accessor function for the black/key color channel.
394*/
395
396/*!
397 \fn uchar QPixelFormat::hueSize() const
398
399 Accessor function for the hue channel size.
400*/
401
402/*!
403 \fn uchar QPixelFormat::saturationSize() const
404
405 Accessor function for the saturation channel size.
406*/
407
408/*!
409 \fn uchar QPixelFormat::lightnessSize() const
410
411 Accessor function for the lightness channel size.
412*/
413
414/*!
415 \fn uchar QPixelFormat::brightnessSize() const
416
417 Accessor function for the brightness channel size.
418*/
419
420/*!
421 \fn uchar QPixelFormat::alphaSize() const
422
423 Accessor function for the alpha channel size.
424*/
425
426/*!
427 \fn uchar QPixelFormat::bitsPerPixel() const
428
429 Accessor function for the bits used per pixel. This function returns the
430 sum of the color channels + the size of the alpha channel.
431*/
432
433/*!
434 \fn AlphaPremultiplied QPixelFormat::premultiplied() const
435
436 Accessor function for the AlphaPremultiplied enum. This indicates if the
437 alpha channel is multiplied in to the color channels.
438
439*/
440
441/*!
442 \fn TypeInterpretation QPixelFormat::typeInterpretation() const
443
444 Accessor function for the type representation of a color channel or a pixel.
445
446 \sa TypeInterpretation
447*/
448
449/*!
450 \fn ByteOrder QPixelFormat::byteOrder() const
451
452 The byte order is almost always set the byte order of the current
453 system. However, it can be useful to describe some YUV formats. This
454 function should never return QPixelFormat::CurrentSystemEndian as this
455 value is translated to a endian value in the constructor.
456*/
457
458/*!
459 \fn AlphaUsage QPixelFormat::alphaUsage() const
460
461 Accessor function for alphaUsage.
462*/
463
464/*!
465 \fn AlphaPosition QPixelFormat::alphaPosition() const
466
467 Accessor function for alphaPosition.
468*/
469
470/*!
471 \fn YUVLayout QPixelFormat::yuvLayout() const
472
473 Accessor function for the YUVLayout. It is difficult to describe the color
474 channels of a YUV pixel format since YUV color model uses macro pixels.
475 Instead the layout of the pixels are stored as an enum.
476*/
477
478/*!
479 \fn uchar QPixelFormat::subEnum() const
480
481 Accessor for the datapart which contains subEnums
482 This is the same as the yuvLayout() function.
483
484 \sa yuvLayout()
485 \internal
486*/
487
488static_assert(sizeof(QPixelFormat) == sizeof(quint64));
489
490
491namespace QtPrivate {
492 QPixelFormat QPixelFormat_createYUV(QPixelFormat::YUVLayout yuvLayout,
493 uchar alphaSize,
494 QPixelFormat::AlphaUsage alphaUsage,
495 QPixelFormat::AlphaPosition alphaPosition,
496 QPixelFormat::AlphaPremultiplied premultiplied,
497 QPixelFormat::TypeInterpretation typeInterpretation,
498 QPixelFormat::ByteOrder byteOrder)
499 {
500 uchar bits_per_pixel = 0;
501 switch (yuvLayout) {
502 case QPixelFormat::YUV444:
503 bits_per_pixel = 24;
504 break;
505 case QPixelFormat::YUV422:
506 bits_per_pixel = 16;
507 break;
508 case QPixelFormat::YUV411:
509 case QPixelFormat::YUV420P:
510 case QPixelFormat::YUV420SP:
511 case QPixelFormat::YV12:
512 bits_per_pixel = 12;
513 break;
514 case QPixelFormat::UYVY:
515 case QPixelFormat::YUYV:
516 bits_per_pixel = 16;
517 break;
518 case QPixelFormat::NV12:
519 case QPixelFormat::NV21:
520 bits_per_pixel = 12;
521 break;
522 case QPixelFormat::IMC1:
523 case QPixelFormat::IMC2:
524 case QPixelFormat::IMC3:
525 case QPixelFormat::IMC4:
526 bits_per_pixel = 12;
527 break;
528 case QPixelFormat::Y8:
529 bits_per_pixel = 8;
530 break;
531 case QPixelFormat::Y16:
532 bits_per_pixel = 16;
533 break;
534 }
535
536 return QPixelFormat(QPixelFormat::YUV,
537 0, 0, 0, 0,
538 bits_per_pixel,
539 alphaSize,
540 alphaUsage,
541 alphaPosition,
542 premultiplied,
543 typeInterpretation,
544 byteOrder,
545 yuvLayout);
546 }
547}
548
549QT_END_NAMESPACE
550

source code of qtbase/src/gui/kernel/qpixelformat.cpp