sample: Add gst_clear_sample() method

Similar to other GstMiniObject clear helper methods like
gst_clear_buffer().

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

3 files changed, 48 insertions, 2 deletions

diff --git a/girs/Gst-1.0.gir b/girs/Gst-1.0.gir
index effa21f91c..f57e64376e 100644
--- a/girs/Gst-1.0.gir
+++ b/girs/Gst-1.0.gir
@@ -38632,11 +38632,11 @@ Free-function: gst_sample_unref</doc>
 copy of the data the source sample contains.</doc>
         <source-position filename="../subprojects/gstreamer/gst/gstsample.h"/>
         <return-value transfer-ownership="full">
-          <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstsample.c">a new copy of @buf.</doc>
+          <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstsample.c">a new copy of @sample.</doc>
           <type name="Sample" c:type="GstSample*"/>
         </return-value>
         <parameters>
-          <instance-parameter name="buf" transfer-ownership="none">
+          <instance-parameter name="sample" transfer-ownership="none">
             <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstsample.c">a #GstSample.</doc>
             <type name="Sample" c:type="const GstSample*"/>
           </instance-parameter>
@@ -49789,6 +49789,24 @@ reference count of the query is decreased and the pointer is set to %NULL.</doc>
         </parameter>
       </parameters>
     </function>
+    <function name="clear_sample" c:identifier="gst_clear_sample" version="1.24" introspectable="0">
+      <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstsample.c">Clears a reference to a #GstSample
+
+@sample_ptr must not be %NULL.
+
+If the reference is %NULL then this function does nothing. Otherwise, the
+reference count of the sample is decreased and the pointer is set to %NULL.</doc>
+      <source-position filename="../subprojects/gstreamer/gst/gstsample.h"/>
+      <return-value transfer-ownership="none">
+        <type name="none" c:type="void"/>
+      </return-value>
+      <parameters>
+        <parameter name="sample_ptr" transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstsample.c">a pointer to a #GstSample reference</doc>
+          <type name="Sample" c:type="GstSample**"/>
+        </parameter>
+      </parameters>
+    </function>
     <function name="clear_structure" c:identifier="gst_clear_structure" version="1.16" introspectable="0">
       <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gststructure.c">Clears a reference to a #GstStructure.
 
diff --git a/subprojects/gstreamer/gst/gstsample.c b/subprojects/gstreamer/gst/gstsample.c
index b8af1a3432..09e3f03691 100644
--- a/subprojects/gstreamer/gst/gstsample.c
+++ b/subprojects/gstreamer/gst/gstsample.c
@@ -479,3 +479,22 @@ gst_sample_copy (const GstSample * sample)
       GST_SAMPLE_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST
           (sample)));
 }
+
+/**
+ * gst_clear_sample: (skip)
+ * @sample_ptr: a pointer to a #GstSample reference
+ *
+ * Clears a reference to a #GstSample
+ *
+ * @sample_ptr must not be %NULL.
+ *
+ * If the reference is %NULL then this function does nothing. Otherwise, the
+ * reference count of the sample is decreased and the pointer is set to %NULL.
+ *
+ * Since: 1.24
+ */
+void
+gst_clear_sample (GstSample ** sample_ptr)
+{
+  gst_clear_mini_object ((GstMiniObject **) sample_ptr);
+}
diff --git a/subprojects/gstreamer/gst/gstsample.h b/subprojects/gstreamer/gst/gstsample.h
index ab83143d2b..da59ff9344 100644
--- a/subprojects/gstreamer/gst/gstsample.h
+++ b/subprojects/gstreamer/gst/gstsample.h
@@ -154,9 +154,18 @@ gst_sample_copy (const GstSample * sample)
 {
   return GST_SAMPLE_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (sample)));
 }
+
+static inline void
+gst_clear_sample (GstSample ** sample_ptr)
+{
+  gst_clear_mini_object ((GstMiniObject **) sample_ptr);
+}
 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 GST_API
 GstSample *   gst_sample_copy (const GstSample * sample);
+
+GST_API
+void          gst_clear_sample (GstSample ** sample_ptr);
 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 
 /**