gstvideoutils

## gstvideoutils gstvideoutils |

## Synopsis

    struct              GstVideoCodecFrame;
    enum                GstVideoCodecFrameFlags;
    #define             GST_VIDEO_CODEC_FRAME_FLAGS         (frame)
    #define             GST_VIDEO_CODEC_FRAME_FLAG_IS_SET   (frame,
                                                             flag)
    #define             GST_VIDEO_CODEC_FRAME_FLAG_SET      (frame,
                                                             flag)
    #define             GST_VIDEO_CODEC_FRAME_FLAG_UNSET    (frame,
                                                             flag)
    #define             GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY(frame)
    #define             GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME(frame)
    #define             GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS(frame)
    #define             GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT (frame)
    #define             GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY(frame)
    #define             GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME(frame)
    #define             GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME_HEADERS(frame)
    #define             GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT(frame)
    #define             GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME(frame)
    #define             GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME_HEADERS(frame)
    #define             GST_VIDEO_CODEC_FRAME_UNSET_SYNC_POINT(frame)
    GstVideoCodecFrame * gst_video_codec_frame_ref          (GstVideoCodecFrame *frame);
    void                gst_video_codec_frame_unref         (GstVideoCodecFrame *frame);
    void                gst_video_codec_frame_set_user_data (GstVideoCodecFrame *frame,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    gpointer            gst_video_codec_frame_get_user_data (GstVideoCodecFrame *frame);
    struct              GstVideoCodecState;
    GstVideoCodecState * gst_video_codec_state_ref          (GstVideoCodecState *state);
    void                gst_video_codec_state_unref         (GstVideoCodecState *state);

## Description

## Details

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

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

    typedef enum {
      GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY            = (1<<0),
      GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT             = (1<<1),
      GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME         = (1<<2),
      GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS = (1<<3)
    } GstVideoCodecFrameFlags;

Flags for GstVideoCodecFrame

`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

### GST_VIDEO_CODEC_FRAME_FLAGS()

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

The entire set of flags for the `frame`

`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

`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

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

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

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

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

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

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

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

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

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

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

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

`frame` : | a GstVideoCodecFrame
Returns : | The previously set user_data. [transfer none]

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

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.

### gst_video_codec_state_ref ()

    GstVideoCodecState * gst_video_codec_state_ref          (GstVideoCodecState *state);

Increases the refcount of the given state by one.

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

`state` : | a GstVideoCodecState