videoencoder: Expose release_frame() and drop_frame() as public API

release_frame() can be useful for manually dropping frames without posting QoS messages like finish_frame() would.
Matches the same kind of API on the decoder side of things.

Modifies the behaviour of release_frame() to make sure events from released frames are stored as 'pending'
and pushed before the next non-dropped frame. This is needed because now release_frame() can be called outside of
finish_frame(), so we would potentially just lose events and bad things would happen.

drop_frame() was also added to match the decoder API. It functions almost identically to finish_frame() without a buffer
attached to the frame, except instead of immediately pushing the frame's events, it will store them as pending.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/7190>

1 files changed, 46 insertions, 0 deletions

diff --git a/girs/GstVideo-1.0.gir b/girs/GstVideo-1.0.gir
index f0ac89363c..af1762780a 100644
--- a/girs/GstVideo-1.0.gir
+++ b/girs/GstVideo-1.0.gir
@@ -8929,6 +8929,28 @@ keep references to the frame, not the buffer.</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="drop_frame" c:identifier="gst_video_encoder_drop_frame" version="1.26">
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">Removes @frame from the list of pending frames, releases it
+and posts a QoS message with the frame's details on the bus.
+Similar to calling gst_video_encoder_finish_frame() without a buffer
+attached to @frame, but this function additionally stores events
+from @frame as pending, to be pushed out alongside the next frame
+submitted via gst_video_encoder_finish_frame().</doc>
+        <source-position filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.h"/>
+        <return-value transfer-ownership="none">
+          <type name="none" c:type="void"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="encoder" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">a #GstVideoEncoder</doc>
+            <type name="VideoEncoder" c:type="GstVideoEncoder*"/>
+          </instance-parameter>
+          <parameter name="frame" transfer-ownership="full">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">a #GstVideoCodecFrame</doc>
+            <type name="VideoCodecFrame" c:type="GstVideoCodecFrame*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="finish_frame" c:identifier="gst_video_encoder_finish_frame">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">@frame must have a valid encoded data buffer, whose metadata fields
 are then appropriately set according to frame data or no buffer at
@@ -8936,6 +8958,10 @@ all if the frame should be dropped.
 It is subsequently pushed downstream or provided to @pre_push.
 In any case, the frame is considered finished and released.
 
+If @frame does not have a buffer attached, it will be dropped, and
+a QoS message will be posted on the bus. Events from @frame will be
+pushed out immediately.
+
 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.</doc>
@@ -9216,6 +9242,26 @@ elements (e.g. muxers).</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="release_frame" c:identifier="gst_video_encoder_release_frame" version="1.26">
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">Removes @frame from list of pending frames and releases it, similar
+to calling gst_video_encoder_finish_frame() without a buffer attached
+to the frame, but does not post a QoS message or do any additional
+processing. Events from @frame are moved to the pending events list.</doc>
+        <source-position filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.h"/>
+        <return-value transfer-ownership="none">
+          <type name="none" c:type="void"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="encoder" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">a #GstVideoEncoder</doc>
+            <type name="VideoEncoder" c:type="GstVideoEncoder*"/>
+          </instance-parameter>
+          <parameter name="frame" transfer-ownership="full">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">a #GstVideoCodecFrame</doc>
+            <type name="VideoCodecFrame" c:type="GstVideoCodecFrame*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="set_headers" c:identifier="gst_video_encoder_set_headers">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.c">Set the codec headers to be sent downstream whenever requested.</doc>
         <source-position filename="../subprojects/gst-plugins-base/gst-libs/gst/video/gstvideoencoder.h"/>