## GstFormat

GstFormat — Dynamically register new formats

## Synopsis

    #include <gst/gst.h>

    enum        GstFormat;
    #define     GST_FORMAT_PERCENT_MAX
    #define     GST_FORMAT_PERCENT_SCALE
    struct      GstFormatDefinition;
    #define     GST_FORMATS_FUNCTION            (type, functionname, ...)
    GstFormat   gst_format_register             (const gchar *nick,
                                                 const gchar *description);
    GstFormat   gst_format_get_by_nick          (const gchar *nick);
    gboolean    gst_formats_contains            (const GstFormat *formats,
                                                 GstFormat format);
    const GstFormatDefinition* gst_format_get_details
                                                (GstFormat format);
    const GList* gst_format_get_definitions     (void);

## Description

GstFormats functions are used to register a new format to the gstreamer core. formats can be used to perform seeking or conversions/query operations.

## Details

### enum GstFormat

    typedef enum {
      GST_FORMAT_UNDEFINED 	=  0,
      GST_FORMAT_DEFAULT   	=  1,
      GST_FORMAT_BYTES   	=  2,
      GST_FORMAT_TIME 	=  3,
      GST_FORMAT_BUFFERS	=  4,
      GST_FORMAT_PERCENT	=  5,
      /* samples for audio, frames/fields for video */
      GST_FORMAT_UNITS 	=  6
    } GstFormat;

Standard predefined formats

`GST_FORMAT_UNDEFINED` | undefined format
`GST_FORMAT_DEFAULT` | the default format of the pad/element
`GST_FORMAT_BYTES` | bytes
`GST_FORMAT_TIME` | time in nanoseconds
`GST_FORMAT_BUFFERS` | buffers
`GST_FORMAT_PERCENT` | percentage of stream
`GST_FORMAT_UNITS` | frames for video, samples for audio, other definitions as defined by the media type.

### GST_FORMAT_PERCENT_MAX

    #define	GST_FORMAT_PERCENT_MAX		1000000LL

The PERCENT format is between 0 and this value

### GST_FORMAT_PERCENT_SCALE

    #define	GST_FORMAT_PERCENT_SCALE	10000LL

The value used to scale down the reported PERCENT format value to its real value.

### struct GstFormatDefinition

    struct GstFormatDefinition {

      GstFormat  value;
      gchar     *nick;
      gchar     *description;
    };

A format definition

GstFormat `value` | The unique id of this format
gchar *`nick` | A short nick of the format
gchar *`description` | A longer description of the format

### GST_FORMATS_FUNCTION()

    #define     GST_FORMATS_FUNCTION(type, functionname, ...)

A convenience function to define a function that returns an array of formats.

`type` : | The type of the first argument of the function
`functionname` : | The name of the function
`...` : | comma separated list of functions closed with 0

### gst_format_register ()

    GstFormat   gst_format_register             (const gchar *nick,
                                                 const gchar *description);

Create a new GstFormat based on the nick or return an allrady registered format with that nick

`nick` : | The nick of the new format
`description` : | The description of the new format
Returns : | A new GstFormat or an already registered format with the same nick.

### gst_format_get_by_nick ()

    GstFormat   gst_format_get_by_nick          (const gchar *nick);

Return the format registered with the given nick.

`nick` : | The nick of the format
Returns : | The format with `nick` or GST_FORMAT_UNDEFINED if the format was not registered.

### gst_formats_contains ()

    gboolean    gst_formats_contains            (const GstFormat *formats,
                                                 GstFormat format);

See if the given format is inside the format array.

`formats` : | The format array to search
`format` : | the format to find
Returns : | TRUE if the format is found inside the array

### gst_format_get_details ()

    const GstFormatDefinition* gst_format_get_details
                                                (GstFormat format);

Get details about the given format.

`format` : | The format to get details of
Returns : | The GstFormatDefinition for `format` or NULL on failure.

### gst_format_get_definitions ()

    const GList* gst_format_get_definitions     (void);

Get a list of all the registered formats.

Returns : | A GList of GstFormatDefinition.

## See Also

GstPad, GstElement