From 27662d5fb89dec28f5e77cf60eea26c33ebc806f Mon Sep 17 00:00:00 2001
From: Seungha Yang <seungha@centricular.com>
Date: Tue, 12 Mar 2024 01:22:03 +0900
Subject: [PATCH] bufferpool: Clarify GstBufferPoolClass::start() usage

Make it clear that chaining up to the default implementation
is optional if subclasses do not want preallocation.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/6328>
---
 girs/Gst-1.0.gir                          | 5 ++++-
 subprojects/gstreamer/gst/gstbufferpool.h | 3 +++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/girs/Gst-1.0.gir b/girs/Gst-1.0.gir
index 4765abc16d..52748beb10 100644
--- a/girs/Gst-1.0.gir
+++ b/girs/Gst-1.0.gir
@@ -4413,7 +4413,10 @@ This function takes ownership of @config.</doc>
       </virtual-method>
       <virtual-method name="start">
         <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstbufferpool.h">Start the bufferpool. The default implementation will preallocate
-min-buffers buffers and put them in the queue.</doc>
+min-buffers buffers and put them in the queue.
+
+Subclasses do not need to chain up to the parent's default implementation
+if they don't want min-buffers based preallocation.</doc>
         <source-position filename="../subprojects/gstreamer/gst/gstbufferpool.h"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstbufferpool.h">whether the pool could be started.</doc>
diff --git a/subprojects/gstreamer/gst/gstbufferpool.h b/subprojects/gstreamer/gst/gstbufferpool.h
index 5d69fa7d45..22ec29e43b 100644
--- a/subprojects/gstreamer/gst/gstbufferpool.h
+++ b/subprojects/gstreamer/gst/gstbufferpool.h
@@ -157,6 +157,9 @@ struct _GstBufferPoolClass {
    * Start the bufferpool. The default implementation will preallocate
    * min-buffers buffers and put them in the queue.
    *
+   * Subclasses do not need to chain up to the parent's default implementation
+   * if they don't want min-buffers based preallocation.
+   *
    * Returns: whether the pool could be started.
    */
   gboolean       (*start)          (GstBufferPool *pool);