ges: Update documentation

And start generating TrackElement children property with a stupid
simple script
This commit is contained in:
Thibault Saunier 2020-04-09 09:29:17 -04:00
parent c8383d69ca
commit 4a9e2c8984
23 changed files with 782 additions and 66 deletions

3
docs/deprecated.md Normal file
View file

@ -0,0 +1,3 @@
# Deprecated APIS
Those APIs have been deprecated and shouldn't be used in newly written code.

View file

@ -0,0 +1,32 @@
#### `freq`
Frequency of test signal. The sample rate needs to be at least 2 times higher.
Value type: #gdouble
See #audiotestsrc:freq
#### `mute`
mute channel
Value type: #gboolean
See #volume:mute
#### `volume`
volume factor, 1.0=100%
Value type: #gdouble
See #volume:volume
#### `volume`
Volume of test signal
Value type: #gdouble
See #audiotestsrc:volume

View file

@ -0,0 +1,16 @@
#### `mute`
mute channel
Value type: #gboolean
See #volume:mute
#### `volume`
volume factor, 1.0=100%
Value type: #gdouble
See #volume:volume

View file

@ -0,0 +1,256 @@
#### `alpha`
alpha of the stream
Value type: #gdouble
#### `color`
Color to use for text (big-endian ARGB).
Value type: #guint
See #timeoverlay:color
#### `fields`
Fields to use for deinterlacing
Valid values:
- **All fields** (0) all
- **Top fields only** (1) top
- **Bottom fields only** (2) bottom
- **Automatically detect** (3) auto
See #deinterlace:fields
#### `font-desc`
Pango font description of font to be used for rendering. See documentation of
pango_font_description_from_string for syntax.
Value type: #gchararray
See #timeoverlay:font-desc
#### `foreground-color`
Foreground color to use (big-endian ARGB)
Value type: #guint
See #videotestsrc:foreground-color
#### `halignment`
Horizontal alignment of the text
Valid values:
- **left** (0) left
- **center** (1) center
- **right** (2) right
- **position** (4) Absolute position clamped to canvas
- **absolute** (5) Absolute position
See #timeoverlay:halignment
#### `height`
height of the source
Value type: #gint
#### `mode`
Deinterlace Mode
Valid values:
- **Auto detection (best effort)** (0) auto
- **Force deinterlacing** (1) interlaced
- **Run in passthrough mode** (2) disabled
- **Auto detection (strict)** (3) auto-strict
See #deinterlace:mode
#### `outline-color`
Color to use for outline the text (big-endian ARGB).
Value type: #guint
See #timeoverlay:outline-color
#### `pattern`
Type of test pattern to generate
Valid values:
- **SMPTE 100% color bars** (0) smpte
- **Random (television snow)** (1) snow
- **100% Black** (2) black
- **100% White** (3) white
- **Red** (4) red
- **Green** (5) green
- **Blue** (6) blue
- **Checkers 1px** (7) checkers-1
- **Checkers 2px** (8) checkers-2
- **Checkers 4px** (9) checkers-4
- **Checkers 8px** (10) checkers-8
- **Circular** (11) circular
- **Blink** (12) blink
- **SMPTE 75% color bars** (13) smpte75
- **Zone plate** (14) zone-plate
- **Gamut checkers** (15) gamut
- **Chroma zone plate** (16) chroma-zone-plate
- **Solid color** (17) solid-color
- **Moving ball** (18) ball
- **SMPTE 100% color bars** (19) smpte100
- **Bar** (20) bar
- **Pinwheel** (21) pinwheel
- **Spokes** (22) spokes
- **Gradient** (23) gradient
- **Colors** (24) colors
See #videotestsrc:pattern
#### `posx`
x position of the stream
Value type: #gint
#### `posy`
y position of the stream
Value type: #gint
#### `shaded-background`
Whether to shade the background under the text area
Value type: #gboolean
See #timeoverlay:shaded-background
#### `text`
Text to be display.
Value type: #gchararray
See #timeoverlay:text
#### `text-height`
Resulting height of font rendering
Value type: #guint
See #timeoverlay:text-height
#### `text-width`
Resulting width of font rendering
Value type: #guint
See #timeoverlay:text-width
#### `text-x`
Resulting X position of font rendering.
Value type: #gint
See #timeoverlay:text-x
#### `text-y`
Resulting X position of font rendering.
Value type: #gint
See #timeoverlay:text-y
#### `tff`
Deinterlace top field first
Valid values:
- **Auto detection** (0) auto
- **Top field first** (1) tff
- **Bottom field first** (2) bff
See #deinterlace:tff
#### `valignment`
Vertical alignment of the text
Valid values:
- **baseline** (0) baseline
- **bottom** (1) bottom
- **top** (2) top
- **position** (3) Absolute position clamped to canvas
- **center** (4) center
- **absolute** (5) Absolute position
See #timeoverlay:valignment
#### `video-direction`
Video direction: rotation and flipping
Valid values:
- **GST_VIDEO_ORIENTATION_IDENTITY** (0) identity
- **GST_VIDEO_ORIENTATION_90R** (1) 90r
- **GST_VIDEO_ORIENTATION_180** (2) 180
- **GST_VIDEO_ORIENTATION_90L** (3) 90l
- **GST_VIDEO_ORIENTATION_HORIZ** (4) horiz
- **GST_VIDEO_ORIENTATION_VERT** (5) vert
- **GST_VIDEO_ORIENTATION_UL_LR** (6) ul-lr
- **GST_VIDEO_ORIENTATION_UR_LL** (7) ur-ll
- **GST_VIDEO_ORIENTATION_AUTO** (8) auto
- **GST_VIDEO_ORIENTATION_CUSTOM** (9) custom
See #videoflip:video-direction
#### `width`
width of the source
Value type: #gint
#### `x-absolute`
Horizontal position when using absolute alignment
Value type: #gdouble
See #timeoverlay:x-absolute
#### `xpos`
Horizontal position when using clamped position alignment
Value type: #gdouble
See #timeoverlay:xpos
#### `y-absolute`
Vertical position when using absolute alignment
Value type: #gdouble
See #timeoverlay:y-absolute
#### `ypos`
Vertical position when using clamped position alignment
Value type: #gdouble
See #timeoverlay:ypos

View file

@ -0,0 +1,16 @@
#### `border`
The border width
Value type: #guint
See #GESVideoTransition:border
#### `invert`
Whether the transition is inverted
Value type: #gboolean
See #GESVideoTransition:invert

View file

@ -0,0 +1,213 @@
#### `alpha`
alpha of the stream
Value type: #gdouble
#### `background-color`
Background color to use (big-endian ARGB)
Value type: #guint
See #videotestsrc:background-color
#### `fields`
Fields to use for deinterlacing
Valid values:
- **All fields** (0) all
- **Top fields only** (1) top
- **Bottom fields only** (2) bottom
- **Automatically detect** (3) auto
See #deinterlace:fields
#### `font-desc`
Pango font description of font to be used for rendering. See documentation of
pango_font_description_from_string for syntax.
Value type: #gchararray
See #timeoverlay:font-desc
#### `foreground-color`
Foreground color to use (big-endian ARGB)
Value type: #guint
See #videotestsrc:foreground-color
#### `halignment`
Horizontal alignment of the text
Valid values:
- **left** (0) left
- **center** (1) center
- **right** (2) right
- **position** (4) Absolute position clamped to canvas
- **absolute** (5) Absolute position
See #timeoverlay:halignment
#### `height`
height of the source
Value type: #gint
#### `mode`
Deinterlace Mode
Valid values:
- **Auto detection (best effort)** (0) auto
- **Force deinterlacing** (1) interlaced
- **Run in passthrough mode** (2) disabled
- **Auto detection (strict)** (3) auto-strict
See #deinterlace:mode
#### `pattern`
Type of test pattern to generate
Valid values:
- **SMPTE 100% color bars** (0) smpte
- **Random (television snow)** (1) snow
- **100% Black** (2) black
- **100% White** (3) white
- **Red** (4) red
- **Green** (5) green
- **Blue** (6) blue
- **Checkers 1px** (7) checkers-1
- **Checkers 2px** (8) checkers-2
- **Checkers 4px** (9) checkers-4
- **Checkers 8px** (10) checkers-8
- **Circular** (11) circular
- **Blink** (12) blink
- **SMPTE 75% color bars** (13) smpte75
- **Zone plate** (14) zone-plate
- **Gamut checkers** (15) gamut
- **Chroma zone plate** (16) chroma-zone-plate
- **Solid color** (17) solid-color
- **Moving ball** (18) ball
- **SMPTE 100% color bars** (19) smpte100
- **Bar** (20) bar
- **Pinwheel** (21) pinwheel
- **Spokes** (22) spokes
- **Gradient** (23) gradient
- **Colors** (24) colors
See #videotestsrc:pattern
#### `posx`
x position of the stream
Value type: #gint
#### `posy`
y position of the stream
Value type: #gint
#### `text-width`
Resulting width of font rendering
Value type: #guint
See #timeoverlay:text-width
#### `text-x`
Resulting X position of font rendering.
Value type: #gint
See #timeoverlay:text-x
#### `text-y`
Resulting X position of font rendering.
Value type: #gint
See #timeoverlay:text-y
#### `tff`
Deinterlace top field first
Valid values:
- **Auto detection** (0) auto
- **Top field first** (1) tff
- **Bottom field first** (2) bff
See #deinterlace:tff
#### `time-mode`
What time to show
Valid values:
- **buffer-time** (0) buffer-time
- **stream-time** (1) stream-time
- **running-time** (2) running-time
- **time-code** (3) time-code
See #timeoverlay:time-mode
#### `use-time-overlay`
Use time overlay, setting a child property corresponding toGstTimeOverlay will
switch this on by default.
Value type: #gboolean
See #GESVideoTestSource:use-time-overlay
#### `valignment`
Vertical alignment of the text
Valid values:
- **baseline** (0) baseline
- **bottom** (1) bottom
- **top** (2) top
- **position** (3) Absolute position clamped to canvas
- **center** (4) center
- **absolute** (5) Absolute position
See #timeoverlay:valignment
#### `video-direction`
Video direction: rotation and flipping
Valid values:
- **GST_VIDEO_ORIENTATION_IDENTITY** (0) identity
- **GST_VIDEO_ORIENTATION_90R** (1) 90r
- **GST_VIDEO_ORIENTATION_180** (2) 180
- **GST_VIDEO_ORIENTATION_90L** (3) 90l
- **GST_VIDEO_ORIENTATION_HORIZ** (4) horiz
- **GST_VIDEO_ORIENTATION_VERT** (5) vert
- **GST_VIDEO_ORIENTATION_UL_LR** (6) ul-lr
- **GST_VIDEO_ORIENTATION_UR_LL** (7) ur-ll
- **GST_VIDEO_ORIENTATION_AUTO** (8) auto
- **GST_VIDEO_ORIENTATION_CUSTOM** (9) custom
See #videoflip:video-direction
#### `width`
width of the source
Value type: #gint

View file

@ -0,0 +1,83 @@
#### `alpha`
alpha of the stream
Value type: #gdouble
#### `fields`
Fields to use for deinterlacing
Valid values:
- **All fields** (0) all
- **Top fields only** (1) top
- **Bottom fields only** (2) bottom
- **Automatically detect** (3) auto
See #deinterlace:fields
#### `height`
height of the source
Value type: #gint
#### `mode`
Deinterlace Mode
Valid values:
- **Auto detection (best effort)** (0) auto
- **Force deinterlacing** (1) interlaced
- **Run in passthrough mode** (2) disabled
- **Auto detection (strict)** (3) auto-strict
See #deinterlace:mode
#### `posx`
x position of the stream
Value type: #gint
#### `posy`
y position of the stream
Value type: #gint
#### `tff`
Deinterlace top field first
Valid values:
- **Auto detection** (0) auto
- **Top field first** (1) tff
- **Bottom field first** (2) bff
See #deinterlace:tff
#### `video-direction`
Video direction: rotation and flipping
Valid values:
- **GST_VIDEO_ORIENTATION_IDENTITY** (0) identity
- **GST_VIDEO_ORIENTATION_90R** (1) 90r
- **GST_VIDEO_ORIENTATION_180** (2) 180
- **GST_VIDEO_ORIENTATION_90L** (3) 90l
- **GST_VIDEO_ORIENTATION_HORIZ** (4) horiz
- **GST_VIDEO_ORIENTATION_VERT** (5) vert
- **GST_VIDEO_ORIENTATION_UL_LR** (6) ul-lr
- **GST_VIDEO_ORIENTATION_UR_LL** (7) ur-ll
- **GST_VIDEO_ORIENTATION_AUTO** (8) auto
- **GST_VIDEO_ORIENTATION_CUSTOM** (9) custom
See #videoflip:video-direction
#### `width`
width of the source
Value type: #gint

View file

@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""
Simple script to update the children properties information for
GESTrackElement-s that add children properties all the time
"""
import gi
import os
import sys
import textwrap
gi.require_version("Gst", "1.0")
gi.require_version("GObject", "2.0")
gi.require_version("GES", "1.0")
from gi.repository import Gst, GES, GObject
overrides = {
"GstFramePositioner": False,
"GstBaseTextOverlay": "timeoverlay",
"GstVideoDirection": "videoflip",
"GESVideoTestSource": "GESVideoTestSource",
"GESVideoTransition": "GESVideoTransition",
}
if __name__ == "__main__":
Gst.init(None)
GES.init()
os.chdir(os.path.realpath(os.path.dirname(__file__)))
tl = GES.Timeline.new_audio_video()
layer = tl.append_layer()
elements = []
def add_clip(c, add=True):
c.props.duration = Gst.SECOND
c.props.start = layer.get_duration()
layer.add_clip(c)
if add:
elements.extend(c.children)
add_clip(GES.UriClipAsset.request_sync(Gst.filename_to_uri(os.path.join("../../", "tests/check/assets/audio_video.ogg"))).extract())
add_clip(GES.TestClip.new())
add_clip(GES.TitleClip.new())
transition = GES.TransitionClip.new_for_nick("crossfade")
add_clip(transition, False)
elements.append(transition)
for element in elements:
gtype = element.__gtype__
print(gtype)
with open(gtype.name + '-children-props.md', 'w') as f:
for prop in GES.TimelineElement.list_children_properties(element):
prefix = '#### `%s`\n\n' % (prop.name)
prefix_len = len(prefix)
lines = textwrap.wrap(prop.blurb, width=80)
doc = prefix + lines[0]
if GObject.type_is_a(prop, GObject.ParamSpecEnum.__gtype__):
lines += ["", "Valid values:"]
for value in prop.enum_class.__enum_values__.values():
lines.append(" - **%s** (%d) %s" % (value.value_name,
int(value), value.value_nick))
else:
lines += ["", "Value type: #" + prop.value_type.name]
typename = overrides.get(prop.owner_type.name, None)
if typename is not False:
if typename is None:
if GObject.type_is_a(prop.owner_type, Gst.Element):
typename = GObject.new(prop.owner_type).get_factory().get_name()
lines += ["", "See #%s:%s" % (typename, prop.name)]
if len(lines) > 1:
doc += '\n'
doc += '\n'.join(lines[1:])
print(doc + "\n", file=f)

View file

@ -6,9 +6,10 @@ gi-index
ges-uri-clip.h
ges-title-clip.h
ges-test-clip.h
ges-effect-clip.h
ges-transition-clip.h
ges-pipeline.h
ges-project.h
ges-effect.h
base-classes.md
ges-timeline-element.h
ges-container.h
@ -16,41 +17,48 @@ gi-index
ges-audio-track.h
ges-video-track.h
ges-asset.h
ges-uri-asset.h
ges-clip-asset.h
ges-effect-asset.h
ges-track-element-asset.h
ges-source-clip-asset.h
ges-effect.h
ges-extractable.h
ges-gerror.h
ges-group.h
ges-meta-container.h
ges-text-overlay.h
ges-marker-list.h
ges-formatter.h
ges-xml-formatter.h
ges-track-element.h
ges-video-source.h
ges-audio-source.h
ges-enums.h
low_level.md
ges-audio-test-source.h
ges-audio-transition.h
ges-audio-uri-source.h
ges-video-uri-source.h
ges-video-test-source.h
ges-title-source.h
ges-text-overlay.h
ges-gerror.h
ges-types.h
ges-enums.h
ges-utils.h
low_level.md
ges-base-xml-formatter.h
ges-command-line-formatter.h
ges-audio-transition.h
ges-base-effect-clip.h
ges-base-effect.h
ges-base-transition-clip.h
ges-clip-asset.h
# ges-effect-asset.h
ges-effect-clip.h
ges-image-source.h
ges-multi-file-source.h
ges-operation-clip.h
ges-operation.h
ges-overlay-clip.h
# ges-pitivi-formatter.h
ges-source-clip.h
ges-source.h
ges-text-overlay-clip.h
ges-title-source.h
ges-track-element-asset.h
ges-transition-clip.h
ges-transition.h
ges-uri-asset.h
ges-video-test-source.h
ges-video-transition.h
ges-video-uri-source.h
# ges-xml-formatter.h
ges-prelude.h
deprecated.md
ges-pitivi-formatter.h
ges-image-source.h
ges-multi-file-source.h

View file

@ -32,6 +32,9 @@ GES_DECLARE_TYPE(AudioTestSource, audio_test_source, AUDIO_TEST_SOURCE);
/**
* GESAudioTestSource:
*
* ### Children Properties
*
* {{ libs/GESAudioTestSource-children-props.md }}
*/
struct _GESAudioTestSource {

View file

@ -31,6 +31,10 @@ GES_DECLARE_TYPE(AudioUriSource, audio_uri_source, AUDIO_URI_SOURCE);
/**
* GESAudioUriSource:
*
* ### Children Properties
*
* {{ libs/GESVideoUriSource-children-props.md }}
*/
struct _GESAudioUriSource {
/*< private >*/

View file

@ -18,11 +18,13 @@
* Boston, MA 02111-1307, USA.
*/
/* SECTION: geseffectasset
/**
* SECTION: geseffectasset
* @title: GESEffectAsset
* @short_description: A GESAsset subclass specialized in GESEffect extraction
*
* This is internal, and implementation details, so we are not showing it in the
* documentation
* This asset has a GStreamer bin-description as ID and is able to determine
* to what track type the effect should be used in.
*/
#ifdef HAVE_CONFIG_H
#include "config.h"

View file

@ -18,6 +18,12 @@
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION: gessourceclipasset
* @title: GESSourceClipAsset
* @short_description: A GESAsset subclass, baseclass for #GESSourceClip-s extraction
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

View file

@ -25,22 +25,6 @@
*
* #GESTitleSource is a GESTimelineElement that implements the notion
* of titles in GES.
*
* ## Children Properties
*
* You can use the following children properties through the
* #ges_timeline_element_set_child_property and alike set of methods:
*
* - #gchar `text`: The text to be rendered
* - #guint `background`: The color of the background
* - #guint `color`: The color of the text
* - #gchar `font-desc`: Pango font description string
* - #GESTextHAlign `halignment`: Horizontal alignment of the text
* - #GESTextVAlign `valignment`: Vertical alignent of the text
* - #gdouble `xpos`: The horizontal position of the text
* - #gdouble `ypos`: The vertical position of the text
* - #gboolean `shaded-background`: Whether to shade the background under the text area
* - #guint `outline-color`: Color to use for outline the text (big-endian ARGB).
*/
#ifdef HAVE_CONFIG_H
#include "config.h"

View file

@ -32,6 +32,9 @@ GES_DECLARE_TYPE(TitleSource, title_source, TITLE_SOURCE);
/**
* GESTitleSource:
*
* ## Children Properties
*
* {{ libs/GESTitleSource-children-props.md }}
*/
struct _GESTitleSource {
GESVideoSource parent;

View file

@ -33,6 +33,10 @@ GES_DECLARE_TYPE(TransitionClip, transition_clip, TRANSITION_CLIP);
* GESTransitionClip:
* @vtype: a #GESVideoStandardTransitionType indicating the type of video transition
* to apply.
*
* ### Children Properties
*
* {{ libs/GESTransitionClip-children-props.md }}
*/
struct _GESTransitionClip {
/*< private >*/

View file

@ -18,6 +18,14 @@
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION:gestypes
* @title: GES Types
* @short_description: GStreamer Editing Services data types
*
* GStreamer Editing Services data types
*/
#pragma once
#include <glib.h>
@ -223,6 +231,9 @@ typedef struct _GESEffectAsset GESEffectAsset;
typedef struct _GESXmlFormatterClass GESXmlFormatterClass;
typedef struct _GESXmlFormatter GESXmlFormatter;
/**
* GES_DECLARE_TYPE: (attributes doc.skip=true)
*/
#define GES_DECLARE_TYPE(ObjName, obj_name, OBJ_NAME) \
GES_API GType ges_##obj_name##_get_type(void); \
G_GNUC_BEGIN_IGNORE_DEPRECATIONS \

View file

@ -19,7 +19,7 @@
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION: gesuriclipasset
* SECTION: gesuriasset
* @title: GESUriClipAsset
* @short_description: A GESAsset subclass specialized in GESUriClip extraction
*
@ -776,15 +776,6 @@ ges_uri_clip_asset_get_stream_assets (GESUriClipAsset * self)
/*****************************************************************
* GESUriSourceAsset implementation *
*****************************************************************/
/**
* SECTION: gesurisourceasset
* @title: GESUriClipAsset
* @short_description: A GESAsset subclass specialized in GESUriSource extraction
*
* NOTE: You should never request such a #GESAsset as they will be created automatically
* by #GESUriClipAsset-s.
*/
G_DEFINE_TYPE_WITH_PRIVATE (GESUriSourceAsset, ges_uri_source_asset,
GES_TYPE_TRACK_ELEMENT_ASSET);

View file

@ -85,6 +85,14 @@ const GList * ges_uri_clip_asset_get_stream_assets (GESUriClipAsset *self);
#define GES_TYPE_URI_SOURCE_ASSET ges_uri_source_asset_get_type()
GES_DECLARE_TYPE(UriSourceAsset, uri_source_asset, URI_SOURCE_ASSET);
/**
* GESUriSourceAsset:
*
* Asset to create a stream specific #GESSource for a media file.
*
* NOTE: You should never request such a #GESAsset as they will be created automatically
* by #GESUriClipAsset-s.
*/
struct _GESUriSourceAsset
{
GESTrackElementAsset parent;

View file

@ -22,23 +22,6 @@
* SECTION:gesvideosource
* @title: GESVideoSource
* @short_description: Base Class for video sources
*
* ## Children Properties:
*
* You can use the following children properties through the
* #ges_track_element_set_child_property and alike set of methods:
*
* - #gdouble `alpha`: The desired alpha for the stream.
* - #gint `posx`: The desired x position for the stream.
* - #gint `posy`: The desired y position for the stream
* - #gint `width`: The desired width for that source.
* Set to 0 if size is not mandatory, will be set to width of the current track.
* - #gint `height`: The desired height for that source.
* Set to 0 if size is not mandatory, will be set to height of the current track.
* - #GstDeinterlaceModes `deinterlace-mode`: Deinterlace Mode
* - #GstDeinterlaceFields `deinterlace-fields`: Fields to use for deinterlacing
* - #GstDeinterlaceFieldLayout `deinterlace-tff`: Deinterlace top field first
* - #GstVideoOrientationMethod `video-direction`: The desired video rotation and flipping.
*/
#ifdef HAVE_CONFIG_H
#include "config.h"

View file

@ -264,7 +264,7 @@ ges_video_test_source_class_init (GESVideoTestSourceClass * klass)
properties[PROP_USE_TIME_OVERLAY] =
g_param_spec_boolean ("use-time-overlay", "Use-time-overlay",
"Use time overlay, setting a child property corresponding to"
"GstTimeOverlay will switch this on by default.", FALSE,
" GstTimeOverlay will switch this on by default.", FALSE,
G_PARAM_READWRITE);
object_class->get_property = get_property;

View file

@ -32,6 +32,10 @@ GES_DECLARE_TYPE(VideoTestSource, video_test_source, VIDEO_TEST_SOURCE);
/**
* GESVideoTestSource:
*
* ### Children Properties
*
* {{ libs/GESVideoTestSource-children-props.md }}
*/
struct _GESVideoTestSource {
/*< private >*/

View file

@ -31,6 +31,10 @@ GES_DECLARE_TYPE(VideoUriSource, video_uri_source, VIDEO_URI_SOURCE);
/**
* GESVideoUriSource:
*
* ### Children Properties
*
* {{ libs/GESVideoUriSource-children-props.md }}
*/
struct _GESVideoUriSource {
/*< private >*/