1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtMultimedia module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "qabstractvideobuffer_p.h"
43
44 #include <qvariant.h>
45
46 QT_BEGIN_NAMESPACE
47
48 /*!
49 \class QAbstractVideoBuffer
50 \brief The QAbstractVideoBuffer class is an abstraction for video data.
51 \since 4.6
52
53 The QVideoFrame class makes use of a QAbstractVideoBuffer internally to reference a buffer of
54 video data. Creating a subclass of QAbstractVideoBuffer will allow you to construct video
55 frames from preallocated or static buffers.
56
57 The contents of a buffer can be accessed by mapping the buffer to memory using the map()
58 function which returns a pointer to memory containing the contents of the the video buffer.
59 The memory returned by map() is released by calling the unmap() function.
60
61 The handle() of a buffer may also be used to manipulate it's contents using type specific APIs.
62 The type of a buffer's handle is given by the handleType() function.
63
64 \sa QVideoFrame
65 */
66
67 /*!
68 \enum QAbstractVideoBuffer::HandleType
69
70 Identifies the type of a video buffers handle.
71
72 \value NoHandle The buffer has no handle, its data can only be accessed by mapping the buffer.
73 \value GLTextureHandle The handle of the buffer is an OpenGL texture ID.
74 \value XvShmImageHandle The handle contains pointer to shared memory XVideo image.
75 \value CoreImageHandle The handle contains pointer to Mac OS X CIImage.
76 \value QPixmapHandle The handle of the buffer is a QPixmap.
77 \value UserHandle Start value for user defined handle types.
78
79 \sa handleType()
80 */
81
82 /*!
83 \enum QAbstractVideoBuffer::MapMode
84
85 Enumerates how a video buffer's data is mapped to memory.
86
87 \value NotMapped The video buffer has is not mapped to memory.
88 \value ReadOnly The mapped memory is populated with data from the video buffer when mapped, but
89 the content of the mapped memory may be discarded when unmapped.
90 \value WriteOnly The mapped memory is uninitialized when mapped, and the content will be used to
91 populate the video buffer when unmapped.
92 \value ReadWrite The mapped memory is populated with data from the video buffer, and the
93 video buffer is repopulated with the content of the mapped memory.
94
95 \sa mapMode(), map()
96 */
97
98 /*!
99 Constructs an abstract video buffer of the given \a type.
100 */
101
QAbstractVideoBuffer(HandleType type)102 QAbstractVideoBuffer::QAbstractVideoBuffer(HandleType type)
103 : d_ptr(new QAbstractVideoBufferPrivate)
104 {
105 Q_D(QAbstractVideoBuffer);
106
107 d->handleType = type;
108 }
109
110 /*!
111 \internal
112 */
113
QAbstractVideoBuffer(QAbstractVideoBufferPrivate & dd,HandleType type)114 QAbstractVideoBuffer::QAbstractVideoBuffer(QAbstractVideoBufferPrivate &dd, HandleType type)
115 : d_ptr(&dd)
116 {
117 Q_D(QAbstractVideoBuffer);
118
119 d->handleType = type;
120 }
121
122 /*!
123 Destroys an abstract video buffer.
124 */
125
~QAbstractVideoBuffer()126 QAbstractVideoBuffer::~QAbstractVideoBuffer()
127 {
128 delete d_ptr;
129 }
130
131 /*!
132 Returns the type of a video buffer's handle.
133
134 \sa handle()
135 */
136
handleType() const137 QAbstractVideoBuffer::HandleType QAbstractVideoBuffer::handleType() const
138 {
139 return d_func()->handleType;
140 }
141
142 /*!
143 \fn QAbstractVideoBuffer::mapMode() const
144
145 Returns the mode a video buffer is mapped in.
146
147 \sa map()
148 */
149
150 /*!
151 \fn QAbstractVideoBuffer::map(MapMode mode, int *numBytes, int *bytesPerLine)
152
153 Maps the contents of a video buffer to memory.
154
155 The map \a mode indicates whether the contents of the mapped memory should be read from and/or
156 written to the buffer. If the map mode includes the QAbstractVideoBuffer::ReadOnly flag the
157 mapped memory will be populated with the content of the video buffer when mapped. If the map
158 mode includes the QAbstractVideoBuffer::WriteOnly flag the content of the mapped memory will be
159 persisted in the buffer when unmapped.
160
161 When access to the data is no longer needed be sure to call the unmap() function to release the
162 mapped memory.
163
164 Returns a pointer to the mapped memory region, or a null pointer if the mapping failed. The
165 size in bytes of the mapped memory region is returned in \a numBytes, and the line stride in \a
166 bytesPerLine.
167
168 When access to the data is no longer needed be sure to unmap() the buffer.
169
170 \note Writing to memory that is mapped as read-only is undefined, and may result in changes
171 to shared data.
172
173 \sa unmap(), mapMode()
174 */
175
176 /*!
177 \fn QAbstractVideoBuffer::unmap()
178
179 Releases the memory mapped by the map() function
180
181 If the \l {QAbstractVideoBuffer::MapMode}{MapMode} included the QAbstractVideoBuffer::WriteOnly
182 flag this will persist the current content of the mapped memory to the video frame.
183
184 \sa map()
185 */
186
187 /*!
188 Returns a type specific handle to the data buffer.
189
190 The type of the handle is given by handleType() function.
191
192 \sa handleType()
193 */
194
handle() const195 QVariant QAbstractVideoBuffer::handle() const
196 {
197 return QVariant();
198 }
199
200
201 QT_END_NAMESPACE
202