1// Copyright (C) 2016 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_p.h"
5
6#include <qvariant.h>
7#include <rhi/qrhi.h>
8
9#include <QDebug>
10
11
12QT_BEGIN_NAMESPACE
13
14/*!
15 \class QAbstractVideoBuffer
16 \internal
17 \brief The QAbstractVideoBuffer class is an abstraction for video data.
18 \inmodule QtMultimedia
19 \ingroup multimedia
20 \ingroup multimedia_video
21
22 The QVideoFrame class makes use of a QAbstractVideoBuffer internally to reference a buffer of
23 video data. Quite often video data buffers may reside in video memory rather than system
24 memory, and this class provides an abstraction of the location.
25
26 In addition, creating a subclass of QAbstractVideoBuffer will allow you to construct video
27 frames from preallocated or static buffers. This caters for cases where the QVideoFrame constructors
28 taking a QByteArray or a QImage do not suffice. This may be necessary when implementing
29 a new hardware accelerated video system, for example.
30
31 The contents of a buffer can be accessed by mapping the buffer to memory using the map()
32 function, which returns a pointer to memory containing the contents of the video buffer.
33 The memory returned by map() is released by calling the unmap() function.
34
35 The handle() of a buffer may also be used to manipulate its contents using type specific APIs.
36 The type of a buffer's handle is given by the handleType() function.
37
38 \sa QVideoFrame
39*/
40
41/*!
42 \enum QVideoFrame::HandleType
43
44 Identifies the type of a video buffers handle.
45
46 \value NoHandle
47 The buffer has no handle, its data can only be accessed by mapping the buffer.
48 \value RhiTextureHandle
49 The handle of the buffer is defined by The Qt Rendering Hardware Interface
50 (RHI). RHI is Qt's internal graphics abstraction for 3D APIs, such as
51 OpenGL, Vulkan, Metal, and Direct 3D.
52
53 \sa handleType()
54*/
55
56/*!
57 \enum QVideoFrame::MapMode
58
59 Enumerates how a video buffer's data is mapped to system memory.
60
61 \value NotMapped
62 The video buffer is not mapped to memory.
63 \value ReadOnly
64 The mapped memory is populated with data from the video buffer when mapped,
65 but the content of the mapped memory may be discarded when unmapped.
66 \value WriteOnly
67 The mapped memory is uninitialized when mapped, but the possibly modified
68 content will be used to populate the video buffer when unmapped.
69 \value ReadWrite
70 The mapped memory is populated with data from the video
71 buffer, and the video buffer is repopulated with the content of the mapped
72 memory when it is unmapped.
73
74 \sa mapMode(), map()
75*/
76
77/*!
78 Constructs an abstract video buffer of the given \a type.
79*/
80QAbstractVideoBuffer::QAbstractVideoBuffer(QVideoFrame::HandleType type, QRhi *rhi)
81 : m_type(type),
82 m_rhi(rhi)
83{
84}
85
86/*!
87 Destroys an abstract video buffer.
88*/
89QAbstractVideoBuffer::~QAbstractVideoBuffer()
90{
91}
92
93/*!
94 Returns the type of a video buffer's handle.
95
96 \sa handle()
97*/
98QVideoFrame::HandleType QAbstractVideoBuffer::handleType() const
99{
100 return m_type;
101}
102
103/*!
104 Returns the QRhi instance.
105*/
106QRhi *QAbstractVideoBuffer::rhi() const
107{
108 return m_rhi;
109}
110
111/*! \fn uchar *QAbstractVideoBuffer::map(MapMode mode, int *numBytes, int *bytesPerLine)
112
113 Independently maps the planes of a video buffer to memory.
114
115 The map \a mode indicates whether the contents of the mapped memory should be read from and/or
116 written to the buffer. If the map mode includes the \c QVideoFrame::ReadOnly flag the
117 mapped memory will be populated with the content of the buffer when initially mapped. If the map
118 mode includes the \c QVideoFrame::WriteOnly flag the content of the possibly modified
119 mapped memory will be written back to the buffer when unmapped.
120
121 When access to the data is no longer needed be sure to call the unmap() function to release the
122 mapped memory and possibly update the buffer contents.
123
124 Returns the number of planes in the mapped video data. For each plane the line stride of that
125 plane will be returned in \a bytesPerLine, and a pointer to the plane data will be returned in
126 \a data. The accumulative size of the mapped data is returned in \a numBytes.
127
128 Not all buffer implementations will map more than the first plane, if this returns a single
129 plane for a planar format the additional planes will have to be calculated from the line stride
130 of the first plane and the frame height. Mapping a buffer with QVideoFrame will do this for
131 you.
132
133 To implement this function create a derivative of QAbstractPlanarVideoBuffer and implement
134 its map function instance instead.
135
136 \since 5.4
137*/
138
139/*!
140 \fn QAbstractVideoBuffer::unmap()
141
142 Releases the memory mapped by the map() function.
143
144 If the \l {QVideoFrame::MapMode}{MapMode} included the \c QVideoFrame::WriteOnly
145 flag this will write the current content of the mapped memory back to the video frame.
146
147 \sa map()
148*/
149
150/*! \fn quint64 QAbstractVideoBuffer::textureHandle(QRhi *rhi, int plane) const
151
152 Returns a texture handle to the data buffer.
153
154 \sa handleType()
155*/
156
157/*
158 \fn int QAbstractPlanarVideoBuffer::map(MapMode mode, int *numBytes, int bytesPerLine[4], uchar *data[4])
159
160 Maps the contents of a video buffer to memory.
161
162 The map \a mode indicates whether the contents of the mapped memory should be read from and/or
163 written to the buffer. If the map mode includes the \c QVideoFrame::ReadOnly flag the
164 mapped memory will be populated with the content of the buffer when initially mapped. If the map
165 mode includes the \c QVideoFrame::WriteOnly flag the content of the possibly modified
166 mapped memory will be written back to the buffer when unmapped.
167
168 When access to the data is no longer needed be sure to call the unmap() function to release the
169 mapped memory and possibly update the buffer contents.
170
171 Returns the number of planes in the mapped video data. For each plane the line stride of that
172 plane will be returned in \a bytesPerLine, and a pointer to the plane data will be returned in
173 \a data. The accumulative size of the mapped data is returned in \a numBytes.
174
175 \sa QAbstractVideoBuffer::map(), QAbstractVideoBuffer::unmap(), QVideoFrame::mapMode()
176*/
177
178#ifndef QT_NO_DEBUG_STREAM
179QDebug operator<<(QDebug dbg, QVideoFrame::MapMode mode)
180{
181 QDebugStateSaver saver(dbg);
182 dbg.nospace();
183 switch (mode) {
184 case QVideoFrame::ReadOnly:
185 return dbg << "ReadOnly";
186 case QVideoFrame::ReadWrite:
187 return dbg << "ReadWrite";
188 case QVideoFrame::WriteOnly:
189 return dbg << "WriteOnly";
190 default:
191 return dbg << "NotMapped";
192 }
193}
194#endif
195
196QT_END_NAMESPACE
197

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