Document QOpenGLPixelTransferOptions

Task-number: QTBUG-35576
Change-Id: I178f5db5f1075b6a395cf8ff73b75fe1765540aa
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

1 files changed, 93 insertions, 0 deletions

diff --git a/src/gui/opengl/qopenglpixeltransferoptions.cpp b/src/gui/opengl/qopenglpixeltransferoptions.cpp
index 4f72b43f37..9ea2e0ecc1 100644
--- a/src/gui/opengl/qopenglpixeltransferoptions.cpp
+++ b/src/gui/opengl/qopenglpixeltransferoptions.cpp
@@ -36,6 +36,23 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+ * \class QOpenGLPixelTransferOptions
+ *
+ * \brief The QOpenGLPixelTransferOptions class describes the pixel storage
+ * modes that affect the unpacking of pixels during texture upload.
+ */
+
+/*!
+ * \fn QOpenGLPixelTransferOptions & QOpenGLPixelTransferOptions::operator=(QOpenGLPixelTransferOptions &&other)
+ * \internal
+ */
+
+/*!
+ * \fn void QOpenGLPixelTransferOptions::swap(QOpenGLPixelTransferOptions &other)
+ * \internal
+ */
+
 class QOpenGLPixelTransferOptionsData : public QSharedData
 {
 public:
@@ -60,16 +77,25 @@ public:
     bool swapBytes;
 };
 
+/*!
+ * Constructs a new QOpenGLPixelTransferOptions instance with the default settings.
+ */
 QOpenGLPixelTransferOptions::QOpenGLPixelTransferOptions()
     : data(new QOpenGLPixelTransferOptionsData)
 {
 }
 
+/*!
+ * \internal
+ */
 QOpenGLPixelTransferOptions::QOpenGLPixelTransferOptions(const QOpenGLPixelTransferOptions &rhs)
     : data(rhs.data)
 {
 }
 
+/*!
+ * \internal
+ */
 QOpenGLPixelTransferOptions &QOpenGLPixelTransferOptions::operator=(const QOpenGLPixelTransferOptions &rhs)
 {
     if (this != &rhs)
@@ -77,85 +103,152 @@ QOpenGLPixelTransferOptions &QOpenGLPixelTransferOptions::operator=(const QOpenG
     return *this;
 }
 
+/*!
+ * Destructor.
+ */
 QOpenGLPixelTransferOptions::~QOpenGLPixelTransferOptions()
 {
 }
 
+/*!
+ * Sets the \a alignment requirements for each pixel row. Corresponds to \c GL_UNPACK_ALIGNMENT.
+ * The default value is 4, as specified by OpenGL.
+ */
 void QOpenGLPixelTransferOptions::setAlignment(int alignment)
 {
     data->alignment = alignment;
 }
 
+/*!
+ * \return the current alignment requirement for each pixel row.
+ */
 int QOpenGLPixelTransferOptions::alignment() const
 {
     return data->alignment;
 }
 
+/*!
+ * Sets the number of images that are skipped to \a skipImages.
+ * Corresponds to \c GL_UNPACK_SKIP_IMAGES. Equivalent to incrementing the pointer
+ * passed to QOpenGLTexture::setData(). The default value is 0.
+ */
 void QOpenGLPixelTransferOptions::setSkipImages(int skipImages)
 {
     data->skipImages = skipImages;
 }
 
+/*!
+ * \return the number of images that are skipped.
+ */
 int QOpenGLPixelTransferOptions::skipImages() const
 {
     return data->skipImages;
 }
 
+/*!
+ * Sets the number of rows that are skipped to \a skipRows.
+ * Corresponds to \c GL_UNPACK_SKIP_ROWS. Equivalent to incrementing the pointer
+ * passed to QOpenGLTexture::setData(). The default value is 0.
+ */
 void QOpenGLPixelTransferOptions::setSkipRows(int skipRows)
 {
     data->skipRows = skipRows;
 }
 
+/*!
+ * \return the number of rows that are skipped.
+ */
 int QOpenGLPixelTransferOptions::skipRows() const
 {
     return data->skipRows;
 }
 
+/*!
+ * Sets the number of pixels that are skipped to \a skipPixels.
+ * Corresponds to \c GL_UNPACK_SKIP_PIXELS. Equivalent to incrementing the pointer
+ * passed to QOpenGLTexture::setData(). The default value is 0.
+ */
 void QOpenGLPixelTransferOptions::setSkipPixels(int skipPixels)
 {
     data->skipPixels = skipPixels;
 }
 
+/*!
+ * \return the number of pixels that are skipped.
+ */
 int QOpenGLPixelTransferOptions::skipPixels() const
 {
     return data->skipPixels;
 }
 
+/*!
+ * Sets the image height for 3D textures to \a imageHeight.
+ * Corresponds to \c GL_UNPACK_IMAGE_HEIGHT.
+ * The default value is 0.
+ */
 void QOpenGLPixelTransferOptions::setImageHeight(int imageHeight)
 {
     data->imageHeight = imageHeight;
 }
 
+/*!
+ * \return the currently set image height.
+ */
 int QOpenGLPixelTransferOptions::imageHeight() const
 {
     return data->imageHeight;
 }
 
+/*!
+ * Sets the number of pixels in a row to \a rowLength.
+ * Corresponds to \c GL_UNPACK_ROW_LENGTH.
+ * The default value is 0.
+ */
 void QOpenGLPixelTransferOptions::setRowLength(int rowLength)
 {
     data->rowLength = rowLength;
 }
 
+/*!
+ * \return the currently set row length.
+ */
 int QOpenGLPixelTransferOptions::rowLength() const
 {
     return data->rowLength;
 }
 
+/*!
+ * \a lsbFirst specifies if bits within a byte are ordered from least to most significat.
+ * The default value is \c false, meaning that the first bit in each byte is the
+ * most significant one. This is significant for bitmap data only.
+ * Corresponds to \c GL_UNPACK_LSB_FIRST.
+ */
 void QOpenGLPixelTransferOptions::setLeastSignificantByteFirst(bool lsbFirst)
 {
     data->lsbFirst = lsbFirst;
 }
 
+/*!
+ * \return \c true if bits within a byte are ordered from least to most significant.
+ */
 bool QOpenGLPixelTransferOptions::isLeastSignificantBitFirst() const
 {
     return data->lsbFirst;
 }
 
+/*!
+ * \a swapBytes specifies if the byte ordering for multibyte components is reversed.
+ * The default value is \c false.
+ * Corresponds to \c GL_UNPACK_SWAP_BYTES.
+ */
 void QOpenGLPixelTransferOptions::setSwapBytesEnabled(bool swapBytes)
 {
     data->swapBytes = swapBytes;
 }
 
+/*!
+ * \return \c true if the byte ordering for multibyte components is reversed.
+ */
 bool QOpenGLPixelTransferOptions::isSwapBytesEnabled() const
 {
     return data->swapBytes;