Commit 43cbc42c authored by Andy Wingo Wingo's avatar Andy Wingo Wingo

the 'brown paper bag' commit. sorry for the email spam on this one, but it will be laaaarrrggggeee

Original commit message from CVS:
the 'brown paper bag' commit. sorry for the email spam on this one, but it will be laaaarrrggggeee
parent 5c10feaf
<!-- ##### SECTION Title ##### -->
cothreads
<!-- ##### SECTION Short_Description ##### -->
userspace threads
<!-- ##### SECTION Long_Description ##### -->
<para>
Cothreads are a simple user-space method for switching between
subtasks. They're based on setjmp()/longjmp() in their current form.
</para>
<para>
Cothreads are used for loop-based elements that pull data instead
of being fed with data. They can also be used to pull a specific region
of data out of their src element.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO CURRENT_STACK_FRAME ##### -->
<para>
Get the current stack frame.
</para>
<!-- ##### STRUCT cothread_state ##### -->
<para>
</para>
@ctx:
@threadnum:
@func:
@argc:
@argv:
@flags:
@sp:
@jmp:
@top_sp:
@pc:
<!-- ##### STRUCT cothread_context ##### -->
<para>
</para>
<!-- ##### USER_FUNCTION cothread_func ##### -->
<para>
the function that will be called when the cothread starts. The function
prototype is like a main() function, so you can do whatever you want with
it.
</para>
@argc: a main-like argument count
@argv: a main-like array of arguments
@Returns: a return code
<!-- ##### MACRO COTHREAD_STARTED ##### -->
<para>
Indicates the cothread is started.
</para>
<!-- ##### MACRO COTHREAD_DESTROYED ##### -->
<para>
Indicates the cothread is destroyed.
</para>
<!-- ##### FUNCTION cothread_context_init ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION cothread_context_free ##### -->
<para>
</para>
@ctx:
<!-- ##### FUNCTION cothread_create ##### -->
<para>
</para>
@ctx:
@Returns:
<!-- ##### FUNCTION cothread_free ##### -->
<para>
</para>
@thread:
<!-- ##### FUNCTION cothread_setfunc ##### -->
<para>
</para>
@thread:
@func:
@argc:
@argv:
<!-- ##### FUNCTION cothread_stop ##### -->
<para>
</para>
@thread:
<!-- ##### FUNCTION cothread_switch ##### -->
<para>
</para>
@thread:
<!-- ##### FUNCTION cothread_set_data ##### -->
<para>
</para>
@thread:
@key:
@data:
<!-- ##### FUNCTION cothread_get_data ##### -->
<para>
</para>
@thread:
@key:
@Returns:
<!-- ##### FUNCTION cothread_lock ##### -->
<para>
</para>
@thread:
<!-- ##### FUNCTION cothread_trylock ##### -->
<para>
</para>
@thread:
@Returns:
<!-- ##### FUNCTION cothread_unlock ##### -->
<para>
</para>
@thread:
<!-- ##### FUNCTION cothread_main ##### -->
<para>
</para>
@ctx:
@Returns:
<!-- ##### FUNCTION cothread_current_main ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION cothread_current ##### -->
<para>
</para>
@Returns:
<!-- ##### SECTION Title ##### -->
GObject
<!-- ##### SECTION Short_Description ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Title ##### -->
Gstreamer
<!-- ##### SECTION Short_Description ##### -->
Media library supporting arbitrary formats and filter graphs.
<!-- ##### SECTION Long_Description ##### -->
<para>
GStreamer is a framework for constructing graphs of various filters
(termed elements here) that will handle streaming media. Any discreet
(packetizable) media type is supported, with provisions for automatically
determining source type. Metadata can be passed with all data to provide
formatting/framing information. Plugins are heavily used to provide for
all elements, allowing one to construct plugins outside of the GST
library, even released binary-only if license require (please don't).
</para>
<para>
GStreamer borrows heavily from both the <ulink
url="http://www.cse.ogi.edu/sysl/">OGI media pipeline</ulink> and
Microsoft's DirectShow, hopefully taking the best of both and leaving the
cruft behind. Its interface is still very fluid (I've redesigned the
metadata handling twice already), and thus can be changed to increase the
sanity/noise ratio.
</para>
<para>
The <application>GStreamer</application> library should be initialized with gst_init() before
it can be used. You should pass a pointer to the main argc and argv variables so that GStreamer can
process its own command line options, as shown in the following example.
<programlisting>
int
main (int argc, char *argv[])
{
// initialize the GStreamer library
gst_init (&amp;argc, &amp;argv);
...
}
</programlisting>
</para>
<para>
Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros
to find the version at compile time.
</para>
<para>
gst_main() and gst_main_quit() enter and exit the main loop.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
Check out both <ulink url="http://www.cse.ogi.edu/sysl/">OGI's
pipeline</ulink> and Microsoft's DirectShow for some background.
</para>
<!-- ##### FUNCTION gst_init ##### -->
<para>
</para>
@argc:
@argv:
<!-- ##### FUNCTION gst_version ##### -->
<para>
</para>
@major:
@minor:
@micro:
<!-- ##### FUNCTION gst_main ##### -->
<para>
</para>
<!-- ##### FUNCTION gst_main_quit ##### -->
<para>
</para>
<!-- ##### MACRO GST_VERSION_MAJOR ##### -->
<para>
The major version of GStreamer at compile time
</para>
<!-- ##### MACRO GST_VERSION_MINOR ##### -->
<para>
The minor version of GStreamer at compile time
</para>
<!-- ##### MACRO GST_VERSION_MICRO ##### -->
<para>
The micro version of GStreamer at compile time
</para>
<!-- ##### SECTION Title ##### -->
GstAggregator
<!-- ##### SECTION Short_Description ##### -->
Combine buffers.
<!-- ##### SECTION Long_Description ##### -->
<para>
The aggregator is mainly used for testing purposes. It has several
methods to request buffers from its pads.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### ENUM GstAggregatorSchedType ##### -->
<para>
</para>
@AGGREGATOR_LOOP:
@AGGREGATOR_LOOP_PEEK:
@AGGREGATOR_LOOP_SELECT:
@AGGREGATOR_CHAIN:
<!-- ##### ARG GstAggregator:num-pads ##### -->
<para>
</para>
<!-- ##### ARG GstAggregator:silent ##### -->
<para>
</para>
<!-- ##### ARG GstAggregator:sched ##### -->
<para>
</para>
<!-- ##### SECTION Title ##### -->
gstarch
<!-- ##### SECTION Short_Description ##### -->
Architecural specific macros and functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
This file contains various macros and function for performing common
GStreamer tasks that requires some knowledge of the underlaying architecture.
Porting to other CPU architectures will typically require adding appropriate
implementations in this file.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO GST_ARCH_CALL ##### -->
<para>
Jumps to a specific location in memory.
</para>
@target: the memory to jump to.
<!-- ##### MACRO GST_ARCH_SET_SP ##### -->
<para>
Sets the stackpointer.
</para>
@stackpointer: the stackpointer to set.
<!-- ##### MACRO GST_ARCH_SETUP_STACK ##### -->
<para>
Make toom on the stack?
</para>
@sp: the stackpointer to modify.
<!-- ##### MACRO GST_ARCH_PRESETJMP ##### -->
<para>
Do something funny, which is required on some archs..
</para>
<!-- ##### SECTION Title ##### -->
GstAutoplug
<!-- ##### SECTION Short_Description ##### -->
Automatically create and connect elements
<!-- ##### SECTION Long_Description ##### -->
<para>
GstAutoplug is an abstract class that is used for constructing and
connecting elements. Two types of autopluggers exist: renderer ones and non
renderer ones. the renderer autopluggers will not have any src pads while the
non renderer ones do.
</para>
<para>
You first need to create a suitable autoplugger with gst_autoplugfactory_make()
(see #GstAutoplugFactory).
The name of the autoplugger must be one of the registered autopluggers
(see #GstStaticAutoplug and #GstStaticAutoplugRender).
</para>
<para>
If the autoplugger supports the RENDERER API, use gst_autoplug_to_renderers() call to
create a bin that connectes the src caps to the specified rendrer elements. You can
then add the bin to a pipeline and run it.
<programlisting>
GstAutoplug *autoplug;
GstElement *element;
GstElement *sink;
/* create a static autoplugger */
autoplug = gst_autoplugfactory_make ("staticrender");
/* create an osssink */
sink = gst_elementfactory_make ("osssink", "our_sink");
/* create an element that can play audio/mp3 through osssink */
element = gst_autoplug_to_renderers (autoplug,
gst_caps_new (
"sink_audio_caps",
"audio/mp3",
NULL
),
sink,
NULL);
/* add the element to a bin and connect the sink pad */
...
</programlisting>
</para>
<para>
If the autoplugger supports the CAPS API, use gst_autoplug_to_caps() call to
connect the src caps to the destination caps. The created bin will have src pads
compatible with the provided sink caps.
<programlisting>
GstAutoplug *autoplug;
GstElement *element;
/* create a static autoplugger */
autoplug = gst_autoplugfactory_make ("static");
/* create an element that converts audio/mp3 to audio/raw */
element = gst_autoplug_to_caps (autoplug,
gst_caps_new (
"sink_audio_caps",
"audio/mp3",
NULL
),
gst_caps_new (
"src_audio_caps",
"audio/raw",
NULL
),
NULL);
/* add the element to a bin and connect the src/sink pads */
...
</programlisting>
</para>
<para>
Optionally you can get a notification when a new object is added to the created
pipeline with a g_signal_connect to the "new_object" signal.
</para>
<para>
Use the regular gst_object_destroy() call to destroy the autoplugger.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstStaticAutoplug, #GstStaticAutoplugRender
</para>
<!-- ##### STRUCT GstAutoplug ##### -->
<para>
</para>
@object:
<!-- ##### ENUM GstAutoplugFlags ##### -->
<para>
The type of the autoplugger.
</para>
@GST_AUTOPLUG_TO_CAPS:
@GST_AUTOPLUG_TO_RENDERER:
@GST_AUTOPLUG_FLAG_LAST:
<!-- ##### FUNCTION gst_autoplug_signal_new_object ##### -->
<para>
</para>
@autoplug:
@object:
<!-- ##### FUNCTION gst_autoplug_to_caps ##### -->
<para>
</para>
@autoplug:
@srccaps:
@sinkcaps:
@Varargs:
@Returns:
<!-- ##### FUNCTION gst_autoplug_to_renderers ##### -->
<para>
</para>
@autoplug:
@srccaps:
@target:
@Varargs:
@Returns:
<!-- ##### SECTION Title ##### -->
GstAutoplugFactory
<!-- ##### SECTION Short_Description ##### -->
Create autopluggers from a factory.
<!-- ##### SECTION Long_Description ##### -->
<para>
An autoplugfactory is used to create instances of an autoplugger. It
can be added to a #GstPlugin as it extends #GstPluginFeature.
</para>
<para>
Use gst_autoplugfactory_new() to create a new autoplugger which can be registered
to a plugin with gst_plugin_add_feature().
</para>
<para>
Use gst_autoplugfactory_find() to find the named autoplugfactory.
or use gst_autoplugfactory_get_list() to get a list of all available autopluggers.
</para>
<para>
Once an autoplugfactory has been obtained use gst_autoplugfactory_create() to
instantiate a real autoplugger. Optionally gst_autoplugfactory_make() to create
a autoplugger from the named factory.
</para>
<para>
Use gst_autoplugfactory_destroy() to remove the factory from the global list.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstAutoplug, #GstPlugin, #GstPluginFeature.
</para>
<!-- ##### STRUCT GstAutoplugFactory ##### -->
<para>
</para>
<!-- ##### FUNCTION gst_autoplugfactory_new ##### -->
<para>
</para>
@name:
@longdesc:
@type:
@Returns:
<!-- ##### FUNCTION gst_autoplugfactory_destroy ##### -->
<para>
</para>
@factory: