diff --git a/gir-files/GES-1.0.gir b/gir-files/GES-1.0.gir index 2e7dd2846..1a22dcd96 100644 --- a/gir-files/GES-1.0.gir +++ b/gir-files/GES-1.0.gir @@ -972,9 +972,155 @@ be created by clips. + 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 +#GESTrackElement: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(). + + 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. + + + %TRUE if @effect is considered a time effect. + + + + + A #GESBaseEffect + + + + + + 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 +#GESTrackElement:has-internal-source set to %TRUE. + + + %TRUE if the child property was found and newly registered. + + + + + A #GESBaseEffect + + + + The name of the child property to register as +a time property + + + + + + 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 +#GESTrackElement:has-internal-source set to %TRUE. + + + %TRUE if the translation functions were set. + + + + + A #GESBaseEffect + + + + The function to use +for querying how a time is translated from the source coordinates to +the sink coordinates of @effect + + + + The function to use +for querying how a time is translated from the sink coordinates to the +source coordinates of @effect + + + + Data to pass to both @source_to_sink_func and +@sink_to_source_func + + + + Method to call to destroy +@user_data, or %NULL + + + + @@ -1008,7 +1154,10 @@ be created by clips. #GESBaseEffectClip-s can have **additional** #GESBaseEffect-s added as non-core elements. These additional effects are applied to the output of the core effects of the clip that they share a #GESTrack with. See -#GESClip for how to add and move these effects from the clip. +#GESClip for how to add and move these effects from the clip. + +Note that you cannot add time effects to #GESBaseEffectClip, neither +as core children, nor as additional effects. @@ -1041,6 +1190,41 @@ of the core effects of the clip that they share a #GESTrack with. See + + 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. + + + The translated time. + + + + + The #GESBaseEffect that is doing the time translation + + + + The #GstClockTime to translation + + + + A table of child +property name/value pairs + + + + + + + Data passed to ges_base_effect_set_time_translation_funcs() + + + + @@ -1181,23 +1365,49 @@ For most uses of a #GESTimeline, it is often sufficient to only interact with #GESClip-s directly, which will take care of creating and organising the elements of the timeline's tracks. -Most subclassed clips will be associated with some *core* -#GESTrackElement-s. When such a clip is added to a layer in a timeline, -it will create these children and they will be added to the timeline's -tracks. You can connect to the #GESContainer::child-added signal to be -notified of their creation. If a clip will produce several core -elements of the same #GESTrackElement:track-type but they are destined -for separate tracks, you should connect to the timeline's +## Core Children + +In more detail, clips will usually have some *core* #GESTrackElement +children, which are created by the clip when it is added to a layer in +a timeline. The type and form of these core children will depend on the +clip's subclass. You can use ges_track_element_is_core() to determine +whether a track element is considered such a core track element. Note, +if a core track element is part of a clip, it will always be treated as +a core *child* of the clip. You can connect to the +#GESContainer::child-added signal to be notified of their creation. + +When a child is added to a clip, the timeline will select its tracks +using #GESTimeline::select-tracks-for-object. Note that it may be the +case that the child will still have no set #GESTrackElement:track +after this process. For example, if the timeline does not have a track +of the corresponding #GESTrack:track-type. A clip can safely contain +such children, which may have their track set later, although they will +play no functioning role in the timeline in the meantime. + +If a clip may create track elements with various +#GESTrackElement:track-type(s), such as a #GESUriClip, but you only +want it to create a subset of these types, you should set the +#GESClip:supported-formats of the clip to the subset of types. This +should be done *before* adding the clip to a layer. + +If a clip will produce several core elements of the same +#GESTrackElement:track-type, you should connect to the timeline's #GESTimeline::select-tracks-for-object signal to coordinate which -tracks each element should land in. +tracks each element should land in. Note, no two core children within a +clip can share the same #GESTrack, so you should not select the same +track for two separate core children. Provided you stick to this rule, +it is still safe to select several tracks for the same core child, the +core child will be copied into the additional tracks. You can manually +add the child to more tracks later using ges_clip_add_child_to_track(). +If you do not wish to use a core child, you can always select no track. The #GESTimelineElement:in-point of the clip will control the -#GESTimelineElement:in-point of these core elements to be the same +#GESTimelineElement:in-point of its core children to be the same value if their #GESTrackElement:has-internal-source is set to %TRUE. The #GESTimelineElement:max-duration of the clip is the minimum -#GESTimelineElement:max-duration of its children. If you set its value -to anything other than its current value, this will also set the +#GESTimelineElement:max-duration of its core children. If you set its +value to anything other than its current value, this will also set the #GESTimelineElement:max-duration of all its core children to the same value if their #GESTrackElement:has-internal-source is set to %TRUE. As a special case, whilst a clip does not yet have any core children, @@ -1206,16 +1416,117 @@ value will be once they are created. ## Effects -Some subclasses (#GESSourceClip and #GESBaseEffect) may also allow +Some subclasses (#GESSourceClip and #GESBaseEffectClip) may also allow their objects to have additional non-core #GESBaseEffect-s elements as children. These are additional effects that are applied to the output data of the core elements. They can be added to the clip using -ges_container_add(), which will take care of adding the effect to the -timeline's tracks. The new effect will be placed between the clip's +ges_clip_add_top_effect(), which will take care of adding the effect to +the timeline's tracks. The new effect will be placed between the clip's core track elements and its other effects. As such, the newly added effect will be applied to any source data **before** the other existing effects. You can change the ordering of effects using -ges_clip_set_top_effect_index(). +ges_clip_set_top_effect_index(). + +Tracks are selected for top effects in the same way as core children. +If you add a top effect to a clip before it is part of a timeline, and +later add the clip to a timeline, the track selection for the top +effects will occur just after the track selection for the core +children. If you add a top effect to a clip that is already part of a +timeline, the track selection will occur immediately. Since a top +effect must be applied on top of a core child, if you use +#GESTimeline::select-tracks-for-object, you should ensure that the +added effects are destined for a #GESTrack that already contains a core +child. + +In addition, if the core child in the track is not +#GESTrackElement:active, then neither can any of its effects be +#GESTrackElement:active. Therefore, if a core child is made in-active, +all of the additional effects in the same track will also become +in-active. Similarly, if an effect is set to be active, then the core +child will also become active, but other effects will be left alone. +Finally, if an active effect is added to the track of an in-active core +child, it will become in-active as well. Note, in contrast, setting a +core child to be active, or an effect to be in-active will *not* change +the other children in the same track. + +### Time Effects + +Some effects also change the timing of their data (see #GESBaseEffect +for what counts as a time effect). Note that a #GESBaseEffectClip will +refuse time effects, but a #GESSource will allow them. + +When added to a clip, time effects may adjust the timing of other +children in the same track. Similarly, when changing the order of +effects, making them (in)-active, setting their time property values +or removing time effects. These can cause the #GESClip:duration-limit +to change in value. However, if such an operation would ever cause the +#GESTimelineElement:duration to shrink such that a clip's #GESSource is +totally overlapped in the timeline, the operation would be prevented. +Note that the same can happen when adding non-time effects with a +finite #GESTimelineElement:max-duration. + +Therefore, when working with time effects, you should -- more so than +usual -- not assume that setting the properties of the clip's children +will succeed. In particular, you should use +ges_timeline_element_set_child_property_full() when setting the time +properties. + +If you wish to preserve the *internal* duration of a source in a clip +during these time effect operations, you can do something like the +following. + +```c +void +do_time_effect_change (GESClip * clip) +{ + GList *tmp, *children; + GESTrackElement *source; + GstClockTime source_outpoint; + GstClockTime new_end; + GError *error = NULL; + + // choose some active source in a track to preserve the internal + // duration of + source = ges_clip_get_track_element (clip, NULL, GES_TYPE_SOURCE); + + // note its current internal end time + source_outpoint = ges_clip_get_internal_time_from_timeline_time ( + clip, source, GES_TIMELINE_ELEMENT_END (clip), NULL); + + // handle invalid out-point + + // stop the children's control sources from clamping when their + // out-point changes with a change in the time effects + children = ges_container_get_children (GES_CONTAINER (clip), FALSE); + + for (tmp = children; tmp; tmp = tmp->next) + ges_track_element_set_auto_clamp_control_source (tmp->data, FALSE); + + // add time effect, or set their children properties, or move them around + ... + // user can make sure that if a time effect changes one source, we should + // also change the time effect for another source. E.g. if + // "GstVideorate::rate" is set to 2.0, we also set "GstPitch::rate" to + // 2.0 + + // Note the duration of the clip may have already changed if the + // duration-limit of the clip dropped below its current value + + new_end = ges_clip_get_timeline_time_from_internal_time ( + clip, source, source_outpoint, &error); + // handle error + + if (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip), + -1, GES_EDIT_MODE_TRIM, GES_EDGE_END, new_end, &error)) + // handle error + + for (tmp = children; tmp; tmp = tmp->next) + ges_track_element_set_auto_clamp_control_source (tmp->data, TRUE); + + g_list_free_full (children, gst_object_unref); + gst_object_unref (source); +} +``` @@ -1304,9 +1615,7 @@ that already contains one of the core children of the same clip. This method can also fail if the adding the track element to the track would break a configuration rule of the corresponding #GESTimeline, such as causing three sources to overlap at a single time, or causing -a source to completely overlap another in the same track. - -Note that @err will not always be set upon failure. +a source to completely overlap another in the same track. The element that was added to @track, either @@ -1328,6 +1637,39 @@ Note that @err will not always be set upon failure. + + Add a top effect to a clip at the given index. + +Unlike using ges_container_add(), this allows you to set the index +in advance. It will also check that no error occurred during the track +selection for the effect. + +Note, only subclasses of #GESClipClass that have +#GES_CLIP_CLASS_CAN_ADD_EFFECTS set to %TRUE (such as #GESSourceClip +and #GESBaseEffectClip) can have additional top effects added. + +Note, if the effect is a time effect, this may be refused if the clip +would not be able to adapt itself once the effect is added. + + + %TRUE if @effect was successfully added to @clip at @index. + + + + + A #GESClip + + + + A top effect to add + + + + The index to add @effect at, or -1 to add at the highest + + + + Finds an element controlled by the clip. If @track is given, then only the track elements in @track are searched for. If @type is @@ -1412,6 +1754,81 @@ match any type + + Gets the #GESClip:duration-limit of the clip. + + + The duration-limit of @clip. + + + + + A #GESClip + + + + + + Convert the timeline time to an internal source time of the child. +This will take any time effects placed on the clip into account (see +#GESBaseEffect for what time effects are supported, and how to +declare them in GES). + +When @timeline_time is above the #GESTimelineElement:start of @clip, +this will return the internal time at which the content that appears at +@timeline_time in the output of the timeline is created in @child. For +example, if @timeline_time corresponds to the current seek position, +this would let you know which part of a media file is being read. + +This will be done assuming the clip has an indefinite end, so the +internal time may be beyond the current out-point of the child, or even +its #GESTimelineElement:max-duration. + +If, instead, @timeline_time is below the current +#GESTimelineElement:start of @clip, this will return what you would +need to set the #GESTimelineElement:in-point of @child to if you set +the #GESTimelineElement:start of @clip to @timeline_time and wanted +to keep the content of @child currently found at the current +#GESTimelineElement:start of @clip at the same timeline position. If +this would be negative, the conversion fails. This is useful for +determining what #GESTimelineElement:in-point would result from a +#GES_EDIT_MODE_TRIM to @timeline_time. + +Note that whilst a clip has no time effects, this second return is +equivalent to finding the internal time at which the content that +appears at @timeline_time in the timeline can be found in @child if it +had indefinite extent in both directions. However, with non-linear time +effects this second return will be more distinct. + +In either case, the returned time would be appropriate to use for the +#GESTimelineElement:in-point or #GESTimelineElement:max-duration of the +child. + +See ges_clip_get_timeline_time_from_internal_time(), which performs the +reverse. + + + The time in the internal coordinates of @child corresponding +to @timeline_time, or #GST_CLOCK_TIME_NONE if the conversion could not +be performed. + + + + + A #GESClip + + + + An #GESTrackElement:active child of @clip with a +#GESTrackElement:track + + + + A time in the timeline time coordinates + + + + Gets the #GESClip:layer of the clip. @@ -1441,26 +1858,89 @@ match any type - - This method allows you to convert a frame number into a #GstClockTime, this -can be used to either seek to a particular frame in the timeline or to later -on edit @self with that timestamp. + + Convert the internal source time from the child to a timeline time. +This will take any time effects placed on the clip into account (see +#GESBaseEffect for what time effects are supported, and how to +declare them in GES). -This method should be use specifically in the case where you want to trim the -clip to a particular frame. +When @internal_time is above the #GESTimelineElement:in-point of +@child, this will return the timeline time at which the internal +content found at @internal_time appears in the output of the timeline's +track. For example, this would let you know where in the timeline a +particular scene in a media file would appear. -The returned timestamp is in the global #GESTimeline time coordinates of @self, not -in the internal time coordinates. In practice, this means that you can not use -that time to set the clip #GESTimelineElement:in-point but it can be used in -the timeline editing API, for example as the @position argument of the -#ges_timeline_element_edit method. +This will be done assuming the clip has an indefinite end, so the +timeline time may be beyond the end of the clip, or even breaking its +#GESClip:duration-limit. -Note that you can get the frame timestamp of a particular clip asset with -#ges_clip_asset_get_frame_time. +If, instead, @internal_time is below the current +#GESTimelineElement:in-point of @child, this will return what you would +need to set the #GESTimelineElement:start of @clip to if you set the +#GESTimelineElement:in-point of @child to @internal_time and wanted to +keep the content of @child currently found at the current +#GESTimelineElement:start of @clip at the same timeline position. If +this would be negative, the conversion fails. This is useful for +determining what position to use in a #GES_EDIT_MODE_TRIM if you wish +to trim to a specific point in the internal content, such as a +particular scene in a media file. + +Note that whilst a clip has no time effects, this second return is +equivalent to finding the timeline time at which the content of @child +at @internal_time would be found in the timeline if it had indefinite +extent in both directions. However, with non-linear time effects this +second return will be more distinct. + +In either case, the returned time would be appropriate to use in +ges_timeline_element_edit() for #GES_EDIT_MODE_TRIM, and similar, if +you wish to use a particular internal point as a reference. For +example, you could choose to end a clip at a certain internal +'out-point', similar to the #GESTimelineElement:in-point, by +translating the desired end time into the timeline coordinates, and +using this position to trim the end of a clip. + +See ges_clip_get_internal_time_from_timeline_time(), which performs the +reverse, or ges_clip_get_timeline_time_from_source_frame() which does +the same conversion, but using frame numbers. - The timestamp corresponding to @frame_number in the element source -in the timeline coordinates. + The time in the timeline coordinates corresponding to +@internal_time, or #GST_CLOCK_TIME_NONE if the conversion could not be +performed. + + + + + A #GESClip + + + + An #GESTrackElement:active child of @clip with a +#GESTrackElement:track + + + + A time in the internal time coordinates of @child + + + + + + Convert the source frame number to a timeline time. This acts the same +as ges_clip_get_timeline_time_from_internal_time() using the core +children of the clip and using the frame number to specify the internal +position, rather than a timestamp. + +The returned timeline time can be used to seek or edit to a specific +frame. + +Note that you can get the frame timestamp of a particular clip asset +with ges_clip_asset_get_frame_time(). + + + The timestamp corresponding to @frame_number in the core +children of @clip, in the timeline coordinates, or #GST_CLOCK_TIME_NONE +if the conversion could not be performed. @@ -1469,8 +1949,8 @@ in the timeline coordinates. - The frame number to get the corresponding timestamp in the - timeline coordinates + The frame number to get the corresponding timestamp of +in the timeline coordinates @@ -1532,6 +2012,24 @@ ges_clip_get_top_effect_index(). + See ges_clip_move_to_layer_full(), which also gives an error. + + + %TRUE if @clip was successfully moved to @layer. + + + + + A #GESClip + + + + The new layer + + + + + Moves a clip to a new layer. If the clip already exists in a layer, it is first removed from its current layer before being added to the new layer. @@ -1551,6 +2049,27 @@ layer. + + Remove a top effect from the clip. + +Note, if the effect is a time effect, this may be refused if the clip +would not be able to adapt itself once the effect is removed. + + + %TRUE if @effect was successfully added to @clip at @index. + + + + + A #GESClip + + + + The top effect to remove + + + + Sets the #GESClip:supported-formats of the clip. This should normally only be called by subclasses, which should be responsible for updating @@ -1571,6 +2090,28 @@ its value, rather than the user. + See ges_clip_set_top_effect_index_full(), which also gives an error. + + + %TRUE if @effect was successfully moved to @newindex. + + + + + A #GESClip + + + + An effect within @clip to move + + + + The index for @effect in @clip + + + + + Set the index of an effect within the clip. See ges_clip_get_top_effect_index(). The new index must be an existing index of the clip. The effect is moved to the new index, and the other @@ -1614,6 +2155,25 @@ ordering. + See ges_clip_split_full(), which also gives an error. + + + The newly created clip resulting +from the splitting @clip, or %NULL if @clip can't be split. + + + + + The #GESClip to split + + + + The timeline position at which to perform the split + + + + + Splits a clip at the given timeline position into two clips. The clip must already have a #GESClip:layer. @@ -1653,11 +2213,29 @@ from the splitting @clip, or %NULL if @clip can't be split. - The timeline position at which to perform the split + The timeline position at which to perform the split, between +the start and end of the clip + + The maximum #GESTimelineElement:duration that can be *currently* set +for the clip, taking into account the #GESTimelineElement:in-point, +#GESTimelineElement:max-duration, #GESTrackElement:active, and +#GESTrackElement:track properties of its children, as well as any +time effects. If there is no limit, this will be set to +#GST_CLOCK_TIME_NONE. + +Note that whilst a clip has no children in any tracks, the limit will +be unknown, and similarly set to #GST_CLOCK_TIME_NONE. + +If the duration-limit would ever go below the current +#GESTimelineElement:duration of the clip due to a change in the above +variables, its #GESTimelineElement:duration will be set to the new +limit. + + The layer this clip lies in. @@ -2562,26 +3140,98 @@ if no track elements are created or an error occurred. - When a single timeline element is edited within its timeline, using -ges_timeline_element_edit(), depending on the edit mode, its -#GESTimelineElement:start, #GESTimelineElement:duration or + When a single timeline element is edited within its timeline at some +position, using ges_timeline_element_edit(), depending on the edit +mode, its #GESTimelineElement:start, #GESTimelineElement:duration or #GESTimelineElement:in-point will be adjusted accordingly. In addition, -other elements in the timeline may also have their properties adjusted. +any clips may change #GESClip:layer. -In fact, the edit is actually performed on the toplevel of the edited -element (usually a #GESClip), which is responsible for moving its -children along with it. For simplicity, in the descriptions we will -use "element" to exclusively refer to toplevel elements. +Each edit can be broken down into a combination of three basic edits: -In the edit mode descriptions, the "start edge", "end edge" and the -"element as a whole" correspond to using #GES_EDGE_START, #GES_EDGE_END -and #GES_EDGE_NONE as part of the edit, respectively. The "start time", -"duration time" and "in-point time" correspond to the -#GESTimelineElement:start, #GESTimelineElement:duration and -#GESTimelineElement:in-point properties, respectively. Moreover, the -"end time" refers to the final time of the element: -#GESTimelineElement:start + #GESTimelineElement:duration. Finally, -the "edit position" is the timeline time used as part of the edit. ++ MOVE: This moves the start of the element to the edit position. ++ START-TRIM: This cuts or grows the start of the element, whilst + maintaining the time at which its internal content appears in the + timeline data output. If the element is made shorter, the data that + appeared at the edit position will still appear in the timeline at + the same time. If the element is made longer, the data that appeared + at the previous start of the element will still appear in the + timeline at the same time. ++ END-TRIM: Similar to START-TRIM, but the end of the element is cut or + grown. + +In particular, when editing a #GESClip: + ++ MOVE: This will set the #GESTimelineElement:start of the clip to the + edit position. ++ START-TRIM: This will set the #GESTimelineElement:start of the clip + to the edit position. To keep the end time the same, the + #GESTimelineElement:duration of the clip will be adjusted in the + opposite direction. In addition, the #GESTimelineElement:in-point of + the clip will be shifted such that the content that appeared at the + new or previous start time, whichever is latest, still appears at the + same timeline time. For example, if a frame appeared at the start of + the clip, and the start of the clip is reduced, the in-point of the + clip will also reduce such that the frame will appear later within + the clip, but at the same timeline position. ++ END-TRIM: This will set the #GESTimelineElement:duration of the clip + such that its end time will match the edit position. + +When editing a #GESGroup: + ++ MOVE: This will set the #GESGroup:start of the clip to the edit + position by shifting all of its children by the same amount. So each + child will maintain their relative positions. ++ START-TRIM: If the group is made shorter, this will START-TRIM any + clips under the group that start after the edit position to the same + edit position. If the group is made longer, this will START-TRIM any + clip under the group whose start matches the start of the group to + the same edit position. ++ END-TRIM: If the group is made shorter, this will END-TRIM any clips + under the group that end after the edit position to the same edit + position. If the group is made longer, this will END-TRIM any clip + under the group whose end matches the end of the group to the same + edit position. + +When editing a #GESTrackElement, if it has a #GESClip parent, this +will be edited instead. Otherwise it is edited in the same way as a +#GESClip. + +The layer priority of a #GESGroup is the lowest layer priority of any +#GESClip underneath it. When a group is edited to a new layer +priority, it will shift all clips underneath it by the same amount, +such that their relative layers stay the same. + +If the #GESTimeline has a #GESTimeline:snapping-distance, then snapping +may occur for some of the edges of the **main** edited element: + ++ MOVE: The start or end edge of *any* #GESSource under the element may + be snapped. ++ START-TRIM: The start edge of a #GESSource whose start edge touches + the start edge of the element may snap. ++ END-TRIM: The end edge of a #GESSource whose end edge touches the end + edge of the element may snap. + +These edges may snap with either the start or end edge of *any* other +#GESSource in the timeline that is not also being moved by the element, +including those in different layers, if they are within the +#GESTimeline:snapping-distance. During an edit, only up to one snap can +occur. This will shift the edit position such that the snapped edges +will touch once the edit has completed. + +Note that snapping can cause an edit to fail where it would have +otherwise succeeded because it may push the edit position such that the +edit would result in an unsupported timeline configuration. Similarly, +snapping can cause an edit to succeed where it would have otherwise +failed. + +For example, in #GES_EDIT_MODE_RIPPLE acting on #GES_EDGE_NONE, the +main element is the MOVED toplevel of the edited element. Any source +under the main MOVED toplevel may have its start or end edge snapped. +Note, these sources cannot snap with each other. The edit may also +push other elements, but any sources under these elements cannot snap, +nor can they be snapped with. If a snap does occur, the MOVE of the +toplevel *and* all other elements pushed by the ripple will be shifted +by the same amount such that the snapped edges will touch. You can also find more explanation about the behaviour of those modes at: [trim, ripple and roll](http://pitivi.org/manual/trimming.html) @@ -2589,65 +3239,84 @@ and [clip management](http://pitivi.org/manual/usingclips.html). The element is edited the normal way (default). - This only moves a single element. If acting on the start edge of the - element, the element's start time is set to the edit position. - If acting on end edge of the element, the element's duration time - is set such that its end time matches the edit position. + If acting on the element as a whole (#GES_EDGE_NONE), this will MOVE + the element by MOVING its toplevel. When acting on the start of the + element (#GES_EDGE_START), this will only MOVE the element, but not + its toplevel parent. This can allow you to move a #GESClip or + #GESGroup to a new start time or layer within its container group, + without effecting other members of the group. When acting on the end + of the element (#GES_EDGE_END), this will END-TRIM the element, + leaving its toplevel unchanged. - The element is edited in ripple mode. This - shifts the element and all later elements (those with equal or later - start times) in the timeline by the same amount. If acting on the - element as a whole, the element's start time is shifted to the edit - position, and later elements are also shifted by the same amount. If - acting on the end edge of the element, the element's **duration time** - is shifted so that the element's end time matches the edit position, - and later elements have their **start time** shifted by the same - amount. + The element is edited in ripple mode: moving + itself as well as later elements, keeping their relative times. This + edits the element the same as #GES_EDIT_MODE_NORMAL. In addition, if + acting on the element as a whole, or the start of the element, any + toplevel element in the same timeline (including different layers) + whose start time is later than the *current* start time of the MOVED + element will also be MOVED by the same shift as the edited element. + If acting on the end of the element, any toplevel element whose start + time is later than the *current* end time of the edited element will + also be MOVED by the same shift as the change in the end of the + edited element. These additional elements will also be shifted by + the same shift in layers as the edited element. - The element is edited in roll mode. This trims - the edge of an element and neighbouring edges (opposite edges of other - elements in the timeline with the same corresponding time value), such - that the edges remain in contact. If acting on the start edge of the - element, the start edge is trimmed to the edit position (see - #GES_EDIT_MODE_TRIM), and any other elements in the timeline whose end - time matches the edited element's start time (evaluated before the - edit) will have their **end** edge trimmed to the same edit position. - Similarly, if acting on the end edge of the element, the end edge is - trimmed to the edit position, and any other elements in the timeline - whose start time matches the edited element's end time will have - their start edge trimmed to the same edit position. + The element is edited in roll mode: swapping its + content for its neighbour's, or vis versa, in the timeline output. + This edits the element the same as #GES_EDIT_MODE_TRIM. In addition, + any neighbours are also TRIMMED at their opposite edge to the same + timeline position. When acting on the start of the element, a + neighbour is any earlier element in the timeline whose end time + matches the *current* start time of the edited element. When acting on + the end of the element, a neighbour is any later element in the + timeline whose start time matches the *current* start time of the + edited element. In addition, a neighbour have a #GESSource at its + end/start edge that shares a track with a #GESSource at the start/end + edge of the edited element. Basically, a neighbour is an element that + can be extended, or cut, to have its content replace, or be replaced + by, the content of the edited element. Acting on the element as a + whole (#GES_EDGE_NONE) is not defined. The element can not shift + layers under this mode. - The element is edited in trim mode. This shifts - the edge of a single element while maintaining the timing of - its internal content in the timeline, so the samples/frames/etc of a - source would still appear at the same timeline time when it is played. - If acting on the start edge of the element, the element's start time - will be shifted to the edit position and the element's in-point time - will be shifted by the same amount. Additionally, the element's - duration time will be shifted the other way such that the element's - end time remains the same. If acting on end edge of the element, the - element's duration time is set such that its end time matches the edit - position. + The element is edited in trim mode. When acting + on the start of the element, this will START-TRIM it. When acting on + the end of the element, this will END-TRIM it. Acting on the element + as a whole (#GES_EDGE_NONE) is not defined. The element is edited in slide mode (not yet - implemented). This shifts the element and will trim the edges of - neighbouring edges on either side accordingly. If acting on the - element as a whole, the element's start time is shifted to the edit - position. Any other elements in the timeline whose end time matches - the edited element's start time (evaluated before the edit) will have - their end edge trimmed to the same edit position. Additionally, any - other elements in the timeline whose start time matches the edited - element's end time will have their start edge trimmed to match the - edited element's **new** end time. + implemented): moving the element replacing or consuming content on + each end. When acting on the element as a whole, this will MOVE the + element, and TRIM any neighbours on either side. A neighbour is + defined in the same way as in #GES_EDIT_MODE_ROLL, but they may be on + either side of the edited elements. Elements at the end with be + START-TRIMMED to the new end position of the edited element. Elements + at the start will be END-TRIMMED to the new start position of the + edited element. Acting on the start or end of the element + (#GES_EDGE_START and #GES_EDGE_END) is not defined. The element can + not shift layers under this mode. + + Return a string representation of @mode. + + + a string representation of @mode. + + + + + a #GESEditMode + + + + Currently we only support effects with 1 sinkpad and 1 sourcepad @@ -2745,20 +3414,35 @@ to what track type the effect should be used in. - Register an element that can change the rate at which media is playing. The -property type must be float or double, and must be a factor of the rate, -i.e. a value of 2.0 must mean that the media plays twice as fast. For -example, this is true for the properties 'rate' and 'tempo' of the element -'pitch', which is already registered by default. By registering the element, -timeline duration can be correctly converted into media duration, allowing -the right segment seeks to be sent to the sources. + Register an element that can change the rate at which media is playing. +The property type must be float or double, and must be a factor of the +rate, i.e. a value of 2.0 must mean that the media plays twice as fast. +Several properties may be registered for a single element type, +provided they all contribute to the rate as independent factors. For +example, this is true for the "GstPitch::rate" and "GstPitch::tempo" +properties. These are already registered by default in GES, along with +#videorate:rate for #videorate and #scaletempo:rate for #scaletempo. -A reference to the GESEffectClass can be obtained as follows: - GES_EFFECT_CLASS (g_type_class_ref (GES_TYPE_EFFECT)); +If such a rate property becomes a child property of a #GESEffect upon +its creation (the element is part of its #GESEffect:bin-description), +it will be automatically registered as a time property (see +ges_base_effect_register_time_property()) and will have its time +translation functions set (see +ges_base_effect_set_time_translation_funcs()) to use the overall rate +of the rate properties. Note that if an effect contains a rate +property as well as a non-rate time property, you should ensure to set +the time translation functions to some other methods using +ges_base_effect_set_time_translation_funcs(). + +Note, you can obtain a reference to the GESEffectClass using + +``` + GES_EFFECT_CLASS (g_type_class_ref (GES_TYPE_EFFECT)); +``` - whether the rate property was succesfully registered. When this -method returns false, a warning is emitted with more information. + %TRUE if the rate property was successfully registered. When +this method returns %FALSE, a warning is emitted with more information. @@ -2767,11 +3451,12 @@ method returns false, a warning is emitted with more information. - Name of the GstElement that changes the rate + The #GstElementFactory name of the element that changes +the rate - Name of the property that changes the rate + The name of the property that changes the rate @@ -2863,6 +3548,25 @@ Example: "videobalance saturation=1.5 hue=+0.5" The formatted files was malformed + The frame number is invalid + + + The operation would lead to a negative +#GES_TIMELINE_ELEMENT_LAYER_PRIORITY. (Since: 1.18) + + + The operation would lead to a negative time. +E.g. for the #GESTimelineElement:start #GESTimelineElement:duration or +#GESTimelineElement:in-point. (Since: 1.18) + + + Some #GESTimelineElement does +not have a large enough #GESTimelineElement:max-duration to cover the +desired operation. (Since: 1.18) + + + The operation would break one of +the overlap conditions for the #GESTimeline. (Since: 1.18) @@ -3750,6 +4454,45 @@ layers will simply play in addition. + See ges_layer_add_asset_full(), which also gives an error. + + + The newly created clip. + + + + + The #GESLayer + + + + The asset to extract the new clip from + + + + The #GESTimelineElement:start value to set on the new clip +If `start == #GST_CLOCK_TIME_NONE`, it will be added to the end +of @layer, i.e. it will be set to @layer's duration + + + + The #GESTimelineElement:in-point value to set on the new +clip + + + + The #GESTimelineElement:duration value to set on the new +clip + + + + The #GESClip:supported-formats to set on the the new +clip, or #GES_TRACK_TYPE_UNKNOWN to use the default + + + + + Extracts a new clip from an asset and adds it to the layer with the given properties. @@ -3790,6 +4533,25 @@ clip, or #GES_TRACK_TYPE_UNKNOWN to use the default + See ges_layer_add_clip_full(), which also gives an error. + + + %TRUE if @clip was properly added to @layer, or %FALSE +if @layer refused to add @clip. + + + + + The #GESLayer + + + + The clip to add + + + + + Adds the given clip to the layer. If the method succeeds, the layer will take ownership of the clip. @@ -4064,24 +4826,8 @@ will make sure there is never 'gaps' between layer priorities. Whether to automatically create a #GESTransitionClip whenever two -#GESClip-s overlap in the layer. Specifically, if this is set to -%TRUE, then wherever two #GESSource-s (that belong to some clip in -the layer) share the same #GESTrackElement:track and the end time of -one source exceeds the #GESTimelineElement:start time of the other, -there will exist a corresponding #GESTransitionClip in the same -layer. These automatic transitions will be created and removed -accordingly. Their temporal extent will cover the overlap of the -two sources (their #GESTimelineElement:start will be set to the -#GESTimelineElement:start of the later source, and their -#GESTimelineElement:duration will be the difference between the -#GESTimelineElement:start of the later source, and the end time of -the earlier source). - -It may be difficult to use this feature if your timeline has multiple -tracks of the same #GESTrack:track-type and you use the -#GESTimeline::select-tracks-for-object signal. You will have to -ensure that any #GESTransition that belongs to a newly created -transition clip is able to arrive in the correct track. +#GESSource-s that both belong to a #GESClip in the layer overlap. +See #GESTimeline for what counts as an overlap. When a layer is added to a #GESTimeline, if this property is left as %FALSE, but the timeline's #GESTimeline:auto-transition is %TRUE, it @@ -6586,10 +7332,11 @@ is one of the timelines that have been extracted from @project The uri where to save @project and @timeline - - The formatter asset to use or %NULL. If %NULL, -will try to save in the same format as the one from which the timeline as been loaded -or default to the best formatter as defined in #ges_find_formatter_for_uri + + The formatter asset to +use or %NULL. If %NULL, will try to save in the same format as the one +from which the timeline as been loaded or default to the best formatter +as defined in #ges_find_formatter_for_uri @@ -6915,6 +7662,15 @@ these effects from the clip. + + Creates a new #GESSourceClip that renders a time overlay on top + + + The newly created #GESSourceClip, +or %NULL if there was an error. + + + @@ -7085,7 +7841,7 @@ for new elements from this class. ## Asset The default asset ID is GESTestClip, but the framerate and video -size can be overriden using an ID of the form: +size can be overridden using an ID of the form: ``` framerate=60/1, width=1920, height=1080, max-duration=5.0 @@ -7895,20 +8651,74 @@ The layers are ordered, with higher priority layers having their content prioritised in the tracks. This ordering can be changed using ges_timeline_move_layer(). +## Editing + +See #GESTimelineElement for the various ways the elements of a timeline +can be edited. + +If you change the timing or ordering of a timeline's +#GESTimelineElement-s, then these changes will not actually be taken +into account in the output of the timeline's tracks until the +ges_timeline_commit() method is called. This allows you to move its +elements around, say, in response to an end user's mouse dragging, with +little expense before finalising their effect on the produced data. + +## Overlaps and Auto-Transitions + +There are certain restrictions placed on how #GESSource-s may overlap +in a #GESTrack that belongs to a timeline. These will be enforced by +GES, so the user will not need to keep track of them, but they should +be aware that certain edits will be refused as a result if the overlap +rules would be broken. + +Consider two #GESSource-s, `A` and `B`, with start times `startA` and +`startB`, and end times `endA` and `endB`, respectively. The start +time refers to their #GESTimelineElement:start, and the end time is +their #GESTimelineElement:start + #GESTimelineElement:duration. These +two sources *overlap* if: + ++ they share the same #GESTrackElement:track (non %NULL), which belongs + to the timeline; ++ they share the same #GES_TIMELINE_ELEMENT_LAYER_PRIORITY; and ++ `startA < endB` and `startB < endA `. + +Note that when `startA = endB` or `startB = endA` then the two sources +will *touch* at their edges, but are not considered overlapping. + +If, in addition, `startA < startB < endA`, then we can say that the +end of `A` overlaps the start of `B`. + +If, instead, `startA <= startB` and `endA >= endB`, then we can say +that `A` fully overlaps `B`. + +The overlap rules for a timeline are that: + +1. One source cannot fully overlap another source. +2. A source can only overlap the end of up to one other source at its + start. +3. A source can only overlap the start of up to one other source at its + end. + +The last two rules combined essentially mean that at any given timeline +position, only up to two #GESSource-s may overlap at that position. So +triple or more overlaps are not allowed. + +If you switch on #GESTimeline:auto-transition, then at any moment when +the end of one source (the first source) overlaps the start of another +(the second source), a #GESTransitionClip will be automatically created +for the pair in the same layer and it will cover their overlap. If the +two elements are edited in a way such that the end of the first source +no longer overlaps the start of the second, the transition will be +automatically removed from the timeline. However, if the two sources +still overlap at the same edges after the edit, then the same +transition object will be kept, but with its timing and layer adjusted +accordingly. + ## Saving To save/load a timeline, you can use the ges_timeline_load_from_uri() and ges_timeline_save_to_uri() methods that use the default format. -## Editing - -If you change the timing or ordering of a timeline's -#GESTimelineElement-s, then these changes will not actually be taken -into account in the timeline until the ges_timeline_commit() method is -called. This allows you to move its elements around, say, in -response to an end user's mouse dragging, with little expense before -finalising their effect. - ## Playing A timeline is a #GstBin with a source #GstPad for each of its @@ -8590,8 +9400,10 @@ current element positions within the timeline. - Whether to automatically create a transition whenever two clips -overlap in the timeline. See #GESLayer:auto-transition. + Whether to automatically create a transition whenever two +#GESSource-s overlap in a track of the timeline. See +#GESLayer:auto-transition if you want this to only happen in some +layers. @@ -8602,9 +9414,9 @@ overlap in the timeline. See #GESLayer:auto-transition. The distance (in nanoseconds) at which a #GESTimelineElement being -moved within the timeline should snap to its neighbours. Note that -such a neighbour includes any element in the timeline, including -across separate layers. 0 means no snapping. +moved within the timeline should snap one of its #GESSource-s with +another #GESSource-s edge. See #GESEditMode for which edges can +snap during an edit. 0 means no snapping. @@ -8786,11 +9598,10 @@ not add the element to any track. Will be emitted whenever a snapping event ends. After a snap event -has started (see #GESTimeline::snapping-started), it can end because -the element whose movement created the snap event has since moved -outside of the #GESTimeline:snapping-distance before its position was -committed. It can also end because the element's movement was ended -by a timeline being committed. +has started (see #GESTimeline::snapping-started), it can later end +because either another timeline edit has occurred (which may or may +not have created a new snapping event), or because the timeline has +been committed. @@ -8811,9 +9622,14 @@ by a timeline being committed. Will be emitted whenever an element's movement invokes a snapping -event (usually by its controlling #GESClip being moved) because its +event during an edit (usually of one of its ancestors) because its start or end point lies within the #GESTimeline:snapping-distance of -another element's start or end point. +another element's start or end point. + +See #GESEditMode to see what can snap during an edit. + +Note that only up to one snapping-started signal will be emitted per +element edit within a timeline. @@ -9002,17 +9818,48 @@ adjust these properties in a convenient way, as well as introduce similar changes in neighbouring or later elements in the timeline. However, a timeline may refuse a change in these properties if they -would place the timeline in an unsupported configuration. For example, -it is not possible for three #GESSourceClip-s in the same layer and -with the same track types to overlap at any given position in the -timeline (only two may overlap, which corresponds to a single -#GESTransition). Similarly, a #GESSourceClip may not entirely cover -another #GESSourceClip in the same layer and with the same track types. +would place the timeline in an unsupported configuration. See +#GESTimeline for its overlap rules. + Additionally, an edit may be refused if it would place one of the timing properties out of bounds (such as a negative time value for #GESTimelineElement:start, or having insufficient internal content to last for the desired #GESTimelineElement:duration). +## Time Coordinates + +There are three main sets of time coordinates to consider when using +timeline elements: + ++ Timeline coordinates: these are the time coordinates used in the + output of the timeline in its #GESTrack-s. Each track share the same + coordinates, so there is only one set of coordinates for the + timeline. These extend indefinitely from 0. The times used for + editing (including setting #GESTimelineElement:start and + #GESTimelineElement:duration) use these coordinates, since these + define when an element is present and for how long the element lasts + for in the timeline. ++ Internal source coordinates: these are the time coordinates used + internally at the element's output. This is only really defined for + #GESTrackElement-s, where it refers to time coordinates used at the + final source pad of the wrapped #GstElement-s. However, these + coordinates may also be used in a #GESClip in reference to its + children. In particular, these are the coordinates used for + #GESTimelineElement:in-point and #GESTimelineElement:max-duration. ++ Internal sink coordinates: these are the time coordinates used + internally at the element's input. A #GESSource has no input, so + these would be undefined. Otherwise, for most #GESTrackElement-s + these will be the same set of coordinates as the internal source + coordinates because the element does not change the timing + internally. Only #GESBaseEffect can support elements where these + are different. See #GESBaseEffect for more information. + +You can determine the timeline time for a given internal source time +in a #GESTrack in a #GESClip using +ges_clip_get_timeline_time_from_internal_time(), and vice versa using +ges_clip_get_internal_time_from_timeline_time(), for the purposes of +editing and setting timings properties. + ## Children Properties If a timeline element owns another #GstObject and wishes to expose @@ -9182,13 +10029,8 @@ specification of the child property Edits the start time of an element within its timeline in ripple mode. -The element is shifted to @start, and later elements are also shifted -by the same amount (see #GES_EDIT_MODE_RIPPLE). An edit may fail if it -would place the timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and +#GES_EDGE_NONE. %TRUE if the ripple edit of @self completed, %FALSE on @@ -9208,15 +10050,8 @@ failure. Edits the end time of an element within its timeline in ripple mode. -The element's duration time is shifted until its end time matches @end, -and later elements have their start time shifted by the same amount -(see #GES_EDIT_MODE_RIPPLE). An edit may fail if it would place the -duration time out of bounds, or if it would place the timeline in an -unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the end time may be set -to the edge of some element in the neighbourhood of @end. +See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and +#GES_EDGE_END. %TRUE if the ripple edit of @self completed, %FALSE on @@ -9236,15 +10071,8 @@ failure. Edits the end time of an element within its timeline in roll mode. -The end of the element is trimmed to @end, and any other element whose -start edge matched the end edge of the element is also trimmed to @end -(see #GES_EDIT_MODE_ROLL). An edit may fail if it would place an -in-point time or duration time out of bounds, or if it would place the -timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the end time may be set -to the edge of some element in the neighbourhood of @end. +See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and +#GES_EDGE_END. %TRUE if the roll edit of @self completed, %FALSE on failure. @@ -9263,15 +10091,8 @@ to the edge of some element in the neighbourhood of @end. Edits the start time of an element within its timeline in roll mode. -The element is trimmed to @start, and any other element whose end edge -matched the start edge of the element is also trimmed to @start (see -#GES_EDIT_MODE_ROLL). An edit may fail if it would place an in-point -time or duration time out of bounds, or if it would place the timeline -in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and +#GES_EDGE_START. %TRUE if the roll edit of @self completed, %FALSE on failure. @@ -9308,18 +10129,37 @@ to the edge of some element in the neighbourhood of @start. + + + + + + + + + + + + + + + + + + + + - Sets #GESTimelineElement:duration for the element. This may fail if it -would place the timeline in an unsupported configuration, or if the -element does not have enough internal content to last for the desired -@duration. + Sets #GESTimelineElement:duration for the element. -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the element's -#GESTimelineElement:duration may instead be adjusted around @duration -such that the edge of @self matches the edge of some other element in -the neighbourhood. In such a case, the return value will still be %TRUE -on success. +Whilst the element is part of a #GESTimeline, this is the same as +editing the element with ges_timeline_element_edit() under +#GES_EDIT_MODE_TRIM with #GES_EDGE_END. In particular, the +#GESTimelineElement:duration of the element may be snapped to a +different timeline time difference from the one given. In addition, +setting may fail if it would place the timeline in an unsupported +configuration, or the element does not have enough internal content to +last the desired duration. %TRUE if @duration could be set for @self. @@ -9428,14 +10268,15 @@ be used. - Sets #GESTimelineElement:start for the element. This may fail if it -would place the timeline in an unsupported configuration. + Sets #GESTimelineElement:start for the element. If the element has a +parent, this will also move its siblings with the same shift. -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the element's -#GESTimelineElement:start may instead be set to the edge of some other -element in the neighbourhood of @start. In such a case, the return -value will still be %TRUE on success. +Whilst the element is part of a #GESTimeline, this is the same as +editing the element with ges_timeline_element_edit() under +#GES_EDIT_MODE_NORMAL with #GES_EDGE_NONE. In particular, the +#GESTimelineElement:start of the element may be snapped to a different +timeline time from the one given. In addition, setting may fail if it +would place the timeline in an unsupported configuration. %TRUE if @start could be set for @self. @@ -9454,15 +10295,8 @@ value will still be %TRUE on success. Edits the start time of an element within its timeline in trim mode. -The element is shifted to @start, and its in-point time is similarly -shifted to ensure that its internal content will appear at the same -timeline time when it is played (see #GES_EDIT_MODE_TRIM). An edit may -fail if it would place the in-point time out of bounds, or if it would -place the timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_TRIM and +#GES_EDGE_START. %TRUE if the trim edit of @self completed, %FALSE on failure. @@ -9539,28 +10373,10 @@ copied from @self. - Edits the element within its timeline by adjusting its -#GESTimelineElement:start, #GESTimelineElement:duration or -#GESTimelineElement:in-point, and potentially doing the same for -other elements in the timeline. See #GESEditMode for details about each -edit mode. An edit may fail if it would place one of these properties -out of bounds, or if it would place the timeline in an unsupported -configuration. + See ges_timeline_element_edit_full(), which also gives an error. -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the edit position may be set -to the edge of some element in the neighbourhood of @position. - -@new_layer_priority can be used to switch @self, and other elements -moved by the edit, to a new layer. New layers may be be created if the -the corresponding layer priority/index does not yet exist for the -timeline. - -@layers can be used as a whitelist to limit changes to elements that -exist in the corresponding layers. If you intend to also switch -elements between layers, then you must ensure that all the involved -layers are included for the switch to succeed (with the exception of -layers may be newly created). +Note that the @layers argument is currently ignored, so you should +just pass %NULL. %TRUE if the edit of @self completed, %FALSE on failure. @@ -9574,7 +10390,7 @@ layers may be newly created). A whitelist of layers where the edit can be performed, %NULL allows all layers in the -timeline +timeline. @@ -9594,7 +10410,60 @@ moved to. -1 means no move The edit position: a new location for the edge of @self -(in nanoseconds) +(in nanoseconds) in the timeline coordinates + + + + + + Edits the element within its timeline by adjusting its +#GESTimelineElement:start, #GESTimelineElement:duration or +#GESTimelineElement:in-point, and potentially doing the same for +other elements in the timeline. See #GESEditMode for details about each +edit mode. An edit may fail if it would place one of these properties +out of bounds, or if it would place the timeline in an unsupported +configuration. + +Note that if you act on a #GESTrackElement, this will edit its parent +#GESClip instead. Moreover, for any #GESTimelineElement, if you select +#GES_EDGE_NONE for #GES_EDIT_MODE_NORMAL or #GES_EDIT_MODE_RIPPLE, this +will edit the toplevel instead, but still in such a way as to make the +#GESTimelineElement:start of @self reach the edit @position. + +Note that if the element's timeline has a +#GESTimeline:snapping-distance set, then the edit position may be +snapped to the edge of some element under the edited element. + +@new_layer_priority can be used to switch @self, and other elements +moved by the edit, to a new layer. New layers may be be created if the +the corresponding layer priority/index does not yet exist for the +timeline. + + + %TRUE if the edit of @self completed, %FALSE on failure. + + + + + The #GESTimelineElement to edit + + + + The priority/index of the layer @self should be +moved to. -1 means no move + + + + The edit mode + + + + The edge of @self where the edit should occur + + + + The edit position: a new location for the edge of @self +(in nanoseconds) in the timeline coordinates @@ -10023,13 +10892,8 @@ will no longer be registered as a child property for the element. Edits the start time of an element within its timeline in ripple mode. -The element is shifted to @start, and later elements are also shifted -by the same amount (see #GES_EDIT_MODE_RIPPLE). An edit may fail if it -would place the timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and +#GES_EDGE_NONE. %TRUE if the ripple edit of @self completed, %FALSE on @@ -10049,15 +10913,8 @@ failure. Edits the end time of an element within its timeline in ripple mode. -The element's duration time is shifted until its end time matches @end, -and later elements have their start time shifted by the same amount -(see #GES_EDIT_MODE_RIPPLE). An edit may fail if it would place the -duration time out of bounds, or if it would place the timeline in an -unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the end time may be set -to the edge of some element in the neighbourhood of @end. +See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and +#GES_EDGE_END. %TRUE if the ripple edit of @self completed, %FALSE on @@ -10077,15 +10934,8 @@ failure. Edits the end time of an element within its timeline in roll mode. -The end of the element is trimmed to @end, and any other element whose -start edge matched the end edge of the element is also trimmed to @end -(see #GES_EDIT_MODE_ROLL). An edit may fail if it would place an -in-point time or duration time out of bounds, or if it would place the -timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the end time may be set -to the edge of some element in the neighbourhood of @end. +See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and +#GES_EDGE_END. %TRUE if the roll edit of @self completed, %FALSE on failure. @@ -10104,15 +10954,8 @@ to the edge of some element in the neighbourhood of @end. Edits the start time of an element within its timeline in roll mode. -The element is trimmed to @start, and any other element whose end edge -matched the start edge of the element is also trimmed to @start (see -#GES_EDIT_MODE_ROLL). An edit may fail if it would place an in-point -time or duration time out of bounds, or if it would place the timeline -in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and +#GES_EDGE_START. %TRUE if the roll edit of @self completed, %FALSE on failure. @@ -10153,20 +10996,8 @@ name/value pairs, followed by %NULL - Sets the property of a child of the element. - -@property_name can either be in the format "prop-name" or -"TypeName::prop-name", where "prop-name" is the name of the property -to set (as used in g_object_set()), and "TypeName" is the type name of -the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is -useful when two children of different types share the same property -name. - -The first child found with the given "prop-name" property that was -registered with ges_timeline_element_add_child_property() (and of the -type "TypeName", if it was given) will have the corresponding -property set to @value. Other children that may have also matched the -property name (and type name) are left unchanged! + See ges_timeline_element_set_child_property_full(), which also gives an +error. Note that ges_timeline_element_set_child_properties() may be more convenient for C programming. @@ -10213,6 +11044,41 @@ ges_timeline_element_add_child_property() is set to @value. + + Sets the property of a child of the element. + +@property_name can either be in the format "prop-name" or +"TypeName::prop-name", where "prop-name" is the name of the property +to set (as used in g_object_set()), and "TypeName" is the type name of +the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is +useful when two children of different types share the same property +name. + +The first child found with the given "prop-name" property that was +registered with ges_timeline_element_add_child_property() (and of the +type "TypeName", if it was given) will have the corresponding +property set to @value. Other children that may have also matched the +property name (and type name) are left unchanged! + + + %TRUE if the property was found and set. + + + + + A #GESTimelineElement + + + + The name of the child property to set + + + + The value to set the property to + + + + Sets several of the children properties of the element. See ges_timeline_element_set_child_property(). @@ -10237,17 +11103,16 @@ name/value pairs, followed by %NULL - Sets #GESTimelineElement:duration for the element. This may fail if it -would place the timeline in an unsupported configuration, or if the -element does not have enough internal content to last for the desired -@duration. + Sets #GESTimelineElement:duration for the element. -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the element's -#GESTimelineElement:duration may instead be adjusted around @duration -such that the edge of @self matches the edge of some other element in -the neighbourhood. In such a case, the return value will still be %TRUE -on success. +Whilst the element is part of a #GESTimeline, this is the same as +editing the element with ges_timeline_element_edit() under +#GES_EDIT_MODE_TRIM with #GES_EDGE_END. In particular, the +#GESTimelineElement:duration of the element may be snapped to a +different timeline time difference from the one given. In addition, +setting may fail if it would place the timeline in an unsupported +configuration, or the element does not have enough internal content to +last the desired duration. %TRUE if @duration could be set for @self. @@ -10390,14 +11255,15 @@ be used. - Sets #GESTimelineElement:start for the element. This may fail if it -would place the timeline in an unsupported configuration. + Sets #GESTimelineElement:start for the element. If the element has a +parent, this will also move its siblings with the same shift. -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the element's -#GESTimelineElement:start may instead be set to the edge of some other -element in the neighbourhood of @start. In such a case, the return -value will still be %TRUE on success. +Whilst the element is part of a #GESTimeline, this is the same as +editing the element with ges_timeline_element_edit() under +#GES_EDIT_MODE_NORMAL with #GES_EDGE_NONE. In particular, the +#GESTimelineElement:start of the element may be snapped to a different +timeline time from the one given. In addition, setting may fail if it +would place the timeline in an unsupported configuration. %TRUE if @start could be set for @self. @@ -10447,15 +11313,8 @@ will need to call this function twice: first to set the timeline to Edits the start time of an element within its timeline in trim mode. -The element is shifted to @start, and its in-point time is similarly -shifted to ensure that its internal content will appear at the same -timeline time when it is played (see #GES_EDIT_MODE_TRIM). An edit may -fail if it would place the in-point time out of bounds, or if it would -place the timeline in an unsupported configuration. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the start time may be set -to the edge of some element in the neighbourhood of @start. +See ges_timeline_element_edit() with #GES_EDIT_MODE_TRIM and +#GES_EDGE_START. %TRUE if the trim edit of @self completed, %FALSE on failure. @@ -11032,8 +11891,30 @@ not the case. + + + + + + + + + + + + + + + + + + + + + + - + @@ -11781,6 +12662,24 @@ ges_track_set_create_element_for_gap_func() on the returned track. + See ges_track_add_element(), which also gives an error. + + + %TRUE if @object was successfully added to @track. + + + + + A #GESTrack + + + + The element to add + + + + + Adds the given track element to the track, which takes ownership of the element. @@ -11908,6 +12807,24 @@ it does not belong to a timeline. + See ges_track_remove_element_full(), which also returns an error. + + + %TRUE if @object was successfully removed from @track. + + + + + A #GESTrack + + + + The element to remove + + + + + Removes the given track element from the track, which revokes ownership of the element. @@ -12188,7 +13105,17 @@ Most users will not have to work directly with track elements since a #GESClip will automatically create track elements for its timeline's tracks and take responsibility for updating them. The only track elements that are not automatically created by clips, but a user is -likely to want to create, are #GESEffect-s. +likely to want to create, are #GESEffect-s. + +## Control Bindings for Children Properties + +You can set up control bindings for a track element child property +using ges_track_element_set_control_source(). A +#GstTimedValueControlSource should specify the timed values using the +internal source coordinates (see #GESTimelineElement). By default, +these will be updated to lie between the #GESTimelineElement:in-point +and out-point of the element. This can be switched off by setting +#GESTrackElement:auto-clamp-control-sources to %FALSE. @@ -12340,6 +13267,34 @@ writeable properties + + Clamp the #GstTimedValueControlSource for the specified child property +to lie between the #GESTimelineElement:in-point and out-point of the +element. The out-point is the #GES_TIMELINE_ELEMENT_END of the element +translated from the timeline coordinates to the internal source +coordinates of the element. + +If the property does not have a #GstTimedValueControlSource set by +ges_track_element_set_control_source(), nothing happens. Otherwise, if +a timed value for the control source lies before the in-point of the +element, or after its out-point, then it will be removed. At the +in-point and out-point times, a new interpolated value will be placed. + + + + + + + A #GESTrackElement + + + + The name of the child property to clamp the control +source of + + + + Edits the element within its track. use #ges_timeline_element_edit instead. @@ -12400,6 +13355,21 @@ for @trackelement. + + Gets #GESTrackElement:auto-clamp-control-sources. + + + Whether the control sources for the child properties of +@object are automatically clamped. + + + + + A #GESTrackElement + + + + Gets properties of a child of @object. Use #ges_timeline_element_get_child_properties @@ -12630,6 +13600,33 @@ or %NULL if it does not belong to a track. + + Get whether the given track element is a core track element. That is, +it was created by the @create_track_elements #GESClipClass method for +some #GESClip. + +Note that such a track element can only be added to a clip that shares +the same #GESAsset as the clip that created it. For example, you are +allowed to move core children between clips that resulted from +ges_container_ungroup(), but you could not move the core child from a +#GESUriClip to a #GESTitleClip or another #GESUriClip with a different +#GESUriClip:uri. + +Moreover, if a core track element is added to a clip, it will always be +added as a core child. Therefore, if this returns %TRUE, then @element +will be a core child of its parent clip. + + + %TRUE if @element is a core track element. + + + + + A #GESTrackElement + + + + Gets an array of #GParamSpec* for all configurable properties of the children of @object. @@ -12732,6 +13729,25 @@ binding from + + Sets #GESTrackElement:auto-clamp-control-sources. If set to %TRUE, this +will immediately clamp all the control sources. + + + + + + + A #GESTrackElement + + + + Whether to automatically clamp the control sources for the +child properties of @object + + + + Sets a property of a child of @object. If there are various child elements that have the same property name, you can distinguish them using the following @@ -12913,6 +13929,18 @@ set to %FALSE, this method will also set the the output of the track. + + Whether the control sources on the element (see +ges_track_element_set_control_source()) will be automatically +updated whenever the #GESTimelineElement:in-point or out-point of the +element change in value. + +See ges_track_element_clamp_control_source() for how this is done +per control source. + +Default value: %TRUE + + This property is used to determine whether the 'internal time' properties of the element have any meaning. In particular, unless @@ -14341,9 +15369,6 @@ account. - - - @@ -14693,6 +15718,20 @@ After this call GES should not be used until another ges_init() call. + + Return a string representation of @mode. + + + a string representation of @mode. + + + + + a #GESEditMode + + + + Get the best formatter for @uri. It tries to find a formatter compatible with @uri extension, if none is found, it returns the default diff --git a/gir-files/Gst-1.0.gir b/gir-files/Gst-1.0.gir index defa1873c..3eaac7897 100644 --- a/gir-files/Gst-1.0.gir +++ b/gir-files/Gst-1.0.gir @@ -898,12 +898,15 @@ of their segment. a SEGMENT_START have posted a SEGMENT_DONE. * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change -in the stream duration. The default bin behaviour is to clear any -cached duration values so that the next duration query will perform -a full duration recalculation. The duration change is posted to the +in the stream duration. The duration change is posted to the application so that it can refetch the new duration with a duration query. Note that these messages can be posted before the bin is -prerolled, in which case the duration query might fail. +prerolled, in which case the duration query might fail. Note also that +there might be a discrepancy (due to internal buffering/queueing) between the +stream being currently displayed and the returned duration query. +Applications might want to also query for duration (and changes) by +listening to the GST_MESSAGE_STREAM_START message, signaling the active start +of a (new) stream. * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it can no longer provide a clock. The default bin behaviour is to @@ -928,11 +931,8 @@ the parent of the bin. A #GstBin implements the following default behaviour for answering to a #GstQuery: -* GST_QUERY_DURATION:If the query has been asked before with the same format -and the bin is a toplevel bin (ie. has no parent), -use the cached previous value. If no previous value was cached, the -query is sent to all sink elements in the bin and the MAXIMUM of all -values is returned. If the bin is a toplevel bin the value is cached. +* GST_QUERY_DURATION: The bin will forward the query to all sink +elements contained within and will return the maximum value. If no sinks are available in the bin, the query fails. * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the @@ -9408,7 +9408,7 @@ not be extended or allocated using a custom allocator. time since Epoch, but using International Atomic Time - as reference (Since 1.18) + as reference (Since: 1.18) @@ -17817,6 +17817,25 @@ check the name of a custom event. + + Checks if @event has the given @name. This function is usually used to +check the name of a custom event. + + + %TRUE if @name matches the name of the event structure. + + + + + The #GstEvent. + + + + name to check as a GQuark + + + + Get the format, minsize, maxsize and async-flag in the buffersize event. @@ -33473,7 +33492,9 @@ producer of the value and the consumer of the value. A #GstPromise is created with gst_promise_new() by the consumer and passed to the producer to avoid thread safety issues with the change callback. A #GstPromise can be replied to with a value (or an error) by the producer -with gst_promise_reply(). gst_promise_interrupt() is for the consumer to +with gst_promise_reply(). The exact value returned is defined by the API +contract of the producer and %NULL may be a valid reply. +gst_promise_interrupt() is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The @GST_PROMISE_RESULT_EXPIRED state set by a call to gst_promise_expire() indicates to the consumer that a value will never @@ -33570,7 +33591,7 @@ message is handled and/or destroyed (possibly unanswered). Retrieve the reply set on @promise. @promise must be in %GST_PROMISE_RESULT_REPLIED and the returned structure is owned by @promise - + The reply set on @promise @@ -33612,7 +33633,7 @@ is not visible to the consumer. a #GstPromise - + a #GstStructure with the the reply contents @@ -37662,45 +37683,90 @@ info to stream time (which is always between 0 and the duration of the stream).< - the playback rate of the segment + the playback rate of the segment is set in response to a seek + event and, without any seek, the value should be `1.0`. This + value is used by elements that synchronize buffer [running + times](additional/design/synchronisation.md#running-time) on + the clock (usually the sink elements), leading to consuming + buffers faster (for a value `> 1.0`) or slower (for `0.0 < + value < 1.0`) than normal playback speed. The rate also + defines the playback direction, meaning that when the value is + lower than `0.0`, the playback happens in reverse, and the + [stream-time](additional/design/synchronisation.md#stream-time) + is going backward. The `rate` value should never be `0.0`. - the already applied rate to the segment + The applied rate is the rate that has been applied to the stream. + The effective/resulting playback rate of a stream is + `rate * applied_rate`. + The applied rate can be set by source elements when a server is + sending the stream with an already modified playback speed + rate. Filter elements that modify the stream in a way that + modifies the playback speed should also modify the applied + rate. For example the #videorate element when its + #videorate:rate property is set will set the applied rate of + the segment it pushed downstream. Also #scaletempo applies the + input segment rate to the stream and outputs a segment with + rate=1.0 and applied_rate=<inputsegment.rate>. - the format of the segment values + the unit used for all of the segment's values. - the running time (plus elapsed time, see offset) of the segment start + the running time (plus elapsed time, see offset) of the + segment [start](GstSegment.start) ([stop](GstSegment.stop) if + rate < 0.0). - the amount (in buffer timestamps) that has already been elapsed in - the segment + the offset expresses the elapsed time (in buffer timestamps) + before a seek with its start (stop if rate < 0.0) seek type + set to #GST_SEEK_TYPE_NONE, the value is set to the position + of the segment at the time of the seek. - the start of the segment in buffer timestamp time (PTS) + the start time of the segment (in buffer timestamps) + [(PTS)](GstBuffer.pts), that is the timestamp of the first + buffer to output inside the segment (last one during + reverse playback). For example decoders will + [clip](gst_segment_clip) out the buffers before the start + time. - the stop of the segment in buffer timestamp time (PTS) + the stop time of the segment (in buffer timestamps) + [(PTS)](GstBuffer.pts), that is the timestamp of the last + buffer to output inside the segment (first one during + reverse playback). For example decoders will + [clip](gst_segment_clip) out buffers after the stop time. - the stream time of the segment start + the stream time of the segment [start](GstSegment.start) + ([stop](GstSegment.stop) if rate < 0.0). - the buffer timestamp position in the segment (used internally by - elements such as sources, demuxers or parsers to track progress) + the buffer timestamp position in the segment is supposed to be + updated by elements such as sources, demuxers or parsers to + track progress by setting it to the last pushed buffer' end time + ([timestamp](GstBuffer.pts) + #GstBuffer.duration) for that + specific segment. The position is used when reconfiguring the + segment with #gst_segment_do_seek when the seek is only + updating the segment (see [offset](GstSegment.offset)). - the duration of the stream + the duration of the segment is the maximum absolute difference + between #GstSegment.start and #GstSegment.stop if stop is not + set, otherwise it should be the difference between those + two values. This should be set by elements that know the + overall stream duration (like demuxers) and will be used when + seeking with #GST_SEEK_TYPE_END. diff --git a/gir-files/GstAudio-1.0.gir b/gir-files/GstAudio-1.0.gir index 0ea4d0543..eb681f1a2 100644 --- a/gir-files/GstAudio-1.0.gir +++ b/gir-files/GstAudio-1.0.gir @@ -691,7 +691,7 @@ return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK). - + List of all audio formats, for use in template caps strings. @@ -8552,17 +8552,6 @@ All scheduling of samples and timestamps is done in this base class together with #GstAudioBaseSink using a default implementation of a #GstAudioRingBuffer that uses threads. - - - - - - - - - - - @@ -8839,6 +8828,13 @@ together with #GstAudioBaseSink using a default implementation of a + + class extension structure. Since: 1.18 + + + + + @@ -8852,11 +8848,6 @@ together with #GstAudioBaseSink using a default implementation of a - - - - - This is the most simple base class for audio sources that only requires @@ -10161,6 +10152,22 @@ string is not a known format. + + Return all the raw audio formats supported by GStreamer. + + + an array of #GstAudioFormat + + + + + + + the number of elements in the returned array + + + + Returns a reorder map for @from to @to that can be used in custom channel reordering code, e.g. to convert from or to the @@ -10259,6 +10266,32 @@ otherwise. + + Return a generic raw audio caps for formats defined in @formats. +If @formats is %NULL returns a caps for all the supported raw audio formats, +see gst_audio_formats_raw(). + + + an audio @GstCaps + + + + + an array of raw #GstAudioFormat, or %NULL + + + + + + the size of @formats + + + + the layout of audio samples + + + + diff --git a/gir-files/GstBase-1.0.gir b/gir-files/GstBase-1.0.gir index 5f19a892e..86c762a4f 100644 --- a/gir-files/GstBase-1.0.gir +++ b/gir-files/GstBase-1.0.gir @@ -1487,7 +1487,7 @@ downstream. - + diff --git a/gir-files/GstCheck-1.0.gir b/gir-files/GstCheck-1.0.gir index 76ad41527..1da5418de 100644 --- a/gir-files/GstCheck-1.0.gir +++ b/gir-files/GstCheck-1.0.gir @@ -2347,7 +2347,7 @@ MT safe. A "crank" consists of three steps: 1: Wait for a #GstClockID to be registered with the #GstTestClock. 2: Advance the #GstTestClock to the time the #GstClockID is waiting, unless - the clock time is already passed the clock id (Since 1.18). + the clock time is already passed the clock id (Since: 1.18). 3: Release the #GstClockID wait. A "crank" can be though of as the notion of manually driving the clock forward to its next logical step. diff --git a/gir-files/GstGL-1.0.gir b/gir-files/GstGL-1.0.gir index df7ec3980..24a813fb1 100644 --- a/gir-files/GstGL-1.0.gir +++ b/gir-files/GstGL-1.0.gir @@ -1054,7 +1054,7 @@ function to allocate and OpenGL resources needed for your application to the texture - + #GstGLBaseSrc handles the nitty gritty details of retrieving an OpenGL context. It also provided some wrappers around #GstBaseSrc's `start()` and `stop()` virtual methods that ensure an OpenGL context is available and @@ -1131,7 +1131,7 @@ current in the calling thread. - + The base class for GStreamer GL Video sources. @@ -3315,10 +3315,12 @@ single input and producing a single output with a #GstGLFramebuffer a #GstGLFilter - + + an input buffer - + + an output buffer @@ -3399,11 +3401,11 @@ any shaders, viewport state, etc must be setup by the caller. a #GstGLFilter - + an input buffer - + an output buffer @@ -3584,10 +3586,12 @@ See also: gst_gl_filter_render_to_target() a #GstGLFilter - + + an input buffer - + + an output buffer @@ -7141,6 +7145,7 @@ gst_gl_upload_set_caps() creating a new #GstBuffer in @outbuf_ptr. This element requires a reconfiguration. + private return value. @@ -8295,25 +8300,32 @@ have been executed when this function returns. - + + Notify a @window about a scroll event. A scroll signal holding the event +coordinates will be emitted. + a #GstGLWindow + x position of the mouse cursor + y position of the mouse cursor + the x offset of the scroll event + the y offset of the scroll event @@ -9177,6 +9189,10 @@ user-defined purposes. + + + + The currently supported formats that can be converted @@ -9469,6 +9485,10 @@ user-defined purposes. + + + + List of video formats that are supported by #GstGLMemory diff --git a/gir-files/GstRtsp-1.0.gir b/gir-files/GstRtsp-1.0.gir index cbeff02ad..5a39e6a65 100644 --- a/gir-files/GstRtsp-1.0.gir +++ b/gir-files/GstRtsp-1.0.gir @@ -3510,15 +3510,13 @@ g_strfreev() when no longer needed. - + Get a newly allocated string describing the request URI for @url combined with the control path for @control_path a string with the request URI combined with the control path. -g_free() after usage. - -Since 1.18 +g_free() after usage. diff --git a/gir-files/GstRtspServer-1.0.gir b/gir-files/GstRtspServer-1.0.gir index fcd1028d0..45d07c35e 100644 --- a/gir-files/GstRtspServer-1.0.gir +++ b/gir-files/GstRtspServer-1.0.gir @@ -3657,6 +3657,20 @@ g_object_unref() after usage. + + Get the configured DSCP QoS of attached media. + + + the DSCP QoS value of attached streams or -1 if disabled. + + + + + a #GstRTSPMedia + + + + Get the element that was used when constructing @media. @@ -4297,6 +4311,23 @@ INADDR_ANY. + + Configure the dscp qos of attached streams to @dscp_qos. + + + + + + + a #GstRTSPMedia + + + + a new dscp qos value (0-63, or -1 to disable) + + + + Set or unset if an EOS event will be sent to the pipeline for @media before it is unprepared. @@ -4733,6 +4764,9 @@ when the media was not in the suspended state. + + + @@ -5416,6 +5450,20 @@ of all medias created from this factory. + + Get the configured media DSCP QoS. + + + the media DSCP QoS value or -1 if disabled. + + + + + a #GstRTSPMediaFactory + + + + Get the latency that is used for receiving media @@ -5728,6 +5776,23 @@ receiving media + + Configure the media dscp qos to @dscp_qos. + + + + + + + a #GstRTSPMediaFactory + + + + a new dscp qos value (0-63, or -1 to disable) + + + + Configure if media created from this factory will have an EOS sent to the pipeline before shutdown. @@ -6005,6 +6070,9 @@ when a client disconnects without sending TEARDOWN. + + + @@ -6315,6 +6383,23 @@ and called when a message has been sent on the transport. + + Function registered with gst_rtsp_stream_transport_set_message_sent_full() +and called when a message has been sent on the transport. + + + + + + + + + + user data + + + + Creates a #GstRTSPMediaFactory object for a given url. @@ -10358,7 +10443,7 @@ It remains valid for as long as @trans is valid. - Signal the installed message_sent callback for @trans. + Signal the installed message_sent / message_sent_full callback for @trans. @@ -10594,6 +10679,31 @@ to a client. This is usually used when sending RTP/RTCP over TCP. + + Install a callback that will be called when a message has been sent on @trans. + + + + + + + a #GstRTSPStreamTransport + + + + a callback called when a message has been sent + + + + user data passed to callback + + + + called with the user_data when no longer needed + + + + Set the timed out state of @trans to @timedout diff --git a/gir-files/GstVideo-1.0.gir b/gir-files/GstVideo-1.0.gir index 466ffa4dd..d62acdef5 100644 --- a/gir-files/GstVideo-1.0.gir +++ b/gir-files/GstVideo-1.0.gir @@ -1485,7 +1485,7 @@ gst_navigation_event_parse_command() to extract the details from the event. A mouse scroll event. Use gst_navigation_event_parse_mouse_scroll_event() to extract the details from -the event. +the event. (Since: 1.18) @@ -3457,7 +3457,7 @@ and SMPTE ST2016-1 - + Enumeration of the different standards that may apply to AFD data: 0) ETSI/DVB: @@ -3466,9 +3466,7 @@ https://www.etsi.org/deliver/etsi_ts/101100_101199/101154/02.01.01_60/ts_101154v 1) ATSC A/53: https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf -2) SMPTE ST2016-1: - -Since 1.18 +2) SMPTE ST2016-1: AFD value is from DVB/ETSI standard @@ -15819,6 +15817,22 @@ the #GstVideoFormat if there is one, or NULL otherwise. + + Return all the raw video formats supported by GStreamer. + + + an array of #GstVideoFormat + + + + + + + the number of elements in the returned array + + + + @@ -15891,6 +15905,55 @@ recognised, and %FALSE otherwise. + + Return a generic raw video caps for formats defined in @formats. +If @formats is %NULL returns a caps for all the supported raw video formats, +see gst_video_formats_raw(). + + + a video @GstCaps + + + + + an array of raw #GstVideoFormat, or %NULL + + + + + + the size of @formats + + + + + + Return a generic raw video caps for formats defined in @formats with features +@features. +If @formats is %NULL returns a caps for all the supported video formats, +see gst_video_formats_raw(). + + + a video @GstCaps + + + + + an array of raw #GstVideoFormat, or %NULL + + + + + + the size of @formats + + + + the #GstCapsFeatures to set on the caps + + + + Extract #GstVideoMasteringDisplayInfo from @mastering diff --git a/gir-files/GstWebRTC-1.0.gir b/gir-files/GstWebRTC-1.0.gir index 756ecc685..4fd6b1516 100644 --- a/gir-files/GstWebRTC-1.0.gir +++ b/gir-files/GstWebRTC-1.0.gir @@ -8,6 +8,20 @@ and/or use gtk-doc annotations. --> + + + + + + + + + + + + + + @@ -78,6 +92,41 @@ and/or use gtk-doc annotations. --> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -322,6 +371,407 @@ for more information. connected + + + + Close the @channel. + + + + + + + a #GstWebRTCDataChannel + + + + + + Send @data as a data message over @channel. + + + + + + + a #GstWebRTCDataChannel + + + + a #GBytes or %NULL + + + + + + Send @str as a string message over @channel. + + + + + + + a #GstWebRTCDataChannel + + + + a string or %NULL + + + + + + Close the @channel. + + + + + + + a #GstWebRTCDataChannel + + + + + + Signal that the data channel reached a low buffered amount. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + + + Signal that the data channel was closed. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + + + Signal that the data channel had an error. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + a #GError + + + + + + Signal that the data channel received a data message. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + a #GBytes or %NULL + + + + + + Signal that the data channel received a string message. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + a string or %NULL + + + + + + Signal that the data channel was opened. Should only be used by subclasses. + + + + + + + a #GstWebRTCDataChannel + + + + + + Send @data as a data message over @channel. + + + + + + + a #GstWebRTCDataChannel + + + + a #GBytes or %NULL + + + + + + Send @str as a string message over @channel. + + + + + + + a #GstWebRTCDataChannel + + + + a string or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Close the data channel + + + + + + + + + + + + + + + + + + + + + the #GError thrown + + + + + + + + + + + a #GBytes of the data received + + + + + + + + + + + the data received as a string + + + + + + + + + + + + + + + + a #GBytes with the data + + + + + + + + + + + the data to send as a string + + + + + + + + + + + + + + + + + + + a #GstWebRTCDataChannel + + + + a #GBytes or %NULL + + + + + + + + + + + + + + a #GstWebRTCDataChannel + + + + a string or %NULL + + + + + + + + + + + + + + a #GstWebRTCDataChannel + + + + + + + + + + + GST_WEBRTC_DATA_CHANNEL_STATE_NEW: new GST_WEBRTC_DATA_CHANNEL_STATE_CONNECTING: connection