subprojects/gst-docs/markdown/application-development/advanced/interfaces.md

   1 ---
   2 title: Interfaces
   3 ...
   4
   5 # Interfaces
   6
   7 [Using an element as a GObject][element-object] presents the use of `GObject`
   8 properties as a simple way for applications and elements to interact. This
   9 method suffices for simple getters and setters, but fails for anything more
  10 complicated. For more complex use cases, GStreamer uses interfaces based on the
  11 `GObject`
  12 [`GTypeInterface`](http://library.gnome.org/devel/gobject/stable/gtype-non-instantiatable-classed.html)
  13 type.
  14
  15 This text is meant to be introductory and does not include source code examples.
  16 Please take a look at the API reference for additional details.
  17
  18 [element-object]: application-development/basics/elements.md#using-an-element-as-a-gobject
  19
  20 ## The URI Handler interface
  21
  22 In our examples so far, we have only showed support for local files
  23 using the “filesrc” element, but GStreamer supports many more location
  24 sources.
  25
  26 GStreamer doesn't require applications to know any `URI` specifics, like
  27 what element to use for a particular network source types. These details
  28 are abstracted by the `GstURIHandler` interface.
  29
  30 There is no strict rule for `URI` naming, but in general, we follow
  31 common-usage naming conventions. For example, assuming you have the
  32 correct plugins installed, GStreamer supports:
  33
  34 ```
  35 file:///<path>/<file>
  36 http://<host>/<path>/<file>
  37 rtsp://<host>/<path>
  38 dvb://<CHANNEL>
  39 ...
  40 ```
  41
  42 In order to get the source or sink element supporting a particular URI,
  43 use `gst_element_make_from_uri ()` with `GST_URI_SRC` or `GST_URI_SINK`
  44 as `GstURIType` depending in the direction you need.
  45
  46 You can convert filenames to and from URIs using GLib's
  47 `g_filename_to_uri ()` and `g_uri_to_filename ()`.
  48
  49 ## The Color Balance interface
  50
  51 The `GstColorBalance` interface is a way to control video-related properties
  52 on an element, such as brightness, contrast and so on. Its sole reason
  53 for existence is that, as far as its authors know, there's no way to
  54 dynamically register properties using `GObject`.
  55
  56 The colorbalance interface is implemented by several plugins, including
  57 `xvimagesink`, `glimagesink` and the `Video4linux2` elements.
  58
  59 ## The Video Overlay interface
  60
  61 The `GstVideoOverlay` interface was created to solve the problem of
  62 embedding video streams in an application window. The application
  63 provides a window handle to an element implementing this interface,
  64 and the element will then use this window handle to draw on
  65 rather than creating a new toplevel window. This is useful to embed
  66 video in video players.
  67
  68 This interface is implemented by, amongst others, the `Video4linux2`
  69 elements and by `glimagesink`, `ximagesink`, `xvimagesink` and `sdlvideosink`.
  70
  71 ## Other interfaces
  72
  73 There are quite a few other interfaces provided by GStreamer and implemented by
  74 some of its elements. Among them:
  75
  76 * `GstChildProxy` For access to internal element's properties on multi-child elements
  77 * `GstNavigation` For the sending and parsing of navigation events
  78 * `GstPreset` For handling element presets
  79 * `GstRTSPExtension` An RTSP Extension interface
  80 * `GstStreamVolume` Interface to provide access and control stream volume levels
  81 * `GstTagSetter` For handling media metadata
  82 * `GstTagXmpWriter` For elements that provide XMP serialization
  83 * `GstTocSetter` For setting and retrieval of TOC-like data
  84 * `GstTuner` For elements providing RF tunning operations
  85 * `GstVideoDirection` For video rotation and flipping controls
  86 * `GstVideoOrientation` For video orientation controls
  87 * `GstWaylandVideo` Wayland video interface
  88