Class Plugin

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.freedesktop.gstreamer.gst.GstObject
org.freedesktop.gstreamer.gst.Plugin
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Plugin extends GstObject

GStreamer is extensible, so GstElement instances can be loaded at runtime. A plugin system can provide one or more of the basic GStreamer GstPluginFeature subclasses.

A plugin should export a symbol gst_plugin_desc that is a struct of type GstPluginDesc. the plugin loader will check the version of the core library the plugin was linked against and will create a new GstPlugin. It will then call the GstPluginInitFunc function that was provided in the gst_plugin_desc.

Once you have a handle to a GstPlugin (e.g. from the GstRegistry), you can add any object that subclasses GstPluginFeature.

Usually plugins are always automatically loaded so you don't need to call gst_plugin_load() explicitly to bring it into memory. There are options to statically link plugins to an app or even use GStreamer without a plugin repository in which case gst_plugin_load() can be needed to bring the plugin into memory.

  • Constructor Details

    • Plugin

      public Plugin(MemorySegment address)
      Create a Plugin instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Plugin

      public Plugin()
      Create a new Plugin.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Plugin class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Plugin asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GstObject
      Returns:
      the instance as if it were its parent type

    • listFree

      public static void listFree(List<Plugin> list)
      Unrefs each member of list, then frees the list.
      Parameters:
      list - list of GstPlugin

    • loadByName

      public static @Nullable Plugin loadByName(String name)
      Load the named plugin. Refs the plugin.
      Parameters:
      name - name of plugin to load
      Returns:
      a reference to a loaded plugin, or null on error.

    • loadFile

      public static Plugin loadFile(String filename) throws GErrorException
      Loads the given plugin and refs it. Caller needs to unref after use.
      Parameters:
      filename - the plugin filename to load
      Returns:
      a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or null if an error occurred.
      Throws:
      GErrorException - see GError

    • registerStatic

      public static boolean registerStatic(int majorVersion, int minorVersion, String name, String description, @Nullable PluginInitFunc initFunc, String version, String license, String source, String package_, String origin)

      Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file).

      You must make sure that GStreamer has been initialised (with gst_init() or via gst_init_get_option_group()) before calling this function.

      Parameters:
      majorVersion - the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here
      minorVersion - the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here
      name - a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)
      description - description of the plugin
      initFunc - pointer to the init function of this plugin.
      version - version string of the plugin
      license - effective license of plugin. Must be one of the approved licenses (see GstPluginDesc above) or the plugin will not be registered.
      source - source module plugin belongs to
      package_ - shipped package plugin belongs to
      origin - URL to provider of plugin
      Returns:
      true if the plugin was registered correctly, otherwise false.

    • registerStaticFull

      public static boolean registerStaticFull(int majorVersion, int minorVersion, String name, String description, @Nullable PluginInitFullFunc initFullFunc, String version, String license, String source, String package_, String origin)

      Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file) with a GstPluginInitFullFunc which allows user data to be passed to the callback function (useful for bindings).

      You must make sure that GStreamer has been initialised (with gst_init() or via gst_init_get_option_group()) before calling this function.

      Parameters:
      majorVersion - the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here
      minorVersion - the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here
      name - a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)
      description - description of the plugin
      initFullFunc - pointer to the init function with user data of this plugin.
      version - version string of the plugin
      license - effective license of plugin. Must be one of the approved licenses (see GstPluginDesc above) or the plugin will not be registered.
      source - source module plugin belongs to
      package_ - shipped package plugin belongs to
      origin - URL to provider of plugin
      Returns:
      true if the plugin was registered correctly, otherwise false.

    • addDependency

      public void addDependency(@Nullable String @Nullable [] envVars, @Nullable String @Nullable [] paths, @Nullable String @Nullable [] names, Set<PluginDependencyFlags> flags)

      Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

      GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

      Parameters:
      envVars - null-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or null. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins".
      paths - null-terminated array of directories/paths where dependent files may be, or null.
      names - null-terminated array of file names (or file name suffixes, depending on flags) to be used in combination with the paths from paths and/or the paths extracted from the environment variables in envVars, or null.
      flags - optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

    • addDependency

      public void addDependency(@Nullable String @Nullable [] envVars, @Nullable String @Nullable [] paths, @Nullable String @Nullable [] names, PluginDependencyFlags... flags)

      Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

      GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

      Parameters:
      envVars - null-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or null. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins".
      paths - null-terminated array of directories/paths where dependent files may be, or null.
      names - null-terminated array of file names (or file name suffixes, depending on flags) to be used in combination with the paths from paths and/or the paths extracted from the environment variables in envVars, or null.
      flags - optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

    • addDependencySimple

      public void addDependencySimple(@Nullable String envVars, @Nullable String paths, @Nullable String names, Set<PluginDependencyFlags> flags)

      Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

      GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

      Convenience wrapper function for gst_plugin_add_dependency() which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above).

      Parameters:
      envVars - one or more environment variables (separated by ':', ';' or ','), or null. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
      paths - one ore more directory paths (separated by ':' or ';' or ','), or null. Example: "/usr/lib/mystuff/plugins"
      names - one or more file names or file name suffixes (separated by commas), or null
      flags - optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

    • addDependencySimple

      public void addDependencySimple(@Nullable String envVars, @Nullable String paths, @Nullable String names, PluginDependencyFlags... flags)

      Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

      GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

      Convenience wrapper function for gst_plugin_add_dependency() which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above).

      Parameters:
      envVars - one or more environment variables (separated by ':', ';' or ','), or null. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
      paths - one ore more directory paths (separated by ':' or ';' or ','), or null. Example: "/usr/lib/mystuff/plugins"
      names - one or more file names or file name suffixes (separated by commas), or null
      flags - optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

    • addStatusError

      public void addStatusError(String message)

    • addStatusInfo

      public void addStatusInfo(String message)

    • addStatusWarning

      public void addStatusWarning(String message)

    • getCacheData

      public @Nullable Structure getCacheData()
      Gets the plugin specific data cache. If it is null there is no cached data stored. This is the case when the registry is getting rebuilt.
      Returns:
      The cached data as a GstStructure or null.

    • getDescription

      public String getDescription()
      Get the long descriptive name of the plugin
      Returns:
      the long name of the plugin

    • getFilename

      public @Nullable String getFilename()
      get the filename of the plugin
      Returns:
      the filename of the plugin

    • getLicense

      public String getLicense()
      get the license of the plugin
      Returns:
      the license of the plugin

    • getName

      public String getName()
      Get the short name of the plugin
      Overrides:
      getName in class GstObject
      Returns:
      the name of the plugin

    • getOrigin

      public String getOrigin()
      get the URL where the plugin comes from
      Returns:
      the origin of the plugin

    • getPackage

      public String getPackage()
      get the package the plugin belongs to.
      Returns:
      the package of the plugin

    • getReleaseDateString

      public @Nullable String getReleaseDateString()

      Get the release date (and possibly time) in form of a string, if available.

      For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain a time component after the date as well, in which case the string will be formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").

      There may be plugins that do not have a valid release date set on them.

      Returns:
      the date string of the plugin, or null if not available.

    • getSource

      public String getSource()
      get the source module the plugin belongs to.
      Returns:
      the source of the plugin

    • getStatusErrors

      public @Nullable String @Nullable [] getStatusErrors()

    • getStatusInfos

      public @Nullable String @Nullable [] getStatusInfos()

    • getStatusWarnings

      public @Nullable String @Nullable [] getStatusWarnings()

    • getVersion

      public String getVersion()
      get the version of the plugin
      Returns:
      the version of the plugin

    • isLoaded

      public boolean isLoaded()
      queries if the plugin is loaded into memory
      Returns:
      true is loaded, false otherwise

    • load

      public @Nullable Plugin load()

      Loads plugin. Note that the return value is the loaded plugin; this Plugin is untouched. The normal use pattern of this function goes like this:

      GstPlugin *loaded_plugin;
loaded_plugin = gst_plugin_load (plugin);
// presumably, we're no longer interested in the potentially-unloaded plugin
gst_object_unref (plugin);
plugin = loaded_plugin;
      Returns:
      a reference to a loaded plugin, or null on error.

    • setCacheData

      public void setCacheData(Structure cacheData)

      Adds plugin specific data to cache. Passes the ownership of the structure to the plugin.

      The cache is flushed every time the registry is rebuilt.

      Parameters:
      cacheData - a structure containing the data to cache

    • builder

      public static Plugin.Builder<? extends Plugin.Builder> builder()
      A Plugin.Builder object constructs a Plugin with the specified properties. Use the various set...() methods to set properties, and finish construction with Plugin.Builder.build().
      Returns:
      the builder object