basesink: Fix annotations
[platform/upstream/gstreamer.git] / subprojects / gstreamer / libs / gst / base / gstbasesink.h
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  *                    2000 Wim Taymans <wtay@chello.be>
4  *
5  * gstbasesink.h:
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20  * Boston, MA 02110-1301, USA.
21  */
22
23 #ifndef __GST_BASE_SINK_H__
24 #define __GST_BASE_SINK_H__
25
26 #include <gst/gst.h>
27 #include <gst/base/base-prelude.h>
28
29 G_BEGIN_DECLS
30
31
32 #define GST_TYPE_BASE_SINK              (gst_base_sink_get_type())
33 #define GST_BASE_SINK(obj)              (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_SINK,GstBaseSink))
34 #define GST_BASE_SINK_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_SINK,GstBaseSinkClass))
35 #define GST_BASE_SINK_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BASE_SINK, GstBaseSinkClass))
36 #define GST_IS_BASE_SINK(obj)           (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SINK))
37 #define GST_IS_BASE_SINK_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SINK))
38 #define GST_BASE_SINK_CAST(obj)         ((GstBaseSink *) (obj))
39
40 /**
41  * GST_BASE_SINK_PAD:
42  * @obj: base sink instance
43  *
44  * Gives the pointer to the #GstPad object of the element.
45  */
46 #define GST_BASE_SINK_PAD(obj)          (GST_BASE_SINK_CAST (obj)->sinkpad)
47
48 #define GST_BASE_SINK_GET_PREROLL_LOCK(obj)   (&GST_BASE_SINK_CAST(obj)->preroll_lock)
49 #define GST_BASE_SINK_PREROLL_LOCK(obj)       (g_mutex_lock(GST_BASE_SINK_GET_PREROLL_LOCK(obj)))
50 #define GST_BASE_SINK_PREROLL_TRYLOCK(obj)    (g_mutex_trylock(GST_BASE_SINK_GET_PREROLL_LOCK(obj)))
51 #define GST_BASE_SINK_PREROLL_UNLOCK(obj)     (g_mutex_unlock(GST_BASE_SINK_GET_PREROLL_LOCK(obj)))
52
53 #define GST_BASE_SINK_GET_PREROLL_COND(obj)   (&GST_BASE_SINK_CAST(obj)->preroll_cond)
54 #define GST_BASE_SINK_PREROLL_WAIT(obj)       \
55       g_cond_wait (GST_BASE_SINK_GET_PREROLL_COND (obj), GST_BASE_SINK_GET_PREROLL_LOCK (obj))
56 #define GST_BASE_SINK_PREROLL_WAIT_UNTIL(obj, end_time) \
57       g_cond_wait_until (GST_BASE_SINK_GET_PREROLL_COND (obj), GST_BASE_SINK_GET_PREROLL_LOCK (obj), end_time)
58 #define GST_BASE_SINK_PREROLL_SIGNAL(obj)     g_cond_signal (GST_BASE_SINK_GET_PREROLL_COND (obj));
59 #define GST_BASE_SINK_PREROLL_BROADCAST(obj)  g_cond_broadcast (GST_BASE_SINK_GET_PREROLL_COND (obj));
60
61 typedef struct _GstBaseSink GstBaseSink;
62 typedef struct _GstBaseSinkClass GstBaseSinkClass;
63 typedef struct _GstBaseSinkPrivate GstBaseSinkPrivate;
64
65 /**
66  * GstBaseSink:
67  *
68  * The opaque #GstBaseSink data structure.
69  */
70 struct _GstBaseSink {
71   GstElement     element;
72
73   /*< protected >*/
74   GstPad        *sinkpad;
75   GstPadMode     pad_mode;
76
77   /*< protected >*/ /* with LOCK */
78   guint64        offset;
79   gboolean       can_activate_pull;
80   gboolean       can_activate_push;
81
82   /*< protected >*/ /* with PREROLL_LOCK */
83   GMutex         preroll_lock;
84   GCond          preroll_cond;
85   gboolean       eos;
86   gboolean       need_preroll;
87   gboolean       have_preroll;
88   gboolean       playing_async;
89
90   /*< protected >*/ /* with STREAM_LOCK */
91   gboolean       have_newsegment;
92   GstSegment     segment;
93
94   /*< private >*/ /* with LOCK */
95   GstClockID     clock_id;
96   gboolean       sync;
97   gboolean       flushing;
98   gboolean       running;
99
100   gint64         max_lateness;
101
102   /*< private >*/
103   GstBaseSinkPrivate *priv;
104
105   gpointer _gst_reserved[GST_PADDING_LARGE];
106 };
107
108 /**
109  * GstBaseSinkClass:
110  * @parent_class: Element parent class
111  * @get_caps: Called to get sink pad caps from the subclass
112  * @set_caps: Notify subclass of changed caps
113  * @fixate: Only useful in pull mode. Implement if you have
114  *     ideas about what should be the default values for the caps you support.
115  * @activate_pull: Subclasses should override this when they can provide an
116  *     alternate method of spawning a thread to drive the pipeline in pull mode.
117  *     Should start or stop the pulling thread, depending on the value of the
118  *     "active" argument. Called after actually activating the sink pad in pull
119  *     mode. The default implementation starts a task on the sink pad.
120  * @get_times: Called to get the start and end times for synchronising
121  *     the passed buffer to the clock
122  * @propose_allocation: configure the allocation query
123  * @start: Start processing. Ideal for opening resources in the subclass
124  * @stop: Stop processing. Subclasses should use this to close resources.
125  * @unlock: Unlock any pending access to the resource. Subclasses should
126  *     unblock any blocked function ASAP and call gst_base_sink_wait_preroll()
127  * @unlock_stop: Clear the previous unlock request. Subclasses should clear
128  *     any state they set during #GstBaseSinkClass::unlock, and be ready to
129  *     continue where they left off after gst_base_sink_wait_preroll(),
130  *     gst_base_sink_wait() or gst_wait_sink_wait_clock() return or
131  *     #GstBaseSinkClass::render is called again.
132  * @query: perform a #GstQuery on the element.
133  * @event: Override this to handle events arriving on the sink pad
134  * @wait_event: Override this to implement custom logic to wait for the event
135  *     time (for events like EOS and GAP). Subclasses should always first
136  *     chain up to the default implementation.
137  * @prepare: Called to prepare the buffer for @render and @preroll. This
138  *     function is called before synchronisation is performed.
139  * @prepare_list: Called to prepare the buffer list for @render_list. This
140  *     function is called before synchronisation is performed.
141  * @preroll: Called to present the preroll buffer if desired.
142  * @render: Called when a buffer should be presented or output, at the
143  *     correct moment if the #GstBaseSink has been set to sync to the clock.
144  * @render_list: Same as @render but used with buffer lists instead of
145  *     buffers.
146  *
147  * Subclasses can override any of the available virtual methods or not, as
148  * needed. At the minimum, the @render method should be overridden to
149  * output/present buffers.
150  */
151 struct _GstBaseSinkClass {
152   GstElementClass parent_class;
153
154   /**
155    * GstBaseSinkClass::get_caps:
156    * @filter: (in) (nullable):
157    *
158    * Called to get sink pad caps from the subclass.
159    */
160   GstCaps*      (*get_caps)     (GstBaseSink *sink, GstCaps *filter);
161   /* notify subclass of new caps */
162   gboolean      (*set_caps)     (GstBaseSink *sink, GstCaps *caps);
163
164   /* fixate sink caps during pull-mode negotiation */
165   GstCaps *     (*fixate)       (GstBaseSink *sink, GstCaps *caps);
166   /* start or stop a pulling thread */
167   gboolean      (*activate_pull)(GstBaseSink *sink, gboolean active);
168
169   /**
170    * GstBaseSinkClass::get_times:
171    * @start: (out): the start #GstClockTime
172    * @end: (out): the end #GstClockTime
173    *
174    * Get the start and end times for syncing on this buffer.
175    */
176   void          (*get_times)    (GstBaseSink *sink, GstBuffer *buffer,
177                                  GstClockTime *start, GstClockTime *end);
178
179   /* propose allocation parameters for upstream */
180   gboolean      (*propose_allocation)   (GstBaseSink *sink, GstQuery *query);
181
182   /* start and stop processing, ideal for opening/closing the resource */
183   gboolean      (*start)        (GstBaseSink *sink);
184   gboolean      (*stop)         (GstBaseSink *sink);
185
186   /* unlock any pending access to the resource. subclasses should unlock
187    * any function ASAP. */
188   gboolean      (*unlock)       (GstBaseSink *sink);
189   /* Clear a previously indicated unlock request not that unlocking is
190    * complete. Sub-classes should clear any command queue or indicator they
191    * set during unlock */
192   gboolean      (*unlock_stop)  (GstBaseSink *sink);
193
194   /* notify subclass of query */
195   gboolean      (*query)        (GstBaseSink *sink, GstQuery *query);
196
197   /* notify subclass of event */
198   gboolean      (*event)        (GstBaseSink *sink, GstEvent *event);
199   /* wait for eos or gap, subclasses should chain up to parent first */
200   GstFlowReturn (*wait_event)   (GstBaseSink *sink, GstEvent *event);
201
202   /* notify subclass of buffer or list before doing sync */
203   GstFlowReturn (*prepare)      (GstBaseSink *sink, GstBuffer *buffer);
204   GstFlowReturn (*prepare_list) (GstBaseSink *sink, GstBufferList *buffer_list);
205
206   /* notify subclass of preroll buffer or real buffer */
207   GstFlowReturn (*preroll)      (GstBaseSink *sink, GstBuffer *buffer);
208   GstFlowReturn (*render)       (GstBaseSink *sink, GstBuffer *buffer);
209   /* Render a BufferList */
210   GstFlowReturn (*render_list)  (GstBaseSink *sink, GstBufferList *buffer_list);
211
212   /*< private >*/
213   gpointer       _gst_reserved[GST_PADDING_LARGE];
214 };
215
216 GST_BASE_API
217 GType           gst_base_sink_get_type (void);
218
219 GST_BASE_API
220 GstFlowReturn   gst_base_sink_do_preroll        (GstBaseSink *sink, GstMiniObject *obj);
221
222 GST_BASE_API
223 GstFlowReturn   gst_base_sink_wait_preroll      (GstBaseSink *sink);
224
225 /* synchronizing against the clock */
226
227 GST_BASE_API
228 void            gst_base_sink_set_sync          (GstBaseSink *sink, gboolean sync);
229
230 GST_BASE_API
231 gboolean        gst_base_sink_get_sync          (GstBaseSink *sink);
232
233 /* Drop buffers which are out of segment */
234
235 GST_BASE_API
236 void            gst_base_sink_set_drop_out_of_segment (GstBaseSink *sink, gboolean drop_out_of_segment);
237
238 GST_BASE_API
239 gboolean        gst_base_sink_get_drop_out_of_segment (GstBaseSink *sink);
240
241 /* dropping late buffers */
242
243 GST_BASE_API
244 void            gst_base_sink_set_max_lateness  (GstBaseSink *sink, gint64 max_lateness);
245
246 GST_BASE_API
247 gint64          gst_base_sink_get_max_lateness  (GstBaseSink *sink);
248
249 /* performing QoS */
250
251 GST_BASE_API
252 void            gst_base_sink_set_qos_enabled   (GstBaseSink *sink, gboolean enabled);
253
254 GST_BASE_API
255 gboolean        gst_base_sink_is_qos_enabled    (GstBaseSink *sink);
256
257 /* doing async state changes */
258
259 GST_BASE_API
260 void            gst_base_sink_set_async_enabled (GstBaseSink *sink, gboolean enabled);
261
262 GST_BASE_API
263 gboolean        gst_base_sink_is_async_enabled  (GstBaseSink *sink);
264
265 /* tuning synchronisation */
266
267 GST_BASE_API
268 void            gst_base_sink_set_ts_offset     (GstBaseSink *sink, GstClockTimeDiff offset);
269
270 GST_BASE_API
271 GstClockTimeDiff gst_base_sink_get_ts_offset    (GstBaseSink *sink);
272
273 /* last sample */
274
275 GST_BASE_API
276 GstSample *     gst_base_sink_get_last_sample   (GstBaseSink *sink);
277
278 GST_BASE_API
279 void            gst_base_sink_set_last_sample_enabled (GstBaseSink *sink, gboolean enabled);
280
281 GST_BASE_API
282 gboolean        gst_base_sink_is_last_sample_enabled (GstBaseSink *sink);
283
284 /* latency */
285
286 GST_BASE_API
287 gboolean        gst_base_sink_query_latency     (GstBaseSink *sink, gboolean *live, gboolean *upstream_live,
288                                                  GstClockTime *min_latency, GstClockTime *max_latency);
289 GST_BASE_API
290 GstClockTime    gst_base_sink_get_latency       (GstBaseSink *sink);
291
292 /* render delay */
293
294 GST_BASE_API
295 void            gst_base_sink_set_render_delay  (GstBaseSink *sink, GstClockTime delay);
296
297 GST_BASE_API
298 GstClockTime    gst_base_sink_get_render_delay  (GstBaseSink *sink);
299
300 /* blocksize */
301
302 GST_BASE_API
303 void            gst_base_sink_set_blocksize     (GstBaseSink *sink, guint blocksize);
304
305 GST_BASE_API
306 guint           gst_base_sink_get_blocksize     (GstBaseSink *sink);
307
308 /* throttle-time */
309
310 GST_BASE_API
311 void            gst_base_sink_set_throttle_time (GstBaseSink *sink, guint64 throttle);
312
313 GST_BASE_API
314 guint64         gst_base_sink_get_throttle_time (GstBaseSink *sink);
315
316 /* max-bitrate */
317
318 GST_BASE_API
319 void            gst_base_sink_set_max_bitrate   (GstBaseSink *sink, guint64 max_bitrate);
320
321 GST_BASE_API
322 guint64         gst_base_sink_get_max_bitrate   (GstBaseSink *sink);
323
324 /* processing deadline */
325 GST_BASE_API
326 void            gst_base_sink_set_processing_deadline  (GstBaseSink *sink, GstClockTime processing_deadline);
327
328 GST_BASE_API
329 GstClockTime    gst_base_sink_get_processing_deadline  (GstBaseSink *sink);
330
331 GST_BASE_API
332 GstClockReturn  gst_base_sink_wait_clock        (GstBaseSink *sink, GstClockTime time,
333                                                  GstClockTimeDiff * jitter);
334 GST_BASE_API
335 GstFlowReturn   gst_base_sink_wait              (GstBaseSink *sink, GstClockTime time,
336                                                  GstClockTimeDiff *jitter);
337
338 GST_BASE_API
339 GstStructure    *gst_base_sink_get_stats (GstBaseSink * sink);
340
341 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseSink, gst_object_unref)
342
343 G_END_DECLS
344
345 #endif /* __GST_BASE_SINK_H__ */