# drawvg - Language Reference

# Table of Contents

- 1 Introduction
- 2 Syntax
  - 2.1 Structure
  - 2.2 Comments
  - 2.3 Commands
    - 2.3.1 Single-Letter Aliases
    - 2.3.2 Implicit Commands
  - 2.4 Arguments
    - 2.4.1 Number Literals
    - 2.4.2 Expressions
    - 2.4.3 Variable Names
    - 2.4.4 Colors
    - 2.4.5 Constants
- 3 Guide
  - 3.1 Paths
    - 3.1.1 Current Point
    - 3.1.2 Defining a Shape
    - 3.1.3 Fill
    - 3.1.4 Stroke
    - 3.1.5 Clip
    - 3.1.6 Preserving Paths
  - 3.2 Variables
    - 3.2.1 User Variables
  - 3.3 Patterns
    - 3.3.1 Gradients
    - 3.3.2 Variables
  - 3.4 Transformations
  - 3.5 State Stack
  - 3.6 Frame Metadata
  - 3.7 `if` / `repeat` Statements
    - 3.7.1 Comparison and Logical Operators
    - 3.7.2 Early Exit
  - 3.8 Procedures
  - 3.9 Functions in Expressions
    - 3.9.1 Function `p`
    - 3.9.2 Function `pathlen`
    - 3.9.3 Function `randomg`
  - 3.10 Tracing with `print`
    - 3.10.1 Function print
    - 3.10.2 Command `print`
- 4 Commands
  - 4.1 `arc`
  - 4.2 `arcn`
  - 4.3 `break`
  - 4.4 `call`
  - 4.5 `circle`
  - 4.6 `clip`, `eoclip`
  - 4.7 `Z`, `z`, `closepath`
  - 4.8 `colorstop`
  - 4.9 `C`, `curveto`
  - 4.10 `c`, `rcurveto`
  - 4.11 `defhsla`
  - 4.12 `defrgba`
  - 4.13 `ellipse`
  - 4.14 `fill`, `eofill`
  - 4.15 `getmetadata`
  - 4.16 `H`, `h`
  - 4.17 `if`
  - 4.18 `lineargrad`
  - 4.19 `L`, `lineto`
  - 4.20 `l`, `rlineto`
  - 4.21 `M`, `moveto`
  - 4.22 `m`, `rmoveto`
  - 4.23 `newpath`
  - 4.24 `preserve`
  - 4.25 `print`
  - 4.26 `proc`
  - 4.27 `Q`
  - 4.28 `q`
  - 4.29 `radialgrad`
  - 4.30 `rect`
  - 4.31 `repeat`
  - 4.32 `resetclip`
  - 4.33 `resetdash`
  - 4.34 `resetmatrix`
  - 4.35 `restore`
  - 4.36 `rotate`
  - 4.37 `roundedrect`
  - 4.38 `save`
  - 4.39 `scale`
  - 4.40 `scalexy`
  - 4.41 `setcolor`
  - 4.42 `setdash`
  - 4.43 `setdashoffset`
  - 4.44 `sethsla`
  - 4.45 `setlinecap`
  - 4.46 `setlinejoin`
  - 4.47 `setlinewidth`
  - 4.48 `setrgba`
  - 4.49 `setvar`
  - 4.50 `stroke`
  - 4.51 `S`, `s`
  - 4.52 `translate`
  - 4.53 `T`, `t`
  - 4.54 `V`, `v`

# 1 Introduction

drawvg (draw vector graphics) is a language to draw two-dimensional graphics on top of video frames. It is not intended to be used as a general-purpose language. Since its scope is limited, it prioritizes being concise and easy to use.

For example, using the Canvas API we can render a triangle running this code in a Web browser:

    const canvas = document.getElementById("canvas");
    const ctx = canvas.getContext("2d");

    ctx.beginPath();
    ctx.moveTo(125, 50);
    ctx.lineTo(100, 100);
    ctx.lineTo(150, 100);
    ctx.closePath();
    ctx.stroke();

The same triangle can be written with this drawvg script:

    moveto 125 50
    lineto 100 100 150 100
    closepath
    stroke

It can be shortened using the aliases for `moveto`, `lineto`, and `closepath`:

    M 125 50
    L 100 100 150 100
    Z
    stroke

Both newlines (`U+000A`) and spaces (`U+0020`) can be used interchangeably as delimiters, so multiple commands can appear on the same line:

    M 125 50 L 100 100 150 100 Z
    stroke

Finally, drawvg can use (ffmpeg-utils)FFmpeg expressions and frame metadata in command arguments. In this example, we are using the variables w (frame width) and h (frame height) to create a circle in the middle of the frame.

    circle (w / 2) (h / 2) (w / 3)
    stroke

Many commands are a direct equivalent to a function in the Cairo graphics library. For such commands, the reference below provides a link to the related Cairo documentation.

# 2 Syntax

The syntax is heavily inspired by languages like Magick Vector Graphics, or SVG’s `<path>`. Many command names are taken from PostScript.

## 2.1 Structure

A drawvg script consists of a series of commands to describe 2D graphics.

A command is an identifier (like `setcolor` or `lineto`) followed by its arguments. Each item in the code (command name, arguments, etc.) is separated by any of the following characters:

- Space (`' '`)
- Comma (`','`)
- Newline (`'\n'`)
- Tabs (`'\t'`)
- Return (`'\r'`)

The beginning of the item indicates how it will be interpreted:

`//`

  Comment

`0`, …, `9`, `+`, `-`

  Number literal

`(`

  Expression

`{`, `}`

  Block delimiters

Anything else

  Name of a command, a color, etc.

## 2.2 Comments

Comments start with two slashes (`//`), and stop at the end of the line (either a `\n`, or the end of the script).

    circle 100 100 50 // this is ignored
    fill

    // this is also ignored

`//` must appear after a space, or at the beginning of the line. If `//` is preceded by any non-blank character, the parser will consider `//` as part of the previous item.

For example, in this script:

    circle 10 10 50// something

The parser throws an error because it tries to parse `50//` as a number literal.

## 2.3 Commands

The way commands are parsed is inspired by SVG’s `<path>`:

- Every command in the script starts with its name, and it is followed by zero or more arguments.
- There are no explicit delimiters between commands or arguments.

  Most programming languages expect characters like parenthesis, commas, or semicolons, to separate items. For example:

      moveto(10, 10); lineto(20, 30);

  The equivalent in drawvg is:

      moveto 10 10 lineto 20 30

- If the command has no arguments (like `closepath` or `stroke`), the next command starts at the next item.

Example In the next script there are 4 different commands:

    newpath rect 10 20 30 40 setcolor teal fill

1. `newpath` requires no arguments.
2. `rect` requires 4 arguments, so it takes the next 4 numbers.
3. `setcolor` requires 1 argument, so it takes the word `teal`.
4. `fill` requires no arguments.

### 2.3.1 Single-Letter Aliases

Most commands in SVG’s `<path>` are also present in drawvg. For some of them, there is an alias to a longer name:

- `curveto` for `C`.
- `rcurveto` for `c`.
- `lineto` for `L`.
- `rlineto` for `l`.
- `moveto` for `M`.
- `rmoveto` for `m`.
- `closepath` for `Z`, `z`.

Other commands only exist in a single-letter form:

- `H`, `h`
- `Q`, `q`
- `S`, `s`
- `V`, `v`
- `T`, `t`

This makes it possible to use a path in SVG to create the same shape in a drawvg script.

### 2.3.2 Implicit Commands

For many commands, the name can be omitted when it is used multiple times in successive calls.

In the reference below, these commands has a Can be Implicit note in their signature.

Example For example, in this script:

    M 50 50
    l 10 10
    l 10 -10
    l 10 10
    l 10 -10
    l 10 10
    stroke

After the first call to `l` (alias to `rlineto`), the command can be executed without the name, so it can be written as:

    M 50 50
    l 10 10 10 -10 10 10 10 -10 10 10
    stroke

To reuse the same command (`l`, in the previous example), the parser checks if the item after the last argument is a numeric value, like a number literal or a FFmpeg expression.

Example In this example:

    l 10 20 30 40 stroke

`l` requires 2 arguments, and can be implicit, so the parser performs this operation:

1. Takes the two next items (`10` and `20`) and emits the first instruction.
2. Checks if the item after `20` is a numeric value. Since it is `30`, it takes `30` and `40` and emits the second instruction (`l 30 40`).
3. Checks if the next item after `40` is a numeric value, but it is a command (`stroke`), so it stops reusing `l`.

This is another feature taken from SVG’s `<path>`. An important difference with SVG is that the separator between items is always required. In SVG, it can be omitted in some cases. For example, the expression `m1-2` is equivalent to `m 1 -2` in SVG, but a syntax error in drawvg.

## 2.4 Arguments

Most commands expect numeric arguments, like number literals, variable names, or expressions.

`setcolor` and `colorstop` expect a color.

`setlinecap` and `setlinejoin` expect a constant value.

### 2.4.1 Number Literals

A number literal is an item in the script that represents a constant value. Any item that starts with a decimal digit (between `0` and `9`), a `-` or a `+`, is interpreted as a number literal.

The value is parsed with `av_strtod`. It supports the prefix `0x` to write a value with hexadecimal digits, and many units (like `K` or `GiB`).

In the next example, all literals represent the same value:

    10000
    1e4
    10K
    0x2710

### 2.4.2 Expressions

(ffmpeg-utils)FFmpeg expressions can be used as arguments for any command that expects a numeric argument. The expression must be enclosed in parenthesis.

Example The variables w and h represent the width and height of the frame. We can compute the center of the frame by dividing them by `2`:

    M (w / 2) (h / 2)

They can also contain parenthesis (to group operations, to call functions, etc):

    moveto
        ((w + 10) / 2)      // x
        (h / (2 * cos(t)))  // y

The variables n and t can be used to compute a value that changes over time.

Example To draw a circle oscillating from left to right, we can use an expression based on `sin(t)` for the `x` coordinate:

    circle
        (w / 2 + sin(2 * t) * w / 4)  // x
        (h / 2)                       // y
        (w / 5)                       // radius

    stroke

Expressions can be split in multiple lines, but they can’t contain comments within them.

    moveto   // This is a comment.
        (w   // This is part of the expression, not a comment.
         + h)

### 2.4.3 Variable Names

When an expression is only a reference to a variable, the parenthesis can be omitted, and the item is just the variable name.

Example The next 3 expressions are equivalent: in all cases, they create a rectangle covering the whole frame.

    rect (0) (0) (w) (h)

    rect 0 0 w h

    rect (0) 0 (w) h

It is possible to create a variable with the same name of a command, and then use it as an argument. In the previous example, the item h is a reference to a variable (frame height), but in other contexts it may be a command (`h`).

For implicit commands, the parser prioritizes commands over variable names when it has to determine if the command is reused.

Example In this example, the variable c is used as the first argument in two calls to `l`. However, only the first one is valid, because in the second call the parser recognizes `c` as a command.

    setvar c 5
    l c 10 c 15

This issue can be fixed by surrounding the start of the second call with parenthesis:

    setvar c 5
    l c 10 (c) 15

### 2.4.4 Colors

The color to stroke and to fill paths can be set with `setcolor`. Its argument has the same syntax for colors in FFmpeg:

- A (ffmpeg-utils)predefined color name.
- In `#RRGGBB` format.
- Optionally, an `@a` suffix can be added to set the alpha value, where `a` is a number between `0` and `1`.

    circle 70 70 60
    setcolor #FF0000
    fill

    circle 170 170 60
    setcolor blue@0.5
    fill

The color can be a variable name. In that case, it must be assigned with `defrgba`, `defhsla`, or `setvar` and a color.

    circle 70 70 60
    setvar CustomGreen #22FF44
    setcolor CustomGreen
    fill

    circle 170 170 60
    defhsla CustomBlue 200 0.7 0.5 1
    setcolor CustomBlue
    fill

The commands `setrgba` and `sethsla` allow setting colors using expressions. Similar to `defrgba` and `defhsla`, but with no intermediate variable.

### 2.4.5 Constants

The argument for `setlinecap` and `setlinejoin` is an identifier referring to a constant value.

    setlinecap round

# 3 Guide

## 3.1 Paths

A path is a complex shape, composed by lines and curves, that can be used to fill a region, to stroke an outline, or to establish a clip region.

In order to draw anything on top of a video frame, first we have to define a path, and then use `stroke` or `fill`.

The tutorial on paths in MDN is a good introduction to the topic. It is focused on SVG’s `<path>`, but the same concepts can be applied in drawvg.

### 3.1.1 Current Point

Some commands require a current point. Initially, the current point is set to `NaN`. It is initialized with `M` or `moveto`. Other commands, like `lineto` or `curveto`, updates the current point to the new end of the shape.

The current point can be cleared with `newpath`. Commands that clear the path, like `stroke` or `fill`, also clear the current point.

Example `rlineto` uses coordinates relative to the current point.

Given this script:

    moveto 20 100
    rlineto 150 -90
    rlineto -50 200
    closepath
    stroke

These are the coordinates of the current point after executing each command:

Command | Current Point
--- | ---
`moveto 20 100` | `20, 100`
`rlineto 150 -90` | `170, 10`
`rlineto -10 50` | `140, 210`
`closepath` | `20, 100`

The same script can be written with single-letter aliases:

    M 20 100 l 150 -90 -50 200 z stroke

### 3.1.2 Defining a Shape

A path is defined by adding lines, curves, or basic shapes.

- Basic shapes
  - `circle`
  - `ellipse`
  - `rect`
  - `roundedrect`
- Lines
  - `M`, `moveto`
  - `m`, `rmoveto`
  - `H`, `h`
  - `V`, `v`
  - `L`, `lineto`
  - `l`, `rlineto`
  - `Z`, `z`, `closepath`
- Curves
  - `arc`, `arcn`
  - `C`, `curveto`,
  - `c`, `rcurveto`
  - `Q`, `q`
  - `S`, `s`
  - `T`, `t`

Single-letter commands are taken from SVG’s `<path>`.

### 3.1.3 Fill

The region within the shape defined by a path can be filled with `fill` or `eofill`. Each command uses a different fill rule:

- `fill` uses the winding rule, also known as nonzero rule.
- `eofill` uses the even–odd rule.

Example This script shows the difference between the winding and even–odd rules:

    rect 50 10 100 60
    circle 150 70 40
    setcolor seagreen
    fill

    rect 50 130 100 60
    circle 150 190 40
    setcolor skyblue
    eofill

### 3.1.4 Stroke

`stroke` draws a line around the shape defined by the path. The stroke can be configured with different commands:

- `setdash`
- `setdashoffset`
- `setlinecap`
- `setlinejoin`
- `setlinewidth`
- `resetdash`

Example This example use `setdashoffset` to animate the stroke:

    moveto 0 0
    lineto w h

    setlinecap round
    setdash 50 50
    setlinewidth 20
    setdashoffset (hypot(w, h) * t / -3)
    setcolor seagreen

    stroke

### 3.1.5 Clip

A clip region can be established with `clip` and `eoclip`.

If there is an active clip region, the new clip region will be the intersection between the existing one and the path. `resetclip` reset the clip region to the whole frame.

`eoclip` uses the even–odd rule to compute the clip region.

Example

    rect 50 50 100 200
    clip

    circle 30 30 150
    setcolor seagreen
    fill

    // Draw outside the clip region.
    resetclip
    circle 30 30 150
    setlinewidth 3
    setcolor skyblue
    stroke

### 3.1.6 Preserving Paths

The path is cleared after any operation on it, like `fill` or `stroke`. To reuse the same path in multiple operations, `preserve` must be called before them.

Example In this example, each path is used twice.

    circle 120 120 50
    setcolor seagreen
    preserve stroke
    clip

    circle 100 100 50
    setcolor skyblue
    preserve fill
    setcolor tomato
    stroke

## 3.2 Variables

A drawvg can use some variables, provided by the interpreter, to compute values in (ffmpeg-utils)FFmpeg expressions:

cx

  X coordinate of the current point.

cy

  Y coordinate of the current point.

w

  Width, in pixels, of the frame.

h

  Height, in pixels, of the frame.

i

  The loop counter in repeat blocks.

n

  Frame number.

t

  Timestamp, in seconds.

ts

  Timestamp, in seconds, of the first frame.

duration

  Duration, in seconds, of the frame.

### 3.2.1 User Variables

New variables can be created with the `setvar` command. It associates a name with a numeric value.

The name must follow these rules:

- It must start with an ASCII letter or an underscore (`_`).
- It can contain only ASCII letters, underscores, and digits.
- It must not match the name of a variable provided by the interpreter (like w or t).

The same variable can be assigned multiple times.

Example In this example, the result of an expression is stored in a variable with the name progress. Then, it is used for the x and width arguments of `rect`.

    setvar progress (w * (pow(mod(t / 2 + 0.5, 1), 2.5)))

    rect ((w - progress) / 2) 0 progress h

    setcolor darkblue
    fill

Currently, a script can contain only 20 different variable names, but this limit can be modified in the future.

## 3.3 Patterns

The pattern for fill and stroke operations can be either a solid color, or a gradient.

- Solid colors.
  - `setcolor`
  - `sethsla`
  - `setrgba`
- Gradients.
  - `lineargrad`
  - `radialgrad`

The pattern is not cleared after being used in a fill or stroke operation, but it is replaced by any command that sets a new pattern.

### 3.3.1 Gradients

To configure a gradient, first call to `lineargrad` or `radialgrad`, and then add color stops by calling `colorstop` for each stop.

Example In this example, the whole frame is filled with a linear gradient:

    lineargrad 0 0 w h
    colorstop 0 skyblue
    colorstop 1 darkblue

    rect 0 0 w h
    fill

In this example, a radial gradient is used to simulate a sphere:

    radialgrad 90 90 5 120 120 100
    colorstop 0.0 #90DDFF
    colorstop 0.9 #000030
    colorstop 1.0 #000000

    rect 0 0 w h
    fill

### 3.3.2 Variables

`setcolor` and `colorstop` accept a variable name as the argument. The variable must be assigned with `defrgba`, `defhsla`, or `setvar` and a color.

Example

    // Use color #1020FF, alpha = 50%
    setvar someblue #1020FF@0.5

    setcolor someblue

    rect 30 30 120 120
    fill

    rect 90 90 120 120
    fill

If a variable has the same name of a (ffmpeg-utils)known color, the variable has preference, and will be used instead of the predefined color.

Example

    setcolor teal
    rect 30 30 120 120
    fill

    setvar teal #70AAAA
    setcolor teal         // Use the new color for `teal`.
    rect 90 90 120 120
    fill

`defrgba` and `defhsla` assign a color to a variable, by providing an expression for each color component:

- For `defrgba`: red, green, blue, and alpha.
- For `defhsla`: hue, saturation, lightness, and alpha.

Each color component must be in range `0` to `1`, except hue, which is `0` to `360`.

Example

    defrgba colorA 1 0.5 0.25 1     // colorA = RGB(255, 127, 63)
    defhsla colorB 200 0.75 0.25 1  // colorB = HSL(200, 75%, 25%)

    rect 0 0 (w / 2) h
    setcolor colorA
    fill

    rect (w / 2) 0 (w / 2) h
    setcolor colorB
    fill

## 3.4 Transformations

The coordinates for each command can be scaled, rotated, and translated, by using the following commands:

- `rotate`
- `scale`
- `scalexy`
- `translate`

The transformations are applied when the command is executed. They have no effect on the existing path, only on the new segments added to it.

They are done by updating the current transformation matrix in the Cairo context. To reset the matrix to its original state, before any transformation, use `resetmatrix`.

The transform origin for scale and rotation is initially at `0, 0`, but it can be adjusted with `translate`.

Example

    // Map (0, 0) as the center of the frame.
    translate (w / 2) (h / 2)

    // Scale the space as if the frame is 1x1 pixel.
    scalexy w h

    // Draw multiple lines with the same arguments,
    // but each one on a different rotation.
    repeat 10 {
        rotate (PI / 10)
        M -0.25 0
        H 0.25
    }

    // Reset transformations, so the scale does not
    // affect stroke.
    resetmatrix

    stroke

## 3.5 State Stack

The state of a drawvg script contains all parameters used for drawing operations, like the current color, the transformation matrix, the stroke configuration, etc.

The `save` command pushes a snapshot of the state to an internal stack. Later, `restore` pops the latest snapshot from the stack, and uses it as the new state.

The parameters that can be saved and restored are:

- Pattern for stroke and fill operations.
  - `lineargrad`
  - `radialgrad`
  - `setrgba`
  - `setcolor`
  - `sethsla`
- Transformation matrix.
  - `resetmatrix`
  - `rotate`
  - `scale`
  - `scalexy`
  - `translate`
- Stroke configuration.
  - `setdash`
  - `setdashoffset`
  - `setlinecap`
  - `setlinejoin`
  - `setlinewidth`
- Clip region
  - `clip`
  - `resetclip`

## 3.6 Frame Metadata

Some FFmpeg filters add metadata to frames. The command `getmetadata` can read metadata items containing a numeric value, and store it in a variable that can be used for command arguments.

Example The `cropdetect` filter computes the parameters to remove empty regions around the video. These parameters are accessible in the `lavfi.cropdetect` keys of the frame metadata.

    // Get metadata from cropdetect filter and store it
    // in `cd*` variables.
    getmetadata cdx lavfi.cropdetect.x
    getmetadata cdy lavfi.cropdetect.y
    getmetadata cdw lavfi.cropdetect.w
    getmetadata cdh lavfi.cropdetect.h

    rect cdx cdy cdw cdh
    setcolor yellow@0.5
    setlinewidth 10
    stroke

To test the script, copy it to a `drawcropdetect.vgs` file, and then execute a command like this:

    ffplay -i example-video.webm -vf 'cropdetect, drawvg=file=drawcropdetect.vgs'

## 3.7 `if` / `repeat` Statements

There is limited support for control flow statements: only `if` and `repeat`.

Both commands receive two arguments: an expression and a block.

    if (condition) {
        // commands
    }

    repeat (count) {
        // commands
    }

`if` executes its block if the result of `(condition)` is not zero.

`repeat` executes its block the number of times specified by `(count)`. In each iteration, the variable i is used as a loop counter.

If the result of the expression is not a finite number (like `NaN`) the block is not executed.

### 3.7.1 Comparison and Logical Operators

(ffmpeg-utils)FFmpeg expressions only supports arithmetic operators (like `+` for addition). Comparison operators (like `!=`) are supported via functions, while logical operators (like `&&` for `AND`) can be emulated with arithmetic operations.

Expression | FFmpeg Equivalent
--- | ---
`x = y` | `eq(x, y)`
`x < y` | `lt(x, y)`
`x > y` | `gt(x, y)`
`x ≤ y` | `lte(x, y)`
`x ≥ y` | `gte(x, y)`
`a ≤ x ≤ b` | `between(x, a, b)`

Logical operators can be emulated with multiplication (for `AND`), or addition (for `OR`):

Expression | FFmpeg Equivalent
--- | ---
`x OR y` | `x + y`
`x AND y` | `x * y`

Example In other programming languages, a code like this:

    if (x > y && z != 1) {
        // …
    }

Can be written for drawvg like this:

    if (gt(x, y) * not(eq(z, 1))) {
        // …
    }

### 3.7.2 Early Exit

`break` causes a `repeat` loop to be terminated immediately.

If it is executed outside a `repeat` block, it terminates the whole script, or the current procedure.

Example In this example, we are using the `randomg` function to draw a line with random segments.

The loop can be executed `500` times, but it is interrupted if the X coordinate of the current point (cx) exceeds the frame width (w). The current point is updated after each call to `rlineto`.

    moveto 0 0

    repeat 500 {
        rlineto
            (randomg(0) * 15)
            (randomg(0) * 20)

        if (gt(cx, w)) {
            break
        }
    }

    stroke

## 3.8 Procedures

A procedure is a name associated with a block that can be executed multiple times. It can take between 0 and 6 parameters.

`proc` is used to set the parameter names and the block for a procedure:

    proc p0 {
        // …
    }

    proc p1 param1 param2 {
        // …
    }

Inside the block, the arguments can be accessed as regular variables:

    proc square center_x center_y side {
        rect
            (center_x - side / 2) (center_y - side / 2)
            side side
    }

`call` executes the block assigned to the procedure name. It requires the name of the procedure, and the value for each parameter defined in the call to `proc`.

    call p0

    call p1 1 2

    call square (w / 2) (h / 2) (w / t)

Example In this example, the procedure `zigzag` draws multiple lines from the current point.

    setvar len (w / 10)
    setlinewidth 5

    proc zigzag {
        repeat 10 {
            l len len len (-len)
        }

        stroke
    }

    setcolor #40C0FF
    M 0 60
    call zigzag

    setcolor #00AABB
    M 0 120
    call zigzag

    setcolor #20F0B7
    M 0 180
    call zigzag

The color and the Y coordinate of the starting point can be sent as procedure arguments:

    setvar len (w / 10)
    setlinewidth 5

    proc zigzag color y {
        setcolor color

        M 0 y
        repeat 10 {
            l len len len (-len)
        }

        stroke
    }

    call zigzag #40C0FF 60
    call zigzag #00AABB 120
    call zigzag #20F0B7 180

When the procedure returns, the value of the variable for each argument is restored to the value it had before calling the procedure. Changes in other variables (with `setvar`, `getmetadata`, `defhsla`, and `defrgba`) are preserved.

Example In the next example, the variable A has the value `0` before calling the procedure P. During the execution of P, `A` is `1`, but after it, A is `0` again.

    setvar A 0

    proc P A {
        print A
    }

    print A
    call P 1
    print A

It writes the following messages:

    [7:7] A = 0.000
    [4:8] A = 1.000
    [9:7] A = 0.000

`break` causes the script to leave the current procedure, similar to the `return` statement in other programming languages, unless it is called within a `repeat` loop.

The body of the procedure must be defined with `proc` before using `call`.

Example In this example, when the procedure `notyet` is called, its body has not yet defined, so the execution fails with the error `Missing body for procedure 'notyet'`.

    call notyet

    proc notyet {
        // ...
    }

A procedure can be redefined by other calls to `proc` with the same name. In such case, `call` invokes the last assigned block.

Example In this example, the procedure `example` has two different blocks.

    proc example {
        // block1
    }

    call example    // executes block1

    proc example {
        // block2
    }

    call example    // executes block2

## 3.9 Functions in Expressions

There are some functions specific to drawvg available in (ffmpeg-utils)FFmpeg expressions.

### 3.9.1 Function `p`

`p(x, y)` returns the color of the pixel at coordinates `x, y`, as a `0xRRGGBBAA` value. It can be assigned to a variable, so the color can be available for `setcolor` and `colorstop` commands.

If a single expression contains multiple calls to the function, it must return the value of the last call in order to use it as a color.

Example In this example, the first call to `p(0, 0)` is stored in the variable 0 of the expression. Then, the same expression makes a second call to `p(1, 1)`, and finally it returns the value in the variable 0.

    setvar pixel (st(0, p(0, 0)); p(1, 1); ld(0))

Since the result of the expression is not the last call to `p`, the variable pixel can not be used as a color, but it still can be used as a numeric `0xRRGGBBAA` value.

If the coordinates are outside the frame, or any of the arguments is not a finite number (like `NaN`), the function returns `NaN`.

The transformation matrix is applied to the arguments. To use the original frame coordinates, call `resetmatrix` between `save` and `restore`:

    save
    resetmatrix
    setvar pixel (p(0, 0))    // top-left pixel of the frame.
    restore

    setcolor pixel

Bitwise operations can be used to extract individual color components:

    setvar pixel (p(x, y))

    if (not(isnan(pixel))) {
        setvar px_red   (pixel / 0x1000000)
        setvar px_green (bitand(pixel / 0x10000, 0xFF))
        setvar px_blue  (bitand(pixel / 0x100, 0xFF))
        setvar px_alpha (bitand(pixel, 0xFF))
    }

### 3.9.2 Function `pathlen`

`pathlen(n)` computes the length of the current path, by adding the length of each line segment returned by `cairo_copy_path_flat`.

The function expects an argument n, as the maximum number of line segments to add to the length, or `0` to add all segments.

Example In this example, `pathlen` is used to animate the stroke of a spiral, in a 5 seconds loop.

    M (w / 2) (h / 2)

    setvar a -1
    repeat 16 {
        rcurveto
            (a * 2 / 3) 0
            (a * 2 / 3) (a)
            0 (a)

        setvar a (-sgn(a) * (abs(a) + 10))
    }

    setlinewidth 3
    setdash
        (pathlen(0) * (1 - mod(t / 5, 1)))
        1e6

    setcolor teal
    stroke

### 3.9.3 Function `randomg`

`randomg(idx)` is similar to the `random(idx)` function, available in (ffmpeg-utils)FFmpeg expressions, but its state is global to the frame, instead of specific to each expression.

To understand the difference, we need to dive into how `random(idx)` works inside a drawvg script.

First, each expression in FFmpeg has a set of 10 internal variables, which can be written with `st(idx, value)`, and can be read with `ld(idx)`. idx is a value between `0` and `9`. These variables are initialized to `0`.

When a drawvg script is parsed, each expression is compiled with `av_expr_parse`, from libavutil, and these compiled expressions are reused for every frame. The changes in the internal variables (with `st(idx, value)`) are visible between frames, but they are not shared between expressions.

Example In this example, the expression for the X coordinate updates its internal variable `0` in every frame:

    circle
        (st(0, mod(ld(0) + 15, w))) // X
        120                         // Y
        (ld(0) + 20)                // radius

    fill

`st(idx, value)` returns the updated value, so it can be used as the result of the expression.

The radius is not affected because its internal variable (from `ld(0)`) is not updated by the other expression.

Also, note that this example is just to show how internal variables are kept between frames. A better approach to create this animation is to use the variables n or t:

    circle (mod(n * 15, w)) 120 20
    fill

The function `random(idx)` returns a pseudorandom value between `0` and `1`. idx is the internal variable that is used both as the seed and to keep the state of the number generator.

Example The next example uses `random(0)` to generate a random value for the center of a circle:

    circle
        (random(0) * w)
        (random(0) * h)
        10

    fill

The circle in every frame is at a different position, but always on the diagonal line of the frame. This happens because the values for the coordinates X and Y are identical, since both number generators use the same seed.

To distribute the circles over the whole frame we need different seeds for each expression. This can be achieved by writing a non-zero value (like `0xF0F0`) to the internal variable of one of expressions, but only when its value is `0`:

    circle
        (random(0) * w)
        (st(0, if(ld(0), ld(0), 0xF0F0)); random(0) * h)
        10

    fill

This approach is only useful if we need completely different positions in each frame. In the next example, random values are used to distribute many circles over the frame, but the position is fixed. The only change over time is the fill color:

    repeat 20 {
        circle
            (st(0, i + 1e5); random(0) * w)
            (st(0, i + 1e10); random(0) * h)
            10
    }

    sethsla (t * 60) 0.5 0.5 1
    preserve fill

    setcolor black@0.5
    setlinewidth 1
    stroke

This is achieved by using a precomputed state before calling `random(0)`. The variable i, updated by `repeat`, is needed to compute different states in each iteration.

The `randomg(idx)` function, which is specific to drawvg scripts, is similar to `random(idx)`, but intended to solve the previous problems:

- All frames have the same seed.
- The state is shared between expressions.

The parameter idx has two uses:

- The last two bits are the index of an internal state, so it is possible to have 4 different number generators.
- The first call to `randomg` with a specific index will use the argument as the seed for the number generator in that index.

In a script like this:

    M (randomg(0xFF1)) (randomg(0xFF0))
    l (randomg(0xAA1)) (randomg(0xFF0))

There are 4 calls to `randomg`:

1. The first call, with the argument `0xFF1`, uses the internal state at index `1` (because `0xFF1` modulo `4` is `1`).

   Since this is the first use of that index, the number generator is initialized with the seed `0xFF1`.

2. The second call has the same behaviour: it initializes the state at index `0` with the value `0xFF0`.
3. The third call has the argument `0xAA1`, and it uses index `1`. Since that state is already initialized (with the seed `0xFF1`), the value `0xAA1` is ignored, and it returns the next number.

Example This example renders a simple rain animation, moving lines from top to bottom.

`randomg` is used to distribute the lines over the frame, and to apply different speeds to each one.

    rect 0 0 w h
    setcolor midnightblue
    fill

    setcolor white

    repeat 50 {
        setvar offset (t * (randomg(0) + 1))

        moveto
            (mod(randomg(0) + offset / 6, 1) * w)
            (mod(randomg(0) + offset, 1) * h)

        rlineto 6 36

        setlinewidth (randomg(1) / 2 + 0.2)
        stroke
    }

## 3.10 Tracing with `print`

It is possible to trace the execution of a drawvg script by printing the value of an expression, either with the `print` command, or with the print function.

In both cases, the values are written to the FFmpeg log.

Printing expressions may have a noticeable impact on the performance, so it is preferable to use it only when necessary.

### 3.10.1 Function print

The function `print(t)` writes the value of t, and returns its argument.

Example Given a line line this:

    M (sin(2 * PI * t) * w) 0

We can see the values of `sin(2 * PI * t)` by surrounding it with a call to `print()`:

    M (print(sin(2 * PI * t)) * w) 0

Executing this script with a 1 second / 8 FPS video shows the expected values for the sine function.

    $ ffmpeg \
        -f lavfi \
        -i 'color=r=8:d=1, drawvg=M (print(sin(2 * PI * t)) * w) 0' \
        -f null /dev/null \
      |& grep 'Eval @'

    [Eval @ 0x7f500f502d20] 0.000000
    [Eval @ 0x7f4ff784b420] 0.707107
    [Eval @ 0x7f4ff784ba20] 1.000000
    [Eval @ 0x7f4ff784c020] 0.707107
    [Eval @ 0x7f4ff784c620] 0.000000
    [Eval @ 0x7f4ff784cc20] -0.707107
    [Eval @ 0x7f4ff784d220] -1.000000
    [Eval @ 0x7f4ff784d820] -0.707107

### 3.10.2 Command `print`

The command `print` accepts an arbitrary number of arguments, and for each one it writes:

- The source location (line and column).
- The source code of the expression.
- The result of evaluating the expression.

When there are multiple expressions, they are separated by the `|` character.

Example The next script prints the position of the current point after the `l` command:

    M 10 20
    l 100 100
    print cx cy
    stroke

For each frame, it produces this output:

    [3:7] cx = 110.000000 | [3:10] cy = 120.000000

The next example prints the values of `random(0)`:

    $ ffmpeg \
        -f lavfi \
        -i 'color=r=8:d=1, drawvg=print (random(0))' \
        -f null /dev/null \
      |& grep 'drawvg @'

    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.229731
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.959813
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.071676
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.044600
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.134127
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.320513
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.857675
    [drawvg @ 0x50a000000180] [1:7] (random(0)) = 0.562456

# 4 Commands

## 4.1 `arc`

`arc xc yc radius angle1 angle2` — Can be implicit

Adds a circular arc of the given radius to the current path. The arc is centered at xc, yc, begins at angle1 and proceeds in the direction of increasing angles to end at angle2.

If there is a current point, a line is added from it to the beginning of the arc. If this is not desired, use `newpath` before `arc` to clear the current point.

See the documentation of the `cairo_arc` function for more details.

Example

    arc 120 120 60 0 (3 * PI / 2)
    stroke

## 4.2 `arcn`

`arcn xc yc radius angle1 angle2` — Can be implicit

Similar to `arc`, but it differs in the direction of the arc between the two angles.

See the documentation of the `cairo_arc_negative` function for more details.

Example In this example, both `arc` and `arcn` have the same angles, but they render different arcs:

    arc  120  90 60 (PI / 2) 0

    newpath
    arcn 120 150 60 (PI / 2) 0

    stroke

`newpath` is needed to prevent a line between the two arcs.

## 4.3 `break`

`break`

`break` terminates the execution of the innermost block, either a `repeat` loop or a procedure.

If it is used outside of a `repeat` / `proc` block, it terminates the script for the current frame.

## 4.4 `call`

`call name args*`

Invokes a procedure defined by `proc`.

See the Procedures section above for more details.

## 4.5 `circle`

`circle xc yc radius` — Can be implicit

Adds a circle of the given radius to the current path. The circle is centered at xc, yc. The current point is cleared before and after adding the circle.

This is a convenience wrapper for `arc`. A call to `circle` is equivalent to:

    newpath
    arc xc yc radius (0) (2 * PI)
    newpath

## 4.6 `clip`, `eoclip`

`clip, eoclip`

Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by `fill` or `eofill`.

`eoclip` uses the even–odd rule. See fill rules for more details.

The path is cleared after updating the clip region, unless the `preserve` command is used before `clip` or `eoclip`.

See the documentation of the `cairo_clip` function for more details.

## 4.7 `Z`, `z`, `closepath`

`Z, z, closepath`

Adds a line segment to the path from the current point to the beginning of the current sub-path, and closes this sub-path. The beginning is set by any of the move commands (`M`, `m`, `moveto`, `rmoveto`).

See the documentation of the `cairo_close_path` function for more details.

## 4.8 `colorstop`

`colorstop offset color` — Can be implicit

Adds a color stop to a gradient pattern.

offset is a value between `0` and `1`, and it specifies the location along the gradient’s control vector.

This command must be executed after `lineargrad` or `radialgrad`.

Color stops can be added in any number of calls to `colorstop`. In the next example, the 3 blocks define the same gradient:

    // 1
    colorstop 0.0 red
    colorstop 0.5 green
    colorstop 1.0 blue

    // 2
    colorstop 0 red 0.5 green
    colorstop 1 blue

    // 3
    colorstop 0 red 0.5 green 1 blue

See the documentation of the `cairo_pattern_add_color_stop_rgba` function for more details.

Example In this example, color stops are added in a `repeat` loop.

    lineargrad 0 0 w h

    repeat 6 {
        defhsla s (i * 60) 0.8 0.5 1
        colorstop (i / 5) s
    }

    rect 0 0 w h
    fill

It is possible to avoid transitions between color stops by repeating the same color in two stops:

    lineargrad 0 0 w h

    repeat 6 {
        defhsla s (i * 60) 0.8 0.5 1
        colorstop (i / 5) s
        colorstop ((i + 1) / 5) s
    }

    rect 0 0 w h
    fill

## 4.9 `C`, `curveto`

`C, curveto x1 y1 x2 y2 x y` — Can be implicit

Draw a cubic Bézier curve from the current point to the end point specified by x, y. The start control point is specified by x1, y1 and the end control point is specified by x2, y2.

The behaviour is identical to the `C` command in SVG’s `<path>`. For more details, see Cubic Bézier Curve on MDN, and the Curve Commands section of the Paths tutorial on MDN.

Example

    moveto 20 20

    curveto
        0 (h / 2)           // start control point
        w (h / 2)           // end control point
        (w - 20) (h - 20)   // end point

    stroke

## 4.10 `c`, `rcurveto`

`c, rcurveto dx1 dy1 dx2 dy2 dx dy` — Can be implicit

Like `curveto`, but the coordinates are relative to the current point.

## 4.11 `defhsla`

`defhsla varname h s l a`

Similar to `sethsla`, but instead of establishing the color for stroke and fill operations, the computed color is assigned to the variable varname.

varname can then be used as a color for `setcolor` and `colorstop`.

See `sethsla` for more details on how the color is computed.

## 4.12 `defrgba`

`defrgba varname r g b a`

Computes a color from the red, green, blue, and alpha components, and assigns it to the variable varname.

All components are values between `0` and `1`. Values outside that range are clamped to it.

## 4.13 `ellipse`

`ellipse cx cy rx ry` — Can be implicit

Adds an ellipse to the current path. Similar to `circle`, but it is possible to use different radius for both axes.

Example

    ellipse 120 120 75 50
    stroke

## 4.14 `fill`, `eofill`

`fill, eofill`

Fill the current path, using the current pattern (either a solid color or a gradient).

`eofill` uses the even–odd rule. See fill rules for more details.

The path is cleared after the operation, unless the `preserve` command is used before `fill` or `eofill`.

See the documentation of the `cairo_fill` function for more details.

## 4.15 `getmetadata`

`getmetadata varname key`

Get the value of a metadata entry created by another filter, and assign it to the variable varname.

If there is no metadata entry for key, or its value is not a number, varname is set to `NaN`.

See the Frame Metadata section above for an example.

## 4.16 `H`, `h`

`H, h x` — Can be implicit

Draw a horizontal line from the current point to x.

The coordinate for `H` is absolute, and for `h` it is relative to the current point.

## 4.17 `if`

`if condition { block }`

Executes a block if the value of condition is not zero, and a finite number (unlike `NaN`).

See the Comparison and Logical Operators section above for more details on how to write conditional expressions.

## 4.18 `lineargrad`

`lineargrad x0 y0 x1 y1`

Set the current pattern to a new linear gradient, along the line from the coordinates x0, y0 to x1, y1.

This gradient can be used for stroke and fill operations.

Use `colorstop` to set the color for each position in the gradient.

## 4.19 `L`, `lineto`

`L, lineto x y` — Can be implicit

Draw a line from the current point to the coordinates at x, y.

See the documentation of the `cairo_line_to` function for more details.

## 4.20 `l`, `rlineto`

`l, rlineto dx dy` — Can be implicit

Like `lineto`, but the coordinates are relative to the current point.

## 4.21 `M`, `moveto`

`M, moveto x y` — Can be implicit

Begin a new sub-path, and set the current point to x, y.

## 4.22 `m`, `rmoveto`

`m, rmoveto dx dy` — Can be implicit

Like `moveto`, but the coordinates are relative to the current point.

## 4.23 `newpath`

`newpath`

Begin a new sub-path. Like `moveto`, but there is no current point after it.

Example In the next example, `newpath` is used in the path on the right to prevent the line connecting both arcs.

    setlinewidth 3

    setcolor skyblue
    arcn 70 90 20 0 (PI)
    arc 70 150 20 0 (PI)
    stroke

    setcolor seagreen
    arcn 170 90 20 0 (PI)
    newpath
    arc 170 150 20 0 (PI)
    stroke

## 4.24 `preserve`

`preserve`

Indicates that the next operation to fill, stroke, or clip, must preserve the path, so the same path can be used in multiple operations.

It has effect on these commands:

- `clip`
- `eoclip`
- `eofill`
- `fill`
- `stroke`

The script can contain any command between `preserve` and the associated operation. This allows modifying other properties, like the current color.

Example In this example, the same path is used for both `fill` and `stroke`, but with different colors.

    circle (w / 2) (h / 2) (w / 3)

    setcolor skyblue
    preserve fill

    setlinewidth 10
    setcolor seagreen
    stroke

`preserve` can be called multiple times, if the same path has to be used in 3 or more operations.

Example In this example, the path created by `circle` is used by `fill`, `stroke`, and `clip`. After `clip`, the path is cleared.

    circle 100 100 50

    preserve fill
    preserve stroke
    clip

## 4.25 `print`

`print expr` — Can be implicit

Print its arguments to the FFmpeg log.

See the Command print section above for more details.

## 4.26 `proc`

`proc name params* { block }`

Assign the block and the parameters for the procedure name. The procedure can be called multiple times with the `call` command.

See the Procedures section above for more details.

## 4.27 `Q`

`Q x1 y1 x y`

Draw a quadratic Bézier curve from the current point to the end point specified by x, y. The control point is specified by x1, y1.

The behaviour is identical to the `Q` command in SVG’s `<path>`. For more details, see Quadratic Bézier curve on MDN, and the Curve Commands section of the Paths tutorial on MDN.

Example

    moveto 20 20

    Q
        0 h                 // control point
        (w - 20) (h - 20)   // end point

    stroke

## 4.28 `q`

`q dx1 dy1 dx dy`

Like `Q`, but the coordinates are relative to the current point.

## 4.29 `radialgrad`

`radialgrad cx0 cy0 radius0 cx1 cy1 radius1`

Creates a new radial gradient between the two circles defined by cx0 cy0 radius0 and cx1 cy1 radius1. Each set of arguments is the coordinates of the center and the radius.

This gradient can be used for stroke and fill operations.

Use `colorstop` to set the color for each position in the gradient.

Example The animation in the next example shows how the two circles defined in the `radialgrad` arguments interact with each other.

The red circle represent the circle for the cx0 cy0 radius0 arguments, and the yellow circle is the one for the cx1 cy1 radius1 arguments.

    setvar cx0 (mod(t * 30, w))
    setvar cy0 120
    setvar radius0 20

    setvar cx1 120
    setvar cy1 120
    setvar radius1 70

    radialgrad
        cx0 cy0 radius0
        cx1 cy1 radius1

    colorstop
        0 lightblue
        1 darkblue

    // Fill the frame with the gradient.
    rect 0 0 w h
    fill

    // Draw inner circle.
    circle cx0 cy0 radius0
    setcolor red
    stroke

    // Draw outer circle.
    circle cx1 cy1 radius1
    setcolor yellow
    stroke

## 4.30 `rect`

`rect x y width height`

Adds a rectangle of the given size (width × height), at position x, y, to the current path. The current point is cleared before and after adding the rectangle.

See the documentation of the `cairo_rectangle` function for more details.

## 4.31 `repeat`

`repeat count { block }`

Executes a block the number of times indicated by count.

In each iteration, the variable i is used as a loop counter. It takes the values from `0` to `count - 1`. When the loop is terminated, the variable is restored to the value before starting the loop.

If count is less than `1`, or it is not a finite number (like `NaN`), the block is not executed.

## 4.32 `resetclip`

`resetclip`

Reset the current clip region to its original state, covering the whole frame.

See the documentation of the `cairo_reset_clip` function for more details.

## 4.33 `resetdash`

`resetdash`

Disable the dash pattern to be used by `stroke`. This reverts any change made by `setdash` and `setdashoffset`.

It calls `cairo_set_dash` with `num_dashes` set to `0`.

## 4.34 `resetmatrix`

`resetmatrix`

Resets the current transformation matrix.

## 4.35 `restore`

`restore`

Restores the state saved by a preceding call to `save`.

For more details, see the State Stack section above, and the `cairo_restore` function.

## 4.36 `rotate`

`rotate angle`

Modifies the current transformation matrix by rotating the user-space axes by angle radians.

See the documentation of the `cairo_rotate` function for more details.

Example In this example:

- `scalexy` maps the coordinates to a 1x1 frame.
- `translate` put `0, 0` at the center of the frame.
- `rotate` rotates 45°.
- `resetmatrix` reverts the transformations before `stroke`, so the line width is not affected by the scale.

    scalexy w h
    translate 0.5 0.5
    rotate (PI / 4)
    rect -0.25 -0.25 0.5 0.5
    resetmatrix
    stroke

## 4.37 `roundedrect`

`roundedrect x y width height radius` — Can be implicit

Like `rect`, but a circular arc is used for the corners.

Example The next example shows the same rectangle, with different values for the corner radius.

The radius is computed by multiplying i (the loop counter) by `4.5`. This number is chosen to make the last shape a perfect circle.

    repeat 9 {
        roundedrect
            (mod(i, 3) * 80 + 5)     // x
            (floor(i / 3) * 80 + 5)  // y
            70 70                    // size
            (i * 4.5)                // radius
    }

    stroke

## 4.38 `save`

`save`

Saves a copy of the current state on an internal stack. This copy can be restored later with `restore`.

For more details, see the State Stack section above, and the `cairo_save` function.

## 4.39 `scale`

`scale sxy`

Similar to `scalexy`, but the same value is used for both axes. It is equivalent to:

`scalexy sxy sxy`

## 4.40 `scalexy`

`scalexy sx sy`

Modifies the current transformation matrix by scaling the X and Y user-space axes by sx and sy respectively.

See the documentation of the `cairo_scale` function for more details.

See `rotate` for an example on combining multiple transformations.

## 4.41 `setcolor`

`setcolor color`

Set a solid color as the current pattern for stroke and fill operations

See the Colors section above for more details.

## 4.42 `setdash`

`setdash length` — Can be implicit

Sets the dash pattern to be used by `stroke`.

Each call to `setdash` adds a length to the pattern, alternating between on and off portions of the stroke.

After a call to `setdash`, `resetdash` is needed either to create a new pattern, or to discard the current one.

See the documentation of the `cairo_set_dash` function for more details.

## 4.43 `setdashoffset`

`setdashoffset offset`

Set the offset into the dash pattern at which the stroke should start.

`setdash` must be called before `setdashoffset`.

See the documentation of the `cairo_set_dash` function for more details.

Example The next animation shows the effect of `setdashoffset` when its argument changes over time.

    scalexy w h
    M 0.5 1
    curveto 0 0.5, 1 0.5, 0.5 0
    resetmatrix

    setdash 20 5 // 20 on, 5 off
    setdashoffset (t * 100)

    setlinewidth 20
    stroke

## 4.44 `sethsla`

`sethsla h s l a`

Set the current pattern to a solid color, given the hue, saturation, and lightness, and alpha components.

h is the hue, a value between `0` and `359`. Negative values are clamped to `0`, and values greater than `359` are interpreted as modulo 360.

s (saturation), l (lightness), and a (alpha), are values between `0` and `1`.

The conversion to RGB is implemented according to the formulae from Wikipedia.

## 4.45 `setlinecap`

`setlinecap cap`

Set the current line cap style, which determines the shape used to draw the end points of lines.

cap must be one of the following names:

- `butt`
- `round`
- `square`

It calls to `cairo_set_line_cap` to set the line cap style.

Example This example draws 3 lines with the same length, each one with a different line cap style:

    setlinewidth 40

    setlinecap butt
    setcolor tomato
    M 60 40 v 100 stroke

    setlinecap round
    setcolor seagreen
    M 120 40 v 100 stroke

    setlinecap square
    setcolor skyblue
    M 180 40 v 100 stroke

    M 20 40 H 220 m 0 100 H 20
    setcolor black@0.5
    setlinewidth 2
    stroke

## 4.46 `setlinejoin`

`setlinejoin join`

Sets the current line join style, which determines the shape used to join two line segments.

join must be one of the following names:

- `bevel`
- `miter`
- `round`

It calls to `cairo_set_line_join` to set the line join style.

Example This example draws 3 lines with the same length, each one with a different line join style:

    setlinewidth 30

    setlinejoin bevel
    setcolor tomato
    M 70 20 l 50 50 50 -50 stroke

    setlinejoin miter
    setcolor seagreen
    M 70 90 l 50 50 50 -50 stroke

    setlinejoin round
    setcolor skyblue
    M 70 160 l 50 50 50 -50 stroke

## 4.47 `setlinewidth`

`setlinewidth width`

Set the line width for `stroke`.

width is affected by the transformation matrix.

To specify a width that is not affected by other transformations, `resetmatrix` can be used between `save` / `restore`:

    save

    resetmatrix
    setlinewidth 1
    stroke

    // Restore matrix after stroke.
    restore

See the documentation of the `cairo_set_line_width` function for more details.

## 4.48 `setrgba`

`setrgba r g b a`

Set the current pattern to a solid color, given the red, green, blue, and alpha components.

All components are values between `0` and `1`. Values outside that range are clamped to it.

## 4.49 `setvar`

`setvar varname value`

Set the variable varname to value.

See the User Variables section above for more details.

## 4.50 `stroke`

`stroke`

Strokes the current path according to the current line width, line join, line cap, and dash settings.

The path is cleared after the operation, unless the `preserve` command is used before `stroke`.

See the documentation of the `cairo_stroke` function for more details.

## 4.51 `S`, `s`

`S, s x2 y2 x y` — Can be implicit

Draw a smooth cubic Bézier curve from the current point to the end point specified by x, y. The end control point is specified by x2, y2.

The start control point is the reflection of the end control point of the previous curve command about the current point.

The behaviour is identical to the `S` command in SVG’s `<path>`. For more details, see Cubic Bézier Curve on MDN, and the Curve Commands section of the Paths tutorial on MDN.

`s` is like `S`, but the coordinates are relative to the current point.

Example

    M 20 120

    c 25 -50, 25 50, 50 0

    repeat 3 {
        s 20 50, 50 0
    }

    stroke

## 4.52 `translate`

`translate tx ty`

Modifies the current transformation matrix by translating the user-space origin by tx, ty.

See the documentation of the `cairo_translate` function for more details.

## 4.53 `T`, `t`

`T, t x y` — Can be implicit

Draw a smooth quadratic Bézier curve from the current point to the end point specified by x, y.

The control point is the reflection of the control point of the previous curve command about the current point.

The behaviour is identical to the `T` command in SVG’s `<path>`. For more details, see Quadratic Bézier curve on MDN, and the Curve Commands section of the Paths tutorial on MDN.

`t` is like `T`, but the coordinates are relative to the current point.

Example

    M 20 120

    q 10 -20, 20 0

    repeat 9 {
        t 20 0
    }

    stroke

## 4.54 `V`, `v`

`V, v y` — Can be implicit

Draw a vertical line from the current point to y.

The coordinate for `V` is absolute, and for `v` it is relative to the current point.