Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
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 togstVideoEncoderFinishFrame
.
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
- newtype VideoEncoder = VideoEncoder (ManagedPtr VideoEncoder)
- class (GObject o, IsDescendantOf VideoEncoder o) => IsVideoEncoder o
- toVideoEncoder :: (MonadIO m, IsVideoEncoder o) => o -> m VideoEncoder
- videoEncoderAllocateOutputBuffer :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Word64 -> m Buffer
- videoEncoderAllocateOutputFrame :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> VideoCodecFrame -> Word64 -> m FlowReturn
- videoEncoderFinishFrame :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> VideoCodecFrame -> m FlowReturn
- videoEncoderGetAllocator :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m (Allocator, AllocationParams)
- videoEncoderGetFrame :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Int32 -> m VideoCodecFrame
- videoEncoderGetFrames :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m [VideoCodecFrame]
- videoEncoderGetLatency :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m (Word64, Word64)
- videoEncoderGetMaxEncodeTime :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> VideoCodecFrame -> m Int64
- videoEncoderGetOldestFrame :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m VideoCodecFrame
- videoEncoderGetOutputState :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m VideoCodecState
- videoEncoderIsQosEnabled :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m Bool
- videoEncoderMergeTags :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Maybe TagList -> TagMergeMode -> m ()
- videoEncoderNegotiate :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> m Bool
- videoEncoderProxyGetcaps :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Maybe Caps -> Maybe Caps -> m Caps
- videoEncoderSetHeaders :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> [Buffer] -> m ()
- videoEncoderSetLatency :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Word64 -> Word64 -> m ()
- videoEncoderSetMinPts :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Word64 -> m ()
- videoEncoderSetOutputState :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Caps -> Maybe VideoCodecState -> m VideoCodecState
- videoEncoderSetQosEnabled :: (HasCallStack, MonadIO m, IsVideoEncoder a) => a -> Bool -> m ()
- constructVideoEncoderQos :: (IsVideoEncoder o, MonadIO m) => Bool -> m (GValueConstruct o)
- getVideoEncoderQos :: (MonadIO m, IsVideoEncoder o) => o -> m Bool
- setVideoEncoderQos :: (MonadIO m, IsVideoEncoder o) => o -> Bool -> m ()
Exported types
newtype VideoEncoder Source #
Memory-managed wrapper type.
VideoEncoder (ManagedPtr VideoEncoder) |
Instances
Eq VideoEncoder Source # | |
Defined in GI.GstVideo.Objects.VideoEncoder (==) :: VideoEncoder -> VideoEncoder -> Bool (/=) :: VideoEncoder -> VideoEncoder -> Bool | |
GObject VideoEncoder Source # | |
Defined in GI.GstVideo.Objects.VideoEncoder | |
ManagedPtrNewtype VideoEncoder Source # | |
Defined in GI.GstVideo.Objects.VideoEncoder toManagedPtr :: VideoEncoder -> ManagedPtr VideoEncoder | |
TypedObject VideoEncoder Source # | |
Defined in GI.GstVideo.Objects.VideoEncoder glibType :: IO GType | |
IsGValue VideoEncoder Source # | Convert |
Defined in GI.GstVideo.Objects.VideoEncoder toGValue :: VideoEncoder -> IO GValue fromGValue :: GValue -> IO VideoEncoder | |
HasParentTypes VideoEncoder Source # | |
Defined in GI.GstVideo.Objects.VideoEncoder | |
type ParentTypes VideoEncoder Source # | |
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
(GObject o, IsDescendantOf VideoEncoder o) => IsVideoEncoder o Source # | |
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
Overloaded methods
allocateOutputBuffer
videoEncoderAllocateOutputBuffer Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Word64 |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> VideoCodecFrame |
|
-> Word64 |
|
-> m FlowReturn | Returns: |
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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> VideoCodecFrame |
|
-> m FlowReturn | Returns: a |
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.
getAllocator
videoEncoderGetAllocator Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Int32 |
|
-> m VideoCodecFrame | Returns: pending unfinished |
Get a pending unfinished VideoCodecFrame
getFrames
videoEncoderGetFrames Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m [VideoCodecFrame] | Returns: pending unfinished |
Get all pending unfinished VideoCodecFrame
getLatency
videoEncoderGetLatency Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m (Word64, Word64) |
Query the configured encoding latency. Results will be returned via
minLatency
and maxLatency
.
getMaxEncodeTime
videoEncoderGetMaxEncodeTime Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> 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
getOldestFrame
videoEncoderGetOldestFrame Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m VideoCodecFrame | Returns: oldest unfinished pending |
Get the oldest unfinished pending VideoCodecFrame
getOutputState
videoEncoderGetOutputState Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m VideoCodecState | Returns: |
Get the current VideoCodecState
isQosEnabled
videoEncoderIsQosEnabled Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m Bool | Returns: |
Checks if encoder
is currently configured to handle Quality-of-Service
events from downstream.
Since: 1.14
mergeTags
videoEncoderMergeTags Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Maybe TagList |
|
-> TagMergeMode |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> m Bool | Returns: |
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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Maybe Caps |
|
-> Maybe Caps |
|
-> m Caps | Returns: a |
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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> [Buffer] |
|
-> m () |
Set the codec headers to be sent downstream whenever requested.
setLatency
videoEncoderSetLatency Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Word64 |
|
-> Word64 |
|
-> m () |
Informs baseclass of encoding latency.
setMinPts
videoEncoderSetMinPts Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Word64 |
|
-> 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 accomodate first DTS, which may be less than first PTS
Since: 1.6
setOutputState
videoEncoderSetOutputState Source #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Caps |
|
-> Maybe VideoCodecState |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsVideoEncoder a) | |
=> a |
|
-> Bool |
|
-> m () |
Configures encoder
to handle Quality-of-Service events from downstream.
Since: 1.14
Properties
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 ]