1 /* GStreamer
2 *
3 * Copyright (C) <2005> Stefan Kost <ensonic at users dot sf dot net>
4 *
5 * gsthelper.c: GObject convenience methods for using dynamic properties
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 */
23 /**
24 * SECTION:gstcontrollergobject
25 * @short_description: #GObject convenience methods for using dynamic properties
26 * @see_also: #GstController
27 *
28 * These methods allow to use some #GstController functionality directly from
29 * the #GObject class.
30 */
32 #ifdef HAVE_CONFIG_H
33 # include "config.h"
34 #endif
36 #include <stdarg.h>
38 #include "gstcontrollerprivate.h"
39 #include "gstcontroller.h"
41 #define GST_CAT_DEFAULT controller_debug
42 GST_DEBUG_CATEGORY_EXTERN (GST_CAT_DEFAULT);
44 /**
45 * gst_object_control_properties:
46 * @object: the object of which some properties should be controlled
47 * @...: %NULL terminated list of property names that should be controlled
48 *
49 * Convenience function for GObject
50 *
51 * Creates a GstController that allows you to dynamically control one, or more, GObject properties.
52 * If the given GObject already has a GstController, it adds the given properties to the existing
53 * controller and returns that controller.
54 *
55 * Returns: The GstController with which the user can control the given properties dynamically or NULL if
56 * one or more of the given properties aren't available, or cannot be controlled, for the given element.
57 * Since: 0.9
58 */
59 GstController *
60 gst_object_control_properties (GObject * object, ...)
61 {
62 GstController *ctrl;
63 va_list var_args;
65 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
67 va_start (var_args, object);
68 ctrl = gst_controller_new_valist (object, var_args);
69 va_end (var_args);
70 return (ctrl);
71 }
73 /**
74 * gst_object_uncontrol_properties:
75 * @object: the object of which some properties should not be controlled anymore
76 * @...: %NULL terminated list of property names that should be controlled
77 *
78 * Convenience function for GObject
79 *
80 * Removes the given element's properties from it's controller
81 *
82 * Returns: %FALSE if one of the given property names isn't handled by the
83 * controller, %TRUE otherwise
84 * Since: 0.9
85 */
86 gboolean
87 gst_object_uncontrol_properties (GObject * object, ...)
88 {
89 gboolean res = FALSE;
90 GstController *ctrl;
92 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
94 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
95 va_list var_args;
97 va_start (var_args, object);
98 res = gst_controller_remove_properties_valist (ctrl, var_args);
99 va_end (var_args);
100 }
101 return (res);
102 }
104 /**
105 * gst_object_get_controller:
106 * @object: the object that has controlled properties
107 *
108 * Gets the controller for the given GObject
109 *
110 * Returns: the controller handling some of the given element's properties, %NULL if no controller
111 * Since: 0.9
112 */
113 /* FIXME 0.11: This should return a new reference */
114 GstController *
115 gst_object_get_controller (GObject * object)
116 {
117 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
119 return (g_object_get_qdata (object, priv_gst_controller_key));
120 }
122 /**
123 * gst_object_set_controller:
124 * @object: the object that should get the controller
125 * @controller: the controller object to plug in
126 *
127 * Sets the controller on the given GObject
128 *
129 * Returns: %FALSE if the GObject already has an controller, %TRUE otherwise
130 * Since: 0.9
131 */
132 /* FIXME 0.11: This should increase the refcount before storing */
133 gboolean
134 gst_object_set_controller (GObject * object, GstController * controller)
135 {
136 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
137 g_return_val_if_fail (controller, FALSE);
139 if (!g_object_get_qdata (object, priv_gst_controller_key)) {
140 g_object_set_qdata (object, priv_gst_controller_key, controller);
141 return (TRUE);
142 }
143 return (FALSE);
144 }
146 /**
147 * gst_object_suggest_next_sync:
148 * @object: the object that has controlled properties
149 *
150 * Convenience function for GObject
151 *
152 * Returns: same thing as gst_controller_suggest_next_sync()
153 * Since: 0.10.13
154 */
155 GstClockTime
156 gst_object_suggest_next_sync (GObject * object)
157 {
158 GstController *ctrl = NULL;
160 g_return_val_if_fail (G_IS_OBJECT (object), GST_CLOCK_TIME_NONE);
162 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
163 return gst_controller_suggest_next_sync (ctrl);
164 }
165 return (GST_CLOCK_TIME_NONE);
166 }
168 /**
169 * gst_object_sync_values:
170 * @object: the object that has controlled properties
171 * @timestamp: the time that should be processed
172 *
173 * Convenience function for GObject
174 *
175 * Returns: same thing as gst_controller_sync_values()
176 * Since: 0.9
177 */
178 gboolean
179 gst_object_sync_values (GObject * object, GstClockTime timestamp)
180 {
181 GstController *ctrl = NULL;
183 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
185 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
186 return gst_controller_sync_values (ctrl, timestamp);
187 }
188 /* this is no failure, its called by elements regardless if there is a
189 * controller assigned or not
190 */
191 return (TRUE);
192 }
194 /**
195 * gst_object_set_control_source:
196 * @object: the controller object
197 * @property_name: name of the property for which the #GstControlSource should be set
198 * @csource: the #GstControlSource that should be used for the property
199 *
200 * Sets the #GstControlSource for @property_name. If there already was a #GstControlSource
201 * for this property it will be unreferenced.
202 *
203 * Returns: %FALSE if the given property isn't handled by the controller or the new #GstControlSource
204 * couldn't be bound to the property, %TRUE if everything worked as expected.
205 *
206 * Since: 0.10.14
207 */
208 gboolean
209 gst_object_set_control_source (GObject * object, const gchar * property_name,
210 GstControlSource * csource)
211 {
212 GstController *ctrl = NULL;
214 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
215 g_return_val_if_fail (GST_IS_CONTROL_SOURCE (csource), FALSE);
217 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
218 return gst_controller_set_control_source (ctrl, property_name, csource);
219 }
220 return FALSE;
221 }
223 /**
224 * gst_object_get_control_source:
225 * @object: the object
226 * @property_name: name of the property for which the #GstControlSource should be get
227 *
228 * Gets the corresponding #GstControlSource for the property. This should be unreferenced
229 * again after use.
230 *
231 * Returns: the #GstControlSource for @property_name or NULL if the property is not
232 * controlled by this controller or no #GstControlSource was assigned yet.
233 *
234 * Since: 0.10.14
235 */
236 GstControlSource *
237 gst_object_get_control_source (GObject * object, const gchar * property_name)
238 {
239 GstController *ctrl = NULL;
241 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
243 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
244 return gst_controller_get_control_source (ctrl, property_name);
245 }
246 return NULL;
247 }
249 /**
250 * gst_object_get_value_arrays:
251 * @object: the object that has controlled properties
252 * @timestamp: the time that should be processed
253 * @value_arrays: list to return the control-values in
254 *
255 * Function to be able to get an array of values for one or more given element
256 * properties.
257 *
258 * If the GstValueArray->values array in list nodes is NULL, it will be created
259 * by the function.
260 * The type of the values in the array are the same as the property's type.
261 *
262 * The g_object_* functions are just convenience functions for GObject
263 *
264 * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
265 * Since: 0.9
266 */
267 gboolean
268 gst_object_get_value_arrays (GObject * object, GstClockTime timestamp,
269 GSList * value_arrays)
270 {
271 GstController *ctrl;
273 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
274 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
276 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
277 return gst_controller_get_value_arrays (ctrl, timestamp, value_arrays);
278 }
279 return (FALSE);
280 }
282 /**
283 * gst_object_get_value_array:
284 * @object: the object that has controlled properties
285 * @timestamp: the time that should be processed
286 * @value_array: array to put control-values in
287 *
288 * Function to be able to get an array of values for one element properties
289 *
290 * If the GstValueArray->values array is NULL, it will be created by the function.
291 * The type of the values in the array are the same as the property's type.
292 *
293 * The g_object_* functions are just convenience functions for GObject
294 *
295 * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
296 * Since: 0.9
297 */
298 gboolean
299 gst_object_get_value_array (GObject * object, GstClockTime timestamp,
300 GstValueArray * value_array)
301 {
302 GstController *ctrl;
304 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
305 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
307 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
308 return gst_controller_get_value_array (ctrl, timestamp, value_array);
309 }
310 return (FALSE);
311 }
313 /**
314 * gst_object_get_control_rate:
315 * @object: the object that has controlled properties
316 *
317 * Obtain the control-rate for this @object. Audio processing #GstElement
318 * objects will use this rate to sub-divide their processing loop and call
319 * gst_object_sync_values() inbetween. The length of the processing segment
320 * should be up to @control-rate nanoseconds.
321 *
322 * If the @object is not under property control, this will return
323 * %GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.
324 *
325 * The control-rate is not expected to change if the element is in
326 * %GST_STATE_PAUSED or %GST_STATE_PLAYING.
327 *
328 * Returns: the control rate in nanoseconds
329 * Since: 0.10.10
330 */
331 GstClockTime
332 gst_object_get_control_rate (GObject * object)
333 {
334 GstController *ctrl;
335 GstClockTime control_rate = GST_CLOCK_TIME_NONE;
337 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
339 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
340 g_object_get (ctrl, "control-rate", &control_rate, NULL);
341 }
342 return (control_rate);
343 }
345 /**
346 * gst_object_set_control_rate:
347 * @object: the object that has controlled properties
348 * @control_rate: the new control-rate in nanoseconds.
349 *
350 * Change the control-rate for this @object. Audio processing #GstElement
351 * objects will use this rate to sub-divide their processing loop and call
352 * gst_object_sync_values() inbetween. The length of the processing segment
353 * should be up to @control-rate nanoseconds.
354 *
355 * The control-rate should not change if the element is in %GST_STATE_PAUSED or
356 * %GST_STATE_PLAYING.
357 *
358 * Since: 0.10.10
359 */
360 void
361 gst_object_set_control_rate (GObject * object, GstClockTime control_rate)
362 {
363 GstController *ctrl;
365 g_return_if_fail (G_IS_OBJECT (object));
367 if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
368 g_object_set (ctrl, "control-rate", control_rate, NULL);
369 }
370 }