<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qabstractvideobuffer.cpp -->
<title>QAbstractVideoBuffer Class | Qt Multimedia 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtmultimedia-index.html">Qt Multimedia</a></td><td ><a href="qtmultimedia-modules.html">C++ Classes</a></td><td >QAbstractVideoBuffer</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QAbstractVideoBuffer Class</h1>
<!-- $$$QAbstractVideoBuffer-brief -->
<p>The <a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a> class is an abstraction for video data. <a href="#details">More...</a></p>
<!-- @@@QAbstractVideoBuffer -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QAbstractVideoBuffer></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += multimedia</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherited By:</td><td class="memItemRight bottomAlign"> <p><a href="qabstractplanarvideobuffer.html">QAbstractPlanarVideoBuffer</a></p>
</td></tr></table></div><ul>
<li><a href="qabstractvideobuffer-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#HandleType-enum">HandleType</a></b> { NoHandle, GLTextureHandle, XvShmImageHandle, CoreImageHandle, ..., UserHandle }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#MapMode-enum">MapMode</a></b> { NotMapped, ReadOnly, WriteOnly, ReadWrite }</td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#QAbstractVideoBuffer">QAbstractVideoBuffer</a></b>(HandleType <i>type</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#dtor.QAbstractVideoBuffer">~QAbstractVideoBuffer</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual QVariant </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#handle">handle</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> HandleType </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#handleType">handleType</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual uchar *</td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#map">map</a></b>(MapMode <i>mode</i>, int *<i>numBytes</i>, int *<i>bytesPerLine</i>) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual MapMode </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#mapMode">mapMode</a></b>() const = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#mapPlanes">mapPlanes</a></b>(MapMode <i>mode</i>, int *<i>numBytes</i>, int[4] <i>bytesPerLine</i>, uchar *[4] <i>data</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#release">release</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractvideobuffer.html#unmap">unmap</a></b>() = 0</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QAbstractVideoBuffer-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a> class is an abstraction for video data.</p>
<p>The <a href="qvideoframe.html">QVideoFrame</a> class makes use of a <a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a> internally to reference a buffer of video data. Quite often video data buffers may reside in video memory rather than system memory, and this class provides an abstraction of the location.</p>
<p>In addition, creating a subclass of <a href="qabstractvideobuffer.html">QAbstractVideoBuffer</a> will allow you to construct video frames from preallocated or static buffers, in cases where the <a href="qvideoframe.html">QVideoFrame</a> constructors taking a QByteArray or a QImage do not suffice. This may be necessary when implementing a new hardware accelerated video system, for example.</p>
<p>The contents of a buffer can be accessed by mapping the buffer to memory using the <a href="qabstractvideobuffer.html#map">map</a>() function, which returns a pointer to memory containing the contents of the video buffer. The memory returned by <a href="qabstractvideobuffer.html#map">map</a>() is released by calling the <a href="qabstractvideobuffer.html#unmap">unmap</a>() function.</p>
<p>The <a href="qabstractvideobuffer.html#handle">handle</a>() of a buffer may also be used to manipulate its contents using type specific APIs. The type of a buffer's handle is given by the <a href="qabstractvideobuffer.html#handleType">handleType</a>() function.</p>
</div>
<p><b>See also </b><a href="qvideoframe.html">QVideoFrame</a>.</p>
<!-- @@@QAbstractVideoBuffer -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$HandleType$$$NoHandle$$$GLTextureHandle$$$XvShmImageHandle$$$CoreImageHandle$$$QPixmapHandle$$$EGLImageHandle$$$UserHandle -->
<h3 class="fn" id="HandleType-enum"><a name="HandleType-enum"></a>enum QAbstractVideoBuffer::<span class="name">HandleType</span></h3>
<p>Identifies the type of a video buffers handle.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::NoHandle</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">The buffer has no handle, its data can only be accessed by mapping the buffer.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::GLTextureHandle</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">The handle of the buffer is an OpenGL texture ID.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::XvShmImageHandle</code></td><td class="topAlign tblval"><code>2</code></td><td class="topAlign">The handle contains pointer to shared memory XVideo image.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::CoreImageHandle</code></td><td class="topAlign tblval"><code>3</code></td><td class="topAlign">The handle contains pointer to macOS CIImage.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::QPixmapHandle</code></td><td class="topAlign tblval"><code>4</code></td><td class="topAlign">The handle of the buffer is a QPixmap.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::EGLImageHandle</code></td><td class="topAlign tblval"><code>5</code></td><td class="topAlign">The handle of the buffer is an EGLImageKHR.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::UserHandle</code></td><td class="topAlign tblval"><code>1000</code></td><td class="topAlign">Start value for user defined handle types.</td></tr>
</table></div>
<p><b>See also </b><a href="qabstractvideobuffer.html#handleType">handleType</a>().</p>
<!-- @@@HandleType -->
<!-- $$$MapMode$$$NotMapped$$$ReadOnly$$$WriteOnly$$$ReadWrite -->
<h3 class="fn" id="MapMode-enum"><a name="MapMode-enum"></a>enum QAbstractVideoBuffer::<span class="name">MapMode</span></h3>
<p>Enumerates how a video buffer's data is mapped to system memory.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::NotMapped</code></td><td class="topAlign tblval"><code>0x00</code></td><td class="topAlign">The video buffer is not mapped to memory.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::ReadOnly</code></td><td class="topAlign tblval"><code>0x01</code></td><td class="topAlign">The mapped memory is populated with data from the video buffer when mapped, but the content of the mapped memory may be discarded when unmapped.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::WriteOnly</code></td><td class="topAlign tblval"><code>0x02</code></td><td class="topAlign">The mapped memory is uninitialized when mapped, but the possibly modified content will be used to populate the video buffer when unmapped.</td></tr>
<tr><td class="topAlign"><code>QAbstractVideoBuffer::ReadWrite</code></td><td class="topAlign tblval"><code>ReadOnly | WriteOnly</code></td><td class="topAlign">The mapped memory is populated with data from the video buffer, and the video buffer is repopulated with the content of the mapped memory when it is unmapped.</td></tr>
</table></div>
<p><b>See also </b><a href="qabstractvideobuffer.html#mapMode">mapMode</a>() and <a href="qabstractvideobuffer.html#map">map</a>().</p>
<!-- @@@MapMode -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QAbstractVideoBuffer[overload1]$$$QAbstractVideoBufferHandleType -->
<h3 class="fn" id="QAbstractVideoBuffer"><a name="QAbstractVideoBuffer"></a>QAbstractVideoBuffer::<span class="name">QAbstractVideoBuffer</span>(<span class="type"><a href="qabstractvideobuffer.html#HandleType-enum">HandleType</a></span> <i>type</i>)</h3>
<p>Constructs an abstract video buffer of the given <i>type</i>.</p>
<!-- @@@QAbstractVideoBuffer -->
<!-- $$$~QAbstractVideoBuffer[overload1]$$$~QAbstractVideoBuffer -->
<h3 class="fn" id="dtor.QAbstractVideoBuffer"><a name="dtor.QAbstractVideoBuffer"></a><code>[virtual] </code>QAbstractVideoBuffer::<span class="name">~QAbstractVideoBuffer</span>()</h3>
<p>Destroys an abstract video buffer.</p>
<!-- @@@~QAbstractVideoBuffer -->
<!-- $$$handle[overload1]$$$handle -->
<h3 class="fn" id="handle"><a name="handle"></a><code>[virtual] </code><span class="type">QVariant</span> QAbstractVideoBuffer::<span class="name">handle</span>() const</h3>
<p>Returns a type specific handle to the data buffer.</p>
<p>The type of the handle is given by <a href="qabstractvideobuffer.html#handleType">handleType</a>() function.</p>
<p><b>See also </b><a href="qabstractvideobuffer.html#handleType">handleType</a>().</p>
<!-- @@@handle -->
<!-- $$$handleType[overload1]$$$handleType -->
<h3 class="fn" id="handleType"><a name="handleType"></a><span class="type"><a href="qabstractvideobuffer.html#HandleType-enum">HandleType</a></span> QAbstractVideoBuffer::<span class="name">handleType</span>() const</h3>
<p>Returns the type of a video buffer's handle.</p>
<p><b>See also </b><a href="qabstractvideobuffer.html#handle">handle</a>().</p>
<!-- @@@handleType -->
<!-- $$$map[overload1]$$$mapMapModeint*int* -->
<h3 class="fn" id="map"><a name="map"></a><code>[pure virtual] </code><span class="type">uchar</span> *QAbstractVideoBuffer::<span class="name">map</span>(<span class="type"><a href="qabstractvideobuffer.html#MapMode-enum">MapMode</a></span> <i>mode</i>, <span class="type">int</span> *<i>numBytes</i>, <span class="type">int</span> *<i>bytesPerLine</i>)</h3>
<p>Maps the contents of a video buffer to memory.</p>
<p>In some cases the video buffer might be stored in video memory or otherwise inaccessible memory, so it is necessary to map the buffer before accessing the pixel data. This may involve copying the contents around, so avoid mapping and unmapping unless required.</p>
<p>The map <i>mode</i> indicates whether the contents of the mapped memory should be read from and/or written to the buffer. If the map mode includes the <code>QAbstractVideoBuffer::ReadOnly</code> flag the mapped memory will be populated with the content of the buffer when initially mapped. If the map mode includes the <code>QAbstractVideoBuffer::WriteOnly</code> flag the content of the possibly modified mapped memory will be written back to the buffer when unmapped.</p>
<p>When access to the data is no longer needed be sure to call the <a href="qabstractvideobuffer.html#unmap">unmap</a>() function to release the mapped memory and possibly update the buffer contents.</p>
<p>Returns a pointer to the mapped memory region, or a null pointer if the mapping failed. The size in bytes of the mapped memory region is returned in <i>numBytes</i>, and the line stride in <i>bytesPerLine</i>.</p>
<p><b>Note: </b>Writing to memory that is mapped as read-only is undefined, and may result in changes to shared data or crashes.</p><p><b>See also </b><a href="qabstractvideobuffer.html#unmap">unmap</a>() and <a href="qabstractvideobuffer.html#mapMode">mapMode</a>().</p>
<!-- @@@map -->
<!-- $$$mapMode[overload1]$$$mapMode -->
<h3 class="fn" id="mapMode"><a name="mapMode"></a><code>[pure virtual] </code><span class="type"><a href="qabstractvideobuffer.html#MapMode-enum">MapMode</a></span> QAbstractVideoBuffer::<span class="name">mapMode</span>() const</h3>
<p>Returns the mode a video buffer is mapped in.</p>
<p><b>See also </b><a href="qabstractvideobuffer.html#map">map</a>().</p>
<!-- @@@mapMode -->
<!-- $$$mapPlanes[overload1]$$$mapPlanesMapModeint*int[4]uchar*[4] -->
<h3 class="fn" id="mapPlanes"><a name="mapPlanes"></a><span class="type">int</span> QAbstractVideoBuffer::<span class="name">mapPlanes</span>(<span class="type"><a href="qabstractvideobuffer.html#MapMode-enum">MapMode</a></span> <i>mode</i>, <span class="type">int</span> *<i>numBytes</i>, <span class="type">int</span>[<span class="type">4</span>] <i>bytesPerLine</i>, <span class="type">uchar</span> *[<span class="type">4</span>] <i>data</i>)</h3>
<p>Independently maps the planes of a video buffer to memory.</p>
<p>The map <i>mode</i> indicates whether the contents of the mapped memory should be read from and/or written to the buffer. If the map mode includes the <code>QAbstractVideoBuffer::ReadOnly</code> flag the mapped memory will be populated with the content of the buffer when initially mapped. If the map mode includes the <code>QAbstractVideoBuffer::WriteOnly</code> flag the content of the possibly modified mapped memory will be written back to the buffer when unmapped.</p>
<p>When access to the data is no longer needed be sure to call the <a href="qabstractvideobuffer.html#unmap">unmap</a>() function to release the mapped memory and possibly update the buffer contents.</p>
<p>Returns the number of planes in the mapped video data. For each plane the line stride of that plane will be returned in <i>bytesPerLine</i>, and a pointer to the plane data will be returned in <i>data</i>. The accumulative size of the mapped data is returned in <i>numBytes</i>.</p>
<p>Not all buffer implementations will map more than the first plane, if this returns a single plane for a planar format the additional planes will have to be calculated from the line stride of the first plane and the frame height. Mapping a buffer with <a href="qvideoframe.html">QVideoFrame</a> will do this for you.</p>
<p>To implement this function create a derivative of <a href="qabstractplanarvideobuffer.html">QAbstractPlanarVideoBuffer</a> and implement its map function instance instead.</p>
<p>This function was introduced in Qt 5.4.</p>
<!-- @@@mapPlanes -->
<!-- $$$release[overload1]$$$release -->
<h3 class="fn" id="release"><a name="release"></a><code>[virtual] </code><span class="type">void</span> QAbstractVideoBuffer::<span class="name">release</span>()</h3>
<p>Releases the video buffer.</p>
<p><a href="qvideoframe.html">QVideoFrame</a> calls QAbstractVideoBuffer::release when the buffer is not used any more and can be destroyed or returned to the buffer pool.</p>
<p>The default implementation deletes the buffer instance.</p>
<!-- @@@release -->
<!-- $$$unmap[overload1]$$$unmap -->
<h3 class="fn" id="unmap"><a name="unmap"></a><code>[pure virtual] </code><span class="type">void</span> QAbstractVideoBuffer::<span class="name">unmap</span>()</h3>
<p>Releases the memory mapped by the <a href="qabstractvideobuffer.html#map">map</a>() function.</p>
<p>If the <a href="qabstractvideobuffer.html#MapMode-enum">MapMode</a> included the <code>QAbstractVideoBuffer::WriteOnly</code> flag this will write the current content of the mapped memory back to the video frame.</p>
<p><b>See also </b><a href="qabstractvideobuffer.html#map">map</a>().</p>
<!-- @@@unmap -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
