GstControllerGObject

## GstControllerGObject GstControllerGObject — GObject convenience methods for using dynamic properties |

## Synopsis

    #include <libs/controller/gstcontroller.h>

    GstController *     gst_object_control_properties       (GObject *object,
                                                             ...);
    gboolean            gst_object_uncontrol_properties     (GObject *object,
                                                             ...);
    GstController *     gst_object_get_controller           (GObject *object);
    gboolean            gst_object_set_controller           (GObject *object,
                                                             GstController *controller);
    GstClockTime        gst_object_suggest_next_sync        (GObject *object);
    gboolean            gst_object_sync_values              (GObject *object,
                                                             GstClockTime timestamp);
    GstControlSource *  gst_object_get_control_source       (GObject *object,
                                                             const gchar *property_name);
    gboolean            gst_object_set_control_source       (GObject *object,
                                                             const gchar *property_name,
                                                             GstControlSource *csource);
    gboolean            gst_object_get_value_arrays         (GObject *object,
                                                             GstClockTime timestamp,
                                                             GSList *value_arrays);
    gboolean            gst_object_get_value_array          (GObject *object,
                                                             GstClockTime timestamp,
                                                             GstValueArray *value_array);
    GstClockTime        gst_object_get_control_rate         (GObject *object);
    void                gst_object_set_control_rate         (GObject *object,
                                                             GstClockTime control_rate);

## Description

These methods allow to use some GstController functionality directly from the GObject class.

## Details

### gst_object_control_properties ()

    GstController *     gst_object_control_properties       (GObject *object,
                                                             ...);

Convenience function for GObject

Creates a GstController that allows you to dynamically control one, or more, GObject properties. If the given GObject already has a GstController, it adds the given properties to the existing controller and returns that controller.

`object` : | the object of which some properties should be controlled
`...` : | `NULL` terminated list of property names that should be controlled
Returns : | The GstController with which the user can control the given properties dynamically or NULL if one or more of the given properties aren't available, or cannot be controlled, for the given element.

Since 0.9

### gst_object_uncontrol_properties ()

    gboolean            gst_object_uncontrol_properties     (GObject *object,
                                                             ...);

Convenience function for GObject

Removes the given element's properties from it's controller

`object` : | the object of which some properties should not be controlled anymore
`...` : | `NULL` terminated list of property names that should be controlled
Returns : | `FALSE` if one of the given property names isn't handled by the controller, `TRUE` otherwise

Since 0.9

### gst_object_get_controller ()

    GstController *     gst_object_get_controller           (GObject *object);

Gets the controller for the given GObject

`object` : | the object that has controlled properties
Returns : | the controller handling some of the given element's properties, `NULL` if no controller

Since 0.9

### gst_object_set_controller ()

    gboolean            gst_object_set_controller           (GObject *object,
                                                             GstController *controller);

Sets the controller on the given GObject

`object` : | the object that should get the controller
`controller` : | the controller object to plug in
Returns : | `FALSE` if the GObject already has an controller, `TRUE` otherwise

Since 0.9

### gst_object_suggest_next_sync ()

    GstClockTime        gst_object_suggest_next_sync        (GObject *object);

Convenience function for GObject

`object` : | the object that has controlled properties
Returns : | same thing as `gst_controller_suggest_next_sync()`

Since 0.10.13

### gst_object_sync_values ()

    gboolean            gst_object_sync_values              (GObject *object,
                                                             GstClockTime timestamp);

Convenience function for GObject

`object` : | the object that has controlled properties
`timestamp` : | the time that should be processed
Returns : | same thing as `gst_controller_sync_values()`

Since 0.9

### gst_object_get_control_source ()

    GstControlSource *  gst_object_get_control_source       (GObject *object,
                                                             const gchar *property_name);

Gets the corresponding GstControlSource for the property. This should be unreferenced again after use.

`object` : | the object
`property_name` : | name of the property for which the GstControlSource should be get
Returns : | the GstControlSource for `property_name` or NULL if the property is not controlled by this controller or no GstControlSource was assigned yet.

Since 0.10.14

### gst_object_set_control_source ()

    gboolean            gst_object_set_control_source       (GObject *object,
                                                             const gchar *property_name,
                                                             GstControlSource *csource);

Sets the GstControlSource for `property_name`. If there already was a GstControlSource for this property it will be unreferenced.

`object` : | the controller object
`property_name` : | name of the property for which the GstControlSource should be set
`csource` : | the GstControlSource that should be used for the property
Returns : | `FALSE` if the given property isn't handled by the controller or the new GstControlSource couldn't be bound to the property, `TRUE` if everything worked as expected.

Since 0.10.14

### gst_object_get_value_arrays ()

    gboolean            gst_object_get_value_arrays         (GObject *object,
                                                             GstClockTime timestamp,
                                                             GSList *value_arrays);

Function to be able to get an array of values for one or more given element properties.

If the GstValueArray->values array in list nodes is NULL, it will be created by the function. The type of the values in the array are the same as the property's type.

The g_object_* functions are just convenience functions for GObject

`object` : | the object that has controlled properties
`timestamp` : | the time that should be processed
`value_arrays` : | list to return the control-values in
Returns : | `TRUE` if the given array(s) could be filled, `FALSE` otherwise

Since 0.9

### gst_object_get_value_array ()

    gboolean            gst_object_get_value_array          (GObject *object,
                                                             GstClockTime timestamp,
                                                             GstValueArray *value_array);

Function to be able to get an array of values for one element properties

If the GstValueArray->values array is NULL, it will be created by the function. The type of the values in the array are the same as the property's type.

The g_object_* functions are just convenience functions for GObject

`object` : | the object that has controlled properties
`timestamp` : | the time that should be processed
`value_array` : | array to put control-values in
Returns : | `TRUE` if the given array(s) could be filled, `FALSE` otherwise

Since 0.9

### gst_object_get_control_rate ()

    GstClockTime        gst_object_get_control_rate         (GObject *object);

Obtain the control-rate for this `object`. Audio processing GstElement objects will use this rate to sub-divide their processing loop and call `gst_object_sync_values()` inbetween. The length of the processing segment should be up to `control`-rate nanoseconds.

If the `object` is not under property control, this will return `GST_CLOCK_TIME_NONE`. This allows the element to avoid the sub-dividing.

The control-rate is not expected to change if the element is in `GST_STATE_PAUSED` or `GST_STATE_PLAYING`.

`object` : | the object that has controlled properties
Returns : | the control rate in nanoseconds

Since 0.10.10

### gst_object_set_control_rate ()

    void                gst_object_set_control_rate         (GObject *object,
                                                             GstClockTime control_rate);

Change the control-rate for this `object`. Audio processing GstElement objects will use this rate to sub-divide their processing loop and call `gst_object_sync_values()` inbetween. The length of the processing segment should be up to `control`-rate nanoseconds.

The control-rate should not change if the element is in `GST_STATE_PAUSED` or `GST_STATE_PLAYING`.

`object` : | the object that has controlled properties
`control_rate` : | the new control-rate in nanoseconds.

Since 0.10.10

## See Also

GstController