## GstFormat

GstFormat — Dynamically register new data formats

## Synopsis

    #include <gst/gst.h>

    enum                GstFormat;
    #define             GST_FORMAT_PERCENT_MAX
    #define             GST_FORMAT_PERCENT_SCALE
                        GstFormatDefinition;
    const gchar*        gst_format_get_name                 (GstFormat format);
    GQuark              gst_format_to_quark                 (GstFormat format);
    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);
    GstIterator*        gst_format_iterate_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, /* must be first in list */
      GST_FORMAT_DEFAULT   	=  1,
      GST_FORMAT_BYTES   	=  2,
      GST_FORMAT_TIME 	=  3,
      GST_FORMAT_BUFFERS =  4,
      GST_FORMAT_PERCENT =  5
    } GstFormat;

Standard predefined formats

`GST_FORMAT_UNDEFINED` | undefined format
`GST_FORMAT_DEFAULT` | the default format of the pad/element. This can be samples for raw audio, frames/fields for raw video (some, but not all, elements support this; use `GST_FORMAT_TIME` if you don't have a good reason to query for samples/frames)
`GST_FORMAT_BYTES` | bytes
`GST_FORMAT_TIME` | time in nanoseconds
`GST_FORMAT_BUFFERS` | buffers (few, if any, elements implement this as of May 2009)
`GST_FORMAT_PERCENT` | percentage of stream (few, if any, elements implement this as of May 2009)

### GST_FORMAT_PERCENT_MAX

    #define GST_FORMAT_PERCENT_MAX		G_GINT64_CONSTANT (1000000)

The PERCENT format is between 0 and this value

### GST_FORMAT_PERCENT_SCALE

    #define GST_FORMAT_PERCENT_SCALE G_GINT64_CONSTANT (10000)

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

### GstFormatDefinition

    typedef struct {
      GstFormat    value;
      const gchar *nick;
      const gchar *description;
      GQuark       quark;
    } GstFormatDefinition;

A format definition

GstFormat `value`; | The unique id of this format
const gchar *`nick`; | A short nick of the format
const gchar *`description`; | A longer description of the format
GQuark `quark`; | A quark for the nick

### gst_format_get_name ()

    const gchar*        gst_format_get_name                 (GstFormat format);

Get a printable name for the given format. Do not modify or free.

`format` : | a GstFormat
Returns : | a reference to the static name of the format or NULL if the format is unknown.

### gst_format_to_quark ()

    GQuark              gst_format_to_quark                 (GstFormat format);

Get the unique quark for the given format.

`format` : | a GstFormat
Returns : | the quark associated with the format or 0 if the format is unknown.

### gst_format_register ()

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

Create a new GstFormat based on the nick or return an already 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. MT safe.

### 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. MT safe.

### gst_format_iterate_definitions ()

    GstIterator*        gst_format_iterate_definitions      (void);

Iterate all the registered formats. The format definition is read only.

Returns : | A GstIterator of GstFormatDefinition.

## See Also

GstPad, GstElement