## Utilities

Utilities — Utility functions for Clutter-Gst.

## Synopsis

    ClutterInitError    clutter_gst_init                    (int *argc,
                                                             char ***argv);
    ClutterInitError    clutter_gst_init_with_args          (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);

## Description

The Clutter-Gst library should be initialized with `clutter_gst_init()` before it can be used. You should pass pointers to the main argc and argv variables so that GStreamer, Clutter and Clutter-Gst gst can process their own command line options, as shown in the following example:

Example 1. Initializing the Clutter-Gst library

    1
    2
    3
    4
    5
    6
    7

    int
    main (int argc, char *argv[])
    {
      // initialize the Clutter-Gst library
      clutter_gst_init (&argc, &argv);
      ...
    }

It's allowed to pass two NULL pointers to `clutter_gst_init()` in case you don't want to pass the command line arguments to GStreamer, Clutter and Clutter-Gst.

You can also use a GOptionEntry array to initialize your own parameters as shown in the next code fragment:

Example 2. Initializing the Clutter-Gst library with additional options

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30

    static GOptionEntry options[] =
    {
      { "framerate", 'f', 0, G_OPTION_ARG_INT, &opt_framerate,
        "Number of frames per second", NULL },
      { "fourcc", 'o', 0, G_OPTION_ARG_STRING,
         &opt_fourcc, "Fourcc of the wanted YUV format", NULL },
      { NULL }
    };

    int
    main (int argc, char *argv[])
    {
       GError           *error = NULL;
       gboolean          result;

       if (!g_thread_supported ())
         g_thread_init (NULL);

       result = clutter_gst_init_with_args (&argc, &argv,
                                            " - Test YUV frames uploading",
                                            options, NULL, &error);

       if (error)
         {
           g_print ("%s\n", error->message);
           g_error_free (error);
           return EXIT_FAILURE;
         }
      ...
    }

## Details

### clutter_gst_init ()

    ClutterInitError    clutter_gst_init                    (int *argc,
                                                             char ***argv);

Utility function to initialize both Clutter and GStreamer.

This function should be called before calling any other GLib functions. If this is not an option, your program must initialise the GLib thread system using `g_thread_init()` before any other GLib functions are called.

`argc` : | pointer to the argument list count
`argv` : | pointer to the argument list vector
Returns : | A ClutterInitError.

### clutter_gst_init_with_args ()

    ClutterInitError    clutter_gst_init_with_args          (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);

This function does the same work as `clutter_gst_init()`. Additionally, it allows you to add your own command line options, and it automatically generates nicely formatted --help output. Clutter's and GStreamer's GOptionGroups are added to the set of available options.

Your program must initialise the GLib thread system using `g_thread_init()` before any other GLib functions are called.

`argc` : | a pointer to the number of command line arguments.
`argv` : | a pointer to the array of command line arguments.
`parameter_string` : | a string which is displayed in the first line of `--help` output, after ``programname` [OPTION...]`
`entries` : | a `NULL`-terminated array of GOptionEntrys describing the options of your program
`translation_domain` : | a translation domain to use for translating the `--help` output for the options in `entries` with `gettext()`, or `NULL`
`error` : | a return location for errors
Returns : | `CLUTTER_INIT_SUCCESS` on success, a negative integer on failure.

Since 1.0