GESBaseEffect

A GESBaseEffect is some operation that applies an effect to the data it receives.

Time Effects

Some operations will change the timing of the stream data they receive in some way. In particular, the GstElement that they wrap could alter the times of the segment they receive in a GST_EVENT_SEGMENT event, or the times of a seek they receive in a GST_EVENT_SEEK event. Such operations would be considered time effects since they translate the times they receive on their source to different times at their sink, and vis versa. This introduces two sets of time coordinates for the event: (internal) sink coordinates and (internal) source coordinates, where segment times are translated from the sink coordinates to the source coordinates, and seek times are translated from the source coordinates to the sink coordinates.

If you use such an effect in GES, you will need to inform GES of the properties that control the timing with ges_base_effect_register_time_property, and the effect's timing behaviour using ges_base_effect_set_time_translation_funcs.

Note that a time effect should not have its has-internal-source set to TRUE.

In addition, note that GES only fully supports time effects whose mapping from the source to sink coordinates (those applied to seeks) obeys:

  • Maps the time 0 to 0. So initial time-shifting effects are excluded.
  • Is monotonically increasing. So reversing effects, and effects that jump backwards in the stream are excluded.
  • Can handle a reasonable GstClockTime, relative to the project. So this would exclude a time effect with an extremely large speed-up that would cause the converted GstClockTime seeks to overflow.
  • Is 'continuously reversible'. This essentially means that for every time in the sink coordinates, we can, to 'good enough' accuracy, calculate the corresponding time in the source coordinates. Moreover, this should correspond to how segment times are translated from sink to source.
  • Only depends on the registered time properties, rather than the state of the GstElement or the data it receives. This would exclude, say, an effect that would speedup if there is more red in the image it receives.

Note that a constant-rate-change effect that is not extremely fast or slow would satisfy these conditions. For such effects, you may wish to use ges_effect_class_register_rate_property.

GESBaseEffect 

GObject
    ╰──GInitiallyUnowned
        ╰──GESTimelineElement
            ╰──GESTrackElement
                ╰──GESOperation
                    ╰──GESBaseEffect
                        ╰──GESEffect

Class structure

GESBaseEffectClass

GES.BaseEffectClass

GES.BaseEffectClass

GES.BaseEffect 

GObject.Object
    ╰──GObject.InitiallyUnowned
        ╰──GES.TimelineElement
            ╰──GES.TrackElement
                ╰──GES.Operation
                    ╰──GES.BaseEffect
                        ╰──GES.Effect

GES.BaseEffect 

GObject.Object
    ╰──GObject.InitiallyUnowned
        ╰──GES.TimelineElement
            ╰──GES.TrackElement
                ╰──GES.Operation
                    ╰──GES.BaseEffect
                        ╰──GES.Effect

Methods

ges_base_effect_is_time_effect 

gboolean
ges_base_effect_is_time_effect (GESBaseEffect * effect)

Get whether the effect is considered a time effect or not. An effect with registered time properties or set translation functions is considered a time effect.

Parameters:

effect –

A GESBaseEffect

Returns –

TRUE if effect is considered a time effect.

Since : 1.18

GES.BaseEffect.prototype.is_time_effect 

function GES.BaseEffect.prototype.is_time_effect(): {
    // javascript wrapper for 'ges_base_effect_is_time_effect'
}

Get whether the effect is considered a time effect or not. An effect with registered time properties or set translation functions is considered a time effect.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

Returns (Number) –

true if effect is considered a time effect.

Since : 1.18

GES.BaseEffect.is_time_effect 

def GES.BaseEffect.is_time_effect (self):
    #python wrapper for 'ges_base_effect_is_time_effect'

Get whether the effect is considered a time effect or not. An effect with registered time properties or set translation functions is considered a time effect.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

Returns (bool) –

True if effect is considered a time effect.

Since : 1.18

ges_base_effect_register_time_property 

gboolean
ges_base_effect_register_time_property (GESBaseEffect * effect,
                                        const gchar * child_property_name)

Register a child property of the effect as a property that, when set, can change the timing of its input data. The child property should be specified as in ges_timeline_element_lookup_child.

You should also set the corresponding time translation using ges_base_effect_set_time_translation_funcs.

Note that effect must not be part of a clip, nor can it have has-internal-source set to TRUE.

Parameters:

effect –

A GESBaseEffect

child_property_name –

The name of the child property to register as a time property

Returns –

TRUE if the child property was found and newly registered.

Since : 1.18

GES.BaseEffect.prototype.register_time_property 

function GES.BaseEffect.prototype.register_time_property(child_property_name: String): {
    // javascript wrapper for 'ges_base_effect_register_time_property'
}

Register a child property of the effect as a property that, when set, can change the timing of its input data. The child property should be specified as in GES.TimelineElement.prototype.lookup_child.

You should also set the corresponding time translation using GES.BaseEffect.prototype.set_time_translation_funcs.

Note that effect must not be part of a clip, nor can it have has-internal-source set to true.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

child_property_name (String) –

The name of the child property to register as a time property

Returns (Number) –

true if the child property was found and newly registered.

Since : 1.18

GES.BaseEffect.register_time_property 

def GES.BaseEffect.register_time_property (self, child_property_name):
    #python wrapper for 'ges_base_effect_register_time_property'

Register a child property of the effect as a property that, when set, can change the timing of its input data. The child property should be specified as in GES.TimelineElement.lookup_child.

You should also set the corresponding time translation using GES.BaseEffect.set_time_translation_funcs.

Note that effect must not be part of a clip, nor can it have has_internal_source set to True.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

child_property_name (str) –

The name of the child property to register as a time property

Returns (bool) –

True if the child property was found and newly registered.

Since : 1.18

ges_base_effect_set_time_translation_funcs 

gboolean
ges_base_effect_set_time_translation_funcs (GESBaseEffect * effect,
                                            GESBaseEffectTimeTranslationFunc source_to_sink_func,
                                            GESBaseEffectTimeTranslationFunc sink_to_source_func,
                                            gpointer user_data,
                                            GDestroyNotify destroy)

Set the time translation query functions for the time effect. If an effect is a time effect, it will have two sets of coordinates: one at its sink and one at its source. The given functions should be able to translate between these two sets of coordinates. More specifically, source_to_sink_func should *emulate* how the corresponding GstElement would translate the GstSegment time field, and sink_to_source_func should emulate how the corresponding GstElement would translate the seek query start and stop values, as used in gst_element_seek. As such, sink_to_source_func should act as an approximate reverse of source_to_sink_func.

Note, these functions will be passed a table of time properties, as registered in ges_base_effect_register_time_property, and their values. The functions should emulate what the translation would be if the time properties were set to the given values. They should not use the currently set values.

Note that effect must not be part of a clip, nor can it have has-internal-source set to TRUE.

Parameters:

effect –

A GESBaseEffect

source_to_sink_func ( [nullable][scope notified][closure]) –

The function to use for querying how a time is translated from the source coordinates to the sink coordinates of effect

sink_to_source_func ( [nullable][scope notified][closure]) –

The function to use for querying how a time is translated from the sink coordinates to the source coordinates of effect

user_data –

Data to pass to both source_to_sink_func and sink_to_source_func

destroy ( [destroy user_data][nullable]) –

Method to call to destroy user_data, or NULL

Returns –

TRUE if the translation functions were set.

Since : 1.18

GES.BaseEffect.prototype.set_time_translation_funcs 

function GES.BaseEffect.prototype.set_time_translation_funcs(source_to_sink_func: GES.BaseEffectTimeTranslationFunc, sink_to_source_func: GES.BaseEffectTimeTranslationFunc): {
    // javascript wrapper for 'ges_base_effect_set_time_translation_funcs'
}

Set the time translation query functions for the time effect. If an effect is a time effect, it will have two sets of coordinates: one at its sink and one at its source. The given functions should be able to translate between these two sets of coordinates. More specifically, source_to_sink_func should *emulate* how the corresponding Gst.Element would translate the Gst.Segment time field, and sink_to_source_func should emulate how the corresponding Gst.Element would translate the seek query start and stop values, as used in Gst.Element.prototype.seek. As such, sink_to_source_func should act as an approximate reverse of source_to_sink_func.

Note, these functions will be passed a table of time properties, as registered in GES.BaseEffect.prototype.register_time_property, and their values. The functions should emulate what the translation would be if the time properties were set to the given values. They should not use the currently set values.

Note that effect must not be part of a clip, nor can it have has-internal-source set to true.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

source_to_sink_func (GES.BaseEffectTimeTranslationFunc) –

The function to use for querying how a time is translated from the source coordinates to the sink coordinates of effect

sink_to_source_func (GES.BaseEffectTimeTranslationFunc) –

The function to use for querying how a time is translated from the sink coordinates to the source coordinates of effect

Returns (Number) –

true if the translation functions were set.

Since : 1.18

GES.BaseEffect.set_time_translation_funcs 

def GES.BaseEffect.set_time_translation_funcs (self, source_to_sink_func, sink_to_source_func):
    #python wrapper for 'ges_base_effect_set_time_translation_funcs'

Set the time translation query functions for the time effect. If an effect is a time effect, it will have two sets of coordinates: one at its sink and one at its source. The given functions should be able to translate between these two sets of coordinates. More specifically, source_to_sink_func should *emulate* how the corresponding Gst.Element would translate the Gst.Segment time field, and sink_to_source_func should emulate how the corresponding Gst.Element would translate the seek query start and stop values, as used in Gst.Element.seek. As such, sink_to_source_func should act as an approximate reverse of source_to_sink_func.

Note, these functions will be passed a table of time properties, as registered in GES.BaseEffect.register_time_property, and their values. The functions should emulate what the translation would be if the time properties were set to the given values. They should not use the currently set values.

Note that effect must not be part of a clip, nor can it have has_internal_source set to True.

Parameters:

effect (GES.BaseEffect) –

A GES.BaseEffect

source_to_sink_func (GES.BaseEffectTimeTranslationFunc) –

The function to use for querying how a time is translated from the source coordinates to the sink coordinates of effect

sink_to_source_func (GES.BaseEffectTimeTranslationFunc) –

The function to use for querying how a time is translated from the sink coordinates to the source coordinates of effect

Returns (bool) –

True if the translation functions were set.

Since : 1.18

Constants

GES_TYPE_BASE_EFFECT 

#define GES_TYPE_BASE_EFFECT ges_base_effect_get_type()

Callbacks

GESBaseEffectTimeTranslationFunc 

GstClockTime
(*GESBaseEffectTimeTranslationFunc) (GESBaseEffect * effect,
                                     GstClockTime time,
                                     GHashTable * time_property_values,
                                     gpointer user_data)

A function for querying how an effect would translate a time if it had the given child property values set. The keys for time_properties will be the same string that was passed to ges_base_effect_register_time_property, the values will be GValue* values of the corresponding child properties. You should always use the values given in time_properties before using the currently set values.

Parameters:

effect –

The GESBaseEffect that is doing the time translation

time –

The GstClockTime to translation

time_property_values ( [element-typegchar*]) –

A table of child property name/value pairs

user_data –

Data passed to ges_base_effect_set_time_translation_funcs

Returns –

The translated time.

Since : 1.18

GES.BaseEffectTimeTranslationFunc 

function GES.BaseEffectTimeTranslationFunc(effect: GES.BaseEffect, time: Number, time_property_values: GHashTable (not introspectable), user_data: Object): {
    // javascript wrapper for 'GESBaseEffectTimeTranslationFunc'
}

A function for querying how an effect would translate a time if it had the given child property values set. The keys for time_properties will be the same string that was passed to GES.BaseEffect.prototype.register_time_property, the values will be GObject.Value* values of the corresponding child properties. You should always use the values given in time_properties before using the currently set values.

Parameters:

effect (GES.BaseEffect) –

The GES.BaseEffect that is doing the time translation

time (Number) –

The Number to translation

time_property_values (GHashTable (not introspectable)) –

A table of child property name/value pairs

user_data (Object) –

Data passed to GES.BaseEffect.prototype.set_time_translation_funcs

Returns (Number) –

The translated time.

Since : 1.18

GES.BaseEffectTimeTranslationFunc 

def GES.BaseEffectTimeTranslationFunc (effect, time, time_property_values, *user_data):
    #python wrapper for 'GESBaseEffectTimeTranslationFunc'

A function for querying how an effect would translate a time if it had the given child property values set. The keys for time_properties will be the same string that was passed to GES.BaseEffect.register_time_property, the values will be GObject.Value* values of the corresponding child properties. You should always use the values given in time_properties before using the currently set values.

Parameters:

effect (GES.BaseEffect) –

The GES.BaseEffect that is doing the time translation

time (int) –

The int to translation

time_property_values (GHashTable (not introspectable)) –

A table of child property name/value pairs

user_data (variadic) –

Data passed to GES.BaseEffect.set_time_translation_funcs

Returns (int) –

The translated time.

Since : 1.18

The results of the search are