1// Copyright (C) 2024 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qabstractvideobuffer.h"
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 \class QAbstractVideoBuffer
10 \since 6.8
11 \brief The QAbstractVideoBuffer class is an abstraction for video data.
12 \inmodule QtMultimedia
13 \ingroup multimedia
14 \ingroup multimedia_video
15
16 The \l QVideoFrame class makes use of a QAbstractVideoBuffer internally to reference a buffer of
17 video data. Creating a subclass of QAbstractVideoBuffer allows you to construct video
18 frames from preallocated or static buffers. The subclass can contain a hardware buffer,
19 and implement access to the data by mapping the buffer to CPU memory.
20
21 The contents of a buffer can be accessed by mapping the buffer to memory using the map()
22 function, which returns a structure containing information about plane layout of the current
23 video data.
24
25 \sa QVideoFrame, QVideoFrameFormat, QVideoFrame::MapMode
26*/
27
28/*!
29 \class QAbstractVideoBuffer::MapData
30 \brief The QAbstractVideoBuffer::MapData structure describes the mapped plane layout.
31 \inmodule QtMultimedia
32 \ingroup multimedia
33 \ingroup multimedia_video
34
35 The structure contains a number of mapped planes, and plane data for each plane,
36 specificly, a number of bytes per line, a data pointer, and a data size.
37 The structure doesn't hold any ownership of the data it refers to.
38
39 A defaultly created structure means that no data has been mapped.
40
41 All the values in the structure default to zeros.
42
43 \sa QAbstractVideoBuffer::map
44*/
45
46/*!
47 \variable QAbstractVideoBuffer::MapData::planeCount
48
49 The number of planes of the mapped video data. If the format of the data
50 is multiplanar, and the value is \c 1, the actual plane layout will
51 be calculated upon invoking of \l QVideoFrame::map from the frame height,
52 \c{bytesPerLine[0]}, and \c{dataSize[0]}.
53
54 Defaults to \c 0.
55*/
56
57/*!
58 \variable QAbstractVideoBuffer::MapData::bytesPerLine
59
60 The array of numbrers of bytes per line for each
61 plane from \c 0 to \c{planeCount - 1}.
62
63 The values of the array default to \c 0.
64*/
65
66/*!
67 \variable QAbstractVideoBuffer::MapData::data
68
69 The array of pointers to the mapped video pixel data
70 for each plane from \c 0 to \c{planeCount - 1}.
71 The implementation of QAbstractVideoBuffer must hold ownership of the data
72 at least until \l QAbstractVideoBuffer::unmap is called.
73
74 The values of the array default to \c nullptr.
75*/
76
77/*!
78 \variable QAbstractVideoBuffer::MapData::dataSize
79
80 The array of sizes in bytes of the mapped video pixel data
81 for each plane from \c 0 to \c{planeCount - 1}.
82
83 The values of the array default to \c 0.
84*/
85
86// must be out-of-line to ensure correct working of dynamic_cast when QHwVideoBuffer is created in tests
87/*!
88 Destroys a video buffer.
89*/
90QAbstractVideoBuffer::~QAbstractVideoBuffer() = default;
91
92/*! \fn QAbstractVideoBuffer::MapData QAbstractVideoBuffer::map(QVideoFrame::MapMode mode)
93
94 Maps the planes of a video buffer to memory.
95
96 Returns a \l MapData structure that contains information about the plane layout of
97 the mapped current video data. If the mapping fails, the method returns the default structure.
98 For CPU memory buffers, the data is considered as already mapped, so the function
99 just returns the plane layout of the preallocated underlying data.
100
101 The map \a mode indicates whether the contents of the mapped memory should be read from and/or
102 written to the buffer. If the map mode includes the \c QVideoFrame::ReadOnly flag the
103 mapped memory will be populated with the content of the buffer when initially mapped. If the map
104 mode includes the \c QVideoFrame::WriteOnly flag the content of the possibly modified
105 mapped memory will be written back to the buffer when unmapped.
106
107 When access to the data is no longer needed, the \l unmap function is called
108 to release the mapped memory and possibly update the buffer contents.
109
110 If the format of the video data is multiplanar, the method may map the whole pixel data
111 as a single plane. In this case, mapping a buffer with \l QVideoFrame
112 will calculate additional planes from the specified line stride of the first plane,
113 the frame height, and the data size.
114*/
115
116/*!
117 \fn QAbstractVideoBuffer::unmap()
118
119 Releases the memory mapped by the map() function.
120
121 If the \l {QVideoFrame::MapMode}{MapMode} included the \c QVideoFrame::WriteOnly
122 flag this will write the current content of the mapped memory back to the video frame.
123
124 For CPU video buffers, the function may be not overridden.
125 The default implementation of \c unmap does nothing.
126
127 \sa map()
128*/
129void QAbstractVideoBuffer::unmap() { }
130
131/*!
132 \fn QAbstractVideoBuffer::format() const
133
134 Gets \l QVideoFrameFormat of the underlying video buffer.
135
136 The format must be available upon construction of \l QVideoFrame.
137 QVideoFrame will contain won instance of the given format, that
138 can be detached and modified.
139*/
140
141QT_END_NAMESPACE
142

source code of qtmultimedia/src/multimedia/video/qabstractvideobuffer.cpp