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