dshow: crossbar dialog was frequently being displayed twice, split up option so it...
[ffmpeg.git] / doc / utils.texi
1 @chapter Syntax
2 @c man begin SYNTAX
3
4 This section documents the syntax and formats employed by the FFmpeg
5 libraries and tools.
6
7 @anchor{quoting_and_escaping}
8 @section Quoting and escaping
9
10 FFmpeg adopts the following quoting and escaping mechanism, unless
11 explicitly specified. The following rules are applied:
12
13 @itemize
14 @item
15 @code{'} and @code{\} are special characters (respectively used for
16 quoting and escaping). In addition to them, there might be other
17 special characters depending on the specific syntax where the escaping
18 and quoting are employed.
19
20 @item
21 A special character is escaped by prefixing it with a '\'.
22
23 @item
24 All characters enclosed between '' are included literally in the
25 parsed string. The quote character @code{'} itself cannot be quoted,
26 so you may need to close the quote and escape it.
27
28 @item
29 Leading and trailing whitespaces, unless escaped or quoted, are
30 removed from the parsed string.
31 @end itemize
32
33 Note that you may need to add a second level of escaping when using
34 the command line or a script, which depends on the syntax of the
35 adopted shell language.
36
37 The function @code{av_get_token} defined in
38 @file{libavutil/avstring.h} can be used to parse a token quoted or
39 escaped according to the rules defined above.
40
41 The tool @file{tools/ffescape} in the FFmpeg source tree can be used
42 to automatically quote or escape a string in a script.
43
44 @subsection Examples
45
46 @itemize
47 @item
48 Escape the string @code{Crime d'Amour} containing the @code{'} special
49 character:
50 @example
51 Crime d\'Amour
52 @end example
53
54 @item
55 The string above contains a quote, so the @code{'} needs to be escaped
56 when quoting it:
57 @example
58 'Crime d'\''Amour'
59 @end example
60
61 @item
62 Include leading or trailing whitespaces using quoting:
63 @example
64 '  this string starts and ends with whitespaces  '
65 @end example
66
67 @item
68 Escaping and quoting can be mixed together:
69 @example
70 ' The string '\'string\'' is a string '
71 @end example
72
73 @item
74 To include a literal @code{\} you can use either escaping or quoting:
75 @example
76 'c:\foo' can be written as c:\\foo
77 @end example
78 @end itemize
79
80 @anchor{date syntax}
81 @section Date
82
83 The accepted syntax is:
84 @example
85 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
86 now
87 @end example
88
89 If the value is "now" it takes the current time.
90
91 Time is local time unless Z is appended, in which case it is
92 interpreted as UTC.
93 If the year-month-day part is not specified it takes the current
94 year-month-day.
95
96 @anchor{time duration syntax}
97 @section Time duration
98
99 There are two accepted syntaxes for expressing time duration.
100
101 @example
102 [-][@var{HH}:]@var{MM}:@var{SS}[.@var{m}...]
103 @end example
104
105 @var{HH} expresses the number of hours, @var{MM} the number of minutes
106 for a maximum of 2 digits, and @var{SS} the number of seconds for a
107 maximum of 2 digits. The @var{m} at the end expresses decimal value for
108 @var{SS}.
109
110 @emph{or}
111
112 @example
113 [-]@var{S}+[.@var{m}...]
114 @end example
115
116 @var{S} expresses the number of seconds, with the optional decimal part
117 @var{m}.
118
119 In both expressions, the optional @samp{-} indicates negative duration.
120
121 @subsection Examples
122
123 The following examples are all valid time duration:
124
125 @table @samp
126 @item 55
127 55 seconds
128
129 @item 12:03:45
130 12 hours, 03 minutes and 45 seconds
131
132 @item 23.189
133 23.189 seconds
134 @end table
135
136 @anchor{video size syntax}
137 @section Video size
138 Specify the size of the sourced video, it may be a string of the form
139 @var{width}x@var{height}, or the name of a size abbreviation.
140
141 The following abbreviations are recognized:
142 @table @samp
143 @item ntsc
144 720x480
145 @item pal
146 720x576
147 @item qntsc
148 352x240
149 @item qpal
150 352x288
151 @item sntsc
152 640x480
153 @item spal
154 768x576
155 @item film
156 352x240
157 @item ntsc-film
158 352x240
159 @item sqcif
160 128x96
161 @item qcif
162 176x144
163 @item cif
164 352x288
165 @item 4cif
166 704x576
167 @item 16cif
168 1408x1152
169 @item qqvga
170 160x120
171 @item qvga
172 320x240
173 @item vga
174 640x480
175 @item svga
176 800x600
177 @item xga
178 1024x768
179 @item uxga
180 1600x1200
181 @item qxga
182 2048x1536
183 @item sxga
184 1280x1024
185 @item qsxga
186 2560x2048
187 @item hsxga
188 5120x4096
189 @item wvga
190 852x480
191 @item wxga
192 1366x768
193 @item wsxga
194 1600x1024
195 @item wuxga
196 1920x1200
197 @item woxga
198 2560x1600
199 @item wqsxga
200 3200x2048
201 @item wquxga
202 3840x2400
203 @item whsxga
204 6400x4096
205 @item whuxga
206 7680x4800
207 @item cga
208 320x200
209 @item ega
210 640x350
211 @item hd480
212 852x480
213 @item hd720
214 1280x720
215 @item hd1080
216 1920x1080
217 @item 2k
218 2048x1080
219 @item 2kflat
220 1998x1080
221 @item 2kscope
222 2048x858
223 @item 4k
224 4096x2160
225 @item 4kflat
226 3996x2160
227 @item 4kscope
228 4096x1716
229 @item nhd
230 640x360
231 @item hqvga
232 240x160
233 @item wqvga
234 400x240
235 @item fwqvga
236 432x240
237 @item hvga
238 480x320
239 @item qhd
240 960x540
241 @end table
242
243 @anchor{video rate syntax}
244 @section Video rate
245
246 Specify the frame rate of a video, expressed as the number of frames
247 generated per second. It has to be a string in the format
248 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
249 number or a valid video frame rate abbreviation.
250
251 The following abbreviations are recognized:
252 @table @samp
253 @item ntsc
254 30000/1001
255 @item pal
256 25/1
257 @item qntsc
258 30000/1001
259 @item qpal
260 25/1
261 @item sntsc
262 30000/1001
263 @item spal
264 25/1
265 @item film
266 24/1
267 @item ntsc-film
268 24000/1001
269 @end table
270
271 @anchor{ratio syntax}
272 @section Ratio
273
274 A ratio can be expressed as an expression, or in the form
275 @var{numerator}:@var{denominator}.
276
277 Note that a ratio with infinite (1/0) or negative value is
278 considered valid, so you should check on the returned value if you
279 want to exclude those values.
280
281 The undefined value can be expressed using the "0:0" string.
282
283 @anchor{color syntax}
284 @section Color
285
286 It can be the name of a color as defined below (case insensitive match) or a
287 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
288 representing the alpha component.
289
290 The alpha component may be a string composed by "0x" followed by an
291 hexadecimal number or a decimal number between 0.0 and 1.0, which
292 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
293 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
294 component is not specified then @samp{0xff} is assumed.
295
296 The string @samp{random} will result in a random color.
297
298 The following names of colors are recognized:
299 @table @samp
300 @item AliceBlue
301 0xF0F8FF
302 @item AntiqueWhite
303 0xFAEBD7
304 @item Aqua
305 0x00FFFF
306 @item Aquamarine
307 0x7FFFD4
308 @item Azure
309 0xF0FFFF
310 @item Beige
311 0xF5F5DC
312 @item Bisque
313 0xFFE4C4
314 @item Black
315 0x000000
316 @item BlanchedAlmond
317 0xFFEBCD
318 @item Blue
319 0x0000FF
320 @item BlueViolet
321 0x8A2BE2
322 @item Brown
323 0xA52A2A
324 @item BurlyWood
325 0xDEB887
326 @item CadetBlue
327 0x5F9EA0
328 @item Chartreuse
329 0x7FFF00
330 @item Chocolate
331 0xD2691E
332 @item Coral
333 0xFF7F50
334 @item CornflowerBlue
335 0x6495ED
336 @item Cornsilk
337 0xFFF8DC
338 @item Crimson
339 0xDC143C
340 @item Cyan
341 0x00FFFF
342 @item DarkBlue
343 0x00008B
344 @item DarkCyan
345 0x008B8B
346 @item DarkGoldenRod
347 0xB8860B
348 @item DarkGray
349 0xA9A9A9
350 @item DarkGreen
351 0x006400
352 @item DarkKhaki
353 0xBDB76B
354 @item DarkMagenta
355 0x8B008B
356 @item DarkOliveGreen
357 0x556B2F
358 @item Darkorange
359 0xFF8C00
360 @item DarkOrchid
361 0x9932CC
362 @item DarkRed
363 0x8B0000
364 @item DarkSalmon
365 0xE9967A
366 @item DarkSeaGreen
367 0x8FBC8F
368 @item DarkSlateBlue
369 0x483D8B
370 @item DarkSlateGray
371 0x2F4F4F
372 @item DarkTurquoise
373 0x00CED1
374 @item DarkViolet
375 0x9400D3
376 @item DeepPink
377 0xFF1493
378 @item DeepSkyBlue
379 0x00BFFF
380 @item DimGray
381 0x696969
382 @item DodgerBlue
383 0x1E90FF
384 @item FireBrick
385 0xB22222
386 @item FloralWhite
387 0xFFFAF0
388 @item ForestGreen
389 0x228B22
390 @item Fuchsia
391 0xFF00FF
392 @item Gainsboro
393 0xDCDCDC
394 @item GhostWhite
395 0xF8F8FF
396 @item Gold
397 0xFFD700
398 @item GoldenRod
399 0xDAA520
400 @item Gray
401 0x808080
402 @item Green
403 0x008000
404 @item GreenYellow
405 0xADFF2F
406 @item HoneyDew
407 0xF0FFF0
408 @item HotPink
409 0xFF69B4
410 @item IndianRed
411 0xCD5C5C
412 @item Indigo
413 0x4B0082
414 @item Ivory
415 0xFFFFF0
416 @item Khaki
417 0xF0E68C
418 @item Lavender
419 0xE6E6FA
420 @item LavenderBlush
421 0xFFF0F5
422 @item LawnGreen
423 0x7CFC00
424 @item LemonChiffon
425 0xFFFACD
426 @item LightBlue
427 0xADD8E6
428 @item LightCoral
429 0xF08080
430 @item LightCyan
431 0xE0FFFF
432 @item LightGoldenRodYellow
433 0xFAFAD2
434 @item LightGreen
435 0x90EE90
436 @item LightGrey
437 0xD3D3D3
438 @item LightPink
439 0xFFB6C1
440 @item LightSalmon
441 0xFFA07A
442 @item LightSeaGreen
443 0x20B2AA
444 @item LightSkyBlue
445 0x87CEFA
446 @item LightSlateGray
447 0x778899
448 @item LightSteelBlue
449 0xB0C4DE
450 @item LightYellow
451 0xFFFFE0
452 @item Lime
453 0x00FF00
454 @item LimeGreen
455 0x32CD32
456 @item Linen
457 0xFAF0E6
458 @item Magenta
459 0xFF00FF
460 @item Maroon
461 0x800000
462 @item MediumAquaMarine
463 0x66CDAA
464 @item MediumBlue
465 0x0000CD
466 @item MediumOrchid
467 0xBA55D3
468 @item MediumPurple
469 0x9370D8
470 @item MediumSeaGreen
471 0x3CB371
472 @item MediumSlateBlue
473 0x7B68EE
474 @item MediumSpringGreen
475 0x00FA9A
476 @item MediumTurquoise
477 0x48D1CC
478 @item MediumVioletRed
479 0xC71585
480 @item MidnightBlue
481 0x191970
482 @item MintCream
483 0xF5FFFA
484 @item MistyRose
485 0xFFE4E1
486 @item Moccasin
487 0xFFE4B5
488 @item NavajoWhite
489 0xFFDEAD
490 @item Navy
491 0x000080
492 @item OldLace
493 0xFDF5E6
494 @item Olive
495 0x808000
496 @item OliveDrab
497 0x6B8E23
498 @item Orange
499 0xFFA500
500 @item OrangeRed
501 0xFF4500
502 @item Orchid
503 0xDA70D6
504 @item PaleGoldenRod
505 0xEEE8AA
506 @item PaleGreen
507 0x98FB98
508 @item PaleTurquoise
509 0xAFEEEE
510 @item PaleVioletRed
511 0xD87093
512 @item PapayaWhip
513 0xFFEFD5
514 @item PeachPuff
515 0xFFDAB9
516 @item Peru
517 0xCD853F
518 @item Pink
519 0xFFC0CB
520 @item Plum
521 0xDDA0DD
522 @item PowderBlue
523 0xB0E0E6
524 @item Purple
525 0x800080
526 @item Red
527 0xFF0000
528 @item RosyBrown
529 0xBC8F8F
530 @item RoyalBlue
531 0x4169E1
532 @item SaddleBrown
533 0x8B4513
534 @item Salmon
535 0xFA8072
536 @item SandyBrown
537 0xF4A460
538 @item SeaGreen
539 0x2E8B57
540 @item SeaShell
541 0xFFF5EE
542 @item Sienna
543 0xA0522D
544 @item Silver
545 0xC0C0C0
546 @item SkyBlue
547 0x87CEEB
548 @item SlateBlue
549 0x6A5ACD
550 @item SlateGray
551 0x708090
552 @item Snow
553 0xFFFAFA
554 @item SpringGreen
555 0x00FF7F
556 @item SteelBlue
557 0x4682B4
558 @item Tan
559 0xD2B48C
560 @item Teal
561 0x008080
562 @item Thistle
563 0xD8BFD8
564 @item Tomato
565 0xFF6347
566 @item Turquoise
567 0x40E0D0
568 @item Violet
569 0xEE82EE
570 @item Wheat
571 0xF5DEB3
572 @item White
573 0xFFFFFF
574 @item WhiteSmoke
575 0xF5F5F5
576 @item Yellow
577 0xFFFF00
578 @item YellowGreen
579 0x9ACD32
580 @end table
581
582 @anchor{channel layout syntax}
583 @section Channel Layout
584
585 A channel layout specifies the spatial disposition of the channels in
586 a multi-channel audio stream. To specify a channel layout, FFmpeg
587 makes use of a special syntax.
588
589 Individual channels are identified by an id, as given by the table
590 below:
591 @table @samp
592 @item FL
593 front left
594 @item FR
595 front right
596 @item FC
597 front center
598 @item LFE
599 low frequency
600 @item BL
601 back left
602 @item BR
603 back right
604 @item FLC
605 front left-of-center
606 @item FRC
607 front right-of-center
608 @item BC
609 back center
610 @item SL
611 side left
612 @item SR
613 side right
614 @item TC
615 top center
616 @item TFL
617 top front left
618 @item TFC
619 top front center
620 @item TFR
621 top front right
622 @item TBL
623 top back left
624 @item TBC
625 top back center
626 @item TBR
627 top back right
628 @item DL
629 downmix left
630 @item DR
631 downmix right
632 @item WL
633 wide left
634 @item WR
635 wide right
636 @item SDL
637 surround direct left
638 @item SDR
639 surround direct right
640 @item LFE2
641 low frequency 2
642 @end table
643
644 Standard channel layout compositions can be specified by using the
645 following identifiers:
646 @table @samp
647 @item mono
648 FC
649 @item stereo
650 FL+FR
651 @item 2.1
652 FL+FR+LFE
653 @item 3.0
654 FL+FR+FC
655 @item 3.0(back)
656 FL+FR+BC
657 @item 4.0
658 FL+FR+FC+BC
659 @item quad
660 FL+FR+BL+BR
661 @item quad(side)
662 FL+FR+SL+SR
663 @item 3.1
664 FL+FR+FC+LFE
665 @item 5.0
666 FL+FR+FC+BL+BR
667 @item 5.0(side)
668 FL+FR+FC+SL+SR
669 @item 4.1
670 FL+FR+FC+LFE+BC
671 @item 5.1
672 FL+FR+FC+LFE+BL+BR
673 @item 5.1(side)
674 FL+FR+FC+LFE+SL+SR
675 @item 6.0
676 FL+FR+FC+BC+SL+SR
677 @item 6.0(front)
678 FL+FR+FLC+FRC+SL+SR
679 @item hexagonal
680 FL+FR+FC+BL+BR+BC
681 @item 6.1
682 FL+FR+FC+LFE+BC+SL+SR
683 @item 6.1
684 FL+FR+FC+LFE+BL+BR+BC
685 @item 6.1(front)
686 FL+FR+LFE+FLC+FRC+SL+SR
687 @item 7.0
688 FL+FR+FC+BL+BR+SL+SR
689 @item 7.0(front)
690 FL+FR+FC+FLC+FRC+SL+SR
691 @item 7.1
692 FL+FR+FC+LFE+BL+BR+SL+SR
693 @item 7.1(wide)
694 FL+FR+FC+LFE+BL+BR+FLC+FRC
695 @item 7.1(wide-side)
696 FL+FR+FC+LFE+FLC+FRC+SL+SR
697 @item octagonal
698 FL+FR+FC+BL+BR+BC+SL+SR
699 @item downmix
700 DL+DR
701 @end table
702
703 A custom channel layout can be specified as a sequence of terms, separated by
704 '+' or '|'. Each term can be:
705 @itemize
706 @item
707 the name of a standard channel layout (e.g. @samp{mono},
708 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
709
710 @item
711 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
712
713 @item
714 a number of channels, in decimal, optionally followed by 'c', yielding
715 the default channel layout for that number of channels (see the
716 function @code{av_get_default_channel_layout})
717
718 @item
719 a channel layout mask, in hexadecimal starting with "0x" (see the
720 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
721 @end itemize
722
723 Starting from libavutil version 53 the trailing character "c" to
724 specify a number of channels will be required, while a channel layout
725 mask could also be specified as a decimal number (if and only if not
726 followed by "c").
727
728 See also the function @code{av_get_channel_layout} defined in
729 @file{libavutil/channel_layout.h}.
730 @c man end SYNTAX
731
732 @chapter Expression Evaluation
733 @c man begin EXPRESSION EVALUATION
734
735 When evaluating an arithmetic expression, FFmpeg uses an internal
736 formula evaluator, implemented through the @file{libavutil/eval.h}
737 interface.
738
739 An expression may contain unary, binary operators, constants, and
740 functions.
741
742 Two expressions @var{expr1} and @var{expr2} can be combined to form
743 another expression "@var{expr1};@var{expr2}".
744 @var{expr1} and @var{expr2} are evaluated in turn, and the new
745 expression evaluates to the value of @var{expr2}.
746
747 The following binary operators are available: @code{+}, @code{-},
748 @code{*}, @code{/}, @code{^}.
749
750 The following unary operators are available: @code{+}, @code{-}.
751
752 The following functions are available:
753 @table @option
754 @item abs(x)
755 Compute absolute value of @var{x}.
756
757 @item acos(x)
758 Compute arccosine of @var{x}.
759
760 @item asin(x)
761 Compute arcsine of @var{x}.
762
763 @item atan(x)
764 Compute arctangent of @var{x}.
765
766 @item between(x, min, max)
767 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
768 equal to @var{max}, 0 otherwise.
769
770 @item bitand(x, y)
771 @item bitor(x, y)
772 Compute bitwise and/or operation on @var{x} and @var{y}.
773
774 The results of the evaluation of @var{x} and @var{y} are converted to
775 integers before executing the bitwise operation.
776
777 Note that both the conversion to integer and the conversion back to
778 floating point can lose precision. Beware of unexpected results for
779 large numbers (usually 2^53 and larger).
780
781 @item ceil(expr)
782 Round the value of expression @var{expr} upwards to the nearest
783 integer. For example, "ceil(1.5)" is "2.0".
784
785 @item clip(x, min, max)
786 Return the value of @var{x} clipped between @var{min} and @var{max}.
787
788 @item cos(x)
789 Compute cosine of @var{x}.
790
791 @item cosh(x)
792 Compute hyperbolic cosine of @var{x}.
793
794 @item eq(x, y)
795 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
796
797 @item exp(x)
798 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
799
800 @item floor(expr)
801 Round the value of expression @var{expr} downwards to the nearest
802 integer. For example, "floor(-1.5)" is "-2.0".
803
804 @item gauss(x)
805 Compute Gauss function of @var{x}, corresponding to
806 @code{exp(-x*x/2) / sqrt(2*PI)}.
807
808 @item gcd(x, y)
809 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
810 @var{y} are 0 or either or both are less than zero then behavior is undefined.
811
812 @item gt(x, y)
813 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
814
815 @item gte(x, y)
816 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
817
818 @item hypot(x, y)
819 This function is similar to the C function with the same name; it returns
820 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
821 right triangle with sides of length @var{x} and @var{y}, or the distance of the
822 point (@var{x}, @var{y}) from the origin.
823
824 @item if(x, y)
825 Evaluate @var{x}, and if the result is non-zero return the result of
826 the evaluation of @var{y}, return 0 otherwise.
827
828 @item if(x, y, z)
829 Evaluate @var{x}, and if the result is non-zero return the evaluation
830 result of @var{y}, otherwise the evaluation result of @var{z}.
831
832 @item ifnot(x, y)
833 Evaluate @var{x}, and if the result is zero return the result of the
834 evaluation of @var{y}, return 0 otherwise.
835
836 @item ifnot(x, y, z)
837 Evaluate @var{x}, and if the result is zero return the evaluation
838 result of @var{y}, otherwise the evaluation result of @var{z}.
839
840 @item isinf(x)
841 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
842
843 @item isnan(x)
844 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
845
846 @item ld(var)
847 Allow to load the value of the internal variable with number
848 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
849 The function returns the loaded value.
850
851 @item log(x)
852 Compute natural logarithm of @var{x}.
853
854 @item lt(x, y)
855 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
856
857 @item lte(x, y)
858 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
859
860 @item max(x, y)
861 Return the maximum between @var{x} and @var{y}.
862
863 @item min(x, y)
864 Return the maximum between @var{x} and @var{y}.
865
866 @item mod(x, y)
867 Compute the remainder of division of @var{x} by @var{y}.
868
869 @item not(expr)
870 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
871
872 @item pow(x, y)
873 Compute the power of @var{x} elevated @var{y}, it is equivalent to
874 "(@var{x})^(@var{y})".
875
876 @item print(t)
877 @item print(t, l)
878 Print the value of expression @var{t} with loglevel @var{l}. If
879 @var{l} is not specified then a default log level is used.
880 Returns the value of the expression printed.
881
882 Prints t with loglevel l
883
884 @item random(x)
885 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
886 internal variable which will be used to save the seed/state.
887
888 @item root(expr, max)
889 Find an input value for which the function represented by @var{expr}
890 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
891
892 The expression in @var{expr} must denote a continuous function or the
893 result is undefined.
894
895 @var{ld(0)} is used to represent the function input value, which means
896 that the given expression will be evaluated multiple times with
897 various input values that the expression can access through
898 @code{ld(0)}. When the expression evaluates to 0 then the
899 corresponding input value will be returned.
900
901 @item sin(x)
902 Compute sine of @var{x}.
903
904 @item sinh(x)
905 Compute hyperbolic sine of @var{x}.
906
907 @item sqrt(expr)
908 Compute the square root of @var{expr}. This is equivalent to
909 "(@var{expr})^.5".
910
911 @item squish(x)
912 Compute expression @code{1/(1 + exp(4*x))}.
913
914 @item st(var, expr)
915 Allow to store the value of the expression @var{expr} in an internal
916 variable. @var{var} specifies the number of the variable where to
917 store the value, and it is a value ranging from 0 to 9. The function
918 returns the value stored in the internal variable.
919 Note, Variables are currently not shared between expressions.
920
921 @item tan(x)
922 Compute tangent of @var{x}.
923
924 @item tanh(x)
925 Compute hyperbolic tangent of @var{x}.
926
927 @item taylor(expr, x)
928 @item taylor(expr, x, id)
929 Evaluate a Taylor series at @var{x}, given an expression representing
930 the @code{ld(id)}-th derivative of a function at 0.
931
932 When the series does not converge the result is undefined.
933
934 @var{ld(id)} is used to represent the derivative order in @var{expr},
935 which means that the given expression will be evaluated multiple times
936 with various input values that the expression can access through
937 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
938
939 Note, when you have the derivatives at y instead of 0,
940 @code{taylor(expr, x-y)} can be used.
941
942 @item time(0)
943 Return the current (wallclock) time in seconds.
944
945 @item trunc(expr)
946 Round the value of expression @var{expr} towards zero to the nearest
947 integer. For example, "trunc(-1.5)" is "-1.0".
948
949 @item while(cond, expr)
950 Evaluate expression @var{expr} while the expression @var{cond} is
951 non-zero, and returns the value of the last @var{expr} evaluation, or
952 NAN if @var{cond} was always false.
953 @end table
954
955 The following constants are available:
956 @table @option
957 @item PI
958 area of the unit disc, approximately 3.14
959 @item E
960 exp(1) (Euler's number), approximately 2.718
961 @item PHI
962 golden ratio (1+sqrt(5))/2, approximately 1.618
963 @end table
964
965 Assuming that an expression is considered "true" if it has a non-zero
966 value, note that:
967
968 @code{*} works like AND
969
970 @code{+} works like OR
971
972 For example the construct:
973 @example
974 if (A AND B) then C
975 @end example
976 is equivalent to:
977 @example
978 if(A*B, C)
979 @end example
980
981 In your C code, you can extend the list of unary and binary functions,
982 and define recognized constants, so that they are available for your
983 expressions.
984
985 The evaluator also recognizes the International System unit prefixes.
986 If 'i' is appended after the prefix, binary prefixes are used, which
987 are based on powers of 1024 instead of powers of 1000.
988 The 'B' postfix multiplies the value by 8, and can be appended after a
989 unit prefix or used alone. This allows using for example 'KB', 'MiB',
990 'G' and 'B' as number postfix.
991
992 The list of available International System prefixes follows, with
993 indication of the corresponding powers of 10 and of 2.
994 @table @option
995 @item y
996 10^-24 / 2^-80
997 @item z
998 10^-21 / 2^-70
999 @item a
1000 10^-18 / 2^-60
1001 @item f
1002 10^-15 / 2^-50
1003 @item p
1004 10^-12 / 2^-40
1005 @item n
1006 10^-9 / 2^-30
1007 @item u
1008 10^-6 / 2^-20
1009 @item m
1010 10^-3 / 2^-10
1011 @item c
1012 10^-2
1013 @item d
1014 10^-1
1015 @item h
1016 10^2
1017 @item k
1018 10^3 / 2^10
1019 @item K
1020 10^3 / 2^10
1021 @item M
1022 10^6 / 2^20
1023 @item G
1024 10^9 / 2^30
1025 @item T
1026 10^12 / 2^40
1027 @item P
1028 10^15 / 2^40
1029 @item E
1030 10^18 / 2^50
1031 @item Z
1032 10^21 / 2^60
1033 @item Y
1034 10^24 / 2^70
1035 @end table
1036
1037 @c man end EXPRESSION EVALUATION
1038
1039 @chapter OpenCL Options
1040 @c man begin OPENCL OPTIONS
1041
1042 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1043 to set the options for the global OpenCL context.
1044
1045 The list of supported options follows:
1046
1047 @table @option
1048 @item build_options
1049 Set build options used to compile the registered kernels.
1050
1051 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1052
1053 @item platform_idx
1054 Select the index of the platform to run OpenCL code.
1055
1056 The specified index must be one of the indexes in the device list
1057 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1058
1059 @item device_idx
1060 Select the index of the device used to run OpenCL code.
1061
1062 The specified index must be one of the indexes in the device list which
1063 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1064
1065 @end table
1066
1067 @c man end OPENCL OPTIONS