爱华网
|
这只是一个获得gstreamer的版本号并打印的简单程序，你所要从中知道的是：gst_initInitializes the GStreamer library, settingup internal path lists, registering built-in elements, and loadingstandard plugins.
This function should be called beforecalling any other GLib functions.
PS：gstreamer是基于Glib的，所以当有些函数不在referencemanual中的时候，应该在Glib的文档寻找。例如以下的例子，是基于Glib的命令行参数解析（Glib可以认为是Linux编程的实用库，不要事事亲力亲为，要看看有没有大家都在用的东西。还有好多东西要学啊！头脑却很僵化！）
|
暂时跳过这个例子。
Elements
The most important object in GStreamer for theapplication programmer is theGstElement(../../gstreamer/html/GstElement.html)object. An element is the basic building block for amediapipeline. All the different high-levelcomponents you will use are derived from GstElement.Everydecoder, encoder, demuxer, video or audiooutput is in fact a GstElement。GstElements大体上分为三类：source element 源元素
Filter-like elements 类过滤器元素
指的是对数据流进行一定操作的功能元素，例如muxer，demuxer，encodec, decodec，filter（例如音量过滤器？）, convetor（例如video scaler，比例变换）等。
sink elememnts 接收器元素
Creating a GstElement
The simplest way to create an element is to usegst_element_factory_make ()(http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstElementFactory.html#gstelement-factory-make). This function takes a factoryname and an element name for the newly createdelement. The name of the element is somethingyou can use later on to look up the element in a bin,forexample. The name will also be used in debugoutput. You can pass NULL as the name argument to getaunique, default name.When you don’t need the element anymore, youneed to unref it using gst_object_unref ()(http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstObject.html#gst-objectunref).This decreases the reference count for theelement by 1. An element has a refcount of 1 when itgets created. An element gets destroyedcompletely when the refcount is decreased to 0.创建一个元素最简单的方法就是使用gst_element_factory_make ()，就好像让一个工厂为你生产一样。像liunx的文件管理机制一样，使用引用计数来决定对象的销毁。注意到，对gst_object_unref ()
Decrements the reference count onobject.If reference count hits zero, destroyobject.This function does not take the lock onobjectas it relies onatomic refcounting.
The unref method should never be called with the LOCK held sincethis might deadlock the dispose function.
锁机制会在某些地方用在element上，但是这个函数保证了操作是原子的，你不应该为它加锁。
获得一个fakesrc工厂生产的名为“source"的元素：
|
gst_element_factory_make是两个函数结合：
|
|
所以你对GstElement可以进行和GObject相关的properties的操作以及Glib的信号操作。
对于Gstreamer的继承体系，有很多疑惑的地方。
|
GstElementFactory提供了制造和查询一个Element的接口。例如你可以确定哪些pads是这个element兼容的。
Linking elements
By linking a source element with zero or morefilter-like elements and finally a sink element, you set upamedia pipeline. Data will flow through theelements. This is the basic concept of media handlinginGStreamer.
|
Important: you must add elements to a bin orpipeline before linking them, since adding an element toabin will disconnect any already existing links.Also, you cannot directly link elements that are not inthesame bin or pipeline; if you want to linkelements or pads at different hierarchy levels, you will needtouse ghost pads (more about ghost padslater).在连接之前，你必须把元素放在容器（流水线）中，这样前面的连接可以自动被断开。如果你想要连接处于不同继承水平的元素，可以使用ghostpads。
（了解一个很好用的库是好事情，但是事实上，最重要的还是:性格——程序员该有的性格！此外才是基本的知识——如数据结构，C等，然后再其次是Linux的IPC，库调用等。而某一个库事实上是其次的东西，但是有可能是紧急的东西，因为得马上派上用场。）Element States
一个元素有四种状态：1.NULL2.READY3.PAUSED4.PLAYING你可以使用gst_element_set_state ()来设置元素的状态，如果从NULL直接到PLAYING，gstreamer也会自动经历中间的状态。BinsA bin is a container element.You can add elements to a bin. Since a bin is an element itself, abin can be handled in the same way as any other element. Therefore,the whole previous chapter (Elements) applies to bins aswell.
|
你可以按照element方式来创建bin和pipeline（使用工厂），也可以使用gst_bin_new() and gst_pipeline_new () .从容器中增加和删除一个元素：gst_bin_add () andgst_bin_remove(). pipeline是最高层的bin，因此你可以把bin放进pipeline中。
Custom bins
The application programmer can create custom binspacked with elements to perform a specific task.
应用程序程序员可以定制容器以完成某项任务。
|
使用上面几行代码就可以完成一个Ogg/Vorbis格式的解码器。
Custom bins can be created with a plugin or an XMLdescription. You will find more information about
creating custom bin in the Plugin Writers Guide
(http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html).
Examples of such custom bins are the playbin and decodebin elementsfrom gst-plugins-base
(http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html).
定制容器可以使用插件或者XML描述。你可以在baseplugins中找到播放和解码元素作为定制容器的示例。
Bus
总线
A bus is a simple system that takes care offorwarding messages from the pipeline threads to an application inits own thread context. The advantage of a bus is that anapplication does not need to be
thread-aware in order to use GStreamer, even though GStreameritself is heavily threaded. Every pipeline contains a bus bydefault, so applications do not need to create a bus or anything.The only thing applications should do is set a message handler on abus, which is similar to a signal handler to an object.When themainloop is running, the bus will periodically be checked for newmessages, and
the callback will be called when any message is available.
总线是处理流水线向应用程序传递的消息的机制，消息会被应用程序自己的线程上下文处理。这样，你就不需要太过考虑线程方面的问题，尽管gstreamer是“严重”多线程的。
每一条流水线都有默认的总线，你不需要自己创建它。你需要为总线安装消息处理函数。当循环运行的时候，总线会周期捕捉消息，然后回调函数会处理任何可达消息。
有两种方法可以使用总线：
1.Run a GLib/Gtk+ main loop (or iterate thedefault GLib main context yourself regularly) and attach some kindof watch to the bus. This way the GLib main loop will check the busfor new messages and notify you whenever there are messages.Typically you would use gst_bus_add_watch () orgst_bus_add_signal_watch () in this case.
To use a bus, attach a message handler to the bus of a pipelineusing gst_bus_add_watch (). This handler will be called wheneverthe pipeline emits a message to the bus. In this handler, check thesignal type (see next section) and do something accordingly. Thereturn value of the handler should be TRUE to remove the messagefrom the bus.
结合实例讲解这一段:
|
to the user about the state of the pipeline. Error messages arefatal and terminate the data-passing. The
error should be repaired to resume pipeline activity. Warnings arenot fatal, but imply a problem
nevertheless. Information messages are for non-problemnotifications. All those messages contain a
GError with the main error type and message, and optionally a debugstring. Both can be extracted
using gst_message_parse_error (), _parse_warning () and _parse_info(). Both error
and debug string should be free’ed after use.
• End-of-stream notification: this is emitted when the stream hasended. The state of the pipeline will
not change, but further media handling will stall. Applications canuse this to skip to the next song in
their playlist. After end-of-stream, it is also possible to seekback in the stream. Playback will then
continue automatically. This message has no specificarguments.
• Tags: emitted when metadata was found in the stream. This can beemitted multiple times for a
pipeline (e.g. once for descriptive metadata such as artist name orsong title, and another one for
stream-information, such as samplerate and bitrate). Applicationsshould cache metadata internally.
gst_message_parse_tag () should be used to parse the taglist, whichshould be
gst_tag_list_free ()’ed when no longer needed.
• State-changes: emitted after a successful state change.gst_message_parse_state_changed ()
can be used to parse the old and new state of thistransition.
• Buffering: emitted during caching of network-streams. One canmanually extract the progress (in
percent) from the message by extracting the “buffer-percent”property from the structure returned by
gst_message_get_structure ().
• Element messages: these are special messages that are unique tocertain elements and usually represent
additional features. The element’s documentation should mention indetail which element messages a
particular element may send. As an example, the ’qtdemux’ QuickTimedemuxer element may send a
’redirect’ element message on certain occasions if the streamcontains a redirect instruction.
• Application-specific messages: any information on those can beextracted by getting the message
structure (see above) and reading its fields. Usually thesemessages can safely be ignored.
Application messages are primarily meant for internal use inapplications in case the application needs
to marshal information from some thread into the main thread. Thisis particularly useful when the
application is making use of element signals (as those signals willbe emitted in the context of the
streaming thread).PadsA pad type is defined by two properties: its directionand its availability. As we’ve mentioned before, GStreamer definestwo pad directions: source pads and sink pads. A pad can have anyof three availabilities: always, sometimes and on request.Dynamic (or sometimes) padsSome elements might not have all of their pads when theelement is created. This can happen, for
example, with an Ogg demuxer element. The element will read the Oggstream and create dynamic pads
for each contained elementary stream (vorbis, theora) when itdetects such a stream in the Ogg stream.
Likewise, it will delete the pad when the stream ends. Thisprinciple is very useful for demuxer elements,
for example.Request padsAn element can also have request pads. These pads arenot created automatically but are only created on
demand. This is very useful for multiplexers, aggregators and teeelements. Aggregators are elements
that merge the content of several input streams together into oneoutput stream. Tee elements are the
reverse: they are elements that have one input stream and copy thisstream to each of their output pads,
which are created on request. Whenever an application needs anothercopy of the stream, it can simply
request a new output pad from the tee element.关于焊盘，它是由对象GstPad定义的。但是作为元素的接口来说，还没找到创建焊盘然后附属到元素的例子。动态焊盘(Dynamic)是由元素，例如demux自动生成的。预定焊盘（Requested）是元素根据请求生成的。焊盘模板也不是独立的概念，它是属于元素的，元素能够生成的焊盘类型由它的焊盘模板决定。The gst_element_get_request_pad () method can be used toget a pad from the element based on
the name of the pad template. It is also possible to request a padthat is compatible with another pad
template. This is very useful if you want to link an element to amultiplexer element and you need to
request a pad that is compatible. The methodgst_element_get_compatible_pad () can be used to
request a compatible pad, as shown in the next example. It willrequest a compatible pad from an Ogg
multiplexer from any input.你可以要求生成某种类型的焊盘，这时你需要指定元素和焊盘模板类型，例如：
|
|
|
the type of media that currently streams over this pad, in whichcase the pad has been negotiated already.焊盘的接受力接受力是焊盘模板或者焊盘的属性。对于焊盘模板来说，它描述了从中衍生的焊盘能通过的媒体类型。对于焊盘来说，它或者是从焊盘模板所衍生的可能的一系列兼容类型（如果是未协商的），或者是正在通过的媒体类型（如果是已协商的）。A pads capabilities are described in a GstCaps object.Internally, a GstCaps
(../../gstreamer/html/gstreamer-GstCaps.html) will contain one ormore GstStructure
(../../gstreamer/html/gstreamer-GstStructure.html) that willdescribe one media type. A negotiated pad
will have capabilities set that contain exactly one structure.Also, this structure will contain only fixed
values. These constraints are not true for unnegotiated pads or padtemplates.模板的接受力又GstCaps对象定义，它包含了一个或多个GstStructure，每一个都描述了一种媒体类型。而协商了的焊盘，它们的接受力被定义为一个GstStructure,而且它的值是固定的。例如，对于音频数据流而言，如果之前这个GstStructure可以有1声道或者2声道，经过协商，它就会被定义为1声道（或则2声道）。也就是说，流的格式的参数被协商而确定下来。As an example, below is a dump of the capabilities ofthe “vorbisdec” element, which you will get by
running gst-inspect vorbisdec. You will see two pads: a source anda sink pad. Both of these pads are
always available, and both have capabilities attached to them. Thesink pad will accept vorbis-encoded
audio data, with the mime-type “audio/x-vorbis”. The source padwill be used to send raw (decoded)
audio samples to the next element, with a raw audio mime-type (inthis case, “audio/x-raw-int”) The
source pad will also contain properties for the audio samplerateand the amount of channels, plus some
more that you don’t need to worry about for now.下面给出了焊盘模板的定义。如果你从这个元素要求生成src的焊盘，那么它就会根据SRC模板生成相应的焊盘。就好像，套色拼隔板？
|
and a value. There are different possible value types that can beused:• Basic types, this can be pretty much any GTyperegistered with Glib. Those properties indicate a
specific, non-dynamic value for this property. Examplesinclude:
• An integer value (G_TYPE_INT): the property has this exactvalue.
• A boolean value (G_TYPE_BOOLEAN): the property is either TRUE orFALSE.
• A float value (G_TYPE_FLOAT): the property has this exactfloating point value.
• A string value (G_TYPE_STRING): the property contains a UTF-8string.
• A fraction value (GST_TYPE_FRACTION): contains a fractionexpressed by an integer numerator
and denominator.
• Range types are GTypes registered by GStreamer to indicate arange of possible values. They are used
for indicating allowed audio samplerate values or supported videosizes. The two types defined in
GStreamer are:
• An integer range value (GST_TYPE_INT_RANGE): the property denotesa range of possible integers,
with a lower and an upper boundary. The “vorbisdec” element, forexample, has a rate property that
can be between 8000 and 50000.
• A float range value (GST_TYPE_FLOAT_RANGE): the property denotesa range of possible floating
point values, with a lower and an upper boundary.
• A fraction range value (GST_TYPE_FRACTION_RANGE): the propertydenotes a range of possible
fraction values, with a lower and an upper boundary.
• A list value (GST_TYPE_LIST): the property can take any valuefrom a list of basic values given in
this list.
Example: caps that express that either a sample rate of 44100 Hzand a sample rate of 48000 Hz is
supported would use a list of integer values, with one value being44100 and one value being 48000.
• An array value (GST_TYPE_ARRAY): the property is an array ofvalues. Each value in the array is a full
value on its own, too. All values in the array should be of thesame elementary type. This means that
an array can contain any combination of integers, lists ofintegers, integer ranges together, and the
same for floats or strings, but it can not contain both floats andints at the same time.
Example: for audio where there are more than two channels involvedthe channel layout needs to be
specified (for one and two channel audio the channel layout isimplicit unless stated otherwise in the
caps). So the channel layout would be an array of integer enumvalues where each enum value
represents a loudspeaker position. Unlike a GST_TYPE_LIST, thevalues in an array will be interpreted
as a whole.参数是接受力的详细信息，例如接收力是音频流，那么就会有声道数这个参数，指明可以接受的声道的数目。而参数有很多种数据类型，它的值和数据类型相关，例如数据类型是list，那么它的值就是list中的一个；如果是interger，那么值就是一个整数。What capabilities are used for
Capabilities (short: caps) describe the type of data that isstreamed between two pads, or that one pad
(template) supports. This makes them very useful for variouspurposes:
• Autoplugging: automatically finding elements to link to a padbased on its capabilities. All
autopluggers use this method.
• Compatibility detection: when two pads are linked, GStreamer canverify if the two pads are talking
about the same media type. The process of linking two pads andchecking if they are compatible is
called “caps negotiation”.
• Metadata: by reading the capabilities from a pad, applicationscan provide information about the type
of media that is being streamed over the pad, which is informationabout the stream that is currently
being played back.
• Filtering: an application can use capabilities to limit thepossible media types that can stream between
two pads to a specific subset of their supported stream types. Anapplication can, for example, use
“filtered caps” to set a specific (fixed or non-fixed) video sizethat should stream between two pads.
You will see an example of filtered caps later in this manual, inSection 18.2. You can do caps filtering
by inserting a capsfilter element into your pipeline and settingits “caps” property. Caps filters are often
placed after converter elements like audioconvert, audioresample,ffmpegcolorspace or videoscale to
force those converters to convert data to a specific output formatat a certain point in a stream.caps有几种用途：1.自动插件2. 兼容性检查,The process of linking two pads and checking ifthey are compatible is
called “caps negotiation”.连接两个pads，并且进行兼容性检查的过程叫做协商。3.元数据,媒体流的信息4.过滤器Using capabilities for metadataA pad can have a set (i.e. one or more) of capabilitiesattached to it. Capabilities (GstCaps) are
represented as an array of one or more GstStructures, and eachGstStructure is an array of fields
where each field consists of a field name string (e.g. "width") anda typed value (e.g. G_TYPE_INT or
GST_TYPE_INT_RANGE).前面提到过一个pad的兼容性是由一组GstStructures定义的，而一个GstStructure是由一组域定义的。每个域都有keystring和一个特定数据类型的值。Creating capabilities for filteringWhile capabilities are mainly used inside a plugin todescribe the media type of the pads, the application
programmer often also has to have basic understanding ofcapabilities in order to interface with the
plugins, especially when using filtered caps. When you’re usingfiltered caps or fixation, you’re limiting
the allowed types of media that can stream between two pads to asubset of their supported media types.
You do this using a capsfilter element in your pipeline. In orderto do this, you also need to create
your own GstCaps.通过过滤器，你可以规定两个元素之间允许通过的数据。
|
This will force the data flow between those twoelements to a certain video format, width, height and
framerate (or the linking will fail if that cannot be achieved inthe context of the elments involved). Keep
in mind that when you use gst_element_link_filtered () it willautomatically create a
capsfilter element for you and insert it into your bin or pipelinebetween the two elements you want
to connect (this is important if you ever want to disconnect thoseelements because then you will have to
disconnect both elements from the capsfilter instead).
注意，这样会在两个元素之间插入一个capsfilter，当你需要断开两个元素的连接的时候，你需要把它们从这个过滤器元素上断开。
Ghost pads
bin没有自己的pad，为了统一的把它当作一个元素使用，Ghostpads被使用，就像UNIX的符号链接。
|
A ghostpad is created using the functiongst_ghost_pad_new ():
|
