GstBaseVideoEncoder

## GstBaseVideoEncoder GstBaseVideoEncoder — Base class for video encoders |

## Synopsis

    #define             GST_BASE_VIDEO_ENCODER_SINK_NAME
    #define             GST_BASE_VIDEO_ENCODER_SRC_NAME
    #define             GST_BASE_VIDEO_ENCODER_FLOW_DROPPED
    struct              GstBaseVideoEncoder;
    struct              GstBaseVideoEncoderClass;
    const GstVideoState * gst_base_video_encoder_get_state  (GstBaseVideoEncoder *coder);
    GstVideoFrame *     gst_base_video_encoder_get_oldest_frame
                                                            (GstBaseVideoEncoder *coder);
    GstFlowReturn       gst_base_video_encoder_finish_frame (GstBaseVideoEncoder *base_video_encoder,
                                                             GstVideoFrame *frame);
    void                gst_base_video_encoder_set_latency  (GstBaseVideoEncoder *base_video_encoder,
                                                             GstClockTime min_latency,
                                                             GstClockTime max_latency);
    void                gst_base_video_encoder_set_latency_fields
                                                            (GstBaseVideoEncoder *base_video_encoder,
                                                             int n_fields);

## Description

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

GstBaseVideoEncoder and subclass should cooperate as follows.

1. Configuration

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

   - GstBaseVideoEncoder calls `set_format` to inform subclass of the format of input video data that it is about to receive. Subclass should setup for encoding and configure base class as appropriate (e.g. latency). While unlikely, it might be called more than once, if changing input parameters require reconfiguration. Baseclass will ensure that processing of current configuration is finished.

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

2. Data processing

   - Base class collects input data and metadata into a frame and hands this to subclass' `handle_frame`.

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

   - If implemented, baseclass calls subclass `shape_output` which then sends data downstream in desired form. Otherwise, it is sent as-is.

   - GstBaseVideoEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if `event` callback has been provided.

3. Shutdown phase

   - GstBaseVideoEncoder 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 should also be able to provide fixed src pad caps in `getcaps` by the time it calls `gst_base_video_encoder_finish_frame`.

Things that subclass need to take care of:

- Provide pad templates

- Provide source pad caps before pushing the first buffer

- Accept data in `handle_frame` and provide encoded results to `gst_base_video_encoder_finish_frame`.

## Details

### GST_BASE_VIDEO_ENCODER_SINK_NAME

    #define GST_BASE_VIDEO_ENCODER_SINK_NAME    "sink"

The name of the templates for the sink pad.

### GST_BASE_VIDEO_ENCODER_SRC_NAME

    #define GST_BASE_VIDEO_ENCODER_SRC_NAME     "src"

The name of the templates for the source pad.

### GST_BASE_VIDEO_ENCODER_FLOW_DROPPED

    #define GST_BASE_VIDEO_ENCODER_FLOW_DROPPED GST_FLOW_CUSTOM_SUCCESS_1

Returned when the event/buffer should be dropped.

### struct GstBaseVideoEncoder

    struct GstBaseVideoEncoder {
      GstBaseVideoCodec base_video_codec;
    };

The opaque GstBaseVideoEncoder data structure.

GstBaseVideoCodec `base_video_codec`; |

### struct GstBaseVideoEncoderClass

    struct GstBaseVideoEncoderClass {
      GstBaseVideoCodecClass              base_video_codec_class;

      /* virtual methods for subclasses */

      gboolean      (*start)              (GstBaseVideoEncoder *coder);

      gboolean      (*stop)               (GstBaseVideoEncoder *coder);

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

      GstFlowReturn (*handle_frame)       (GstBaseVideoEncoder *coder,
                                           GstVideoFrame *frame);

      gboolean      (*reset)              (GstBaseVideoEncoder *coder);
      GstFlowReturn (*finish)             (GstBaseVideoEncoder *coder);

      GstFlowReturn (*shape_output)       (GstBaseVideoEncoder *coder,
                                           GstVideoFrame *frame);

      gboolean      (*event)              (GstBaseVideoEncoder *coder,
                                           GstEvent *event);
    };

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 `get_caps` are likely needed as well.

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.
`set_format` () | Optional. Notifies subclass of incoming data format. GstVideoState fields have already been set according to provided caps.
`handle_frame` () | Provides input frame to subclass.
`reset` () |
`finish` () | Optional. Called to request subclass to dispatch any pending remaining data (e.g. at EOS).
`shape_output` () | Optional. Allows subclass to push frame downstream in whatever shape or form it deems appropriate. If not provided, provided encoded frame data is simply pushed downstream.
`event` () | Optional. Event handler on the sink pad. This function should return TRUE if the event was handled and should be discarded (i.e. not unref'ed).

### gst_base_video_encoder_get_state ()

    const GstVideoState * gst_base_video_encoder_get_state  (GstBaseVideoEncoder *coder);

`base_video_encoder` : | a GstBaseVideoEncoder
Returns : | GstVideoState describing format of video data.

### gst_base_video_encoder_get_oldest_frame ()

    GstVideoFrame *     gst_base_video_encoder_get_oldest_frame
                                                            (GstBaseVideoEncoder *coder);

`base_video_encoder` : | a GstBaseVideoEncoder
Returns : | oldest unfinished pending GstVideoFrame

### gst_base_video_encoder_finish_frame ()

    GstFlowReturn       gst_base_video_encoder_finish_frame (GstBaseVideoEncoder *base_video_encoder,
                                                             GstVideoFrame *frame);

`frame` must have a valid encoded data buffer, whose metadata fields are then appropriately set according to frame data or no buffer at all if the frame should be dropped. It is subsequently pushed downstream or provided to `shape_output`. In any case, the frame is considered finished and released.

`base_video_encoder` : | a GstBaseVideoEncoder
`frame` : | an encoded GstVideoFrame
Returns : | a GstFlowReturn resulting from sending data downstream

### gst_base_video_encoder_set_latency ()

    void                gst_base_video_encoder_set_latency  (GstBaseVideoEncoder *base_video_encoder,
                                                             GstClockTime min_latency,
                                                             GstClockTime max_latency);

Informs baseclass of encoding latency.

`base_video_encoder` : | a GstBaseVideoEncoder
`min_latency` : | minimum latency
`max_latency` : | maximum latency

### gst_base_video_encoder_set_latency_fields ()

    void                gst_base_video_encoder_set_latency_fields
                                                            (GstBaseVideoEncoder *base_video_encoder,
                                                             int n_fields);

Informs baseclass of encoding latency in terms of fields (both min and max latency).

`base_video_encoder` : | a GstBaseVideoEncoder
`fields` : | latency in fields

## See Also

GstBaseTransform