Skip to content

Latest commit

 

History

History
902 lines (576 loc) · 24 KB

api-gst.md

File metadata and controls

902 lines (576 loc) · 24 KB
Raw

GStreamer (GST) Element API Reference

The GST API is used to create Custom GStreamer (GST) Elements. Once created, GST Elements can be added to either a Custom Source Custom Component, or Custom Sink).

There are restrictions imposed on the type of Elements that can be added to one of the Custom Types. The Element must have at most a single static sink (input) pad and at most a single static source (output) pad. Therefore, no tees, muxers, aggregators, or demuxers (this list may not be complete).

The first element added to a Custom Source

  • Must be a Source element and without a sink pad.

The last element added to a Custom Sink

  • must be a Sink element and without a source pad.

Element Construction and Destruction

GST Elements are created by calling dsl_gst_element_new and deleted by calling dsl_gst_element_delete, dsl_gst_element_delete_many, or dsl_gst_element_delete_all.

Element Properties

Elements have properties that define and control there behavior. DSL provides services to read and write properties of type:

  • boolean
  • float
  • int
  • uint
  • int64
  • uint64
  • string
  • caps

All elements have at least one property which is the name property of type string.

GST Caps Objects

GStreamer Caps Objects define media types and are used to query and set Element properties of type caps. GST Caps Objects are created by calling dsl_gst_caps_new and deleted by calling dsl_gst_caps_delete, dsl_gst_caps_delete_many, or dsl_gst_caps_delete_all.

Using Python for example.

# Create the new Caps Object from a string representation of the desired caps.
retval = dsl_gst_caps_new('my-video-caps',
  'video/x-raw, framerate=15/1, width=1280, height=720')


# Set the Element's caps property used the Caps Object  
retval = dsl_gst_element_property_caps_set('my-element',
  'caps', 'my-caps-object')


# Delete the Caps Object when done.
retval = dsl_gst_caps_delele('my-caps-object')

Adding/Removing Pad-Probe-handlers

Multiple sink (input) and/or source (output) Pad-Probe Handlers can be added to any Element by calling dsl_gst_element_pph_add and removed with dsl_gst_element_pph_remove.

GST API

Constructors

Destructors

Caps Object Methods

Element Methods

Return Values

The following return codes are used by the GStreamer Element API

#define DSL_RESULT_GST_ELEMENT_RESULT                               0x00D00000
#define DSL_RESULT_GST_ELEMENT_NAME_NOT_UNIQUE                      0x00D00001
#define DSL_RESULT_GST_ELEMENT_NAME_NOT_FOUND                       0x00D00002
#define DSL_RESULT_GST_ELEMENT_THREW_EXCEPTION                      0x00D00003
#define DSL_RESULT_GST_ELEMENT_IN_USE                               0x00D00004
#define DSL_RESULT_GST_ELEMENT_SET_FAILED                           0x00D00005
#define DSL_RESULT_GST_ELEMENT_HANDLER_ADD_FAILED                   0x00D00006
#define DSL_RESULT_GST_ELEMENT_HANDLER_REMOVE_FAILED                0x00D00007
#define DSL_RESULT_GST_ELEMENT_PAD_TYPE_INVALID                     0x00D00008

Constructors

dsl_gst_caps_new

DslReturnType dsl_gst_caps_new(const wchar_t* name, const wchar_t* caps);

This constructor creates a uniquely named GST Caps Object from a string representation..

Parameters

  • name - [in] unique name for the GStreamer Caps Object to create.
  • caps - [in] a string defining the caps to create.

Returns DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_caps_new('my-video-caps',
  'video/x-raw, framerate=15/1, width=1280, height=720')

dsl_gst_element_new

DslReturnType dsl_gst_element_new(const wchar_t* name, const wchar_t* factory_name);

This constructor creates a uniquely named GStreamer Element from a plugin factory name. Construction will fail if the name is currently in use.

Parameters

  • name - [in] unique name for the GStreamer Element to create.
  • factory_name - [in] factory (plugin) name for the Element to create.

Returns DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_element_new('my-element', 'my-plugin)

Destructors

dsl_gst_caps_delete

DslReturnType dsl_gst_caps_delete(const wchar_t* name);

This destructor deletes a uniquely named GST Caps Object.

Parameters

  • name - [in] unique name of the GST Caps Object to delete.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_caps_delete('my-video-caps')

dsl_gst_caps_delete_many

DslReturnType dsl_gst_caps_delete_many(const wchar_t** names);

This destructor deletes a NULL terminated list of GST Caps Objects. This service will return with an error if any of the Caps Objects are currently not found.

Parameters

  • names - [in] NULL terminated list of GStreamer Elements to delete.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_caps_delete_many('my-caps-1',
  'my-caps-2', 'my-caps-3', None)

dsl_gst_caps_delete_all

DslReturnType dsl_gst_caps_delete_all();

This destructor deletes all GST Caps Objects in memory.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_caps_delete_all()

dsl_gst_element_delete

DslReturnType dsl_gst_element_delete(const wchar_t* name);

This destructor deletes a uniquely named GST Element. This service will fail if the Element is currently in-use .

Parameters

  • name - [in] unique name for the GST Element to delete.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_element_delete('my-element')

dsl_gst_element_delete_many

DslReturnType dsl_gst_element_delete_many(const wchar_t** names);

This destructor deletes a NULL terminated list of GST Elements. This service will return with an error if any of the Elements are currently in-use or not found.

Parameters

  • names - [in] NULL terminated list of GST Elements to delete.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_element_delete_many('my-element-1',
  'my-element-2', 'my-element-3', None)

dsl_gst_element_delete_all

DslReturnType dsl_gst_element_delete_all();

This destructor deletes all GST Elements in memory. This service will return with an error if any of the Elements are currently in-use.

Returns DSL_RESULT_SUCCESS on successful deletion. One of the Return Values defined above on failure

Python Example

retval = dsl_gst_element_delete_all()

Caps Object Methods

dsl_gst_caps_string_get

DslReturnType dsl_gst_caps_string_get(const wchar_t* name, const wchar_t** caps);

This service queries a uniquely named GST Caps Object for its current caps in string format.

Parameters

  • name - [in] unique name for the Caps Object to query.
  • caps - [out] a string representation of the Caps Object's current caps.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, caps = dsl_gst_caps_string_get('my-caps-object')

Element Methods

dsl_gst_element_property_boolean_get

DslReturnType dsl_gst_element_property_boolean_get(const wchar_t* name,
  const wchar_t* property, boolean* value);

This service gets a named boolean property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_boolean_get('my-element',
  'some-boolean-property')

dsl_gst_element_property_boolean_set

DslReturnType dsl_gst_element_property_boolean_set(const wchar_t* name,
  const wchar_t* property, boolean value);

This service sets a named boolean property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_boolean_set('my-element',
  'some-boolean-property', True)

dsl_gst_element_property_float_get

DslReturnType dsl_gst_element_property_float_get(const wchar_t* name,
  const wchar_t* property, float* value);

This service gets a named float property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_float_get('my-element',
  'some-float-property')

dsl_gst_element_property_float_set

DslReturnType dsl_gst_element_property_float_set(const wchar_t* name,
  const wchar_t* property, float value);

This service sets a named float property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_float_set('my-element',
  'some-float-property', 0.99)

dsl_gst_element_property_uint_get

DslReturnType dsl_gst_element_property_uint_get(const wchar_t* name,
  const wchar_t* property, uint* value);

This service gets a named unsigned integer property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_uint_get('my-element',
  'some-uint-property')

dsl_gst_element_property_uint_set

DslReturnType dsl_gst_element_property_uint_set(const wchar_t* name,
  const wchar_t* property, uint value);

This service sets a named unsigned integer property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_uint_set('my-element',
  'some-uint-property', 1234)

dsl_gst_element_property_int_get

DslReturnType dsl_gst_element_property_int_get(const wchar_t* name,
  const wchar_t* property, int* value);

This service gets a named signed integer property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_int_get('my-element',
  'some-int-property')

dsl_gst_element_property_int_set

DslReturnType dsl_gst_element_property_int_set(const wchar_t* name,
  const wchar_t* property, int value);

This service sets a named signed integer property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_int_set('my-element',
  'some-int-property', 1234)

dsl_gst_element_property_uint64_get

DslReturnType dsl_gst_element_property_uint64_get(const wchar_t* name,
  const wchar_t* property, uint64_t* value);

This service gets a named 64 bit unsigned integer property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_uint64_get('my-element',
  'some-uint64-property')

dsl_gst_element_property_uint64_set

DslReturnType dsl_gst_element_property_uint64_set(const wchar_t* name,
  const wchar_t* property, uint64_t value);

This service sets a named 64 bit unsigned integer property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_uint64_set('my-element',
  'some-uint64-property', 0x0123456789abcdef)

dsl_gst_element_property_int64_get

DslReturnType dsl_gst_element_property_int64_get(const wchar_t* name,
  const wchar_t* property, int64_t* value);

This service gets a named 64 bit signed integer property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_int64_get('my-element',
  'some-int64-property')

dsl_gst_element_property_int64_set

DslReturnType dsl_gst_element_property_int64_set(const wchar_t* name,
  const wchar_t* property, int64_t value);

This service sets a named 64 bit signed integer property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_int64_set('my-element',
  'some-int64-property', 0x0123456789abcdef)

dsl_gst_element_property_string_get

DslReturnType dsl_gst_element_property_string_get(const wchar_t* name,
  const wchar_t* property, const wchar_t** value);

This service gets a named string property from a named Element.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query.
  • value - [out] current value for the named property.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, value = dsl_gst_element_property_string_get('my-element',
  'some-string-property')

dsl_gst_element_property_string_set

DslReturnType dsl_gst_element_property_string_set(const wchar_t* name,
  const wchar_t* property, const wchar_t* value);

This service sets a named string property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update.
  • value - [in] new value for the named property.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_property_string_set('my-element',
  'some-string-property', 'some-string-value')

dsl_gst_element_property_caps_get

DslReturnType dsl_gst_element_property_caps_get(const wchar_t* name,
   const wchar_t* property, const wchar_t* caps);

This service creates a named GST Caps Object from a named Element's property of type caps. After the call, the new Caps Object can be queried for its string representation by calling dsl_gst_caps_string_get.

Parameters

  • name - [in] unique name for the Element to query.
  • property - [in] unique name of the property to query, typically "caps".
  • caps - [out] unique name for the Caps Object to create.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

# Create the new GST Caps object from the element's 'caps' property
retval = dsl_gst_element_property_caps_get('my-element', 'caps', 'new-caps-object')


# Read the caps string from the Caps Object.
retval, caps = dsl_gst_caps_string_get('new-caps-object')


# Delete the Caps Object when done.
retval = dsl_gst_caps_delele('new-caps-object')

dsl_gst_element_property_caps_set

DslReturnType dsl_gst_element_property_caps_set(const wchar_t* name,
   const wchar_t* property, const wchar_t* caps);

This service sets a named string property for a named Element.

Parameters

  • name - [in] unique name for the Element to update.
  • property - [in] unique name of the property to update, typically "caps".
  • value - [in] unique name of the Caps Object to use.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

# Create the new Caps Object from a string representation of the desired caps.
retval = dsl_gst_caps_new('my-video-caps',
  'video/x-raw, framerate=15/1, width=1280, height=720')


# Set the Element's caps property used the Caps Object  
retval = dsl_gst_element_property_caps_set('my-element',
  'caps', 'my-caps-object')


# Delete the Caps Object when done.
retval = dsl_gst_caps_delele('my-caps-object')

dsl_gst_element_pph_add

DslReturnType dsl_gst_element_pph_add(const wchar_t* name,
  const wchar_t* handler, uint pad);

This service adds a Pad Probe Handler to either the Sink or Source pad of the named Element.

Parameters

  • name - [in] unique name of the Element to update.
  • handler - [in] unique name of Pad Probe Handler to add.
  • pad - [in] which of the two pads to add the handler to: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_pph_add('my-element', 'my-pph-handler', DSL_PAD_SINK)

dsl_gst_element_pph_remove

DslReturnType dsl_gst_element_pph_remove(const wchar_t* name,
  const wchar_t* handler, uint pad);

This service removes a Pad Probe Handler from either the Sink or Source pad of the named GST Element. This service will fail if the named handler is not owned by the Inference Component

Parameters

  • name - [in] unique name of the Element to update.
  • handler - [in] unique name of Pad Probe Handler to remove
  • pad - [in] to which of the two pads to remove the handler from: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_gst_element_pph_remove('my-element', 'my-pph-handler', DSL_PAD_SINK)

API Reference