GStreamer Base Plugins 1.0 Library Reference Manual: gstvideoutils

## gstvideoutils gstvideoutils |

## Functions

#define | GST_VIDEO_CODEC_FRAME_FLAGS()
#define | GST_VIDEO_CODEC_FRAME_FLAG_IS_SET()
#define | GST_VIDEO_CODEC_FRAME_FLAG_SET()
#define | GST_VIDEO_CODEC_FRAME_FLAG_UNSET()
#define | GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY()
#define | GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME()
#define | GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS()
#define | GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT()
#define | GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY()
#define | GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME()
#define | GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME_HEADERS()
#define | GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT()
#define | GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME()
#define | GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME_HEADERS()
#define | GST_VIDEO_CODEC_FRAME_UNSET_SYNC_POINT()
GstVideoCodecFrame * | gst_video_codec_frame_ref ()
void | gst_video_codec_frame_unref ()
void | gst_video_codec_frame_set_user_data ()
gpointer | gst_video_codec_frame_get_user_data ()
GstVideoCodecState * | gst_video_codec_state_ref ()
void | gst_video_codec_state_unref ()

## Types and Values

struct | GstVideoCodecFrame
enum | GstVideoCodecFrameFlags
struct | GstVideoCodecState

## Object Hierarchy

## Description

## Functions

### GST_VIDEO_CODEC_FRAME_FLAGS()

    #define GST_VIDEO_CODEC_FRAME_FLAGS(frame) ((frame)->flags)

The entire set of flags for the `frame`

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_FLAG_IS_SET()

    #define GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame,flag)   !!(GST_VIDEO_CODEC_FRAME_FLAGS(frame) & (flag))

Checks whether the given `flag` is set

#### Parameters

frame | a GstVideoCodecFrame |
flag | a flag to check for |

### GST_VIDEO_CODEC_FRAME_FLAG_SET()

    #define GST_VIDEO_CODEC_FRAME_FLAG_SET(frame,flag)     (GST_VIDEO_CODEC_FRAME_FLAGS(frame) |= (flag))

This macro sets the given bits

#### Parameters

frame | a GstVideoCodecFrame |
flag | Flag to set, can be any number of bits in guint32. |

### GST_VIDEO_CODEC_FRAME_FLAG_UNSET()

    #define GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame,flag)   (GST_VIDEO_CODEC_FRAME_FLAGS(frame) &= ~(flag))

This macro usets the given bits.

#### Parameters

frame | a GstVideoCodecFrame |
flag | Flag to unset |

### GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY()

    #define GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY))

Tests if the buffer should only be decoded but not sent downstream.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME()

    #define GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))

Tests if the frame must be encoded as a keyframe. Applies only to frames provided to encoders. Decoders can safely ignore this field.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS()

    #define GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))

Tests if encoder should output stream headers before outputting the resulting encoded buffer for the given frame.

Applies only to frames provided to encoders. Decoders can safely ignore this field.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT()

    #define GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))

Tests if the frame is a synchronization point (like a keyframe).

Decoder implementations can use this to detect keyframes.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY()

    #define GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY(frame)    (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY))

Sets the buffer to not be sent downstream.

Decoder implementation can use this if they have frames that are not meant to be displayed.

Encoder implementation can safely ignore this field.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME()

    #define GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))

### GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME_HEADERS()

    #define GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME_HEADERS(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))

### GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT()

    #define GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))

Sets the frame to be a synchronization point (like a keyframe).

Encoder implementations should set this accordingly.

Decoder implementing parsing features should set this when they detect such a synchronization point.

#### Parameters

frame | a GstVideoCodecFrame |

### GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME()

    #define GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))

### GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME_HEADERS()

    #define GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME_HEADERS(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))

### GST_VIDEO_CODEC_FRAME_UNSET_SYNC_POINT()

    #define GST_VIDEO_CODEC_FRAME_UNSET_SYNC_POINT(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))

### gst_video_codec_frame_ref ()

    GstVideoCodecFrame *
    gst_video_codec_frame_ref (GstVideoCodecFrame *frame);

Increases the refcount of the given frame by one.

#### Parameters

frame | a GstVideoCodecFrame |

#### Returns

`buf`

### gst_video_codec_frame_unref ()

    void
    gst_video_codec_frame_unref (GstVideoCodecFrame *frame);

Decreases the refcount of the frame. If the refcount reaches 0, the frame will be freed.

#### Parameters

frame | a GstVideoCodecFrame |

### gst_video_codec_frame_set_user_data ()

    void
    gst_video_codec_frame_set_user_data (GstVideoCodecFrame *frame,
                                         gpointer user_data,
                                         GDestroyNotify notify);

Sets `user_data` on the frame and the GDestroyNotify that will be called when the frame is freed. Allows to attach private data by the subclass to frames.

If a `user_data` was previously set, then the previous set `notify` will be called before the `user_data` is replaced.

#### Parameters

frame | a GstVideoCodecFrame |
user_data | private data |
notify | a GDestroyNotify. | [closure user_data]

### gst_video_codec_frame_get_user_data ()

    gpointer
    gst_video_codec_frame_get_user_data (GstVideoCodecFrame *frame);

Gets private data set on the frame by the subclass via `gst_video_codec_frame_set_user_data()` previously.

#### Parameters

frame | a GstVideoCodecFrame |

#### Returns

The previously set user_data.

[transfer none]

### gst_video_codec_state_ref ()

    GstVideoCodecState *
    gst_video_codec_state_ref (GstVideoCodecState *state);

Increases the refcount of the given state by one.

#### Parameters

state | a GstVideoCodecState |

#### Returns

`buf`

### gst_video_codec_state_unref ()

    void
    gst_video_codec_state_unref (GstVideoCodecState *state);

Decreases the refcount of the state. If the refcount reaches 0, the state will be freed.

#### Parameters

state | a GstVideoCodecState |

## Types and Values

### struct GstVideoCodecFrame

    struct GstVideoCodecFrame {
      guint32 system_frame_number; /* ED */
      guint32 decode_frame_number; /* ED */
      guint32 presentation_frame_number; /* ED */

      GstClockTime dts;       /* ED */
      GstClockTime pts;       /* ED */
      GstClockTime duration;  /* ED */

      int distance_from_sync; /* ED */

      GstBuffer *input_buffer; /* ED */
      GstBuffer *output_buffer; /* ED */

      GstClockTime deadline; /* D */
    };

A GstVideoCodecFrame represents a video frame both in raw and encoded form.

#### Members

guint32 `system_frame_number`; | Unique identifier for the frame. Use this if you need to get hold of the frame later (like when data is being decoded). Typical usage in decoders is to set this on the opaque value provided to the library and get back the frame using `gst_video_decoder_get_frame()` |
guint32 `decode_frame_number`; |  |
guint32 `presentation_frame_number`; |  |
GstClockTime `dts`; | Decoding timestamp |
GstClockTime `pts`; | Presentation timestamp |
GstClockTime `duration`; | Duration of the frame |
int `distance_from_sync`; | Distance in frames from the last synchronization point. |
GstBuffer *`input_buffer`; | the input GstBuffer that created this frame. The buffer is owned by the frame and references to the frame instead of the buffer should |
GstBuffer *`output_buffer`; | the output GstBuffer. Implementations should set this either directly, or by using the ``gst_video_decoder_alloc_output_frame()`` or ``gst_video_decoder_alloc_output_buffer()`` methods. The buffer is owned by the frame and references to the frame instead of the buffer should be kept. |
GstClockTime `deadline`; | Running time when the frame will be used. |

### enum GstVideoCodecFrameFlags

Flags for GstVideoCodecFrame

#### Members

GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY | is the frame only meant to be decoded |
GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT | is the frame a synchronization point (keyframe) |
GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME | should the output frame be made a keyframe |
GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS | should the encoder output stream headers |

### struct GstVideoCodecState

    struct GstVideoCodecState {
      GstVideoInfo info;

      GstCaps *caps;

      GstBuffer *codec_data;
    };

Structure representing the state of an incoming or outgoing video stream for encoders and decoders.

Decoders and encoders will receive such a state through their respective `set_format` vmethods.

Decoders and encoders can set the downstream state, by using the ``gst_video_decoder_set_output_state()`` or ``gst_video_encoder_set_output_state()`` methods.

#### Members

GstVideoInfo `info`; | The GstVideoInfo describing the stream |
GstCaps *`caps`; | The GstCaps |
GstBuffer *`codec_data`; | (optional) a GstBuffer corresponding to the 'codec_data' field of a stream. |