utils.texi 21 KB

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