1 /* GStreamer 2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu> 3 * 2000,2004 Wim Taymans <wim@fluendo.com> 4 * 5 * gstelement.h: Header for GstElement 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 24 #ifndef __GST_ELEMENT_H__ 25 #define __GST_ELEMENT_H__ 26 27 #include <glib.h> 28 29 G_BEGIN_DECLS 30 31 /* gstelement.h and gstelementfactory.h include each other */ 32 typedef struct _GstElement GstElement; 33 typedef struct _GstElementClass GstElementClass; 34 35 /* gstmessage.h needs State */ 36 /** 37 * GstState: 38 * @GST_STATE_VOID_PENDING: no pending state. 39 * @GST_STATE_NULL : the NULL state or initial state of an element. 40 * @GST_STATE_READY : the element is ready to go to PAUSED. 41 * @GST_STATE_PAUSED : the element is PAUSED, it is ready to accept and 42 * process data. Sink elements however only accept one 43 * buffer and then block. 44 * @GST_STATE_PLAYING : the element is PLAYING, the #GstClock is running and 45 * the data is flowing. 46 * 47 * The possible states an element can be in. States can be changed using 48 * gst_element_set_state() and checked using gst_element_get_state(). 49 */ 50 typedef enum { 51 GST_STATE_VOID_PENDING = 0, 52 GST_STATE_NULL = 1, 53 GST_STATE_READY = 2, 54 GST_STATE_PAUSED = 3, 55 GST_STATE_PLAYING = 4 56 } GstState; 57 58 #define GST_TYPE_ELEMENT (gst_element_get_type ()) 59 #define GST_IS_ELEMENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ELEMENT)) 60 #define GST_IS_ELEMENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ELEMENT)) 61 #define GST_ELEMENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ELEMENT, GstElementClass)) 62 #define GST_ELEMENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ELEMENT, GstElement)) 63 #define GST_ELEMENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ELEMENT, GstElementClass)) 64 #define GST_ELEMENT_CAST(obj) ((GstElement*)(obj)) 65 66 /** 67 * GstStateChangeReturn: 68 * @GST_STATE_CHANGE_FAILURE : the state change failed 69 * @GST_STATE_CHANGE_SUCCESS : the state change succeeded 70 * @GST_STATE_CHANGE_ASYNC : the state change will happen asynchronously 71 * @GST_STATE_CHANGE_NO_PREROLL: the state change succeeded but the element 72 * cannot produce data in %GST_STATE_PAUSED. 73 * This typically happens with live sources. 74 * 75 * The possible return values from a state change function such as 76 * gst_element_set_state(). Only @GST_STATE_CHANGE_FAILURE is a real failure. 77 */ 78 typedef enum { 79 GST_STATE_CHANGE_FAILURE = 0, 80 GST_STATE_CHANGE_SUCCESS = 1, 81 GST_STATE_CHANGE_ASYNC = 2, 82 GST_STATE_CHANGE_NO_PREROLL = 3 83 } GstStateChangeReturn; 84 85 #include <gst/gstconfig.h> 86 #include <gst/gstobject.h> 87 #include <gst/gstpad.h> 88 #include <gst/gstbus.h> 89 #include <gst/gstclock.h> 90 #include <gst/gstelementfactory.h> 91 #include <gst/gstplugin.h> 92 #include <gst/gstpluginfeature.h> 93 #include <gst/gstiterator.h> 94 #include <gst/gstmessage.h> 95 #include <gst/gstquery.h> 96 #include <gst/gsttaglist.h> 97 #include <gst/gstcontext.h> 98 99 /* NOTE: this probably should be done with an #ifdef to decide 100 * whether to safe-cast or to just do the non-checking cast. 101 */ 102 103 /** 104 * GST_STATE: 105 * @elem: a #GstElement to return state for. 106 * 107 * This macro returns the current #GstState of the element. 108 */ 109 #define GST_STATE(elem) (GST_ELEMENT_CAST(elem)->current_state) 110 111 /** 112 * GST_STATE_NEXT: 113 * @elem: a #GstElement to return the next state for. 114 * 115 * This macro returns the next #GstState of the element. 116 */ 117 #define GST_STATE_NEXT(elem) (GST_ELEMENT_CAST(elem)->next_state) 118 119 /** 120 * GST_STATE_PENDING: 121 * @elem: a #GstElement to return the pending state for. 122 * 123 * This macro returns the currently pending #GstState of the element. 124 */ 125 #define GST_STATE_PENDING(elem) (GST_ELEMENT_CAST(elem)->pending_state) 126 127 /** 128 * GST_STATE_TARGET: 129 * @elem: a #GstElement to return the target state for. 130 * 131 * This macro returns the target #GstState of the element. 132 */ 133 #define GST_STATE_TARGET(elem) (GST_ELEMENT_CAST(elem)->target_state) 134 135 /** 136 * GST_STATE_RETURN: 137 * @elem: a #GstElement to return the last state result for. 138 * 139 * This macro returns the last #GstStateChangeReturn value. 140 */ 141 #define GST_STATE_RETURN(elem) (GST_ELEMENT_CAST(elem)->last_return) 142 143 #define __GST_SIGN(val) ((val) < 0 ? -1 : ((val) > 0 ? 1 : 0)) 144 /** 145 * GST_STATE_GET_NEXT: 146 * @cur: A starting #GstState 147 * @pending: A target #GstState 148 * 149 * Given a current state @cur and a target state @pending, calculate the next (intermediate) 150 * #GstState. 151 */ 152 #define GST_STATE_GET_NEXT(cur,pending) ((GstState)((cur) + __GST_SIGN ((gint)(pending) - (gint)(cur)))) 153 /** 154 * GST_STATE_TRANSITION: 155 * @cur: A current state 156 * @next: A next state 157 * 158 * Given a current state @cur and a next state @next, calculate the associated 159 * #GstStateChange transition. 160 */ 161 #define GST_STATE_TRANSITION(cur,next) ((GstStateChange)(((cur)<<3)|(next))) 162 /** 163 * GST_STATE_TRANSITION_CURRENT: 164 * @trans: A #GstStateChange 165 * 166 * Given a state transition @trans, extract the current #GstState. 167 */ 168 #define GST_STATE_TRANSITION_CURRENT(trans) ((GstState)((trans)>>3)) 169 /** 170 * GST_STATE_TRANSITION_NEXT: 171 * @trans: A #GstStateChange 172 * 173 * Given a state transition @trans, extract the next #GstState. 174 */ 175 #define GST_STATE_TRANSITION_NEXT(trans) ((GstState)((trans)&0x7)) 176 177 /** 178 * GstStateChange: 179 * @GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY. 180 * * The element must check if the resources it needs are available. Device 181 * sinks and -sources typically try to probe the device to constrain their 182 * caps. 183 * * The element opens the device (in case feature need to be probed). 184 * @GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED. 185 * * The element pads are activated in order to receive data in PAUSED. 186 * Streaming threads are started. 187 * * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete 188 * the state change when they have enough information. It is a requirement 189 * for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change 190 * when they receive the first buffer or %GST_EVENT_EOS (preroll). 191 * Sinks also block the dataflow when in PAUSED. 192 * * A pipeline resets the running_time to 0. 193 * * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data. 194 * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING. 195 * * Most elements ignore this state change. 196 * * The pipeline selects a #GstClock and distributes this to all the children 197 * before setting them to PLAYING. This means that it is only allowed to 198 * synchronize on the #GstClock in the PLAYING state. 199 * * The pipeline uses the #GstClock and the running_time to calculate the 200 * base_time. The base_time is distributed to all children when performing 201 * the state change. 202 * * Sink elements stop blocking on the preroll buffer or event and start 203 * rendering the data. 204 * * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed 205 * to post %GST_MESSAGE_EOS when not in the PLAYING state. 206 * * While streaming in PAUSED or PLAYING elements can create and remove 207 * sometimes pads. 208 * * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. 209 * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. 210 * * Most elements ignore this state change. 211 * * The pipeline calculates the running_time based on the last selected 212 * #GstClock and the base_time. It stores this information to continue 213 * playback when going back to the PLAYING state. 214 * * Sinks unblock any #GstClock wait calls. 215 * * When a sink does not have a pending buffer to play, it returns 216 * #GST_STATE_CHANGE_ASYNC from this state change and completes the state 217 * change when it receives a new buffer or an %GST_EVENT_EOS. 218 * * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted 219 * when going back to the PLAYING state. The EOS messages are queued in 220 * #GstBin containers. 221 * * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. 222 * @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. 223 * * Sinks unblock any waits in the preroll. 224 * * Elements unblock any waits on devices 225 * * Chain or get_range functions return %GST_FLOW_FLUSHING. 226 * * The element pads are deactivated so that streaming becomes impossible and 227 * all streaming threads are stopped. 228 * * The sink forgets all negotiated formats 229 * * Elements remove all sometimes pads 230 * @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. 231 * * Elements close devices 232 * * Elements reset any internal state. 233 * @GST_STATE_CHANGE_NULL_TO_NULL : state change from NULL to NULL. (Since: 1.14) 234 * @GST_STATE_CHANGE_READY_TO_READY : state change from READY to READY, 235 * This might happen when going to PAUSED asynchronously failed, in that case 236 * elements should make sure they are in a proper, coherent READY state. (Since: 1.14) 237 * @GST_STATE_CHANGE_PAUSED_TO_PAUSED : state change from PAUSED to PAUSED. 238 * This might happen when elements were in PLAYING state and 'lost state', 239 * they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since: 1.14) 240 * @GST_STATE_CHANGE_PLAYING_TO_PLAYING : state change from PLAYING to PLAYING. (Since: 1.14) 241 * 242 * These are the different state changes an element goes through. 243 * %GST_STATE_NULL ⇒ %GST_STATE_PLAYING is called an upwards state change 244 * and %GST_STATE_PLAYING ⇒ %GST_STATE_NULL a downwards state change. 245 */ 246 typedef enum /*< flags=0 >*/ 247 { 248 GST_STATE_CHANGE_NULL_TO_READY = (GST_STATE_NULL<<3) | GST_STATE_READY, 249 GST_STATE_CHANGE_READY_TO_PAUSED = (GST_STATE_READY<<3) | GST_STATE_PAUSED, 250 GST_STATE_CHANGE_PAUSED_TO_PLAYING = (GST_STATE_PAUSED<<3) | GST_STATE_PLAYING, 251 GST_STATE_CHANGE_PLAYING_TO_PAUSED = (GST_STATE_PLAYING<<3) | GST_STATE_PAUSED, 252 GST_STATE_CHANGE_PAUSED_TO_READY = (GST_STATE_PAUSED<<3) | GST_STATE_READY, 253 GST_STATE_CHANGE_READY_TO_NULL = (GST_STATE_READY<<3) | GST_STATE_NULL, 254 GST_STATE_CHANGE_NULL_TO_NULL = (GST_STATE_NULL<<3) | GST_STATE_NULL, 255 GST_STATE_CHANGE_READY_TO_READY = (GST_STATE_READY<<3) | GST_STATE_READY, 256 GST_STATE_CHANGE_PAUSED_TO_PAUSED = (GST_STATE_PAUSED<<3) | GST_STATE_PAUSED, 257 GST_STATE_CHANGE_PLAYING_TO_PLAYING = (GST_STATE_PLAYING<<3) | GST_STATE_PLAYING 258 } GstStateChange; 259 260 /** 261 * GstElementFlags: 262 * @GST_ELEMENT_FLAG_LOCKED_STATE: ignore state changes from parent 263 * @GST_ELEMENT_FLAG_SINK: the element is a sink 264 * @GST_ELEMENT_FLAG_SOURCE: the element is a source. 265 * @GST_ELEMENT_FLAG_PROVIDE_CLOCK: the element can provide a clock 266 * @GST_ELEMENT_FLAG_REQUIRE_CLOCK: the element requires a clock 267 * @GST_ELEMENT_FLAG_INDEXABLE: the element can use an index 268 * @GST_ELEMENT_FLAG_LAST: offset to define more flags 269 * 270 * The standard flags that an element may have. 271 */ 272 typedef enum 273 { 274 GST_ELEMENT_FLAG_LOCKED_STATE = (GST_OBJECT_FLAG_LAST << 0), 275 GST_ELEMENT_FLAG_SINK = (GST_OBJECT_FLAG_LAST << 1), 276 GST_ELEMENT_FLAG_SOURCE = (GST_OBJECT_FLAG_LAST << 2), 277 GST_ELEMENT_FLAG_PROVIDE_CLOCK = (GST_OBJECT_FLAG_LAST << 3), 278 GST_ELEMENT_FLAG_REQUIRE_CLOCK = (GST_OBJECT_FLAG_LAST << 4), 279 GST_ELEMENT_FLAG_INDEXABLE = (GST_OBJECT_FLAG_LAST << 5), 280 /* padding */ 281 GST_ELEMENT_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 10) 282 } GstElementFlags; 283 284 /** 285 * GST_ELEMENT_IS_LOCKED_STATE: 286 * @elem: A #GstElement to query 287 * 288 * Check if the element is in the locked state and therefore will ignore state 289 * changes from its parent object. 290 */ 291 #define GST_ELEMENT_IS_LOCKED_STATE(elem) (GST_OBJECT_FLAG_IS_SET(elem,GST_ELEMENT_FLAG_LOCKED_STATE)) 292 293 /** 294 * GST_ELEMENT_NAME: 295 * @elem: A #GstElement to query 296 * 297 * Gets the name of this element. This is not thread-safe by default 298 * (i.e. you will have to make sure the object lock is taken yourself). 299 * If in doubt use gst_element_get_name() instead. 300 */ 301 #define GST_ELEMENT_NAME(elem) (GST_OBJECT_NAME(elem)) 302 303 /** 304 * GST_ELEMENT_PARENT: 305 * @elem: A #GstElement to query 306 * 307 * Get the parent object of this element. This is not thread-safe by default 308 * (i.e. you will have to make sure the object lock is taken yourself). 309 * If in doubt use gst_object_get_parent() instead. 310 */ 311 #define GST_ELEMENT_PARENT(elem) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(elem))) 312 313 /** 314 * GST_ELEMENT_BUS: 315 * @elem: A #GstElement to query 316 * 317 * Get the message bus of this element. This is not thread-safe by default 318 * (i.e. you will have to make sure the object lock is taken yourself). 319 * If in doubt use gst_element_get_bus() instead. 320 */ 321 #define GST_ELEMENT_BUS(elem) (GST_ELEMENT_CAST(elem)->bus) 322 323 /** 324 * GST_ELEMENT_CLOCK: 325 * @elem: A #GstElement to query 326 * 327 * Get the clock of this element.This is not thread-safe by default 328 * (i.e. you will have to make sure it is safe yourself). 329 * If in doubt use gst_element_get_clock() instead. 330 */ 331 #define GST_ELEMENT_CLOCK(elem) (GST_ELEMENT_CAST(elem)->clock) 332 333 /** 334 * GST_ELEMENT_PADS: 335 * @elem: A #GstElement to query 336 * 337 * Get the pads of this elements. 338 */ 339 #define GST_ELEMENT_PADS(elem) (GST_ELEMENT_CAST(elem)->pads) 340 341 /** 342 * GST_ELEMENT_START_TIME: 343 * @elem: a #GstElement to return the start time for. 344 * 345 * This macro returns the start_time of the @elem. The start_time is the 346 * running_time of the pipeline when the element went to PAUSED. 347 */ 348 #define GST_ELEMENT_START_TIME(elem) (GST_ELEMENT_CAST(elem)->start_time) 349 350 GST_API 351 GstStructure *gst_make_element_message_details (const char *name, ...); 352 353 #define GST_ELEMENT_MESSAGE_MAKE_DETAILS(args) gst_make_element_message_details args 354 355 /** 356 * GST_ELEMENT_FLOW_ERROR: 357 * @el: the element that generates the error 358 * @flow_return: the GstFlowReturn leading to that ERROR message 359 * 360 * Utility function that elements can use in case they encountered a fatal 361 * data processing error due to wrong flow processing. 362 * 363 * Since: 1.10 364 */ 365 #define GST_ELEMENT_FLOW_ERROR(el,flow_return) \ 366 G_STMT_START { \ 367 GST_ELEMENT_ERROR_WITH_DETAILS (el, STREAM, FAILED, \ 368 ("Internal data stream error."), \ 369 ("streaming stopped, reason %s (%d)", gst_flow_get_name (flow_return), flow_return), \ 370 ("flow-return", G_TYPE_INT, flow_return, NULL));\ 371 } G_STMT_END 372 373 /** 374 * GST_ELEMENT_ERROR_WITH_DETAILS: 375 * @el: the element that generates the error 376 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 377 * @code: error code defined for that domain (see #gstreamer-GstGError) 378 * @text: the message to display (format string and args enclosed in 379 parentheses) 380 * @debug: debugging information for the message (format string and args 381 enclosed in parentheses) 382 * @args: optional name, type, value triplets, which will be stored 383 * in the associated GstStructure. NULL terminator required. 384 * Must be enclosed within parentheses. 385 * 386 * Utility function that elements can use in case they encountered a fatal 387 * data processing error. The pipeline will post an error message and the 388 * application will be requested to stop further media processing. 389 * 390 * Since: 1.10 391 */ 392 #define GST_ELEMENT_ERROR_WITH_DETAILS(el,domain,code,text,debug,args) \ 393 G_STMT_START { \ 394 gchar *__txt = _gst_element_error_printf text; \ 395 gchar *__dbg = _gst_element_error_printf debug; \ 396 if (__txt) \ 397 GST_WARNING_OBJECT (el, "error: %s", __txt); \ 398 if (__dbg) \ 399 GST_WARNING_OBJECT (el, "error: %s", __dbg); \ 400 gst_element_message_full_with_details (GST_ELEMENT(el), \ 401 GST_MESSAGE_ERROR, GST_ ## domain ## _ERROR, \ 402 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 403 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 404 } G_STMT_END 405 406 /** 407 * GST_ELEMENT_ERROR: 408 * @el: the element that generates the error 409 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 410 * @code: error code defined for that domain (see #gstreamer-GstGError) 411 * @text: the message to display (format string and args enclosed in 412 parentheses) 413 * @debug: debugging information for the message (format string and args 414 enclosed in parentheses) 415 * 416 * Utility function that elements can use in case they encountered a fatal 417 * data processing error. The pipeline will post an error message and the 418 * application will be requested to stop further media processing. 419 */ 420 #define GST_ELEMENT_ERROR(el,domain,code,text,debug) \ 421 G_STMT_START { \ 422 gchar *__txt = _gst_element_error_printf text; \ 423 gchar *__dbg = _gst_element_error_printf debug; \ 424 if (__txt) \ 425 GST_WARNING_OBJECT (el, "error: %s", __txt); \ 426 if (__dbg) \ 427 GST_WARNING_OBJECT (el, "error: %s", __dbg); \ 428 gst_element_message_full (GST_ELEMENT(el), \ 429 GST_MESSAGE_ERROR, GST_ ## domain ## _ERROR, \ 430 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 431 GST_FUNCTION, __LINE__); \ 432 } G_STMT_END 433 434 /** 435 * GST_ELEMENT_WARNING_WITH_DETAILS: 436 * @el: the element that generates the warning 437 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 438 * @code: error code defined for that domain (see #gstreamer-GstGError) 439 * @text: the message to display (format string and args enclosed in 440 parentheses) 441 * @debug: debugging information for the message (format string and args 442 enclosed in parentheses) 443 * @args: optional name, type, value triplets, which will be stored 444 * in the associated GstStructure. NULL terminator required. 445 * Must be enclosed within parentheses. 446 * 447 * Utility function that elements can use in case they encountered a non-fatal 448 * data processing problem. The pipeline will post a warning message and the 449 * application will be informed. 450 * 451 * Since: 1.10 452 */ 453 #define GST_ELEMENT_WARNING_WITH_DETAILS(el, domain, code, text, debug, args)\ 454 G_STMT_START { \ 455 gchar *__txt = _gst_element_error_printf text; \ 456 gchar *__dbg = _gst_element_error_printf debug; \ 457 if (__txt) \ 458 GST_WARNING_OBJECT (el, "warning: %s", __txt); \ 459 if (__dbg) \ 460 GST_WARNING_OBJECT (el, "warning: %s", __dbg); \ 461 gst_element_message_full_with_details (GST_ELEMENT(el), \ 462 GST_MESSAGE_WARNING, GST_ ## domain ## _ERROR, \ 463 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 464 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 465 } G_STMT_END 466 467 /** 468 * GST_ELEMENT_WARNING: 469 * @el: the element that generates the warning 470 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 471 * @code: error code defined for that domain (see #gstreamer-GstGError) 472 * @text: the message to display (format string and args enclosed in 473 parentheses) 474 * @debug: debugging information for the message (format string and args 475 enclosed in parentheses) 476 * 477 * Utility function that elements can use in case they encountered a non-fatal 478 * data processing problem. The pipeline will post a warning message and the 479 * application will be informed. 480 */ 481 #define GST_ELEMENT_WARNING(el, domain, code, text, debug) \ 482 G_STMT_START { \ 483 gchar *__txt = _gst_element_error_printf text; \ 484 gchar *__dbg = _gst_element_error_printf debug; \ 485 if (__txt) \ 486 GST_WARNING_OBJECT (el, "warning: %s", __txt); \ 487 if (__dbg) \ 488 GST_WARNING_OBJECT (el, "warning: %s", __dbg); \ 489 gst_element_message_full (GST_ELEMENT(el), \ 490 GST_MESSAGE_WARNING, GST_ ## domain ## _ERROR, \ 491 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 492 GST_FUNCTION, __LINE__); \ 493 } G_STMT_END 494 495 /** 496 * GST_ELEMENT_INFO_WITH_DETAILS: 497 * @el: the element that generates the information 498 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 499 * @code: error code defined for that domain (see #gstreamer-GstGError) 500 * @text: the message to display (format string and args enclosed in 501 parentheses) 502 * @debug: debugging information for the message (format string and args 503 enclosed in parentheses) 504 * @args: optional name, type, value triplets, which will be stored 505 * in the associated GstStructure. NULL terminator required. 506 * Must be enclosed within parentheses. 507 * 508 * Utility function that elements can use in case they want to inform 509 * the application of something noteworthy that is not an error. 510 * The pipeline will post a info message and the 511 * application will be informed. 512 * Optional name, type, value triplets may be supplied, and will be stored 513 * in the associated GstStructure. NULL terminator required. 514 * 515 * Since: 1.10 516 */ 517 #define GST_ELEMENT_INFO_WITH_DETAILS(el, domain, code, text, debug, args) \ 518 G_STMT_START { \ 519 gchar *__txt = _gst_element_error_printf text; \ 520 gchar *__dbg = _gst_element_error_printf debug; \ 521 if (__txt) \ 522 GST_INFO_OBJECT (el, "info: %s", __txt); \ 523 if (__dbg) \ 524 GST_INFO_OBJECT (el, "info: %s", __dbg); \ 525 gst_element_message_full_with_details (GST_ELEMENT(el), \ 526 GST_MESSAGE_INFO, GST_ ## domain ## _ERROR, \ 527 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 528 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 529 } G_STMT_END 530 531 /** 532 * GST_ELEMENT_INFO: 533 * @el: the element that generates the information 534 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) 535 * @code: error code defined for that domain (see #gstreamer-GstGError) 536 * @text: the message to display (format string and args enclosed in 537 parentheses) 538 * @debug: debugging information for the message (format string and args 539 enclosed in parentheses) 540 * 541 * Utility function that elements can use in case they want to inform 542 * the application of something noteworthy that is not an error. 543 * The pipeline will post a info message and the 544 * application will be informed. 545 */ 546 #define GST_ELEMENT_INFO(el, domain, code, text, debug) \ 547 G_STMT_START { \ 548 gchar *__txt = _gst_element_error_printf text; \ 549 gchar *__dbg = _gst_element_error_printf debug; \ 550 if (__txt) \ 551 GST_INFO_OBJECT (el, "info: %s", __txt); \ 552 if (__dbg) \ 553 GST_INFO_OBJECT (el, "info: %s", __dbg); \ 554 gst_element_message_full (GST_ELEMENT(el), \ 555 GST_MESSAGE_INFO, GST_ ## domain ## _ERROR, \ 556 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 557 GST_FUNCTION, __LINE__); \ 558 } G_STMT_END 559 560 /* the state change mutexes and conds */ 561 /** 562 * GST_STATE_GET_LOCK: 563 * @elem: a #GstElement 564 * 565 * Get a reference to the state lock of @elem. 566 * This lock is used by the core. It is taken while getting or setting 567 * the state, during state changes, and while finalizing. 568 */ 569 #define GST_STATE_GET_LOCK(elem) (&(GST_ELEMENT_CAST(elem)->state_lock)) 570 /** 571 * GST_STATE_GET_COND: 572 * @elem: a #GstElement 573 * 574 * Get the conditional used to signal the completion of a state change. 575 */ 576 #define GST_STATE_GET_COND(elem) (&GST_ELEMENT_CAST(elem)->state_cond) 577 578 #define GST_STATE_LOCK(elem) g_rec_mutex_lock(GST_STATE_GET_LOCK(elem)) 579 #define GST_STATE_TRYLOCK(elem) g_rec_mutex_trylock(GST_STATE_GET_LOCK(elem)) 580 #define GST_STATE_UNLOCK(elem) g_rec_mutex_unlock(GST_STATE_GET_LOCK(elem)) 581 #define GST_STATE_WAIT(elem) g_cond_wait (GST_STATE_GET_COND (elem), \ 582 GST_OBJECT_GET_LOCK (elem)) 583 #define GST_STATE_WAIT_UNTIL(elem, end_time) g_cond_wait_until (GST_STATE_GET_COND (elem), \ 584 GST_OBJECT_GET_LOCK (elem), end_time) 585 #define GST_STATE_SIGNAL(elem) g_cond_signal (GST_STATE_GET_COND (elem)); 586 #define GST_STATE_BROADCAST(elem) g_cond_broadcast (GST_STATE_GET_COND (elem)); 587 588 /** 589 * GstElement: 590 * @state_lock: Used to serialize execution of gst_element_set_state() 591 * @state_cond: Used to signal completion of a state change 592 * @state_cookie: Used to detect concurrent execution of 593 * gst_element_set_state() and gst_element_get_state() 594 * @target_state: the target state of an element as set by the application 595 * @current_state: the current state of an element 596 * @next_state: the next state of an element, can be #GST_STATE_VOID_PENDING if 597 * the element is in the correct state. 598 * @pending_state: the final state the element should go to, can be 599 * #GST_STATE_VOID_PENDING if the element is in the correct state 600 * @last_return: the last return value of an element state change 601 * @bus: the bus of the element. This bus is provided to the element by the 602 * parent element or the application. A #GstPipeline has a bus of its own. 603 * @clock: the clock of the element. This clock is usually provided to the 604 * element by the toplevel #GstPipeline. 605 * @base_time: the time of the clock right before the element is set to 606 * PLAYING. Subtracting @base_time from the current clock time in the PLAYING 607 * state will yield the running_time against the clock. 608 * @start_time: the running_time of the last PAUSED state 609 * @numpads: number of pads of the element, includes both source and sink pads. 610 * @pads: (element-type Gst.Pad): list of pads 611 * @numsrcpads: number of source pads of the element. 612 * @srcpads: (element-type Gst.Pad): list of source pads 613 * @numsinkpads: number of sink pads of the element. 614 * @sinkpads: (element-type Gst.Pad): list of sink pads 615 * @pads_cookie: updated whenever the a pad is added or removed 616 * @contexts: (element-type Gst.Context): list of contexts 617 * 618 * GStreamer element abstract base class. 619 */ 620 struct _GstElement 621 { 622 GstObject object; 623 624 /*< public >*/ /* with LOCK */ 625 GRecMutex state_lock; 626 627 /* element state */ 628 GCond state_cond; 629 guint32 state_cookie; 630 GstState target_state; 631 GstState current_state; 632 GstState next_state; 633 GstState pending_state; 634 GstStateChangeReturn last_return; 635 636 GstBus *bus; 637 638 /* allocated clock */ 639 GstClock *clock; 640 GstClockTimeDiff base_time; /* NULL/READY: 0 - PAUSED: current time - PLAYING: difference to clock */ 641 GstClockTime start_time; 642 643 /* element pads, these lists can only be iterated while holding 644 * the LOCK or checking the cookie after each LOCK. */ 645 guint16 numpads; 646 GList *pads; 647 guint16 numsrcpads; 648 GList *srcpads; 649 guint16 numsinkpads; 650 GList *sinkpads; 651 guint32 pads_cookie; 652 653 /* with object LOCK */ 654 GList *contexts; 655 656 /*< private >*/ 657 gpointer _gst_reserved[GST_PADDING-1]; 658 }; 659 660 /** 661 * GstElementClass: 662 * @parent_class: the parent class structure 663 * @metadata: metadata for elements of this class 664 * @elementfactory: the #GstElementFactory that creates these elements 665 * @padtemplates: a #GList of #GstPadTemplate 666 * @numpadtemplates: the number of padtemplates 667 * @pad_templ_cookie: changed whenever the padtemplates change 668 * @request_new_pad: called when a new pad is requested 669 * @release_pad: called when a request pad is to be released 670 * @get_state: get the state of the element 671 * @set_state: set a new state on the element 672 * @change_state: called by @set_state to perform an incremental state change 673 * @set_bus: set a #GstBus on the element 674 * @provide_clock: gets the #GstClock provided by the element 675 * @set_clock: set the #GstClock on the element 676 * @send_event: send a #GstEvent to the element 677 * @query: perform a #GstQuery on the element 678 * @state_changed: called immediately after a new state was set. 679 * @post_message: called when a message is posted on the element. Chain up to 680 * the parent class' handler to have it posted on the bus. 681 * @set_context: set a #GstContext on the element 682 * 683 * GStreamer element class. Override the vmethods to implement the element 684 * functionality. 685 */ 686 struct _GstElementClass 687 { 688 GstObjectClass parent_class; 689 690 /*< public >*/ 691 /* the element metadata */ 692 gpointer metadata; 693 694 /* factory that the element was created from */ 695 GstElementFactory *elementfactory; 696 697 /* templates for our pads */ 698 GList *padtemplates; 699 gint numpadtemplates; 700 guint32 pad_templ_cookie; 701 702 /*< private >*/ 703 /* signal callbacks */ 704 void (*pad_added) (GstElement *element, GstPad *pad); 705 void (*pad_removed) (GstElement *element, GstPad *pad); 706 void (*no_more_pads) (GstElement *element); 707 708 /*< public >*/ 709 /* virtual methods for subclasses */ 710 711 /* request/release pads */ 712 /* FIXME 2.0 harmonize naming with gst_element_request_pad */ 713 GstPad* (*request_new_pad) (GstElement *element, GstPadTemplate *templ, 714 const gchar* name, const GstCaps *caps); 715 716 void (*release_pad) (GstElement *element, GstPad *pad); 717 718 /* state changes */ 719 GstStateChangeReturn (*get_state) (GstElement * element, GstState * state, 720 GstState * pending, GstClockTime timeout); 721 GstStateChangeReturn (*set_state) (GstElement *element, GstState state); 722 GstStateChangeReturn (*change_state) (GstElement *element, GstStateChange transition); 723 void (*state_changed) (GstElement *element, GstState oldstate, 724 GstState newstate, GstState pending); 725 726 /* bus */ 727 void (*set_bus) (GstElement * element, GstBus * bus); 728 729 /* set/get clocks */ 730 GstClock* (*provide_clock) (GstElement *element); 731 gboolean (*set_clock) (GstElement *element, GstClock *clock); 732 733 /* query functions */ 734 gboolean (*send_event) (GstElement *element, GstEvent *event); 735 736 gboolean (*query) (GstElement *element, GstQuery *query); 737 738 gboolean (*post_message) (GstElement *element, GstMessage *message); 739 740 void (*set_context) (GstElement *element, GstContext *context); 741 742 /*< private >*/ 743 gpointer _gst_reserved[GST_PADDING_LARGE-2]; 744 }; 745 746 /* element class pad templates */ 747 748 GST_API 749 void gst_element_class_add_pad_template (GstElementClass *klass, GstPadTemplate *templ); 750 751 GST_API 752 void gst_element_class_add_static_pad_template (GstElementClass *klass, GstStaticPadTemplate *static_templ); 753 754 GST_API 755 void gst_element_class_add_static_pad_template_with_gtype (GstElementClass *klass, 756 GstStaticPadTemplate *static_templ, 757 GType pad_type); 758 759 GST_API 760 GstPadTemplate* gst_element_class_get_pad_template (GstElementClass *element_class, const gchar *name); 761 762 GST_API 763 GList* gst_element_class_get_pad_template_list (GstElementClass *element_class); 764 765 /* element class meta data */ 766 767 GST_API 768 void gst_element_class_set_metadata (GstElementClass *klass, 769 const gchar *longname, 770 const gchar *classification, 771 const gchar *description, 772 const gchar *author); 773 GST_API 774 void gst_element_class_set_static_metadata (GstElementClass *klass, 775 const gchar *longname, 776 const gchar *classification, 777 const gchar *description, 778 const gchar *author); 779 GST_API 780 void gst_element_class_add_metadata (GstElementClass * klass, 781 const gchar * key, const gchar * value); 782 GST_API 783 void gst_element_class_add_static_metadata (GstElementClass * klass, 784 const gchar * key, const gchar * value); 785 GST_API 786 const gchar * gst_element_class_get_metadata (GstElementClass * klass, 787 const gchar * key); 788 789 790 /* element instance */ 791 792 GST_API 793 GType gst_element_get_type (void); 794 795 /* basic name and parentage stuff from GstObject */ 796 797 /** 798 * gst_element_get_name: 799 * @elem: a #GstElement to get the name of @elem. 800 * 801 * Returns a copy of the name of @elem. 802 * Caller should g_free() the return value after usage. 803 * For a nameless element, this returns %NULL, which you can safely g_free() 804 * as well. 805 * 806 * Returns: (transfer full) (nullable): the name of @elem. g_free() 807 * after usage. MT safe. 808 * 809 */ 810 #define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT_CAST(elem)) 811 812 /** 813 * gst_element_set_name: 814 * @elem: a #GstElement to set the name of. 815 * @name: the new name 816 * 817 * Sets the name of the element, getting rid of the old name if there was one. 818 */ 819 #define gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT_CAST(elem),name) 820 821 /** 822 * gst_element_get_parent: 823 * @elem: a #GstElement to get the parent of. 824 * 825 * Get the parent of an element. 826 * 827 * Returns: (transfer full): the parent of an element. 828 */ 829 #define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT_CAST(elem)) 830 831 /** 832 * gst_element_set_parent: 833 * @elem: a #GstElement to set the parent of. 834 * @parent: the new parent #GstObject of the element. 835 * 836 * Sets the parent of an element. 837 */ 838 #define gst_element_set_parent(elem,parent) gst_object_set_parent(GST_OBJECT_CAST(elem),parent) 839 840 /* clocking */ 841 842 GST_API 843 GstClock* gst_element_provide_clock (GstElement *element); 844 845 GST_API 846 GstClock* gst_element_get_clock (GstElement *element); 847 848 GST_API 849 gboolean gst_element_set_clock (GstElement *element, GstClock *clock); 850 851 GST_API 852 void gst_element_set_base_time (GstElement *element, GstClockTime time); 853 854 GST_API 855 GstClockTime gst_element_get_base_time (GstElement *element); 856 857 GST_API 858 void gst_element_set_start_time (GstElement *element, GstClockTime time); 859 860 GST_API 861 GstClockTime gst_element_get_start_time (GstElement *element); 862 863 /* bus */ 864 865 GST_API 866 void gst_element_set_bus (GstElement * element, GstBus * bus); 867 868 GST_API 869 GstBus * gst_element_get_bus (GstElement * element); 870 871 /* context */ 872 873 GST_API 874 void gst_element_set_context (GstElement * element, GstContext * context); 875 876 GST_API 877 GList * gst_element_get_contexts (GstElement * element); 878 879 GST_API 880 GstContext * gst_element_get_context (GstElement * element, const gchar * context_type); 881 882 GST_API 883 GstContext * gst_element_get_context_unlocked (GstElement * element, const gchar * context_type); 884 885 /* pad management */ 886 887 GST_API 888 gboolean gst_element_add_pad (GstElement *element, GstPad *pad); 889 890 GST_API 891 gboolean gst_element_remove_pad (GstElement *element, GstPad *pad); 892 893 GST_API 894 void gst_element_no_more_pads (GstElement *element); 895 896 GST_API 897 GstPad* gst_element_get_static_pad (GstElement *element, const gchar *name); 898 899 GST_API 900 GstPad* gst_element_get_request_pad (GstElement *element, const gchar *name); 901 902 GST_API 903 GstPad* gst_element_request_pad (GstElement *element, GstPadTemplate *templ, 904 const gchar * name, const GstCaps *caps); 905 GST_API 906 void gst_element_release_request_pad (GstElement *element, GstPad *pad); 907 908 GST_API 909 GstIterator * gst_element_iterate_pads (GstElement * element); 910 911 GST_API 912 GstIterator * gst_element_iterate_src_pads (GstElement * element); 913 914 GST_API 915 GstIterator * gst_element_iterate_sink_pads (GstElement * element); 916 917 /** 918 * GstElementForeachPadFunc: 919 * @element: the #GstElement 920 * @pad: a #GstPad 921 * @user_data: user data passed to the foreach function 922 * 923 * Function called for each pad when using gst_element_foreach_sink_pad(), 924 * gst_element_foreach_src_pad(), or gst_element_foreach_pad(). 925 * 926 * Returns: %FALSE to stop iterating pads, %TRUE to continue 927 * 928 * Since: 1.14 929 */ 930 typedef gboolean (*GstElementForeachPadFunc) (GstElement * element, 931 GstPad * pad, 932 gpointer user_data); 933 934 GST_API 935 gboolean gst_element_foreach_sink_pad (GstElement * element, 936 GstElementForeachPadFunc func, 937 gpointer user_data); 938 GST_API 939 gboolean gst_element_foreach_src_pad (GstElement * element, 940 GstElementForeachPadFunc func, 941 gpointer user_data); 942 GST_API 943 gboolean gst_element_foreach_pad (GstElement * element, 944 GstElementForeachPadFunc func, 945 gpointer user_data); 946 /* event/query/format stuff */ 947 948 GST_API 949 gboolean gst_element_send_event (GstElement *element, GstEvent *event); 950 951 GST_API 952 gboolean gst_element_seek (GstElement *element, gdouble rate, 953 GstFormat format, GstSeekFlags flags, 954 GstSeekType start_type, gint64 start, 955 GstSeekType stop_type, gint64 stop); 956 GST_API 957 gboolean gst_element_query (GstElement *element, GstQuery *query); 958 959 /* messages */ 960 961 GST_API 962 gboolean gst_element_post_message (GstElement * element, GstMessage * message); 963 964 /* error handling */ 965 /* gcc versions < 3.3 warn about NULL being passed as format to printf */ 966 #if (!defined(__GNUC__) || (__GNUC__ < 3) || (__GNUC__ == 3 && __GNUC_MINOR__ < 3)) 967 GST_API 968 gchar * _gst_element_error_printf (const gchar *format, ...); 969 #else 970 GST_API 971 gchar * _gst_element_error_printf (const gchar *format, ...) G_GNUC_PRINTF (1, 2); 972 #endif 973 974 GST_API 975 void gst_element_message_full (GstElement * element, GstMessageType type, 976 GQuark domain, gint code, gchar * text, 977 gchar * debug, const gchar * file, 978 const gchar * function, gint line); 979 GST_API 980 void gst_element_message_full_with_details (GstElement * element, GstMessageType type, 981 GQuark domain, gint code, gchar * text, 982 gchar * debug, const gchar * file, 983 const gchar * function, gint line, 984 GstStructure * structure); 985 986 /* state management */ 987 988 GST_API 989 gboolean gst_element_is_locked_state (GstElement *element); 990 991 GST_API 992 gboolean gst_element_set_locked_state (GstElement *element, gboolean locked_state); 993 994 GST_API 995 gboolean gst_element_sync_state_with_parent (GstElement *element); 996 997 GST_API 998 GstStateChangeReturn gst_element_get_state (GstElement * element, 999 GstState * state, 1000 GstState * pending, 1001 GstClockTime timeout); 1002 GST_API 1003 GstStateChangeReturn gst_element_set_state (GstElement *element, GstState state); 1004 1005 GST_API 1006 void gst_element_abort_state (GstElement * element); 1007 1008 GST_API 1009 GstStateChangeReturn gst_element_change_state (GstElement * element, 1010 GstStateChange transition); 1011 1012 GST_API 1013 GstStateChangeReturn gst_element_continue_state (GstElement * element, 1014 GstStateChangeReturn ret); 1015 GST_API 1016 void gst_element_lost_state (GstElement * element); 1017 1018 1019 typedef void (*GstElementCallAsyncFunc) (GstElement * element, 1020 gpointer user_data); 1021 GST_API 1022 void gst_element_call_async (GstElement * element, 1023 GstElementCallAsyncFunc func, gpointer user_data, 1024 GDestroyNotify destroy_notify); 1025 1026 /* factory management */ 1027 1028 GST_API 1029 GstElementFactory* gst_element_get_factory (GstElement *element); 1030 1031 /* utility functions */ 1032 1033 GST_API 1034 gulong gst_element_add_property_notify_watch (GstElement * element, 1035 const gchar * property_name, 1036 gboolean include_value); 1037 GST_API 1038 gulong gst_element_add_property_deep_notify_watch (GstElement * element, 1039 const gchar * property_name, 1040 gboolean include_value); 1041 GST_API 1042 void gst_element_remove_property_notify_watch (GstElement * element, 1043 gulong watch_id); 1044 1045 GST_API 1046 GstPadTemplate* gst_element_get_pad_template (GstElement *element, const gchar *name); 1047 1048 GST_API 1049 GList* gst_element_get_pad_template_list (GstElement *element); 1050 GST_API 1051 const gchar * gst_element_get_metadata (GstElement * element, const gchar * key); 1052 1053 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 1054 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstElement, gst_object_unref) 1055 #endif 1056 1057 G_END_DECLS 1058 1059 #endif /* __GST_ELEMENT_H__ */ 1060