GObject 与 GStreamer 中文手册

GObject对象系统
简单的说，GObject对象系统是一个建立在GLIB基础上的，
用C语言完成的，具有跨平台特色的、灵活的、可扩展的、非常容易映射到其它语言的面向对象的框架。
如果你是一个C语言的执着的追随者，你没有理由不研究一下它。

NOTE:
glib库是Linux平台下最常用的C语言函数库，它具有很好的可移植性和实用性。
glib是Gtk +库和Gnome的基础。
glib可以在多个平台下使用，比如Linux、Unix、Windows等。glib为许多标准的、常用的C语言结构提供了相应的替代物。
中文名    glib
简    介  Linux平台下最常用的C语言函数库
特    点  很好的可移植性和实用性
类型定义  整数类型

glib库是Linux平台下最常用的C语言函数库，它具有很好的可移植性和实用性。
glib是Gtk+库和Gnome的基础。glib可以在多个平台下使用，比如Linux、Unix、Windows等。
glib为许多标准的、常用的C语言结构提供了相应的替代物。
如果在程序中要使用到glib库中的函数，则应该包含glib.h头文件（在gtk.h和gnome.h头文件中已经包含了glib.h了）
 

一、前言

大多数现代的计算机语言都带有自己的类型和对象系统，并附带算法结构。
正象GLib提供的基本类型和算法结构（如链表、哈希表等）一样，
GObject的对象系统提供了一种灵活的、可扩展的、并容易映射（到其它语言）的面向对象的C语言框架。
它的实质可以概括为：
 . 一个通用类型系统，用来注册任意的、轻便的、单根继承的、并能推导出任意深度的结构类型的界面，
   它照顾组合对象的定制、初始化和内存管理，类结构，保持对象的父子关系，处理这些类型的动态实现。
   也就是说，这些类型的实现是在运行时重置和卸载的；
 . 一个基本类型的实现集，如整型，枚举型和结构型等；
 . 一个基本对象体系之上的基本对象类型的实现的例子--GObject基本类型；
 . 一个信号系统，允许用户非常灵活的自定义虚的或重载对象的方法，并且能充当非常有效力的通知机制；
 . 一个可扩展的参数/变量体系，支持所有的能被用作处理对象属性或其它参数化类型的基本的类型。
 

二、类型（GType）与对象（GObject）

GLib中最有特色的是它的对象系统--GObject System，它是以Gtype为基础而实现的一套单根继承的C语言的面向对象的框架。
GType 是GLib 运行时类型认证和管理系统。GType API 是GObject的基础系统，所以理解GType是理解GObject的关键。
Gtype提供了注册和管理所有基本数据类型、用户定义对象和界面类型的技术实现。
（注意：在运用任一GType和GObject函数之前必需运行g_type_init()函数来初始化类型系统。）
为实现类型定制和注册这一目的，所有类型必需是静态的或动态的这二者之一。
静态的类型永远不能在运行时加载或卸载，而动态的类型则可以。
静态类型由g_type_register_static()创建，通过GTypeInfo结构来取得类型的特殊信息。
动态类型则由g_type_register_dynamic()创建，用GTypePlugin结构来取代GTypeInfo，并且还包括g_type_plugin_*()系列API。
这些注册函数通常只运行一次，目的是取得它们返回的专有类的类型标识。
还可以用g_type_register_fundamental来注册基础类型，它同时需要GTypeInfo和GTypeFundamentalInfo两个结构，
事实上大多数情况下这是不必要的，因为系统预先定义的基础类型是优于用户自定义的。
（本文重点介绍创建和使用静态的类型。）
 

三、对象的定义

在GObject系统中，对象由三个部分组成：
 . 对象的ID标识（唯一，无符号长整型，所有此类对象共同的标识）；
 . 对象的类结构（唯一，结构型，由对象的所有实例共同拥有）；
 . 对象的实例（多个，结构型，对象的具体实现）。
基于GObject的对象到底是什么样的呢？下面是基于GObject的简单对象 -- Boy的定义代码：
/* boy.h */
#ifndef __BOY_H__
#define __BOY_H__
#include <glib-object.h>
#define BOY_TYPE (boy_get_type())
#define BOY(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),BOY_TYPE,Boy))

typedef struct _Boy Boy;
typedef struct _BoyClass BoyClass;
struct _Boy {
  GObject parent;
  //
  gint age;
  gchar *name;
  void (*cry)(void);
};
struct _BoyClass {
  GObjectClass parent_class;
  //
  void (*boy_born)(void);
};
GType boy_get_type(void);
Boy*  boy_new(void);
int boy_get_age(Boy *boy);
void boy_set_age(Boy *boy, int age);
char* boy_get_name(Boy *boy);
void boy_set_name(Boy *boy, char *name);
Boy*  boy_new_with_name(gchar *name);
Boy*  boy_new_with_age(gint age);
Boy*  boy_new_with_name_and_age(gchar *name, gint age);
void  boy_info(Boy *boy);
#endif /* __BOY_H__*/

这是一段典型的C语言头文件定义，包括编译预处理，宏定义，数据结构定义和函数声明；
首先要看的是两个数据结构对象Boy和BoyClass，
结构类型_Boy是Boy对象的实例，就是说我们每创建一个Boy对象，也就同时创建了一个Boy结构。
Boy对象中的parent表示此对象的父类，GObject系统中所有对象的共同的根都是GObject类，所以这是必须的；
其它的成员可以是公共的，这里包括表示年龄的age，表示名字的name和表示方法的函数指针cry，外部代码可以操作或引用它们。
结构类型_BoyClass是Boy对象的类结构，它是所有Boy对象实例所共有的。
BoyClass中的parent_class是GObjectClass，同GObject是所有对象的共有的根一样，GObejctClass是所有对象的类结构的根。
在BoyClass中我们还定义了一个函数指针boy_born，也就是说这一函数指针也是所有Boy对象实例共有的，
所有的Boy实例都可以调用它；同样，如果需要的话，你也可以在类结构中定义其它数据成员。
其余的函数定义包括三种，
一种是取得Boy对象的类型ID的函数boy_get_type，这是必须有的；
另一种是创建Boy对象实例的函数boy_new和boy_new_with_*，这是非常清晰明了的创建对象的方式，
当然你也可以用g_object_new函数来创建对象；
第三种是设定或取得Boy对象属性成员的值的函数boy_get_*和boy_set_*。
正常情况下这三种函数都是一个对象所必需的，另外一个函数boy_info用来显示此对象的当前状态。
宏在GObject系统中用得相当广泛，也相当重要，这里我们定义了两个非常关键的宏，
BOY_TYPE宏封装了boy_get_type函数，可以直接取得并替代Boy对象的ID标识；
BOY(obj)宏是G_TYPE_CHECK_INSTANCE_CAST宏的再一次封装，
目的是将一个Gobject对象强制转换为Boy对象，这在对象的继承中十分关键，也经常用到。
 

四、对象的实现

下面的代码实现了上面的Boy对象的定义：
/* boy.c */
#include "boy.h"
enum { BOY_BORN, LAST_SIGNAL };
static gint boy_signals[LAST_SIGNAL] = { 0 };
static void boy_cry (void);
static void boy_born(void);
static void boy_init(Boy *boy);
static void boy_class_init(BoyClass *boyclass);
GType boy_get_type(void)
{
  static GType boy_type = 0;
  if(!boy_type)
  {
    static const GTypeInfo boy_info = {
      sizeof(BoyClass),
      NULL,NULL,
      (GClassInitFunc)boy_class_init,NULL,NULL,
      sizeof(Boy),
      0,
      (GInstanceInitFunc)boy_init
    };
    boy_type = g_type_register_static(G_TYPE_OBJECT,"Boy",&boy_info,0);
  }
  return boy_type;
}
static void boy_init(Boy *boy)
{
  boy->age = 0;
  boy->name = "none";
  boy->cry = boy_cry;
}
static void boy_class_init(BoyClass *boyclass)
{
  boyclass->boy_born = boy_born;
  boy_signals[BOY_BORN] = g_signal_new("boy_born",
  BOY_TYPE,
  G_SIGNAL_RUN_FIRST,
  G_STRUCT_OFFSET(BoyClass,boy_born),
  NULL,NULL,
  g_cclosure_marshal_VOID__VOID,
  G_TYPE_NONE, 0, NULL);
}
Boy *boy_new(void)
{
  Boy *boy;
  boy = g_object_new(BOY_TYPE, NULL);
  g_signal_emit(boy,boy_signals[BOY_BORN],0);
  return boy;
}
int boy_get_age(Boy *boy)
{
  return boy->age;
}
void boy_set_age(Boy *boy, int age)
{
boy->age = age;
}
char *boy_get_name(Boy *boy)
{
  return boy->name;
}
void boy_set_name(Boy *boy, char *name)
{
  boy->name = name;
}
Boy*  boy_new_with_name(gchar *name)
{
  Boy* boy;
  boy = boy_new();
  boy_set_name(boy, name);
  return boy;
}
Boy*  boy_new_with_age(gint age)
{
  Boy* boy;
  boy = boy_new();
  boy_set_age(boy, age);
  return boy;
}
Boy *boy_new_with_name_and_age(gchar *name, gint age)
{
  Boy *boy;
  boy = boy_new();
  boy_set_name(boy,name);
  boy_set_age(boy,age);
  return boy;
}
static void boy_cry (void)
{
  g_print("The Boy is crying ......\n");
}
static void boy_born(void)
{
  g_print("Message : A boy was born .\n");
}
void  boy_info(Boy *boy)
{
  g_print("The Boy name is %s\n", boy->name);
  g_print("The Boy age is %d\n", boy->age);
}
在这段代码中，出现了实现Boy对象的关键函数，这是在Boy对象的定义中未出现的，也是没必要出现的。
就是两个初始化函数，boy_init和boy_class_init，它们分别用来初始化实例结构和类结构。
它们并不被在代码中明显调用，关键是将其用宏转换为地址指针，然后赋值到GTypeInfo结构中，
然后由GType系统自行处理，同时将它们定义为静态的也是非常必要的。
GTypeInfo结构中定义了对象的类型信息，包括以下内容：
包括类结构的长度（必需，即我们定义的BoyClass结构的长度）；
基础初始化函数（base initialization function，可选）；
基础结束化函数（base finalization function，可选）； 
（以上两个函数可以对对象使用的内存来做分配和释放操作，使用时要用GBaseInitFunc和GBaseFinalizeFunc来转换为指针，
本例中均未用到，故设为NULL。）
类初始化函数（即我们这里的boy_class_init函数，用GclassInit宏来转换，可选，仅用于类和实例类型）；
类结束函数（可选）；
实例初始化函数（可选，即我们这里的boy_init函数）；
最后一个成员是GType变量表（可选）。
定义好GTypeInfo结构后就可以用g_type_register_static函数来注册对象的类型了。
g_type_register_static函数用来注册对象的类型，它的第一个参数是表示此对象的父类的对象类型
，我们这里是G_TYPE_OBJECT，这个宏用来表示GObject的父类；
第二个参数表示此对象的名称，这里为"Boy"；
第三个参数是此对象的GTypeInfo结构型指针，这里赋值为&boyinfo；
第四个参数是对象注册成功后返回此对象的整型ID标识。
g_object_new函数，用来创建一个基于G_OBJECT的对象，它可以有多个参数，
第一个参数是上面说到的已注册的对象标识ID；
第二个参数表示后面参数的数量，如果为0，则没有第三个参数；
第三个参数开始类型都是GParameter类型，它也是一个结构型，
定义为：
struct GParameter{
const gchar* name;
GValue value;
};
关于GValue，它是变量类型的统一定义，它是基础的变量容器结构，用于封装变量的值和变量的类型，可以GOBJECT文档的GVALUE部分。
 

五、信号的定义和应用

在GObject系统中，信号是一种定制对象行为的手段，同时也是一种多种用途的通知机制。
初学者可能是在GTK+中首先接触到信号这一概念的，事实上在普通的字符界面编程中也可以正常应用，这可能是很多初学者未曾想到的。
一个对象可以没有信号，也可以有多个信号。
当有一或多个信号时，信号的名称定义是必不可少的，此时C语言的枚举类型的功能就凸显出来了，
用LAST_SIGNAL来表示最后一个信号（不用实现的信号）是一种非常良好的编程风格。
这里为Boy对象定义了一个信号BOY_BORN，在对象创建时发出，表示Boy对象诞生。
同时还需要定义静态的整型指针数组来保存信号的标识，以便于下一步处理信号时使用。
对象的类结构是所有对象的实例所共有的，我们将信号也定义在对象的类结构中，
如此信号同样也是所有对象的实例所共有的，任意一个对象的实例都可以处理信号。
因此我们有必要在在类初始化函数中创建信号（这也可能是GObject设计者的初衷）。
函数g_signal_new用来创建一个新的信号，它的详细使用方法可以在GObject的API文档中找到。
信号创建成功后，返回一个信号的标识ID，如此就可以用发射信号函数g_signal_emit向指定义对象的实例发射信号，
从而执行相应的功能。
本例中每创建一个新的Boy对象，就会发射一次BOY_BORN信号，也就会执行一次我们定义的boy_born函数，
也就输出一行"Message : A boy was born ."信息。
 

六、对象的属性和方法

对象实例所有的属性和方法一般都定义在对象的实例结构中，属性定义为变量或变量指针，
而方法则定义为函数指针，如此，我们一定要定义函数为static类型，当为函数指针赋值时，才能有效。
 

七、对象的继承

以下为继承自Boy对象的Man对象的实现，Man对象在Boy对象的基础上又增加了一个属性job和一个方法bye。
#ifndef __MAN_H__
#define __MAN_H__
#include "boy.h"
#define MAN_TYPE  (man_get_type())
#define MAN(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),MAN_TYPE,Man))
typedef struct _Man Man;
typedef struct _ManClass ManClass;
struct _Man {
  Boy parent;
  char *job;
  void (*bye)(void);
};
struct _ManClass {
  BoyClass parent_class;
};
GType man_get_type(void);
Man*  man_new(void);
gchar* man_get_gob(Man *man);
void  man_set_job(Man *man, gchar *job);
Man*  man_new_with_name_age_and_job(gchar *name, gint age, gchar *job);
void man_info(Man *man);
#endif //__MAN_H__

/* man.c */
#include "man.h"
static void man_bye(void);
static void man_init(Man *man);
static void man_class_init(Man *man);
GType man_get_type(void)
{
static GType man_type = 0;
if(!man_type)
{
static const GTypeInfo man_info = {
sizeof(ManClass),
NULL, NULL,
(GClassInitFunc)man_class_init,
NULL, NULL,
sizeof(Man),
0,
(GInstanceInitFunc)man_init
};
man_type = g_type_register_static(BOY_TYPE, "Man", &man_info, 0);
}
return man_type;
}
static void man_init(Man *man)
{
man->job = "none";
man->bye = man_bye;
}
static void man_class_init(Man *man)
{
}
Man*  man_new(void)
{
Man *man;
man = g_object_new(MAN_TYPE, 0);
return man;
}
gchar* man_get_gob(Man *man)
{
return man->job;
}
void  man_set_job(Man *man, gchar *job)
{
man->job = job;
}
Man*  man_new_with_name_age_and_job(gchar *name, gint age, gchar *job)
{
Man *man;
man = man_new();
boy_set_name(BOY(man), name);
boy_set_age(BOY(man), age);
man_set_job(man, job);
return man;
}
static void man_bye(void)
{
g_print("Goodbye everyone !\n");
}
void man_info(Man *man)
{
g_print("the man name is %s\n", BOY(man)->name);
g_print("the man age is %d\n", BOY(man)->age);
g_print("the man job is %s\n", man->job);
}
关键在于定义对象时将父对象实例定义为Boy，父类设定为BoyClass，
在注册此对象时将其父对象类型设为BOY_TYPE，在设定对象属性时如用到父对象的属性要强制转换下，
如取得对象的name属性，就必须用BOY(obj)->name，因为Man本身没有name属性，而其父对象Boy有，
所以用BOY宏将其强制为Boy类型的对象。
 

八、测试我们定义的对象

#include <glib.h>
#include "boy.h"
#include "man.h"
int main(int argc, char *argv[])
{
Boy *tom, *peter;
Man *green, *brown;
g_type_init();//注意，初始化类型系统，必需
tom = boy_new_with_name("Tom");
tom->cry();
boy_info(tom);
peter = boy_new_with_name_and_age("Peter", 10);
peter->cry();
boy_info(peter);
green = man_new();
boy_set_name(BOY(green), "Green");
//设定Man对象的name属性用到其父对象Boy的方法
boy_set_age(BOY(green), 28);
man_set_job(green, "Doctor");
green->bye();
man_info(green);
brown = man_new_with_name_age_and_job("Brown", 30, "Teacher");
brown->bye();
man_info(brown);
}
Makefile文件如下：
CC = gcc
all:
$(CC) -c boy.c `pkg-config --cflags glib-2.0 gobject-2.0`
$(CC) -c man.c `pkg-config --cflags glib-2.0 gobject-2.0`
$(CC) -c main.c `pkg-config --cflags glib-2.0 gobject-2.0`
$(CC) -o simple boy.o man.o main.o `pkg-config --libs glib-2.0 gobject-2.0`
执行make命令编译，编译结束后，执行./simple运行此测试程序，输出结果如下：
Message : A boy was born .
The Boy is crying ......
The Boy name is Tom
The Boy age is 0
Message : A boy was born .
The Boy is crying ......
The Boy name is Peter
The Boy age is 10
Goodbye everyone !
the man name is Green
the man age is 28
the man job is Doctor
Goodbye everyone !
the man name is Brown
the man age is 30
the man job is Teacher
Makefile中用到`pkg-config -cflags -libs gobject-2.0`，
在GLIB中将线程（gthread），插件（gmoudle）和对象系统（gobject）这三个子系统区别对待，编译时要注意加入相应的参数。
本文只是概要的介绍了如何定义和实现GObject对象，GObject系统中还有很多相关内容，
如：枚举和标识类型（Enumeration and flags types）；
Gboxed，是Gtype系统中注册一种封装为不透明的C语言结构类型的机制；
许多对象用到的参数对象都是C结构类型，使用者不必了解其结构的内部定义，即不透明，GBoxed即是实现这一功能的机制；
标准的参数和变量类型的定义（Standard Parameter and Value Types）等，它们都以C语言来开发，是深入了解和掌握GObject的关键。
透过以上代码实现，我们还可以看出，以GLIB为基础的GTK+/GNOME开发环境所具有的独特的编程风格和独到的开发思想。
这一点在长期的编程实践中会体验得更深刻。
有了GObject系统这一基础，GTK+通过它将X窗口环境中的控件（Widget）巧妙的封装起来，
这使开发LINUX平台上的GUI应用程序更方便，更快捷。
以上代码在Redhat 8.0 Linux平台，GLIB2.2.1环境下编译通过。

 

Gstreamer应用开发手册

I. 介绍
GStreamer 是一个非常强大而且通用的流媒体应用程序框架。 
GStreamer所具备的很多优点来源于其框架的模块化: GStreamer能够无缝的合并新的插件。 
但是, 由于追求模块化和高效率, 使得GStreamer在整个框架上变的复杂, 也同时因为复杂度的提高, 
使得开发一个新的应用程序显得不是那么的简单。
这个指南试图帮助你了解GStreamer的框架(version 0.10.3.1)以方便你在GStreamer框架的基础上做开发。 
第一章节将重点关注如何开发一个简单的音频播放器, 通过对整个过程的讲解,力图使你能够理解有关GStreamer的一些概念。
在之后的章节中,我们将讨论一些关于媒体播放(playback)控制的高级问题, 这些问题包括了录音、录象和编辑等等。

第1章. 序言
本章将从技术的角度来描述本手册的总体结构。

1.1. GStreamer是什么 ?
GStreamer是一个创建流媒体应用程序的框架。
其基本设计思想来自于俄勒冈(Oregon)研究生学院有关视频管道的创意, 同时也借鉴了DirectShow的设计思想。
GStreamer的程序开发框架使得编写任意类型的流媒体应用程序成为了可能。
在编写处理音频、视频或者两者皆有的应用程序时, GStreamer可以让你的工作变得简单。
GStreamer并不受限于音频和视频处理, 它能够处理任意类型的数据流。
管道设计的方法对于实际应用的滤波器几乎没有负荷, 它甚至可以用来设计出对延时有很高要求的高端音频应用程序。
GStreamer最显著的用途是在构建一个播放器上。
GStreamer已经支持很多格式的文件了, 包括: MP3、Ogg/Vorbis、MPEG-1/2、AVI、Quicktime、 mod等等。
从这个角度看,GStreamer更象是一个播放器。
但是它主要的优点却是在于: 它的可插入组件能够很方便的接入到任意的管道当中。
这个优点使得利用GStreamer编写一个万能的可编辑音视频应用程序成为可能。
GStreamer框架是基于插件的, 有些插件中提供了各种各样的多媒体数字信号编解码器,也有些提供了其他的功能。
所有的插件都能够被链接到任意的已经定义了的数据流管道中。
GStreamer的管道能够被GUI编辑器编辑, 能够以XML文件来保存。这样的设计使得管道程序库的消耗变得非常少。
GStreamer核心库函数是一个处理插件、数据流和媒体操作的框架。
 GStreamer核心库还提供了一个API, 这个API是开放给程序员使用的---
当程序员需要使用其他的插件来编写他所需要的应用程序的时候可以使用它。

1.2. 谁需要读这个手册?
本手册是从一个程序开发人员的角度来描述GStreamer的: 
它叙述了如何利用GStreamer的开发库以及工具来编写一个基于GStreamer的应用程序。
对于想学习"如何编写插件"的朋友们, 我们建议你去参考<<插件编写指南(Plugin Writers Guide)>>。

1.3. 预备知识
为了更好的理解本手册的内容, 你应该具备基本的C语言基础。
由于GStreamer一直采用GObject编程模式, 所以本手册也假定你已经理解了GObject的基本概念。
你可能还需要一些GTK+和GDK的知识, 这方面的知识你可以参照Eric Harlow的书Developing Linux Applications with GTK+ and GDK。
另外, 当你读完本手册后, 请读一下GStreamer Plugin Writer's Guide。 
当然,你还需要关注一下其它的GStreamer文档。

1.4. 本手册结构
为了帮助你更好的学习本手册, 我们将本手册分为几个大的部分, 
每一部分阐述了一个在GStreamer应用程序开发过程中特殊而又有用的话题。
如下所示:
Part I --- GStreamer 应用程序开发手册 (0.10.9.1)给你一个关于GStreamer总的概况叙述。
Part II --- GStreamer 应用程序开发手册 (0.10.9.1)阐述GStreamer应用程序开发的基本概念。
           本章结束后, 你将可以使用GStreamer来开发你自己的音频播放器。
Part III --- GStreamer 应用程序开发手册 (0.10.9.1)我们将继续讨论一些有关GStreamer深层次的主题, 
这些主题告诉了我们为什么GStreamer能在众多的竞争者当中脱颖而出。
我们将使用动态参数和动态接口来讨论应用程序中管道的交讯问题, 我们还将讨论线程同步、时钟同步、以及其他同步问题。
这些问题的讨论不仅向你讲述如何使用GStreamer的API, 
而且还将告诉你一些基于GStreamer应用程序开发过程中所经常遇到的问题的解决办法,
 通过这些知识的学习使你更加深刻的理解GStreamer的基本概念。

Part IV --- GStreamer 应用程序开发手册 (0.10.9.1)我们将进入GStreamer 的高级编程领域。
你不需要对GStreamer所有的细节都了解清楚,但是基本的GStreamer概念仍然是需要的。
我们将讨论XML、playbin、 autopluggers等话题。

Part V --- GStreamer 应用程序开发手册 (0.10.9.1)你将学习到一些有关GStreamer与GNOME、KDE、OS、X或者Windows集成的知识, 
当然你还将学习到一些有关调试和如何处理常见问题的方法。通过这些知识的学习, 将更好的方便你使用GStreamer 

第2章. 动机和目标
从历史的角度来看，Linux在多媒体方面已经远远落后于其他的操作系统。
Microsoft's Windows 和Apple's MacOS它们对多媒体设备、多媒体创作、播放和实时处理等方面已经有了很好的支持。
另一方面，Linux对多媒体应用的综合贡献比较少，这也使得Linux很难在专业级别的软件上与MS Windows 和MacOS去竞争。
GStreamer正是为解决Linux多媒体方面当前问题而设计的。


2.1. 当前的问题
我们描述了当今Linux平台下媒体处理的一些典型问题。


2.1.1. 大量的代码复制
对于那些想要播放一个声音文件的Linux用户来说，他们必须搜索各种声音播放器来播放不同格式文件，
而在这些播放器中，大部分的都一遍又一遍地重复使用了相同的代码。
对于那些想在应用程序中嵌入视频剪辑的Linux开发人员来说，他们必须要用粗略的hacks来运行外部的视频播放器，
因为没有一套可用的库提供给开发人员来创建可定制的播放器。


2.1.2. “一个目标”媒体播放器/媒体库
典型的MPEG播放器可以播放MPEG视频和音频，多数的播放器实现了完整的底层构造来达到他们的唯一目标：播放。
没有一套有效的机制可以提供对于音频和视频数据过滤和效果处理，更没有制定在视频或音频数据中添加滤波器或特殊效果的任何规定。
如果你希望将MPEG-2视频流转为AVI文件，那么你的最佳选择是，将所有的MPEG-2解码算法从播放器分离出来，并复制到你的AVI编码器中，因为这类算法不能简单的在应用程序之间共享。
开发人员曾经尝试着创建一个可以处理多种媒体类型的库，但由于缺乏通用的API，所以如何集成就成了重要的工作了。
因为在集成的过程中，我们需要关注一些特殊的媒体类型(avi文件，libmpeg2，...)，而集成这些媒体类型文件需要一个统一的接口。
GStreamer允许将这些库与通用的API一起打包，这样就简化了集成和复用。


2.1.3. 没有统一的插件管理机制
典型的播放器对于不同的媒体类型会有不同的插件，两个媒体播放器会实现各自不同的插件机制，
所以编解码器不能方便的交换。每一个典型的媒体播放器的插管理件系统是具有其特定应用程序的需求。
缺少统一的插件机制，已经严重阻碍了二进制编解码器的发展，因为没有一家公司希望将代码移植到不同的插件机制。
GStreamer当然也采用自己的插件系统，它为插件开发者提供了一个非常丰富的框架，从而保证这些插件能够广泛应用，
并与其他插件能够无缝的交互。GStreamer为插件提供的框架是非常灵活，它足以满足大多数插件的需求。


2.1.4. 拙劣的用户感
因为上述问题的原因，使得应用程序开发人员将相当多的时间花在如何处理后端、插件机制等等问题上。
从而耽误了大部分的项目时间，这样就常常导致后端和用户界面都只完成了一半，于是就导致了拙劣的用户感。


2.1.5. 没有网络透明度的规定
当前还没有一个底层框架出现，来允许对网络透明媒体的操作。
有趣的是，一个分布式的MPEG编码器能够复制非分布式编码器的相同的算法。
并没有关于使用 GNOME 和 KDE 桌面平台的技术的规定被制定出来，因为GNOME 和 KDE 桌面平台本身还在改进和完善，
所以很难将多媒体恰当地集成到很多用户的环境中。注意到GStreamer还提供很多种方法，
这些方法提供将GSreamer与不同的桌面系统进行集成(见附录里的集成一节)，而这些方法往往都不是网络透明化。
GStreamer内核在最底层没有采用网络透明技术，只是在顶层加了作为本地使用，
这就是说，创建一个核心组件的包就变得比较容易了。GStreamer允许管道在TCP协议上分离，
使用tcp插件来实现GStreamer数据协议，这个被包含在gst-plugins模块，目录gst/tcp


2.1.6. 与Windows?的产品还存在差距
我们要想看到Linux桌面系统的成功就要立足于可靠的媒体处理。
我们必须为商业编解码器和多媒体应用扫清障碍，这样Linux才能成为多媒体领域的一个选择。


2.2. 设计目标
我们将阐述在GStreamer开发中的目标．


2.2.1. 结构清晰且威力强大
GStreamer提供一套清晰的接口给以下一些开发人员：
希望构建媒体管道的应用程序员。程序员可以使用一系列强有利的工具来创建媒体管道，而不用去写一行代码，
从而使得复杂的媒体控制变得非常简单。
插件程序员。GStreamer向插件程序员提供了简洁而简单的API来创建self-plugin(自包含)插件，
同时还集成了大量的调试和跟踪机制和工具。GStreamer也提供了一系列现实例子。


2.2.2. 面向对象的编程思想
GStreamer是依附于GLib 2.0对象模型的，熟悉GLib或者旧版本的GTK+的程序员对GStreamer将会驾轻就熟。
GStreamer采用了信号与对象属性的机制。
所有对象的属性和功能都能在运行态被查询。
GStreamer与GTK+的编程方法非常相似，需要对象模型，对象所有(ownership of objects)，参考计算（reference counting）...


2.2.3. 灵活的可扩展性能
所有的GStreamer对象都可以采用GObject继承的方法进行扩展。
所有的插件都可以被动态装载，可以独立的扩展或升级。


2.2.4. 支持插件以二进制形式发布
作为共享库发布的插件能够在运行态直接加载，插件的所有属性可以由GObject属性来设置，而无需(事实上决不)去安装插件的头文件。
我们更多的关注在插件能够独立化，运行的时候还需要很多与插件相关的因素。


2.2.5. 高性能
高性能主要体现在：
   .  使用GLib的g_mem_chunk和非模块化分配算法使得内存分配尽可能最小。
   .  插件之间的连接非常轻型(light-weight)。
      数据在管道中的传递使用最小的消耗，管道中插件之间的数据传递只会涉及指针废弃。
   .  提供了一套对目标内存直接进行操作的机制。
      例如，插件可以向X server共享的内存空间直接写数据，缓冲区也可以指向任意的内存，如声卡的内部硬件缓冲区。
   .  refcounting和写拷贝将memcpy减少到最低。子缓冲区有效地将缓冲区分离为易于管理的块。
   .  使用线程联合(cothreads)减少线程消耗。
      线程联合(cothreads)是简单又高速的方法来切换子程序，作为衡量最低消耗600个cpu周期的标准。
   .  使用特殊的插件从而支持硬件加速。
   .  采用带有说明的插件注册，这样的话只在实际需要使用该插件才会去装载。
   .  所有的判断数据都不用互斥锁。


2.2.6. 核心库与插件(core/plugins)分离
GStreamer内核的本质是media-agnostic，我们了解的仅仅是字节和块，以及包含基本的元件，
GStreamer内核的强大功能甚至能够实现底层系统工具，像cp。
所有的媒体处理功能都是由插件从外部提供给内核的，并告诉内核如何去处理特定的媒体类型。


2.2.7. 为多媒体数字信号编解码实验提供一个框架
GStreamer成为一个简单的框架，编解码器的开发人员可以试验各种不同的算法，
提高开源多媒体编解码器开发的速度，如Theora and Vorbis。

第3章. 基础概念介绍

本章将介绍GStreamer的基本概念。
理解这些概念对于你后续的学习非常重要,因为后续深入的讲解我们都假定你已经完全理解了这些概念。
 

3.1. 元件(Elements)

元件(element)是GStreamer中最重要的概念。
你可以通过创建一系列的元件(Elements),并把它们连接起来,从而让数据流在这个被连接的各个元件(Elements)之间传输。
每个元件(Elements)都有一个特殊的函数接口,对于有些元件(Elements)的函数接口它们是用于能够读取文件的数据,解码文件数据的。
而有些元件(Elements)的函数接口只是输出相应的数据到具体的设备上(例如,声卡设备)。
你可以将若干个元件(Elements)连接在一起,从而创建一个管道(pipeline)来完成一个特殊的任务,
例如,媒体播放或者录音。GStreamer已经默认安装了很多有用的元件(Elements),
通过使用这些元件(Elements)你能够构建一个具有多种功能的应用程序。
当然,如果你需要的话,你可以自己编写一个新的元件(Elements)。
对于如何编写元件(Elements)的话题在GStreamer Plugin Writer's Guide中有详细的说明。
 

3.2. 箱柜(Bins)和管道(pipelines)

箱柜(Bins)是一个可以装载元件(element)的容器。
管道(pipelines)是箱柜(Bins)的一个特殊的子类型,管道(pipelines)可以操作包含在它自身内部的所有元件(element)。
因为箱柜(Bins)本身又是元件(element)的子集,所以你能够象操作普通元件(element)一样的操作一个箱柜(Bins), 
通过这种方法可以降低你的应用程序的复杂度。你可以改变一个箱柜(Bins)的状态来改变箱柜(Bins)内部所有元件(element)的状态。
箱柜(Bins)可以发送总线消息(bus messages)给它的 子集元件(element)(这些消息包括:错误消息(error messages),
标签消息(tag messages),EOS消息(EOS messages))。
管道(pipeline)是高级的箱柜(Bins)。当你设定管道的暂停或者播放状态的时候,数据流将开始流动,
并且媒体数据处理也开始处理。一旦开始,管道将在一个 单独的线程中运行,直到被停止或者数据流播放完毕。
 

3.3. 衬垫(Pads)

衬垫(Pads)在GStreamer中被用于多个元件的链接,从而让数据流能在这样的链接中流动。 
一个衬垫(Pads)可以被看作是一个元件(element)插座或者端口,元件(element)之间的链接就是依靠着衬垫(Pads)。 
衬垫(Pads)有处理特殊数据的能力:一个衬垫(Pads)能够限制数据流类型的通过。链接成功的条件是：
只有在两个衬垫(Pads)允许通过的数据类型一致的时候才被建立。
数据类型的设定使用了一个叫做caps negotiation的方法。数据类型被为一个GstCaps变量所描述。
下面的这个比喻可能对你理解衬垫(Pads)有所帮助。一个衬垫(Pads)很象一个物理设备上的插头。 
例如一个家庭影院系统。一个家庭影院系统由一个功放(amplifier),一个DVD机,还有一个无声的视频投影组成。 
我们需要连接DVD机到功放(amplifier),因为两个设备都有音频插口;
我们还需要连接投影机到DVD机上,因为 两个设备都有视频处理插口。
但我们很难将投影机与功放(amplifier)连接起来,因为他们之间处理的是不同的 插口。
GStreamer衬垫(Pads)的作用跟家庭影院系统中的插口是一样的。
对于大部分情况,所有的数据流都是在链接好的元素之间流动。
数据向元件(element)以外流出可以通过一个或者多个 source 衬垫(Pads),
元件(element)接受数据是通过一个或者多个sink 衬垫(Pads)来完成的。
Source元件(element)和sink元件(element)分别有且仅有一个 sink 衬垫(Pads)或者source 衬垫(Pads)。
数据在这里代表的是缓冲区(buffers) (GstBuffer对象描述了数据的缓冲区(buffers)的信息)和事件(events) 
(GstEvent对象描述了数据的事件(events)信息)。 

II.构建一个应用程序
在这一部分，我们将讨论GStreamer中的一些基本概念以及一些常用的对 象，像元件、衬垫和缓存等。
我们给这些对象以一种形象化的描述，相信这样会对我们在后边学习到如何构建一条管道时大有帮助。
首先你会对GStreamer的API有个粗略的认识，用这些API来构建一个基于元件的应用程序已经绰绰有余。
然后你 会学习到如何构建一个简单的基于命令行的应用程序。
注意：在这部分我们会了解一些底层（low-level）的API以及GStreamer的 一些概念。
如果你立马想构建一个应用程序，你可能会使用一些高层（higher-level）的API，它们会在这手册的后部分被提到。
 

第4章. 初始化GStreamer

当你准备写一个GStreamer应用程序时，你仅需要通过包含头文件gst/gst.h 来访问库函数。
除此之外，不要忘记初始化GStreamer库。 
 

4.1. 简易初始化

在GStreamer库被使用前，主应用程序中应该先调用函数gst_init，
这个函数将会对GStreamer库做一些必要的初始化工作，
同时 也能够对GStreamer的命令行参数进行解析。
一个典型的初始化GStreamer库的代码 [1] 如下所示：

例4-1. 初始化GStreamer
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  const gchar *nano_str;
  guint major, minor, micro, nano;

  gst_init (&argc, &argv);

  gst_version (&major, &minor, &micro, &nano);

  if (nano == 1)
    nano_str = "(CVS)";
  else if (nano == 2)
    nano_str = "(Prerelease)";
  else
    nano_str = "";

  printf ("This program is linked against GStreamer %d.%d.%d %s\n",
          major, minor, micro, nano_str);

  return 0;
}

你可以使用GST_VERSION_MAJOR, GST_VERSION_MINOR以及GST_VERSION_MICRO 三个宏得到你的GStreamer版本信息，
或者使用函数gst_version得到当前你所调用的程序库的版本信息。
目前GStreamer使用了一种 保证主要版本和次要版本中API-/以及ABI兼容的策略。
当命令行参数不需要被GStreamer解析的时候，你可以在调用函数gst_init时使用2个NULL参数。  
注[1] 这个例子中的代码可以直接提取出来,并在GStreamer的examples/manual目录下可以找到。
 

4.2. 使用GOption接口来初始化

你同样可以使用GOption表来初始化你的参数。例子如下: 
例4-2. 使用GOption接口来初始化

#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  gboolean silent = FALSE;
  gchar *savefile = NULL;
  GOptionContext *ctx;
  GError *err = NULL;
  GOptionEntry entries[] = {
    { "silent", 's', 0, G_OPTION_ARG_NONE, &silent,
      "do not output status information", NULL },
    { "output", 'o', 0, G_OPTION_ARG_STRING, &savefile,
      "save xml representation of pipeline to FILE and exit", "FILE" },
    { NULL }
  };

  ctx = g_option_context_new ("- Your application");
  g_option_context_add_main_entries (ctx, entries, NULL);
  g_option_context_add_group (ctx, gst_init_get_option_group ());
  if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
    g_print ("Failed to initialize: %s\n", err->message);
    g_error_free (err);
    return 1;
  }

  printf ("Run me with --help to see the Application options appended.\n");

  return 0;
}

如例子中的代码所示，你可以通过 GOption 表来定义你的命令行选项。
将表与由gst_init_get_option_group函数返回的选项组一同传给GLib初始化函数。
通过使用GOption表来初始化GSreamer，你的程序还可以解析除标准GStreamer选项以外的命令行选项.
 

第5章. 元件(Element)

对程序员来说，GStreamer 中最重要的一个概念就是 GstElement 对象。
元件是构建一个媒体管道的基本块。所有上层(high-level)部件都源自GstElement对象。
任何一个解码器编码器、分离器、视频/音频输出部件实际上都是一个 GstElement对象。
 

5.1. 什么是元件?

对程序员来说，元件就像一个黑盒子。
你从元件的一端输入数据，元件对数据进行一些处理，然后数据从元件的另一段输出。
拿一个解码元件来说，你输入一 些有特定编码的数据，元件会输出相应的解码数据。
在下一章 (Pads and capabilities)，你将学习到更多关于对元件进行数据输入输出的知识，
以及如何在你的程序中实现数据的输入输出。
 

5.1.1.源元件

源元件(Source elements)为管道产生数据，比如从磁盘或者声卡读取数据。 
图 5-1 形象化的源元件。我们总是将源衬垫(source pad)画在元件的右端。
图 5-1.形象化的源元件


源元件不接收数据，仅产生数据。
你可从上图中明白这一点，因为上图仅有一个源衬垫(右端)，同样的, 源衬垫也仅产生数据(对外部而言)。
 

5.1.2. 过滤器(filters)、转换器(convertors)、分流器(demuxers)、整流器(muxers)以及编解码器(codecs)

过滤器(Filters)以及类过滤元件(Filter-like elements)都同时拥有输入和输出衬垫。
他们对从输入衬垫得到的数据进行操作，然后将数据提供给输出衬垫。
音量元件(filter)、视频转换器 (convertor)、Ogg分流器或者 Vorbis 解码器都是这种类型的元件。
类过滤元件可以拥有任意个的源衬垫或者接收衬垫。
像一个视频分流器可能有一个接收衬垫以及多个(1-N)源衬垫，每个接收衬垫对应一种元数据流 (elementary stream)。
相反地，解码器只有一个源衬垫及一个接收衬垫。
图 5-2. 形象化的过滤元件

图5-2 形象化了类过滤元件。
这个特殊的元件同时拥有源端和接收端。
接收输入数据的接收衬垫在元件的左端，源衬垫在右端。

图 5-3. 形象化的拥有多个输出的过滤元件

图5-3 显示了另一种了类过滤元件。它有多个输出衬垫(source pad)。
Ogg分流器是个很好的实例。因为Ogg流包含了视频和音频。
一个源衬垫可能包含视频元数据流，另一个则包含音频元数据流。
当一个新的衬垫被创 建时，分流器通常会产生一个信号。程序员可以在信号处理事件中处理新的元数据流。
 

5.1.3.接收元件

接收元件是媒体管道的末端，它接收数据但不产生任何数据。
写磁盘、利用声卡播放声音以及视频输出等都是由接收元件实现的。
图 5-4 显示了接收元件。

图 5-4. 形象化的接收元件
 

5.2. 创建一个GstElement对象

创建一个元件的最简单的方法是通过函数gst_element_factory_make ()。 
这个函数使用一个已存在的工厂对象名和一个新的元件名来创建元件。
创建完之后, 你可以用新的元件名在箱柜（bin）中查询得到这个元件。
这个名字同样可以用来调试程序的输 出。你可以通过传递 NULL 来得到一个默认的具有唯一性的名字。
当你不再需要一个元件时，你需要使用 gst_object_unref ()来对它进行解引用。 
这会将一个元件的引用数减少1。任何一个元件在创建时，其引用记数为1。当其引用记数为0时，该元件会被销毁。

下面的例子[1] 显示了如果通过一个fakesrc工厂对象来创建一个名叫source的元件。
程序会检查元件是否创建成功。检查完毕后，程序会销毁元件。
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElement *element;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element */
  element = gst_element_factory_make ("fakesrc", "source");
  if (!element) {
    g_print ("Failed to create element of type 'fakesrc'\n");
    return -1;
  }

  gst_object_unref (GST_OBJECT (element));

  return 0;
}

gst_element_factory_make 是2个函数的速记。
一个GstElement 对象由工厂对象创建而来。
为了创建一个元件，你需要使用一个唯一的工厂对象名字来访问一个  GstElementFactory对象。
gst_element_factory_find ()就 是做了这样的事。

下面的代码段创建了一个工厂对象，这个工厂对象被用来创建一个fakesrc元件 —— 伪装的数据源。
函数 gst_element_factory_create() 将会使用元件工厂并根据给定的名字来创建一个元件。
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElementFactory *factory;
  GstElement * element;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element, method #2 */
  factory = gst_element_factory_find ("fakesrc");
  if (!factory) {
    g_print ("Failed to find factory of type 'fakesrc'\n");
    return -1;
  }
  element = gst_element_factory_create (factory, "source");
  if (!element) {
    g_print ("Failed to create element, even though its factory exists!\n");
    return -1;
  }

  gst_object_unref (GST_OBJECT (element));

  return 0;
}
    
注[1] 这个例子中的代码可以直接提取出来,并在GStreamer的examples/manual目录下可以找到。
 

5.3. 使用元件作为GObject 对象

GstElement的属性大多通过标准的 GObject 对象实现的。
使用 GObject 的方法可以对GstElement实行查询、设置、获取属性的值。同样 GParamSpecs 也被支持。
每个 GstElement 都从其基类 GstObject 继承了至少一个“名字”属性。
这个名字属性将在函数gst_element_factory_make ()或者函数gst_element_factory_create ()中使用到。
你可通过函数 gst_object_set_name 设置该属性，通过 gst_object_get_name 得到一个对象的名字属性。
你也可以通过下面的方法来得到一个对象的名字属性。 
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElement *element;
  gchar *name;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* create element */
  element = gst_element_factory_make ("fakesrc", "source");

  /* get name */
  g_object_get (G_OBJECT (element), "name", &name, NULL);
  g_print ("The name of the element is '%s'.\n", name);
  g_free (name);

  gst_object_unref (GST_OBJECT (element));

  return 0;
}
    
大多数的插件(plugins)都提供了一些额外的方法，这些方法给程序员提供了更多的关于该元件的注册信息或配置信息。
gst-inspect 是一个用来查询特定元件特性（properties）的实用工具。
它也提供了诸如函数简短介绍，参数的类型及其支持的范围等信息。关于 gst-inspect 更详细的信息请参考附录。
关于GObject特性更详细的信息，我们推荐你去阅读 GObject手册 以及  Glib 对象系统介绍.
GstElement对象同样提供了许多的 GObject 信号方法来实现一个灵活的回调机制。
你同样可以使用 gst-inspect来检查一个特定元件所支持的信号。
总之，信号和特性是元件与应用程序交互的最基本的方式。
 

5.4. 深入了解元件工厂

在前面的部分，我们简要介绍过 GstElementFactory 可以用来创建一个元件的实例，
但是工厂元件不仅仅只能做这件事，工厂元件作为在 GStreamer 注册系统中的一个基本类型，
它可以描述所有的插件(plugins)以及由GStreamer创建的元件。这意味着工厂元件可以应用于一些自动元件实例， 
像自动插件(autopluggers); 或者创建一个可用元件列表，像管道对应用程序的类似操作(像GStreamer Editor) 。 
 

5.4.1.通过元 件工厂得到元件的信息

像gst-inspect 这样的工具可以给出一个元件的概要: 
插件(plugin)的作者、
描述性的元件名称(或者简称)、
元件的等级（rank）
以及元件的类别(category)。

类别可以用来得到一个元件的类型，这个类型是在使用工厂元件创建该元件时做创建的。
例如类别可以是 Codec/Decoder/Video(视频解码器)、Source/Video(视频发生器)、Sink/Video(视频输出器)。
音频也有类似的类别。同样还存在 Codec/Demuxer和Codec/Muxer，甚至更多的类别。
Gst-inspect将会列出当前所有的工厂对象，gst-inspect <factory-name> 将会列出特定工厂对象的所有概要信息。 
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElementFactory *factory;

  /* init GStreamer */
  gst_init (&argc, &argv);

  /* get factory */
  factory = gst_element_factory_find ("audiotestsrc");
  if (!factory) {
    g_print ("You don't have the 'audiotestsrc' element installed!\n");
    return -1;
  }

  /* display information */
  g_print ("The '%s' element is a member of the category %s.\n"
           "Description: %s\n",
           gst_plugin_feature_get_name (GST_PLUGIN_FEATURE (factory)),
           gst_element_factory_get_klass (factory),
           gst_element_factory_get_description (factory));

  return 0;
}
      
你可以通过gst_registry_pool_feature_list (GST_TYPE_ELEMENT_FACTORY)得到所有在GStreamer中注册过的工厂元件。
 

5.4.2. 找出元件所包含的衬垫

工厂元件最有用处的功能可能是它包含了对元件所能产生的衬垫的一个详细描述，
以及这些衬垫的功能(以行外话讲: 就是指这些衬垫所支持的媒体类型)，
而得到 这些信息是不需要将所有的插件(plugins)都装载到内存中。
这可用来给一个编码器提供一个编码列表，或在多媒体播放器自动加载插件时发挥作用。
目前 所有基于 GStreamer 的多媒体播放器以及自动加载器(autoplugger)都是以上述方式工作。
当我们在下一章：衬垫与功能（ Pads and capabilities）中学习到 GstPad 与 GstCaps 时，会对上面的特性有个更清晰的了解。

5.5. 链接元件

通过将一个源元件，零个或多个类过滤元件，和一个接收元件链接在一起，你可以建立起一条媒体管道。
数据将在这些元件间流过。这是 GStreamer 中处理媒体的基本概念。
图5-5 用3个链接的元件形象化了媒体管道。
图5-5.形象化3个链接的元件
 
通过链接这三个元件，我们创建了一条简单的元件链。
元件链中源元件("element1")的输出将会是类过滤元件 ("element2")的输入。
类过滤元件将会对数据进行某些操作，
然后将数据输出给最终的接收元件("element3")。
把上述过程想象成一个简单的 Ogg/Vorbis 音频解码器。
源元件从磁盘读取文件。
第二个元件就是Ogg/Vorbis 音频解码器
。最终的接收元件是你的声卡，它用来播放经过解码的音频数据。
我们将在该手册的后部分用一个简单的图来构建这个 Ogg/Vorbis 播放器。
上述的过程用代码表示为: 
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElement *pipeline;
  GstElement *source, *filter, *sink;

  /* init */
  gst_init (&argc, &argv);

  /* create pipeline */
  pipeline = gst_pipeline_new ("my-pipeline");

  /* create elements */
  source = gst_element_factory_make ("fakesrc", "source");
  filter = gst_element_factory_make ("identity", "filter");
  sink = gst_element_factory_make ("fakesink", "sink");

  /* must add elements to pipeline before linking them */
  gst_bin_add_many (GST_BIN (pipeline), source, filter, sink, NULL);

  /* link */
  if (!gst_element_link_many (source, filter, sink, NULL)) {
    g_warning ("Failed to link elements!");
  }

[..]

}
    
对于一些特定的链接行为，可以通过函数gst_element_link () 以及 gst_element_link_pads()来实现。
你可以使用不同的gst_pad_link_* ()函数来得到单个衬垫的引用并将它们链接起来。
更详细的信息请参考API手册。

注意:在链接不同的元件之前，你需要确保这些元件都被加在同一个箱柜中，
因为将一个元件加载到一个箱柜中会破坏该元件已存在的一些链接关系。
同时，你不能直接链接不在同一箱柜或管道中的元件。
如果你想要连接处于不同层次中的元件或衬垫，你将使用到精灵衬垫(关于精灵衬垫更多的信息将在后续章节中讲到) 。
 

5.6. 元件状态

一个元件在被创建后，它不会执行任何操作。所以你需要改变元件的状态，使得它能够做某些事情。 
Gstreamer中，元件有四种状态，每种状态都有其特定的意义。
这四种状态为:
  . GST_STATE_NULL:   默认状态。该状态将会回收所有被该元件占用的资源。
  . GST_STATE_READY:  准备状态。
                      元件会得到所有所需的全局资源，这些全局资源将被通过该元件的数据流所使用。
                      例如打开设备、分配缓存等。但在这种状态下，数据流仍未开始被处 理，
                      所以数据流的位置信息应该自动置0。
                      如果数据流先前被打开过，它应该被关闭，并且其位置信息、特性信息应该被重新置为初始状态。
  . GST_STATE_PAUSED: 在这种状态下，元件已经对流开始了处理，但此刻暂停了处理。
                      因此该状态下元件可以修改流的位置信息，读取或者处理流数据，
                      以及一旦状态变为 PLAYING，流可以重放数据流。这种情况下，时钟是禁止运行的。
                      总之， PAUSED 状态除了不能运行时钟外，其它与 PLAYING 状态一模一样。
                      处于 PAUSED 状态的元件会很快变换到 PLAYING 状态。
                      举例来说，视频或音频输出元件会等待数据的到来，并将它们压入队列。
                      一旦状态改变，元件就会处理接收到的数据。同样，视频接收元件能够播放数据的第 一帧。
                      (因为这并不会影响时钟)。自动加载器（Autopluggers）可以对已经加载进管道的插件进行这种状态转换。
                      其它更多的像codecs或者 filters这种元件不需要在这个状态上做任何事情。
  . GST_STATE_PLAYING: PLAYING 状态除了当前运行时钟外，其它与 PAUSED 状态一模一样。
                      你可以通过函数gst_element_set_state()来改变一个元件的状态。
                      你如果显式地改变一个元件的状态，GStreamer可能会 使它在内部经过一些中间状态。
                      例如你将一个元件从 NULL 状态设置为 PLAYING 状态，
                      GStreamer在其内部会使得元件经历过 READY 以及 PAUSED 状态。

当处于GST_STATE_PLAYING 状态，管道会自动处理数据。
它们不需要任何形式的迭代。 GStreamer 会开启一个新的线程来处理数据。
GStreamer 同样可以使用 GstBus在管道线程和应用程序现成间交互信息。
详情请参考 第 7 章。 
 

第6章. 箱柜（Bins）

箱柜是一种容器元件。你可以往箱柜中添加元件。由于箱柜本身也是一种元件，所以你可以像普通元件一样 操作箱柜。
因此，先前关于元件(Elements) 那章的内容同样可以应用于箱柜。
 

6.1.什么是箱柜

箱柜允许你将一组有链接的元件组合成一个大的逻辑元件。你不再需要对单个元件进行操作，而仅仅操作箱柜。
当你在构建一个复杂的 管道时，你会发现箱柜的巨大优势，因为它允许你将复杂的管道分解成一些小块。
箱柜同样可以对包含在其中的元件进行管理。
它会计算数据怎样流入箱柜，并对流入的数据流制定一个最佳的计划（generate an optimal plan）。
计划制定（Plan generation）是GStreamer中最复杂的步骤之一。你可从16.2部分更详细地了解这个部分。
图6-1. 形象化的箱柜


GStreamer程序员经常会用到的一个特殊的箱柜：
管道：是一种允许对所包含的元件进行安排（scheduling）的普通容器。
顶层（toplevel）箱柜必须为一个管道。因 此每个GStreamer应用程序都至少需要一个管道。
当应用程序启动后，管道会自动运行在后台线程中。  
 

6.2. 创建箱柜

你可以通过使用创建其他元件的方法来创建一个箱柜，如使用元件工厂等。
当然也有一些更便利的函数来创建箱柜— (gst_bin_new()和 gst_pipeline_new ())。
你可以使用gst_bin_add()往箱柜中增加元件，使用gst_bin_remove()移除箱柜中的元件。
当你往箱 柜中增加一个元件后，箱柜会对该元件产生一个所属关系;
当你销毁一个箱柜后，箱柜中的元件同样被销毁 (dereferenced);
当你将一个元件从箱柜移除后，该元件会被自动销毁(dereferenced)。
#include <gst/gst.h>

int
main (int   argc,
      char *argv[])
{
  GstElement *bin, *pipeline, *source, *sink;

  /* init */
  gst_init (&argc, &argv);

  /* create */
  pipeline = gst_pipeline_new ("my_pipeline");
  bin = gst_pipeline_new ("my_bin");
  source = gst_element_factory_make ("fakesrc", "source");
  sink = gst_element_factory_make ("fakesink", "sink");

  /* set up pipeline */
  gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
  gst_bin_add (GST_BIN (pipeline), bin);
  gst_element_link (source, sink);

[..]

}
    
有多种方法来查询一个箱柜中的元件。你可以通过函数gst_bin_get_list()得到一个箱柜中所有元件的一个列表。 
详细信息请参考API手册 GstBin 部分。
 

6.3.自定义箱柜

程序员可以自定义能执行特定任务的箱柜。例如，你可以参照下面的代码写一个 Ogg/Vorbis 解码器。
int
main (int   argc,
      char *argv[])
{
  GstElement *player;


  /* init */
  gst_init (&argc, &argv);


  /* create player */
  player = gst_element_factory_make ("oggvorbisplayer", "player");


  /* set the source audio file */
  g_object_set (player, "location", "helloworld.ogg", NULL);


  /* start playback */
  gst_element_set_state (GST_ELEMENT (player), GST_STATE_PLAYING);
[..]
}
    
自定义的箱柜可以同插件或XML解释器一起被创建。
你可从 Plugin Writers Guide得到更多关于创建自定义箱柜的信息。 
gst-plugins-base中的playbin与decodebin元件都是自定义箱柜的例子。 

 

第7章. 总线(Bus)

总线是一个简单的系统，它采用自己的线程机制将一个管道线程的消息分发到一个应用程序当中。
总线的优势是：当使用GStreamer的时候，应用程序不需要线程识别，即便GStreamer已经被加载了多个线程。
每一个管道默认包含一个总线，所以应用程序不需要再创建总线。
应用程序只需要在总线上设置一个类似于对象的信号处理器的消息处理器。
当主循环运行的时候，总线将会轮询这个消息处理器是否有新的消息，当消息被采集到后，总线将呼叫相应的回调函数来完成任务。
 

7.1. 如何使用一个总线(Bus)

使用总线有两种方法，如下：
  . 运行GLib/Gtk+ 主循环 (你也可以自己运行默认的GLib的主循环)，然后使用侦听器对总线进行侦听。
    使用这种方法，GLib的主循环将轮询总线上是否存在新的消息，当存在新的消息的时候，总线会马上通知你。
    在这种情况下，你会用到gst_bus_add_watch () / gst_bus_add_signal_watch ()两个函数。
    当使用总线时，设置消息处理器到管道的总线上可以使用gst_bus_add_watch ()。 
    来创建一个消息处理器来侦听管道。每当管道发出一个消息到总线，这个消息处理器就会被触发，
    消息处理器则开始检测消息信号类型（见下章）从而决定哪些事件将被处理。
    当处理器从总线删除某个消息的时候，其返回值应为TRUE。
  . 自己侦听总线消息，使用gst_bus_peek () 和/或 gst_bus_poll () 就可以实现。
#include <gst/gst.h>


static GMainLoop *loop;


static gboolean
my_bus_callback (GstBus     *bus,
GstMessage *message,
gpointer    data)
{
  g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));


  switch (GST_MESSAGE_TYPE (message)) {
    case GST_MESSAGE_ERROR: {
      GError *err;
      gchar *debug;


      gst_message_parse_error (message, &err, &debug);
      g_print ("Error: %s\n", err->message);
      g_error_free (err);
      g_free (debug);


      g_main_loop_quit (loop);
      break;
    }
    case GST_MESSAGE_EOS:
      /* end-of-stream */
      g_main_loop_quit (loop);
      break;
    default:
      /* unhandled message */
      break;
  }


  /* we want to be notified again the next time there is a message
   * on the bus, so returning TRUE (FALSE means we want to stop watching
   * for messages on the bus and our callback should not be called again)
   */
  return TRUE;
}


gint
main (gint   argc,
      gchar *argv[])
{
  GstElement *pipeline;
  GstBus *bus;


  /* init */
  gst_init (&argc, &argv);


  /* create pipeline, add handler */
  pipeline = gst_pipeline_new ("my_pipeline");


  /* adds a watch for new message on our pipeline's message bus to
   * the default GLib main context, which is the main context that our
   * GLib main loop is attached to below
   */
  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
  gst_bus_add_watch (bus, my_bus_callback, NULL);
  gst_object_unref (bus);


[..]


  /* create a mainloop that runs/iterates the default GLib main context
   * (context NULL), in other words: makes the context check if anything
   * it watches for has happened. When a message has been posted on the
   * bus, the default main context will automatically call our
   * my_bus_callback() function to notify us of that message.
   * The main loop will be run until someone calls g_main_loop_quit()
   */
  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);


  /* clean up */
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_element_unref (pipeline);
  gst_main_loop_unref (loop)


  return 0;
}
    
理解消息处理器在主循环的线程context被调用是相当重要的，因为在总线上管道和应用程序之间的交互是异步，
所以上述方法无法适用于实时情况，比如音频轨道、无间隔播放（理论上的）、视频效果之间的交叉混合。
如果需要满足实时要求，实现上述功能，你就需要编写一个GStreamer插件来实现在管道中直接触发回调。
而对于一些初级的应用来说，使用从管道传递消息给应用程序的方法来实现应用程序与管道的交互，还是非常有用的。
这种方法的好处是GStreamer内部所有的线程将被应用程序隐藏，而开发人员也不必去担心线程问题。
注意：如果你使用了默认的GLib主循环来实现管道与应用程序的交互，建议你可以将“消息”信号链接到总线上，
而不必在管道上使用侦听器，这样对于所有可能的消息类型，你就不需用switch()，
只要连接到所需要的信号格式为"message::<type>"，其中<Type>是一种消息类型（见下一节对消息类型的详细解释）
上面的代码段也可以这样写：
GstBus *bus;


[..]


bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline);
gst_bus_add_signal_watch (bus);
g_signal_connect (bus, "message::error", G_CALLBACK (cb_message_error), NULL);
g_signal_connect (bus, "message::eos", G_CALLBACK (cb_message_eos), NULL);


[..]
    
如果你没有使用GLib主循环，默认的消息信号将会无效，
然而，你可以导出一个小助手给集成提供你使用的主循环，启动产生总线信号。 
(详细见 documentation )　

 

7.2. 消息类型(Message types)

GStreamer有几种由总线传递的预定义消息类型，这些消息都是可扩展的。
插件可以定义另外的一些消息，应用程序可以有这些消息的绝对代码或者忽略它们。
强烈推荐应用程序至少要处理错误消息并直接的反馈给用户。


所有的消息都有一个消息源、类型和时间戳。
这个消息源能被用来判断由哪个元件发出消息。
例如，在众多的消息中，应用程序只对上层的管道发出的消息感兴趣（如状态变换的提示）。
下面列出所有的消息种类、代表的意义，以及如何解析具体消息的内容。
  . 错误、警告和消息提示：
    它们被各个元件用来在必要的时候告知用户现在管道的状态。
    错误信息表明有致命的错误并且终止数据传送。
    错误应该被修复，这样才能继续管道的工作。
    警告并不是致命的，但是暗示有问题存在。
    消息提示用来告知非错误的信息。
    这些消息含有一个带有主要的错误类型和消息的GError，和一个任选的调试字符串。
    这两项都可以用gst_message_parse_error (), _parse_warning () 以及 _parse_info ()三个函数来提取其信息。
    当使用完毕后,错误和修正字符串都将被释放。
  . 数据流结束(End-of-stream)提示：
    当数据流结束的时候，该消息被发送。管道的状态不会改变，但是之后的媒体操作将会停止。
    应用程序可以通过收到这一消息来跳到播放列表的下一首歌。
    在数据流结束提示出现之后，仍然可以通过向后搜索来回到以前数据流前面的位置。
    之后的播放工作将会自动的继续执行。这个消息没有特殊的参数。
  . 标签(Tags):
    当元数据在数据流中被找到的时候，此消息被发送。
    一个管道可以发出多个Tag(如元数据的描述里有艺术家、歌曲名，另外的例子如流的信息采样率和比特率)。
    应用程序应该将元数据存储在缓存里。函
    数gst_message_parse_tag () 被用来解析tag的列表，当该列表不再使用的时候,函数gst_tag_list_free () 释放其相应的tag。
  . 状态转换(State-changes)：
    当状态成功的转换时发送该消息。函数gst_message_parse_state_changed ()可以用来解析转换中的新旧状态。
  . 缓冲(Buffering):
    当缓冲网络数据流时此消息被发送。你可以通过函数gst_message_get_structure ()的返回值，来解析"buffer-percent" 属性，
    从而手动的得到缓冲进度（该缓冲进度以百分比的形式表示）。
  . 元件消息（Element messages）：
    它是一组特殊的消息，用以标识一个特定元件。这样一组特殊的消息通常表述了一些额外的信息。
    元件的信息应该被详细的描述，因为这样一些元件信息将被作为消息而发送给其他元件。
    例如：'qtdemux' QuickTime 整流器（demuxer）应该把'redirect'信息保存于该元件信息当中，
    以便在某种特殊情况下将'redirect'元件信息发送出去。
  . Application-specific消息：
    我们可以将取得的消息结构解析出来，从而得到有关Application-specific消息的任何信息。
    通常这些信息是能够被安全地忽略。


应用程序消息主要用于内部，以备从一些线程排列信息到主线程应用的需求。
这些在使用元件信号的应用中非常实用(这些信号在数据流线程的上下文被发射)。 

 

第8章. 衬垫(Pads)及其功能

如我们在Elements一章中看到的那样，衬垫(Pads)是元件对 外的接口。
数据流从一个元件的源衬垫(source pad)到另一个元件的接收衬垫(sink pad)。
衬垫的功能(capabilities)决定了一个元件所能处理的媒体类型。
在这章的后续讲解中，我们将对衬垫的功能做更详细的说明。 (见第8.2节).

 

8.1. 衬垫(Pads)

一个衬垫的类型由2个特性决定:
  . 它的数据导向(direction)以及它的时效性(availability)。


正如我们先前提到 的，Gstreamer定义了2种衬垫的数据导向:源衬垫以及接收衬垫。
衬垫的数据导向这个术语是从元件内部的角度给予定义的: 元件通过它们的接收衬垫接收数据，通过它们的源衬垫输出数据。
如果通过一张图来形象地表述，接收衬垫画在元件的左侧，而源衬垫画在元件的右侧，数据从左向右流动。 [1]


衬垫的时效性比衬垫的数据导向复杂得多。一个衬垫可以拥有三种类型的时效性: 
  . 永久型(always)、随机型(sometimes)、请求型(on request)。
三种时效性的意义顾名思义: 永久型的衬垫一直会存在，
随机型的衬垫只在某种特定的条件下才存在(会随机消失的衬垫也属于随机型)，
请求型的衬垫只在应用程序明确发出请求时才出现。

 

8.1.1. 动态（随机）衬垫

一些元件在其被创建时不会立刻产生所有它将用到的衬垫。
例如在一个Ogg demuxer的元件中可能发生这种情况。这个元件将会读取Ogg流，
每当它在Ogg流中检测到一些元数据流时(例如vorbis，theora )，它会为每个元数据流创建动态衬垫。
同样，它也会在流终止时删除该衬垫。动态衬垫在demuxer这种元件中可以起到很大的作用。
运行gst-inspect oggdemux只会显示出一个衬垫在元件中: 
一个名字叫作'sink'的接收衬垫，其它的衬垫都处于'休眠'中，
你可以从衬垫模板(pad template)中的"Exists: Sometimes"的属性看到这些信息。
衬垫会根据你所播放的Ogg文件的类型而产生，认识到这点 对于你创建一个动态管道特别重要。
当元件通过它的随机型(sometimes)衬垫模板创建了一个随机型(sometimes)的衬垫的时侯，
你可以通过对该元件绑定一个信号处理器(signal handler)，通过它来得知衬垫被创建。下面一段代码演示了如何这样做:
名叫'sink'的接收衬垫，其它的衬垫都处于'休眠'中，显而易见这是衬垫”有时存在”的特性。
衬垫会根据你所播放的Ogg文件的类型而产生，这点在你 准备创建一个动态管道时显得特别重要，
当元件创建了一个”有时存在”的衬垫时，你可以通过对该元件触发一个信号处理器(signal handler) 来得知衬垫被创建。
下面一段代码演示了如何这样做:
#include <gst/gst.h>

static void
cb_new_pad (GstElement *element,
   GstPad     *pad,
   gpointer    data)
{
  gchar *name;


  name = gst_pad_get_name (pad);
  g_print ("A new pad %s was created\n", name);
  g_free (name);


  /* here, you would setup a new pad link for the newly created pad */
[..]


}


int 
main (int   argc,
      char *argv[]) 
{
  GstElement *pipeline, *source, *demux;
  GMainLoop *loop;


  /* init */
  gst_init (&argc, &argv);


  /* create elements */
  pipeline = gst_pipeline_new ("my_pipeline");
  source = gst_element_factory_make ("filesrc", "source");
  g_object_set (source, "location", argv[1], NULL);
  demux = gst_element_factory_make ("oggdemux", "demuxer");


  /* you would normally check that the elements were created properly */


  /* put together a pipeline */
  gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
  gst_element_link_pads (source, "src", demux, "sink");


  /* listen for newly created pads */
  g_signal_connect (demux, "pad-added", G_CALLBACK (cb_new_pad), NULL);


  /* start the pipeline */
  gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);


[..]


}
      

8.1.2. 请求衬垫

元件同样可以拥有请求衬垫(request pads)。这种衬垫不是自动被创建，而是根据请求被创建的。
这在多路复用(multiplexers)类型的元件中有很大的用处。例如 aggregators以及tee元件。
Aggregators 元件可以把多个输入流合并成一个输出流; 
tee元件正好相反，它只有一个输入流，然后根据请求把数据流发送到不同的输出衬垫
。只要应用程序需要另一份数据流，它可以简单的从tee元件请求到一个 输出衬垫。
下面一段代码演示了怎样在一个”tee”元件请求一个新的输出衬垫:
static void
some_function (GstElement *tee)
{
  GstPad * pad;
  gchar *name;


  pad = gst_element_get_request_pad (tee, "src%d");
  name = gst_pad_get_name (pad);
  g_print ("A new pad %s was created\n", name);
  g_free (name);


  /* here, you would link the pad */
[..]


  /* and, after doing that, free our reference */
  gst_object_unref (GST_OBJECT (pad));
}
      
gst_element_get_request_pad()方法可以从一个元件中得到一个衬垫，这个衬垫基于衬垫模板的名字(pad template)。
同样可以请求一个同其它衬垫模板兼容的衬垫，这点在某些情况下非常重要。
比如当你想要将一个元件连接到一个多路复用型的元件时，你就需要请求一个带兼容性的衬垫。
gst_element_get_compatible_pad()方法可以得到一个带兼容性的衬垫。
下面一段代码将从一个基于Ogg的带多输入衬垫的元件中请求一个带兼容性的衬垫。
static void
link_to_multiplexer (GstPad     *tolink_pad,
    GstElement *mux)
{
  GstPad *pad;
  gchar *srcname, *sinkname;


  srcname = gst_pad_get_name (tolink_pad);
  pad = gst_element_get_compatible_pad (mux, tolink_pad);
  gst_pad_link (tolinkpad, pad);
  sinkname = gst_pad_get_name (pad);
  gst_object_unref (GST_OBJECT (pad));


  g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
  g_free (sinkname);
  g_free (srcname);
}
      
注[1]事实上，数据流可以逆流（upstream）地在一个元件中从源衬垫到接收衬垫。
但数据总是从一个元件的源衬垫到另一个元件的接收衬垫。

 

8.2.衬垫(Pads)的性能

由于衬垫对于一个元件起了非常重要的作用，因此就有了一个术语来描述能够通过衬垫或当前通过衬垫的数据流。
这个术语就是功能 (capabilities)。在这里，我们将简要介绍什么是衬垫的功能以及怎么使用它们。
这些足以使我们对这个概念有个大 致的了解。
如果想要对衬垫的功能有更深入的了解，并知道在GStreamer 中定义的所有的衬垫的功能，
请参考插件开发手册 Plugin Writers Guide。


衬垫的功能(capabilities)是与衬垫模板(pad templates)以及衬垫实例相关联的。
对于衬垫模板，衬垫的功能(capabilities)描述的是:
  . 当通过该衬垫模板创建了一个衬垫后,该衬垫允许通过的媒体类型。
对于衬垫实例，功能可以描述所有可能通过该衬垫的媒体类型(通常是该衬垫实例所属的衬垫模板的功能的一份拷贝)，
或者是当前已经通过该衬垫的流媒体类型。前一种情况，该衬垫实例还未有任何数据流在其中通过。

 

8.2.1. 分解功能

衬垫的功能通过GstCaps 对象来进行描述。一个GstCaps对象会包含一个或多个 GstStructure。
一个 GstStructure描述一种媒体类型。
一个被数据流通过的衬垫(negotiated pad)存在功能集(capabilities set)，每种功能只包含一个GstStructure结构。
结构中只包含固定的值。但上述约束并不对尚未有数据流通过的衬垫(unnegotiated pads)或衬垫模板有效。
下面给出了一个例子，你可以通过运行 gst-inspect vorbisdec 看到"vorbisdec" 元件的一些功能。
你可能会看到2个衬垫: 源衬垫和接收衬垫，2个衬垫的时效性都是永久型，并且每个衬垫都有相应的功能描述。
接收衬垫将会接收vorbis编码的音频数据，其 mime-type显示为"audio/x-vorbis"。
源衬垫可以将解码后的音频数据采样(raw audio samples)发送给下一个元件，其 mime-type显示为为"audio/x-raw-int"。
源衬垫的功能描述中还包含了一些其它的特性: 音频采样率(audio samplerate)、声道数、以及一些你可能并不太关心的信息。
Pad Templates:
  SRC template: 'src'
    Availability: Always
    Capabilities:
      audio/x-raw-float
                   rate: [ 8000, 50000 ]
               channels: [ 1, 2 ]
             endianness: 1234
                  width: 32
          buffer-frames: 0
 
  SINK template: 'sink'
    Availability: Always
    Capabilities:
      audio/x-vorbis
      

8.2.2. 特性与值

特性(Properties)用来描述功能中的额外信息(注:除数据流类型之外的信息)。
一条特性由一个关键字和一个值组 成。下面是一些值的类型:
基本类型，几乎涵盖了Glib 中的所有GType类型。这些类型为每条特性(Properties)指明了一个明确，非动态的值。
例子如下所示:
  . 整型(G_TYPE_INT): 明确的数值（相对范围值）。
  . 布尔类型:(G_TYPE_BOOLEAN):  TRUE 或FALSE。
  . 浮点类型:(G_TYPE_FLOAT): 明确的浮点数。
  . 字符串类型:(G_TYPE_STRING): UTF-8 编码的字符串。
  . 分数类型:(GST_TYPE_FRACTION): 由整数做分子分母的分数。
  . 范围类型(Range types):由GStreamer注册的且属于GTypes的一种数据类型。
    它指明了一个范围值。范围类型通常被用来指示支持的音频采样率范围或者支持 的视频文件大小范围。
    GStreamer 中又有2种不同类型的范围值。
  . 整型范围值(GST_TYPE_INT_RANGE): 用最大和最小边界值指明了一个整型数值范围。
    举例来说: "vorbisdec"元件的采样率范围为8000-50000。
  . 浮点范围值(GST_TYPE_FLOAT_RANGE): 用最大和最小边界值指明了一个浮点数值范围。
  . 分数范围值(GST_TYPE_FRACTION_RANGE): 用最大和最小边界值指明了一个分数数值范围。
  . 列表类型(GST_TYPE_LIST):可以在给定的列表中取任何一个值。
    示例:某个衬垫的功能如果想要表示其支持采样率为44100Hz以及48000Hz的数据，
    它可以用一个包含44100和48000的列表 数据类型。
  . 数组类型(GST_TYPE_ARRAY): 一组数据。数组中的每个元素都是特性的全值(full value)。
    数组中的元素必须是同样的数据类型。这意味着一个数组可以包含任意的整数，整型的列表，整型范围的组合。
    对于浮点数与字符串类型也是如此， 但一个数组不能同时包含整数与浮点数。
    示例: 对于一个多于两个声道的音频文件，其声道布局(channel layout)需要被特别指明。
    (对于单声道和双声道的音频文件除非明确指明在特性中指明其声道数，否则按默认处理)。
    因此声道布局应该用一个枚举数组类 型来存储。每个枚举值代表了一个喇叭位置。
    与 GST_TYPE_LIST类型不一样的是，数组类型是作为一个整体来看待的。

 

8.3.衬垫(Pads)性能的用途

衬垫的功能(Capabilities)(简称 caps)描述了两个衬垫之间的数据流类型，或者它们所支持的数据流类型。功能主要用于以下用途:
  . 自动填充(Autoplugging): 
    根据元件的功能自动找到可连接的元件。所有的自动充填器(autopluggers)都采用的这种方法。
  . 兼容性检测(Compatibility detection): 
    当两个个衬垫连接时，GStreamer 会验证它们是否采用的同样的数据流格式进行交互。
    连接并验证两个衬垫是否兼容的过程叫”功能谈判”(caps negotiation)。
  . 元数据(Metadata): 通过读取衬垫的功能(capabilities),应用程序能够提供有关当前流经衬垫的正在播放的媒体类型信息。
    而这个信息我们叫做元数据(Metadata)。
  . 过滤(Filtering): 应用程序可以通过衬垫的功能(capabilities)来给两个交互的衬垫之间的媒体类型加以限制，
    这些被限制的媒体类型的集合应该是两个交互的衬垫共同支持的格式集的子集。
    举例来说:应用程序可以使用"filtered caps"指明两个 交互的衬垫所支持的视频大小(固定或不固定)。
    在本手册的后面部分 Section 18.2，你可以看到一个使用带过滤功能(filtered caps)衬垫的例子。
    你可以往你的管道中插入一个 capsfilter元件，并设置其衬垫的功能(capabilities)属性，
    从而实现衬垫的功能(capabilities)的过滤。功能过滤器(caps filters)一般放在一些转换元件后面，
    将数据在特定的位置强制转换成特定的输出格式。
    
这些转换元件有: audioconvert、audioresample、ffmpegcolorspace 和 videoscale。

8.3.1. 使用衬垫的功能(capabilities)来操作元数据

一个衬垫能够有多个功能。功能(GstCaps)可以用一个包含一个或多个 GstStructures 的数组来表示。
每个GstStructures由一个名字字符串(比如说 "width")和相应的值(类型可能为G_TYPE_INT或GST_TYPE_INT_RANGE)构成。
值得注意的是，这里有三种不同的衬垫的功能(capabilities)需要区分:
衬垫的可能功能(possible capabilities)(通常是通过对衬垫模板使用gst-inspect 得到)，
衬垫的允许功能(allowed caps)(它是衬垫模板的功能的子集，具体取决于每对交互衬垫的可能功能)， 
衬垫的最后协商功能(lastly negotiated caps)(准确的流或缓存格式，只包含一个结构，以及没有像范围值或列表值这种不定变量)。
你可以通过查询每个功能的结构得到一个衬垫功能集的所有功能。你可以通过gst_caps_get_structure()得到一个功能的 GstStructure，
通过gst_caps_get_size()得到一个GstCaps对象中的GstStructure数量。
简易衬垫的功能(capabilities)(simple caps )是指仅有一个GstStructure，
固定衬垫的功能(capabilities)(fixed caps)指其仅有一个GstStructure，且没有可变的数据类型(像范围或列表等)。
另外还有两种特殊的功能 - 任意衬垫的功能(capabilities)(ANY caps)和空衬垫的功能(capabilities)(empty caps)。
下面的例子演示了如何从一个固定的视频功能提取出宽度和高度信息：
static void
read_video_props (GstCaps *caps)
{
  gint width, height;
  const GstStructure *str;


  g_return_if_fail (gst_caps_is_fixed (caps));


  str = gst_caps_get_structure (caps, 0);
  if (!gst_structure_get_int (str, "width", &width) ||
      !gst_structure_get_int (str, "height", &height)) {
    g_print ("No width/height available\n");
    return;
  }


  g_print ("The video size of this set of capabilities is %dx%d\n",
  width, height);
}
      

8.3.2. 功能(capabilities)应用于过滤器

由于衬垫的功能(capabilities)常被包含于插件(plugin)中，且用来描述衬垫支持的媒体类型，
所以程序员在为了在插件(plugin)间 进行交互时，尤其是使用过滤功能(filtered caps)时，
通常需要对衬垫功能有着基本的理解。当你使用过滤功能(filtered caps)或固定功能(fixation)时，
你就对交互的衬垫间所允许的媒体类型做了限制，限制其为交互的衬垫所支持的媒体类型的一个子集。
你可以通过 在管道中使用capsfilter元件实现上述功能，而为了做这些，你需要创建你自己的GstCaps。
这里我们给出最容易的方法是，你可以通过gst_caps_new_simple()函数来创建你自己的GstCaps。
static gboolean
link_elements_with_filter (GstElement *element1, GstElement *element2)
{
  gboolean link_ok;
  GstCaps *caps;


  caps = gst_caps_new_simple ("video/x-raw-yuv",
       "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
     "width", G_TYPE_INT, 384,
     "height", G_TYPE_INT, 288,
     "framerate", GST_TYPE_FRACTION, 25, 1,
     NULL);


  link_ok = gst_element_link_filtered (element1, element2, caps);
  gst_caps_unref (caps);


  if (!link_ok) {
    g_warning ("Failed to link element1 and element2!");
  }


  return link_ok;
}
      
上述代码会将两个元件间交互的数据限制为特定的视频格式、宽度、高度以及帧率(如果没达到这些限制条件，两个元件就会连接失败)。
请记住:当你使用 gst_element_link_filtered()时，Gstreamer会自动创建一个capsfilter元件，将其加入到你的箱柜或管道中， 
并插入到你想要交互的两个元件间。(当你想要断开两个元件的连接时，你需要注意到这一点)。
在某些情况下，当你想要在两个衬垫间创建一个更精确的带过滤连接的功能集时，
你可以用到一个更精简的函数- gst_caps_new_full (): 
static gboolean
link_elements_with_filter (GstElement *element1, GstElement *element2)
{
  gboolean link_ok;
  GstCaps *caps;
                                                                                
  caps = gst_caps_new_full (
      gst_structure_new ("video/x-raw-yuv",
"width", G_TYPE_INT, 384,
"height", G_TYPE_INT, 288,
"framerate", GST_TYPE_FRACTION, 25, 1,
NULL),
      gst_structure_new ("video/x-raw-rgb",
"width", G_TYPE_INT, 384,
"height", G_TYPE_INT, 288,
"framerate", GST_TYPE_FRACTION, 25, 1,
NULL),
      NULL);


  link_ok = gst_element_link_filtered (element1, element2, caps);
  gst_caps_unref (caps);


  if (!link_ok) {
    g_warning ("Failed to link element1 and element2!");
  }


  return link_ok;
}
      
关于GstStructure以及GstCaps的详细API信息可以参考API参考手册。

 

8.4. 精灵衬垫(Ghost pads)

你可以从图 8-1看 到，箱柜没有一个属于它自己的衬垫，这就是”精灵衬垫”的由来。
图8-1. 没有使用精灵衬垫的GstBin元件
 
精灵衬垫来自于箱柜中某些元件，它同样可以在该箱柜中被直接访问。精灵衬垫与UNIX文件系统中的符号链接很类似。
使用箱柜，你可以在你的代码中将 箱柜当作一个普通元件来使用。
图 8-2. 使用了精灵衬垫的GstBin元件
 
图 8-2 显示了一个精灵衬垫。最左边元件的接收衬垫同样也是整个箱柜的精灵衬垫。
由于精灵衬垫看起来与其它衬垫没什么区别，而且与其它衬垫有着类似的功能。
所以它 们可以加到任何一种元件上，而不仅仅是GstBin。
通过函数gst_ghost_pad_new ()可以创建一个ghostpad ：
#include <gst/gst.h>


int
main (int   argc,
      char *argv[])
{
  GstElement *bin, *sink;
  GstPad *pad;


  /* init */
  gst_init (&argc, &argv);


  /* create element, add to bin */
  sink = gst_element_factory_make ("fakesink", "sink");
  bin = gst_bin_new ("mybin");
  gst_bin_add (GST_BIN (bin), sink);


  /* add ghostpad */
  pad = gst_element_get_pad (sink, "sink");
  gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
  gst_object_unref (GST_OBJECT (pad));


[..]


}
    
上面的例子中，箱柜不仅有精灵衬垫，而且还存在一个带名叫”sink”的接收衬垫的元件。
因此这个箱柜可以作为那个元件的替代者。你可以将其它的元 件与这个箱柜进行连接。 

 

第9章. 缓冲区(Buffers)和事件(Events)

管道的数据流由一组缓冲区和事件组成，缓冲区包括实际的管道数据，事件包括控制信息，如寻找信息和流的终止信号。
所有这些数据流在运行的时候自动的流过管道。这一章将主要为你阐述这些概念。

 

9.1. 缓冲区(Buffers)

缓冲区包含了你创建的管道里的数据流。通常一个源元件会创建一个新的缓冲区，
同时元件还将会把缓冲区的数据传递给下一个元件。当使用GStreamer底层构造来创建一个媒体管道的时候，
你不需要自己来处理缓冲区,元件将会为你处理这些缓冲区。
一个缓冲区主要由以下一个组成：
  . 指向某块内存的指针
  . 内存的大小
  . 缓冲区的时间戳
  . 一个引用计数，指出了缓冲区所使用的元件数。没有元件可引用的时候，这个引用将用于销毁缓冲区。


这里有一个简单的例子，我们先创建了一个缓冲区，然后为这个缓冲区分配内存，然后将数据存放在缓冲区中，并传递至下一个元件。
该元件读取数据，处理某些事件（像创建一个新的缓冲区并进行解码），对该缓冲区解引用，这将造成数据空闲，
导致缓冲区被销毁。典型的音频和视频解码器就是这样工作的。
尽管如此，还有一些更为复杂的设定，元件会适当的修改缓冲区，也就是说，不会分配一个新的缓冲区。
元件也可以写入硬件内存（如视频捕获源）或是使用XShm从X-server分配内存。缓冲区只能读，等等。

 

9.2. 事件(Events)

事件是一系列控制粒子，随着缓冲区被发送到管道的上游和下游。
下游事件通知流状态相同的元件，可能的事件包括中断，flush，流的终止信号等等。
在应用程序与元件之间的交互以及事件与事件之间的交互中,上游事件被用于改变管道中数据流的状态，如查找。
对于应用程序来说，上游事件非常重要，下游事件则是为了说明获取更加完善的数据概念上的图像。
由于大多数应用程序以时间为单位查找，下面的例子实现了同样的功能：
static void
seek_to_time (GstElement *element,
     guint64     time_ns)
{
  GstEvent *event;


  event = gst_event_new_seek (GST_SEEK_METHOD_SET |
     GST_FORMAT_TIME,
     time_ns);
  gst_element_send_event (element, event);
}
    
以上代码主要是说明其具体的工作原理，快捷算法是一个函数 gst_element_seek ()。 

 

第10章. 你的第一个应用程序

在这一章中将会对先前的章节做个总结。它通过一个小程序来讲述GStreamer 的各个方面:
初始化库，创建元件，将元件打包进管道，播放管道中的数据内容。
通过这些步骤，你将能够自己开发一个简易的，支持Ogg/Vorbis格式的音频播放器。

 

10.1. 第一个Hello world程序

我们现在开始创建第一个简易的应用程序 – 一个基于命令行并支持Ogg/Vorbis格式的音频播放器。
我们只需要使用标准的 Gstreamer的组件(components)就能够开发出这个程序。
它通过命令行来指定播放的文件。让我们开始这段旅程:
如在 第4章中学到的那样，
第一件事情是要通过gst_init()函数来初始化 GStreamer库。确保程序包含了 gst/gst.h 头文件，
这样GStreamer库中的对象和函数才能够被正确地定义。你可以通过#include <gst/gst.h> 指令来包含 gst/gst.h 头文件。
然后你可以通过函数gst_element_factory_make ()来创建不同的元件。
对于Ogg/Vorbis音频播放器，我们需要一个源元件从磁盘读取文件。 GStreamer 中有一个”filesrc”的元件可以胜任此事。
其次我们需要一些东西来解析从磁盘读取的文件。 GStreamer 中有两个元件可以分别来解析Ogg/Vorbis文件。
第一个将 Ogg 数据流解析成元数据流的元件叫”oggdemux”。第二个是 Vorbis 音频解码器，通常称为”vorbisdec”。
由于”oggdemux”为每个元数据流动态创建衬垫，所以你得为”oggdemux”元件设置"pad- added" 的事件处理函数。
像8.1.1部分讲 解的那样，"pad-added" 的事件处理函数可以用来将 Ogg 解码元件和 Vorbis 解码元件连接起来。
最后，我们还需要一个音频输出元件 - “alsasink”。它会将数据传送给 ALSA 音频设备。
万事俱备，只欠东风。我们需要把所有的元件都包含到一个容器元件中 -  GstPipeline，
然后在这个管道中一直轮循，直到我们播放完整的歌曲。我们在第6章中 学习过如何将元件包含进容器元件，
在5.6部分了解过元件的状 态信息。我们同样需要在管道总线上加消息处理来处理错误信息和检测流结束标志。 
现在给出我们第一个音频播放器的所有代码:
#include <gst/gst.h>


/*
 * Global objects are usually a bad thing. For the purpose of this
 * example, we will use them, however.
 */


GstElement *pipeline, *source, *parser, *decoder, *conv, *sink;


static gboolean
bus_call (GstBus     *bus,
 GstMessage *msg,
 gpointer    data)
{
  GMainLoop *loop = data;


  switch (GST_MESSAGE_TYPE (msg)) {
    case GST_MESSAGE_EOS:
      g_print ("End-of-stream\n");
      g_main_loop_quit (loop);
      break;
    case GST_MESSAGE_ERROR: {
      gchar *debug;
      GError *err;


      gst_message_parse_error (msg, &err, &debug);
      g_free (debug);


      g_print ("Error: %s\n", err->message);
      g_error_free (err);


      g_main_loop_quit (loop);
      break;
    }
    default:
      break;
  }


  return TRUE;
}


static void
new_pad (GstElement *element,
GstPad     *pad,
gpointer    data)
{
  GstPad *sinkpad;
  /* We can now link this pad with the audio decoder */
  g_print ("Dynamic pad created, linking parser/decoder\n");


  sinkpad = gst_element_get_pad (decoder, "sink");
  gst_pad_link (pad, sinkpad);


  gst_object_unref (sinkpad);
}


int
main (int   argc,
      char *argv[])
{
  GMainLoop *loop;
  GstBus *bus;


  /* initialize GStreamer */
  gst_init (&argc, &argv);
  loop = g_main_loop_new (NULL, FALSE);


  /* check input arguments */
  if (argc != 2) {
    g_print ("Usage: %s <Ogg/Vorbis filename>\n", argv[0]);
    return -1;
  }


  /* create elements */
  pipeline = gst_pipeline_new ("audio-player");
  source = gst_element_factory_make ("filesrc", "file-source");
  parser = gst_element_factory_make ("oggdemux", "ogg-parser");
  decoder = gst_element_factory_make ("vorbisdec", "vorbis-decoder");
  conv = gst_element_factory_make ("audioconvert", "converter");
  sink = gst_element_factory_make ("alsasink", "alsa-output");
  if (!pipeline || !source || !parser || !decoder || !conv || !sink) {
    g_print ("One element could not be created\n");
    return -1;
  }


  /* set filename property on the file source. Also add a message
   * handler. */
  g_object_set (G_OBJECT (source), "location", argv[1], NULL);


  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
  gst_bus_add_watch (bus, bus_call, loop);
  gst_object_unref (bus);


  /* put all elements in a bin */
  gst_bin_add_many (GST_BIN (pipeline),
   source, parser, decoder, conv, sink, NULL);


  /* link together - note that we cannot link the parser and
   * decoder yet, becuse the parser uses dynamic pads. For that,
   * we set a pad-added signal handler. */
  gst_element_link (source, parser);
  gst_element_link_many (decoder, conv, sink, NULL);
  g_signal_connect (parser, "pad-added", G_CALLBACK (new_pad), NULL);


  /* Now set to playing and iterate. */
  g_print ("Setting to PLAYING\n");
  gst_element_set_state (pipeline, GST_STATE_PLAYING);
  g_print ("Running\n");
  g_main_loop_run (loop);


  /* clean up nicely */
  g_print ("Returned, stopping playback\n");
  gst_element_set_state (pipeline, GST_STATE_NULL);
  g_print ("Deleting pipeline\n");
  gst_object_unref (GST_OBJECT (pipeline));


  return 0;
}


    
我们现在创建了一个完整的管道。我们可以用下面的图来形象地描述这个管道:
图10-1. "hello world"管道
 

10.2. 编译运行helloworld.c

通过命令 
$ gcc -Wall $(pkg-config --cflags --libs gstreamer-0.10) helloworld.c -o helloworld 
来编译例子helloworld。
编译这个应用程序，GStreamer需要使用pkg-config来 得到编译器和连接标志。
如果你的GStreamer不是以默认的方式安装，请确保环境变量 PKG_CONFIG_PATH 设置正确($libdir/pkgconfig)。
如果环境变量设置不对，应用程序不会通过编译。
你可以通过./helloworld file.ogg命令来 运行例子。用你自己的Ogg/Vorbis 文件来代替 file.ogg 运行上述命令。

 

10.3. 结论

对我们的第一个例子做个总结。像你看到的那样，我们是通过非常底层(low-level)的API来建立的管道，这样也非常有效。
在这份手册的后面 部分，你可以看到通过使用一些高层(higher-level)的API
可以花费比这个例子更少的代码来建立一个有着更强大功能的媒体播放器。
我们将在 GStreamer应用程序开发手册(0.10.9.1)的第四部分讨 论这个话题。
我们现在需要对 GStreamer 的内部机制有更深的了解。
在这个例子中，我们可以很容易的用其它的元件来代替"filesrc"元件。
比如从网络读取数据的元件，或者从其它任何能够更好的将数据与你桌面环 境整和在一起的元件。
同样你可以使用其它的解码器来支持其它的媒体类型。如果你的程序不是运行在Linux上，
而是运行在 Mac OS X，Windows 或 FreeBSD 上，你可以使用不同的音频接收元件。 
甚至你可以使用filesink将数据写到磁盘上而不是将它们播放出来。 
所有这些，都显示了 GStreamer 元件的一个巨大优势 - 可重用性(reusability)。