1/* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 *
5 * gstbin.h: Header for GstBin container object
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., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
21 */
22
23
24#ifndef __GST_BIN_H__
25#define __GST_BIN_H__
26
27#include <gst/gstelement.h>
28#include <gst/gstiterator.h>
29#include <gst/gstbus.h>
30
31G_BEGIN_DECLS
32
33#define GST_TYPE_BIN (gst_bin_get_type ())
34#define GST_IS_BIN(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BIN))
35#define GST_IS_BIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BIN))
36#define GST_BIN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BIN, GstBinClass))
37#define GST_BIN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BIN, GstBin))
38#define GST_BIN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BIN, GstBinClass))
39#define GST_BIN_CAST(obj) ((GstBin*)(obj))
40
41/**
42 * GstBinFlags:
43 * @GST_BIN_FLAG_LAST: the last enum in the series of flags for bins.
44 * Derived classes can use this as first value in a list of flags.
45 *
46 * GstBinFlags are a set of flags specific to bins. Most are set/used
47 * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro,
48 * and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET ().
49 */
50typedef enum {
51 /* padding */
52 GST_BIN_FLAG_LAST = (GST_ELEMENT_FLAG_LAST << 5)
53} GstBinFlags;
54
55typedef struct _GstBin GstBin;
56typedef struct _GstBinClass GstBinClass;
57typedef struct _GstBinPrivate GstBinPrivate;
58
59/**
60 * GST_BIN_NUMCHILDREN:
61 * @bin: a #GstBin
62 *
63 * Gets the number of children in a bin.
64 */
65#define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren)
66/**
67 * GST_BIN_CHILDREN:
68 * @bin: a #GstBin
69 *
70 * Gets the list with children in a bin.
71 */
72#define GST_BIN_CHILDREN(bin) (GST_BIN_CAST(bin)->children)
73/**
74 * GST_BIN_CHILDREN_COOKIE:
75 * @bin: a #GstBin
76 *
77 * Gets the children cookie that watches the children list.
78 */
79#define GST_BIN_CHILDREN_COOKIE(bin) (GST_BIN_CAST(bin)->children_cookie)
80
81/**
82 * GstBin:
83 * @numchildren: the number of children in this bin
84 * @children: the list of children in this bin
85 * @children_cookie: updated whenever @children changes
86 * @child_bus: internal bus for handling child messages
87 * @messages: queued and cached messages
88 * @polling: the bin is currently calculating its state
89 * @state_dirty: the bin needs to recalculate its state (deprecated)
90 * @clock_dirty: the bin needs to select a new clock
91 * @provided_clock: the last clock selected
92 * @clock_provider: the element that provided @provided_clock
93 *
94 * The GstBin base class. Subclasses can access these fields provided
95 * the LOCK is taken.
96 */
97struct _GstBin {
98 GstElement element;
99
100 /*< public >*/ /* with LOCK */
101 /* our children, subclass are supposed to update these
102 * fields to reflect their state with _iterate_*() */
103 gint numchildren;
104 GList *children;
105 guint32 children_cookie;
106
107 GstBus *child_bus;
108 GList *messages;
109
110 gboolean polling;
111 gboolean state_dirty;
112
113 gboolean clock_dirty;
114 GstClock *provided_clock;
115 GstElement *clock_provider;
116
117 /*< private >*/
118 GstBinPrivate *priv;
119
120 gpointer _gst_reserved[GST_PADDING - 1];
121};
122
123/**
124 * GstBinClass:
125 * @parent_class: bin parent class
126 * @add_element: method to add an element to a bin
127 * @remove_element: method to remove an element from a bin
128 * @handle_message: method to handle a message from the children
129 *
130 * Subclasses can override the @add_element and @remove_element to
131 * update the list of children in the bin.
132 *
133 * The @handle_message method can be overridden to implement custom
134 * message handling. @handle_message takes ownership of the message, just like
135 * #gst_element_post_message.
136 */
137struct _GstBinClass {
138 GstElementClass parent_class;
139
140 /*< private >*/
141 GThreadPool *pool;
142
143 /* signals */
144 void (*element_added) (GstBin *bin, GstElement *child);
145 void (*element_removed) (GstBin *bin, GstElement *child);
146
147 /*< public >*/
148 /* virtual methods for subclasses */
149 gboolean (*add_element) (GstBin *bin, GstElement *element);
150 gboolean (*remove_element) (GstBin *bin, GstElement *element);
151
152 void (*handle_message) (GstBin *bin, GstMessage *message);
153
154 /*< private >*/
155 /* signal added 0.10.22 */
156 gboolean (*do_latency) (GstBin *bin);
157
158 /*< private >*/
159 gpointer _gst_reserved[GST_PADDING-1];
160};
161
162GType gst_bin_get_type (void);
163GstElement* gst_bin_new (const gchar *name);
164
165/* add and remove elements from the bin */
166gboolean gst_bin_add (GstBin *bin, GstElement *element);
167gboolean gst_bin_remove (GstBin *bin, GstElement *element);
168
169/* retrieve a single child */
170GstElement* gst_bin_get_by_name (GstBin *bin, const gchar *name);
171GstElement* gst_bin_get_by_name_recurse_up (GstBin *bin, const gchar *name);
172GstElement* gst_bin_get_by_interface (GstBin *bin, GType iface);
173
174/* retrieve multiple children */
175GstIterator* gst_bin_iterate_elements (GstBin *bin);
176GstIterator* gst_bin_iterate_sorted (GstBin *bin);
177GstIterator* gst_bin_iterate_recurse (GstBin *bin);
178
179GstIterator* gst_bin_iterate_sinks (GstBin *bin);
180GstIterator* gst_bin_iterate_sources (GstBin *bin);
181GstIterator* gst_bin_iterate_all_by_interface (GstBin *bin, GType iface);
182
183/* latency */
184gboolean gst_bin_recalculate_latency (GstBin * bin);
185
186
187G_END_DECLS
188
189
190#endif /* __GST_BIN_H__ */
191