## GstFormat

GstFormat — Dynamically register new data formats

## Functions

const gchar * | gst_format_get_name ()
GQuark | gst_format_to_quark ()
GstFormat | gst_format_register ()
GstFormat | gst_format_get_by_nick ()
gboolean | gst_formats_contains ()
const GstFormatDefinition * | gst_format_get_details ()
GstIterator * | gst_format_iterate_definitions ()

## Types and Values

enum | GstFormat
#define | GST_FORMAT_PERCENT_MAX
#define | GST_FORMAT_PERCENT_SCALE
struct | GstFormatDefinition

## Includes

    #include <gst/gst.h>

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

## Functions

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

#### Parameters

format | a GstFormat |

#### Returns

a reference to the static name of the format or `NULL` if the format is unknown.

[nullable]

### gst_format_to_quark ()

    GQuark
    gst_format_to_quark (GstFormat format);

Get the unique quark for the given format.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

formats | The format array to search. | [array zero-terminated=1]
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.

#### Parameters

format | The format to get details of |

#### Returns

The GstFormatDefinition for `format` or `NULL` on failure.

MT safe.

[nullable]

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

[transfer full]

## Types and Values

### enum GstFormat

Standard predefined formats

#### Members

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.

### struct GstFormatDefinition

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

A format definition

#### Members

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 |

## See Also

GstPad, GstElement