a2d30f2557fef2214fe38a0a52a2b3bc46f9b683
[platform/upstream/gstreamer.git] / docs / gst / tmpl / gstelement.sgml
1 <!-- ##### SECTION Title ##### -->
2 GstElement
3
4 <!-- ##### SECTION Short_Description ##### -->
5 Base class for all pipeline elements
6
7 <!-- ##### SECTION Long_Description ##### -->
8 <para>
9 GstElement is the base class needed to construct an element that can be
10 used in a GST pipeline.  As such, it is not a functional entity, and
11 cannot do anything when placed in a pipeline.
12 </para>
13
14 <para>
15 All GstElements have a list containing the #GstPad structure for all their
16 inputs and outputs.  These can be added with gst_element_add_pad() or
17 gst_element_add_ghost_pad(), and retrieved by name with
18 gst_element_get_pad(), or in a list form by gst_element_get_pad_list().
19 </para>
20
21 <para>
22 gst_element_connect() is a convenience function provided to make it
23 simpler to connect pads of two elements together.
24 </para>
25
26 <!-- ##### SECTION See_Also ##### -->
27 <para>
28
29 </para>
30
31 <!-- ##### ENUM GstElementState ##### -->
32 <para>
33 This enum defines the standard states an element may be in.  You will normally
34 use gst_element_set_state() to change the state of an element.
35
36 </para>
37
38 @GST_STATE_NONE_PENDING: The element is in the desired state.
39 @GST_STATE_NULL: Reset the state of an element.
40 @GST_STATE_READY: will make the element ready to start processing data. some
41 elements might have a non trivial way to initialize themselves.
42 @GST_STATE_PLAYING: means there really is data flowing through the graph.
43 @GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow.
44
45 <!-- ##### ENUM GstElementStateReturn ##### -->
46 <para>
47 This enum defines the standard return values that an element
48 can return after a state change.
49
50 </para>
51
52 @GST_STATE_FAILURE: the element could not perform the state change
53 @GST_STATE_SUCCESS: the element successfully changed its state
54 @GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible
55
56 <!-- ##### MACRO GST_STATE ##### -->
57 <para>
58 This macro returns the current state of the element.
59 </para>
60
61 @obj: Element to return state for.
62
63
64 <!-- ##### MACRO GST_STATE_PENDING ##### -->
65 <para>
66 This macro returns the currently pending state of the element.
67 </para>
68
69 @obj: Element to return the pending state for.
70
71
72 <!-- ##### MACRO GST_STATE_TRANSITION ##### -->
73 <para>
74 Returns the state transition this object is going through.
75 </para>
76
77 @obj: the Element to return the state transition for
78
79
80 <!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
81 <para>
82 The Element is going from the NULL state to the READY state.
83 </para>
84
85
86
87 <!-- ##### MACRO GST_STATE_READY_TO_PLAYING ##### -->
88 <para>
89 The Element is going from the READY state to the PLAYING state.
90 </para>
91
92
93
94 <!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
95 <para>
96 The Element is going from the PLAYING state to the PAUSED state.
97 </para>
98
99
100
101 <!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
102 <para>
103 The Element is going from the PAUSED state to the PLAYING state.
104 </para>
105
106
107
108 <!-- ##### MACRO GST_STATE_PLAYING_TO_READY ##### -->
109 <para>
110 The Element is going from the PLAYING state to the READY state.
111 </para>
112
113
114
115 <!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
116 <para>
117 The Element is going from the READY state to the NULL state.
118 </para>
119
120
121
122 <!-- ##### ENUM GstElementFlags ##### -->
123 <para>
124 This enum defines the standard flags that an element may have.
125 </para>
126
127 @GST_ELEMENT_COMPLEX: 
128 @GST_ELEMENT_DECOUPLED: 
129 @GST_ELEMENT_THREAD_SUGGESTED: 
130 @GST_ELEMENT_NO_SEEK: 
131 @GST_ELEMENT_NEW_LOOPFUNC: 
132 @GST_ELEMENT_COTHREAD_STOPPING: 
133 @GST_ELEMENT_USE_COTHREAD: 
134 @GST_ELEMENT_FLAG_LAST: 
135
136 <!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
137 <para>
138 Queries whether the Element should be placed in a thread.
139 </para>
140
141 @obj: The element to query
142
143
144 <!-- ##### MACRO GST_ELEMENT_IS_COTHREAD_STOPPING ##### -->
145 <para>
146 Queries whether the cothread holding this element needs to be stopped.
147 </para>
148
149 @obj: The element to query
150
151
152 <!-- ##### STRUCT GstElement ##### -->
153 <para>
154
155 </para>
156
157
158 <!-- ##### STRUCT GstElementDetails ##### -->
159 <para>
160 This struct is used to define public information about the element.  It
161 describes the element, mostly for the benefit of editors.
162 </para>
163
164 @longname: 
165 @klass: 
166 @description: 
167 @version: 
168 @author: 
169 @copyright: 
170
171 <!-- ##### STRUCT GstElementFactory ##### -->
172 <para>
173 This factory is used when registering the element, and contains the name
174 of the element, the GtkType value for it, as well as a pointer to the
175 GstElementDetails struct for the element.
176 </para>
177
178 @name: 
179 @type: 
180 @details: 
181 @padtemplates: 
182 @numpadtemplates: 
183
184 <!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
185 <para>
186 This function type is used to specify a loop function for the element.  It
187 is passed the element in question, and is expect to return only in error
188 circumstances.
189 </para>
190
191 @element: The element in question.
192
193
194 <!-- ##### FUNCTION gst_element_new ##### -->
195 <para>
196
197 </para>
198
199 @Returns: 
200
201
202 <!-- ##### MACRO gst_element_destroy ##### -->
203 <para>
204
205 </para>
206
207 @element: the element to destroy
208
209
210 <!-- ##### FUNCTION gst_element_set_loop_function ##### -->
211 <para>
212
213 </para>
214
215 @element: 
216 @loop: 
217
218
219 <!-- ##### FUNCTION gst_element_set_name ##### -->
220 <para>
221
222 </para>
223
224 @element: 
225 @name: 
226
227
228 <!-- ##### FUNCTION gst_element_get_name ##### -->
229 <para>
230
231 </para>
232
233 @element: 
234 @Returns: 
235
236
237 <!-- ##### FUNCTION gst_element_set_manager ##### -->
238 <para>
239
240 </para>
241
242 @element: 
243 @manager: 
244
245
246 <!-- ##### FUNCTION gst_element_get_manager ##### -->
247 <para>
248
249 </para>
250
251 @element: 
252 @Returns: 
253
254
255 <!-- ##### FUNCTION gst_element_add_pad ##### -->
256 <para>
257
258 </para>
259
260 @element: 
261 @pad: 
262
263
264 <!-- ##### FUNCTION gst_element_get_pad ##### -->
265 <para>
266
267 </para>
268
269 @element: 
270 @name: 
271 @Returns: GList of pads
272
273
274 <!-- ##### FUNCTION gst_element_get_pad_list ##### -->
275 <para>
276
277 </para>
278
279 @element: 
280 @Returns: 
281
282
283 <!-- ##### FUNCTION gst_element_get_padtemplate_list ##### -->
284 <para>
285
286 </para>
287
288 @element: 
289 @Returns: 
290
291
292 <!-- ##### FUNCTION gst_element_get_padtemplate_by_name ##### -->
293 <para>
294
295 </para>
296
297 @element: 
298 @name: 
299 @Returns: 
300
301
302 <!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
303 <para>
304
305 </para>
306
307 @element: 
308 @pad: 
309
310
311 <!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
312 <para>
313
314 </para>
315
316 @element: 
317 @pad: 
318
319
320 <!-- ##### FUNCTION gst_element_request_pad ##### -->
321 <para>
322
323 </para>
324
325 @element: 
326 @templ: 
327 @Returns: 
328 <!-- # Unused Parameters # -->
329 @temp: 
330
331
332 <!-- ##### FUNCTION gst_element_request_pad_by_name ##### -->
333 <para>
334
335 </para>
336
337 @element: 
338 @name: 
339 @Returns: 
340
341
342 <!-- ##### FUNCTION gst_element_connect ##### -->
343 <para>
344
345 </para>
346
347 @src: 
348 @srcpadname: 
349 @dest: 
350 @destpadname: 
351
352
353 <!-- ##### FUNCTION gst_element_disconnect ##### -->
354 <para>
355
356 </para>
357
358 @src: 
359 @srcpadname: 
360 @dest: 
361 @destpadname: 
362
363
364 <!-- ##### FUNCTION gst_element_set_state ##### -->
365 <para>
366
367 </para>
368
369 @element: 
370 @state: 
371 @Returns: 
372
373
374 <!-- ##### FUNCTION gst_element_error ##### -->
375 <para>
376
377 </para>
378
379 @element: 
380 @error: 
381
382
383 <!-- ##### FUNCTION gst_element_get_factory ##### -->
384 <para>
385
386 </para>
387
388 @element: 
389 @Returns: 
390
391
392 <!-- ##### FUNCTION gst_element_signal_eos ##### -->
393 <para>
394
395 </para>
396
397 @element: 
398
399
400 <!-- ##### FUNCTION gst_element_save_thyself ##### -->
401 <para>
402
403 </para>
404
405 @element: 
406 @parent: 
407 @Returns: 
408
409
410 <!-- ##### FUNCTION gst_element_load_thyself ##### -->
411 <para>
412
413 </para>
414
415 @parent: 
416 @elements: 
417 @Returns: 
418
419
420 <!-- ##### FUNCTION gst_elementfactory_new ##### -->
421 <para>
422
423 </para>
424
425 @name: 
426 @type: 
427 @details: 
428 @Returns: 
429
430
431 <!-- ##### FUNCTION gst_elementfactory_destroy ##### -->
432 <para>
433
434 </para>
435
436 @elementfactory: 
437
438
439 <!-- ##### FUNCTION gst_elementfactory_add_padtemplate ##### -->
440 <para>
441
442 </para>
443
444 @elementfactory: 
445 @templ: 
446 <!-- # Unused Parameters # -->
447 @temp: 
448 @pad: 
449
450
451 <!-- ##### FUNCTION gst_elementfactory_find ##### -->
452 <para>
453
454 </para>
455
456 @name: 
457 @Returns: 
458
459
460 <!-- ##### FUNCTION gst_elementfactory_get_list ##### -->
461 <para>
462
463 </para>
464
465 @Returns: 
466
467
468 <!-- ##### FUNCTION gst_elementfactory_can_src_caps ##### -->
469 <para>
470
471 </para>
472
473 @factory: 
474 @caps: 
475 @Returns: 
476
477
478 <!-- ##### FUNCTION gst_elementfactory_can_sink_caps ##### -->
479 <para>
480
481 </para>
482
483 @factory: 
484 @caps: 
485 @Returns: 
486
487
488 <!-- ##### FUNCTION gst_elementfactory_can_src_caps_list ##### -->
489 <para>
490
491 </para>
492
493 @factory: 
494 @caps: 
495 @Returns: 
496
497
498 <!-- ##### FUNCTION gst_elementfactory_can_sink_caps_list ##### -->
499 <para>
500
501 </para>
502
503 @factory: 
504 @caps: 
505 @Returns: 
506
507
508 <!-- ##### FUNCTION gst_elementfactory_create ##### -->
509 <para>
510
511 </para>
512
513 @factory: 
514 @name: 
515 @Returns: 
516
517
518 <!-- ##### FUNCTION gst_elementfactory_make ##### -->
519 <para>
520
521 </para>
522
523 @factoryname: 
524 @name: 
525 @Returns: 
526
527
528 <!-- ##### FUNCTION gst_elementfactory_save_thyself ##### -->
529 <para>
530
531 </para>
532
533 @factory: 
534 @parent: 
535 @Returns: 
536
537
538 <!-- ##### FUNCTION gst_elementfactory_load_thyself ##### -->
539 <para>
540
541 </para>
542
543 @parent: 
544 @Returns: 
545
546
547 <!-- ##### SIGNAL GstElement::state-change ##### -->
548 <para>
549 Is trigered whenever the state of an element changes
550 </para>
551
552 @gstelement: the object which received the signal.
553 @arg1: the new state of the object
554
555 <!-- ##### SIGNAL GstElement::new-pad ##### -->
556 <para>
557 Is trigered whenever a new pad is added to an element
558 </para>
559
560 @gstelement: the object which received the signal.
561 @arg1: the new pad that was added
562
563 <!-- ##### SIGNAL GstElement::new-ghost-pad ##### -->
564 <para>
565
566 Is trigered whenever a new ghost pad is added to an element
567 </para>
568
569 @gstelement: the object which received the signal.
570 @arg1: the new ghost pad that was added
571
572 <!-- ##### SIGNAL GstElement::error ##### -->
573 <para>
574 Is trigered whenever an error occured
575
576 </para>
577
578 @gstelement: the object which received the signal.
579 @arg1: the error message
580
581 <!-- ##### SIGNAL GstElement::eos ##### -->
582 <para>
583
584 </para>
585
586 @gstelement: the object which received the signal.
587