Polish the video documentation a bit.

Change-Id: I7f76f710b64379ae6935cd86aed37914a7f85d0b
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>
Reviewed-by: Jonas Rabbe <jonas.rabbe@nokia.com>

1 files changed, 53 insertions, 25 deletions

diff --git a/src/multimedia/video/qvideoframe.cpp b/src/multimedia/video/qvideoframe.cpp
index a49814097..687716ac8 100644
--- a/src/multimedia/video/qvideoframe.cpp
+++ b/src/multimedia/video/qvideoframe.cpp
@@ -122,23 +122,33 @@ private:
 
 /*!
     \class QVideoFrame
-    \brief The QVideoFrame class provides a representation of a frame of video data.
+    \brief The QVideoFrame class represents a frame of video data.
     \since 1.0
     \inmodule QtMultimedia
 
-    A QVideoFrame encapsulates the data of a video frame, and information about the frame.
+    A QVideoFrame encapsulates the pixel data of a video frame, and information about the frame.
 
-    The contents of a video frame can be mapped to memory using the map() function.  While
+    Video frames can come from several places - decoded \l {QMediaPlayer}{media}, a
+    \l {QCamera}{camera}, or generated programmatically.  The way pixels are described in these
+    frames can vary greatly, and some pixel formats offer greater compression opportunities at
+    the expense of ease of use.
+
+    The pixel contents of a video frame can be mapped to memory using the map() function.  While
     mapped, the video data can accessed using the bits() function, which returns a pointer to a
-    buffer.  The total size of this buffer is given by the mappedBytes() function, and the size of each line is given
-    by bytesPerLine().  The return value of the handle() function may be used to access frame data
-    using the internal buffer's native APIs.
+    buffer.  The total size of this buffer is given by the mappedBytes() function, and the size of
+    each line is given by bytesPerLine().  The return value of the handle() function may also be
+    used to access frame data using the internal buffer's native APIs (for example - an OpenGL
+    texture handle).
+
+    A video frame can also have timestamp information associated with it.  These timestamps can be
+    used by an implementation of \l QAbstractVideoSurface to determine when to start and stop
+    displaying the frame, but not all surfaces might respect this setting.
 
-    The video data in a QVideoFrame is encapsulated in a QAbstractVideoBuffer.  A QVideoFrame
+    The video pixel data in a QVideoFrame is encapsulated in a QAbstractVideoBuffer.  A QVideoFrame
     may be constructed from any buffer type by subclassing the QAbstractVideoBuffer class.
 
-    \note QVideoFrame is explicitly shared, any change made to video frame will also apply to any
-    copies.
+    \note Since video frames can be expensive to copy, QVideoFrame is explicitly shared, so any
+    change made to a video frame will also apply to any copies.
 */
 
 /*!
@@ -174,10 +184,10 @@ private:
     QImage::Format_RGB555.
 
     \value Format_ARGB8565_Premultiplied
-    The frame is stored using a 24-bit premultiplied ARGB format (8-6-6-5).
+    The frame is stored using a 24-bit premultiplied ARGB format (8-5-6-5).
 
     \value Format_BGRA32
-    The frame is stored using a 32-bit ARGB format (0xBBGGRRAA).
+    The frame is stored using a 32-bit BGRA format (0xBBGGRRAA).
 
     \value Format_BGRA32_Premultiplied
     The frame is stored using a premultiplied 32bit BGRA format.
@@ -345,7 +355,8 @@ QVideoFrame::QVideoFrame(const QImage &image)
 }
 
 /*!
-    Constructs a copy of \a other.
+    Constructs a shallow copy of \a other.  Since QVideoFrame is
+    explicitly shared, these two instances will reflect the same frame.
 
     \since 1.0
 */
@@ -355,7 +366,9 @@ QVideoFrame::QVideoFrame(const QVideoFrame &other)
 }
 
 /*!
-    Assigns the contents of \a other to a video frame.
+    Assigns the contents of \a other to this video frame.  Since QVideoFrame is
+    explicitly shared, these two instances will reflect the same frame.
+
     \since 1.0
 */
 QVideoFrame &QVideoFrame::operator =(const QVideoFrame &other)
@@ -518,24 +531,32 @@ QAbstractVideoBuffer::MapMode QVideoFrame::mapMode() const
 }
 
 /*!
-    Maps the contents of a video frame to memory.
+    Maps the contents of a video frame to system (CPU addressable) memory.
+
+    In some cases the video frame data might be stored in video memory or otherwise inaccessible
+    memory, so it is necessary to map a frame before accessing the pixel data.  This may involve
+    copying the contents around, so avoid mapping and unmapping unless required.
 
     The map \a mode indicates whether the contents of the mapped memory should be read from and/or
-    written to the frame.  If the map mode includes the QAbstractVideoBuffer::ReadOnly flag the
-    mapped memory will be populated with the content of the video frame when mapped.  If the map
-    mode inclues the QAbstractVideoBuffer::WriteOnly flag the content of the mapped memory will be
-    persisted in the frame when unmapped.
+    written to the frame.  If the map mode includes the \c QAbstractVideoBuffer::ReadOnly flag the
+    mapped memory will be populated with the content of the video frame when initially mapped.  If the map
+    mode includes the \c QAbstractVideoBuffer::WriteOnly flag the content of the possibly modified
+    mapped memory will be written back to the frame when unmapped.
 
     While mapped the contents of a video frame can be accessed directly through the pointer returned
     by the bits() function.
 
-    When access to the data is no longer needed be sure to call the unmap() function to release the
+    When access to the data is no longer needed, be sure to call the unmap() function to release the
     mapped memory and possibly update the video frame contents.
 
-    If the video frame is mapped in read only mode, it's allowed to map it for reading again,
-    in all the other cases it's necessary to unmap the frame first.
+    If the video frame has been mapped in read only mode, it is permissible to map it
+    multiple times in read only mode (and unmap it a corresponding number of times). In all
+    other cases it is necessary to unmap the frame first before mapping a second time.
+
+    \note Writing to memory that is mapped as read-only is undefined, and may result in changes
+    to shared data or crashes.
 
-    Returns true if the buffer was mapped to memory in the given \a mode and false otherwise.
+    Returns true if the frame was mapped to memory in the given \a mode and false otherwise.
 
     \since 1.0
     \sa unmap(), mapMode(), bits()
@@ -612,8 +633,8 @@ void QVideoFrame::unmap()
 /*!
     Returns the number of bytes in a scan line.
 
-    \note This is the bytes per line of the first plane only.  The bytes per line of subsequent
-    planes should be calculated as per the frame type.
+    \note For planar formats this is the bytes per line of the first plane only.  The bytes per line of subsequent
+    planes should be calculated as per the frame \l{QVideoFrame::PixelFormat}{pixel format}.
 
     This value is only valid while the frame data is \l {map()}{mapped}.
 
@@ -631,7 +652,8 @@ int QVideoFrame::bytesPerLine() const
     This value is only valid while the frame data is \l {map()}{mapped}.
 
     Changes made to data accessed via this pointer (when mapped with write access)
-    are only guaranteed to have been persisted when unmap() is called.
+    are only guaranteed to have been persisted when unmap() is called and when the
+    buffer has been mapped for writing.
 
     \since 1.0
     \sa map(), mappedBytes(), bytesPerLine()
@@ -734,6 +756,9 @@ void QVideoFrame::setEndTime(qint64 time)
 /*!
     Returns a video pixel format equivalent to an image \a format.  If there is no equivalent
     format QVideoFrame::InvalidType is returned instead.
+
+    \note In general \l QImage does not handle YUV formats.
+
     \since 1.0
 */
 QVideoFrame::PixelFormat QVideoFrame::pixelFormatFromImageFormat(QImage::Format format)
@@ -761,6 +786,9 @@ QVideoFrame::PixelFormat QVideoFrame::pixelFormatFromImageFormat(QImage::Format
 /*!
     Returns an image format equivalent to a video frame pixel \a format.  If there is no equivalent
     format QImage::Format_Invalid is returned instead.
+
+    \note In general \l QImage does not handle YUV formats.
+
     \since 1.0
 */
 QImage::Format QVideoFrame::imageFormatFromPixelFormat(PixelFormat format)