gi-gstvideo-1.0.26: GStreamerVideo bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.GstVideo.Objects.VideoEncoder

Description

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

GstVideoEncoder and subclass should cooperate as follows.

Configuration

  • Initially, GstVideoEncoder calls start when the encoder element is activated, which allows subclass to perform any global setup.
  • GstVideoEncoder calls setFormat 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.
  • GstVideoEncoder calls stop at end of all processing.

Data processing

  • Base class collects input data and metadata into a frame and hands this to subclass' handleFrame.
  • If codec processing results in encoded data, subclass should call gstVideoEncoderFinishFrame to have encoded data pushed downstream.
  • If implemented, baseclass calls subclass prePush just prior to pushing to allow subclasses to modify some metadata on the buffer. If it returns GST_FLOW_OK, the buffer is pushed downstream.
  • GstVideoEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

  • GstVideoEncoder 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 gstVideoEncoderFinishFrame.

Things that subclass need to take care of:

  • Provide pad templates
  • Provide source pad caps before pushing the first buffer
  • Accept data in handleFrame and provide encoded results to gstVideoEncoderFinishFrame.

The VideoEncoder:qos property will enable the Quality-of-Service features of the encoder which gather statistics about the real-time performance of the downstream elements. If enabled, subclasses can use videoEncoderGetMaxEncodeTime to check if input frames are already late and drop them right away to give a chance to the pipeline to catch up.

Synopsis

Exported types

newtype VideoEncoder Source #

Memory-managed wrapper type.

Constructors

VideoEncoder (ManagedPtr VideoEncoder) 

Instances

Instances details
Eq VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

GObject VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

ManagedPtrNewtype VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

Methods

toManagedPtr :: VideoEncoder -> ManagedPtr VideoEncoder

TypedObject VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

Methods

glibType :: IO GType

HasParentTypes VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

IsGValue (Maybe VideoEncoder) Source #

Convert VideoEncoder to and from GValue. See toGValue and fromGValue.

Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe VideoEncoder -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe VideoEncoder)

type ParentTypes VideoEncoder Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

type ParentTypes VideoEncoder = '[Element, Object, Object, Preset]

class (GObject o, IsDescendantOf VideoEncoder o) => IsVideoEncoder o Source #

Type class for types which can be safely cast to VideoEncoder, for instance with toVideoEncoder.

Instances

Instances details
(GObject o, IsDescendantOf VideoEncoder o) => IsVideoEncoder o Source # 
Instance details

Defined in GI.GstVideo.Objects.VideoEncoder

toVideoEncoder :: (MonadIO m, IsVideoEncoder o) => o -> m VideoEncoder Source #

Cast to VideoEncoder, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Expand

Methods

abortState, addControlBinding, addPad, addPropertyDeepNotifyWatch, addPropertyNotifyWatch, allocateOutputBuffer, allocateOutputFrame, bindProperty, bindPropertyFull, callAsync, changeState, continueState, createAllPads, defaultError, deletePreset, finishFrame, finishSubframe, forceFloating, foreachPad, foreachSinkPad, foreachSrcPad, freezeNotify, getv, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, isEditable, isFloating, isLockedState, isQosEnabled, iteratePads, iterateSinkPads, iterateSrcPads, link, linkFiltered, linkPads, linkPadsFiltered, linkPadsFull, loadPreset, lostState, mergeTags, messageFull, messageFullWithDetails, negotiate, noMorePads, notify, notifyByPspec, postMessage, provideClock, proxyGetcaps, query, queryConvert, queryDuration, queryPosition, ref, refSink, releaseRequestPad, removeControlBinding, removePad, removePropertyNotifyWatch, renamePreset, requestPad, requestPadSimple, runDispose, savePreset, seek, seekSimple, sendEvent, stealData, stealQdata, suggestNextSync, syncStateWithParent, syncValues, thawNotify, unlink, unlinkPads, unparent, unref, watchClosure.

Getters

getAllocator, getBaseTime, getBus, getClock, getCompatiblePad, getCompatiblePadTemplate, getContext, getContextUnlocked, getContexts, getControlBinding, getControlRate, getCurrentClockTime, getCurrentRunningTime, getData, getFactory, getFrame, getFrames, getGValueArray, getLatency, getMaxEncodeTime, getMeta, getMetadata, getMinForceKeyUnitInterval, getName, getOldestFrame, getOutputState, getPadTemplate, getPadTemplateList, getParent, getPathString, getPresetNames, getProperty, getPropertyNames, getQdata, getRequestPad, getStartTime, getState, getStaticPad, getValue.

Setters

setBaseTime, setBus, setClock, setContext, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setData, setDataFull, setHeaders, setLatency, setLockedState, setMeta, setMinForceKeyUnitInterval, setMinPts, setName, setOutputState, setParent, setProperty, setQosEnabled, setStartTime, setState.

allocateOutputBuffer

videoEncoderAllocateOutputBuffer Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Word64

size: size of the buffer

-> m Buffer

Returns: allocated buffer

Helper function that allocates a buffer to hold an encoded video frame for encoder's current VideoCodecState.

allocateOutputFrame

videoEncoderAllocateOutputFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: a VideoCodecFrame

-> Word64

size: size of the buffer

-> m FlowReturn

Returns: FlowReturnOk if an output buffer could be allocated

Helper function that allocates a buffer to hold an encoded video frame for encoder's current VideoCodecState. Subclass should already have configured video state and set src pad caps.

The buffer allocated here is owned by the frame and you should only keep references to the frame, not the buffer.

finishFrame

videoEncoderFinishFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: an encoded VideoCodecFrame

-> m FlowReturn

Returns: a FlowReturn resulting from sending data downstream

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 prePush. In any case, the frame is considered finished and released.

After calling this function the output buffer of the frame is to be considered read-only. This function will also change the metadata of the buffer.

finishSubframe

videoEncoderFinishSubframe Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: a VideoCodecFrame being encoded

-> m FlowReturn

Returns: a FlowReturn resulting from pushing the buffer downstream.

If multiple subframes are produced for one input frame then use this method for each subframe, except for the last one. Before calling this function, you need to fill frame->output_buffer with the encoded buffer to push.

You must call gst_video_encoder_finish_frame() for the last sub-frame to tell the encoder that the frame has been fully encoded.

This function will change the metadata of frame and frame->output_buffer will be pushed downstream.

Since: 1.18

getAllocator

videoEncoderGetAllocator Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m (Allocator, AllocationParams) 

Lets VideoEncoder sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after use it.

getFrame

videoEncoderGetFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Int32

frameNumber: system_frame_number of a frame

-> m VideoCodecFrame

Returns: pending unfinished VideoCodecFrame identified by frameNumber.

Get a pending unfinished VideoCodecFrame

getFrames

videoEncoderGetFrames Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m [VideoCodecFrame]

Returns: pending unfinished VideoCodecFrame.

Get all pending unfinished VideoCodecFrame

getLatency

videoEncoderGetLatency Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m (Word64, Word64) 

Query the configured encoding latency. Results will be returned via minLatency and maxLatency.

getMaxEncodeTime

videoEncoderGetMaxEncodeTime Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: a VideoCodecFrame

-> m Int64

Returns: max decoding time.

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

If no QoS events have been received from downstream, or if VideoEncoder:qos is disabled this function returns MAXINT64.

Since: 1.14

getMinForceKeyUnitInterval

videoEncoderGetMinForceKeyUnitInterval Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: the encoder

-> m Word64

Returns: the minimum force-keyunit interval

Returns the minimum force-keyunit interval, see videoEncoderSetMinForceKeyUnitInterval for more details.

Since: 1.18

getOldestFrame

videoEncoderGetOldestFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m VideoCodecFrame

Returns: oldest unfinished pending VideoCodecFrame

Get the oldest unfinished pending VideoCodecFrame

getOutputState

videoEncoderGetOutputState Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m VideoCodecState

Returns: VideoCodecState describing format of video data.

Get the current VideoCodecState

isQosEnabled

videoEncoderIsQosEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: the encoder

-> m Bool

Returns: True if the encoder is configured to perform Quality-of-Service.

Checks if encoder is currently configured to handle Quality-of-Service events from downstream.

Since: 1.14

mergeTags

videoEncoderMergeTags Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Maybe TagList

tags: a TagList to merge, or NULL to unset previously-set tags

-> TagMergeMode

mode: the TagMergeMode to use, usually GST_TAG_MERGE_REPLACE

-> m () 

Sets the video encoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with videoEncoderMergeTags.

Note that this is provided for convenience, and the subclass is not required to use this and can still do tag handling on its own.

MT safe.

negotiate

videoEncoderNegotiate Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> m Bool

Returns: True if the negotiation succeeded, else False.

Negotiate with downstream elements to currently configured VideoCodecState. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails.

proxyGetcaps

videoEncoderProxyGetcaps Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

enc: a VideoEncoder

-> Maybe Caps

caps: initial caps

-> Maybe Caps

filter: filter caps

-> m Caps

Returns: a Caps owned by caller

Returns caps that express caps (or sink template caps if caps == NULL) restricted to resolution/format/... combinations supported by downstream elements (e.g. muxers).

setHeaders

videoEncoderSetHeaders Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> [Buffer]

headers: a list of Buffer containing the codec header

-> m () 

Set the codec headers to be sent downstream whenever requested.

setLatency

videoEncoderSetLatency Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Word64

minLatency: minimum latency

-> Word64

maxLatency: maximum latency

-> m () 

Informs baseclass of encoding latency.

setMinForceKeyUnitInterval

videoEncoderSetMinForceKeyUnitInterval Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: the encoder

-> Word64

interval: minimum interval

-> m () 

Sets the minimum interval for requesting keyframes based on force-keyunit events. Setting this to 0 will allow to handle every event, setting this to CLOCK_TIME_NONE causes force-keyunit events to be ignored.

Since: 1.18

setMinPts

videoEncoderSetMinPts Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Word64

minPts: minimal PTS that will be passed to handle_frame

-> m () 

Request minimal value for PTS passed to handle_frame.

For streams with reordered frames this can be used to ensure that there is enough time to accommodate first DTS, which may be less than first PTS

Since: 1.6

setOutputState

videoEncoderSetOutputState Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: a VideoEncoder

-> Caps

caps: the Caps to use for the output

-> Maybe VideoCodecState

reference: An optional reference gstVideoCodecState

-> m VideoCodecState

Returns: the newly configured output state.

Creates a new VideoCodecState with the specified caps as the output state for the encoder. Any previously set output state on encoder will be replaced by the newly created one.

The specified caps should not contain any resolution, pixel-aspect-ratio, framerate, codec-data, .... Those should be specified instead in the returned VideoCodecState.

If the subclass wishes to copy over existing fields (like pixel aspect ratio, or framerate) from an existing VideoCodecState, it can be provided as a reference.

If the subclass wishes to override some fields from the output state (like pixel-aspect-ratio or framerate) it can do so on the returned VideoCodecState.

The new output state will only take effect (set on pads and buffers) starting from the next call to gst_video_encoder_finish_frame().

setQosEnabled

videoEncoderSetQosEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a) 
=> a

encoder: the encoder

-> Bool

enabled: the new qos value.

-> m () 

Configures encoder to handle Quality-of-Service events from downstream.

Since: 1.14

Properties

minForceKeyUnitInterval

Minimum interval between force-keyunit requests in nanoseconds. See videoEncoderSetMinForceKeyUnitInterval for more details.

Since: 1.18

constructVideoEncoderMinForceKeyUnitInterval :: (IsVideoEncoder o, MonadIO m) => Word64 -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “min-force-key-unit-interval” property. This is rarely needed directly, but it is used by new.

getVideoEncoderMinForceKeyUnitInterval :: (MonadIO m, IsVideoEncoder o) => o -> m Word64 Source #

Get the value of the “min-force-key-unit-interval” property. When overloading is enabled, this is equivalent to

get videoEncoder #minForceKeyUnitInterval

setVideoEncoderMinForceKeyUnitInterval :: (MonadIO m, IsVideoEncoder o) => o -> Word64 -> m () Source #

Set the value of the “min-force-key-unit-interval” property. When overloading is enabled, this is equivalent to

set videoEncoder [ #minForceKeyUnitInterval := value ]

qos

No description available in the introspection data.

constructVideoEncoderQos :: (IsVideoEncoder o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “qos” property. This is rarely needed directly, but it is used by new.

getVideoEncoderQos :: (MonadIO m, IsVideoEncoder o) => o -> m Bool Source #

Get the value of the “qos” property. When overloading is enabled, this is equivalent to

get videoEncoder #qos

setVideoEncoderQos :: (MonadIO m, IsVideoEncoder o) => o -> Bool -> m () Source #

Set the value of the “qos” property. When overloading is enabled, this is equivalent to

set videoEncoder [ #qos := value ]