diff options
Diffstat (limited to 'docs')
56 files changed, 1748 insertions, 1530 deletions
diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 661735357..f81b57e7b 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -94,15 +94,6 @@ GST_DEBUG_ENABLE_CATEGORIES </SECTION> <SECTION> -<FILE>gstextratypes</FILE> -<TITLE>GstExtraTypes</TITLE> -GST_TYPE_FILENAME -<SUBSECTION Standard> -gst_extra_get_filename_type -GST_DISABLE_LOADSAVE_REGISTRY -</SECTION> - -<SECTION> <FILE>gstscheduler</FILE> <TITLE>GstScheduler</TITLE> GST_SCHEDULER_PARENT @@ -202,7 +193,7 @@ gst_bin_details <SECTION> <FILE>gstparse</FILE> <TITLE>GstParse</TITLE> -GstParseErrors +GstParseError gst_parse_launch gst_parse_launchv </SECTION> @@ -360,22 +351,25 @@ gst_element_get_managing_bin gst_element_add_pad gst_element_remove_pad gst_element_get_pad +gst_element_get_static_pad +gst_element_get_request_pad gst_element_get_pad_list gst_element_get_padtemplate_list gst_element_get_padtemplate_by_name gst_element_add_ghost_pad gst_element_remove_ghost_pad -gst_element_request_compatible_pad -gst_element_request_pad_by_name gst_element_get_compatible_pad +gst_element_get_compatible_static_pad +gst_element_get_compatible_request_pad gst_element_get_compatible_pad_filtered gst_element_connect +gst_element_connect_many gst_element_connect_filtered -gst_element_connect_elements -gst_element_connect_elements_filtered -gst_element_connect_elements_many +gst_element_connect_pads +gst_element_connect_pads_filtered gst_element_disconnect -gst_element_disconnect_elements +gst_element_disconnect_many +gst_element_disconnect_pads gst_element_set_state gst_element_get_state gst_element_wait_state_change @@ -500,22 +494,6 @@ GST_IS_CLOCK_CLASS </SECTION> <SECTION> -<FILE>gstsystemclock</FILE> -<TITLE>GstSystemClock</TITLE> -GstSystemClock -gst_system_clock_obtain -<SUBSECTION Standard> -gst_system_clock_get_type -GstSystemClockClass -GST_TYPE_SYSTEM_CLOCK -GST_SYSTEM_CLOCK -GST_SYSTEM_CLOCK_CLASS -GST_IS_SYSTEM_CLOCK -GST_IS_SYSTEM_CLOCK_CLASS -</SECTION> - - -<SECTION> <FILE>gstlog</FILE> <SUBSECTION Standard> gst_info @@ -1096,211 +1074,3 @@ gst_static_autoplug_render_get_type GST_STATIC_AUTOPLUG_RENDER_CLASS GST_IS_STATIC_AUTOPLUG_RENDER_CLASS </SECTION> - -<SECTION> -<FILE>gstaggregator</FILE> -<TITLE>GstAggregator</TITLE> -GstAggregatorSchedType -<SUBSECTION Standard> -gst_aggregator_details -GstAggregator -gst_aggregator_factory_init -GST_AGGREGATOR -GST_IS_AGGREGATOR -GST_TYPE_AGGREGATOR -gst_aggregator_get_type -GST_AGGREGATOR_CLASS -GST_IS_AGGREGATOR_CLASS -</SECTION> - -<SECTION> -<FILE>gstfilesrc</FILE> -<TITLE>GstFileSrc</TITLE> -<SUBSECTION Standard> -GstFileSrcFlags -GstFileSrc -GstFileSrcClass -gst_filesrc_get_type -GST_TYPE_FILESRC -GST_FILESRC -GST_FILESRC_CLASS -GST_IS_FILESRC -GST_IS_FILESRC_CLASS -</SECTION> - -<SECTION> -<FILE>gstfakesink</FILE> -<TITLE>GstFakeSink</TITLE> -<SUBSECTION Standard> -GstFakeSink -GstFakeSinkClass -gst_fakesink_get_type -GST_TYPE_FAKESINK -GST_FAKESINK -GST_FAKESINK_CLASS -GST_IS_FAKESINK -GST_IS_FAKESINK_CLASS -gst_fakesink_factory_init -</SECTION> - -<SECTION> -<FILE>gstfakesrc</FILE> -<TITLE>GstFakeSrc</TITLE> -<SUBSECTION Standard> -GstFakeSrc -GstFakeSrcOutputType -gst_fakesrc_get_type -GstFakeSrcClass -GST_TYPE_FAKESRC -GST_FAKESRC -GST_FAKESRC_CLASS -GST_IS_FAKESRC -GST_IS_FAKESRC_CLASS -GstFakeSrcDataType -GstFakeSrcFillType -GstFakeSrcSizeType -gst_fakesrc_factory_init -</SECTION> - -<SECTION> -<FILE>gstfdsink</FILE> -<TITLE>GstFdSink</TITLE> -<SUBSECTION Standard> -GstFdSink -GstFdSinkClass -gst_fdsink_get_type -GST_TYPE_FDSINK -GST_FDSINK -GST_FDSINK_CLASS -GST_IS_FDSINK -GST_IS_FDSINK_CLASS -</SECTION> - -<SECTION> -<FILE>gstfdsrc</FILE> -<TITLE>GstFdSrc</TITLE> -<SUBSECTION Standard> -GstFdSrc -GstFdSrcClass -gst_fdsrc_get_type -GST_TYPE_FDSRC -GST_FDSRC -GST_FDSRC_CLASS -GST_IS_FDSRC -GST_IS_FDSRC_CLASS -</SECTION> - -<SECTION> -<FILE>gstidentity</FILE> -<TITLE>GstIdentity</TITLE> -<SUBSECTION Standard> -GstIdentity -GstIdentityClass -gst_identity_get_type -GST_TYPE_IDENTITY -GST_IDENTITY -GST_IDENTITY_CLASS -GST_IS_IDENTITY -GST_IS_IDENTITY_CLASS -</SECTION> - -<SECTION> -<FILE>gstqueue</FILE> -<TITLE>GstQueue</TITLE> -<SUBSECTION Standard> -GstQueue -GstQueueClass -gst_queue_get_type -GST_TYPE_QUEUE -GST_QUEUE -GST_QUEUE_CLASS -GST_IS_QUEUE -GST_IS_QUEUE_CLASS -</SECTION> - -<SECTION> -<FILE>gstpipefilter</FILE> -<TITLE>GstPipefilter</TITLE> -<SUBSECTION Standard> -GST_TYPE_PIPEFILTER -GST_PIPEFILTER -GST_PIPEFILTER_CLASS -GST_IS_PIPEFILTER -GST_IS_PIPEFILTER_CLASS -GstPipeFilterFlags -GstPipefilter -GstPipefilterClass -gst_pipefilter_get_type -</SECTION> - -<SECTION> -<FILE>gststatistics</FILE> -<TITLE>GstStatistics</TITLE> -<SUBSECTION Standard> -GstStatistics -GstStatisticsClass -stats -GST_STATISTICS -GST_IS_STATISTICS -GST_TYPE_STATISTICS -gst_statistics_get_type -GST_STATISTICS_CLASS -GST_IS_STATISTICS_CLASS -</SECTION> - - -<SECTION> -<FILE>gsttypefind</FILE> -<TITLE>GstTypeFind</TITLE> -<SUBSECTION Standard> -GstTypeFind -GstTypeFindClass -gst_typefind_get_type -GST_TYPE_TYPEFIND -GST_TYPEFIND -GST_TYPEFIND_CLASS -GST_IS_TYPEFIND -GST_IS_TYPEFIND_CLASS -</SECTION> - -<SECTION> -<FILE>gstdisksink</FILE> -<TITLE>GstDiskSink</TITLE> -<SUBSECTION Standard> -GstDiskSink -GstDiskSinkFlags -GST_DISKSINK -GST_IS_DISKSINK -GST_TYPE_DISKSINK -gst_disksink_get_type -GST_DISKSINK_CLASS -GST_IS_DISKSINK_CLASS -</SECTION> - -<SECTION> -<FILE>gstmultidisksrc</FILE> -<TITLE>GstMultiDiskSrc</TITLE> -GstMultiDiskSrcFlags -<SUBSECTION Standard> -GstMultiDiskSrc -GST_MULTIDISKSRC -GST_IS_MULTIDISKSRC -GST_TYPE_MULTIDISKSRC -gst_multidisksrc_get_type -GST_MULTIDISKSRC_CLASS -GST_IS_MULTIDISKSRC_CLASS -</SECTION> - -<SECTION> -<FILE>gstmd5sink</FILE> -<TITLE>GstMD5Sink</TITLE> -<SUBSECTION Standard> -GST_MD5SINK -GST_IS_MD5SINK -GST_TYPE_MD5SINK -gst_md5sink_get_type -GST_MD5SINK_CLASS -GST_IS_MD5SINK_CLASS -gst_md5sink_factory_init -</SECTION> - diff --git a/docs/gst/gstreamer.types.in b/docs/gst/gstreamer.types.in index 52709f2b8..5890f3327 100644 --- a/docs/gst/gstreamer.types.in +++ b/docs/gst/gstreamer.types.in @@ -10,7 +10,6 @@ gst_pad_get_type gst_padtemplate_get_type gst_ghost_pad_get_type gst_thread_get_type -gst_tee_get_type gst_plugin_feature_get_type gst_autoplug_get_type gst_autoplugfactory_get_type @@ -18,25 +17,5 @@ gst_typefactory_get_type gst_elementfactory_get_type gst_schedulerfactory_get_type gst_scheduler_get_type -gst_system_clock_get_type gst_timecache_get_type gst_xml_get_type - -gst_aggregator_get_type -gst_fakesrc_get_type -gst_fakesink_get_type - -gst_filesrc_get_type -gst_fdsrc_get_type - -gst_fdsink_get_type -gst_disksink_get_type - -gst_pipefilter_get_type -gst_identity_get_type -gst_queue_get_type - -gst_statistics_get_type -gst_md5sink_get_type -gst_typefind_get_type - diff --git a/docs/gst/tmpl/gstaggregator.sgml b/docs/gst/tmpl/gstaggregator.sgml index afcfb6f16..46ca5a927 100644 --- a/docs/gst/tmpl/gstaggregator.sgml +++ b/docs/gst/tmpl/gstaggregator.sgml @@ -25,23 +25,3 @@ methods to request buffers from its pads. @AGGREGATOR_LOOP_SELECT: @AGGREGATOR_CHAIN: -<!-- ##### ARG GstAggregator:num-pads ##### --> -<para> - -</para> - -<!-- ##### ARG GstAggregator:silent ##### --> -<para> - -</para> - -<!-- ##### ARG GstAggregator:sched ##### --> -<para> - -</para> - -<!-- ##### ARG GstAggregator:last-message ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gstbin.sgml b/docs/gst/tmpl/gstbin.sgml index f4ba3dc10..6ac0bbffe 100644 --- a/docs/gst/tmpl/gstbin.sgml +++ b/docs/gst/tmpl/gstbin.sgml @@ -54,7 +54,6 @@ Flags for a bin. @GST_BIN_SELF_SCHEDULABLE: @GST_BIN_FLAG_PREFER_COTHREADS: @GST_BIN_FLAG_FIXED_CLOCK: -@GST_BIN_SELF_ITERATING: @GST_BIN_FLAG_LAST: <!-- ##### STRUCT GstBin ##### --> diff --git a/docs/gst/tmpl/gstdisksink.sgml b/docs/gst/tmpl/gstdisksink.sgml index efa98148b..419b53577 100644 --- a/docs/gst/tmpl/gstdisksink.sgml +++ b/docs/gst/tmpl/gstdisksink.sgml @@ -14,20 +14,3 @@ The disksink write to a file. The filename can be given as an argument. #GstFdSink </para> -<!-- ##### SIGNAL GstDiskSink::handoff ##### --> -<para> -Is emited after the buffer has been written to the disk. -</para> - -@gstdisksink: the object which received the signal. - -<!-- ##### ARG GstDiskSink:location ##### --> -<para> -The filename to write to. -</para> - -<!-- ##### ARG GstDiskSink:maxfilesize ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gstelement.sgml b/docs/gst/tmpl/gstelement.sgml index 9d9f381c1..c24dd75a7 100644 --- a/docs/gst/tmpl/gstelement.sgml +++ b/docs/gst/tmpl/gstelement.sgml @@ -376,6 +376,26 @@ instead. @Returns: GList of pads +<!-- ##### FUNCTION gst_element_get_static_pad ##### --> +<para> + +</para> + +@element: +@name: +@Returns: + + +<!-- ##### FUNCTION gst_element_get_request_pad ##### --> +<para> + +</para> + +@element: +@name: +@Returns: + + <!-- ##### FUNCTION gst_element_get_pad_list ##### --> <para> @@ -424,33 +444,33 @@ instead. @pad: -<!-- ##### FUNCTION gst_element_request_compatible_pad ##### --> +<!-- ##### FUNCTION gst_element_get_compatible_pad ##### --> <para> </para> @element: -@templ: +@pad: @Returns: -<!-- ##### FUNCTION gst_element_request_pad_by_name ##### --> +<!-- ##### FUNCTION gst_element_get_compatible_static_pad ##### --> <para> </para> @element: -@name: +@templ: @Returns: -<!-- ##### FUNCTION gst_element_get_compatible_pad ##### --> +<!-- ##### FUNCTION gst_element_get_compatible_request_pad ##### --> <para> </para> @element: -@pad: +@templ: @Returns: @@ -471,9 +491,21 @@ instead. </para> @src: -@srcpadname: @dest: +@Returns: +<!-- # Unused Parameters # --> +@srcpadname: @destpadname: + + +<!-- ##### FUNCTION gst_element_connect_many ##### --> +<para> + +</para> + +@element_1: +@element_2: +@Varargs: @Returns: @@ -483,63 +515,70 @@ instead. </para> @src: -@srcpadname: @dest: -@destpadname: @filtercaps: @Returns: +<!-- # Unused Parameters # --> +@srcpadname: +@destpadname: -<!-- ##### FUNCTION gst_element_connect_elements ##### --> +<!-- ##### FUNCTION gst_element_connect_pads ##### --> <para> </para> @src: +@srcpadname: @dest: +@destpadname: @Returns: -<!-- ##### FUNCTION gst_element_connect_elements_filtered ##### --> +<!-- ##### FUNCTION gst_element_connect_pads_filtered ##### --> <para> </para> @src: +@srcpadname: @dest: +@destpadname: @filtercaps: @Returns: -<!-- ##### FUNCTION gst_element_connect_elements_many ##### --> +<!-- ##### FUNCTION gst_element_disconnect ##### --> <para> </para> -@element_1: -@element_2: -@Varargs: -@Returns: +@src: +@dest: +<!-- # Unused Parameters # --> +@srcpadname: +@destpadname: -<!-- ##### FUNCTION gst_element_disconnect ##### --> +<!-- ##### FUNCTION gst_element_disconnect_many ##### --> <para> </para> -@src: -@srcpadname: -@dest: -@destpadname: +@element_1: +@element_2: +@Varargs: -<!-- ##### FUNCTION gst_element_disconnect_elements ##### --> +<!-- ##### FUNCTION gst_element_disconnect_pads ##### --> <para> </para> @src: +@srcpadname: @dest: +@destpadname: <!-- ##### FUNCTION gst_element_set_state ##### --> diff --git a/docs/gst/tmpl/gstfakesink.sgml b/docs/gst/tmpl/gstfakesink.sgml index a8b33e89b..361a67d1a 100644 --- a/docs/gst/tmpl/gstfakesink.sgml +++ b/docs/gst/tmpl/gstfakesink.sgml @@ -16,36 +16,3 @@ with the buffer. (fakesink) </para> -<!-- ##### SIGNAL GstFakeSink::handoff ##### --> -<para> -This signal is emmitted when a buffer is handled. -</para> - -@gstfakesink: the object which received the signal. -@arg1: The buffer that is received. - -<!-- ##### ARG GstFakeSink:num-sinks ##### --> -<para> -The number of sink pads. -</para> - -<!-- ##### ARG GstFakeSink:silent ##### --> -<para> -Indicates the plugin should not emit messages. -</para> - -<!-- ##### ARG GstFakeSink:dump ##### --> -<para> -Dump the contents of the buffer -</para> - -<!-- ##### ARG GstFakeSink:sync ##### --> -<para> -Sync on the clock -</para> - -<!-- ##### ARG GstFakeSink:last-message ##### --> -<para> -The last message this plugin emmited. -</para> - diff --git a/docs/gst/tmpl/gstfakesrc.sgml b/docs/gst/tmpl/gstfakesrc.sgml index 58611a1aa..dfc2d5710 100644 --- a/docs/gst/tmpl/gstfakesrc.sgml +++ b/docs/gst/tmpl/gstfakesrc.sgml @@ -14,86 +14,3 @@ The <classname>GstFakeSrc</classname> generates empty buffers. (fakesrc) </para> -<!-- ##### SIGNAL GstFakeSrc::handoff ##### --> -<para> - -</para> - -@gstfakesrc: the object which received the signal. -@arg1: - -<!-- ##### ARG GstFakeSrc:num-sources ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:loop-based ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:output ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:data ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:sizetype ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:sizemin ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:sizemax ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:filltype ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:pattern ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:num-buffers ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:eos ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:silent ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:dump ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:parentsize ##### --> -<para> - -</para> - -<!-- ##### ARG GstFakeSrc:last-message ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gstfdsink.sgml b/docs/gst/tmpl/gstfdsink.sgml index a9f732764..ec3e297b2 100644 --- a/docs/gst/tmpl/gstfdsink.sgml +++ b/docs/gst/tmpl/gstfdsink.sgml @@ -14,8 +14,3 @@ Write data to a file descriptor. </para> -<!-- ##### ARG GstFdSink:fd ##### --> -<para> -The filedescriptor to write to. -</para> - diff --git a/docs/gst/tmpl/gstfdsrc.sgml b/docs/gst/tmpl/gstfdsrc.sgml index 882a45198..dd2c183b7 100644 --- a/docs/gst/tmpl/gstfdsrc.sgml +++ b/docs/gst/tmpl/gstfdsrc.sgml @@ -14,18 +14,3 @@ Read buffers from a file descriptor. </para> -<!-- ##### ARG GstFdSrc:location ##### --> -<para> -The filedescriptor to read from. Pass the argument as a char* (???) -</para> - -<!-- ##### ARG GstFdSrc:bytesperread ##### --> -<para> -The number of bytes per read. -</para> - -<!-- ##### ARG GstFdSrc:offset ##### --> -<para> -Get the current offset in the file. -</para> - diff --git a/docs/gst/tmpl/gstfilesrc.sgml b/docs/gst/tmpl/gstfilesrc.sgml index e86a3463f..67715c209 100644 --- a/docs/gst/tmpl/gstfilesrc.sgml +++ b/docs/gst/tmpl/gstfilesrc.sgml @@ -15,38 +15,3 @@ and subbuffers. </para> -<!-- ##### ARG GstFileSrc:offset ##### --> -<para> -The offset in the file that is currently being read. -</para> - -<!-- ##### ARG GstFileSrc:location ##### --> -<para> -The filename -</para> - -<!-- ##### ARG GstFileSrc:filesize ##### --> -<para> -The filesize. -</para> - -<!-- ##### ARG GstFileSrc:fd ##### --> -<para> -The file descriptor. -</para> - -<!-- ##### ARG GstFileSrc:blocksize ##### --> -<para> -The size of the buffers to pass to the peer element. -</para> - -<!-- ##### ARG GstFileSrc:mmapsize ##### --> -<para> -The size of the mmapped area. -</para> - -<!-- ##### ARG GstFileSrc:touch ##### --> -<para> -Indicates the mmapped area should be touched to bring it into memory. -</para> - diff --git a/docs/gst/tmpl/gstidentity.sgml b/docs/gst/tmpl/gstidentity.sgml index a4ef012ec..e5a1a65bd 100644 --- a/docs/gst/tmpl/gstidentity.sgml +++ b/docs/gst/tmpl/gstidentity.sgml @@ -14,51 +14,3 @@ Pass data without modification. </para> -<!-- ##### SIGNAL GstIdentity::handoff ##### --> -<para> - -</para> - -@gstidentity: the object which received the signal. -@arg1: - -<!-- ##### ARG GstIdentity:loop-based ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:sleep-time ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:duplicate ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:error-after ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:drop-probability ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:silent ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:last-message ##### --> -<para> - -</para> - -<!-- ##### ARG GstIdentity:dump ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gstparse.sgml b/docs/gst/tmpl/gstparse.sgml index b97b55c8e..5346cc252 100644 --- a/docs/gst/tmpl/gstparse.sgml +++ b/docs/gst/tmpl/gstparse.sgml @@ -44,15 +44,14 @@ can be made with <option>{}</option>. </para> -<!-- ##### ENUM GstParseErrors ##### --> +<!-- ##### ENUM GstParseError ##### --> <para> </para> @GST_PARSE_ERROR_SYNTAX: -@GST_PARSE_ERROR_CREATING_ELEMENT: -@GST_PARSE_ERROR_NOSUCH_ELEMENT: -@GST_PARSE_ERROR_INTERNAL: +@GST_PARSE_ERROR_NO_SUCH_ELEMENT: +@GST_PARSE_ERROR_NO_SUCH_PROPERTY: @GST_PARSE_ERROR_CONNECT: <!-- ##### FUNCTION gst_parse_launch ##### --> @@ -61,6 +60,7 @@ can be made with <option>{}</option>. </para> @pipeline_description: +@error: @Returns: <!-- # Unused Parameters # --> @cmdline: @@ -73,6 +73,7 @@ can be made with <option>{}</option>. </para> @argv: +@error: @Returns: diff --git a/docs/gst/tmpl/gstpipefilter.sgml b/docs/gst/tmpl/gstpipefilter.sgml index 55f1469e7..968c3132a 100644 --- a/docs/gst/tmpl/gstpipefilter.sgml +++ b/docs/gst/tmpl/gstpipefilter.sgml @@ -15,8 +15,3 @@ buffers from its output. </para> -<!-- ##### ARG GstPipefilter:command ##### --> -<para> -Sets the command to be executed. -</para> - diff --git a/docs/gst/tmpl/gstqueue.sgml b/docs/gst/tmpl/gstqueue.sgml index a8e74dd24..af326b0b0 100644 --- a/docs/gst/tmpl/gstqueue.sgml +++ b/docs/gst/tmpl/gstqueue.sgml @@ -25,24 +25,3 @@ The queue blocks by default. </para> -<!-- ##### ARG GstQueue:leaky ##### --> -<para> - -</para> - -<!-- ##### ARG GstQueue:level ##### --> -<para> -Get the number of buffers in the queue. -</para> - -<!-- ##### ARG GstQueue:max-level ##### --> -<para> -Specify the maximum number of buffers in the queue before the queue -blocks. -</para> - -<!-- ##### ARG GstQueue:may-deadlock ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gstreamer-unused.sgml b/docs/gst/tmpl/gstreamer-unused.sgml index 74cbfd14a..0d7a09b73 100644 --- a/docs/gst/tmpl/gstreamer-unused.sgml +++ b/docs/gst/tmpl/gstreamer-unused.sgml @@ -58,6 +58,27 @@ audioraw GObject +<!-- ##### SECTION ./tmpl/gstaggregator.sgml:Long_Description ##### --> +<para> +The aggregator is mainly used for testing purposes. It has several +methods to request buffers from its pads. +</para> + + +<!-- ##### SECTION ./tmpl/gstaggregator.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstaggregator.sgml:Short_Description ##### --> +Combine buffers. + + +<!-- ##### SECTION ./tmpl/gstaggregator.sgml:Title ##### --> +GstAggregator + + <!-- ##### SECTION ./tmpl/gstasyncdisksrc.sgml:Long_Description ##### --> <para> Reads data from a file. You can seek to a specific location by setting @@ -157,6 +178,26 @@ Generic connection between elements. GstConnection +<!-- ##### SECTION ./tmpl/gstdisksink.sgml:Long_Description ##### --> +<para> +The disksink write to a file. The filename can be given as an argument. +</para> + + +<!-- ##### SECTION ./tmpl/gstdisksink.sgml:See_Also ##### --> +<para> +#GstFdSink +</para> + + +<!-- ##### SECTION ./tmpl/gstdisksink.sgml:Short_Description ##### --> +Write to a file + + +<!-- ##### SECTION ./tmpl/gstdisksink.sgml:Title ##### --> +GstDiskSink + + <!-- ##### SECTION ./tmpl/gstdisksrc.sgml:Long_Description ##### --> <para> Asynchonously read buffers from a file. @@ -198,6 +239,129 @@ GstDiskSrc GstEsdSink +<!-- ##### SECTION ./tmpl/gstextratypes.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstextratypes.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstextratypes.sgml:Short_Description ##### --> + + + +<!-- ##### SECTION ./tmpl/gstextratypes.sgml:Title ##### --> +GstExtraTypes + + +<!-- ##### SECTION ./tmpl/gstfakesink.sgml:Long_Description ##### --> +<para> +Take a buffer and gst_buffer_unref() it. This element does nothing +with the buffer. (fakesink) + +</para> + + +<!-- ##### SECTION ./tmpl/gstfakesink.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstfakesink.sgml:Short_Description ##### --> +Sources a buffer without doing anything with it. (fakesink) + + +<!-- ##### SECTION ./tmpl/gstfakesink.sgml:Title ##### --> +GstFakeSink + + +<!-- ##### SECTION ./tmpl/gstfakesrc.sgml:Long_Description ##### --> +<para> +The <classname>GstFakeSrc</classname> generates empty buffers. (fakesrc) +</para> + + +<!-- ##### SECTION ./tmpl/gstfakesrc.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstfakesrc.sgml:Short_Description ##### --> +Generate empty buffers. (fakesrc) + + +<!-- ##### SECTION ./tmpl/gstfakesrc.sgml:Title ##### --> +GstFakeSrc + + +<!-- ##### SECTION ./tmpl/gstfdsink.sgml:Long_Description ##### --> +<para> +Write data to a file descriptor. +</para> + + +<!-- ##### SECTION ./tmpl/gstfdsink.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstfdsink.sgml:Short_Description ##### --> +Write data to a file descriptor. (fdsink) + + +<!-- ##### SECTION ./tmpl/gstfdsink.sgml:Title ##### --> +GstFdSink + + +<!-- ##### SECTION ./tmpl/gstfdsrc.sgml:Long_Description ##### --> +<para> +Read buffers from a file descriptor. +</para> + + +<!-- ##### SECTION ./tmpl/gstfdsrc.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstfdsrc.sgml:Short_Description ##### --> +Read buffers from a file descriptor. (fdsrc) + + +<!-- ##### SECTION ./tmpl/gstfdsrc.sgml:Title ##### --> +GstFdSrc + + +<!-- ##### SECTION ./tmpl/gstfilesrc.sgml:Long_Description ##### --> +<para> +FileSrc is used to read buffers from a file. It efficiently uses mmap +and subbuffers. +</para> + + +<!-- ##### SECTION ./tmpl/gstfilesrc.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstfilesrc.sgml:Short_Description ##### --> +Read data from a file + + +<!-- ##### SECTION ./tmpl/gstfilesrc.sgml:Title ##### --> +GstFileSrc + + <!-- ##### SECTION ./tmpl/gstfilter.sgml:Long_Description ##### --> <para> Filters take data in and spit data out. They are the main Element in a filter graph. @@ -261,6 +425,46 @@ Reads data from a URL. (httpsrc) GstHttpSrc +<!-- ##### SECTION ./tmpl/gstidentity.sgml:Long_Description ##### --> +<para> +Pass data without modification. +</para> + + +<!-- ##### SECTION ./tmpl/gstidentity.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstidentity.sgml:Short_Description ##### --> +Pass data without modification. (identity) + + +<!-- ##### SECTION ./tmpl/gstidentity.sgml:Title ##### --> +GstIdentity + + +<!-- ##### SECTION ./tmpl/gstmd5sink.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstmd5sink.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstmd5sink.sgml:Short_Description ##### --> + + + +<!-- ##### SECTION ./tmpl/gstmd5sink.sgml:Title ##### --> +GstMD5Sink + + <!-- ##### SECTION ./tmpl/gstmeta.sgml:Long_Description ##### --> <para> The point of the metadata is to provide some context for each buffer. In @@ -374,6 +578,78 @@ Provide context for buffers GstMeta +<!-- ##### SECTION ./tmpl/gstmultidisksrc.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstmultidisksrc.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstmultidisksrc.sgml:Short_Description ##### --> + + + +<!-- ##### SECTION ./tmpl/gstmultidisksrc.sgml:Title ##### --> +GstMultiDiskSrc + + +<!-- ##### SECTION ./tmpl/gstpipefilter.sgml:Long_Description ##### --> +<para> +A GstPipefilter pipes data to an external program and creates +buffers from its output. +</para> + + +<!-- ##### SECTION ./tmpl/gstpipefilter.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstpipefilter.sgml:Short_Description ##### --> +A wrapper around every stdin/stdout capable program + + +<!-- ##### SECTION ./tmpl/gstpipefilter.sgml:Title ##### --> +GstPipefilter + + +<!-- ##### SECTION ./tmpl/gstqueue.sgml:Long_Description ##### --> +<para> +Simple data queue. Data is queued till max_level buffers any subsequent buffers +sent to this filter will block until free space becomes available in the buffer. +The queue is typically used in conjunction with a thread. +</para> +<para> +You can query how many buffers are queued with the level argument. +</para> +<para> +The default queue length is set to 10. +</para> +<para> +The queue blocks by default. +</para> + + +<!-- ##### SECTION ./tmpl/gstqueue.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstqueue.sgml:Short_Description ##### --> +Simple asynchronous data queue. + + +<!-- ##### SECTION ./tmpl/gstqueue.sgml:Title ##### --> +GstQueue + + <!-- ##### SECTION ./tmpl/gstsinesrc.sgml:Long_Description ##### --> <para> Create a sine wave of a given frequency and volume. @@ -438,6 +714,68 @@ The start point of a filter graph GstSrc +<!-- ##### SECTION ./tmpl/gststatistics.sgml:Long_Description ##### --> +<para> +The plugin doesn't alter the data but provides statistics about +the data stream, such as buffers/bytes/events etc. +</para> + + +<!-- ##### SECTION ./tmpl/gststatistics.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gststatistics.sgml:Short_Description ##### --> +Provide statistics about data that passes this plugin + + +<!-- ##### SECTION ./tmpl/gststatistics.sgml:Title ##### --> +GstStatistics + + +<!-- ##### SECTION ./tmpl/gstsystemclock.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstsystemclock.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gstsystemclock.sgml:Short_Description ##### --> + + + +<!-- ##### SECTION ./tmpl/gstsystemclock.sgml:Title ##### --> +GstSystemClock + + +<!-- ##### SECTION ./tmpl/gsttypefind.sgml:Long_Description ##### --> +<para> +This element can be added to the pipeline and will notify the listener of +the detected mime type of the stream. It is used in autoplugging. +</para> + + +<!-- ##### SECTION ./tmpl/gsttypefind.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/gsttypefind.sgml:Short_Description ##### --> +Detect the mime type of a media stream + + +<!-- ##### SECTION ./tmpl/gsttypefind.sgml:Title ##### --> +GstTypeFind + + <!-- ##### SECTION ./tmpl/plugin.sgml:Long_Description ##### --> <para> @@ -1889,6 +2227,12 @@ This macro unsets the given state on the element. </para> +<!-- ##### MACRO GST_TYPE_FILENAME ##### --> +<para> +A type that can be used to indicate a filename. +</para> + + <!-- ##### MACRO GST_TYPE_FILTER ##### --> <para> @@ -2378,6 +2722,40 @@ This macro unsets the given state on the element. @v: +<!-- ##### ARG GstAggregator:last-message ##### --> +<para> + +</para> + + +<!-- ##### ARG GstAggregator:num-pads ##### --> +<para> + +</para> + + +<!-- ##### ARG GstAggregator:sched ##### --> +<para> + +</para> + + +<!-- ##### ARG GstAggregator:silent ##### --> +<para> + +</para> + + +<!-- ##### ENUM GstAggregatorSchedType ##### --> +<para> + +</para> + +@AGGREGATOR_LOOP: +@AGGREGATOR_LOOP_PEEK: +@AGGREGATOR_LOOP_SELECT: +@AGGREGATOR_CHAIN: + <!-- ##### STRUCT GstAsyncDiskSrc ##### --> <para> @@ -2586,12 +2964,31 @@ the pool. </para> +<!-- ##### SIGNAL GstDiskSink::handoff ##### --> +<para> +Is emited after the buffer has been written to the disk. +</para> + +@gstdisksink: the object which received the signal. + <!-- ##### ARG GstDiskSink:closed ##### --> <para> </para> +<!-- ##### ARG GstDiskSink:location ##### --> +<para> +The filename to write to. +</para> + + +<!-- ##### ARG GstDiskSink:maxfilesize ##### --> +<para> + +</para> + + <!-- ##### ENUM GstDiskSinkFlags ##### --> <para> @@ -2716,12 +3113,50 @@ GstElementDetails struct for the element. </para> +<!-- ##### SIGNAL GstFakeSink::handoff ##### --> +<para> +This signal is emmitted when a buffer is handled. +</para> + +@gstfakesink: the object which received the signal. +@arg1: The buffer that is received. + +<!-- ##### ARG GstFakeSink:dump ##### --> +<para> +Dump the contents of the buffer +</para> + + +<!-- ##### ARG GstFakeSink:last-message ##### --> +<para> +The last message this plugin emmited. +</para> + + +<!-- ##### ARG GstFakeSink:num-sinks ##### --> +<para> +The number of sink pads. +</para> + + <!-- ##### ARG GstFakeSink:num-sources ##### --> <para> </para> +<!-- ##### ARG GstFakeSink:silent ##### --> +<para> +Indicates the plugin should not emit messages. +</para> + + +<!-- ##### ARG GstFakeSink:sync ##### --> +<para> +Sync on the clock +</para> + + <!-- ##### STRUCT GstFakeSinkClass ##### --> <para> @@ -2734,12 +3169,110 @@ GstElementDetails struct for the element. </para> +<!-- ##### SIGNAL GstFakeSrc::handoff ##### --> +<para> + +</para> + +@gstfakesrc: the object which received the signal. +@arg1: + +<!-- ##### ARG GstFakeSrc:data ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:dump ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:eos ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:filltype ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:last-message ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:loop-based ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:num-buffers ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:num-sources ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:output ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:parentsize ##### --> +<para> + +</para> + + <!-- ##### ARG GstFakeSrc:patern ##### --> <para> </para> +<!-- ##### ARG GstFakeSrc:pattern ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:silent ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:sizemax ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:sizemin ##### --> +<para> + +</para> + + +<!-- ##### ARG GstFakeSrc:sizetype ##### --> +<para> + +</para> + + <!-- ##### STRUCT GstFakeSrcClass ##### --> <para> @@ -2752,6 +3285,12 @@ GstElementDetails struct for the element. </para> +<!-- ##### ARG GstFdSink:fd ##### --> +<para> +The filedescriptor to write to. +</para> + + <!-- ##### STRUCT GstFdSinkClass ##### --> <para> @@ -2764,12 +3303,72 @@ GstElementDetails struct for the element. </para> +<!-- ##### ARG GstFdSrc:bytesperread ##### --> +<para> +The number of bytes per read. +</para> + + +<!-- ##### ARG GstFdSrc:location ##### --> +<para> +The filedescriptor to read from. Pass the argument as a char* (???) +</para> + + +<!-- ##### ARG GstFdSrc:offset ##### --> +<para> +Get the current offset in the file. +</para> + + <!-- ##### STRUCT GstFdSrcClass ##### --> <para> </para> +<!-- ##### ARG GstFileSrc:blocksize ##### --> +<para> +The size of the buffers to pass to the peer element. +</para> + + +<!-- ##### ARG GstFileSrc:fd ##### --> +<para> +The file descriptor. +</para> + + +<!-- ##### ARG GstFileSrc:filesize ##### --> +<para> +The filesize. +</para> + + +<!-- ##### ARG GstFileSrc:location ##### --> +<para> +The filename +</para> + + +<!-- ##### ARG GstFileSrc:mmapsize ##### --> +<para> +The size of the mmapped area. +</para> + + +<!-- ##### ARG GstFileSrc:offset ##### --> +<para> +The offset in the file that is currently being read. +</para> + + +<!-- ##### ARG GstFileSrc:touch ##### --> +<para> +Indicates the mmapped area should be touched to bring it into memory. +</para> + + <!-- ##### STRUCT GstFilter ##### --> <para> @@ -2813,12 +3412,68 @@ Specify the location of the file. The location must be a fully qualified URL. </para> +<!-- ##### SIGNAL GstIdentity::handoff ##### --> +<para> + +</para> + +@gstidentity: the object which received the signal. +@arg1: + <!-- ##### ARG GstIdentity:control ##### --> <para> </para> +<!-- ##### ARG GstIdentity:drop-probability ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:dump ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:duplicate ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:error-after ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:last-message ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:loop-based ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:silent ##### --> +<para> + +</para> + + +<!-- ##### ARG GstIdentity:sleep-time ##### --> +<para> + +</para> + + <!-- ##### STRUCT GstIdentityClass ##### --> <para> @@ -2842,6 +3497,14 @@ Flags indicating properties about the meta data. @GST_META_FREEABLE: the meta data can be freed +<!-- ##### ENUM GstMultiDiskSrcFlags ##### --> +<para> + +</para> + +@GST_MULTIDISKSRC_OPEN: +@GST_MULTIDISKSRC_FLAG_LAST: + <!-- ##### STRUCT GstObjectClass ##### --> <para> @@ -2936,6 +3599,23 @@ The function that will be called when a QoS message is sent. @pad: the pad that sent the QoS message @qos_message: the message +<!-- ##### ENUM GstParseErrors ##### --> +<para> + +</para> + +@GST_PARSE_ERROR_SYNTAX: +@GST_PARSE_ERROR_CREATING_ELEMENT: +@GST_PARSE_ERROR_NOSUCH_ELEMENT: +@GST_PARSE_ERROR_INTERNAL: +@GST_PARSE_ERROR_CONNECT: + +<!-- ##### ARG GstPipefilter:command ##### --> +<para> +Sets the command to be executed. +</para> + + <!-- ##### STRUCT GstPipelineClass ##### --> <para> @@ -2990,6 +3670,31 @@ Specify wether the queue blocks or not. </para> +<!-- ##### ARG GstQueue:leaky ##### --> +<para> + +</para> + + +<!-- ##### ARG GstQueue:level ##### --> +<para> +Get the number of buffers in the queue. +</para> + + +<!-- ##### ARG GstQueue:max-level ##### --> +<para> +Specify the maximum number of buffers in the queue before the queue +blocks. +</para> + + +<!-- ##### ARG GstQueue:may-deadlock ##### --> +<para> + +</para> + + <!-- ##### ARG GstQueue:timeout ##### --> <para> @@ -3117,12 +3822,98 @@ Flags for the GstSrc element @GST_SRC_ASYNC: Indicates that this src is asynchronous @GST_SRC_FLAG_LAST: subclasses can use this to number their flags +<!-- ##### SIGNAL GstStatistics::update ##### --> +<para> + +</para> + +@gststatistics: the object which received the signal. + +<!-- ##### ARG GstStatistics:buffer-update-freq ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:buffers ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:bytes ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:bytes-update-freq ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:event-update-freq ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:events ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:silent ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:update ##### --> +<para> + +</para> + + +<!-- ##### ARG GstStatistics:update-on-eos ##### --> +<para> + +</para> + + +<!-- ##### STRUCT GstSystemClock ##### --> +<para> + +</para> + +@clock: + <!-- ##### STRUCT GstTee ##### --> <para> </para> +<!-- ##### ARG GstTee:last-message ##### --> +<para> + +</para> + + +<!-- ##### ARG GstTee:num-pads ##### --> +<para> + +</para> + + +<!-- ##### ARG GstTee:silent ##### --> +<para> + +</para> + + <!-- ##### STRUCT GstTeeClass ##### --> <para> @@ -3163,6 +3954,20 @@ TRUE if the thread should be created. @data: @message: +<!-- ##### SIGNAL GstTypeFind::have-type ##### --> +<para> +The signal to indicate the mime type was detected. +</para> + +@gsttypefind: the object which received the signal. +@arg1: The mime type that was detected + +<!-- ##### ARG GstTypeFind:caps ##### --> +<para> + +</para> + + <!-- ##### ARG GstTypeFind:type ##### --> <para> Query the element for the current mime type @@ -4460,6 +5265,43 @@ must be defined to activate the tracing functionality. @state: @Returns: +<!-- ##### FUNCTION gst_element_connect_elements ##### --> +<para> + +</para> + +@src: +@dest: +@Returns: + +<!-- ##### FUNCTION gst_element_connect_elements_filtered ##### --> +<para> + +</para> + +@src: +@dest: +@filtercaps: +@Returns: + +<!-- ##### FUNCTION gst_element_connect_elements_many ##### --> +<para> + +</para> + +@element_1: +@element_2: +@Varargs: +@Returns: + +<!-- ##### FUNCTION gst_element_disconnect_elements ##### --> +<para> + +</para> + +@src: +@dest: + <!-- ##### FUNCTION gst_element_get_type ##### --> <para> @@ -4510,6 +5352,15 @@ must be defined to activate the tracing functionality. @Returns: +<!-- ##### FUNCTION gst_element_request_compatible_pad ##### --> +<para> + +</para> + +@element: +@templ: +@Returns: + <!-- ##### FUNCTION gst_element_request_pad ##### --> <para> @@ -4520,6 +5371,15 @@ must be defined to activate the tracing functionality. @Returns: @temp: +<!-- ##### FUNCTION gst_element_request_pad_by_name ##### --> +<para> + +</para> + +@element: +@name: +@Returns: + <!-- ##### FUNCTION gst_element_restore_thyself ##### --> <para> @@ -5509,6 +6369,13 @@ Call the EOS function of the pad @src: +<!-- ##### FUNCTION gst_system_clock_obtain ##### --> +<para> + +</para> + +@Returns: + <!-- ##### FUNCTION gst_tee_chain ##### --> <para> diff --git a/docs/gst/tmpl/gststatistics.sgml b/docs/gst/tmpl/gststatistics.sgml index 0966d3e7f..100aed6af 100644 --- a/docs/gst/tmpl/gststatistics.sgml +++ b/docs/gst/tmpl/gststatistics.sgml @@ -15,55 +15,3 @@ the data stream, such as buffers/bytes/events etc. </para> -<!-- ##### SIGNAL GstStatistics::update ##### --> -<para> - -</para> - -@gststatistics: the object which received the signal. - -<!-- ##### ARG GstStatistics:buffers ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:bytes ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:events ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:buffer-update-freq ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:bytes-update-freq ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:event-update-freq ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:update-on-eos ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:update ##### --> -<para> - -</para> - -<!-- ##### ARG GstStatistics:silent ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gsttee.sgml b/docs/gst/tmpl/gsttee.sgml index 868ee2ba9..ad5d8acd7 100644 --- a/docs/gst/tmpl/gsttee.sgml +++ b/docs/gst/tmpl/gsttee.sgml @@ -14,18 +14,3 @@ A tee can be used to split out the filter graph. </para> -<!-- ##### ARG GstTee:silent ##### --> -<para> - -</para> - -<!-- ##### ARG GstTee:num-pads ##### --> -<para> - -</para> - -<!-- ##### ARG GstTee:last-message ##### --> -<para> - -</para> - diff --git a/docs/gst/tmpl/gsttypefind.sgml b/docs/gst/tmpl/gsttypefind.sgml index ace6c2187..4fb597271 100644 --- a/docs/gst/tmpl/gsttypefind.sgml +++ b/docs/gst/tmpl/gsttypefind.sgml @@ -15,16 +15,3 @@ the detected mime type of the stream. It is used in autoplugging. </para> -<!-- ##### SIGNAL GstTypeFind::have-type ##### --> -<para> -The signal to indicate the mime type was detected. -</para> - -@gsttypefind: the object which received the signal. -@arg1: The mime type that was detected - -<!-- ##### ARG GstTypeFind:caps ##### --> -<para> - -</para> - diff --git a/docs/manual/advanced-autoplugging.xml b/docs/manual/advanced-autoplugging.xml index c5b89e110..eb7d5c70d 100644 --- a/docs/manual/advanced-autoplugging.xml +++ b/docs/manual/advanced-autoplugging.xml @@ -21,28 +21,27 @@ <programlisting> ... /* now it's time to get the parser */ - parse = gst_elementfactory_make ("mp3parse", "parse"); - decoder = gst_elementfactory_make ("mpg123", "decoder"); + decoder = gst_elementfactory_make ("mad", "decoder"); ... </programlisting> <para> While this mechanism is quite effective it also has some big problems: The elements are created based on their name. Indeed, we create an - element mpg123 by explicitly stating the mpg123 elements name. - Our little program therefore always uses the mpg123 decoder element + element mad by explicitly stating the mad element's name. + Our little program therefore always uses the mad decoder element to decode the MP3 audio stream, even if there are 3 other MP3 decoders in the system. We will see how we can use a more general way to create an MP3 decoder element. </para> <para> - We have to introduce the concept of MIME types and capabilities + We have to introduce the concept of MIME types and capabilities added to the source and sink pads. </para> </sect1> <sect1> - <title>more on MIME Types</title> + <title>More on MIME Types</title> <para> GStreamer uses MIME types to indentify the different types of data that can be handled by the elements. They are the high level @@ -124,9 +123,9 @@ a function that can be used to determine if a given buffer is of the given MIME type. </para> - <para> - There is also an association between a MIME type and a file - extension. + <para> + There is also an association between a MIME type and a file extension, but the use of typefind + functions (similar to file(1)) is preferred.. </para> <para> The type information is maintained in a list of @@ -202,86 +201,9 @@ struct _GstType { This function will return 0 if the extension was not known. </para> </sect2> - - <sect2> - <title>id to <classname>GstElementFactory</classname> conversion</title> - <para> - When we have obtained a given type id using one of the above methods, - we can obtain a list of all the elements that operate on this MIME - type or extension. - </para> - <para> - Obtain a list of all the elements that use this id as source with: - </para> - <programlisting> - GList *list; - - list = gst_type_gst_srcs (id); - </programlisting> - - <para> - Obtain a list of all the elements that use this id as sink with: - </para> - <programlisting> - GList *list; - - list = gst_type_gst_sinks (id); - </programlisting> - <para> - When you have a list of elements, you can simply take the first - element of the list to obtain an appropriate element. - </para> - <note> - <para> - As you can see, there might be a multitude of elements that - are able to operate on audio/raw types. some might include: - <itemizedlist> - <listitem> - <para> - an MP3 audio encoder. - </para> - </listitem> - <listitem> - <para> - an audio sink. - </para> - </listitem> - <listitem> - <para> - an audio resampler. - </para> - </listitem> - <listitem> - <para> - a spectrum filter. - </para> - </listitem> - </itemizedlist> - Depending on the application, you might want to use a different - element. This is why GStreamer leaves that decision up to the - application programmer. - </para> - </note> - - </sect2> - - <sect2> - <title>id to id path detection</title> - <para> - You can obtain a <classname>GList</classname> of elements that - will transform the source id into the destination id. - </para> - <programlisting> - GList *list; - - list = gst_type_gst_sink_to_src (sourceid, sinkid); - </programlisting> - <para> - This piece of code will give you the elements needed to construct - a path from sourceid to sinkid. This function is mainly used in - autoplugging the pipeline. - </para> - </sect2> + <para> + For more information, see <xref linkend="cha-autoplug"/>. + </para> </sect1> <sect1> diff --git a/docs/manual/advanced-threads.xml b/docs/manual/advanced-threads.xml index 77680e2cd..f9b00b96b 100644 --- a/docs/manual/advanced-threads.xml +++ b/docs/manual/advanced-threads.xml @@ -1,7 +1,7 @@ <chapter id="cha-threads"> <title>Threads</title> <para> - GStreamer has support for multithreading throught the use of + GStreamer has support for multithreading through the use of the <classname>GstThread</classname> object. This object is in fact a special <classname>GstBin</classname> that will become a thread when started. </para> @@ -13,39 +13,58 @@ <programlisting> GstElement *my_thread; - // create the thread object + /* create the thread object */ my_thread = gst_thread_new ("my_thread"); - g_return_if_fail (audio_thread != NULL); + /* you could have used gst_elementfactory_make ("thread", "my_thread"); */ + g_return_if_fail (my_thread != NULL); - // add some plugins + /* add some plugins */ gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (funky_src)); gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (cool_effect)); - // connect the elements here... + /* connect the elements here... */ ... - // start playing + /* start playing */ gst_element_set_state (GST_ELEMENT (my_thread), GST_STATE_PLAYING); </programlisting> - <para> - The above program will create a thread with two elements in it. As soon - as it is set to the PLAYING state, the thread will start to iterate. + <para> + The above program will create a thread with two elements in it. As soon as it is set to the + PLAYING state, the thread will start to iterate itself. You never need to manually iterate a + thread. </para> - <note> - <para> - A thread should normally contain a source element. Most often, the thread - is fed with data from a queue. - </para> - </note> - + <sect2> + <title>Constraints placed on the pipeline by the GstThread</title> + <para> + Within the pipeline, everything is the same as in any other bin. The difference lies at the + thread boundary, at the connection between the thread and the outside world (containing bin). + Since GStreamer is fundamentally buffer-oriented rather than byte-oriented, the natural + solution to this problem is an element that can "buffer" the buffers between the threads, in a + thread-safe fashion. This element is the queue, described more fully in <xref + linkend="cha-queues"/>. It doesn't matter if the queue is placed in the containing bin or in + the thread itself, but it needs to be present on one side of the other to enable inter-thread + communication. + </para> + </sect2> + <sect2> + <title>When would you want to use a thread?</title> + <para> + If you are writing a GUI application, making the top-level bin a thread will make your GUI + more responsive. If it were a pipeline instead, it would have to be iterated by your + application's event loop, which increases the latency between events (say, keyboard presses) + and responses from the GUI. In addition, any slight hang in the GUI would delay iteration of + the pipeline, which (for example) could cause pops in the output of the sound card, if it is + an audio pipeline. + </para> + </sect2> <para> - A thread will be visualised as below + A thread can be visualised as below </para> <figure float="1" id="sec-threads-img"> - <title>a thread</title> + <title>A thread</title> <mediaobject> <imageobject> <imagedata fileref="images/thread.&magic;" format="&magic;" /> diff --git a/docs/manual/appendix-checklist.xml b/docs/manual/appendix-checklist.xml index 46980e091..fd7a891f3 100644 --- a/docs/manual/appendix-checklist.xml +++ b/docs/manual/appendix-checklist.xml @@ -34,6 +34,12 @@ </listitem> <listitem> <para> + <option>--gst-mask-help</option> + Print out the meaning of gst-mask-* values. + </para> + </listitem> + <listitem> + <para> <option>--gst-plugin-spew</option> Enable printout of errors while loading GST plugins. </para> @@ -47,16 +53,15 @@ <listitem> <para> <option>--help</option> Print the a short desciption of the - options and an overview of the current debugging/info masks - set. + options </para> </listitem> </itemizedlist> </para> <para> - The follwing table gives an overview of the mask values and - their meaning. (enabled) means that the corresponding flag - has been set. + The following table gives an overview of the mask values and their meaning. (enabled) means + that the corresponding flag is set by default. This table is available to any GStreamer + application by the --gst-mask-help option. </para> <programlisting> Mask (to be OR'ed) info/debug FLAGS diff --git a/docs/manual/appendix-debugging.xml b/docs/manual/appendix-debugging.xml index 46980e091..fd7a891f3 100644 --- a/docs/manual/appendix-debugging.xml +++ b/docs/manual/appendix-debugging.xml @@ -34,6 +34,12 @@ </listitem> <listitem> <para> + <option>--gst-mask-help</option> + Print out the meaning of gst-mask-* values. + </para> + </listitem> + <listitem> + <para> <option>--gst-plugin-spew</option> Enable printout of errors while loading GST plugins. </para> @@ -47,16 +53,15 @@ <listitem> <para> <option>--help</option> Print the a short desciption of the - options and an overview of the current debugging/info masks - set. + options </para> </listitem> </itemizedlist> </para> <para> - The follwing table gives an overview of the mask values and - their meaning. (enabled) means that the corresponding flag - has been set. + The following table gives an overview of the mask values and their meaning. (enabled) means + that the corresponding flag is set by default. This table is available to any GStreamer + application by the --gst-mask-help option. </para> <programlisting> Mask (to be OR'ed) info/debug FLAGS diff --git a/docs/manual/appendix-programs.xml b/docs/manual/appendix-programs.xml index 28a1c1791..7f57334bb 100644 --- a/docs/manual/appendix-programs.xml +++ b/docs/manual/appendix-programs.xml @@ -4,40 +4,37 @@ </para> <sect1> - <title><command>gstreamer-register</command></title> + <title><command>gst-register</command></title> <para> - <command>gstreamer-register</command> is used to rebuild the database of plugins. + <command>gst-register</command> is used to rebuild the database of plugins. It is used after a new plugin has been added to the system. The plugin database - can be found in <filename>/etc/gstreamer/reg.xml</filename>. + can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>. </para> </sect1> <sect1> - <title><command>gstreamer-launch</command></title> + <title><command>gst-launch</command></title> <para> This is a tool that will construct pipelines based on a command-line - syntax. + syntax. FIXME: need a more extensive grammar reference </para> <para> A simple commandline looks like: <screen> -gstreamer-launch filesrc location=hello.mp3 ! mp3parse ! mpg123 ! audiosink +gst-launch filesrc location=hello.mp3 ! mad ! osssink </screen> A more complex pipeline looks like: <screen> -gstreamer-launch filesrc redpill.vob audio_00! (ac3parse ! ac3dec ! audiosink) \ -video_00! (mpeg2dec ! videosink) +gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \ + demux.audio_00! { ac3parse ! a52dec ! osssink } \ + demux.video_00! { mpeg2dec ! xvideosink } </screen> </para> <para> - Note that the parser isn't capable of more complex pipelines yet, including - the VOB player above. The minor tweaks will be made post 0.2.1. - </para> - <para> You can also use the the parser in you own code. <application>GStreamer</application> provides a function gst_parse_launch () that you can use to construt a pipeline. The following programs lets you create an mp3 pipeline using the gst_parse_launch () @@ -51,17 +48,21 @@ main (int argc, char *argv[]) { GstElement *pipeline; GstElement *filesrc; + GError *error = NULL; gst_init (&argc, &argv); if (argc != 2) { - g_print ("usage: %s <filename>\n", argv[0]); + g_print ("usage: %s <filename>\n", argv[0]); return -1; } - pipeline = gst_pipeline_new ("my_pipeline"); - - gst_parse_launch ("filesrc[my_filesrc] ! mp3parse ! mpg123 ! osssink", GST_BIN (pipeline)); + pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &error); + if (!pipeline) { + g_print ("Parse error: %s\n", error->message); + exit (1); + } + filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc"); g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL); @@ -81,20 +82,20 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title><command>gstreamer-inspect</command></title> + <title><command>gst-inspect</command></title> <para> This is a tool to query a plugin or an element about its properties. </para> <para> - To query the information about the element mpg123, you would specify: + To query the information about the element mad, you would specify: </para> <screen> -gstreamer-inspect mpg123 +gst-inspect mad </screen> <para> - Below is the output of a query for the audiosink element: + Below is the output of a query for the osssink element: </para> <screen> @@ -102,56 +103,72 @@ Factory Details: Long name: Audio Sink (OSS) Class: Sink/Audio Description: Output to a sound card via OSS - Version: 0.1.0 - Author(s): Erik Walthinsen <omega@cse.ogi.edu> + Version: 0.3.3.1 + Author(s): Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be> Copyright: (C) 1999 +GObject + +----GstObject + +----GstElement + +----GstOssSink + Pad Templates: SINK template: 'sink' - Exists: Always + Availability: Always Capabilities: - 'audiosink_sink': + 'osssink_sink': MIME type: 'audio/raw': - format: Integer: 16 + format: String: int + endianness: Integer: 1234 + width: List: + Integer: 8 + Integer: 16 depth: List: Integer: 8 Integer: 16 - rate: Integer range: 8000 - 48000 channels: Integer range: 1 - 2 + law: Integer: 0 + signed: List: + Boolean: FALSE + Boolean: TRUE + rate: Integer range: 1000 - 48000 + Element Flags: GST_ELEMENT_THREADSUGGESTED - no flags set Element Implementation: No loopfunc(), must be chain-based or not configured yet - Has change_state() function + Has change_state() function: gst_osssink_change_state + Has custom save_thyself() function: gst_element_save_thyself + Has custom restore_thyself() function: gst_element_restore_thyself + +Clocking Interaction: + element requires a clock + element provides a clock: GstOssClock Pads: SINK: 'sink' Implementation: - Has chainfunc(): 0x4001cde8 - Has default eosfunc() gst_pad_eos_func() + Has chainfunc(): 0x40056fc0 Pad Template: 'sink' - Capabilities: - 'audiosink_sink': - MIME type: 'audio/raw': - format: Integer: 16 - depth: List: - Integer: 8 - Integer: 16 - rate: Integer range: 8000 - 48000 - channels: Integer range: 1 - 2 Element Arguments: - GstAudioSink::mute: Boolean - GstAudioSink::format: Enum (default 16) - (8): 8 Bits - (16): 16 Bits - GstAudioSink::channels: Enum (default 2) + name : String (Default "element") + device : String (Default "/dev/dsp") + mute : Boolean (Default false) + format : Integer (Default 16) + channels : Enum "GstAudiosinkChannels" (default 1) + (0): Silence (1): Mono (2): Stereo - GstAudioSink::frequency: Integer + frequency : Integer (Default 11025) + fragment : Integer (Default 6) + buffer-size : Integer (Default 4096) + +Element Signals: + "handoff" : void user_function (GstOssSink* object, + gpointer user_data); </screen> <para> @@ -159,11 +176,11 @@ Element Arguments: </para> <screen> -gstreamer-inspect gstelements +gst-inspect gstelements </screen> </sect1> <sect1> - <title><command>gstmediaplay</command></title> + <title><command>gst-play</command></title> <para> A sample media player. </para> diff --git a/docs/manual/autoplugging.xml b/docs/manual/autoplugging.xml index 01f9852cc..24b03f217 100644 --- a/docs/manual/autoplugging.xml +++ b/docs/manual/autoplugging.xml @@ -2,8 +2,8 @@ <title>Autoplugging</title> <para> <application>GStreamer</application> provides an API to automatically - construct complex pipelinebased on source and destination capabilities. - This feature is very usefull if you want to convert type X to type Y but + construct complex pipelines based on source and destination capabilities. + This feature is very useful if you want to convert type X to type Y but don't care about the plugins needed to accomplish this task. The autoplugger will consult the plugin repository, select and connect the elements needed for the conversion. @@ -106,7 +106,7 @@ <listitem> <para> Add the autoplugcache element to a bin and connect the sink pad to the src - pad of an element with unkown caps. + pad of an element with unknown caps. </para> </listitem> <listitem> @@ -141,8 +141,52 @@ </orderedlist> </para> <para> - In the next chapter we will create a new version of our helloworld exaple using the + In the next chapter we will create a new version of our helloworld example using the autoplugger, the autoplugcache and the typefind element. </para> </sect1> + <sect1> + <title>Another approach to autoplugging</title> + <para> + The autoplug API is interesting, but often impractical. It is static; it cannot deal with + dynamic pipelines (insert ref here). What one often wants is just an element to stick into a + pipeline that will DWIM (ref). Enter the spider. + </para> + <sect2> + <title>The spider element</title> + <para> + The spider element is a generalized autoplugging element. At this point (April 2002), it's + the best we've got; it can be inserted anywhere within a pipeline to perform caps + conversion, if possible. Consider the following gst-launch line: + <programlisting> + $ gst-launch filesrc location=my.mp3 ! spider ! osssink + </programlisting> + The spider will detect the type of the stream, autoplug it to the osssink's caps, and play + the pipeline. It's neat. + </para> + </sect2> + <sect2> + <title>Spider features</title> + <para> + <orderedlist> + <listitem> + <para> + Automatically typefinds the incoming stream. + </para> + </listitem> + <listitem> + <para> + Has request pads on the src side. This means that it can autoplug one source stream + into many sink streams. For example, a MPEG1 system stream can have audio as well as + video; that pipeline would be represented in gst-launch syntax as + <programlisting> + $ gst-launch filesrc location=my.mpeg1 ! spider ! { queue ! osssink } spider.src_%d! + { queue ! xvideosink } + </programlisting> + </para> + </listitem> + </orderedlist> + </para> + </sect2> + </sect1> </chapter> diff --git a/docs/manual/basics-bins.xml b/docs/manual/basics-bins.xml index a60e07190..47f05c466 100644 --- a/docs/manual/basics-bins.xml +++ b/docs/manual/basics-bins.xml @@ -7,7 +7,7 @@ <para> Bins allow you to combine connected elements into one logical element. You do not deal with the individual elements anymore but with just one element, the bin. - We will see that this is extremely powerfull when you are going to construct + We will see that this is extremely powerful when you are going to construct complex pipelines since it allows you to break up the pipeline in smaller chunks. </para> <para> @@ -37,9 +37,10 @@ </listitem> <listitem> <para> - A thread (<classname>GstThread</classname>). All the elements in the thread bin will - run in a separate thread. You will have to use this bin if you carfully have to - synchronize audio and video for example. You will learn more about threads in.. <!-- FIXME --> + A thread (<classname>GstThread</classname>). The plan for the + <classname>GstThread</classname> will be run in a separate thread. You will have to use + this bin if you have to carefully synchronize audio and video, for example. You will learn + more about threads in <xref linkend="cha-threads"/>. </para> </listitem> </itemizedlist> @@ -48,26 +49,22 @@ <sect1 id="sec-bin-create"> <title>Creating a bin</title> <para> - You create a bin with a specified name 'mybin' with: + Bins register themselves in the GStreamer registry, so they can be created in the normal way: </para> <programlisting> - GstElement *bin; - - gst_bin_new ("mybin"); - ... - </programlisting> - <para> - A thread can be created with: - </para> - <programlisting> - GstElement *thread; + GstElement *bin, *thread, *pipeline; - gst_thread_new ("mythread"); - ... + /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal + GstBin doesn't affect plan generation */ + bin = gst_elementfactory_make ("bin", "mybin"); + + /* create a new thread, and give it a unique name */ + thread = gst_elementfactory_make ("thread", NULL); + + /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs, + gst_<bintype>_new (). these are equivalent to the gst_elementfactory_make () syntax. */ + pipeline = gst_pipeline_new ("pipeline_name"); </programlisting> - <para> - Pipelines are created with gst_pipeline_new ("name"); - </para> </sect1> <sect1 id="sec-bin-adding"> @@ -86,8 +83,9 @@ ... </programlisting> <para> - Bins and threads can be added to other bins too. This allows you to create nested - bins. + Bins and threads can be added to other bins too. This allows you to create nested bins. Note + that it doesn't make very much sense to add a <classname>GstPipeline</classname> to anything, + as it's a toplevel bin that needs to be explicitly iterated. </para> <para> To get an element from the bin you can use: @@ -100,7 +98,7 @@ </programlisting> <para> You can see that the name of the element becomes very handy for retrieving the - element from an bin by using the elements name. gst_bin_get_by_name () will + element from an bin by using the element's name. gst_bin_get_by_name () will recursively search nested bins. </para> <para> @@ -114,7 +112,7 @@ while (elements) { GstElement *element = GST_ELEMENT (elements->data); - g_print ("element in bin: %s\n", gst_element_get_name (element)); + g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element))); elements = g_list_next (elements); } @@ -129,6 +127,18 @@ gst_bin_remove (GST_BIN (bin), element); ... </programlisting> + <para> + To add many elements to a bin at the same time, try the gst_bin_add_many () API. Remember to + pass NULL as the last argument. + </para> + <programlisting> + GstElement *filesrc, *decoder, *audiosink; + GstBin *bin; + + /* instantiate the elements and the bins... */ + + gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL); + </programlisting> </sect1> <sect1 id="sec-bin-custom"> @@ -137,43 +147,56 @@ The application programmer can create custom bins packed with elements to perform a specific task. This allow you to write an MPEG audio decoder with just the follwing lines of code: + </para> + <programlisting> - <programlisting> - - // create the mp3player element + /* create the mp3player element */ GstElement *mp3player = gst_elementfactory_make ("mp3player", "mp3player"); - // set the source mp3 audio file + /* set the source mp3 audio file */ g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL); - // start playback + /* start playback */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING); ... - // pause playback + /* pause playback */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED); ... - // stop + /* stop */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL); - </programlisting> + </programlisting> + <para> + Note that the above code assumes that the mp3player bin derives itself from a + <classname>GstThread</classname>, which begins to play as soon as its state is set to PLAYING. + Other bin types may need explicit iteration. For more information, see <xref + linkend="cha-threads"/>. Custom bins can be created with a plugin or an XML description. You will find more - information about creating custom bin in the Filter-Writers-Guide. + information about creating custom bin in the Plugin Writers Guide (FIXME ref). </para> </sect1> <sect1 id="sec-bin-ghostpads"> - <title>Ghostpads</title> + <title>Ghost pads</title> <para> - You can see from figure ... how a bin has no pads of its own. This is where Ghostpads - come into play. + You can see from figure <xref linkend="sec-bin-noghost-img"/> how a bin has no pads of its own. + This is where "ghost pads" come into play. </para> + <figure float="1" id="sec-bin-noghost-img"> + <title>Visualisation of a <classname>GstBin</classname> element without ghost pads</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/bin-element-noghost.&magic;" format="&magic;" /> + </imageobject> + </mediaobject> + </figure> <para> - A ghostpad is a pad from some element in the bin that has been promoted to the bin. + A ghost pad is a pad from some element in the bin that has been promoted to the bin. This way, the bin also has a pad. The bin becomes just another element with a pad and you can then use the bin just like any other element. This is a very important feature for creating custom bins. </para> <figure float="1" id="sec-bin-ghost-img"> - <title>Visualisation of a <classname>GstBin</classname> element with a ghostpad</title> + <title>Visualisation of a <classname>GstBin</classname> element with a ghost pad</title> <mediaobject> <imageobject> <imagedata fileref="images/bin-element-ghost.&magic;" format="&magic;" /> @@ -181,18 +204,18 @@ </mediaobject> </figure> <para> - Above is a representation of a ghostpad. the sinkpad of element one is now also a pad + Above is a representation of a ghost pad. The sink pad of element one is now also a pad of the bin. </para> <para> - Ghostpads can actually be added to all <classname>GstElement</classname>s and not just - <classname>GstBin</classname>s. Use the following code example to add a ghostpad to a bin: + Ghost pads can actually be added to all <classname>GstElement</classname>s and not just + <classname>GstBin</classname>s. Use the following code example to add a ghost pad to a bin: </para> <programlisting> GstElement *bin; GstElement *element; - element = gst_elementfactory_create ("mpg123", "decoder"); + element = gst_elementfactory_create ("mad", "decoder"); bin = gst_bin_new ("mybin"); gst_bin_add (GST_BIN (bin), element); @@ -210,7 +233,7 @@ filesrc = gst_elementfactory_create ("filesrc", "disk_reader"); - gst_element_connect (filesrc, "src", bin, "sink"); + gst_element_connect_pads (filesrc, "src", bin, "sink"); ... </programlisting> </sect1> diff --git a/docs/manual/basics-data.xml b/docs/manual/basics-data.xml index 78c1bca98..043a8fa2b 100644 --- a/docs/manual/basics-data.xml +++ b/docs/manual/basics-data.xml @@ -51,7 +51,7 @@ <para> A more complex case is when the filter modifies the data in place. It does so and simply passes on the buffer to the next element. This is just - as easy to deal with. An element that works in place has to be carefull when + as easy to deal with. An element that works in place has to be careful when the buffer is used in more than one element; a copy on write has to made in this situation. </para> diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml index 5d76c1fa5..3b361dee8 100644 --- a/docs/manual/basics-elements.xml +++ b/docs/manual/basics-elements.xml @@ -12,21 +12,16 @@ different components you are going to use are derived from this GstElement. This means that a lot of functions you are going to use operate on this object. </para> - <para> - You will see that those elements have pads. These are the elements - connections with the 'outside' world. Depending on the number and direction of - the pads, we can see three types of elements: source, filter and sink element. - </para> - <para> - These three types are all the same GstElement object, they just differ in how - the pads are. + <para> Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of + different aspects. One of these aspects is the presence of "pads", or connection points. This + terminology arises from soldering; pads are where wires can be attached. </para> <sect2 id="sec-elements-src"> - <title>GStreamer source elements</title> + <title>Source elements</title> <para> - This element will generate data that will be used by the pipeline. It is - typically a file or an audio source. + Source elements generate data for use by a pipeline, for example reading from disk or from a + sound card. </para> <para> Below you see how we will visualize the element. @@ -48,19 +43,17 @@ </sect2> <sect2 id="sec-elements-filter"> - <title>GStreamer filter elements</title> - <para> - Filter elements both have an input and an output pad. They operate on data - they receive in the sink pad and send the result to the src pad. - </para> + <title>Filters and codecs</title> <para> - Examples of a filter element might include: an MPEG decoder, volume filter,... - </para> + Filter elements both have input and output pads. They operate on data they receive in their + sink pads and produce data on their src pads. For example, MPEG decoders and volume filters + would fall into this category. + </para> <para> - Filters may also contain any number of input pads and output pads. For example, - a video mixer might have to input pads (the images of the two different video - streams) and one output pad. - </para> + Elements are not constrained as to the number of pads they migh have; for example, a video + mixer might have two input pads (the images of the two different video streams) and one + output pad. + </para> <figure float="1" id="sec-element-filterimg"> <title>Visualisation of a filter element</title> <mediaobject> @@ -71,7 +64,7 @@ </figure> <para> The above figure shows the visualisation of a filter element. This element has - one sink pad (input) and one src (output) pad. Sink pads are drawn on the left + one sink (input) pad and one src (output) pad. Sink pads are drawn on the left of the element. </para> <figure float="1" id="sec-element-multifilterimg"> @@ -84,21 +77,21 @@ </mediaobject> </figure> <para> - The above figure shows the visualisation of a filter element with more than one - output pad. An example of such a filter is the AVI splitter. This element will - parse the input data and extracts the audio and video data. Most of these filters - dynamically send out a signal when a new pad is created so that the application - programmer can connect an arbitrary element to the newly created pad. - </para> + The above figure shows the visualisation of a filter element with more than one output pad. + An example of such a filter is the AVI splitter (demuxer). This element will parse the input + data and extracts the audio and video data. Most of these filters dynamically send out a + signal when a new pad is created so that the application programmer can connect an arbitrary + element to the newly created pad. + </para> </sect2> <sect2 id="sec-elements-sink"> - <title>GStreamer sink elements</title> - <para> - This element accepts data but will not generate any new data. A sink element - is typically a file on disk, a soundcard, a display,... It is presented as - below: - </para> + <title>Sink elements</title> + <para> + Sink elements are terminal points in a media pipeline. They accept data but do not produce + anything. Disk writing, soundcard playback, and video output woul all be implemented by sink + elements. + </para> <figure float="1" id="sec-element-sinkimg"> <title>Visualisation of a sink element</title> <mediaobject> @@ -117,12 +110,12 @@ </para> <para> The following code example is used to get a factory that can be used to create the - mpg123 element, an mp3 decoder. + 'mad' element, an mp3 decoder. </para> <programlisting> GstElementFactory *factory; - factory = gst_elementfactory_find ("mpg123"); + factory = gst_elementfactory_find ("mad"); </programlisting> <para> Once you have the handle to the elementfactory, you can create a real element with @@ -133,23 +126,23 @@ element = gst_elementfactory_create (factory, "decoder"); </programlisting> - <para> - gst_elementfactory_create () will use the elementfactory to create an element with the - given name. The name of the element is something you can use later on to lookup the - element in a bin, for example. - </para> - <para> - A simple shortcut exists for creating an element from a factory. The following example - creates an element, named "decoder" from the elementfactory named "mpg123". This - convenient function is most widly used to create an element. - </para> + <para> + gst_elementfactory_create () will use the elementfactory to create an element with the given + name. The name of the element is something you can use later on to lookup the element in a + bin, for example. You can pass NULL as the name argument to get a unique, default name. + </para> + <para> + A simple shortcut exists for creating an element from a factory. The following example creates + an element, named "decoder" from the elementfactory named "mad". This convenient function is + most widely used to create an element. + </para> <programlisting> GstElement *element; - element = gst_elementfactory_make ("mpg123", "decoder"); + element = gst_elementfactory_make ("mad", "decoder"); </programlisting> <para> - An element can be destroyed with: + An element can be destroyed with: FIXME talk about refcounting </para> <programlisting> GstElement *element; diff --git a/docs/manual/basics-helloworld.xml b/docs/manual/basics-helloworld.xml index 8fe65276c..6072152e1 100644 --- a/docs/manual/basics-helloworld.xml +++ b/docs/manual/basics-helloworld.xml @@ -8,13 +8,12 @@ <sect1> <title>Hello world</title> - <para> - We will create a simple first application. In fact it will be a complete - MP3 player, using standard <application>GStreamer</application> components. The player will read from - a file that is given as the first argument of the program. + <para> + We will create a simple first application, a complete MP3 player, using standard + <application>GStreamer</application> components. The player will read from a file that is + given as the first argument of the program. </para> - <programlisting> #include <gst/gst.h> @@ -45,15 +44,10 @@ main (int argc, char *argv[]) audiosink = gst_elementfactory_make ("osssink", "play_audio"); /* add objects to the main pipeline */ - gst_bin_add (GST_BIN (pipeline), filesrc); - gst_bin_add (GST_BIN (pipeline), decoder); - gst_bin_add (GST_BIN (pipeline), audiosink); + gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); /* connect src to sink */ - gst_pad_connect (gst_element_get_pad (filesrc, "src"), - gst_element_get_pad (decoder, "sink")); - gst_pad_connect (gst_element_get_pad (decoder, "src"), - gst_element_get_pad (audiosink, "sink")); + gst_element_connect_many (filesrc, decoder, audiosink, NULL); /* start playing */ gst_element_set_state (pipeline, GST_STATE_PLAYING); @@ -64,10 +58,8 @@ main (int argc, char *argv[]) gst_element_set_state (pipeline, GST_STATE_NULL); /* we don't need a reference to these objects anymore */ - gst_object_unref (GST_OBJECT (audiosink)); - gst_object_unref (GST_OBJECT (decoder)); - gst_object_unref (GST_OBJECT (filesrc)); gst_object_unref (GST_OBJECT (pipeline)); + /* unreffing the pipeline unrefs the contained elements as well */ exit (0); } @@ -98,8 +90,8 @@ main (int argc, char *argv[]) </programlisting> <para> - We are going to create 3 elements and one pipeline. Since all objects are - in fact elements, we can define them as: + We are going to create 3 elements and one pipeline. Since all elements share the same base + type, <classname>GstElement</classname>, we can define them as: </para> <programlisting> ... @@ -142,7 +134,7 @@ main (int argc, char *argv[]) is installed on the system where this application is executed. </para> <programlisting> - /* now it's time to get the parser */ + /* now it's time to get the decoder */ decoder = gst_elementfactory_make ("mad", "decoder"); </programlisting> <para> @@ -167,9 +159,7 @@ main (int argc, char *argv[]) </para> <programlisting> /* add objects to the main pipeline */ - gst_bin_add (GST_BIN (pipeline), filesrc); - gst_bin_add (GST_BIN (pipeline), decoder); - gst_bin_add (GST_BIN (pipeline), audiosink); + gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); </programlisting> <para> @@ -177,10 +167,7 @@ main (int argc, char *argv[]) </para> <programlisting> /* connect src to sink */ - gst_pad_connect (gst_element_get_pad (filesrc, "src"), - gst_element_get_pad (decoder, "sink")); - gst_pad_connect (gst_element_get_pad (decoder, "src"), - gst_element_get_pad (audiosink, "sink")); + gst_element_connect_many (filesrc, decoder, audiosink, NULL); </programlisting> <para> @@ -229,16 +216,13 @@ main (int argc, char *argv[]) /* stop the pipeline */ gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (GST_OBJECT (audiosink)); - gst_object_unref (GST_OBJECT (decoder)); - gst_object_unref (GST_OBJECT (filesrc)); gst_object_unref (GST_OBJECT (pipeline)); exit (0); </programlisting> <note> <para> - don't forget to set the state of the pipeline to NULL. This will free + Don't forget to set the state of the pipeline to NULL. This will free all of the resources held by the elements. </para> </note> @@ -246,7 +230,7 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title>compiling helloworld.c</title> + <title>Compiling helloworld.c</title> <para> To compile the helloworld example, use: </para> @@ -268,10 +252,10 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title>conclusion</title> + <title>Conclusion</title> <para> This concludes our first example. As you see, setting up a pipeline - is very lowlevel but powerfull. You will later in this manual how + is very lowlevel but powerful. You will later in this manual how you can create a custom MP3 element with a more high level API. </para> <para> @@ -284,7 +268,7 @@ main (int argc, char *argv[]) We could use a disksink to write the raw samples to a file, for example. It should also be clear that inserting filters, like a stereo effect, into the pipeline is not that hard to do. The most important thing is - that you can reuse allready existing elements. + that you can reuse already existing elements. </para> </sect1> </chapter> diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index 36bd02184..953367a6d 100644 --- a/docs/manual/basics-pads.xml +++ b/docs/manual/basics-pads.xml @@ -1,7 +1,7 @@ <chapter id="cha-pads"> <title>GstPad</title> <para> - As we have seen in the previous chapter (GstElement), the pads are the elements + As we have seen in the previous chapter (GstElement), the pads are the element's connections with the outside world. </para> <para> @@ -44,7 +44,7 @@ <title>Useful pad functions</title> <para> You can get the name of a pad with gst_pad_get_name () and set its name with - get_pad_set_name(); + get_pad_set_name(). </para> <para> gst_pad_get_direction (GstPad *pad) can be used to query if the pad is a sink @@ -53,8 +53,8 @@ </para> <para> You can get the parent of the pad, this is the element that this pad belongs to, - with get_pad_set_parent(GstPad *pad). This function will return a pointer to a - GstObject. + with get_pad_get_parent(GstPad *pad). This function will return a pointer to a + GstElement. </para> </sect2> <sect2 id="sec-pads-dynamic"> @@ -63,10 +63,10 @@ Some elements might not have their pads when they are created. This can, for example, happen with an MPEG2 system demuxer. The demuxer will create its pads at runtime when it detects the different elementary streams in the MPEG2 - system stream. + system stream. </para> <para> - Running <application>gstreamer-inspect mpeg2parse</application> will show that + Running <application>gst-inspect mpegdemux</application> will show that the element has only one pad: a sink pad called 'sink'. The other pads are "dormant" as you can see in the padtemplates from the 'Exists: Sometimes' property. Depending on the type of MPEG2 file you play, the pads are created. We @@ -104,7 +104,7 @@ main(int argc, char *argv[]) // create pipeline and do something usefull ... - mpeg2parser = gst_elementfactory_make ("mpeg2parse", "mpeg2parse"); + mpeg2parser = gst_elementfactory_make ("mpegdemux", "mpegdemux"); g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_connect_func, pipeline); ... @@ -141,19 +141,19 @@ main(int argc, char *argv[]) ... element = gst_elementfactory_make ("tee", "element"); - pad = gst_element_request_pad_by_name (element, "src%d"); + pad = gst_element_get_request_pad (element, "src%d"); g_print ("new pad %s\n", gst_pad_get_name (pad)); ... </programlisting> <para> - The gst_element_request_pad_by_name method can be used to get a pad + The gst_element_get_request_pad method can be used to get a pad from the element based on the name_template of the padtemplate. </para> <para> It is also possible to request a pad that is compatible with another padtemplate. This is very usefull if you want to connect an element to a muxer element and you need to request a pad that is compatible. The - gst_element_request_compatible_pad is used to request a compatible pad, as + gst_element_get_compatible_pad is used to request a compatible pad, as is shown in the next example. </para> <programlisting> @@ -162,11 +162,11 @@ main(int argc, char *argv[]) GstPad *pad; ... element = gst_elementfactory_make ("tee", "element"); - mp3parse = gst_elementfactory_make ("mp3parse", "mp3parse"); + mad = gst_elementfactory_make ("mad", "mad"); - templ = gst_element_get_padtemplate_by_name (mp3parse, "sink"); + templ = gst_element_get_padtemplate_by_name (mad, "sink"); - pad = gst_element_request_compatible_pad (element, templ); + pad = gst_element_get_compatible_pad (element, templ); g_print ("new pad %s\n", gst_pad_get_name (pad)); ... </programlisting> @@ -181,7 +181,7 @@ main(int argc, char *argv[]) <para> We will briefly describe what capabilities are, enough for you to get a basic understanding of the concepts. You will find more information on how to create capabilities in the - filter-writer-guide. + Plugin Writer's Guide. </para> <sect2 id="sec-pads-caps"> @@ -207,8 +207,8 @@ struct _GstCaps { }; </programlisting> <para> - Below is a dump of the capabilities of the element mpg123, as shown by - <command>gstreamer-inspect</command>. + Below is a dump of the capabilities of the element mad, as shown by + <command>gst-inspect</command>. You can see two pads: sink and src. Both pads have capability information attached to them. </para> <para> @@ -221,26 +221,25 @@ struct _GstCaps { </para> <programlisting> Pads: - SINK: 'sink' - .... - Capabilities: - 'mpg123_sink': - MIME type: 'audio/mp3': - layer: Integer range: 1 - 3 - bitrate: Integer range: 8 - 320 - framed: Boolean: TRUE + SINK template: 'sink' + Availability: Always + Capabilities: + 'mad_sink': + MIME type: 'audio/mp3': - SRC: 'src' - .... + SRC template: 'src' + Availability: Always Capabilities: - 'mpg123_src': - MIME type: 'audio/raw': - format: Integer: 16 - depth: Integer: 16 - rate: Integer range: 11025 - 48000 - channels: List: - Integer: 1 - Integer: 2 + 'mad_src': + MIME type: 'audio/raw': + format: String: int + endianness: Integer: 1234 + width: Integer: 16 + depth: Integer: 16 + channels: Integer range: 1 - 2 + law: Integer: 0 + signed: Boolean: TRUE + rate: Integer range: 11025 - 48000 </programlisting> </sect2> <sect2 id="sec-pads-props"> @@ -260,7 +259,7 @@ Pads: <listitem> <para> An integer range value. The property denotes a range of possible values. In the case - of the mpg123 element: the src pad has a property rate that can go from 11025 to 48000. + of the mad element: the src pad has a property rate that can go from 11025 to 48000. </para> </listitem> <listitem> @@ -349,7 +348,7 @@ Pads: </para> <para> As we said, a capability has a name, a mime-type and some properties. The signature of the - function to create a new <classname>GstCaps *</classname> structure is like: + function to create a new <classname>GstCaps</classname> structure is like: <programlisting> GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); </programlisting> diff --git a/docs/manual/basics-plugins.xml b/docs/manual/basics-plugins.xml index a89d9cb90..a8fa76abb 100644 --- a/docs/manual/basics-plugins.xml +++ b/docs/manual/basics-plugins.xml @@ -20,6 +20,11 @@ one or more autopluggers </para> </listitem> + <listitem> + <para> + exported symbols for use in other plugins + </para> + </listitem> </itemizedlist> <para> The plugins have one simple method: plugin_init () where all the elementfactories are diff --git a/docs/manual/bins.xml b/docs/manual/bins.xml index a60e07190..47f05c466 100644 --- a/docs/manual/bins.xml +++ b/docs/manual/bins.xml @@ -7,7 +7,7 @@ <para> Bins allow you to combine connected elements into one logical element. You do not deal with the individual elements anymore but with just one element, the bin. - We will see that this is extremely powerfull when you are going to construct + We will see that this is extremely powerful when you are going to construct complex pipelines since it allows you to break up the pipeline in smaller chunks. </para> <para> @@ -37,9 +37,10 @@ </listitem> <listitem> <para> - A thread (<classname>GstThread</classname>). All the elements in the thread bin will - run in a separate thread. You will have to use this bin if you carfully have to - synchronize audio and video for example. You will learn more about threads in.. <!-- FIXME --> + A thread (<classname>GstThread</classname>). The plan for the + <classname>GstThread</classname> will be run in a separate thread. You will have to use + this bin if you have to carefully synchronize audio and video, for example. You will learn + more about threads in <xref linkend="cha-threads"/>. </para> </listitem> </itemizedlist> @@ -48,26 +49,22 @@ <sect1 id="sec-bin-create"> <title>Creating a bin</title> <para> - You create a bin with a specified name 'mybin' with: + Bins register themselves in the GStreamer registry, so they can be created in the normal way: </para> <programlisting> - GstElement *bin; - - gst_bin_new ("mybin"); - ... - </programlisting> - <para> - A thread can be created with: - </para> - <programlisting> - GstElement *thread; + GstElement *bin, *thread, *pipeline; - gst_thread_new ("mythread"); - ... + /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal + GstBin doesn't affect plan generation */ + bin = gst_elementfactory_make ("bin", "mybin"); + + /* create a new thread, and give it a unique name */ + thread = gst_elementfactory_make ("thread", NULL); + + /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs, + gst_<bintype>_new (). these are equivalent to the gst_elementfactory_make () syntax. */ + pipeline = gst_pipeline_new ("pipeline_name"); </programlisting> - <para> - Pipelines are created with gst_pipeline_new ("name"); - </para> </sect1> <sect1 id="sec-bin-adding"> @@ -86,8 +83,9 @@ ... </programlisting> <para> - Bins and threads can be added to other bins too. This allows you to create nested - bins. + Bins and threads can be added to other bins too. This allows you to create nested bins. Note + that it doesn't make very much sense to add a <classname>GstPipeline</classname> to anything, + as it's a toplevel bin that needs to be explicitly iterated. </para> <para> To get an element from the bin you can use: @@ -100,7 +98,7 @@ </programlisting> <para> You can see that the name of the element becomes very handy for retrieving the - element from an bin by using the elements name. gst_bin_get_by_name () will + element from an bin by using the element's name. gst_bin_get_by_name () will recursively search nested bins. </para> <para> @@ -114,7 +112,7 @@ while (elements) { GstElement *element = GST_ELEMENT (elements->data); - g_print ("element in bin: %s\n", gst_element_get_name (element)); + g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element))); elements = g_list_next (elements); } @@ -129,6 +127,18 @@ gst_bin_remove (GST_BIN (bin), element); ... </programlisting> + <para> + To add many elements to a bin at the same time, try the gst_bin_add_many () API. Remember to + pass NULL as the last argument. + </para> + <programlisting> + GstElement *filesrc, *decoder, *audiosink; + GstBin *bin; + + /* instantiate the elements and the bins... */ + + gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL); + </programlisting> </sect1> <sect1 id="sec-bin-custom"> @@ -137,43 +147,56 @@ The application programmer can create custom bins packed with elements to perform a specific task. This allow you to write an MPEG audio decoder with just the follwing lines of code: + </para> + <programlisting> - <programlisting> - - // create the mp3player element + /* create the mp3player element */ GstElement *mp3player = gst_elementfactory_make ("mp3player", "mp3player"); - // set the source mp3 audio file + /* set the source mp3 audio file */ g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL); - // start playback + /* start playback */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING); ... - // pause playback + /* pause playback */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED); ... - // stop + /* stop */ gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL); - </programlisting> + </programlisting> + <para> + Note that the above code assumes that the mp3player bin derives itself from a + <classname>GstThread</classname>, which begins to play as soon as its state is set to PLAYING. + Other bin types may need explicit iteration. For more information, see <xref + linkend="cha-threads"/>. Custom bins can be created with a plugin or an XML description. You will find more - information about creating custom bin in the Filter-Writers-Guide. + information about creating custom bin in the Plugin Writers Guide (FIXME ref). </para> </sect1> <sect1 id="sec-bin-ghostpads"> - <title>Ghostpads</title> + <title>Ghost pads</title> <para> - You can see from figure ... how a bin has no pads of its own. This is where Ghostpads - come into play. + You can see from figure <xref linkend="sec-bin-noghost-img"/> how a bin has no pads of its own. + This is where "ghost pads" come into play. </para> + <figure float="1" id="sec-bin-noghost-img"> + <title>Visualisation of a <classname>GstBin</classname> element without ghost pads</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/bin-element-noghost.&magic;" format="&magic;" /> + </imageobject> + </mediaobject> + </figure> <para> - A ghostpad is a pad from some element in the bin that has been promoted to the bin. + A ghost pad is a pad from some element in the bin that has been promoted to the bin. This way, the bin also has a pad. The bin becomes just another element with a pad and you can then use the bin just like any other element. This is a very important feature for creating custom bins. </para> <figure float="1" id="sec-bin-ghost-img"> - <title>Visualisation of a <classname>GstBin</classname> element with a ghostpad</title> + <title>Visualisation of a <classname>GstBin</classname> element with a ghost pad</title> <mediaobject> <imageobject> <imagedata fileref="images/bin-element-ghost.&magic;" format="&magic;" /> @@ -181,18 +204,18 @@ </mediaobject> </figure> <para> - Above is a representation of a ghostpad. the sinkpad of element one is now also a pad + Above is a representation of a ghost pad. The sink pad of element one is now also a pad of the bin. </para> <para> - Ghostpads can actually be added to all <classname>GstElement</classname>s and not just - <classname>GstBin</classname>s. Use the following code example to add a ghostpad to a bin: + Ghost pads can actually be added to all <classname>GstElement</classname>s and not just + <classname>GstBin</classname>s. Use the following code example to add a ghost pad to a bin: </para> <programlisting> GstElement *bin; GstElement *element; - element = gst_elementfactory_create ("mpg123", "decoder"); + element = gst_elementfactory_create ("mad", "decoder"); bin = gst_bin_new ("mybin"); gst_bin_add (GST_BIN (bin), element); @@ -210,7 +233,7 @@ filesrc = gst_elementfactory_create ("filesrc", "disk_reader"); - gst_element_connect (filesrc, "src", bin, "sink"); + gst_element_connect_pads (filesrc, "src", bin, "sink"); ... </programlisting> </sect1> diff --git a/docs/manual/buffers.xml b/docs/manual/buffers.xml index 78c1bca98..043a8fa2b 100644 --- a/docs/manual/buffers.xml +++ b/docs/manual/buffers.xml @@ -51,7 +51,7 @@ <para> A more complex case is when the filter modifies the data in place. It does so and simply passes on the buffer to the next element. This is just - as easy to deal with. An element that works in place has to be carefull when + as easy to deal with. An element that works in place has to be careful when the buffer is used in more than one element; a copy on write has to made in this situation. </para> diff --git a/docs/manual/components.xml b/docs/manual/components.xml index a4272342f..0c5923f78 100644 --- a/docs/manual/components.xml +++ b/docs/manual/components.xml @@ -1,5 +1,10 @@ <chapter id="cha-components"> <title>Components</title> + + <para> + FIXME: This chapter is way out of date. + </para> + <para> <application>GStreamer</application> includes components that people can include in their programs. diff --git a/docs/manual/connections.xml b/docs/manual/connections.xml index 381315f5a..2504ca794 100644 --- a/docs/manual/connections.xml +++ b/docs/manual/connections.xml @@ -45,16 +45,42 @@ </programlisting> <para> - A convenient shortcut for the above code is done with the gst_element_connect () + A convenient shortcut for the above code is done with the gst_element_connect_pads () function: </para> <programlisting> // connect them - gst_element_connect (element1, "src", element2, "sink"); + gst_element_connect_pads (element1, "src", element2, "sink"); .... // and disconnect them - gst_element_disconnect (element1, "src", element2, "sink"); + gst_element_disconnect_pads (element1, "src", element2, "sink"); + + </programlisting> + <para> + An even more convenient shortcut for single-source, single-sink elements is the + gst_element_connect () function: + </para> + <programlisting> + + // connect them + gst_element_connect (element1, element2); + .... + // and disconnect them + gst_element_disconnect (element1, element2); + + </programlisting> + <para> + If you have more than one element to connection, the gst_element_connect_many () function takes + a NULL-terminated list of elements: + </para> + <programlisting> + + // connect them + gst_element_connect_many (element1, element2, element3, element4, NULL); + .... + // and disconnect them + gst_element_disconnect_many (element1, element2, element3, element4, NULL); </programlisting> <para> @@ -70,7 +96,7 @@ <title>Making filtered connections</title> <para> You can also force a specific media type on the connection by using gst_pad_connect_filtered () - and gst_element_connect_filtered (). + and gst_element_connect_filtered (). FIXME link to caps documentation. </para> </sect1> diff --git a/docs/manual/cothreads.xml b/docs/manual/cothreads.xml index 7fc9c6796..f50f53ad7 100644 --- a/docs/manual/cothreads.xml +++ b/docs/manual/cothreads.xml @@ -1,9 +1,9 @@ <chapter id="cha-cothreads"> <title>Cothreads</title> - <para> - Cothreads are user-space threads that greatly reduce context - switching overhead introduced by regular kernel threads. - Cothreads are also used to handle the more complex elements. + <para> + Cothreads are user-space threads that greatly reduce context switching overhead introduced by + regular kernel threads. Cothreads are also used to handle the more complex elements. They differ + from other user-space threading libraries in that they are scheduled explictly by GStreamer. </para> <para> A cothread is created by a <classname>GstBin</classname> whenever an element is found @@ -72,7 +72,7 @@ chain_function (GstPad *pad, GstBuffer *buffer) <sect1 id="sec-loop-based"> <title>Loop-based elements</title> <para> - As opposed to chain-based elements, Loop-based elements enter an + As opposed to chain-based elements, loop-based elements enter an infinite loop that looks like this: <programlisting> @@ -97,24 +97,24 @@ chain_function (GstPad *pad, GstBuffer *buffer) </para> <para> - When the request for a buffer cannot immedialty satisfied, the control - will be given to the source element of the loop-based element until it - performs a push on its source pad. At that time the control is handed back - to the loop-based element, etc... The the execution trace can get fairly - complex using cothreads when there are multiple input/output pads for the - loop-based element. + When the request for a buffer cannot immediatly satisfied, the control will be given to the + source element of the loop-based element until it performs a push on its source pad. At that + time the control is handed back to the loop-based element, etc... The the execution trace can + get fairly complex using cothreads when there are multiple input/output pads for the + loop-based element. Cothread switches are performed within the call to gst_pad_pull and + gst_pad_push; from the perspective of the loop-based element, it just "appears" that + gst_pad_push (or _pull) might take a long time to return. </para> <para> - Loop based elements are mainly used for the more complex elements that need a - specific amount of data before they can start to produce output. An example - of such an element is the mpeg video decoder. the element will pull a buffer, - performs some decoding on it and optionally requests more buffers to decode, when - a complete video frame has been decoded, a buffer is send out. + Loop based elements are mainly used for the more complex elements that need a specific amount + of data before they can start to produce output. An example of such an element is the mpeg + video decoder. the element will pull a buffer, performs some decoding on it and optionally + requests more buffers to decode, when a complete video frame has been decoded, a buffer is + send out. For example, any plugin using the bytestream library will need to be loop-based. </para> <para> - There is no problem in putting cothreaded elements into a - <classname>GstThread</classname> to create even more complex pipelines with - both user and kernel space threads. + There is no problem in putting cothreaded elements into a <classname>GstThread</classname> to + create even more complex pipelines with both user and kernel space threads. </para> </sect1> diff --git a/docs/manual/debugging.xml b/docs/manual/debugging.xml index 46980e091..fd7a891f3 100644 --- a/docs/manual/debugging.xml +++ b/docs/manual/debugging.xml @@ -34,6 +34,12 @@ </listitem> <listitem> <para> + <option>--gst-mask-help</option> + Print out the meaning of gst-mask-* values. + </para> + </listitem> + <listitem> + <para> <option>--gst-plugin-spew</option> Enable printout of errors while loading GST plugins. </para> @@ -47,16 +53,15 @@ <listitem> <para> <option>--help</option> Print the a short desciption of the - options and an overview of the current debugging/info masks - set. + options </para> </listitem> </itemizedlist> </para> <para> - The follwing table gives an overview of the mask values and - their meaning. (enabled) means that the corresponding flag - has been set. + The following table gives an overview of the mask values and their meaning. (enabled) means + that the corresponding flag is set by default. This table is available to any GStreamer + application by the --gst-mask-help option. </para> <programlisting> Mask (to be OR'ed) info/debug FLAGS diff --git a/docs/manual/dynamic.xml b/docs/manual/dynamic.xml index 56fe4e330..b5b190606 100644 --- a/docs/manual/dynamic.xml +++ b/docs/manual/dynamic.xml @@ -36,10 +36,10 @@ idle_func (gpointer data) int main(int argc, char *argv[]) { - GstElement *pipeline, *src, *parse; + GstElement *pipeline, *src, *demux; + struct poptOption *gst_table; gst_init (&argc, &argv); - gnome_init ("MPEG1 Video player","0.0.1", argc, argv); pipeline = gst_pipeline_new ("pipeline"); g_return_val_if_fail (pipeline != NULL, -1); @@ -48,20 +48,18 @@ main(int argc, char *argv[]) g_return_val_if_fail (src != NULL, -1); g_object_set (G_OBJECT (src), "location", argv[1], NULL); - parse = gst_elementfactory_make ("mpeg1parse", "parse"); - g_return_val_if_fail (parse != NULL, -1); + demux = gst_elementfactory_make ("mpegdemux", "demux"); + g_return_val_if_fail (demux != NULL, -1); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (src)); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (parse)); + gst_bin_add_many (GST_BIN (pipeline), src, demux, NULL); - g_signal_connect (G_OBJECT (parse), "new_pad", + g_signal_connect (G_OBJECT (demux), "new_pad", G_CALLBACK (new_pad_created), pipeline); g_signal_connect (G_OBJECT (src), "eos", G_CALLBACK (eof), NULL); - gst_pad_connect (gst_element_get_pad (src, "src"), - gst_element_get_pad (parse, "sink")); + gst_element_connect (src, parse); gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING); @@ -75,20 +73,19 @@ main(int argc, char *argv[]) } </programlisting> - <para> - We create two elements: a filesrc (the element that will read the - file from disk) and an mpeg1parser. We also add an EOS (End Of Stream) - signal to the filesrc so that we will be notified when the file has ended. - There's nothing special about this piece of code except for the signal - 'new_pad' that we connected to the mpeg1parser using: + <para> + We create two elements: a file source and an MPEG demuxer.. We also add an EOS (End Of Stream) + signal to the filesrc so that we will be notified when the file has ended. There's nothing + special about this piece of code except for the signal 'new_pad' that we connected to the + mpegdemux using: </para> <programlisting> - g_signal_connect (G_OBJECT (parse), "new_pad", + g_signal_connect (G_OBJECT (demux), "new_pad", G_CALLBACK (new_pad_created), pipeline); </programlisting> <para> When an elementary stream has been detected in the system stream, - mpeg1parse will create a new pad that will provide the data of the + mpegdemux will create a new pad that will provide the data of the elementary stream. A function 'new_pad_created' will be called when the pad is created: </para> @@ -96,12 +93,10 @@ main(int argc, char *argv[]) void new_pad_created (GstElement *parse, GstPad *pad, GstElement *pipeline) { - GstElement *parse_audio, *parse_video, *decode, *decode_video, *play, *videoscale, *show; + GstElement *decode_audio, *parse_video, *decode_video, *play, *videoscale, *show; GstElement *audio_queue, *video_queue; GstElement *audio_thread, *video_thread; - GtkWidget *appwindow; - g_print ("***** a new pad %s was created\n", gst_pad_get_name (pad)); gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PAUSED); @@ -110,38 +105,28 @@ new_pad_created (GstElement *parse, GstPad *pad, GstElement *pipeline) if (strncmp (gst_pad_get_name (pad), "audio_", 6) == 0) { // construct internal pipeline elements - parse_audio = gst_elementfactory_make ("mp3parse", "parse_audio"); - g_return_if_fail (parse_audio != NULL); - decode = gst_elementfactory_make ("mpg123", "decode_audio"); + decode = gst_elementfactory_make ("mad", "decode_audio"); g_return_if_fail (decode != NULL); - play = gst_elementfactory_make ("audiosink", "play_audio"); + play = gst_elementfactory_make ("osssink", "play_audio"); g_return_if_fail (play != NULL); // create the thread and pack stuff into it audio_thread = gst_thread_new ("audio_thread"); g_return_if_fail (audio_thread != NULL); - gst_bin_add (GST_BIN (audio_thread), GST_ELEMENT (parse_audio)); - gst_bin_add (GST_BIN (audio_thread), GST_ELEMENT (decode)); - gst_bin_add (GST_BIN (audio_thread), GST_ELEMENT (play)); + gst_bin_add_many (GST_BIN (audio_thread), decode_audio, play, NULL); // set up pad connections gst_element_add_ghost_pad (GST_ELEMENT (audio_thread), - gst_element_get_pad (parse_audio, "sink")); - gst_pad_connect (gst_element_get_pad (parse_audio,"src"), - gst_element_get_pad (decode,"sink")); - gst_pad_connect (gst_element_get_pad (decode,"src"), - gst_element_get_pad (play,"sink")); + gst_element_get_pad (decode_audio, "sink")); + gst_element_connect (decode, play); // construct queue and connect everything in the main pipelie audio_queue = gst_elementfactory_make ("queue", "audio_queue"); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (audio_queue)); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (audio_thread)); + gst_bin_add_many (GST_BIN (pipeline), audio_queue, audio_thread, NULL); - gst_pad_connect (pad, - gst_element_get_pad (audio_queue, "sink")); - gst_pad_connect (gst_element_get_pad (audio_queue, "src"), - gst_element_get_pad (audio_thread, "sink")); + gst_pad_connect (pad, gst_element_get_pad (audio_queue, "sink")); + gst_element_connect (audio_queue, audio_thread); // set up thread state and kick things off g_print ("setting to READY state\n"); @@ -151,47 +136,31 @@ new_pad_created (GstElement *parse, GstPad *pad, GstElement *pipeline) else if (strncmp (gst_pad_get_name (pad), "video_", 6) == 0) { // construct internal pipeline elements - parse_video = gst_elementfactory_make ("mp1videoparse", "parse_video"); - g_return_if_fail (parse_video != NULL); - decode_video = gst_elementfactory_make ("mpeg_play", "decode_video"); + decode_video = gst_elementfactory_make ("mpeg2dec", "decode_video"); g_return_if_fail (decode_video != NULL); - show = gst_elementfactory_make ("videosink", "show"); + show = gst_elementfactory_make ("xvideosink", "show"); g_return_if_fail (show != NULL); - appwindow = gnome_app_new ("MPEG1 player", "MPEG1 player"); - gnome_app_set_contents (GNOME_APP (appwindow), - gst_util_get_widget_arg (GTK_OBJECT (show), "widget")); - gtk_widget_show_all (appwindow); - // create the thread and pack stuff into it video_thread = gst_thread_new ("video_thread"); g_return_if_fail (video_thread != NULL); - gst_bin_add (GST_BIN (video_thread), GST_ELEMENT (parse_video)); - gst_bin_add (GST_BIN (video_thread), GST_ELEMENT (decode_video)); - gst_bin_add (GST_BIN (video_thread), GST_ELEMENT (show)); + gst_bin_add_many (GST_BIN (video_thread), decode_video, show, NULL); // set up pad connections gst_element_add_ghost_pad (GST_ELEMENT (video_thread), gst_element_get_pad (parse_video, "sink")); - gst_pad_connect (gst_element_get_pad (parse_video, "src"), - gst_element_get_pad (decode_video, "sink")); - gst_pad_connect (gst_element_get_pad (decode_video, "src"), - gst_element_get_pad (show, "sink")); + gst_element_connect (decode_video, show); // construct queue and connect everything in the main pipeline video_queue = gst_elementfactory_make ("queue", "video_queue"); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (video_queue)); - gst_bin_add (GST_BIN (pipeline), GST_ELEMENT (video_thread)); + gst_bin_add_many (GST_BIN (pipeline), video_queue, video_thread); - gst_pad_connect (pad, - gst_element_get_pad (video_queue, "sink")); - gst_pad_connect (gst_element_get_pad (video_queue, "src"), - gst_element_get_pad (video_thread, "sink")); + gst_pad_connect (pad, gst_element_get_pad (video_queue, "sink")); + gst_element_connect (video_queue, video_thread); // set up thread state and kick things off - g_object_set (G_OBJECT (video_thread), "create_thread", TRUE, NULL); g_print ("setting to READY state\n"); gst_element_set_state (GST_ELEMENT (video_thread), GST_STATE_READY); } @@ -199,10 +168,9 @@ new_pad_created (GstElement *parse, GstPad *pad, GstElement *pipeline) gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING); } </programlisting> - <para> - In the above example, we created new elements based on the name of - the newly created pad. We added them to a new thread There are other possibilities to check the - type of the pad, for example, by using the MIME type and the properties - of the pad. + <para> + In the above example, we created new elements based on the name of the newly created pad. We + then added them to a new thread. There are other possibilities to check the type of the pad, for + example by using the MIME type and the properties of the pad. </para> </chapter> diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml index 5d76c1fa5..3b361dee8 100644 --- a/docs/manual/elements.xml +++ b/docs/manual/elements.xml @@ -12,21 +12,16 @@ different components you are going to use are derived from this GstElement. This means that a lot of functions you are going to use operate on this object. </para> - <para> - You will see that those elements have pads. These are the elements - connections with the 'outside' world. Depending on the number and direction of - the pads, we can see three types of elements: source, filter and sink element. - </para> - <para> - These three types are all the same GstElement object, they just differ in how - the pads are. + <para> Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of + different aspects. One of these aspects is the presence of "pads", or connection points. This + terminology arises from soldering; pads are where wires can be attached. </para> <sect2 id="sec-elements-src"> - <title>GStreamer source elements</title> + <title>Source elements</title> <para> - This element will generate data that will be used by the pipeline. It is - typically a file or an audio source. + Source elements generate data for use by a pipeline, for example reading from disk or from a + sound card. </para> <para> Below you see how we will visualize the element. @@ -48,19 +43,17 @@ </sect2> <sect2 id="sec-elements-filter"> - <title>GStreamer filter elements</title> - <para> - Filter elements both have an input and an output pad. They operate on data - they receive in the sink pad and send the result to the src pad. - </para> + <title>Filters and codecs</title> <para> - Examples of a filter element might include: an MPEG decoder, volume filter,... - </para> + Filter elements both have input and output pads. They operate on data they receive in their + sink pads and produce data on their src pads. For example, MPEG decoders and volume filters + would fall into this category. + </para> <para> - Filters may also contain any number of input pads and output pads. For example, - a video mixer might have to input pads (the images of the two different video - streams) and one output pad. - </para> + Elements are not constrained as to the number of pads they migh have; for example, a video + mixer might have two input pads (the images of the two different video streams) and one + output pad. + </para> <figure float="1" id="sec-element-filterimg"> <title>Visualisation of a filter element</title> <mediaobject> @@ -71,7 +64,7 @@ </figure> <para> The above figure shows the visualisation of a filter element. This element has - one sink pad (input) and one src (output) pad. Sink pads are drawn on the left + one sink (input) pad and one src (output) pad. Sink pads are drawn on the left of the element. </para> <figure float="1" id="sec-element-multifilterimg"> @@ -84,21 +77,21 @@ </mediaobject> </figure> <para> - The above figure shows the visualisation of a filter element with more than one - output pad. An example of such a filter is the AVI splitter. This element will - parse the input data and extracts the audio and video data. Most of these filters - dynamically send out a signal when a new pad is created so that the application - programmer can connect an arbitrary element to the newly created pad. - </para> + The above figure shows the visualisation of a filter element with more than one output pad. + An example of such a filter is the AVI splitter (demuxer). This element will parse the input + data and extracts the audio and video data. Most of these filters dynamically send out a + signal when a new pad is created so that the application programmer can connect an arbitrary + element to the newly created pad. + </para> </sect2> <sect2 id="sec-elements-sink"> - <title>GStreamer sink elements</title> - <para> - This element accepts data but will not generate any new data. A sink element - is typically a file on disk, a soundcard, a display,... It is presented as - below: - </para> + <title>Sink elements</title> + <para> + Sink elements are terminal points in a media pipeline. They accept data but do not produce + anything. Disk writing, soundcard playback, and video output woul all be implemented by sink + elements. + </para> <figure float="1" id="sec-element-sinkimg"> <title>Visualisation of a sink element</title> <mediaobject> @@ -117,12 +110,12 @@ </para> <para> The following code example is used to get a factory that can be used to create the - mpg123 element, an mp3 decoder. + 'mad' element, an mp3 decoder. </para> <programlisting> GstElementFactory *factory; - factory = gst_elementfactory_find ("mpg123"); + factory = gst_elementfactory_find ("mad"); </programlisting> <para> Once you have the handle to the elementfactory, you can create a real element with @@ -133,23 +126,23 @@ element = gst_elementfactory_create (factory, "decoder"); </programlisting> - <para> - gst_elementfactory_create () will use the elementfactory to create an element with the - given name. The name of the element is something you can use later on to lookup the - element in a bin, for example. - </para> - <para> - A simple shortcut exists for creating an element from a factory. The following example - creates an element, named "decoder" from the elementfactory named "mpg123". This - convenient function is most widly used to create an element. - </para> + <para> + gst_elementfactory_create () will use the elementfactory to create an element with the given + name. The name of the element is something you can use later on to lookup the element in a + bin, for example. You can pass NULL as the name argument to get a unique, default name. + </para> + <para> + A simple shortcut exists for creating an element from a factory. The following example creates + an element, named "decoder" from the elementfactory named "mad". This convenient function is + most widely used to create an element. + </para> <programlisting> GstElement *element; - element = gst_elementfactory_make ("mpg123", "decoder"); + element = gst_elementfactory_make ("mad", "decoder"); </programlisting> <para> - An element can be destroyed with: + An element can be destroyed with: FIXME talk about refcounting </para> <programlisting> GstElement *element; diff --git a/docs/manual/factories.xml b/docs/manual/factories.xml index c5b89e110..eb7d5c70d 100644 --- a/docs/manual/factories.xml +++ b/docs/manual/factories.xml @@ -21,28 +21,27 @@ <programlisting> ... /* now it's time to get the parser */ - parse = gst_elementfactory_make ("mp3parse", "parse"); - decoder = gst_elementfactory_make ("mpg123", "decoder"); + decoder = gst_elementfactory_make ("mad", "decoder"); ... </programlisting> <para> While this mechanism is quite effective it also has some big problems: The elements are created based on their name. Indeed, we create an - element mpg123 by explicitly stating the mpg123 elements name. - Our little program therefore always uses the mpg123 decoder element + element mad by explicitly stating the mad element's name. + Our little program therefore always uses the mad decoder element to decode the MP3 audio stream, even if there are 3 other MP3 decoders in the system. We will see how we can use a more general way to create an MP3 decoder element. </para> <para> - We have to introduce the concept of MIME types and capabilities + We have to introduce the concept of MIME types and capabilities added to the source and sink pads. </para> </sect1> <sect1> - <title>more on MIME Types</title> + <title>More on MIME Types</title> <para> GStreamer uses MIME types to indentify the different types of data that can be handled by the elements. They are the high level @@ -124,9 +123,9 @@ a function that can be used to determine if a given buffer is of the given MIME type. </para> - <para> - There is also an association between a MIME type and a file - extension. + <para> + There is also an association between a MIME type and a file extension, but the use of typefind + functions (similar to file(1)) is preferred.. </para> <para> The type information is maintained in a list of @@ -202,86 +201,9 @@ struct _GstType { This function will return 0 if the extension was not known. </para> </sect2> - - <sect2> - <title>id to <classname>GstElementFactory</classname> conversion</title> - <para> - When we have obtained a given type id using one of the above methods, - we can obtain a list of all the elements that operate on this MIME - type or extension. - </para> - <para> - Obtain a list of all the elements that use this id as source with: - </para> - <programlisting> - GList *list; - - list = gst_type_gst_srcs (id); - </programlisting> - - <para> - Obtain a list of all the elements that use this id as sink with: - </para> - <programlisting> - GList *list; - - list = gst_type_gst_sinks (id); - </programlisting> - <para> - When you have a list of elements, you can simply take the first - element of the list to obtain an appropriate element. - </para> - <note> - <para> - As you can see, there might be a multitude of elements that - are able to operate on audio/raw types. some might include: - <itemizedlist> - <listitem> - <para> - an MP3 audio encoder. - </para> - </listitem> - <listitem> - <para> - an audio sink. - </para> - </listitem> - <listitem> - <para> - an audio resampler. - </para> - </listitem> - <listitem> - <para> - a spectrum filter. - </para> - </listitem> - </itemizedlist> - Depending on the application, you might want to use a different - element. This is why GStreamer leaves that decision up to the - application programmer. - </para> - </note> - - </sect2> - - <sect2> - <title>id to id path detection</title> - <para> - You can obtain a <classname>GList</classname> of elements that - will transform the source id into the destination id. - </para> - <programlisting> - GList *list; - - list = gst_type_gst_sink_to_src (sourceid, sinkid); - </programlisting> - <para> - This piece of code will give you the elements needed to construct - a path from sourceid to sinkid. This function is mainly used in - autoplugging the pipeline. - </para> - </sect2> + <para> + For more information, see <xref linkend="cha-autoplug"/>. + </para> </sect1> <sect1> diff --git a/docs/manual/goals.xml b/docs/manual/goals.xml index f8c5225df..f699face7 100644 --- a/docs/manual/goals.xml +++ b/docs/manual/goals.xml @@ -38,11 +38,11 @@ <sect2 id="sec-goals-object"> <title>Object oriented</title> <para> - Adhere as much as possible to the glib2.0 object model. A programmer familiar - with glib2 and GTK+ will be confortable with GStreamer. - </para> + Adhere to the GLib 2.0 object model. A programmer familiar with GLib 2.0 or older versions + of Gtk+ will be comfortable with GStreamer. + </para> <para> - GStreamer uses the mechanism of signals and object arguments. + GStreamer uses the mechanism of signals and object properties. </para> <para> All objects can be queried at runtime for their various properties and @@ -53,7 +53,7 @@ <sect2 id="sec-goals-extensible"> <title>Extensible</title> <para> - All GStreamer Objects can be extended using the glib2 inheritance methods. + All GStreamer Objects can be extended using the GObject inheritance methods. </para> <para> All plugins are loaded dynamically and can be extended and upgraded @@ -63,15 +63,14 @@ <sect2 id="sec-goals-binary"> <title>Allow binary only plugins</title> - <para> - plugins are shared libraries that are loaded at runtime. since all the - properties of the plugin can be set using the GObject properties, there - is no need to have any header files installed for the plugins. - </para> + <para> + Plugins are shared libraries that are loaded at runtime. Since all the properties of the + plugin can be set using the GObject properties, there is no need (and in fact no way) to + have any header files installed for the plugins. + </para> <para> Special care has been taking into making the plugin completely self - contained. This is in the operations, specification of the capabilities - of the plugin and properties. + contained. All relevant aspects of plugins can be queried at run-time. </para> </sect2> @@ -83,44 +82,43 @@ <itemizedlist> <listitem> <para> - Using glib g_mem_chunk where possible to minimize dynamic memory + Using GLib g_mem_chunk where possible to minimize dynamic memory allocation. </para> </listitem> <listitem> <para> - Connections between plugins are extremely light-weight. Data can travel + Extremely light-weight connections between plugins. Data can travel the pipeline with minimal overhead. </para> </listitem> <listitem> <para> - Provide a mechanism to directly work on the target memory. A - plugin can for example directly write to the X servers shared mem. - Buffers can also point to arbitrary memory like kernel memory. + Providing a mechanism to directly work on the target memory. A plugin can for example + directly write to the X server's shared memory space. Buffers can also point to + arbitrary memory, such as a sound card's internal hardware buffer. </para> </listitem> <listitem> <para> - Refcounting and copy on write to minimize the amount of memcpy. - Subbufers to efficiently split the data in a buffer. + Refcounting and copy on write minimize usage of memcpy(3). + Sub-buffers efficiently split buffers into manageable pieces. </para> </listitem> <listitem> <para> - Pipelines can be constructed using cothreads to minimize the - threading overhead. Cothreads are a simple user-space method for - switching between subtasks. + The use of cothreads to minimize the threading overhead. Cothreads are a simple and fast + user-space method for switching between subtasks. </para> </listitem> <listitem> <para> - HW acceleration is possible by writing a specialized plugin. + Allowing HW acceleration by the use of specialized plugins. </para> </listitem> <listitem> <para> - Uses a plugin registry with the specifications of the plugins so + Using a plugin registry with the specifications of the plugins so that the plugin loading can be delayed until the plugin is actually used. </para> diff --git a/docs/manual/gstreamer-manual.xml b/docs/manual/gstreamer-manual.xml index f4dd80fda..4a8875528 100644 --- a/docs/manual/gstreamer-manual.xml +++ b/docs/manual/gstreamer-manual.xml @@ -61,6 +61,15 @@ </para> </authorblurb> </author> + <author> + <firstname>Andy</firstname> + <surname>Wingo</surname> + <authorblurb> + <para> + <email>wingo@pobox.com</email> + </para> + </authorblurb> + </author> </authorgroup> <legalnotice id="legalnotice"> @@ -81,15 +90,14 @@ <part id="overview"><title>Overview</title> <partintro> - <para> - The first chapter of the book gives you an overview of <application>GStreamer</application> - design goals. Chapter 2 rapidly covers the basics of <application>GStreamer</application> - programming. In chapter 3 we will move on to the examples. - Since <application>GStreamer</application> adheres to the GTK+/glib2 programming model, the reader is - assumed to understand the basics of GTK+ and the glib2.0 object model. - For a gentle introduction to GTK+, you may wish to read the <emphasis>GTK+ - Tutorial</emphasis> or Eric Harlow's book <emphasis>Developing Linux - Applications with GTK+ and GDK</emphasis>. + <para> + <xref linkend="overview"/> gives you an overview of <application>GStreamer</application> + design goals. <xref linkend="basic-concepts"/> rapidly covers the basics of + <application>GStreamer</application> programming. In <xref linkend="build-app"/> we will move + on to the examples. Since <application>GStreamer</application> uses GLib 2.0, the reader is + assumed to understand the basics of the GObject object model. For a gentle introduction to + this system, you may wish to read the <emphasis>GTK+ Tutorial</emphasis> or Eric Harlow's + book <emphasis>Developing Linux Applications with GTK+ and GDK</emphasis>. </para> </partintro> @@ -186,8 +194,6 @@ &HELLOWORLD2; &DPARAMS; - - &UTILITY; </part> <!-- ############ XML in GStreamer - part ############# --> @@ -196,10 +202,10 @@ <partintro> <para> - <application>GStreamer</application> has the posibility to externalize the pipelines - you create using an XML format. You can load a previously - created pipeline by loading the XML file. - </para> + <application>GStreamer</application> has the possibility to serialize the pipelines you + create using an XML format. You can load a previously created pipeline by loading the XML + file. + </para> </partintro> &XML; diff --git a/docs/manual/helloworld.xml b/docs/manual/helloworld.xml index 8fe65276c..6072152e1 100644 --- a/docs/manual/helloworld.xml +++ b/docs/manual/helloworld.xml @@ -8,13 +8,12 @@ <sect1> <title>Hello world</title> - <para> - We will create a simple first application. In fact it will be a complete - MP3 player, using standard <application>GStreamer</application> components. The player will read from - a file that is given as the first argument of the program. + <para> + We will create a simple first application, a complete MP3 player, using standard + <application>GStreamer</application> components. The player will read from a file that is + given as the first argument of the program. </para> - <programlisting> #include <gst/gst.h> @@ -45,15 +44,10 @@ main (int argc, char *argv[]) audiosink = gst_elementfactory_make ("osssink", "play_audio"); /* add objects to the main pipeline */ - gst_bin_add (GST_BIN (pipeline), filesrc); - gst_bin_add (GST_BIN (pipeline), decoder); - gst_bin_add (GST_BIN (pipeline), audiosink); + gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); /* connect src to sink */ - gst_pad_connect (gst_element_get_pad (filesrc, "src"), - gst_element_get_pad (decoder, "sink")); - gst_pad_connect (gst_element_get_pad (decoder, "src"), - gst_element_get_pad (audiosink, "sink")); + gst_element_connect_many (filesrc, decoder, audiosink, NULL); /* start playing */ gst_element_set_state (pipeline, GST_STATE_PLAYING); @@ -64,10 +58,8 @@ main (int argc, char *argv[]) gst_element_set_state (pipeline, GST_STATE_NULL); /* we don't need a reference to these objects anymore */ - gst_object_unref (GST_OBJECT (audiosink)); - gst_object_unref (GST_OBJECT (decoder)); - gst_object_unref (GST_OBJECT (filesrc)); gst_object_unref (GST_OBJECT (pipeline)); + /* unreffing the pipeline unrefs the contained elements as well */ exit (0); } @@ -98,8 +90,8 @@ main (int argc, char *argv[]) </programlisting> <para> - We are going to create 3 elements and one pipeline. Since all objects are - in fact elements, we can define them as: + We are going to create 3 elements and one pipeline. Since all elements share the same base + type, <classname>GstElement</classname>, we can define them as: </para> <programlisting> ... @@ -142,7 +134,7 @@ main (int argc, char *argv[]) is installed on the system where this application is executed. </para> <programlisting> - /* now it's time to get the parser */ + /* now it's time to get the decoder */ decoder = gst_elementfactory_make ("mad", "decoder"); </programlisting> <para> @@ -167,9 +159,7 @@ main (int argc, char *argv[]) </para> <programlisting> /* add objects to the main pipeline */ - gst_bin_add (GST_BIN (pipeline), filesrc); - gst_bin_add (GST_BIN (pipeline), decoder); - gst_bin_add (GST_BIN (pipeline), audiosink); + gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); </programlisting> <para> @@ -177,10 +167,7 @@ main (int argc, char *argv[]) </para> <programlisting> /* connect src to sink */ - gst_pad_connect (gst_element_get_pad (filesrc, "src"), - gst_element_get_pad (decoder, "sink")); - gst_pad_connect (gst_element_get_pad (decoder, "src"), - gst_element_get_pad (audiosink, "sink")); + gst_element_connect_many (filesrc, decoder, audiosink, NULL); </programlisting> <para> @@ -229,16 +216,13 @@ main (int argc, char *argv[]) /* stop the pipeline */ gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (GST_OBJECT (audiosink)); - gst_object_unref (GST_OBJECT (decoder)); - gst_object_unref (GST_OBJECT (filesrc)); gst_object_unref (GST_OBJECT (pipeline)); exit (0); </programlisting> <note> <para> - don't forget to set the state of the pipeline to NULL. This will free + Don't forget to set the state of the pipeline to NULL. This will free all of the resources held by the elements. </para> </note> @@ -246,7 +230,7 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title>compiling helloworld.c</title> + <title>Compiling helloworld.c</title> <para> To compile the helloworld example, use: </para> @@ -268,10 +252,10 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title>conclusion</title> + <title>Conclusion</title> <para> This concludes our first example. As you see, setting up a pipeline - is very lowlevel but powerfull. You will later in this manual how + is very lowlevel but powerful. You will later in this manual how you can create a custom MP3 element with a more high level API. </para> <para> @@ -284,7 +268,7 @@ main (int argc, char *argv[]) We could use a disksink to write the raw samples to a file, for example. It should also be clear that inserting filters, like a stereo effect, into the pipeline is not that hard to do. The most important thing is - that you can reuse allready existing elements. + that you can reuse already existing elements. </para> </sect1> </chapter> diff --git a/docs/manual/helloworld2.xml b/docs/manual/helloworld2.xml index ba3b6dc81..0234aaef6 100644 --- a/docs/manual/helloworld2.xml +++ b/docs/manual/helloworld2.xml @@ -1,8 +1,8 @@ <chapter id="cha-hello2"> <title>Your second application</title> - <para> - In a previous chapter we created a first version of the helloworld - application. We then explained a better way of creating the elements + <para> + FIXME: delete this section, talk more about the spider. In a previous chapter we created a first + version of the helloworld application. We then explained a better way of creating the elements using factories identified by MIME types and the autoplugger. </para> @@ -35,7 +35,7 @@ main (int argc, char *argv[]) gst_init (&argc, &argv); if (argc != 2) { - g_print ("usage: %s <filename>\n", argv[0]); + g_print ("usage: %s <filename>\n", argv[0]); exit (-1); } diff --git a/docs/manual/highlevel-components.xml b/docs/manual/highlevel-components.xml index a4272342f..0c5923f78 100644 --- a/docs/manual/highlevel-components.xml +++ b/docs/manual/highlevel-components.xml @@ -1,5 +1,10 @@ <chapter id="cha-components"> <title>Components</title> + + <para> + FIXME: This chapter is way out of date. + </para> + <para> <application>GStreamer</application> includes components that people can include in their programs. diff --git a/docs/manual/init.xml b/docs/manual/init.xml index 985dcc214..bae542d74 100644 --- a/docs/manual/init.xml +++ b/docs/manual/init.xml @@ -34,5 +34,29 @@ main (int argc, char *argv[]) Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to get the <application>GStreamer</application> version you are building against. </para> + <sect1> + <title>The popt interface</title> + <para> + more info here + </para> + <programlisting> +int +main(int argc, char *argv[]) +{ + gboolean silent = FALSE; + gchar *savefile = NULL; + struct poptOption options[] = { + {"silent", 's', POPT_ARG_NONE|POPT_ARGFLAG_STRIP, &silent, 0, + "do not output status information", NULL}, + {"output", 'o', POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &savefile, 0, + "save xml representation of pipeline to FILE and exit", "FILE"}, + POPT_TABLEEND + }; + + gst_init_with_popt_table (&argc, &argv, options); + + ... + </programlisting> + </sect1> </chapter> diff --git a/docs/manual/intro-motivation.xml b/docs/manual/intro-motivation.xml index 1ba996f8d..69ea414d9 100644 --- a/docs/manual/intro-motivation.xml +++ b/docs/manual/intro-motivation.xml @@ -80,7 +80,7 @@ </para> <para> No provisions have been made for emerging technologies such as - the GNOME object embedding using BONOBO. + the GNOME object embedding using Bonobo. </para> <para> While the GStreamer core does not use network transparent technologies diff --git a/docs/manual/intro-preface.xml b/docs/manual/intro-preface.xml index 208c25ee9..5c45bfc31 100644 --- a/docs/manual/intro-preface.xml +++ b/docs/manual/intro-preface.xml @@ -23,11 +23,11 @@ <para> GStreamer, however, is much more than just another media player. Its main advantages are that the pluggable components also make it possible - to write a full flegded video or audio editing application. + to write a full fledged video or audio editing application. </para> <para> - The framework is based on plug-ins that will provide the various codec + The framework is based on plugins that will provide the various codec and other functionality. The plugins can be connected and arranged in a pipeline. This pipeline defines the flow of the data. Pipelines can also be edited with a GUI editor and saved as XML so that pipeline diff --git a/docs/manual/intro.xml b/docs/manual/intro.xml index 208c25ee9..5c45bfc31 100644 --- a/docs/manual/intro.xml +++ b/docs/manual/intro.xml @@ -23,11 +23,11 @@ <para> GStreamer, however, is much more than just another media player. Its main advantages are that the pluggable components also make it possible - to write a full flegded video or audio editing application. + to write a full fledged video or audio editing application. </para> <para> - The framework is based on plug-ins that will provide the various codec + The framework is based on plugins that will provide the various codec and other functionality. The plugins can be connected and arranged in a pipeline. This pipeline defines the flow of the data. Pipelines can also be edited with a GUI editor and saved as XML so that pipeline diff --git a/docs/manual/motivation.xml b/docs/manual/motivation.xml index 1ba996f8d..69ea414d9 100644 --- a/docs/manual/motivation.xml +++ b/docs/manual/motivation.xml @@ -80,7 +80,7 @@ </para> <para> No provisions have been made for emerging technologies such as - the GNOME object embedding using BONOBO. + the GNOME object embedding using Bonobo. </para> <para> While the GStreamer core does not use network transparent technologies diff --git a/docs/manual/pads.xml b/docs/manual/pads.xml index 36bd02184..953367a6d 100644 --- a/docs/manual/pads.xml +++ b/docs/manual/pads.xml @@ -1,7 +1,7 @@ <chapter id="cha-pads"> <title>GstPad</title> <para> - As we have seen in the previous chapter (GstElement), the pads are the elements + As we have seen in the previous chapter (GstElement), the pads are the element's connections with the outside world. </para> <para> @@ -44,7 +44,7 @@ <title>Useful pad functions</title> <para> You can get the name of a pad with gst_pad_get_name () and set its name with - get_pad_set_name(); + get_pad_set_name(). </para> <para> gst_pad_get_direction (GstPad *pad) can be used to query if the pad is a sink @@ -53,8 +53,8 @@ </para> <para> You can get the parent of the pad, this is the element that this pad belongs to, - with get_pad_set_parent(GstPad *pad). This function will return a pointer to a - GstObject. + with get_pad_get_parent(GstPad *pad). This function will return a pointer to a + GstElement. </para> </sect2> <sect2 id="sec-pads-dynamic"> @@ -63,10 +63,10 @@ Some elements might not have their pads when they are created. This can, for example, happen with an MPEG2 system demuxer. The demuxer will create its pads at runtime when it detects the different elementary streams in the MPEG2 - system stream. + system stream. </para> <para> - Running <application>gstreamer-inspect mpeg2parse</application> will show that + Running <application>gst-inspect mpegdemux</application> will show that the element has only one pad: a sink pad called 'sink'. The other pads are "dormant" as you can see in the padtemplates from the 'Exists: Sometimes' property. Depending on the type of MPEG2 file you play, the pads are created. We @@ -104,7 +104,7 @@ main(int argc, char *argv[]) // create pipeline and do something usefull ... - mpeg2parser = gst_elementfactory_make ("mpeg2parse", "mpeg2parse"); + mpeg2parser = gst_elementfactory_make ("mpegdemux", "mpegdemux"); g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_connect_func, pipeline); ... @@ -141,19 +141,19 @@ main(int argc, char *argv[]) ... element = gst_elementfactory_make ("tee", "element"); - pad = gst_element_request_pad_by_name (element, "src%d"); + pad = gst_element_get_request_pad (element, "src%d"); g_print ("new pad %s\n", gst_pad_get_name (pad)); ... </programlisting> <para> - The gst_element_request_pad_by_name method can be used to get a pad + The gst_element_get_request_pad method can be used to get a pad from the element based on the name_template of the padtemplate. </para> <para> It is also possible to request a pad that is compatible with another padtemplate. This is very usefull if you want to connect an element to a muxer element and you need to request a pad that is compatible. The - gst_element_request_compatible_pad is used to request a compatible pad, as + gst_element_get_compatible_pad is used to request a compatible pad, as is shown in the next example. </para> <programlisting> @@ -162,11 +162,11 @@ main(int argc, char *argv[]) GstPad *pad; ... element = gst_elementfactory_make ("tee", "element"); - mp3parse = gst_elementfactory_make ("mp3parse", "mp3parse"); + mad = gst_elementfactory_make ("mad", "mad"); - templ = gst_element_get_padtemplate_by_name (mp3parse, "sink"); + templ = gst_element_get_padtemplate_by_name (mad, "sink"); - pad = gst_element_request_compatible_pad (element, templ); + pad = gst_element_get_compatible_pad (element, templ); g_print ("new pad %s\n", gst_pad_get_name (pad)); ... </programlisting> @@ -181,7 +181,7 @@ main(int argc, char *argv[]) <para> We will briefly describe what capabilities are, enough for you to get a basic understanding of the concepts. You will find more information on how to create capabilities in the - filter-writer-guide. + Plugin Writer's Guide. </para> <sect2 id="sec-pads-caps"> @@ -207,8 +207,8 @@ struct _GstCaps { }; </programlisting> <para> - Below is a dump of the capabilities of the element mpg123, as shown by - <command>gstreamer-inspect</command>. + Below is a dump of the capabilities of the element mad, as shown by + <command>gst-inspect</command>. You can see two pads: sink and src. Both pads have capability information attached to them. </para> <para> @@ -221,26 +221,25 @@ struct _GstCaps { </para> <programlisting> Pads: - SINK: 'sink' - .... - Capabilities: - 'mpg123_sink': - MIME type: 'audio/mp3': - layer: Integer range: 1 - 3 - bitrate: Integer range: 8 - 320 - framed: Boolean: TRUE + SINK template: 'sink' + Availability: Always + Capabilities: + 'mad_sink': + MIME type: 'audio/mp3': - SRC: 'src' - .... + SRC template: 'src' + Availability: Always Capabilities: - 'mpg123_src': - MIME type: 'audio/raw': - format: Integer: 16 - depth: Integer: 16 - rate: Integer range: 11025 - 48000 - channels: List: - Integer: 1 - Integer: 2 + 'mad_src': + MIME type: 'audio/raw': + format: String: int + endianness: Integer: 1234 + width: Integer: 16 + depth: Integer: 16 + channels: Integer range: 1 - 2 + law: Integer: 0 + signed: Boolean: TRUE + rate: Integer range: 11025 - 48000 </programlisting> </sect2> <sect2 id="sec-pads-props"> @@ -260,7 +259,7 @@ Pads: <listitem> <para> An integer range value. The property denotes a range of possible values. In the case - of the mpg123 element: the src pad has a property rate that can go from 11025 to 48000. + of the mad element: the src pad has a property rate that can go from 11025 to 48000. </para> </listitem> <listitem> @@ -349,7 +348,7 @@ Pads: </para> <para> As we said, a capability has a name, a mime-type and some properties. The signature of the - function to create a new <classname>GstCaps *</classname> structure is like: + function to create a new <classname>GstCaps</classname> structure is like: <programlisting> GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); </programlisting> diff --git a/docs/manual/plugins.xml b/docs/manual/plugins.xml index a89d9cb90..a8fa76abb 100644 --- a/docs/manual/plugins.xml +++ b/docs/manual/plugins.xml @@ -20,6 +20,11 @@ one or more autopluggers </para> </listitem> + <listitem> + <para> + exported symbols for use in other plugins + </para> + </listitem> </itemizedlist> <para> The plugins have one simple method: plugin_init () where all the elementfactories are diff --git a/docs/manual/programs.xml b/docs/manual/programs.xml index 28a1c1791..7f57334bb 100644 --- a/docs/manual/programs.xml +++ b/docs/manual/programs.xml @@ -4,40 +4,37 @@ </para> <sect1> - <title><command>gstreamer-register</command></title> + <title><command>gst-register</command></title> <para> - <command>gstreamer-register</command> is used to rebuild the database of plugins. + <command>gst-register</command> is used to rebuild the database of plugins. It is used after a new plugin has been added to the system. The plugin database - can be found in <filename>/etc/gstreamer/reg.xml</filename>. + can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>. </para> </sect1> <sect1> - <title><command>gstreamer-launch</command></title> + <title><command>gst-launch</command></title> <para> This is a tool that will construct pipelines based on a command-line - syntax. + syntax. FIXME: need a more extensive grammar reference </para> <para> A simple commandline looks like: <screen> -gstreamer-launch filesrc location=hello.mp3 ! mp3parse ! mpg123 ! audiosink +gst-launch filesrc location=hello.mp3 ! mad ! osssink </screen> A more complex pipeline looks like: <screen> -gstreamer-launch filesrc redpill.vob audio_00! (ac3parse ! ac3dec ! audiosink) \ -video_00! (mpeg2dec ! videosink) +gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \ + demux.audio_00! { ac3parse ! a52dec ! osssink } \ + demux.video_00! { mpeg2dec ! xvideosink } </screen> </para> <para> - Note that the parser isn't capable of more complex pipelines yet, including - the VOB player above. The minor tweaks will be made post 0.2.1. - </para> - <para> You can also use the the parser in you own code. <application>GStreamer</application> provides a function gst_parse_launch () that you can use to construt a pipeline. The following programs lets you create an mp3 pipeline using the gst_parse_launch () @@ -51,17 +48,21 @@ main (int argc, char *argv[]) { GstElement *pipeline; GstElement *filesrc; + GError *error = NULL; gst_init (&argc, &argv); if (argc != 2) { - g_print ("usage: %s <filename>\n", argv[0]); + g_print ("usage: %s <filename>\n", argv[0]); return -1; } - pipeline = gst_pipeline_new ("my_pipeline"); - - gst_parse_launch ("filesrc[my_filesrc] ! mp3parse ! mpg123 ! osssink", GST_BIN (pipeline)); + pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &error); + if (!pipeline) { + g_print ("Parse error: %s\n", error->message); + exit (1); + } + filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc"); g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL); @@ -81,20 +82,20 @@ main (int argc, char *argv[]) </sect1> <sect1> - <title><command>gstreamer-inspect</command></title> + <title><command>gst-inspect</command></title> <para> This is a tool to query a plugin or an element about its properties. </para> <para> - To query the information about the element mpg123, you would specify: + To query the information about the element mad, you would specify: </para> <screen> -gstreamer-inspect mpg123 +gst-inspect mad </screen> <para> - Below is the output of a query for the audiosink element: + Below is the output of a query for the osssink element: </para> <screen> @@ -102,56 +103,72 @@ Factory Details: Long name: Audio Sink (OSS) Class: Sink/Audio Description: Output to a sound card via OSS - Version: 0.1.0 - Author(s): Erik Walthinsen <omega@cse.ogi.edu> + Version: 0.3.3.1 + Author(s): Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be> Copyright: (C) 1999 +GObject + +----GstObject + +----GstElement + +----GstOssSink + Pad Templates: SINK template: 'sink' - Exists: Always + Availability: Always Capabilities: - 'audiosink_sink': + 'osssink_sink': MIME type: 'audio/raw': - format: Integer: 16 + format: String: int + endianness: Integer: 1234 + width: List: + Integer: 8 + Integer: 16 depth: List: Integer: 8 Integer: 16 - rate: Integer range: 8000 - 48000 channels: Integer range: 1 - 2 + law: Integer: 0 + signed: List: + Boolean: FALSE + Boolean: TRUE + rate: Integer range: 1000 - 48000 + Element Flags: GST_ELEMENT_THREADSUGGESTED - no flags set Element Implementation: No loopfunc(), must be chain-based or not configured yet - Has change_state() function + Has change_state() function: gst_osssink_change_state + Has custom save_thyself() function: gst_element_save_thyself + Has custom restore_thyself() function: gst_element_restore_thyself + +Clocking Interaction: + element requires a clock + element provides a clock: GstOssClock Pads: SINK: 'sink' Implementation: - Has chainfunc(): 0x4001cde8 - Has default eosfunc() gst_pad_eos_func() + Has chainfunc(): 0x40056fc0 Pad Template: 'sink' - Capabilities: - 'audiosink_sink': - MIME type: 'audio/raw': - format: Integer: 16 - depth: List: - Integer: 8 - Integer: 16 - rate: Integer range: 8000 - 48000 - channels: Integer range: 1 - 2 Element Arguments: - GstAudioSink::mute: Boolean - GstAudioSink::format: Enum (default 16) - (8): 8 Bits - (16): 16 Bits - GstAudioSink::channels: Enum (default 2) + name : String (Default "element") + device : String (Default "/dev/dsp") + mute : Boolean (Default false) + format : Integer (Default 16) + channels : Enum "GstAudiosinkChannels" (default 1) + (0): Silence (1): Mono (2): Stereo - GstAudioSink::frequency: Integer + frequency : Integer (Default 11025) + fragment : Integer (Default 6) + buffer-size : Integer (Default 4096) + +Element Signals: + "handoff" : void user_function (GstOssSink* object, + gpointer user_data); </screen> <para> @@ -159,11 +176,11 @@ Element Arguments: </para> <screen> -gstreamer-inspect gstelements +gst-inspect gstelements </screen> </sect1> <sect1> - <title><command>gstmediaplay</command></title> + <title><command>gst-play</command></title> <para> A sample media player. </para> diff --git a/docs/manual/states.xml b/docs/manual/states.xml index 28064055d..d60319073 100644 --- a/docs/manual/states.xml +++ b/docs/manual/states.xml @@ -146,7 +146,7 @@ </note> <para> The pipeline has to be in the PAUSED or NULL state if you want to insert or modify an element - in the pipeline. We will cover dynamic pipeline behaviour in ... <!-- fixme --> + in the pipeline. We will cover dynamic pipeline behaviour in <xref linkend="cha-dynamic"/>. </para> </sect1> diff --git a/docs/manual/threads.xml b/docs/manual/threads.xml index 77680e2cd..f9b00b96b 100644 --- a/docs/manual/threads.xml +++ b/docs/manual/threads.xml @@ -1,7 +1,7 @@ <chapter id="cha-threads"> <title>Threads</title> <para> - GStreamer has support for multithreading throught the use of + GStreamer has support for multithreading through the use of the <classname>GstThread</classname> object. This object is in fact a special <classname>GstBin</classname> that will become a thread when started. </para> @@ -13,39 +13,58 @@ <programlisting> GstElement *my_thread; - // create the thread object + /* create the thread object */ my_thread = gst_thread_new ("my_thread"); - g_return_if_fail (audio_thread != NULL); + /* you could have used gst_elementfactory_make ("thread", "my_thread"); */ + g_return_if_fail (my_thread != NULL); - // add some plugins + /* add some plugins */ gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (funky_src)); gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (cool_effect)); - // connect the elements here... + /* connect the elements here... */ ... - // start playing + /* start playing */ gst_element_set_state (GST_ELEMENT (my_thread), GST_STATE_PLAYING); </programlisting> - <para> - The above program will create a thread with two elements in it. As soon - as it is set to the PLAYING state, the thread will start to iterate. + <para> + The above program will create a thread with two elements in it. As soon as it is set to the + PLAYING state, the thread will start to iterate itself. You never need to manually iterate a + thread. </para> - <note> - <para> - A thread should normally contain a source element. Most often, the thread - is fed with data from a queue. - </para> - </note> - + <sect2> + <title>Constraints placed on the pipeline by the GstThread</title> + <para> + Within the pipeline, everything is the same as in any other bin. The difference lies at the + thread boundary, at the connection between the thread and the outside world (containing bin). + Since GStreamer is fundamentally buffer-oriented rather than byte-oriented, the natural + solution to this problem is an element that can "buffer" the buffers between the threads, in a + thread-safe fashion. This element is the queue, described more fully in <xref + linkend="cha-queues"/>. It doesn't matter if the queue is placed in the containing bin or in + the thread itself, but it needs to be present on one side of the other to enable inter-thread + communication. + </para> + </sect2> + <sect2> + <title>When would you want to use a thread?</title> + <para> + If you are writing a GUI application, making the top-level bin a thread will make your GUI + more responsive. If it were a pipeline instead, it would have to be iterated by your + application's event loop, which increases the latency between events (say, keyboard presses) + and responses from the GUI. In addition, any slight hang in the GUI would delay iteration of + the pipeline, which (for example) could cause pops in the output of the sound card, if it is + an audio pipeline. + </para> + </sect2> <para> - A thread will be visualised as below + A thread can be visualised as below </para> <figure float="1" id="sec-threads-img"> - <title>a thread</title> + <title>A thread</title> <mediaobject> <imageobject> <imagedata fileref="images/thread.&magic;" format="&magic;" /> diff --git a/docs/manual/utility.xml b/docs/manual/utility.xml deleted file mode 100644 index 2bc6504af..000000000 --- a/docs/manual/utility.xml +++ /dev/null @@ -1,90 +0,0 @@ -<chapter id="cha-utility"> - <title>Utility functions</title> - <para> - while you can use the regular g_object_getv () function to - query the value of an object property, <application>GStreamer</application> - provides some easy wrappers for this common operation. - </para> - <para> - Instead of writing the following glib code to query the GTK_STRING value - of an object: - </para> - <programlisting> - GtkArg arg; - guchar *value; - - arg.name = argname; - g_object_getv (G_OBJECT (object), 1, &arg); - value = GTK_VALUE_STRING (arg); - </programlisting> - <para> - You can also use: - </para> - <programlisting> - value = gst_util_get_string_arg (object, argname); - </programlisting> - <para> - These convenience functions exist for the following types: - <itemizedlist> - <listitem> - <para> - gint: with gst_util_get_int_arg (); - </para> - </listitem> - <listitem> - <para> - gboolean: with gst_util_get_bool_arg (); - </para> - </listitem> - <listitem> - <para> - glong: with gst_util_get_long_arg (); - </para> - </listitem> - <listitem> - <para> - gfloat: with gst_util_get_float_arg (); - </para> - </listitem> - <listitem> - <para> - gdouble: with gst_util_get_double_arg (); - </para> - </listitem> - <listitem> - <para> - guchar*: with gst_util_get_string_arg (); - </para> - </listitem> - <listitem> - <para> - gpointer: with gst_util_get_pointer_arg (); - </para> - </listitem> - </itemizedlist> - </para> - <para> - One usually sets object properties using g_object_set (). The problem with this - method is that you need to know the type of the property. A convenience function, - gst_utils_set_object_arg () is therefore provided so that you can always set - the property with a string value. for example: - </para> - <programlisting> - gst_util_set_object_arg (someobject, "int_property", "1000"); - </programlisting> - <para> - Will do The Right Thing(tm), converting the string to the type of the property when - needed. - </para> - - <para> - There is also another utility function that can be used to dump a block - of memory on the console. This function is very usefull for plugin - developers. The function will dump size bytes of the memory pointed - to by mem. - </para> - <programlisting> - void gst_util_dump_mem (guchar *mem, guint size); - </programlisting> - -</chapter> |