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 42 QT_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 524 Q_STATIC_ASSERT(sizeof(QPixelFormat) == sizeof(quint64)); 525 526 527 namespace QtPrivate { QPixelFormat_createYUV(QPixelFormat::YUVLayout yuvLayout,uchar alphaSize,QPixelFormat::AlphaUsage alphaUsage,QPixelFormat::AlphaPosition alphaPosition,QPixelFormat::AlphaPremultiplied premultiplied,QPixelFormat::TypeInterpretation typeInterpretation,QPixelFormat::ByteOrder byteOrder)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 585 QT_END_NAMESPACE 586