Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
drawvg-reference.html2968 linesDownload Raw Back to doc
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">2<html>3<!-- Created by , GNU Texinfo 7.1.1 -->4  <head>5    <meta charset="utf-8">6    <title>7      drawvg - Language Reference8    </title>9    <meta name="viewport" content="width=device-width,initial-scale=1.0">10    <link rel="stylesheet" type="text/css" href="bootstrap.min.css">11    <link rel="stylesheet" type="text/css" href="style.min.css">12  </head>13  <body>14    <div class="container">15      <h1>16      drawvg - Language Reference17      </h1>18 19 20<a name="SEC_Top"></a>21 22<div class="element-contents" id="SEC_Contents">23<h2 class="contents-heading">Table of Contents</h2>24 25<div class="contents">26 27<ul class="toc-numbered-mark">28  <li><a id="toc-Introduction" href="#Introduction">1 Introduction</a></li>29  <li><a id="toc-Syntax" href="#Syntax">2 Syntax</a>30  <ul class="toc-numbered-mark">31    <li><a id="toc-Structure" href="#Structure">2.1 Structure</a></li>32    <li><a id="toc-Comments" href="#Comments">2.2 Comments</a></li>33    <li><a id="toc-Commands" href="#Commands">2.3 Commands</a>34    <ul class="toc-numbered-mark">35      <li><a id="toc-Single_002dLetter-Aliases" href="#Single_002dLetter-Aliases">2.3.1 Single-Letter Aliases</a></li>36      <li><a id="toc-Implicit-Commands" href="#Implicit-Commands">2.3.2 Implicit Commands</a></li>37    </ul></li>38    <li><a id="toc-Arguments" href="#Arguments">2.4 Arguments</a>39    <ul class="toc-numbered-mark">40      <li><a id="toc-Number-Literals" href="#Number-Literals">2.4.1 Number Literals</a></li>41      <li><a id="toc-Expressions" href="#Expressions">2.4.2 Expressions</a></li>42      <li><a id="toc-Variable-Names" href="#Variable-Names">2.4.3 Variable Names</a></li>43      <li><a id="toc-Colors-1" href="#Colors-1">2.4.4 Colors</a></li>44      <li><a id="toc-Constants" href="#Constants">2.4.5 Constants</a></li>45    </ul></li>46  </ul></li>47  <li><a id="toc-Guide" href="#Guide">3 Guide</a>48  <ul class="toc-numbered-mark">49    <li><a id="toc-Paths" href="#Paths">3.1 Paths</a>50    <ul class="toc-numbered-mark">51      <li><a id="toc-Current-Point" href="#Current-Point">3.1.1 Current Point</a></li>52      <li><a id="toc-Defining-a-Shape" href="#Defining-a-Shape">3.1.2 Defining a Shape</a></li>53      <li><a id="toc-Fill" href="#Fill">3.1.3 Fill</a></li>54      <li><a id="toc-Stroke" href="#Stroke">3.1.4 Stroke</a></li>55      <li><a id="toc-Clip" href="#Clip">3.1.5 Clip</a></li>56      <li><a id="toc-Preserving-Paths" href="#Preserving-Paths">3.1.6 Preserving Paths</a></li>57    </ul></li>58    <li><a id="toc-Variables" href="#Variables">3.2 Variables</a>59    <ul class="toc-numbered-mark">60      <li><a id="toc-User-Variables-1" href="#User-Variables-1">3.2.1 User Variables</a></li>61    </ul></li>62    <li><a id="toc-Patterns" href="#Patterns">3.3 Patterns</a>63    <ul class="toc-numbered-mark">64      <li><a id="toc-Gradients" href="#Gradients">3.3.1 Gradients</a></li>65      <li><a id="toc-Variables-1" href="#Variables-1">3.3.2 Variables</a></li>66    </ul></li>67    <li><a id="toc-Transformations" href="#Transformations">3.4 Transformations</a></li>68    <li><a id="toc-State-Stack-1" href="#State-Stack-1">3.5 State Stack</a></li>69    <li><a id="toc-Frame-Metadata-1" href="#Frame-Metadata-1">3.6 Frame Metadata</a></li>70    <li><a id="toc-if-_002f-repeat-Statements" href="#if-_002f-repeat-Statements">3.7 <code class="code">if</code> / <code class="code">repeat</code> Statements</a>71    <ul class="toc-numbered-mark">72      <li><a id="toc-Comparison-and-Logical-Operators" href="#Comparison-and-Logical-Operators">3.7.1 Comparison and Logical Operators</a></li>73      <li><a id="toc-Early-Exit" href="#Early-Exit">3.7.2 Early Exit</a></li>74    </ul></li>75    <li><a id="toc-Procedures-1" href="#Procedures-1">3.8 Procedures</a></li>76    <li><a id="toc-Functions-in-Expressions" href="#Functions-in-Expressions">3.9 Functions in Expressions</a>77    <ul class="toc-numbered-mark">78      <li><a id="toc-Function-p" href="#Function-p">3.9.1 Function <code class="code">p</code></a></li>79      <li><a id="toc-Function-pathlen" href="#Function-pathlen">3.9.2 Function <code class="code">pathlen</code></a></li>80      <li><a id="toc-Function-randomg" href="#Function-randomg">3.9.3 Function <code class="code">randomg</code></a></li>81    </ul></li>82    <li><a id="toc-Tracing-with-print" href="#Tracing-with-print">3.10 Tracing with <code class="code">print</code></a>83    <ul class="toc-numbered-mark">84      <li><a id="toc-Function-print" href="#Function-print">3.10.1 Function print</a></li>85      <li><a id="toc-Command-print-1" href="#Command-print-1">3.10.2 Command <code class="code">print</code></a></li>86    </ul></li>87  </ul></li>88  <li><a id="toc-Commands-1" href="#Commands-1">4 Commands</a>89  <ul class="toc-numbered-mark">90    <li><a id="toc-arc" href="#arc">4.1 <code class="code">arc</code></a></li>91    <li><a id="toc-arcn" href="#arcn">4.2 <code class="code">arcn</code></a></li>92    <li><a id="toc-break" href="#break">4.3 <code class="code">break</code></a></li>93    <li><a id="toc-call" href="#call">4.4 <code class="code">call</code></a></li>94    <li><a id="toc-circle" href="#circle">4.5 <code class="code">circle</code></a></li>95    <li><a id="toc-clip_002c-eoclip" href="#clip_002c-eoclip">4.6 <code class="code">clip</code>, <code class="code">eoclip</code></a></li>96    <li><a id="toc-Z_002c-z_002c-closepath" href="#Z_002c-z_002c-closepath">4.7 <code class="code">Z</code>, <code class="code">z</code>, <code class="code">closepath</code></a></li>97    <li><a id="toc-colorstop" href="#colorstop">4.8 <code class="code">colorstop</code></a></li>98    <li><a id="toc-C_002c-curveto" href="#C_002c-curveto">4.9 <code class="code">C</code>, <code class="code">curveto</code></a></li>99    <li><a id="toc-c_002c-rcurveto" href="#c_002c-rcurveto">4.10 <code class="code">c</code>, <code class="code">rcurveto</code></a></li>100    <li><a id="toc-defhsla" href="#defhsla">4.11 <code class="code">defhsla</code></a></li>101    <li><a id="toc-defrgba" href="#defrgba">4.12 <code class="code">defrgba</code></a></li>102    <li><a id="toc-ellipse" href="#ellipse">4.13 <code class="code">ellipse</code></a></li>103    <li><a id="toc-fill_002c-eofill" href="#fill_002c-eofill">4.14 <code class="code">fill</code>, <code class="code">eofill</code></a></li>104    <li><a id="toc-getmetadata" href="#getmetadata">4.15 <code class="code">getmetadata</code></a></li>105    <li><a id="toc-H_002c-h" href="#H_002c-h">4.16 <code class="code">H</code>, <code class="code">h</code></a></li>106    <li><a id="toc-if" href="#if">4.17 <code class="code">if</code></a></li>107    <li><a id="toc-lineargrad" href="#lineargrad">4.18 <code class="code">lineargrad</code></a></li>108    <li><a id="toc-L_002c-lineto" href="#L_002c-lineto">4.19 <code class="code">L</code>, <code class="code">lineto</code></a></li>109    <li><a id="toc-l_002c-rlineto" href="#l_002c-rlineto">4.20 <code class="code">l</code>, <code class="code">rlineto</code></a></li>110    <li><a id="toc-M_002c-moveto" href="#M_002c-moveto">4.21 <code class="code">M</code>, <code class="code">moveto</code></a></li>111    <li><a id="toc-m_002c-rmoveto" href="#m_002c-rmoveto">4.22 <code class="code">m</code>, <code class="code">rmoveto</code></a></li>112    <li><a id="toc-newpath" href="#newpath">4.23 <code class="code">newpath</code></a></li>113    <li><a id="toc-preserve" href="#preserve">4.24 <code class="code">preserve</code></a></li>114    <li><a id="toc-print" href="#print">4.25 <code class="code">print</code></a></li>115    <li><a id="toc-proc" href="#proc">4.26 <code class="code">proc</code></a></li>116    <li><a id="toc-Q" href="#Q">4.27 <code class="code">Q</code></a></li>117    <li><a id="toc-q" href="#q">4.28 <code class="code">q</code></a></li>118    <li><a id="toc-radialgrad" href="#radialgrad">4.29 <code class="code">radialgrad</code></a></li>119    <li><a id="toc-rect" href="#rect">4.30 <code class="code">rect</code></a></li>120    <li><a id="toc-repeat" href="#repeat">4.31 <code class="code">repeat</code></a></li>121    <li><a id="toc-resetclip" href="#resetclip">4.32 <code class="code">resetclip</code></a></li>122    <li><a id="toc-resetdash" href="#resetdash">4.33 <code class="code">resetdash</code></a></li>123    <li><a id="toc-resetmatrix" href="#resetmatrix">4.34 <code class="code">resetmatrix</code></a></li>124    <li><a id="toc-restore" href="#restore">4.35 <code class="code">restore</code></a></li>125    <li><a id="toc-rotate" href="#rotate">4.36 <code class="code">rotate</code></a></li>126    <li><a id="toc-roundedrect" href="#roundedrect">4.37 <code class="code">roundedrect</code></a></li>127    <li><a id="toc-save" href="#save">4.38 <code class="code">save</code></a></li>128    <li><a id="toc-scale" href="#scale">4.39 <code class="code">scale</code></a></li>129    <li><a id="toc-scalexy" href="#scalexy">4.40 <code class="code">scalexy</code></a></li>130    <li><a id="toc-setcolor" href="#setcolor">4.41 <code class="code">setcolor</code></a></li>131    <li><a id="toc-setdash" href="#setdash">4.42 <code class="code">setdash</code></a></li>132    <li><a id="toc-setdashoffset" href="#setdashoffset">4.43 <code class="code">setdashoffset</code></a></li>133    <li><a id="toc-sethsla" href="#sethsla">4.44 <code class="code">sethsla</code></a></li>134    <li><a id="toc-setlinecap" href="#setlinecap">4.45 <code class="code">setlinecap</code></a></li>135    <li><a id="toc-setlinejoin" href="#setlinejoin">4.46 <code class="code">setlinejoin</code></a></li>136    <li><a id="toc-setlinewidth" href="#setlinewidth">4.47 <code class="code">setlinewidth</code></a></li>137    <li><a id="toc-setrgba" href="#setrgba">4.48 <code class="code">setrgba</code></a></li>138    <li><a id="toc-setvar" href="#setvar">4.49 <code class="code">setvar</code></a></li>139    <li><a id="toc-stroke" href="#stroke">4.50 <code class="code">stroke</code></a></li>140    <li><a id="toc-S_002c-s" href="#S_002c-s">4.51 <code class="code">S</code>, <code class="code">s</code></a></li>141    <li><a id="toc-translate" href="#translate">4.52 <code class="code">translate</code></a></li>142    <li><a id="toc-T_002c-t" href="#T_002c-t">4.53 <code class="code">T</code>, <code class="code">t</code></a></li>143    <li><a id="toc-V_002c-v" href="#V_002c-v">4.54 <code class="code">V</code>, <code class="code">v</code></a></li>144  </ul></li>145</ul>146</div>147</div>148 149 150 151<a name="Introduction"></a>152<h2 class="chapter">1 Introduction<span class="pull-right"><a class="anchor hidden-xs" href="#Introduction" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Introduction" aria-hidden="true">TOC</a></span></h2>153 154<p>drawvg (<em class="emph">draw vector graphics</em>) is a language to draw155two-dimensional graphics on top of video frames. It is not intended to156be used as a general-purpose language. Since its scope is limited, it157prioritizes being concise and easy to use.158</p>159<p>For example, using the160<a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API">Canvas161API</a> we can render a triangle running this code in a Web browser:162</p>163<div class="example">164<pre class="example-preformatted">const canvas = document.getElementById(&quot;canvas&quot;);165const ctx = canvas.getContext(&quot;2d&quot;);166 167ctx.beginPath();168ctx.moveTo(125, 50);169ctx.lineTo(100, 100);170ctx.lineTo(150, 100);171ctx.closePath();172ctx.stroke();173</pre></div>174 175<p>The same triangle can be written with this drawvg script:176</p>177<div class="example">178<pre class="example-preformatted">moveto 125 50179lineto 100 100 150 100180closepath181stroke182</pre></div>183 184<p>It can be shortened using the aliases for <a class="ref" href="#cmd_005fmoveto"><code class="code">moveto</code></a>, <a class="ref" href="#cmd_005flineto"><code class="code">lineto</code></a>,185and <a class="ref" href="#cmd_005fclosepath"><code class="code">closepath</code></a>:186</p>187<div class="example">188<pre class="example-preformatted">M 125 50189L 100 100 150 100190Z191stroke192</pre></div>193 194<p>Both newlines (<code class="code">U+000A</code>) and spaces (<code class="code">U+0020</code>) can be used195interchangeably as delimiters, so multiple commands can appear on the196same line:197</p>198<div class="example">199<pre class="example-preformatted">M 125 50 L 100 100 150 100 Z200stroke201</pre></div>202 203 204<p>Finally, drawvg can use <a data-manual="ffmpeg-utils" href="ffmpeg-utils.html#Expression-Evaluation">FFmpeg expressions</a> and frame metadata in command arguments. In205this example, we are using the variables <var class="var">w</var> (frame width) and <var class="var">h</var>206(frame height) to create a circle in the middle of the frame.207</p>208<div class="example">209<pre class="example-preformatted">circle (w / 2) (h / 2) (w / 3)210stroke211</pre></div>212 213<p>Many commands are a direct equivalent to a function in the214<a class="uref" href="https://www.cairographics.org/">Cairo graphics library</a>. For such215commands, the reference below provides a link to the related Cairo216documentation.217</p>218<a name="Syntax"></a>219<h2 class="chapter">2 Syntax<span class="pull-right"><a class="anchor hidden-xs" href="#Syntax" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Syntax" aria-hidden="true">TOC</a></span></h2>220 221 222<p>The syntax is heavily inspired by languages like223<a class="uref" href="https://imagemagick.org/script/magick-vector-graphics.php">Magick224Vector Graphics</a>, or <a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a>. Many command names are taken from225<a class="uref" href="https://en.wikipedia.org/wiki/PostScript">PostScript</a>.226</p>227<a name="Structure"></a>228<h3 class="section">2.1 Structure<span class="pull-right"><a class="anchor hidden-xs" href="#Structure" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Structure" aria-hidden="true">TOC</a></span></h3>229 230<p>A drawvg script consists of a series of commands to describe 2D231graphics.232</p>233<p>A command is an identifier (like <a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a> or <a class="ref" href="#cmd_005flineto"><code class="code">lineto</code></a>)234followed by its arguments. Each item in the code (command name,235arguments, etc.) is separated by any of the following characters:236</p>237<ul class="itemize mark-bullet">238<li>Space (<code class="code">' '</code>)239</li><li>Comma (<code class="code">','</code>)240</li><li>Newline (<code class="code">'\n'</code>)241</li><li>Tabs (<code class="code">'\t'</code>)242</li><li>Return (<code class="code">'\r'</code>)243</li></ul>244 245<p>The beginning of the item indicates how it will be interpreted:246</p>247<dl class="table">248<dt><span class="r"><code class="code">//</code></span></dt>249<dd><p>Comment250</p></dd>251<dt><span class="r"><code class="code">0</code>, &hellip;, <code class="code">9</code>, <code class="code">+</code>, <code class="code">-</code></span></dt>252<dd><p>Number literal253</p></dd>254<dt><span class="r"><code class="code">(</code></span></dt>255<dd><p>Expression256</p></dd>257<dt><span class="r"><code class="code">{</code>, <code class="code">}</code></span></dt>258<dd><p>Block delimiters259</p></dd>260<dt><span class="r">Anything else</span></dt>261<dd><p>Name of a command, a color, etc.262</p></dd>263</dl>264 265<a name="Comments"></a>266<h3 class="section">2.2 Comments<span class="pull-right"><a class="anchor hidden-xs" href="#Comments" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Comments" aria-hidden="true">TOC</a></span></h3>267 268<p>Comments start with two slashes (<code class="code">//</code>), and stop at the end of the269line (either a <code class="code">\n</code>, or the end of the script).270</p>271<div class="example">272<pre class="example-preformatted">circle 100 100 50 // this is ignored273fill274 275// this is also ignored276</pre></div>277 278<p><code class="code">//</code> must appear after a space, or at the beginning of the line. If279<code class="code">//</code> is preceded by any non-blank character, the parser will280consider <code class="code">//</code> as part of the previous item.281</p>282<p>For example, in this script:283</p>284<div class="example">285<pre class="example-preformatted">circle 10 10 50// something286</pre></div>287 288<p>The parser throws an error because it tries to parse <code class="code">50//</code> as a289number literal.290</p>291<a name="Commands"></a>292<h3 class="section">2.3 Commands<span class="pull-right"><a class="anchor hidden-xs" href="#Commands" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Commands" aria-hidden="true">TOC</a></span></h3>293 294<p>The way commands are parsed is inspired by <a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a>:295</p>296<ul class="itemize mark-bullet">297<li>Every command in the script starts with its name, and it is followed by298zero or more arguments.299 300</li><li>There are no explicit delimiters between commands or arguments.301 302<p>Most programming languages expect characters like parenthesis, commas,303or semicolons, to separate items. For example:304</p>305<div class="example">306<pre class="example-preformatted">moveto(10, 10); lineto(20, 30);307</pre></div>308 309<p>The equivalent in drawvg is:310</p>311<div class="example">312<pre class="example-preformatted">moveto 10 10 lineto 20 30313</pre></div>314 315</li><li>If the command has no arguments (like <a class="ref" href="#cmd_005fclosepath"><code class="code">closepath</code></a> or316<a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a>), the next command starts at the next item.317 318</li></ul>319 320<table class="cartouche" border="1"><tr><th>321Example</th></tr><tr><td>322<p>In the next script there are 4 different commands:323</p>324<div class="example">325<pre class="example-preformatted">newpath rect 10 20 30 40 setcolor teal fill326</pre></div>327 328<ol class="enumerate">329<li> <a class="ref" href="#cmd_005fnewpath"><code class="code">newpath</code></a> requires no arguments.330 331</li><li> <a class="ref" href="#cmd_005frect"><code class="code">rect</code></a> requires 4 arguments, so it takes the next 4 numbers.332 333</li><li> <a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a> requires 1 argument, so it takes the word <code class="code">teal</code>.334 335</li><li> <a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a> requires no arguments.336</li></ol>337 338</td></tr></table>339 340<a name="Single_002dLetter-Aliases"></a>341<h4 class="subsection">2.3.1 Single-Letter Aliases<span class="pull-right"><a class="anchor hidden-xs" href="#Single_002dLetter-Aliases" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Single_002dLetter-Aliases" aria-hidden="true">TOC</a></span></h4>342 343<p>Most commands in <a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a> are also present in drawvg. For some of them,344there is an alias to a longer name:345</p>346<ul class="itemize mark-bullet">347<li><a class="ref" href="#cmd_005fcurveto"><code class="code">curveto</code></a> for <a class="ref" href="#cmd_005fC"><code class="code">C</code></a>.348</li><li><a class="ref" href="#cmd_005frcurveto"><code class="code">rcurveto</code></a> for <a class="ref" href="#cmd_005fc"><code class="code">c</code></a>.349</li><li><a class="ref" href="#cmd_005flineto"><code class="code">lineto</code></a> for <a class="ref" href="#cmd_005fL"><code class="code">L</code></a>.350</li><li><a class="ref" href="#cmd_005frlineto"><code class="code">rlineto</code></a> for <a class="ref" href="#cmd_005fl"><code class="code">l</code></a>.351</li><li><a class="ref" href="#cmd_005fmoveto"><code class="code">moveto</code></a> for <a class="ref" href="#cmd_005fM"><code class="code">M</code></a>.352</li><li><a class="ref" href="#cmd_005frmoveto"><code class="code">rmoveto</code></a> for <a class="ref" href="#cmd_005fm"><code class="code">m</code></a>.353</li><li><a class="ref" href="#cmd_005fclosepath"><code class="code">closepath</code></a> for <a class="ref" href="#cmd_005fZ"><code class="code">Z</code></a>, <a class="ref" href="#cmd_005fz"><code class="code">z</code></a>.354</li></ul>355 356<p>Other commands only exist in a single-letter form:357</p>358<ul class="itemize mark-bullet">359<li><a class="ref" href="#cmd_005fH"><code class="code">H</code></a>, <a class="ref" href="#cmd_005fh"><code class="code">h</code></a>360</li><li><a class="ref" href="#cmd_005fQ"><code class="code">Q</code></a>, <a class="ref" href="#cmd_005fq"><code class="code">q</code></a>361</li><li><a class="ref" href="#cmd_005fS"><code class="code">S</code></a>, <a class="ref" href="#cmd_005fs"><code class="code">s</code></a>362</li><li><a class="ref" href="#cmd_005fV"><code class="code">V</code></a>, <a class="ref" href="#cmd_005fv"><code class="code">v</code></a>363</li><li><a class="ref" href="#cmd_005fT"><code class="code">T</code></a>, <a class="ref" href="#cmd_005ft"><code class="code">t</code></a>364</li></ul>365 366<p>This makes it possible to use a path in SVG to create the same shape in367a drawvg script.368</p>369<a class="anchor" id="implicit-commands"></a><a name="Implicit-Commands"></a>370<h4 class="subsection">2.3.2 Implicit Commands<span class="pull-right"><a class="anchor hidden-xs" href="#Implicit-Commands" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Implicit-Commands" aria-hidden="true">TOC</a></span></h4>371 372<p>For many commands, the name can be omitted when it is used multiple373times in successive calls.374</p>375<p>In the reference below, these commands has a <em class="emph">Can be Implicit</em> note376in their signature.377</p>378<table class="cartouche" border="1"><tr><th>379Example</th></tr><tr><td>380<p>For example, in this script:381</p>382<div class="example">383<pre class="example-preformatted">M 50 50384l 10 10385l 10 -10386l 10 10387l 10 -10388l 10 10389stroke390</pre></div>391 392<p>After the first call to <a class="ref" href="#cmd_005fl"><code class="code">l</code></a> (alias to <a class="ref" href="#cmd_005frlineto"><code class="code">rlineto</code></a>), the command393can be executed without the name, so it can be written as:394</p>395<div class="example">396<pre class="example-preformatted">M 50 50397l 10 10 10 -10 10 10 10 -10 10 10398stroke399</pre></div>400 401</td></tr></table>402 403<p>To reuse the same command (<a class="ref" href="#cmd_005fl"><code class="code">l</code></a>, in the previous example), the404parser checks if the item after the last argument is a numeric value,405like a number literal or a FFmpeg expression.406</p>407<table class="cartouche" border="1"><tr><th>408Example</th></tr><tr><td>409<p>In this example:410</p>411<div class="example">412<pre class="example-preformatted">l 10 20 30 40 stroke413</pre></div>414 415<p><a class="ref" href="#cmd_005fl"><code class="code">l</code></a> requires 2 arguments, and can be implicit, so the parser416performs this operation:417</p>418<ol class="enumerate">419<li> Takes the two next items (<code class="code">10</code> and <code class="code">20</code>) and emits the first420instruction.421 422</li><li> Checks if the item after <code class="code">20</code> is a numeric value. Since it is423<code class="code">30</code>, it takes <code class="code">30</code> and <code class="code">40</code> and emits the second424instruction (<code class="code">l 30 40</code>).425 426</li><li> Checks if the next item after <code class="code">40</code> is a numeric value, but it is a427command (<a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a>), so it stops reusing <a class="ref" href="#cmd_005fl"><code class="code">l</code></a>.428 429</li></ol>430 431</td></tr></table>432 433<p>This is another feature taken from <a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a>. An important difference with434SVG is that the separator between items is always required. In SVG, it can be435omitted in some cases. For example, the expression <code class="code">m1-2</code> is equivalent to436<code class="code">m 1 -2</code> in SVG, but a syntax error in drawvg.437</p>438<a name="Arguments"></a>439<h3 class="section">2.4 Arguments<span class="pull-right"><a class="anchor hidden-xs" href="#Arguments" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Arguments" aria-hidden="true">TOC</a></span></h3>440 441<p>Most commands expect numeric arguments, like number literals, variable442names, or expressions.443</p>444<p><a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a> and <a class="ref" href="#cmd_005fcolorstop"><code class="code">colorstop</code></a> expect a color.445</p>446<p><a class="ref" href="#cmd_005fsetlinecap"><code class="code">setlinecap</code></a> and <a class="ref" href="#cmd_005fsetlinejoin"><code class="code">setlinejoin</code></a> expect a constant value.447</p>448<a name="Number-Literals"></a>449<h4 class="subsection">2.4.1 Number Literals<span class="pull-right"><a class="anchor hidden-xs" href="#Number-Literals" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Number-Literals" aria-hidden="true">TOC</a></span></h4>450 451<p>A number literal is an item in the script that represents a constant452value. Any item that starts with a decimal digit (between <code class="code">0</code> and453<code class="code">9</code>), a <code class="code">-</code> or a <code class="code">+</code>, is interpreted as a number literal.454</p>455<p>The value is parsed with456<a class="uref" href="https://ffmpeg.org/doxygen/trunk/eval_8c.html#a7d21905c92ee5af0bb529d2daf8cb7c3"><code class="code">av_strtod</code></a>.457It supports the prefix <code class="code">0x</code> to write a value with hexadecimal458digits, and459<a class="uref" href="https://ffmpeg.org/ffmpeg-utils.html#:~:text=The%20evaluator%20also%20recognizes%20the%20International%20System%20unit%20prefixes">many460units</a> (like <code class="code">K</code> or <code class="code">GiB</code>).461</p>462<p>In the next example, all literals represent the same value:463</p>464<div class="example">465<pre class="example-preformatted">100004661e446710K4680x2710469</pre></div>470 471<a name="Expressions"></a>472<h4 class="subsection">2.4.2 Expressions<span class="pull-right"><a class="anchor hidden-xs" href="#Expressions" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Expressions" aria-hidden="true">TOC</a></span></h4>473 474<p><a data-manual="ffmpeg-utils" href="ffmpeg-utils.html#Expression-Evaluation">FFmpeg expressions</a> can be used as arguments for any command that expects a numeric475argument. The expression must be enclosed in parenthesis.476</p>477<table class="cartouche" border="1"><tr><th>478Example</th></tr><tr><td>479<p>The variables <var class="var">w</var> and <var class="var">h</var> represent the width and height of the480frame. We can compute the center of the frame by dividing them by <code class="code">2</code>:481</p>482<div class="example">483<pre class="example-preformatted">M (w / 2) (h / 2)484</pre></div>485 486<p>They can also contain parenthesis (to group operations, to call functions,487etc):488</p>489<div class="example">490<pre class="example-preformatted">moveto491    ((w + 10) / 2)      // x492    (h / (2 * cos(t)))  // y493</pre></div>494 495</td></tr></table>496 497<p>The variables <var class="var">n</var> and <var class="var">t</var> can be used to compute a value that changes498over time.499</p>500<table class="cartouche" border="1"><tr><th>501Example</th></tr><tr><td>502<p>To draw a circle oscillating from left to right, we can use an503expression based on <code class="code">sin(t)</code> for the <code class="code">x</code> coordinate:504</p>505<div class="example">506<pre class="example-preformatted">circle507    (w / 2 + sin(2 * t) * w / 4)  // x508    (h / 2)                       // y509    (w / 5)                       // radius510 511stroke512</pre></div>513 514</td></tr></table>515 516<p>Expressions can be split in multiple lines, but they can&rsquo;t contain517comments within them.518</p>519<div class="example">520<pre class="example-preformatted">moveto   // This is a comment.521    (w   // This is part of the expression, not a comment.522     + h)523</pre></div>524 525<a name="Variable-Names"></a>526<h4 class="subsection">2.4.3 Variable Names<span class="pull-right"><a class="anchor hidden-xs" href="#Variable-Names" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Variable-Names" aria-hidden="true">TOC</a></span></h4>527 528<p>When an expression is only a reference to a variable, the parenthesis529can be omitted, and the item is just the variable name.530</p>531<table class="cartouche" border="1"><tr><th>532Example</th></tr><tr><td>533<p>The next 3 expressions are equivalent: in all cases, they create a534rectangle covering the whole frame.535</p>536<div class="example">537<pre class="example-preformatted">rect (0) (0) (w) (h)538 539rect 0 0 w h540 541rect (0) 0 (w) h542</pre></div>543 544</td></tr></table>545 546<p>It is possible to create a variable with the same name of a command, and547then use it as an argument. In the previous example, the item <var class="var">h</var> is a548reference to a variable (frame height), but in other contexts it may be549a command (<a class="ref" href="#cmd_005fh"><code class="code">h</code></a>).550</p>551<p>For <a class="ref" href="#implicit-commands">implicit commands</a>, the parser prioritizes552commands over variable names when it has to determine if the command is553reused.554</p>555<table class="cartouche" border="1"><tr><th>556Example</th></tr><tr><td>557<p>In this example, the variable <var class="var">c</var> is used as the first argument in two558calls to <a class="ref" href="#cmd_005fl"><code class="code">l</code></a>. However, only the first one is valid, because in the559second call the parser recognizes <a class="ref" href="#cmd_005fc"><code class="code">c</code></a> as a command.560</p>561<div class="example">562<pre class="example-preformatted">setvar c 5563l c 10 c 15564</pre></div>565 566<p>This issue can be fixed by surrounding the start of the second call with567parenthesis:568</p>569<div class="example">570<pre class="example-preformatted">setvar c 5571l c 10 (c) 15572</pre></div>573 574</td></tr></table>575 576<a class="anchor" id="Colors"></a><a name="Colors-1"></a>577<h4 class="subsection">2.4.4 Colors<span class="pull-right"><a class="anchor hidden-xs" href="#Colors-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Colors-1" aria-hidden="true">TOC</a></span></h4>578 579<p>The color to stroke and to fill paths can be set with <a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a>.580Its argument has the same syntax for colors in FFmpeg:581</p>582<ul class="itemize mark-bullet">583<li>A <a data-manual="ffmpeg-utils" href="ffmpeg-utils.html#Color">predefined color name</a>.584 585</li><li>In <code class="code">#RRGGBB</code> format.586 587</li><li>Optionally, an <code class="code">@a</code> suffix can be added to set the alpha value,588where <code class="code">a</code> is a number between <code class="code">0</code> and <code class="code">1</code>.589</li></ul>590 591<div class="example">592<pre class="example-preformatted">circle 70 70 60593setcolor #FF0000594fill595 596circle 170 170 60597setcolor blue@0.5598fill599</pre></div>600 601<p>The color can be a variable name. In that case, it must be assigned with602<a class="ref" href="#cmd_005fdefrgba"><code class="code">defrgba</code></a>, <a class="ref" href="#cmd_005fdefhsla"><code class="code">defhsla</code></a>, or <a class="ref" href="#cmd_005fsetvar"><code class="code">setvar</code></a> and a color.603</p>604<div class="example">605<pre class="example-preformatted">circle 70 70 60606setvar CustomGreen #22FF44607setcolor CustomGreen608fill609 610circle 170 170 60611defhsla CustomBlue 200 0.7 0.5 1612setcolor CustomBlue613fill614</pre></div>615 616<p>The commands <a class="ref" href="#cmd_005fsetrgba"><code class="code">setrgba</code></a> and <a class="ref" href="#cmd_005fsethsla"><code class="code">sethsla</code></a> allow setting colors using617expressions. Similar to <a class="ref" href="#cmd_005fdefrgba"><code class="code">defrgba</code></a> and <a class="ref" href="#cmd_005fdefhsla"><code class="code">defhsla</code></a>, but with no618intermediate variable.619</p>620<a name="Constants"></a>621<h4 class="subsection">2.4.5 Constants<span class="pull-right"><a class="anchor hidden-xs" href="#Constants" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Constants" aria-hidden="true">TOC</a></span></h4>622 623<p>The argument for <a class="ref" href="#cmd_005fsetlinecap"><code class="code">setlinecap</code></a> and <a class="ref" href="#cmd_005fsetlinejoin"><code class="code">setlinejoin</code></a> is an624identifier referring to a constant value.625</p>626<div class="example">627<pre class="example-preformatted">setlinecap round628</pre></div>629 630<a name="Guide"></a>631<h2 class="chapter">3 Guide<span class="pull-right"><a class="anchor hidden-xs" href="#Guide" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Guide" aria-hidden="true">TOC</a></span></h2>632 633<a name="Paths"></a>634<h3 class="section">3.1 Paths<span class="pull-right"><a class="anchor hidden-xs" href="#Paths" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Paths" aria-hidden="true">TOC</a></span></h3>635 636<p>A path is a complex shape, composed by lines and curves, that can be637used to fill a region, to stroke an outline, or to establish a clip638region.639</p>640<p>In order to draw anything on top of a video frame, first we have to641define a path, and then use <a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a> or <a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a>.642</p>643<p>The644<a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths">tutorial645on paths in MDN</a> is a good introduction to the topic. It is focused on646<a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a>, but the same concepts can be applied in drawvg.647</p>648<a class="anchor" id="current-point"></a><a name="Current-Point"></a>649<h4 class="subsection">3.1.1 Current Point<span class="pull-right"><a class="anchor hidden-xs" href="#Current-Point" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Current-Point" aria-hidden="true">TOC</a></span></h4>650 651<p>Some commands require a <em class="emph">current point</em>. Initially, the652<em class="emph">current point</em> is set to653<a class="uref" href="https://en.wikipedia.org/wiki/NaN"><code class="code">NaN</code></a>. It is initialized654with <a class="ref" href="#cmd_005fM"><code class="code">M</code></a> or <a class="ref" href="#cmd_005fmoveto"><code class="code">moveto</code></a>. Other commands, like <a class="ref" href="#cmd_005flineto"><code class="code">lineto</code></a> or655<a class="ref" href="#cmd_005fcurveto"><code class="code">curveto</code></a>, updates the <em class="emph">current point</em> to the new end of the656shape.657</p>658<p>The <em class="emph">current point</em> can be cleared with <a class="ref" href="#cmd_005fnewpath"><code class="code">newpath</code></a>. Commands659that clear the path, like <a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a> or <a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a>, also clear the660<em class="emph">current point</em>.661</p>662<table class="cartouche" border="1"><tr><th>663Example</th></tr><tr><td>664<p><a class="ref" href="#cmd_005frlineto"><code class="code">rlineto</code></a> uses coordinates relative to the <em class="emph">current point</em>.665</p>666<p>Given this script:667</p>668<div class="example">669<pre class="example-preformatted">moveto 20 100670rlineto 150 -90671rlineto -50 200672closepath673stroke674</pre></div>675 676<p>These are the coordinates of the <em class="emph">current point</em> after executing677each command:678</p>679<table class="multitable">680<thead><tr><th width="50%">Command</th><th width="50%">Current Point</th></tr></thead>681<tbody><tr><td width="50%"><code class="code">moveto 20 100</code></td><td width="50%"><code class="code">20, 100</code></td></tr>682<tr><td width="50%"><code class="code">rlineto 150 -90</code></td><td width="50%"><code class="code">170, 10</code></td></tr>683<tr><td width="50%"><code class="code">rlineto -10 50</code></td><td width="50%"><code class="code">140, 210</code></td></tr>684<tr><td width="50%"><code class="code">closepath</code></td><td width="50%"><code class="code">20, 100</code></td></tr>685</tbody>686</table>687 688<p>The same script can be written with single-letter aliases:689</p>690<div class="example">691<pre class="example-preformatted">M 20 100 l 150 -90 -50 200 z stroke692</pre></div>693 694</td></tr></table>695 696<a name="Defining-a-Shape"></a>697<h4 class="subsection">3.1.2 Defining a Shape<span class="pull-right"><a class="anchor hidden-xs" href="#Defining-a-Shape" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Defining-a-Shape" aria-hidden="true">TOC</a></span></h4>698 699<p>A path is defined by adding lines, curves, or basic shapes.700</p>701<ul class="itemize mark-bullet">702<li>Basic shapes703 704<ul class="itemize mark-bullet">705<li><a class="ref" href="#cmd_005fcircle"><code class="code">circle</code></a>706</li><li><a class="ref" href="#cmd_005fellipse"><code class="code">ellipse</code></a>707</li><li><a class="ref" href="#cmd_005frect"><code class="code">rect</code></a>708</li><li><a class="ref" href="#cmd_005froundedrect"><code class="code">roundedrect</code></a>709</li></ul>710 711</li><li>Lines712<ul class="itemize mark-bullet">713<li><a class="ref" href="#cmd_005fM"><code class="code">M</code></a>, <a class="ref" href="#cmd_005fmoveto"><code class="code">moveto</code></a>714</li><li><a class="ref" href="#cmd_005fm"><code class="code">m</code></a>, <a class="ref" href="#cmd_005frmoveto"><code class="code">rmoveto</code></a>715</li><li><a class="ref" href="#cmd_005fH"><code class="code">H</code></a>, <a class="ref" href="#cmd_005fh"><code class="code">h</code></a>716</li><li><a class="ref" href="#cmd_005fV"><code class="code">V</code></a>, <a class="ref" href="#cmd_005fv"><code class="code">v</code></a>717</li><li><a class="ref" href="#cmd_005fL"><code class="code">L</code></a>, <a class="ref" href="#cmd_005flineto"><code class="code">lineto</code></a>718</li><li><a class="ref" href="#cmd_005fl"><code class="code">l</code></a>, <a class="ref" href="#cmd_005frlineto"><code class="code">rlineto</code></a>719</li><li><a class="ref" href="#cmd_005fZ"><code class="code">Z</code></a>, <a class="ref" href="#cmd_005fz"><code class="code">z</code></a>, <a class="ref" href="#cmd_005fclosepath"><code class="code">closepath</code></a>720</li></ul>721 722</li><li>Curves723<ul class="itemize mark-bullet">724<li><a class="ref" href="#cmd_005farc"><code class="code">arc</code></a>, <a class="ref" href="#cmd_005farcn"><code class="code">arcn</code></a>725</li><li><a class="ref" href="#cmd_005fC"><code class="code">C</code></a>, <a class="ref" href="#cmd_005fcurveto"><code class="code">curveto</code></a>,726</li><li><a class="ref" href="#cmd_005fc"><code class="code">c</code></a>, <a class="ref" href="#cmd_005frcurveto"><code class="code">rcurveto</code></a>727</li><li><a class="ref" href="#cmd_005fQ"><code class="code">Q</code></a>, <a class="ref" href="#cmd_005fq"><code class="code">q</code></a>728</li><li><a class="ref" href="#cmd_005fS"><code class="code">S</code></a>, <a class="ref" href="#cmd_005fs"><code class="code">s</code></a>729</li><li><a class="ref" href="#cmd_005fT"><code class="code">T</code></a>, <a class="ref" href="#cmd_005ft"><code class="code">t</code></a>730</li></ul>731 732</li></ul>733 734<p>Single-letter commands are taken from <a class="uref" href="https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/path">SVG&rsquo;s <code class="code">&lt;path&gt;</code></a>.735</p>736<a class="anchor" id="fill-rules"></a><a name="Fill"></a>737<h4 class="subsection">3.1.3 Fill<span class="pull-right"><a class="anchor hidden-xs" href="#Fill" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Fill" aria-hidden="true">TOC</a></span></h4>738 739<p>The region within the shape defined by a path can be filled with740<a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a> or <a class="ref" href="#cmd_005feofill"><code class="code">eofill</code></a>. Each command uses a different741<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#cairo-fill-rule-t">fill742rule</a>:743</p>744<ul class="itemize mark-bullet">745<li><a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a> uses the746<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#CAIRO-FILL-RULE-WINDING:CAPS">winding747rule</a>, also known as748<a class="uref" href="https://en.wikipedia.org/wiki/Nonzero-rule">nonzero rule</a>.749</li><li><a class="ref" href="#cmd_005feofill"><code class="code">eofill</code></a> uses the750<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#CAIRO-FILL-RULE-EVEN-ODD:CAPS">even&ndash;odd751rule</a>.752</li></ul>753 754<table class="cartouche" border="1"><tr><th>755Example</th></tr><tr><td>756<p>This script shows the difference between the757<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#CAIRO-FILL-RULE-WINDING:CAPS">winding</a>758and759<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#CAIRO-FILL-RULE-EVEN-ODD:CAPS">even&ndash;odd</a>760rules:761</p>762<div class="example">763<pre class="example-preformatted">rect 50 10 100 60764circle 150 70 40765setcolor seagreen766fill767 768rect 50 130 100 60769circle 150 190 40770setcolor skyblue771eofill772</pre></div>773 774</td></tr></table>775 776<a name="Stroke"></a>777<h4 class="subsection">3.1.4 Stroke<span class="pull-right"><a class="anchor hidden-xs" href="#Stroke" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Stroke" aria-hidden="true">TOC</a></span></h4>778 779<p><a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a> draws a line around the shape defined by the path. The780stroke can be configured with different commands:781</p>782<ul class="itemize mark-bullet">783<li><a class="ref" href="#cmd_005fsetdash"><code class="code">setdash</code></a>784</li><li><a class="ref" href="#cmd_005fsetdashoffset"><code class="code">setdashoffset</code></a>785</li><li><a class="ref" href="#cmd_005fsetlinecap"><code class="code">setlinecap</code></a>786</li><li><a class="ref" href="#cmd_005fsetlinejoin"><code class="code">setlinejoin</code></a>787</li><li><a class="ref" href="#cmd_005fsetlinewidth"><code class="code">setlinewidth</code></a>788</li><li><a class="ref" href="#cmd_005fresetdash"><code class="code">resetdash</code></a>789</li></ul>790 791<table class="cartouche" border="1"><tr><th>792Example</th></tr><tr><td>793<p>This example use <a class="ref" href="#cmd_005fsetdashoffset"><code class="code">setdashoffset</code></a> to animate the stroke:794</p>795<div class="example">796<pre class="example-preformatted">moveto 0 0797lineto w h798 799setlinecap round800setdash 50 50801setlinewidth 20802setdashoffset (hypot(w, h) * t / -3)803setcolor seagreen804 805stroke806</pre></div>807 808</td></tr></table>809 810<a name="Clip"></a>811<h4 class="subsection">3.1.5 Clip<span class="pull-right"><a class="anchor hidden-xs" href="#Clip" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Clip" aria-hidden="true">TOC</a></span></h4>812 813<p>A <a class="uref" href="https://en.wikipedia.org/wiki/Clipping_(computer_graphics)">clip814region</a> can be established with <a class="ref" href="#cmd_005fclip"><code class="code">clip</code></a> and <a class="ref" href="#cmd_005feoclip"><code class="code">eoclip</code></a>.815</p>816<p>If there is an active clip region, the new clip region will be the817intersection between the existing one and the path. <a class="ref" href="#cmd_005fresetclip"><code class="code">resetclip</code></a>818reset the clip region to the whole frame.819</p>820<p><a class="ref" href="#cmd_005feoclip"><code class="code">eoclip</code></a> uses the821<a class="uref" href="https://www.cairographics.org/manual/cairo-cairo-t.html#CAIRO-FILL-RULE-EVEN-ODD:CAPS">even&ndash;odd822rule</a> to compute the clip region.823</p>824<table class="cartouche" border="1"><tr><th>825Example</th></tr><tr><td>826<div class="example">827<pre class="example-preformatted">rect 50 50 100 200828clip829 830circle 30 30 150831setcolor seagreen832fill833 834// Draw outside the clip region.835resetclip836circle 30 30 150837setlinewidth 3838setcolor skyblue839stroke840</pre></div>841 842</td></tr></table>843 844<a name="Preserving-Paths"></a>845<h4 class="subsection">3.1.6 Preserving Paths<span class="pull-right"><a class="anchor hidden-xs" href="#Preserving-Paths" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Preserving-Paths" aria-hidden="true">TOC</a></span></h4>846 847<p>The path is cleared after any operation on it, like <a class="ref" href="#cmd_005ffill"><code class="code">fill</code></a> or848<a class="ref" href="#cmd_005fstroke"><code class="code">stroke</code></a>. To reuse the same path in multiple operations,849<a class="ref" href="#cmd_005fpreserve"><code class="code">preserve</code></a> must be called before them.850</p>851<table class="cartouche" border="1"><tr><th>852Example</th></tr><tr><td>853<p>In this example, each path is used twice.854</p>855<div class="example">856<pre class="example-preformatted">circle 120 120 50857setcolor seagreen858preserve stroke859clip860 861circle 100 100 50862setcolor skyblue863preserve fill864setcolor tomato865stroke866</pre></div>867 868</td></tr></table>869 870<a name="Variables"></a>871<h3 class="section">3.2 Variables<span class="pull-right"><a class="anchor hidden-xs" href="#Variables" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Variables" aria-hidden="true">TOC</a></span></h3>872 873<p>A drawvg can use some variables, provided by the interpreter, to compute874values in <a data-manual="ffmpeg-utils" href="ffmpeg-utils.html#Expression-Evaluation">FFmpeg expressions</a>:875</p>876<dl class="table">877<dt><var class="var">cx</var></dt>878<dd><p>X coordinate of the <a class="ref" href="#current-point">current point</a>.879</p>880</dd>881<dt><var class="var">cy</var></dt>882<dd><p>Y coordinate of the <a class="ref" href="#current-point">current point</a>.883</p>884</dd>885<dt><var class="var">w</var></dt>886<dd><p>Width, in pixels, of the frame.887</p>888</dd>889<dt><var class="var">h</var></dt>890<dd><p>Height, in pixels, of the frame.891</p>892</dd>893<dt><var class="var">i</var></dt>894<dd><p>The loop counter in repeat blocks.895</p>896</dd>897<dt><var class="var">n</var></dt>898<dd><p>Frame number.899</p>900</dd>901<dt><var class="var">t</var></dt>902<dd><p>Timestamp, in seconds.903</p>904</dd>905<dt><var class="var">ts</var></dt>906<dd><p>Timestamp, in seconds, of the first frame.907</p>908</dd>909<dt><var class="var">duration</var></dt>910<dd><p>Duration, in seconds, of the frame.911</p></dd>912</dl>913 914<a class="anchor" id="User-Variables"></a><a name="User-Variables-1"></a>915<h4 class="subsection">3.2.1 User Variables<span class="pull-right"><a class="anchor hidden-xs" href="#User-Variables-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-User-Variables-1" aria-hidden="true">TOC</a></span></h4>916 917<p>New variables can be created with the <a class="ref" href="#cmd_005fsetvar"><code class="code">setvar</code></a> command. It918associates a name with a numeric value.919</p>920<p>The name must follow these rules:921</p>922<ul class="itemize mark-bullet">923<li>It must start with an ASCII letter or an underscore (<code class="code">_</code>).924 925</li><li>It can contain only ASCII letters, underscores, and digits.926 927</li><li>It must not match the name of a variable provided by the interpreter928(like <var class="var">w</var> or <var class="var">t</var>).929</li></ul>930 931<p>The same variable can be assigned multiple times.932</p>933<table class="cartouche" border="1"><tr><th>934Example</th></tr><tr><td>935<p>In this example, the result of an expression is stored in a variable936with the name <var class="var">progress</var>. Then, it is used for the <var class="var">x</var> and937<var class="var">width</var> arguments of <a class="ref" href="#cmd_005frect"><code class="code">rect</code></a>.938</p>939<div class="example">940<pre class="example-preformatted">setvar progress (w * (pow(mod(t / 2 + 0.5, 1), 2.5)))941 942rect ((w - progress) / 2) 0 progress h943 944setcolor darkblue945fill946</pre></div>947 948</td></tr></table>949 950<p>Currently, a script can contain only 20 different variable names, but951this limit can be modified in the future.952</p>953<a class="anchor" id="current-pattern"></a><a name="Patterns"></a>954<h3 class="section">3.3 Patterns<span class="pull-right"><a class="anchor hidden-xs" href="#Patterns" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Patterns" aria-hidden="true">TOC</a></span></h3>955 956<p>The pattern for fill and stroke operations can be either a solid color,957or a gradient.958</p>959<ul class="itemize mark-bullet">960<li>Solid colors.961 962<ul class="itemize mark-bullet">963<li><a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a>964</li><li><a class="ref" href="#cmd_005fsethsla"><code class="code">sethsla</code></a>965</li><li><a class="ref" href="#cmd_005fsetrgba"><code class="code">setrgba</code></a>966</li></ul>967 968</li><li>Gradients.969 970<ul class="itemize mark-bullet">971<li><a class="ref" href="#cmd_005flineargrad"><code class="code">lineargrad</code></a>972</li><li><a class="ref" href="#cmd_005fradialgrad"><code class="code">radialgrad</code></a>973</li></ul>974 975</li></ul>976 977<p>The pattern is not cleared after being used in a fill or stroke978operation, but it is replaced by any command that sets a new pattern.979</p>980<a name="Gradients"></a>981<h4 class="subsection">3.3.1 Gradients<span class="pull-right"><a class="anchor hidden-xs" href="#Gradients" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Gradients" aria-hidden="true">TOC</a></span></h4>982 983<p>To configure a gradient, first call to <a class="ref" href="#cmd_005flineargrad"><code class="code">lineargrad</code></a> or984<a class="ref" href="#cmd_005fradialgrad"><code class="code">radialgrad</code></a>, and then add color stops by calling <a class="ref" href="#cmd_005fcolorstop"><code class="code">colorstop</code></a>985for each stop.986</p>987<table class="cartouche" border="1"><tr><th>988Example</th></tr><tr><td>989<p>In this example, the whole frame is filled with a linear gradient:990</p>991<div class="example">992<pre class="example-preformatted">lineargrad 0 0 w h993colorstop 0 skyblue994colorstop 1 darkblue995 996rect 0 0 w h997fill998</pre></div>999 1000<p>In this example, a radial gradient is used to simulate a sphere:1001</p>1002<div class="example">1003<pre class="example-preformatted">radialgrad 90 90 5 120 120 1001004colorstop 0.0 #90DDFF1005colorstop 0.9 #0000301006colorstop 1.0 #0000001007 1008rect 0 0 w h1009fill1010</pre></div>1011 1012</td></tr></table>1013 1014<a name="Variables-1"></a>1015<h4 class="subsection">3.3.2 Variables<span class="pull-right"><a class="anchor hidden-xs" href="#Variables-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Variables-1" aria-hidden="true">TOC</a></span></h4>1016 1017<p><a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a> and <a class="ref" href="#cmd_005fcolorstop"><code class="code">colorstop</code></a> accept a variable name as the1018argument. The variable must be assigned with <a class="ref" href="#cmd_005fdefrgba"><code class="code">defrgba</code></a>,1019<a class="ref" href="#cmd_005fdefhsla"><code class="code">defhsla</code></a>, or <a class="ref" href="#cmd_005fsetvar"><code class="code">setvar</code></a> and a color.1020</p>1021<table class="cartouche" border="1"><tr><th>1022Example</th></tr><tr><td>1023<div class="example">1024<pre class="example-preformatted">// Use color #1020FF, alpha = 50%1025setvar someblue #1020FF@0.51026 1027setcolor someblue1028 1029rect 30 30 120 1201030fill1031 1032rect 90 90 120 1201033fill1034</pre></div>1035 1036</td></tr></table>1037 1038<p>If a variable has the same name of a <a data-manual="ffmpeg-utils" href="ffmpeg-utils.html#Color">known color</a>, the1039variable has preference, and will be used instead of the predefined color.1040</p>1041<table class="cartouche" border="1"><tr><th>1042Example</th></tr><tr><td>1043<div class="example">1044<pre class="example-preformatted">setcolor teal1045rect 30 30 120 1201046fill1047 1048setvar teal #70AAAA1049setcolor teal         // Use the new color for `teal`.1050rect 90 90 120 1201051fill1052</pre></div>1053 1054</td></tr></table>1055 1056<p><a class="ref" href="#cmd_005fdefrgba"><code class="code">defrgba</code></a> and <a class="ref" href="#cmd_005fdefhsla"><code class="code">defhsla</code></a> assign a color to a variable, by providing1057an expression for each color component:1058</p>1059<ul class="itemize mark-bullet">1060<li>For <a class="ref" href="#cmd_005fdefrgba"><code class="code">defrgba</code></a>: <em class="emph">red</em>, <em class="emph">green</em>, <em class="emph">blue</em>, and1061<em class="emph">alpha</em>.1062 1063</li><li>For <a class="ref" href="#cmd_005fdefhsla"><code class="code">defhsla</code></a>: <em class="emph">hue</em>, <em class="emph">saturation</em>, <em class="emph">lightness</em>, and1064<em class="emph">alpha</em>.1065</li></ul>1066 1067<p>Each color component must be in range <code class="code">0</code> to <code class="code">1</code>, except1068<em class="emph">hue</em>, which is <code class="code">0</code> to <code class="code">360</code>.1069</p>1070<table class="cartouche" border="1"><tr><th>1071Example</th></tr><tr><td>1072<div class="example">1073<pre class="example-preformatted">defrgba colorA 1 0.5 0.25 1     // colorA = RGB(255, 127, 63)1074defhsla colorB 200 0.75 0.25 1  // colorB = HSL(200, 75%, 25%)1075 1076rect 0 0 (w / 2) h1077setcolor colorA1078fill1079 1080rect (w / 2) 0 (w / 2) h1081setcolor colorB1082fill1083</pre></div>1084 1085</td></tr></table>1086 1087<a class="anchor" id="transformation-matrix"></a><a name="Transformations"></a>1088<h3 class="section">3.4 Transformations<span class="pull-right"><a class="anchor hidden-xs" href="#Transformations" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Transformations" aria-hidden="true">TOC</a></span></h3>1089 1090<p>The coordinates for each command can be scaled, rotated, and translated,1091by using the following commands:1092</p>1093<ul class="itemize mark-bullet">1094<li><a class="ref" href="#cmd_005frotate"><code class="code">rotate</code></a>1095</li><li><a class="ref" href="#cmd_005fscale"><code class="code">scale</code></a>1096</li><li><a class="ref" href="#cmd_005fscalexy"><code class="code">scalexy</code></a>1097</li><li><a class="ref" href="#cmd_005ftranslate"><code class="code">translate</code></a>1098</li></ul>1099 1100<p>The transformations are applied when the command is executed. They have1101no effect on the existing path, only on the new segments added to it.1102</p>1103<p>They are done by updating the1104<a class="uref" href="https://www.cairographics.org/manual/cairo-Transformations.html">current1105transformation matrix</a> in the Cairo context. To reset the matrix to its1106original state, before any transformation, use <a class="ref" href="#cmd_005fresetmatrix"><code class="code">resetmatrix</code></a>.1107</p>1108<p>The transform origin for scale and rotation is initially at <code class="code">0, 0</code>,1109but it can be adjusted with <a class="ref" href="#cmd_005ftranslate"><code class="code">translate</code></a>.1110</p>1111<table class="cartouche" border="1"><tr><th>1112Example</th></tr><tr><td>1113<div class="example">1114<pre class="example-preformatted">// Map (0, 0) as the center of the frame.1115translate (w / 2) (h / 2)1116 1117// Scale the space as if the frame is 1x1 pixel.1118scalexy w h1119 1120// Draw multiple lines with the same arguments,1121// but each one on a different rotation.1122repeat 10 {1123    rotate (PI / 10)1124    M -0.25 01125    H 0.251126}1127 1128// Reset transformations, so the scale does not1129// affect stroke.1130resetmatrix1131 1132stroke1133</pre></div>1134 1135</td></tr></table>1136 1137<a class="anchor" id="State-Stack"></a><a name="State-Stack-1"></a>1138<h3 class="section">3.5 State Stack<span class="pull-right"><a class="anchor hidden-xs" href="#State-Stack-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-State-Stack-1" aria-hidden="true">TOC</a></span></h3>1139 1140<p>The state of a drawvg script contains all parameters used for drawing1141operations, like the current color, the transformation matrix, the1142stroke configuration, etc.1143</p>1144<p>The <a class="ref" href="#cmd_005fsave"><code class="code">save</code></a> command pushes a snapshot of the state to an internal1145stack. Later, <a class="ref" href="#cmd_005frestore"><code class="code">restore</code></a> pops the latest snapshot from the stack,1146and uses it as the new state.1147</p>1148<p>The parameters that can be saved and restored are:1149</p>1150<ul class="itemize mark-bullet">1151<li>Pattern for stroke and fill operations.1152 1153<ul class="itemize mark-bullet">1154<li><a class="ref" href="#cmd_005flineargrad"><code class="code">lineargrad</code></a>1155</li><li><a class="ref" href="#cmd_005fradialgrad"><code class="code">radialgrad</code></a>1156</li><li><a class="ref" href="#cmd_005fsetrgba"><code class="code">setrgba</code></a>1157</li><li><a class="ref" href="#cmd_005fsetcolor"><code class="code">setcolor</code></a>1158</li><li><a class="ref" href="#cmd_005fsethsla"><code class="code">sethsla</code></a>1159</li></ul>1160 1161</li><li>Transformation matrix.1162 1163<ul class="itemize mark-bullet">1164<li><a class="ref" href="#cmd_005fresetmatrix"><code class="code">resetmatrix</code></a>1165</li><li><a class="ref" href="#cmd_005frotate"><code class="code">rotate</code></a>1166</li><li><a class="ref" href="#cmd_005fscale"><code class="code">scale</code></a>1167</li><li><a class="ref" href="#cmd_005fscalexy"><code class="code">scalexy</code></a>1168</li><li><a class="ref" href="#cmd_005ftranslate"><code class="code">translate</code></a>1169</li></ul>1170 1171</li><li>Stroke configuration.1172 1173<ul class="itemize mark-bullet">1174<li><a class="ref" href="#cmd_005fsetdash"><code class="code">setdash</code></a>1175</li><li><a class="ref" href="#cmd_005fsetdashoffset"><code class="code">setdashoffset</code></a>1176</li><li><a class="ref" href="#cmd_005fsetlinecap"><code class="code">setlinecap</code></a>1177</li><li><a class="ref" href="#cmd_005fsetlinejoin"><code class="code">setlinejoin</code></a>1178</li><li><a class="ref" href="#cmd_005fsetlinewidth"><code class="code">setlinewidth</code></a>1179</li></ul>1180 1181</li><li>Clip region1182 1183<ul class="itemize mark-bullet">1184<li><a class="ref" href="#cmd_005fclip"><code class="code">clip</code></a>1185</li><li><a class="ref" href="#cmd_005fresetclip"><code class="code">resetclip</code></a>1186</li></ul>1187 1188</li></ul>1189 1190<a class="anchor" id="Frame-Metadata"></a><a name="Frame-Metadata-1"></a>1191<h3 class="section">3.6 Frame Metadata<span class="pull-right"><a class="anchor hidden-xs" href="#Frame-Metadata-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Frame-Metadata-1" aria-hidden="true">TOC</a></span></h3>1192 1193<p>Some FFmpeg filters add metadata to frames. The command1194<a class="ref" href="#cmd_005fgetmetadata"><code class="code">getmetadata</code></a> can read metadata items containing a numeric value,1195and store it in a variable that can be used for command arguments.1196</p>1197<table class="cartouche" border="1"><tr><th>1198Example</th></tr><tr><td>1199<p>The <code class="code">cropdetect</code> filter computes the parameters to remove empty1200regions around the video. These parameters are accessible in the

Showing the first 1,200 of 2968 lines. Download the file for the rest.

codekingpro/portable-devtools · Team Ai