QStreamer::QElement Class Reference

#include <qelement.h>

Inheritance diagram for QStreamer::QElement:

List of all members.

Public Member Functions
virtual	~QElement ()
class QPipeline *	pipeline ()
class QPipeline *	pipeline () const
const QString &	name () const
	Returns the name of the element.
QElement *	parent ()
	Returns the parent element if this element belongs to another element.
const QElement *	parent () const
	Returns the parent element if this element belongs to another element.
class QMediaError &	error ()
	Returns a handle to the output path element should use if reporting errors.
QElementList &	children ()
	Returns the child element list.
const QElementList &	children () const
	Returns the child element list.
const QPinList &	pins () const
	Returns the pin list for the element.
class QMediaClock *	clock ()
void	setClock (class QMediaClock *clock)
bool	connectSourceTo (QElement *destinationElement, const QString &destinationPinName="sink")
	Overloaded function to connect the pin named "src" on this element to the given pin on the given destination element.
bool	connectSourceTo (const QString &sourcePinName, QElement *destinationElement, const QString &destinationPinName="sink")
class QSourcePin *	sourcePin (const QString &name)
class QSinkPin *	sinkPin (const QString &name)
Protected Member Functions
	QElement (const QString &name, class QPipeline *parent)
	QElement (const QString &name, QElement *parent)
bool	addChild (QElement *child)
bool	removeChild (QElement *child)
bool	addPin (QPin *pin)
bool	removePin (QPin *pin)
QPinList &	pins ()
	Returns the pinlist of this element.
class QSourcePin *	constructSourcePin (const QString &name)
void	deleteSourcePin (class QSourcePin *pin)
void	setParentElement (QElement *parent)

---

Detailed Description

Defines the basic component for sourcing, sinking or transforming media within a media pipeline.

And element is a unit which contains one basic object. There are three basic types of elements of which each type can typically be expanded upon for special requirements.

• A Source element is an element which provides media to the pipeline. This can typically be a file source, a video camera or a live media stream such as a multicast RTP session.
• A transform element is an element which performs some sort of transformation on the data which it is provided. A basic transform element could for example be a video decompressor that translates from compressed media to uncompressed media.
• A sink element provides a destination for media such as a sound output, a wave file output, or a video context on the screen.

Elements provide a somewhat sealed environment as they are meant to me analagous to electronic components connected together with wires. Standard inband data between elements occurs through "connected" "pins". Elements can contain source pins, sink pins or both.

A source pin is a pin which is used for output from an element. The naming of the pin suggests that it is a data source to elements later in the pipeline (or "downstream").

A sink pin is a pin which when connected to a source pin is how an element receives incoming data to be processed or displayed.

Downstream elements are responsible for allocating memory for upstream elements through calls made to the allocateBuffer() function on their pins. This is done like this to decrease the amount of memory allocations made by the pipeline. In the case of a video sink where there might be a "presentation buffer", a "fill buffer", and a "back buffer". Only 3 frames of video need to be preallocated, so when video codec's request a new frame allocation, the video sink will be responsible for providing one of its preallocated buffers which displaying the other two.

Out of band data can also be passed over pins either directly through calls to the pins' "postEvent" methods or through the elements' post event method which broadcasts events upstream and/or downstream through all pin connections. There is also a means of broadcasting an out-of-band event to all elements of the pipeline via the postEvent() call on the pipeline itself.

Asynchronous messages from the pipeline providing non-critical information occur through signals emitted from the QPipeline class. Elements are not QObjects and therefore do not have signals. Therefore they call postMessage from within the element to the pipeline to queue messages to be passed via signals.

---

Constructor & Destructor Documentation

QStreamer::QElement::~QElement

(

)

[virtual]

Destructor

Note:

The pipeline is designed to tear itself down. While it should be safe to delete elements directly, in the case of cleanup, it is better to let the pipeline delete its elements.

QStreamer::QElement::QElement	(	const QString &	name,
		class QPipeline *	parent
	)		[protected]

Constructor

Note:

this constructor registers itself with the parent defined.

Parameters:

name	the name of this element for debugging and informative reasons.
parent	the parent pipeline which this pin should directly belong to.

QStreamer::QElement::QElement	(	const QString &	name,
		QElement *	parent
	)		[protected]

Constructor

Note:

this constructor registers itself with the parent defined.

Parameters:

name	the name of this element for debugging and informative reasons.
parent	the parent element which this pin should directly belong to.

---

Member Function Documentation

bool QStreamer::QElement::addChild

(

QElement *

child )

[protected]

Adds a child element to this element. This action simulates "binning".

Parameters:

child

the child element to add

Returns:

true on success, false if the element is already in the list or already belongs to another element.

bool QStreamer::QElement::addPin

(

QPin *

pin )

[protected]

Register a pin with the element.

This registration is not only for tracking pins, but is also used for broadcasting pipeline events and passing queries up and down stream.

Parameters:

pin	the pin to add to the element

Returns:

true on success, false if the pin is already owned by another element or another pin of the same name already exists/

QElementList & QStreamer::QElement::children

(

)

Returns the child element list.

const QElementList & QStreamer::QElement::children

(

)

const

Returns the child element list.

class QMediaClock * QStreamer::QElement::clock

(

)

Returns the clock configured for this element.

By default an element will inherit the clock of its owner and provide its clock to elements which it owns. However, a clock can be assigned directly to an element which is useful for circumstances such as media synchronization. (like syncing audio with video based on the audio clock as opposed to the system clock).

Returns:

the media clock used by this element.

bool QStreamer::QElement::connectSourceTo	(	QElement *	destinationElement,
		const QString &	destinationPinName = "sink"
	)

Overloaded function to connect the pin named "src" on this element to the given pin on the given destination element.

bool QStreamer::QElement::connectSourceTo	(	const QString &	sourcePinName,
		QElement *	destinationElement,
		const QString &	destinationPinName = "sink"
	)

Connects the pin with the given source name from this element to the given QSinkPin on the given destination element.

The connection produced by this call allows buffers, events and queries to be passed from this element to the given element via the path defined by this connection.

Parameters:

sourcePinName	the name of the source pin on this element.
destinationElement	the element containing the destination QSinkPin
destinationPinName	the name of the pin on the destination element to connect to.

Returns:

true on success. False if this pin or the sink pin either don't exist or are already connected to something else.

QSourcePin * QStreamer::QElement::constructSourcePin

(

const QString &

name )

[protected]

Helper function to construct and register a source pin by the given name to this element.

Parameters:

name	the name to give the pin.

Returns:

a pointer to the new pin or 0 if there was an error constructing or adding the pin.

void QStreamer::QElement::deleteSourcePin

(

class QSourcePin *

pin )

[protected]

Helper function to deregister and delete a source pin from the element.

Parameters:

pin	the pin to deregister and delete.

class QMediaError & QStreamer::QElement::error

(

)

Returns a handle to the output path element should use if reporting errors.

const QString & QStreamer::QElement::name

(

)

const [inline]

Returns the name of the element.

QElement * QStreamer::QElement::parent

(

)

[inline]

Returns the parent element if this element belongs to another element.

const QElement * QStreamer::QElement::parent

(

)

const [inline]

Returns the parent element if this element belongs to another element.

const QPinList & QStreamer::QElement::pins

(

)

const

Returns the pin list for the element.

QPinList & QStreamer::QElement::pins

(

)

[protected]

Returns the pinlist of this element.

class QPipeline * QStreamer::QElement::pipeline

(

)

const [inline]

Returns the pipeline instance which the element belongs to.

Returns:

the pipeline instance or null of the element is not yet a member of a pipeline.

class QPipeline * QStreamer::QElement::pipeline

(

)

[inline]

Returns the pipeline instance which the element belongs to.

Returns:

the pipeline instance or null of the element is not yet a member of a pipeline.

bool QStreamer::QElement::removeChild

(

QElement *

child )

[protected]

Removes a child element from this element.

Parameters:

child

the child element to remove from the list.

Returns:

true on success, false if the child element could not be found to be removed.

bool QStreamer::QElement::removePin

(

QPin *

pin )

[protected]

Deregisters a pin from the element

Parameters:

pin	the pin to deregister

Returns:

true on success, false if this element didn't actually own the pin.

void QStreamer::QElement::setClock

(

class QMediaClock *

clock )

Configures the clock to use for synchronization.

Parameters:

clock

either an instance of a QMediaClock or 0 to signify that the element should inherit its' owner's clock.

void QStreamer::QElement::setParentElement

(

QElement *

parent )

[protected]

Sets the parent element

Note:

this function is not meant to be called from outside of the removeChild function as it is meant to remove reference to the parent to make pipeline teardown cleaner.

QSinkPin * QStreamer::QElement::sinkPin

(

const QString &

name )

Returns the sink pin with the given name.

Returns:

either the pointer to the requested sink pin or 0 if it could not be found.

QSourcePin * QStreamer::QElement::sourcePin

(

const QString &

name )

Returns the source pin with the given name.

Returns:

either the pointer to the requested source pin or 0 if it could not be found.

---

The documentation for this class was generated from the following files:

• QStreamer/include/qelement.h
• QStreamer/source/qelement.cpp