/usr/share/doc/gstreamer1.0-doc/pwg/html/section-basics-data.html is in gstreamer1.0-doc 1.8.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>GstMiniObject, Buffers and Events</title><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="GStreamer Plugin Writer's Guide (1.8.0)"><link rel="up" href="chapter-intro-basics.html" title="Chapter 2. Foundations"><link rel="prev" href="section-basics-pads.html" title="Pads"><link rel="next" href="section-basics-types.html" title="Media types and Properties"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">GstMiniObject, Buffers and Events</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="section-basics-pads.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Foundations</th><td width="20%" align="right"> <a accesskey="n" href="section-basics-types.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-basics-data"></a>GstMiniObject, Buffers and Events</h2></div></div></div><p>
All streams of data in <span class="application">GStreamer</span> are chopped up into chunks that are
passed from a source pad on one element to a sink pad on another element.
<span class="emphasis"><em>GstMiniObject</em></span> is the structure used to hold these
chunks of data.
</p><p>
GstMiniObject contains the following important types:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
An exact type indicating what type of data (event, buffer, ...)
this GstMiniObject is.
</p></li><li class="listitem"><p>
A reference count indicating the number of elements currently
holding a reference to the miniobject. When the reference count
falls to zero, the miniobject will be disposed, and its memory will be
freed in some sense (see below for more details).
</p></li></ul></div><p>
</p><p>
For data transport, there are two types of GstMiniObject defined:
events (control) and buffers (content).
</p><p>
Buffers may contain any sort of data that the two linked pads
know how to handle. Normally, a buffer contains a chunk of some sort of
audio or video data that flows from one element to another.
</p><p>
Buffers also contain metadata describing the buffer's contents. Some of
the important types of metadata are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Pointers to one or more GstMemory objects. GstMemory objects are
refcounted objects that encapsulate a region of memory.
</p></li><li class="listitem"><p>
A timestamp indicating the preferred display timestamp of the
content in the buffer.
</p></li></ul></div><p>
</p><p>
Events
contain information on the state of the stream flowing between the two
linked pads. Events will only be sent if the element explicitly supports
them, else the core will (try to) handle the events automatically. Events
are used to indicate, for example, a media type, the end of a
media stream or that the cache should be flushed.
</p><p>
Events may contain several of the following items:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A subtype indicating the type of the contained event.
</p></li><li class="listitem"><p>
The other contents of the event depend on the specific event type.
</p></li></ul></div><p>
</p><p>
Events will be discussed extensively in <a class="xref" href="chapter-advanced-events.html" title="Chapter 17. Events: Seeking, Navigation and More">Chapter 17, <i>Events: Seeking, Navigation and More</i></a>.
Until then, the only event that will be used is the <span class="emphasis"><em>EOS</em></span>
event, which is used to indicate the end-of-stream (usually end-of-file).
</p><p>
See the <span class="emphasis"><em>GStreamer Library Reference</em></span> for the current implementation details of a <a class="ulink" href="../../gstreamer/html/gstreamer-GstMiniObject.html" target="_top"><code class="classname">GstMiniObject</code></a>, <a class="ulink" href="../../gstreamer/html/GstBuffer.html" target="_top"><code class="classname">GstBuffer</code></a> and <a class="ulink" href="../../gstreamer/html/GstEvent.html" target="_top"><code class="classname">GstEvent</code></a>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="sect2-buffer-allocation"></a>Buffer Allocation</h3></div></div></div><p>
Buffers are able to store chunks of memory of several different
types. The most generic type of buffer contains memory allocated
by malloc(). Such buffers, although convenient, are not always
very fast, since data often needs to be specifically copied into
the buffer.
</p><p>
Many specialized elements create buffers that point to special
memory. For example, the filesrc element usually
maps a file into the address space of the application (using mmap()),
and creates buffers that point into that address range. These
buffers created by filesrc act exactly like generic buffers, except
that they are read-only. The buffer freeing code automatically
determines the correct method of freeing the underlying memory.
Downstream elements that receive these kinds of buffers do not
need to do anything special to handle or unreference it.
</p><p>
Another way an element might get specialized buffers is to
request them from a downstream peer through a GstBufferPool or
GstAllocator. Elements can ask a GstBufferPool or GstAllocator
from the downstream peer element. If downstream is able to provide
these objects, upstream can use them to allocate buffers.
See more in <a class="xref" href="chapter-allocation.html" title="Chapter 15. Memory allocation">Memory allocation</a>.
</p><p>
Many sink elements have accelerated methods for copying data
to hardware, or have direct access to hardware. It is common
for these elements to be able to create a GstBufferPool or
GstAllocator for their upstream peers. One such example is
ximagesink. It creates buffers that contain XImages. Thus,
when an upstream peer copies data into the buffer, it is copying
directly into the XImage, enabling ximagesink to draw the
image directly to the screen instead of having to copy data
into an XImage first.
</p><p>
Filter elements often have the opportunity to either work on
a buffer in-place, or work while copying from a source buffer
to a destination buffer. It is optimal to implement both
algorithms, since the <span class="application">GStreamer</span> framework can choose the
fastest algorithm as appropriate. Naturally, this only makes
sense for strict filters -- elements that have exactly the
same format on source and sink pads.
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="section-basics-pads.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="chapter-intro-basics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="section-basics-types.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Pads </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Media types and Properties</td></tr></table></div></body></html>
|