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