GstBaseVideoDecoder

## GstBaseVideoDecoder GstBaseVideoDecoder — Base class for video decoders |

## Functions

#define | GST_BASE_AUDIO_DECODER_ERROR()
void | gst_base_video_decoder_class_set_capture_pattern ()
GstVideoFrame * | gst_base_video_decoder_get_frame ()
GstVideoFrame * | gst_base_video_decoder_get_oldest_frame ()
void | gst_base_video_decoder_add_to_frame ()
void | gst_base_video_decoder_lost_sync ()
GstFlowReturn | gst_base_video_decoder_have_frame ()
void | gst_base_video_decoder_set_sync_point ()
gboolean | gst_base_video_decoder_set_src_caps ()
GstBuffer * | gst_base_video_decoder_alloc_src_buffer ()
GstFlowReturn | gst_base_video_decoder_alloc_src_frame ()
GstVideoState * | gst_base_video_decoder_get_state ()
GstClockTimeDiff | gst_base_video_decoder_get_max_decode_time ()
GstFlowReturn | gst_base_video_decoder_finish_frame ()

## Types and Values

#define | GST_BASE_VIDEO_DECODER_SINK_NAME
#define | GST_BASE_VIDEO_DECODER_SRC_NAME
#define | GST_BASE_VIDEO_DECODER_FLOW_NEED_DATA
#define | GST_BASE_VIDEO_DECODER_FLOW_DROPPED
struct | GstBaseVideoDecoder
struct | GstBaseVideoDecoderClass

## Description

This base class is for video decoders turning encoded data into raw video frames.

GstBaseVideoDecoder and subclass should cooperate as follows.

1. Configuration

   - Initially, GstBaseVideoDecoder calls `start` when the decoder element is activated, which allows subclass to perform any global setup.

   - GstBaseVideoDecoder calls `set_format` to inform subclass of caps describing input video data that it is about to receive, including possibly configuration data. While unlikely, it might be called more than once, if changing input parameters require reconfiguration.

   - GstBaseVideoDecoder calls `stop` at end of all processing.

2. Data processing

   - Base class gathers input data, and optionally allows subclass to parse this into subsequently manageable chunks, typically corresponding to and referred to as 'frames'.

   - Input frame is provided to subclass' `handle_frame`.

   - If codec processing results in decoded data, subclass should call `gst_base_video_decoder_finish_frame` to have decoded data pushed downstream.

3. Shutdown phase

   - GstBaseVideoDecoder class calls `stop` to inform the subclass that data parsing will be stopped.

Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also needs to set the fixed caps on srcpad, when the format is ensured. This is typically when base class calls subclass' `set_format` function, though it might be delayed until calling `gst_base_video_decoder_finish_frame` .

Subclass is also responsible for providing (presentation) timestamps (likely based on corresponding input ones). If that is not applicable or possible, baseclass provides limited framerate based interpolation.

Similarly, the baseclass provides some limited (legacy) seeking support (upon explicit subclass request), as full-fledged support should rather be left to upstream demuxer, parser or alike. This simple approach caters for seeking and duration reporting using estimated input bitrates.

Baseclass provides some support for reverse playback, in particular in case incoming data is not packetized or upstream does not provide fragments on keyframe boundaries. However, subclass should then be prepared for the parsing and frame processing stage to occur separately (rather than otherwise the latter immediately following the former), and should ensure the parsing stage properly marks keyframes or rely on upstream to do so properly for incoming data.

Things that subclass need to take care of:

- Provide pad templates

- Set source pad caps when appropriate

- Configure some baseclass behaviour parameters.

- Optionally parse input data, if it is not considered packetized. Parse sync is obtained either by providing baseclass with a mask and pattern or a custom `scan_for_sync`. When sync is established, `parse_data` should invoke `gst_base_video_decoder_add_to_frame` and `gst_base_video_decoder_have_frame` as appropriate.

- Accept data in `handle_frame` and provide decoded results to `gst_base_video_decoder_finish_frame`.

## Functions

### GST_BASE_AUDIO_DECODER_ERROR()

    #define             GST_BASE_AUDIO_DECODER_ERROR(el, w, domain, code, text, debug, ret)

### gst_base_video_decoder_class_set_capture_pattern ()

    void
    gst_base_video_decoder_class_set_capture_pattern
                                   (GstBaseVideoDecoderClass *klass,
                                    guint32 mask,
                                    guint32 pattern);

### gst_base_video_decoder_get_frame ()

    GstVideoFrame *
    gst_base_video_decoder_get_frame (GstBaseVideoDecoder *coder,
                                      int frame_number);

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |
frame_number | system_frame_number of a frame |

#### Returns

pending unfinished GstVideoFrame identified by `frame_number` .

### gst_base_video_decoder_get_oldest_frame ()

    GstVideoFrame *
    gst_base_video_decoder_get_oldest_frame
                                   (GstBaseVideoDecoder *coder);

Sets the mask and pattern that will be scanned for to obtain parse sync. Note that a non-zero `mask` implies that `scan_for_sync` will be ignored.

#### Parameters

base_video_decoder_class | a GstBaseVideoDecoderClass |

### gst_base_video_decoder_add_to_frame ()

    void
    gst_base_video_decoder_add_to_frame (GstBaseVideoDecoder *base_video_decoder,
                                         int n_bytes);

### gst_base_video_decoder_lost_sync ()

    void
    gst_base_video_decoder_lost_sync (GstBaseVideoDecoder *base_video_decoder);

Advances out-of-sync input data by 1 byte and marks it accordingly.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

### gst_base_video_decoder_have_frame ()

    GstFlowReturn
    gst_base_video_decoder_have_frame (GstBaseVideoDecoder *base_video_decoder);

Gathers all data collected for currently parsed frame, gathers corresponding metadata and passes it along for further processing, i.e. `handle_frame` .

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

#### Returns

a GstFlowReturn

### gst_base_video_decoder_set_sync_point ()

    void
    gst_base_video_decoder_set_sync_point (GstBaseVideoDecoder *base_video_decoder);

Marks current frame as a sync point, i.e. keyframe.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

### gst_base_video_decoder_set_src_caps ()

    gboolean
    gst_base_video_decoder_set_src_caps (GstBaseVideoDecoder *base_video_decoder);

Sets src pad caps according to currently configured GstVideoState.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

### gst_base_video_decoder_alloc_src_buffer ()

    GstBuffer *
    gst_base_video_decoder_alloc_src_buffer
                                   (GstBaseVideoDecoder *base_video_decoder);

Helper function that uses gst_pad_alloc_buffer_and_set_caps to allocate a buffer to hold a video frame for `base_video_decoder` 's current GstVideoState.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

#### Returns

allocated buffer

### gst_base_video_decoder_alloc_src_frame ()

    GstFlowReturn
    gst_base_video_decoder_alloc_src_frame
                                   (GstBaseVideoDecoder *base_video_decoder,
                                    GstVideoFrame *frame);

Helper function that uses gst_pad_alloc_buffer_and_set_caps to allocate a buffer to hold a video frame for `base_video_decoder` 's current GstVideoState. Subclass should already have configured video state and set src pad caps.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |
frame | a GstVideoFrame |

#### Returns

result from pad alloc call

### gst_base_video_decoder_get_state ()

    GstVideoState *
    gst_base_video_decoder_get_state (GstBaseVideoDecoder *base_video_decoder);

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |

#### Returns

GstVideoState describing format of video data.

### gst_base_video_decoder_get_max_decode_time ()

    GstClockTimeDiff
    gst_base_video_decoder_get_max_decode_time
                                   (GstBaseVideoDecoder *base_video_decoder,
                                    GstVideoFrame *frame);

Determines maximum possible decoding time for `frame` that will allow it to decode and arrive in time (as determined by QoS events). In particular, a negative result means decoding in time is no longer possible and should therefore occur as soon/skippy as possible.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |
frame | a GstVideoFrame |

#### Returns

max decoding time.

### gst_base_video_decoder_finish_frame ()

    GstFlowReturn
    gst_base_video_decoder_finish_frame (GstBaseVideoDecoder *base_video_decoder,
                                         GstVideoFrame *frame);

Removes next `n_bytes` of input data and adds it to currently parsed frame.

#### Parameters

base_video_decoder | a GstBaseVideoDecoder |
n_bytes | an encoded GstVideoFrame |

## Types and Values

### GST_BASE_VIDEO_DECODER_SINK_NAME

    #define GST_BASE_VIDEO_DECODER_SINK_NAME    "sink"

The name of the templates for the sink pad.

### GST_BASE_VIDEO_DECODER_SRC_NAME

    #define GST_BASE_VIDEO_DECODER_SRC_NAME     "src"

The name of the templates for the source pad.

### GST_BASE_VIDEO_DECODER_FLOW_NEED_DATA

    #define GST_BASE_VIDEO_DECODER_FLOW_NEED_DATA GST_FLOW_CUSTOM_SUCCESS

Returned while parsing to indicate more data is needed.

### GST_BASE_VIDEO_DECODER_FLOW_DROPPED

    #define GST_BASE_VIDEO_DECODER_FLOW_DROPPED GST_FLOW_CUSTOM_SUCCESS_1

Returned when the event/buffer should be dropped.

### struct GstBaseVideoDecoder

    struct GstBaseVideoDecoder {
      GstBaseVideoCodec base_video_codec;
    };

The opaque GstBaseVideoDecoder data structure.

### struct GstBaseVideoDecoderClass

    struct GstBaseVideoDecoderClass {
      GstBaseVideoCodecClass base_video_codec_class;

      gboolean      (*start)          (GstBaseVideoDecoder *coder);

      gboolean      (*stop)           (GstBaseVideoDecoder *coder);

      int           (*scan_for_sync)  (GstBaseVideoDecoder *decoder, gboolean at_eos,
                                       int offset, int n);

      GstFlowReturn (*parse_data)     (GstBaseVideoDecoder *decoder, gboolean at_eos);

      gboolean      (*set_format)     (GstBaseVideoDecoder *coder, GstVideoState * state);

      gboolean      (*reset)          (GstBaseVideoDecoder *coder);

      GstFlowReturn (*finish)         (GstBaseVideoDecoder *coder);

      GstFlowReturn (*handle_frame)   (GstBaseVideoDecoder *coder, GstVideoFrame *frame);
    };

Subclasses can override any of the available virtual methods or not, as needed. At minimum `handle_frame` needs to be overridden, and `set_format` and likely as well. If non-packetized input is supported or expected, `parse` needs to be overridden as well.

#### Members

GstBaseVideoCodecClass `base_video_codec_class`; |  |
`start` () | Optional. Called when the element starts processing. Allows opening external resources. |
`stop` () | Optional. Called when the element stops processing. Allows closing external resources. |
`scan_for_sync` () | Optional. Allows subclass to obtain sync for subsequent parsing by custom means (above an beyond scanning for specific marker and mask). |
`parse_data` () | Required for non-packetized input. Allows chopping incoming data into manageable units (frames) for subsequent decoding. |
`set_format` () | Notifies subclass of incoming data format (caps). |
`reset` () | Optional. Allows subclass (codec) to perform post-seek semantics reset. |
`finish` () | Optional. Called to request subclass to dispatch any pending remaining data (e.g. at EOS). |
`handle_frame` () | Provides input data frame to subclass. |

## See Also

GstBaseTransform