diff --git a/docs/gst/gstreamer.hierarchy b/docs/gst/gstreamer.hierarchy index 247904e9da..3fcebbbbf3 100644 --- a/docs/gst/gstreamer.hierarchy +++ b/docs/gst/gstreamer.hierarchy @@ -9,6 +9,7 @@ GtkObject GstFakeSrc GstFakeSink GstDiskSrc + GstHttpSrc GstFdSrc GstSineSrc GstFdSink diff --git a/docs/gst/tmpl/gstcaps.sgml b/docs/gst/tmpl/gstcaps.sgml index 38ae27e70c..b3e9fb9b4d 100644 --- a/docs/gst/tmpl/gstcaps.sgml +++ b/docs/gst/tmpl/gstcaps.sgml @@ -7,7 +7,67 @@ Capabilities of pads GstCaps is used to attach capabilities to a pad. Capabilities are made of -a mime-type and a set of properties. +a mime-type and a set of properties. GstCaps can be named and chained into +a list, which is then a GstCaps on its own. + + +GstCaps are created with gst_caps_new(), which takes a name, a mime type and +a pointer to a #GstProps. A convenience macro with a cleaner syntax is +available to create a caps with GST_CAPS_NEW(). The following example shows how +to create a GstCaps. + + GstCaps *caps; + + caps = gst_caps_new ( + "my_caps", /* capability name */ + "audio/raw", /* mime type */ + gst_props_new ( /* properties */ + "format", GST_PROPS_STRING ("float"), + "layout", GST_PROPS_INT (5), + NULL)); + + +The following code example is equivalent to the above example: + + GstCaps *caps; + + caps = GST_CAPS_NEW ( + "my_caps", /* capability name */ + "audio/raw", /* mime type */ + "format", GST_PROPS_STRING ("float"), + "channels", GST_PROPS_INT (5) + ); + + + +GstCaps are refcounted with gst_caps_ref() and gst_caps_unref(). + + +GstCaps can be chained with the gst_caps_append(), gst_caps_prepend() and +gst_caps_chain() functions. Use gst_caps_get_by_name() to get a named caps +structure from a chained list. + + +To get the properties of a caps structure the functions +gst_caps_get_boolean(), gst_caps_get_fourcc_int(), gst_caps_get_int(), +gst_caps_get_string(), which all take a property name as an argument. + + +The properties of the caps structure can be modified with gst_caps_set, which +takes a list of key value pairs in the #GstProps syntax as shown by this example: + + + GstCaps *caps; + .... + + gst_caps_set (caps, "format", GST_PROPS_STRING ("int"), NULL); + gst_caps_set (caps, "channels", GST_PROPS_INT (20), NULL); + + + + +before modifying a GstCaps, it is a good idea to make a copy if it first with +gst_caps_copy_on_write(). This will copy thr GstCaps if the refcount is >1. diff --git a/docs/gst/tmpl/gstcpu.sgml b/docs/gst/tmpl/gstcpu.sgml index cbf398b4a3..0c3c2e5f89 100644 --- a/docs/gst/tmpl/gstcpu.sgml +++ b/docs/gst/tmpl/gstcpu.sgml @@ -10,7 +10,9 @@ Request the features of the CPU. This module can be used when developing plugins. It is typically used to enable special optimisations based on the features of the CPU. - + + +You'll get a bitmask of flags with gst_cpu_get_flags(). diff --git a/docs/gst/tmpl/gsthttpsrc.sgml b/docs/gst/tmpl/gsthttpsrc.sgml index 2ba4a00e8d..f1c74b859a 100644 --- a/docs/gst/tmpl/gsthttpsrc.sgml +++ b/docs/gst/tmpl/gsthttpsrc.sgml @@ -14,3 +14,14 @@ Reads data from a URL. + + +Specify the location of the file. The location must be a fully qualified URL. + + + + +Specify how many bytes to read at a time. + + + diff --git a/docs/gst/tmpl/gstpad.sgml b/docs/gst/tmpl/gstpad.sgml index b243f14d7a..d4ba520522 100644 --- a/docs/gst/tmpl/gstpad.sgml +++ b/docs/gst/tmpl/gstpad.sgml @@ -6,14 +6,66 @@ The connection between Elements -Elements are connected to each other via "pads", which are extremely light-weight generic -connections. +#GstElement are connected to each other via "pads", which are extremely light-weight generic +connections. After two pad are retrieved from an element with gst_element_get_pad(), the pads +can be connected with gst_pad_connect(). + + +PedTemplates are use to describe the runtime behaviour of an element and what pads it +will have during its lifetime. Pads are typically created from a padtemplate with +GST_PADTEMPLATE_NEW() or with the factory macro GST_PADTEMPLATE_FACTORY(). + + +Pad and PadTemplates have #GstCaps attached to it to describe the media type they +are capable of dealing with. gst_pad_get_caps() and gst_pad_set_caps() are used to +manipulate the caps of the pads. gst_padtemplate_get_caps() is used to get the +caps of a padtemplate. It's not possible to modify the caps of a padtemplate after +creation. The following code example shows the code to create a pad from a padtemplate. + +GST_PADTEMPLATE_FACTORY (my_factory, + "sink", /* the name of the pad */ + GST_PAD_SINK, /* the direction of the pad */ + GST_PAD_ALWAYS, /* when this pad will be present */ + GST_CAPS_NEW ( /* the capabilities of the padtemplate */ + "my_caps", + "audio/raw", + "format", GST_PROPS_STRING ("int"), + "channels", GST_PROPS_INT_RANGE (1, 6) + ) +) +void +my_method (void) +{ + GstPad *pad; + + pad = gst_pad_new_from_template (GST_PADTEMPLATE_GET (my_factory), "sink"); + ... +} + +Pads created from a padtemplate cannot set capabilities that are incompatible with +the padtemplates capabilities. + + +Pads without padtemplates can be created with gst_pad_new() which takes a direction and +a name as an argument. + + +gst_pad_get_parent() will retrieve the GstElement that owns the pad. + + +GstElements creating a pad will typicilally use the various gst_pad_set_*_function() calls +to register callbacks for various events on the pads. + + +GstElements will use gst_pad_push() and gst_pad_pull() to push out or pull a buffer in. The +gst_pad_pullregion() function can be used to request for a buffer with a specific offset (in +time or in bytes). - +#GstCaps, #GstElement @@ -638,26 +690,26 @@ Call the EOS function of the pad - +Get the length of the region that is being pulled. -@pad: +@pad: the real pad to query. - +Get the offset of the region that is being pulled. -@pad: +@pad: the real pad to query. - +Get the type of the region that is being pulled. -@pad: +@pad: the real pad to query. @@ -785,26 +837,26 @@ Get the EOS function of the real pad. - +Get the negotiate function from the real pad. -@pad: +@pad: the real pad to query. - +Get the newcaps function from the real pad. -@pad: +@pad: the real pad to query. - +Get the bufferpoolfunction from the real pad. -@pad: +@pad: the real pad to query. @@ -840,7 +892,8 @@ Indicates when this pad will become available. @GST_PAD_ALWAYS: the pad is always available @GST_PAD_SOMETIMES: the pad will become available depending on the media stream -@GST_PAD_REQUEST: +@GST_PAD_REQUEST: th pad is only available on request with +gst_element_request_pad_by_name() or gst_element_request_compatible_pad(). @@ -855,65 +908,66 @@ Indicates when this pad will become available. - +Get a handle to the padtemplate #GstCaps -@templ: +@templ: the template to query - +Get the direction of the padtemplate. -@templ: +@templ: the template to query - +Get the nametemplate of the padtemplate. -@templ: +@templ: the template to query - +Get the presence of the padtemplate. -@templ: +@templ: the template to query - +Create a new padtemplate. -@padname: -@dir: -@pres: -@a...: +@padname: the nametemplate for the pads that will be created with this template +@dir: the direction of the pads. +@pres: the presence of the pads. +@a...: the capabilities of this padtemplate usually created with GST_CAPS_NEW() - +Create a factory for a padtemplate. This can be used if you only want one instance +of the padtemplate. Use GST_PADTEMPLATE_GET() to get the unique padtemplate. -@name: -@padname: -@dir: -@pres: -@a...: +@name: th name of the factory +@padname: the nametemplate of the pads +@dir: the direction of the pads. +@pres: the presence of the pads. +@a...: the capabilities of this padtemplate, usually created with GST_CAPS_NEW() - +Get the padtemplate of the factory created with GST_PADTEMPLATE_FACTORY() -@fact: +@fact: the factory name to get the padtemplate from. @@ -927,8 +981,6 @@ Indicates when this pad will become available. @caps: @Varargs: @Returns: - -@factory: @@ -948,8 +1000,6 @@ Indicates when this pad will become available. @templ: @parent: @Returns: - -@pad: diff --git a/docs/gst/tmpl/gstparse.sgml b/docs/gst/tmpl/gstparse.sgml index 5cd6fc2996..44961a548f 100644 --- a/docs/gst/tmpl/gstparse.sgml +++ b/docs/gst/tmpl/gstparse.sgml @@ -7,7 +7,36 @@ Parses commandline syntax into a pipeline. This method allows you to create a pipeline from a command -line syntax description. +line syntax description. The following example creates a simple +mp3 player. + + GstElement *pipeline; + + /* create a pipeline to hold our elements */ + pipeline = gst_pipeline_new ("launch"); + + /* build a pipeline in the pipeline */ + gst_parse_launch ("disksrc location=some.mp3 ! mad ! osssink", GST_BIN (pipeline)); + + /* play the thing */ + gst_element_set_state (pipeline, GST_STATE_PLAYING); + + while (gst_bin_iterate (GST_BIN (pipeline))); + + gst_element_set_state (pipeline, GST_STATE_NULL); + + + + + +Elements are separated with a , properties are set with +property=value, specific pads +of an element are selected by replacing the with +padname. + + +Elements can be added to a bin by embracing them with . Threads +can be made with . diff --git a/docs/gst/tmpl/gstpipeline.sgml b/docs/gst/tmpl/gstpipeline.sgml index f486cfb193..05c2302598 100644 --- a/docs/gst/tmpl/gstpipeline.sgml +++ b/docs/gst/tmpl/gstpipeline.sgml @@ -12,12 +12,6 @@ including threading, as well as provide simple interfaces to common functions, like 'Play'. - -The pipeline also has the capability to autoplug. This feature -allows you to only define the input/output plugins and let the -pipeline figure out what plugins to use. - - diff --git a/docs/gst/tmpl/gstplugin.sgml b/docs/gst/tmpl/gstplugin.sgml index ff213c9327..c22231e17a 100644 --- a/docs/gst/tmpl/gstplugin.sgml +++ b/docs/gst/tmpl/gstplugin.sgml @@ -6,13 +6,51 @@ Dynamically loadable Elements -GStreamer is extensible so GstElements can be loaded at runtime. - +GStreamer is extensible so GstElements can be loaded at runtime. A plugin +system can provide one or more of the following basic GStreamer +objects factories: + + + + A #GstElementFactory: the components to build a pipeline. + + + + + A #GstTypeFactory: A MIME type and an optional typefind function. + + + + + A #GstAutoplugFactory: An object used to automatically construct pipelines. + + + + + +A new plugin is created with gst_plugin_new(). this function will return a handle +to the GstPlugin or NULL if the plugin could not be created. + + +Once a GstPlugin element has been created, you can add the different types of factories +to it with gst_plugin_add_factory(), gst_plugin_add_type(), gst_plugin_add_autoplugger(). + + +Gstreamer plugins should have a method plugin_init that is called +by the loader. + + +use gst_plugin_find(), gst_plugin_get_list(), gst_plugin_get_factory_list(), gst_plugin_get_type_list() and +gst_plugin_get_autoplug_list() to query the plugin repository. + + +Plugins are always automaticlly loaded so you don't need to call gst_plugin_load() explicitly +to bring it into memory. - +#GstElement, #GstType, #GstAutoplug diff --git a/docs/gst/tmpl/gstprops.sgml b/docs/gst/tmpl/gstprops.sgml index ed99e9a333..381f899c8d 100644 --- a/docs/gst/tmpl/gstprops.sgml +++ b/docs/gst/tmpl/gstprops.sgml @@ -12,7 +12,7 @@ are usually used in conjunction with GstCaps. -GstCaps +#GstCaps diff --git a/docs/gst/tmpl/gstreamer-unused.sgml b/docs/gst/tmpl/gstreamer-unused.sgml index 29a890b92d..1e74019d1e 100644 --- a/docs/gst/tmpl/gstreamer-unused.sgml +++ b/docs/gst/tmpl/gstreamer-unused.sgml @@ -67,14 +67,6 @@ Query the element for the current mime type - - - - - -@pad: -@buf: - @@ -83,13 +75,7 @@ Query the element for the current mime type @pad: @parent: - - -Specify the location of the file. The location must be a fully qualified URL. - - - - + @@ -97,7 +83,7 @@ Specify the location of the file. The location must be a fully qualified URL. @pad: @buf: - + @@ -112,6 +98,14 @@ Specify the location of the file. The location must be a fully qualified URL. @Returns: + + + + + +@pad: +@buf: + @@ -206,6 +200,12 @@ the stream. @gstsrc: the object which received the signal. @arg1: the object which received the signal + + + + + + @@ -213,12 +213,6 @@ the stream. @Returns: - - - - - - @@ -372,16 +366,16 @@ subclass use this to start their flag enumeration @audiosink: @channels: + +Generic connection between elements. + + - -Generic connection between elements. - - @@ -661,13 +655,13 @@ Specify the current offset in the file. @sheight: @bytes_per_line: - + - + @@ -701,17 +695,24 @@ Specify the current offset in the file. @name: @Returns: + + + + + + - + +@src: @@ -721,13 +722,6 @@ Specify the current offset in the file. @id: @sink: - - - - - -@src: - @@ -1141,13 +1135,6 @@ GstFilter @obj: - - - - - -@Returns: - @@ -1155,6 +1142,13 @@ GstFilter @obj: + + + + + +@Returns: + @@ -1163,6 +1157,13 @@ GstFilter @pad: @Returns: + + + + + +@thread: + @@ -1173,13 +1174,6 @@ GstFilter @y1: @y2: - - - - - -@thread: - Flags for the GstSrc element @@ -1255,13 +1249,6 @@ Defines an entry for a padfactory. @obj: - - - - - -@klass: - @@ -1269,6 +1256,13 @@ Defines an entry for a padfactory. @Returns: + + + + + +@klass: + Indicates a sinkpad for the padfactory. @@ -1304,6 +1298,12 @@ Indicates a sinkpad for the padfactory. @pad: @Returns: + + + + + + @@ -1312,12 +1312,6 @@ Indicates a sinkpad for the padfactory. @name: @Returns: - - - - - - @@ -1427,12 +1421,6 @@ This macro sets the given flags. @flag: Flag to set, can by any number of bits in guint32. @obj: GstSrc to set flag in. - - - - - - @@ -1440,6 +1428,12 @@ This macro sets the given flags. @a: + + + + + + @@ -1461,16 +1455,16 @@ This macro sets the given flags. + +GstSink + + A flag indicating that MMX instructions are supported. - -GstSink - - @@ -1608,13 +1602,6 @@ Indicates a srcpad for the padfactory. @obj: - - -Specify how many bytes to read at a time. - - - - @@ -1784,13 +1771,6 @@ or a video card. - - - - - -@Returns: - @@ -1798,6 +1778,13 @@ or a video card. @obj: + + + + + +@Returns: + @@ -1818,6 +1805,12 @@ Query whether this object has multiple input pads. @obj: Element to query for multiple input pads. + + + + + + @@ -1826,12 +1819,6 @@ Query whether this object has multiple input pads. @format: @args...: - - - - - - @@ -2249,6 +2236,13 @@ this in the factory definition. @audiosink: + + + + + +@obj: + This macro unsets the given state on the element. @@ -2257,13 +2251,6 @@ This macro unsets the given state on the element. @obj: Element to unset state of. @flag: State to unset, can be any number of bits in guint32. - - - - - -@obj: - @@ -2336,13 +2323,6 @@ The number of bytes per read. @obj: - - - - - -@Returns: - @@ -2353,6 +2333,13 @@ The number of bytes per read. @format: @args...: + + + + + +@Returns: + @@ -2457,14 +2444,9 @@ This macro sets the given state on the element. @obj: - - + +Information about video buffers. - - -@src: -@offset: -@size: @@ -2473,9 +2455,14 @@ This macro sets the given state on the element. @Returns: - -Information about video buffers. + + + + +@src: +@offset: +@size: @@ -2579,13 +2566,13 @@ A flag indicating that SSE instructions are supported. @obj: - + - + @@ -2666,6 +2653,12 @@ Information about audio buffers. + + + + + + @@ -2674,12 +2667,6 @@ Information about audio buffers. @factory: @Returns: - - - - - - Specify the location of the file to read. @@ -2743,13 +2730,6 @@ the offset. - - - - - -@obj: - @@ -2758,6 +2738,13 @@ the offset. @name: @Returns: + + + + + +@obj: + Get the current number of bytes read. @@ -2806,13 +2793,6 @@ plugin @klass: - - - - - -@obj: - @@ -2820,6 +2800,13 @@ plugin @klass: + + + + + +@obj: + Indicates this pad is active diff --git a/gst/gstpad.c b/gst/gstpad.c index 54c9a8e6e9..48bd1e376c 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -917,10 +917,10 @@ gst_pad_get_peer (GstPad *pad) } /** - * gst_pad_get_buffer_pool: + * gst_pad_get_bufferpool: * @pad: the pad to get the bufferpool from * - * Gst the bufferpool of the peer pad of the given + * Get the bufferpool of the peer pad of the given * pad * * Returns: The GstBufferPool or NULL. @@ -1456,11 +1456,12 @@ gst_padtemplate_init (GstPadTemplate *templ) } /** - * gst_padtemplate_create: + * gst_padtemplate_new: * @name_template: the name template * @direction: the direction for the template * @presence: the presence of the pad * @caps: a list of capabilities for the template + * @...: more capabilities * * Creates a new padtemplate from the given arguments. *