Branch data Line data Source code
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 : : */
22 : :
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 functionallity directly from
29 : : * the #GObject class.
30 : : */
31 : :
32 : : #ifdef HAVE_CONFIG_H
33 : : # include "config.h"
34 : : #endif
35 : :
36 : : #include <stdarg.h>
37 : :
38 : : #include "gstcontrollerprivate.h"
39 : : #include "gstcontroller.h"
40 : :
41 : : #define GST_CAT_DEFAULT controller_debug
42 : : GST_DEBUG_CATEGORY_EXTERN (GST_CAT_DEFAULT);
43 : :
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 : 0 : gst_object_control_properties (GObject * object, ...)
61 : : {
62 : : GstController *ctrl;
63 : : va_list var_args;
64 : :
65 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), NULL);
[ # # ][ # # ]
66 : :
67 : 0 : va_start (var_args, object);
68 : 0 : ctrl = gst_controller_new_valist (object, var_args);
69 : 0 : va_end (var_args);
70 : 0 : return (ctrl);
71 : : }
72 : :
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 : 0 : gst_object_uncontrol_properties (GObject * object, ...)
88 : : {
89 : 0 : gboolean res = FALSE;
90 : : GstController *ctrl;
91 : :
92 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
93 : :
94 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
95 : : va_list var_args;
96 : :
97 : 0 : va_start (var_args, object);
98 : 0 : res = gst_controller_remove_properties_valist (ctrl, var_args);
99 : 0 : va_end (var_args);
100 : : }
101 : 0 : return (res);
102 : : }
103 : :
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 : 2 : gst_object_get_controller (GObject * object)
116 : : {
117 [ - + ][ + - ]: 2 : g_return_val_if_fail (G_IS_OBJECT (object), NULL);
[ - + ][ - + ]
118 : :
119 : 2 : return (g_object_get_qdata (object, priv_gst_controller_key));
120 : : }
121 : :
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 : 0 : gst_object_set_controller (GObject * object, GstController * controller)
135 : : {
136 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
137 [ # # ]: 0 : g_return_val_if_fail (controller, FALSE);
138 : :
139 [ # # ]: 0 : if (!g_object_get_qdata (object, priv_gst_controller_key)) {
140 : 0 : g_object_set_qdata (object, priv_gst_controller_key, controller);
141 : 0 : return (TRUE);
142 : : }
143 : 0 : return (FALSE);
144 : : }
145 : :
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 : 0 : gst_object_suggest_next_sync (GObject * object)
157 : : {
158 : 0 : GstController *ctrl = NULL;
159 : :
160 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), GST_CLOCK_TIME_NONE);
[ # # ][ # # ]
161 : :
162 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
163 : 0 : return gst_controller_suggest_next_sync (ctrl);
164 : : }
165 : 0 : return (GST_CLOCK_TIME_NONE);
166 : : }
167 : :
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 : 1 : gst_object_sync_values (GObject * object, GstClockTime timestamp)
180 : : {
181 : 1 : GstController *ctrl = NULL;
182 : :
183 [ - + ][ + - ]: 1 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ - + ][ - + ]
184 : :
185 [ - + ]: 1 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
186 : 0 : 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 : 1 : return (TRUE);
192 : : }
193 : :
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 : 0 : gst_object_set_control_source (GObject * object, const gchar * property_name,
210 : : GstControlSource * csource)
211 : : {
212 : 0 : GstController *ctrl = NULL;
213 : :
214 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
215 [ # # ][ # # ]: 0 : g_return_val_if_fail (GST_IS_CONTROL_SOURCE (csource), FALSE);
[ # # ][ # # ]
216 : :
217 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
218 : 0 : return gst_controller_set_control_source (ctrl, property_name, csource);
219 : : }
220 : 0 : return FALSE;
221 : : }
222 : :
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 : 0 : gst_object_get_control_source (GObject * object, const gchar * property_name)
238 : : {
239 : 0 : GstController *ctrl = NULL;
240 : :
241 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), NULL);
[ # # ][ # # ]
242 : :
243 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
244 : 0 : return gst_controller_get_control_source (ctrl, property_name);
245 : : }
246 : 0 : return NULL;
247 : : }
248 : :
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 : 0 : gst_object_get_value_arrays (GObject * object, GstClockTime timestamp,
269 : : GSList * value_arrays)
270 : : {
271 : : GstController *ctrl;
272 : :
273 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
274 [ # # ]: 0 : g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
275 : :
276 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
277 : 0 : return gst_controller_get_value_arrays (ctrl, timestamp, value_arrays);
278 : : }
279 : 0 : return (FALSE);
280 : : }
281 : :
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 : 0 : gst_object_get_value_array (GObject * object, GstClockTime timestamp,
300 : : GstValueArray * value_array)
301 : : {
302 : : GstController *ctrl;
303 : :
304 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
305 [ # # ]: 0 : g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
306 : :
307 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
308 : 0 : return gst_controller_get_value_array (ctrl, timestamp, value_array);
309 : : }
310 : 0 : return (FALSE);
311 : : }
312 : :
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 : 0 : gst_object_get_control_rate (GObject * object)
333 : : {
334 : : GstController *ctrl;
335 : 0 : GstClockTime control_rate = GST_CLOCK_TIME_NONE;
336 : :
337 [ # # ][ # # ]: 0 : g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
[ # # ][ # # ]
338 : :
339 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
340 : 0 : g_object_get (ctrl, "control-rate", &control_rate, NULL);
341 : : }
342 : 0 : return (control_rate);
343 : : }
344 : :
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 : 0 : gst_object_set_control_rate (GObject * object, GstClockTime control_rate)
362 : : {
363 : : GstController *ctrl;
364 : :
365 [ # # ][ # # ]: 0 : g_return_if_fail (G_IS_OBJECT (object));
[ # # ][ # # ]
366 : :
367 [ # # ]: 0 : if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
368 : 0 : g_object_set (ctrl, "control-rate", control_rate, NULL);
369 : : }
370 : : }
|
