Gst.Element – gstreamer-1.0 – Vala Binding Reference

Description:

[ CCode ( type_id = "gst_element_get_type ()" ) ]
public abstract class Element : Object

GstElement is the abstract base class needed to construct an element that can be used in a GStreamer pipeline.

Please refer to the plugin writers guide for more information on creating Element subclasses.

The name of a Element can be get with gst_element_get_name and set with gst_element_set_name. For speed, GST_ELEMENT_NAME can be used in the core when using the appropriate locking. Do not use this in plug-ins or applications in order to retain ABI compatibility.

Elements can have pads (of the type Pad). These pads link to pads on other elements. Buffer flow between these linked pads. A Element has a List of Pad structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with add_pad and remove_pad.

An existing pad of an element can be retrieved by name with get_static_pad. A new dynamic pad can be created using request_pad with a PadTemplate. An iterator of all pads can be retrieved with iterate_pads.

Elements can be linked through their pads. If the link is straightforward, use the link convenience function to link two elements, or link_many for more elements in a row. Use link_filtered to link two elements constrained by a specified set of Caps. For finer control, use gst_element_link_pads and link_pads_filtered to specify the pads to link on each element by name.

Each element has a state (see State). You can get and set the state of an element with get_state and set_state. Setting a state triggers a StateChange. To get a string representation of a State, use state_get_name.

You can get and set a Clock on an element using get_clock and set_clock. Some elements can provide a clock for the pipeline if the PROVIDE_CLOCK flag is set. With the provide_clock method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the REQUIRE_CLOCK() flag is set, a clock should be set on the element with set_clock.

Note that clock selection and distribution is normally handled by the toplevel Pipeline so the clock functions are only to be used in very specific situations.

Example: Dynamic pipelines:

// See http://docs.gstreamer.com/x/aAAF
// for a detailed description

public class Main {
	private Gst.Pipeline pipeline;
	private Gst.Element source;
	private Gst.Element convert;
	private Gst.Element sink;

	//
	// Handler for the pad-added signal.
	//
	// This function will be called by the pad-added signal.
	//
	private void pad_added_handler (Gst.Element src, Gst.Pad new_pad) {
		Gst.Pad sink_pad = this.convert.get_static_pad ("sink");
		print ("Received new pad '%s' from '%s':\n", new_pad.name, src.name);

		// If our converter is already linked, we have nothing to do here:
		if (sink_pad.is_linked ()) {
			print ("	We are already linked. Ignoring.\n");
			return ;
		}

		// Check the new pad's type:
		Gst.Caps new_pad_caps = new_pad.query_caps (null);
		weak Gst.Structure new_pad_struct = new_pad_caps.get_structure (0);
		string new_pad_type = new_pad_struct.get_name ();
		if (!new_pad_type.has_prefix ("audio/x-raw")) {
			print ("	It has type '%s' which is not raw audio. Ignoring.\n", new_pad_type);
			return ;
		}

		// Attempt the link:
		Gst.PadLinkReturn ret = new_pad.link (sink_pad);
		if (ret != Gst.PadLinkReturn.OK) {
			print ("	Type is '%s' but link failed.\n", new_pad_type);
		} else {
			print ("	Link succeeded (type '%s').\n", new_pad_type);
		}
	}

	//
	// Example runner
	//
	public int run () {
		// Create the elements:
		this.source = Gst.ElementFactory.make ("uridecodebin", "source");
		this.convert = Gst.ElementFactory.make ("audioconvert", "convert");
		this.sink = Gst.ElementFactory.make ("autoaudiosink", "sink");

		// Create the empty pipeline:
		this.pipeline = new Gst.Pipeline ("test-pipeline");

		if (this.pipeline == null || this.source == null || this.convert == null || this.sink == null) {
			print ("Not all elements could be created.\n");
			return -1;
		}

		// Build the pipeline. Note that we are NOT linking the source at this
		// point. We will do it later.

		this.pipeline.add_many (this.source, this.convert , this.sink);
		if (!this.convert.link (this.sink)) {
			print ("Elements could not be linked.\n");
			return -1;
		}

		// Set the URI to play:
		this.source.set ("uri", "http://docs.gstreamer.com/media/sintel_trailer-480p.webm");

		// Connect to the pad-added signal:
		this.source.pad_added.connect (pad_added_handler);

		// Start playing:
		Gst.StateChangeReturn ret = this.pipeline.set_state (Gst.State.PLAYING);
		if (ret == Gst.StateChangeReturn.FAILURE) {
			stderr.puts ("Unable to set the pipeline to the playing state.\n");
			return -1;
		}

		// Listen to the bus:
		Gst.Bus bus = this.pipeline.get_bus ();
		bool terminate = false;
		do {
			Gst.Message msg = bus.timed_pop_filtered (Gst.CLOCK_TIME_NONE,
				Gst.MessageType.STATE_CHANGED | Gst.MessageType.ERROR | Gst.MessageType.EOS);

			// Parse message:
			if (msg != null) {
				switch (msg.type) {
				case Gst.MessageType.ERROR:
					GLib.Error err;
					string debug_info;

					msg.parse_error (out err, out debug_info);
					stderr.printf ("Error received from element %s: %s\n", msg.src.name, err.message);
					stderr.printf ("Debugging information: %s\n", (debug_info != null)? debug_info : "none");
					terminate = true;
					break;

				case Gst.MessageType.EOS:
					print ("End-Of-Stream reached.\n");
					terminate = true;
					break;

				case Gst.MessageType.STATE_CHANGED:
					// We are only interested in state-changed messages from the pipeline:
					if (msg.src == this.pipeline) {
						Gst.State old_state;
						Gst.State new_state;
						Gst.State pending_state;

						msg.parse_state_changed (out old_state, out new_state, out pending_state);
						print ("Pipeline state changed from %s to %s:\n",
							Gst.Element.state_get_name (old_state),
							Gst.Element.state_get_name (new_state));
					}
					break;

				default:
					//We should not reach here:
					assert_not_reached ();
				}
			}
		} while (!terminate);

		// Free resources:
		bus = null;
		this.pipeline.set_state (Gst.State.NULL);
		this.pipeline = null;

		return 0;
	}

	public static int main (string[] args) {
		// Initialize GStreamer:
		Gst.init (ref args);

		// Run the example:
		return new Main ().run ();
	}
}

valac --pkg gstreamer-1.0 dynamic-pipelines.vala

All known sub-classes:

Pipeline

Namespace: Gst

Content:

Static methods:

public static Element make_from_uri (URIType type, string uri, string? elementname) throws Error

Creates an element for handling the given URI.

public static bool register (Plugin? plugin, string name, uint rank, Type type)

Create a new elementfactory capable of instantiating objects of the type and add the factory to plugin.

public static unowned string state_change_return_get_name (StateChangeReturn state_ret)

Gets a string representing the given state change result.

public static unowned string state_get_name (State state)

Gets a string representing the given state.

public static void type_set_skip_documentation (Type type)

Marks type as "documentation should be skipped".

Creation methods:

protected Element ()

Methods:

public void abort_state ()

Abort the state change of the element.

public class void add_metadata (string key, string value)

Set key with value as metadata in this.

public bool add_pad (Pad pad)

Adds a pad (link point) to this.

public class void add_pad_template (PadTemplate templ)

Adds a padtemplate to an element class.

public ulong add_property_deep_notify_watch (string? property_name, bool include_value)

public ulong add_property_notify_watch (string? property_name, bool include_value)

public class void add_static_metadata (string key, string value)

Set key with value as metadata in this.

public class void add_static_pad_template (StaticPadTemplate static_templ)

Adds a pad template to an element class based on the static pad template templ.

public class void add_static_pad_template_with_gtype (StaticPadTemplate static_templ, Type pad_type)

Adds a pad template to an element class based on the static pad template templ.

public void call_async (owned ElementCallAsyncFunc func)

Calls func from another thread and passes

user_data

to it.

public virtual StateChangeReturn change_state (StateChange transition)

Perform transition on this .

public class unowned string class_get_metadata (string key)

Get metadata with key in this .

public class unowned PadTemplate? class_get_pad_template (string name)

Retrieves a padtemplate from this with the given name.

public class unowned List<PadTemplate> class_get_pad_template_list ()

Retrieves a list of the pad templates associated with this.

public StateChangeReturn continue_state (StateChangeReturn ret)

Commit the state change of the element and proceed to the next pending state if any.

public void create_all_pads ()

Creates a pad for each pad template that is always available.

public bool foreach_pad (ElementForeachPadFunc func)

Call func with user_data for each of this's pads.

public bool foreach_sink_pad (ElementForeachPadFunc func)

Call func with user_data for each of this's sink pads.

public bool foreach_src_pad (ElementForeachPadFunc func)

Call func with user_data for each of this's source pads.

public ClockTime get_base_time ()

Returns the base time of the element.

public Bus? get_bus ()

Returns the bus of the element.

public Clock? get_clock ()

Gets the currently configured clock of the element.

public Pad? get_compatible_pad (Pad pad, Caps? caps)

Looks for an unlinked pad to which the given pad can link.

public unowned PadTemplate? get_compatible_pad_template (PadTemplate compattempl)

Retrieves a pad template from this that is compatible with compattempl.

public Context? get_context (string context_type)

Gets the context with context_type set on the element or NULL.

public Context? get_context_unlocked (string context_type)

Gets the context with context_type set on the element or NULL.

public List<Context> get_contexts ()

Gets the contexts set on the element.

public ClockTime get_current_clock_time ()

Returns the current clock time of the element, as in, the time of the element's clock, or GST_CLOCK_TIME_NONE if there is no clock.

public ClockTime get_current_running_time ()

Returns the running time of the element.

public unowned ElementFactory? get_factory ()

Retrieves the factory that was used to create this element.

public unowned string get_metadata (string key)

Get metadata with key in klass.

public unowned PadTemplate? get_pad_template (string name)

Retrieves a padtemplate from this with the given name.

public unowned List<PadTemplate> get_pad_template_list ()

Retrieves a list of the pad templates associated with this.

public Pad? get_request_pad (string name)

The name of this function is confusing to people learning GStreamer.

public ClockTime get_start_time ()

Returns the start time of the element.

public virtual StateChangeReturn get_state (out State state, out State pending, ClockTime timeout)

Gets the state of the element.

public Pad? get_static_pad (string name)

Retrieves a pad from this by name.

public bool is_locked_state ()

Checks if the state of an element is locked.

public Iterator iterate_pads ()

Retrieves an iterator of this's pads.

public Iterator iterate_sink_pads ()

Retrieves an iterator of this's sink pads.

public Iterator iterate_src_pads ()

Retrieves an iterator of this's source pads.

public bool link (Element dest)

Links this to dest.

public bool link_filtered (Element dest, Caps? filter)

Links this to dest using the given caps as filtercaps.

public bool link_many (Element[] elements)

Chain together a series of elements.

public bool link_pads (string? srcpadname, Element dest, string? destpadname, PadLinkCheck flags = DEFAULT)

Links the two named pads of the source and destination elements.

public bool link_pads_filtered (string? srcpadname, Element dest, string? destpadname, Caps? filter)

Links the two named pads of the source and destination elements.

public void lost_state ()

Brings the element to the lost state.

public void message_full (MessageType type, Quark domain, int code, owned string? text, owned string? debug, string file, string function, int line)

Post an error, warning or info message on the bus from inside an element.

public void message_full_with_details (MessageType type, Quark domain, int code, owned string? text, owned string? debug, string file, string function, int line, owned Structure structure)

Post an error, warning or info message on the bus from inside an element.

public virtual bool post_message (owned Message message)

Post a message on the element's Bus.

public virtual Clock? provide_clock ()

Get the clock provided by the given element.

public virtual bool query (Query query)

Performs a query on the given element.

public bool query_convert (Format src_format, int64 src_val, Format dest_format, out int64 dest_val)

Queries an element to convert src_val in

src_format

to dest_format.

public bool query_duration (Format format, out int64 duration)

Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds.

public bool query_position (Format format, out int64 cur)

Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds.

public virtual void release_pad (Pad pad)

public void release_request_pad (Pad pad)

Makes the element free the previously requested pad as obtained with request_pad.

public bool remove_pad (Pad pad)

Removes pad from this.

public void remove_property_notify_watch (ulong watch_id)

public virtual Pad? request_pad (PadTemplate templ, string? name, Caps? caps)

Retrieves a request pad from the element according to the provided template.

public Pad? request_pad_simple (string name)

Retrieves a pad from the element by name (e.g. "src_\%d").

public bool seek (double rate, Format format, SeekFlags flags, SeekType start_type, int64 start, SeekType stop_type, int64 stop)

Sends a seek event to an element.

public bool seek_simple (Format format, SeekFlags seek_flags, int64 seek_pos)

Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream.

public virtual bool send_event (owned Event event)

Sends an event to an element.

public void set_base_time (ClockTime time)

Set the base time of an element.

public virtual void set_bus (Bus? bus)

Sets the bus of the element.

public virtual bool set_clock (Clock? clock)

Sets the clock for the element.

public virtual void set_context (Context context)

Sets the context of the element.

public bool set_locked_state (bool locked_state)

Locks the state of an element, so state changes of the parent don't affect this element anymore.

public class void set_metadata (string longname, string classification, string description, string author)

Sets the detailed information for a Element.

public void set_start_time (ClockTime time)

Set the start time of an element.

public virtual StateChangeReturn set_state (State state)

Sets the state of the element.

public class void set_static_metadata (string longname, string classification, string description, string author)

Sets the detailed information for a Element.

public virtual void state_changed (State oldstate, State newstate, State pending)

public bool sync_state_with_parent ()

Tries to change the state of the element to the same as its parent.

public void unlink (Element dest)

Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked.

public void unlink_many (Element[] elements)

Unlinks a series of elements.

public void unlink_pads (string srcpadname, Element dest, string destpadname)

Unlinks the two named pads of the source and destination elements.

Signals:

public virtual signal void no_more_pads ()

This signals that the element will not generate more dynamic pads.

public virtual signal void pad_added (Pad pad)

a new Pad has been added to the element.

public virtual signal void pad_removed (Pad pad)

a Pad has been removed from the element

Fields:

Inherited Members:

All known members inherited from class GLib.Object

@get
@new
@ref
@set
add_toggle_ref
add_weak_pointer
bind_property
connect
constructed
disconnect
dispose
dup_data
dup_qdata
force_floating
freeze_notify
get_class
get_data

get_property
get_qdata
get_type
getv
interface_find_property
interface_install_property
interface_list_properties
is_floating
new_valist
new_with_properties
newv
notify
notify_property
ref_count
ref_sink
remove_toggle_ref
remove_weak_pointer

replace_data
replace_qdata
set_data
set_data_full
set_property
set_qdata
set_qdata_full
set_valist
setv
steal_data
steal_qdata
thaw_notify
unref
watch_closure
weak_ref
weak_unref

Element

Object Hierarchy: