]> git.sesse.net Git - ffmpeg/blob - doc/utils.texi
Merge commit '48362ceadeb2eb5286ae94ef7f9542d990ff7ec7'
[ffmpeg] / 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 @samp{'} and @samp{\} 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 @samp{\}.
22
23 @item
24 All characters enclosed between @samp{''} are included literally in the
25 parsed string. The quote character @samp{'} 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 @samp{\} 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 @item 2kdci
242 2048x1080
243 @item 4kdci
244 4096x2160
245 @item uhd2160
246 3840x2160
247 @item uhd4320
248 7680x4320
249 @end table
250
251 @anchor{video rate syntax}
252 @section Video rate
253
254 Specify the frame rate of a video, expressed as the number of frames
255 generated per second. It has to be a string in the format
256 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
257 number or a valid video frame rate abbreviation.
258
259 The following abbreviations are recognized:
260 @table @samp
261 @item ntsc
262 30000/1001
263 @item pal
264 25/1
265 @item qntsc
266 30000/1001
267 @item qpal
268 25/1
269 @item sntsc
270 30000/1001
271 @item spal
272 25/1
273 @item film
274 24/1
275 @item ntsc-film
276 24000/1001
277 @end table
278
279 @anchor{ratio syntax}
280 @section Ratio
281
282 A ratio can be expressed as an expression, or in the form
283 @var{numerator}:@var{denominator}.
284
285 Note that a ratio with infinite (1/0) or negative value is
286 considered valid, so you should check on the returned value if you
287 want to exclude those values.
288
289 The undefined value can be expressed using the "0:0" string.
290
291 @anchor{color syntax}
292 @section Color
293
294 It can be the name of a color as defined below (case insensitive match) or a
295 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
296 representing the alpha component.
297
298 The alpha component may be a string composed by "0x" followed by an
299 hexadecimal number or a decimal number between 0.0 and 1.0, which
300 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
301 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
302 component is not specified then @samp{0xff} is assumed.
303
304 The string @samp{random} will result in a random color.
305
306 The following names of colors are recognized:
307 @table @samp
308 @item AliceBlue
309 0xF0F8FF
310 @item AntiqueWhite
311 0xFAEBD7
312 @item Aqua
313 0x00FFFF
314 @item Aquamarine
315 0x7FFFD4
316 @item Azure
317 0xF0FFFF
318 @item Beige
319 0xF5F5DC
320 @item Bisque
321 0xFFE4C4
322 @item Black
323 0x000000
324 @item BlanchedAlmond
325 0xFFEBCD
326 @item Blue
327 0x0000FF
328 @item BlueViolet
329 0x8A2BE2
330 @item Brown
331 0xA52A2A
332 @item BurlyWood
333 0xDEB887
334 @item CadetBlue
335 0x5F9EA0
336 @item Chartreuse
337 0x7FFF00
338 @item Chocolate
339 0xD2691E
340 @item Coral
341 0xFF7F50
342 @item CornflowerBlue
343 0x6495ED
344 @item Cornsilk
345 0xFFF8DC
346 @item Crimson
347 0xDC143C
348 @item Cyan
349 0x00FFFF
350 @item DarkBlue
351 0x00008B
352 @item DarkCyan
353 0x008B8B
354 @item DarkGoldenRod
355 0xB8860B
356 @item DarkGray
357 0xA9A9A9
358 @item DarkGreen
359 0x006400
360 @item DarkKhaki
361 0xBDB76B
362 @item DarkMagenta
363 0x8B008B
364 @item DarkOliveGreen
365 0x556B2F
366 @item Darkorange
367 0xFF8C00
368 @item DarkOrchid
369 0x9932CC
370 @item DarkRed
371 0x8B0000
372 @item DarkSalmon
373 0xE9967A
374 @item DarkSeaGreen
375 0x8FBC8F
376 @item DarkSlateBlue
377 0x483D8B
378 @item DarkSlateGray
379 0x2F4F4F
380 @item DarkTurquoise
381 0x00CED1
382 @item DarkViolet
383 0x9400D3
384 @item DeepPink
385 0xFF1493
386 @item DeepSkyBlue
387 0x00BFFF
388 @item DimGray
389 0x696969
390 @item DodgerBlue
391 0x1E90FF
392 @item FireBrick
393 0xB22222
394 @item FloralWhite
395 0xFFFAF0
396 @item ForestGreen
397 0x228B22
398 @item Fuchsia
399 0xFF00FF
400 @item Gainsboro
401 0xDCDCDC
402 @item GhostWhite
403 0xF8F8FF
404 @item Gold
405 0xFFD700
406 @item GoldenRod
407 0xDAA520
408 @item Gray
409 0x808080
410 @item Green
411 0x008000
412 @item GreenYellow
413 0xADFF2F
414 @item HoneyDew
415 0xF0FFF0
416 @item HotPink
417 0xFF69B4
418 @item IndianRed
419 0xCD5C5C
420 @item Indigo
421 0x4B0082
422 @item Ivory
423 0xFFFFF0
424 @item Khaki
425 0xF0E68C
426 @item Lavender
427 0xE6E6FA
428 @item LavenderBlush
429 0xFFF0F5
430 @item LawnGreen
431 0x7CFC00
432 @item LemonChiffon
433 0xFFFACD
434 @item LightBlue
435 0xADD8E6
436 @item LightCoral
437 0xF08080
438 @item LightCyan
439 0xE0FFFF
440 @item LightGoldenRodYellow
441 0xFAFAD2
442 @item LightGreen
443 0x90EE90
444 @item LightGrey
445 0xD3D3D3
446 @item LightPink
447 0xFFB6C1
448 @item LightSalmon
449 0xFFA07A
450 @item LightSeaGreen
451 0x20B2AA
452 @item LightSkyBlue
453 0x87CEFA
454 @item LightSlateGray
455 0x778899
456 @item LightSteelBlue
457 0xB0C4DE
458 @item LightYellow
459 0xFFFFE0
460 @item Lime
461 0x00FF00
462 @item LimeGreen
463 0x32CD32
464 @item Linen
465 0xFAF0E6
466 @item Magenta
467 0xFF00FF
468 @item Maroon
469 0x800000
470 @item MediumAquaMarine
471 0x66CDAA
472 @item MediumBlue
473 0x0000CD
474 @item MediumOrchid
475 0xBA55D3
476 @item MediumPurple
477 0x9370D8
478 @item MediumSeaGreen
479 0x3CB371
480 @item MediumSlateBlue
481 0x7B68EE
482 @item MediumSpringGreen
483 0x00FA9A
484 @item MediumTurquoise
485 0x48D1CC
486 @item MediumVioletRed
487 0xC71585
488 @item MidnightBlue
489 0x191970
490 @item MintCream
491 0xF5FFFA
492 @item MistyRose
493 0xFFE4E1
494 @item Moccasin
495 0xFFE4B5
496 @item NavajoWhite
497 0xFFDEAD
498 @item Navy
499 0x000080
500 @item OldLace
501 0xFDF5E6
502 @item Olive
503 0x808000
504 @item OliveDrab
505 0x6B8E23
506 @item Orange
507 0xFFA500
508 @item OrangeRed
509 0xFF4500
510 @item Orchid
511 0xDA70D6
512 @item PaleGoldenRod
513 0xEEE8AA
514 @item PaleGreen
515 0x98FB98
516 @item PaleTurquoise
517 0xAFEEEE
518 @item PaleVioletRed
519 0xD87093
520 @item PapayaWhip
521 0xFFEFD5
522 @item PeachPuff
523 0xFFDAB9
524 @item Peru
525 0xCD853F
526 @item Pink
527 0xFFC0CB
528 @item Plum
529 0xDDA0DD
530 @item PowderBlue
531 0xB0E0E6
532 @item Purple
533 0x800080
534 @item Red
535 0xFF0000
536 @item RosyBrown
537 0xBC8F8F
538 @item RoyalBlue
539 0x4169E1
540 @item SaddleBrown
541 0x8B4513
542 @item Salmon
543 0xFA8072
544 @item SandyBrown
545 0xF4A460
546 @item SeaGreen
547 0x2E8B57
548 @item SeaShell
549 0xFFF5EE
550 @item Sienna
551 0xA0522D
552 @item Silver
553 0xC0C0C0
554 @item SkyBlue
555 0x87CEEB
556 @item SlateBlue
557 0x6A5ACD
558 @item SlateGray
559 0x708090
560 @item Snow
561 0xFFFAFA
562 @item SpringGreen
563 0x00FF7F
564 @item SteelBlue
565 0x4682B4
566 @item Tan
567 0xD2B48C
568 @item Teal
569 0x008080
570 @item Thistle
571 0xD8BFD8
572 @item Tomato
573 0xFF6347
574 @item Turquoise
575 0x40E0D0
576 @item Violet
577 0xEE82EE
578 @item Wheat
579 0xF5DEB3
580 @item White
581 0xFFFFFF
582 @item WhiteSmoke
583 0xF5F5F5
584 @item Yellow
585 0xFFFF00
586 @item YellowGreen
587 0x9ACD32
588 @end table
589
590 @anchor{channel layout syntax}
591 @section Channel Layout
592
593 A channel layout specifies the spatial disposition of the channels in
594 a multi-channel audio stream. To specify a channel layout, FFmpeg
595 makes use of a special syntax.
596
597 Individual channels are identified by an id, as given by the table
598 below:
599 @table @samp
600 @item FL
601 front left
602 @item FR
603 front right
604 @item FC
605 front center
606 @item LFE
607 low frequency
608 @item BL
609 back left
610 @item BR
611 back right
612 @item FLC
613 front left-of-center
614 @item FRC
615 front right-of-center
616 @item BC
617 back center
618 @item SL
619 side left
620 @item SR
621 side right
622 @item TC
623 top center
624 @item TFL
625 top front left
626 @item TFC
627 top front center
628 @item TFR
629 top front right
630 @item TBL
631 top back left
632 @item TBC
633 top back center
634 @item TBR
635 top back right
636 @item DL
637 downmix left
638 @item DR
639 downmix right
640 @item WL
641 wide left
642 @item WR
643 wide right
644 @item SDL
645 surround direct left
646 @item SDR
647 surround direct right
648 @item LFE2
649 low frequency 2
650 @end table
651
652 Standard channel layout compositions can be specified by using the
653 following identifiers:
654 @table @samp
655 @item mono
656 FC
657 @item stereo
658 FL+FR
659 @item 2.1
660 FL+FR+LFE
661 @item 3.0
662 FL+FR+FC
663 @item 3.0(back)
664 FL+FR+BC
665 @item 4.0
666 FL+FR+FC+BC
667 @item quad
668 FL+FR+BL+BR
669 @item quad(side)
670 FL+FR+SL+SR
671 @item 3.1
672 FL+FR+FC+LFE
673 @item 5.0
674 FL+FR+FC+BL+BR
675 @item 5.0(side)
676 FL+FR+FC+SL+SR
677 @item 4.1
678 FL+FR+FC+LFE+BC
679 @item 5.1
680 FL+FR+FC+LFE+BL+BR
681 @item 5.1(side)
682 FL+FR+FC+LFE+SL+SR
683 @item 6.0
684 FL+FR+FC+BC+SL+SR
685 @item 6.0(front)
686 FL+FR+FLC+FRC+SL+SR
687 @item hexagonal
688 FL+FR+FC+BL+BR+BC
689 @item 6.1
690 FL+FR+FC+LFE+BC+SL+SR
691 @item 6.1
692 FL+FR+FC+LFE+BL+BR+BC
693 @item 6.1(front)
694 FL+FR+LFE+FLC+FRC+SL+SR
695 @item 7.0
696 FL+FR+FC+BL+BR+SL+SR
697 @item 7.0(front)
698 FL+FR+FC+FLC+FRC+SL+SR
699 @item 7.1
700 FL+FR+FC+LFE+BL+BR+SL+SR
701 @item 7.1(wide)
702 FL+FR+FC+LFE+BL+BR+FLC+FRC
703 @item 7.1(wide-side)
704 FL+FR+FC+LFE+FLC+FRC+SL+SR
705 @item octagonal
706 FL+FR+FC+BL+BR+BC+SL+SR
707 @item downmix
708 DL+DR
709 @end table
710
711 A custom channel layout can be specified as a sequence of terms, separated by
712 '+' or '|'. Each term can be:
713 @itemize
714 @item
715 the name of a standard channel layout (e.g. @samp{mono},
716 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
717
718 @item
719 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
720
721 @item
722 a number of channels, in decimal, optionally followed by 'c', yielding
723 the default channel layout for that number of channels (see the
724 function @code{av_get_default_channel_layout})
725
726 @item
727 a channel layout mask, in hexadecimal starting with "0x" (see the
728 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
729 @end itemize
730
731 Starting from libavutil version 53 the trailing character "c" to
732 specify a number of channels will be required, while a channel layout
733 mask could also be specified as a decimal number (if and only if not
734 followed by "c").
735
736 See also the function @code{av_get_channel_layout} defined in
737 @file{libavutil/channel_layout.h}.
738 @c man end SYNTAX
739
740 @chapter Expression Evaluation
741 @c man begin EXPRESSION EVALUATION
742
743 When evaluating an arithmetic expression, FFmpeg uses an internal
744 formula evaluator, implemented through the @file{libavutil/eval.h}
745 interface.
746
747 An expression may contain unary, binary operators, constants, and
748 functions.
749
750 Two expressions @var{expr1} and @var{expr2} can be combined to form
751 another expression "@var{expr1};@var{expr2}".
752 @var{expr1} and @var{expr2} are evaluated in turn, and the new
753 expression evaluates to the value of @var{expr2}.
754
755 The following binary operators are available: @code{+}, @code{-},
756 @code{*}, @code{/}, @code{^}.
757
758 The following unary operators are available: @code{+}, @code{-}.
759
760 The following functions are available:
761 @table @option
762 @item abs(x)
763 Compute absolute value of @var{x}.
764
765 @item acos(x)
766 Compute arccosine of @var{x}.
767
768 @item asin(x)
769 Compute arcsine of @var{x}.
770
771 @item atan(x)
772 Compute arctangent of @var{x}.
773
774 @item between(x, min, max)
775 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
776 equal to @var{max}, 0 otherwise.
777
778 @item bitand(x, y)
779 @item bitor(x, y)
780 Compute bitwise and/or operation on @var{x} and @var{y}.
781
782 The results of the evaluation of @var{x} and @var{y} are converted to
783 integers before executing the bitwise operation.
784
785 Note that both the conversion to integer and the conversion back to
786 floating point can lose precision. Beware of unexpected results for
787 large numbers (usually 2^53 and larger).
788
789 @item ceil(expr)
790 Round the value of expression @var{expr} upwards to the nearest
791 integer. For example, "ceil(1.5)" is "2.0".
792
793 @item clip(x, min, max)
794 Return the value of @var{x} clipped between @var{min} and @var{max}.
795
796 @item cos(x)
797 Compute cosine of @var{x}.
798
799 @item cosh(x)
800 Compute hyperbolic cosine of @var{x}.
801
802 @item eq(x, y)
803 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
804
805 @item exp(x)
806 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
807
808 @item floor(expr)
809 Round the value of expression @var{expr} downwards to the nearest
810 integer. For example, "floor(-1.5)" is "-2.0".
811
812 @item gauss(x)
813 Compute Gauss function of @var{x}, corresponding to
814 @code{exp(-x*x/2) / sqrt(2*PI)}.
815
816 @item gcd(x, y)
817 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
818 @var{y} are 0 or either or both are less than zero then behavior is undefined.
819
820 @item gt(x, y)
821 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
822
823 @item gte(x, y)
824 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
825
826 @item hypot(x, y)
827 This function is similar to the C function with the same name; it returns
828 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
829 right triangle with sides of length @var{x} and @var{y}, or the distance of the
830 point (@var{x}, @var{y}) from the origin.
831
832 @item if(x, y)
833 Evaluate @var{x}, and if the result is non-zero return the result of
834 the evaluation of @var{y}, return 0 otherwise.
835
836 @item if(x, y, z)
837 Evaluate @var{x}, and if the result is non-zero return the evaluation
838 result of @var{y}, otherwise the evaluation result of @var{z}.
839
840 @item ifnot(x, y)
841 Evaluate @var{x}, and if the result is zero return the result of the
842 evaluation of @var{y}, return 0 otherwise.
843
844 @item ifnot(x, y, z)
845 Evaluate @var{x}, and if the result is zero return the evaluation
846 result of @var{y}, otherwise the evaluation result of @var{z}.
847
848 @item isinf(x)
849 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
850
851 @item isnan(x)
852 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
853
854 @item ld(var)
855 Load the value of the internal variable with number
856 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
857 The function returns the loaded value.
858
859 @item log(x)
860 Compute natural logarithm of @var{x}.
861
862 @item lt(x, y)
863 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
864
865 @item lte(x, y)
866 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
867
868 @item max(x, y)
869 Return the maximum between @var{x} and @var{y}.
870
871 @item min(x, y)
872 Return the minimum between @var{x} and @var{y}.
873
874 @item mod(x, y)
875 Compute the remainder of division of @var{x} by @var{y}.
876
877 @item not(expr)
878 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
879
880 @item pow(x, y)
881 Compute the power of @var{x} elevated @var{y}, it is equivalent to
882 "(@var{x})^(@var{y})".
883
884 @item print(t)
885 @item print(t, l)
886 Print the value of expression @var{t} with loglevel @var{l}. If
887 @var{l} is not specified then a default log level is used.
888 Returns the value of the expression printed.
889
890 Prints t with loglevel l
891
892 @item random(x)
893 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
894 internal variable which will be used to save the seed/state.
895
896 @item root(expr, max)
897 Find an input value for which the function represented by @var{expr}
898 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
899
900 The expression in @var{expr} must denote a continuous function or the
901 result is undefined.
902
903 @var{ld(0)} is used to represent the function input value, which means
904 that the given expression will be evaluated multiple times with
905 various input values that the expression can access through
906 @code{ld(0)}. When the expression evaluates to 0 then the
907 corresponding input value will be returned.
908
909 @item sin(x)
910 Compute sine of @var{x}.
911
912 @item sinh(x)
913 Compute hyperbolic sine of @var{x}.
914
915 @item sqrt(expr)
916 Compute the square root of @var{expr}. This is equivalent to
917 "(@var{expr})^.5".
918
919 @item squish(x)
920 Compute expression @code{1/(1 + exp(4*x))}.
921
922 @item st(var, expr)
923 Store the value of the expression @var{expr} in an internal
924 variable. @var{var} specifies the number of the variable where to
925 store the value, and it is a value ranging from 0 to 9. The function
926 returns the value stored in the internal variable.
927 Note, Variables are currently not shared between expressions.
928
929 @item tan(x)
930 Compute tangent of @var{x}.
931
932 @item tanh(x)
933 Compute hyperbolic tangent of @var{x}.
934
935 @item taylor(expr, x)
936 @item taylor(expr, x, id)
937 Evaluate a Taylor series at @var{x}, given an expression representing
938 the @code{ld(id)}-th derivative of a function at 0.
939
940 When the series does not converge the result is undefined.
941
942 @var{ld(id)} is used to represent the derivative order in @var{expr},
943 which means that the given expression will be evaluated multiple times
944 with various input values that the expression can access through
945 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
946
947 Note, when you have the derivatives at y instead of 0,
948 @code{taylor(expr, x-y)} can be used.
949
950 @item time(0)
951 Return the current (wallclock) time in seconds.
952
953 @item trunc(expr)
954 Round the value of expression @var{expr} towards zero to the nearest
955 integer. For example, "trunc(-1.5)" is "-1.0".
956
957 @item while(cond, expr)
958 Evaluate expression @var{expr} while the expression @var{cond} is
959 non-zero, and returns the value of the last @var{expr} evaluation, or
960 NAN if @var{cond} was always false.
961 @end table
962
963 The following constants are available:
964 @table @option
965 @item PI
966 area of the unit disc, approximately 3.14
967 @item E
968 exp(1) (Euler's number), approximately 2.718
969 @item PHI
970 golden ratio (1+sqrt(5))/2, approximately 1.618
971 @end table
972
973 Assuming that an expression is considered "true" if it has a non-zero
974 value, note that:
975
976 @code{*} works like AND
977
978 @code{+} works like OR
979
980 For example the construct:
981 @example
982 if (A AND B) then C
983 @end example
984 is equivalent to:
985 @example
986 if(A*B, C)
987 @end example
988
989 In your C code, you can extend the list of unary and binary functions,
990 and define recognized constants, so that they are available for your
991 expressions.
992
993 The evaluator also recognizes the International System unit prefixes.
994 If 'i' is appended after the prefix, binary prefixes are used, which
995 are based on powers of 1024 instead of powers of 1000.
996 The 'B' postfix multiplies the value by 8, and can be appended after a
997 unit prefix or used alone. This allows using for example 'KB', 'MiB',
998 'G' and 'B' as number postfix.
999
1000 The list of available International System prefixes follows, with
1001 indication of the corresponding powers of 10 and of 2.
1002 @table @option
1003 @item y
1004 10^-24 / 2^-80
1005 @item z
1006 10^-21 / 2^-70
1007 @item a
1008 10^-18 / 2^-60
1009 @item f
1010 10^-15 / 2^-50
1011 @item p
1012 10^-12 / 2^-40
1013 @item n
1014 10^-9 / 2^-30
1015 @item u
1016 10^-6 / 2^-20
1017 @item m
1018 10^-3 / 2^-10
1019 @item c
1020 10^-2
1021 @item d
1022 10^-1
1023 @item h
1024 10^2
1025 @item k
1026 10^3 / 2^10
1027 @item K
1028 10^3 / 2^10
1029 @item M
1030 10^6 / 2^20
1031 @item G
1032 10^9 / 2^30
1033 @item T
1034 10^12 / 2^40
1035 @item P
1036 10^15 / 2^40
1037 @item E
1038 10^18 / 2^50
1039 @item Z
1040 10^21 / 2^60
1041 @item Y
1042 10^24 / 2^70
1043 @end table
1044
1045 @c man end EXPRESSION EVALUATION
1046
1047 @chapter OpenCL Options
1048 @c man begin OPENCL OPTIONS
1049
1050 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1051 to set the options for the global OpenCL context.
1052
1053 The list of supported options follows:
1054
1055 @table @option
1056 @item build_options
1057 Set build options used to compile the registered kernels.
1058
1059 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1060
1061 @item platform_idx
1062 Select the index of the platform to run OpenCL code.
1063
1064 The specified index must be one of the indexes in the device list
1065 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1066
1067 @item device_idx
1068 Select the index of the device used to run OpenCL code.
1069
1070 The specified index must be one of the indexes in the device list which
1071 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1072
1073 @end table
1074
1075 @c man end OPENCL OPTIONS