← Back to branch summary

~ubuntu-branches/ubuntu/natty/gst-entrans/natty

« back to all changes in this revision

Viewing changes to docs/plugins/gst-entrans-plugins-docs.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard
  • Date: 2010-09-13 19:49:29 UTC
  • Revision ID: james.westby@ubuntu.com-20100913194929-qz90a14xyxln9yfz
Tags: upstream-0.10.2
Import upstream version 0.10.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/plugins/gst-entrans-plugins-docs.sgml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
 
3
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
4
<!ENTITY % url-entities SYSTEM "url.entities">
 
5
<!ENTITY % text-entities SYSTEM "text.entities">
 
6
<!ENTITY % version-entities SYSTEM "version.entities">
 
7
%url-entities;
 
8
%text-entities;
 
9
%version-entities;
 
10
]>
 
11
 
 
12
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
 
13
  <bookinfo>
 
14
    <title>GStreamer Entrans &GST_MAJORMINOR; Reference Manual</title>
 
15
  </bookinfo>
 
16
 
 
17
  <chapter>
 
18
    <title>gst-entrans Elements</title>
 
19
    <xi:include href="xml/element-astat.xml" />
 
20
    <xi:include href="xml/element-boxscale.xml" />
 
21
    <xi:include href="xml/element-bufferjoin.xml" />
 
22
    <xi:include href="xml/element-capssetter.xml" />
 
23
    <xi:include href="xml/element-cshift.xml" />
 
24
    <xi:include href="xml/element-csub.xml" />
 
25
    <xi:include href="xml/element-dam.xml" />
 
26
    <xi:include href="xml/element-decimate.xml" />
 
27
    <xi:include href="xml/element-delogo.xml" />
 
28
    <xi:include href="xml/element-detectinter.xml" />
 
29
    <xi:include href="xml/element-divxkey.xml" />
 
30
    <xi:include href="xml/element-dnr.xml" />
 
31
    <xi:include href="xml/element-fields.xml" />
 
32
    <xi:include href="xml/element-hqdn3d.xml" />
 
33
    <xi:include href="xml/element-ivtc.xml" />
 
34
    <xi:include href="xml/element-kerneldeint.xml" />
 
35
    <xi:include href="xml/element-mask.xml" />
 
36
    <xi:include href="xml/element-mp2enc.xml" />
 
37
    <xi:include href="xml/element-msharpen.xml" />
 
38
    <xi:include href="xml/element-multiprocpipe.xml" />
 
39
    <xi:include href="xml/element-procpipe.xml" />
 
40
    <xi:include href="xml/element-rbswap.xml" />
 
41
    <xi:include href="xml/element-shift.xml" />
 
42
    <xi:include href="xml/element-smooth.xml" />
 
43
    <xi:include href="xml/element-soften.xml" />
 
44
    <xi:include href="xml/element-stabilize.xml" />
 
45
    <xi:include href="xml/element-stamp.xml" />
 
46
    <xi:include href="xml/element-unsharp.xml" />
 
47
    <xi:include href="xml/element-whitebalance.xml" />
 
48
    <xi:include href="xml/element-xsharpen.xml" />
 
49
    <xi:include href="xml/element-y4mtrans.xml" />
 
50
    <xi:include href="xml/element-y4mparse.xml" />
 
51
  </chapter>
 
52
 
 
53
  <chapter>
 
54
    <title>gst-entrans Plugins</title>
 
55
 
 
56
<para>
 
57
The collective intent of the above plugins is to provide the GStreamer
 
58
framework with a set of filters as already available in various other
 
59
multimedia applications, e.g. &mplayer;/&mencoder;, &transcode;, &avidemux;,
 
60
many of them often duplicated over and over again.  Once so available in
 
61
GStreamer framework, they are accessible by a common API, so that the
 
62
<emphasis>very same code</emphasis> can be used repeatedly (as
 
63
opposed to duplicated), in line with
 
64
<ulink url="&url-gst-home;data/doc/gstreamer/head/manual/html/chapter-motivation.html">
 
65
  GStreamer Motivation &amp; Goals</ulink>.
 
66
</para>
 
67
<para>
 
68
There a number of ways to make such filters available, each requiring more or
 
69
less effort, and providing less or more quality (typically in that order).
 
70
Foremost, of course, is to perform a code-level port, making the filter
 
71
(operation) natively available in GStreamer.  Alternatively, one could resort
 
72
to dynamic or runtime <quote>binding</quote>
 
73
</para>
 
74
 
 
75
<sect2>
 
76
<title>Code Ports</title>
 
77
<para>
 
78
Clearly, when being done properly, this leads to most robust quality
 
79
results.  As it also requires most effort and maintenance, priority focus is
 
80
given to the <quote>popular</quote> ones, defined here as roughly
 
81
proportional to occurrence across various existing applications.
 
82
 
 
83
The following table compares some filter operations, that implement an identical
 
84
or very similar algorithm.
 
85
<informaltable>
 
86
<tgroup cols="5">
 
87
<thead>
 
88
<row>
 
89
  <entry>mencoder</entry>
 
90
  <entry>transcode</entry>
 
91
  <entry>avidemux</entry>
 
92
  <entry>virtualdub</entry>
 
93
  <entry>GStreamer</entry>
 
94
</row>
 
95
</thead>
 
96
<tbody>
 
97
<row>
 
98
  <entry>rectangle</entry>
 
99
  <entry>mask</entry>
 
100
  <entry>Blacken borders</entry>
 
101
  <entry>?</entry>
 
102
  <entry><link linkend="GstMask">mask</link></entry>
 
103
</row>
 
104
<row>
 
105
  <entry>swapuv</entry>
 
106
  <entry>videocore rgbswap</entry>
 
107
  <entry>Swap U and V</entry>
 
108
  <entry>?</entry>
 
109
  <entry><link linkend="GstRbSwap">rbswap</link></entry>
 
110
</row>
 
111
<row>
 
112
  <entry>eq2</entry>
 
113
  <entry>gamma</entry>
 
114
  <entry>MPlayer eq2</entry>
 
115
  <entry>?</entry>
 
116
  <entrytbl rowsep='0' cols='1'>
 
117
    <tbody>
 
118
      <row>
 
119
        <entry><link linkend="GstGamma">gamma gamma=1/[transcode value]</link></entry>
 
120
      </row>
 
121
      <row>
 
122
        <entry><link linkend="GstVideoBalance">videobalance</link></entry>
 
123
      </row>
 
124
    </tbody>
 
125
  </entrytbl>
 
126
</row>
 
127
<row>
 
128
  <entry>field, phase</entry>
 
129
  <entry>fields, doublefps</entry>
 
130
  <entry>drop, * fields</entry>
 
131
  <entry>?</entry>
 
132
  <entry><link linkend="GstFields">fields</link></entry>
 
133
</row>
 
134
<row>
 
135
  <entry>-</entry>
 
136
  <entry>decimate</entry>
 
137
  <entry>Decomb decimate</entry>
 
138
  <entry>Decomb</entry>
 
139
  <entry><link linkend="GstDecimate">decimate</link></entry>
 
140
</row>
 
141
<row>
 
142
  <entry>-</entry>
 
143
  <entry>32detect</entry>
 
144
  <entry>-</entry>
 
145
  <entry>?</entry>
 
146
  <entry><link linkend="GstDetectInter">detectinter</link></entry>
 
147
</row>
 
148
<row>
 
149
  <entry>-</entry>
 
150
  <entry>ivtc</entry>
 
151
  <entry>Decomb telecide</entry>
 
152
  <entry>Decomb</entry>
 
153
  <entry><link linkend="GstIvtc">ivtc</link></entry>
 
154
</row>
 
155
<row>
 
156
  <entry>kerndeint</entry>
 
157
  <entry>-</entry>
 
158
  <entry>kernel deinterlacer</entry>
 
159
  <entry>kerndeint</entry>
 
160
  <entry><link linkend="GstKernelDeint">kerneldeint</link></entry>
 
161
</row>
 
162
<row>
 
163
  <entry>unsharp</entry>
 
164
  <entry>unsharp</entry>
 
165
  <entry>-</entry>
 
166
  <entry>?</entry>
 
167
  <entry><link linkend="GstUnsharp">unsharp</link></entry>
 
168
</row>
 
169
<row>
 
170
  <entry>hqdn3d</entry>
 
171
  <entry>hqdn3d</entry>
 
172
  <entry>MPlayer hqdn3d</entry>
 
173
  <entry>?</entry>
 
174
  <entry><link linkend="GstHqdn3d">hqdn3d</link></entry>
 
175
</row>
 
176
<row>
 
177
  <entry>denoise3d</entry>
 
178
  <entry>denoise3d</entry>
 
179
  <entry>MPlayer denoise3d</entry>
 
180
  <entry>?</entry>
 
181
  <entry><link linkend="GstHqdn3d">hqdn3d</link> high-quality=false</entry>
 
182
</row>
 
183
<row>
 
184
  <entry>-</entry>
 
185
  <entry>dnr</entry>
 
186
  <entry>Denoise</entry>
 
187
  <entry>?</entry>
 
188
  <entry><link linkend="GstDnr">dnr</link></entry>
 
189
</row>
 
190
<row>
 
191
  <entry>-</entry>
 
192
  <entry>smooth</entry>
 
193
  <entry>-</entry>
 
194
  <entry>?</entry>
 
195
  <entry><link linkend="GstSmooth">smooth</link></entry>
 
196
</row>
 
197
<row>
 
198
  <entry>-</entry>
 
199
  <entry>msharpen</entry>
 
200
  <entry>MSharpen</entry>
 
201
  <entry>msharpen</entry>
 
202
  <entry><link linkend="GstMsharpen">msharpen</link></entry>
 
203
</row>
 
204
<row>
 
205
  <entry>-</entry>
 
206
  <entry>xsharpen</entry>
 
207
  <entry>-</entry>
 
208
  <entry>xsharpen</entry>
 
209
  <entry><link linkend="GstXsharpen">xsharpen</link></entry>
 
210
</row>
 
211
<row>
 
212
  <entry>-</entry>
 
213
  <entry>cshift</entry>
 
214
  <entry>Chroma shift</entry>
 
215
  <entry>?</entry>
 
216
  <entry><link linkend="GstCshift">cshift</link></entry>
 
217
</row>
 
218
<row>
 
219
  <entry>-</entry>
 
220
  <entry>csub</entry>
 
221
  <entry>-</entry>
 
222
  <entry>?</entry>
 
223
  <entry><link linkend="GstCsub">csub</link></entry>
 
224
</row>
 
225
<row>
 
226
  <entry>?</entry>
 
227
  <entry>whitebalance</entry>
 
228
  <entry>?</entry>
 
229
  <entry>?</entry>
 
230
  <entry><link linkend="GstWhitebalance">whitebalance</link></entry>
 
231
</row>
 
232
<row>
 
233
  <entry>-</entry>
 
234
  <entry>divxkey</entry>
 
235
  <entry>-</entry>
 
236
  <entry>?</entry>
 
237
  <entry><link linkend="GstDivxKey">divxkey</link></entry>
 
238
</row>
 
239
<row>
 
240
  <entry>delogo</entry>
 
241
  <entry>-</entry>
 
242
  <entry>MPlayer delogo</entry>
 
243
  <entry>?</entry>
 
244
  <entry><link linkend="GstDelogo">delogo</link></entry>
 
245
</row>
 
246
<row>
 
247
  <entry>volume</entry>
 
248
  <entry>astat</entry>
 
249
  <entry>-</entry>
 
250
  <entry>?</entry>
 
251
  <entry><link linkend="GstAstat">astat</link></entry>
 
252
</row>
 
253
</tbody>
 
254
</tgroup>
 
255
</informaltable>
 
256
 
 
257
The above table by no means intends to suggest
 
258
that &GStreamer; offers the widest collection of filters available
 
259
(at present?).
 
260
Indeed, other programs as mentioned above often have many alternative
 
261
implementations and algorithms with similar goals.
 
262
The above merely considers the &GStreamer; perspective/intersection, and if anything,
 
263
simply illustrates there is a great deal of duplicating,
 
264
copying and reworking out there.
 
265
</para>
 
266
</sect2>
 
267
 
 
268
<sect2>
 
269
<title>Runtime Binding</title>
 
270
 
 
271
<para>
 
272
The &netpbm; and &mjpegtools; suites provide long since a number of image/video
 
273
processing operations as stand-alone programs.
 
274
</para>
 
275
 
 
276
<para>
 
277
If so desired, and these programs are present and <varname>PATH</varname>
 
278
accessible, they can be used in a pipeline.
 
279
For example, one or more &mjpegtools; filters can appear as
 
280
follows:
 
281
<informalexample>
 
282
<programlisting>
 
283
y4menc ! y4mtrans command=yuvdenoise ! y4mparse
 
284
</programlisting>
 
285
<programlisting>
 
286
y4menc ! y4mtrans command=y4mdenoise ! <!--
 
287
-->y4mtrans command=yuvmedianfilter ! y4mparse
 
288
</programlisting>
 
289
</informalexample>
 
290
</para>
 
291
 
 
292
<para>
 
293
Be aware that the above pipeline fragments have
 
294
timestamp resequencing as a side-effect.  So, take care not to cause an
 
295
<quote>imbalance</quote> when muxing,
 
296
e.g. by using <link linkend="GstStamp">stamp</link> if needed in other
 
297
streams.
 
298
</para>
 
299
 
 
300
<para>
 
301
The elements used above can also be put to use in dealing with a set of files
 
302
(as input or output).  For example,
 
303
<informalexample>
 
304
<programlisting>
 
305
jpeg2yuv -f 25 -j image-%05.jpg > image.yuv
 
306
<lineannotation># then run following pipeline</lineannotation>
 
307
filesrc location=image.yuv ! y4mparse ! videoflip ! \
 
308
  y4menc ! filesink location=image-out.yuv
 
309
<lineannotation># if desired
 
310
# y4mtopnm and pnmtojpeg processing</lineannotation>
 
311
</programlisting>
 
312
</informalexample>
 
313
Of course, the intermediate file could be omitted by means of some piping,
 
314
and <link linkend="GstProcPipe">procpipe</link> may come in handy as well.
 
315
</para>
 
316
 
 
317
</sect2>
 
318
 
 
319
    <xi:include href="xml/plugin-avidemux.xml" />
 
320
    <xi:include href="xml/plugin-entrans.xml" />
 
321
    <xi:include href="xml/plugin-mencoder.xml" />
 
322
    <xi:include href="xml/plugin-transcode.xml" />
 
323
    <xi:include href="xml/plugin-virtualdub.xml" />
 
324
    <xi:include href="xml/plugin-y4m.xml" />
 
325
  </chapter>
 
326
 
 
327
  <chapter>
 
328
    <title>gst-entrans Helper Elements and Utilities</title>
 
329
    <para>
 
330
      Note that although what is provided here could conceivably be
 
331
      called and considered a library,
 
332
      it is only so used <emphasis>internally</emphasis>
 
333
      and provided for at this time.
 
334
    </para>
 
335
    <xi:include href="xml/video-utils.xml" />
 
336
    <xi:include href="xml/gstproctrans.xml" />
 
337
    <xi:include href="xml/gstmultiproctrans.xml" />
 
338
  </chapter>
 
339
 
 
340
</book>