Confirm, emeritus
1,680
edits
Changes
Created page with "= Gecko Media Plugins (GMPs) = == On Disk Layout == GMPs consist of a directory on disk containing two files, at a minimum: a dynamic library and a meta-data file. The plug..."
= Gecko Media Plugins (GMPs) =
== On Disk Layout ==
GMPs consist of a directory on disk containing two files, at a minimum: a dynamic library and a meta-data file.
The plugin directory name must start with "gmp-", and the rest of the name will be considered the plugin's "base name." For example - "gmp-foobar" has a base name of "foobar".
The dynamic library's name must be the plugin's base name surrounded by platform conventions for a dynamic library. Given our "foobar" example, this would be "libfoobar.dylib" on OS X, "foobar.dll" on Windows, and "libfoobar.so" on Linux.
The plugin meta-data file is a UTF-8 text file named with ".info" after the plugin base name. Given our "foobar" example, this would be "foobar.info".
== The Dynamic Library ==
The main dynamic library needs to expose three C functions publicly:
<pre>
typedef GMPErr (*GMPInitFunc)(void);
typedef GMPErr (*GMPGetAPIFunc)(const char* apiName,
void* apiStruct,
size_t structSize);
typedef void (*GMPShutdownFunc)(void);
</pre>
== The Meta-Data File ==
GMP meta data is stored in a UTF-8 text file with platform-appropriate line breaks. Each line is a record. Name, description, version, and capability records are required, in order. An example:
<pre>
Name: Cisco OpenH264
Description: Provides encoding and decoding of h.264 video via code licensed by Cisco.
Version: 2.1
Capability: encode-video, decode-video
</pre>
The capability record lists strings used to identify APIs provided by the GMP.
== How Gecko Loads a GMP ==
Gecko scans known locations either on disk or in the Windows registry for GMPs. It maintains a list of known GMPs, and when an API is requested by a consumer it scans the list for a GMP that can provide the API.
Gecko will then spin up a child process for the GMP. GMPs can only be loaded out-of-process, there is no in-process option. Furthermore, child processes may be sandboxed, so GMPs cannot depend on being able to do things outside of the sandbox (like write to disk).
The child process will load the GMP's DLL into the process, then call the publicly exposed <code>GMPInit</code> function. Next Gecko will call the publicly exposed <code>GMPGetAPI</code> function, requesting the desired API data (see the Base API section for more info).
At this point Gecko and the GMP will start doing actual work via the information in the API object. When all consumers are done with the GMP, Gecko will call the publicly exposed <code>GMPShutdown</code> function before closing the child process.
== Base API ==
== On Disk Layout ==
GMPs consist of a directory on disk containing two files, at a minimum: a dynamic library and a meta-data file.
The plugin directory name must start with "gmp-", and the rest of the name will be considered the plugin's "base name." For example - "gmp-foobar" has a base name of "foobar".
The dynamic library's name must be the plugin's base name surrounded by platform conventions for a dynamic library. Given our "foobar" example, this would be "libfoobar.dylib" on OS X, "foobar.dll" on Windows, and "libfoobar.so" on Linux.
The plugin meta-data file is a UTF-8 text file named with ".info" after the plugin base name. Given our "foobar" example, this would be "foobar.info".
== The Dynamic Library ==
The main dynamic library needs to expose three C functions publicly:
<pre>
typedef GMPErr (*GMPInitFunc)(void);
typedef GMPErr (*GMPGetAPIFunc)(const char* apiName,
void* apiStruct,
size_t structSize);
typedef void (*GMPShutdownFunc)(void);
</pre>
== The Meta-Data File ==
GMP meta data is stored in a UTF-8 text file with platform-appropriate line breaks. Each line is a record. Name, description, version, and capability records are required, in order. An example:
<pre>
Name: Cisco OpenH264
Description: Provides encoding and decoding of h.264 video via code licensed by Cisco.
Version: 2.1
Capability: encode-video, decode-video
</pre>
The capability record lists strings used to identify APIs provided by the GMP.
== How Gecko Loads a GMP ==
Gecko scans known locations either on disk or in the Windows registry for GMPs. It maintains a list of known GMPs, and when an API is requested by a consumer it scans the list for a GMP that can provide the API.
Gecko will then spin up a child process for the GMP. GMPs can only be loaded out-of-process, there is no in-process option. Furthermore, child processes may be sandboxed, so GMPs cannot depend on being able to do things outside of the sandbox (like write to disk).
The child process will load the GMP's DLL into the process, then call the publicly exposed <code>GMPInit</code> function. Next Gecko will call the publicly exposed <code>GMPGetAPI</code> function, requesting the desired API data (see the Base API section for more info).
At this point Gecko and the GMP will start doing actual work via the information in the API object. When all consumers are done with the GMP, Gecko will call the publicly exposed <code>GMPShutdown</code> function before closing the child process.
== Base API ==
