// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only

#include "qabstractvideobuffer.h"

QT_BEGIN_NAMESPACE

/*!
    \class QAbstractVideoBuffer
    \since 6.8
    \brief The QAbstractVideoBuffer class is an abstraction for video data.
    \inmodule QtMultimedia
    \ingroup multimedia
    \ingroup multimedia_video

    The \l QVideoFrame class makes use of a QAbstractVideoBuffer internally to reference a buffer of
    video data. Creating a subclass of QAbstractVideoBuffer allows you to construct video
    frames from preallocated or static buffers. The subclass can contain a hardware buffer,
    and implement access to the data by mapping the buffer to CPU memory.

    The contents of a buffer can be accessed by mapping the buffer to memory using the map()
    function, which returns a structure containing information about plane layout of the current
    video data.

    \sa QVideoFrame, QVideoFrameFormat, QVideoFrame::MapMode
*/

/*!
    \class QAbstractVideoBuffer::MapData
    \brief The QAbstractVideoBuffer::MapData structure describes the mapped plane layout.
    \inmodule QtMultimedia
    \ingroup multimedia
    \ingroup multimedia_video

    The structure contains a number of mapped planes, and plane data for each plane,
    specificly, a number of bytes per line, a data pointer, and a data size.
    The structure doesn't hold any ownership of the data it refers to.

    A defaultly created structure means that no data has been mapped.

    All the values in the structure default to zeros.

    \sa QAbstractVideoBuffer::map
*/

/*!
    \variable QAbstractVideoBuffer::MapData::planeCount

    The number of planes of the mapped video data. If the format of the data
    is multiplanar, and the value is \c 1, the actual plane layout will
    be calculated upon invoking of \l QVideoFrame::map from the frame height,
    \c{bytesPerLine[0]}, and \c{dataSize[0]}.

    Defaults to \c 0.
*/

/*!
    \variable QAbstractVideoBuffer::MapData::bytesPerLine

    The array of numbrers of bytes per line for each
    plane from \c 0 to \c{planeCount - 1}.

    The values of the array default to \c 0.
*/

/*!
    \variable QAbstractVideoBuffer::MapData::data

    The array of pointers to the mapped video pixel data
    for each plane from \c 0 to \c{planeCount - 1}.
    The implementation of QAbstractVideoBuffer must hold ownership of the data
    at least until \l QAbstractVideoBuffer::unmap is called.

    The values of the array default to \c nullptr.
*/

/*!
    \variable QAbstractVideoBuffer::MapData::dataSize

    The array of sizes in bytes of the mapped video pixel data
    for each plane from \c 0 to \c{planeCount - 1}.

    The values of the array default to \c 0.
*/

// must be out-of-line to ensure correct working of dynamic_cast when QHwVideoBuffer is created in tests
/*!
    Destroys a video buffer.
*/
QAbstractVideoBuffer::~QAbstractVideoBuffer() = default;

/*! \fn QAbstractVideoBuffer::MapData QAbstractVideoBuffer::map(QVideoFrame::MapMode mode)

    Maps the planes of a video buffer to memory.

    Returns a \l MapData structure that contains information about the plane layout of
    the mapped current video data. If the mapping fails, the method returns the default structure.
    For CPU memory buffers, the data is considered as already mapped, so the function
    just returns the plane layout of the preallocated underlying data.

    The map \a mode indicates whether the contents of the mapped memory should be read from and/or
    written to the buffer.  If the map mode includes the \c QVideoFrame::ReadOnly flag the
    mapped memory will be populated with the content of the buffer when initially mapped.  If the map
    mode includes the \c QVideoFrame::WriteOnly flag the content of the possibly modified
    mapped memory will be written back to the buffer when unmapped.

    When access to the data is no longer needed, the \l unmap function is called
    to release the mapped memory and possibly update the buffer contents.

    If the format of the video data is multiplanar, the method may map the whole pixel data
    as a single plane. In this case, mapping a buffer with \l QVideoFrame
    will calculate additional planes from the specified line stride of the first plane,
    the frame height, and the data size.
*/

/*!
    \fn QAbstractVideoBuffer::unmap()

    Releases the memory mapped by the map() function.

    If the \l {QVideoFrame::MapMode}{MapMode} included the \c QVideoFrame::WriteOnly
    flag this will write the current content of the mapped memory back to the video frame.

    For CPU video buffers, the function may be not overridden.
    The default implementation of \c unmap does nothing.

    \sa map()
*/
void QAbstractVideoBuffer::unmap() { }

/*!
    \fn QAbstractVideoBuffer::format() const

    Gets \l QVideoFrameFormat of the underlying video buffer.

    The format must be available upon construction of \l QVideoFrame.
    QVideoFrame will contain won instance of the given format, that
    can be detached and modified.
*/

QT_END_NAMESPACE