Custom paths

Custom paths (shapes) can be created through JS code indicated in 'shape', either inline or through a file.  
The following GPAC JS modules are imported:  

    - `Sys` as `sys`  
    - All EVG as `evg`  
    - `os` form QuickJS  

  
See [https://doxygen.gpac.io]() for more information on EVG and Sys JS APIs.  
  
The code is exposed the scene as `this`. The variable `this.path` is created, representing an empty path.  
Example
```
"shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0, this.width, this.height/3); this.path.add_path(el);"
```
  
  
The default behaviour is to use the shape width and height as reference size for texture mapping.  
If your custom path is textured, with bounding rectangle size different from the indicated shape size, set the variable `this.tx_adjust` to true.  
  
In the previous example, the texture mapping will not be impacted by the custom path size.  
  
Example
```
"shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0, this.width, this.height/3); this.path.add_path(el); this.tx_adjust = true;"
```
  
In this example, the texture mapping will be adjusted to the desired size.  
  
The global variables and functions are available (c.f. `gpac -h avmix:global`):  

    - get_media_time(): return media time in seconds (float) of output  
    - get_media_time(SRC): get time of source with id `SRC`, return -4 if not found, -3 if not playing, -2 if in prefetch, -1 if timing not yet known, media time in seconds (float) otherwise  
    - current_utc_clock: current UTC time in ms  
    - video_time: output video time  
    - video_timescale: output video timescale  
    - video_width: output video width  
    - video_height: output video height  

  
If your path needs to be reevaluated on regular basis, set the value `this.reload` to the timeout to next reload, in milliseconds.  
  
Options:  

- rx (0): horizontal radius for rounded rect in percent of object width if positive, in absolute value if negative, value `y` means use `ry`  
- ry (0): vertical radius for rounded rect in percent of object height if positive, in absolute value if negative, value `x` means use `rx`  
- tl (1): top-left corner scaler (positive, 0 disables corner)  
- bl (1): bottom-left corner scaler (positive, 0 disables corner)  
- tr (1): top-right corner scaler (positive, 0 disables corner)  
- br (1): bottom-right corner scaler (positive, 0 disables corner)  
- rs (false): repeat texture horizontally  
- rt (false): repeat texture vertically  
- keep_ar (true): keep aspect ratio  
- pad_color ('0x00FFFFFF'): color to use for texture padding if `rs` or `rt` are false. Use `none` to use texture edge, `0x00FFFFFF` for transparent (always enforced if source is transparent)  
- txmx ([]): texture matrix - all 6 coefficients must be set, i.e. [xx xy tx yx yy ty]  
- cmx ([]): color transform - all 20 coefficients must be set in order, i.e. [Mrr, Mrg, Mrb, Mra, Tr, Mgr, Mgg ...]  
- line_width (0): line width in percent of width if positive, or absolute value if negative  
- line_color ('white'): line color, `linear` for linear gradient and `radial` for radial gradient  
- line_pos ('center'): line/shape positioning. Possible values are:  

    - center: line is centered around shape  
    - outside: line is outside the shape  
    - inside: line is inside the shape  

- line_dash ('plain'): line dashing mode. Possible values are:  

    - plain: no dash  
    - dash: predefined dash pattern is used  
    - dot:  predefined dot pattern is used  
    - dashdot:  predefined dash-dot pattern is used  
    - dashdashdot:  predefined dash-dash-dot pattern is used  
    - dashdotdot:  predefined dash-dot-dot pattern is used  

- dashes ([]): dash/dot pattern lengths for custom dashes (these will be multiplied by line size)  
- cap ('flat'): line end style. Possible values are:  

    - flat: flat end  
    - round: round end  
    - square: square end (extends limit compared to flat)  
    - triangle: triangle end  

- join ('miter'): line joint style. Possible values are:  

    - miter: miter join (straight lines)  
    - round: round join  
    - bevel: bevel join  
    - bevelmiter: bevel+miter join  

- miter_limit (2): miter limit for joint styles  
- dash_length (-1): length of path to outline, negative values mean full path  
- dash_offset (0): offset in path at which the outline starts  
- blit (true): use blit if possible, otherwise EVG texturing. If disabled, always use texturing  
- fill ('none'): fill color if used without sources, `linear` for linear gradient and `radial` for radial gradient  
- img (''): image for scene without sources or when `replace` is set. Accepts either a path to a local image (JPG or PNG), the ID of an offscreen group or the ID of a sequence  
- alpha (1): global texture transparency  
- replace (''): if `img` or `fill` is set and shape is using source, set multi texture option. Possible modes are:  

    - a, r, g or b: replace alpha source component by indicated component from `img` . If prefix `-` is set, replace by one minus the indicated component  
    - m: mix using `mix_ratio` the color components of source and `img` and set alpha to full opacity  
    - M: mix using `mix_ratio` all components of source and `img`, including alpha  
    - xC: mix source 1 and source 2 using `img` component `C` (`a`, `r`, `g` or `b`) and force alpha to full opacity  
    - XC: mix source 1 and source 2 using `img` component `C` (`a`, `r`, `g` or `b`), including alpha  

  

- shape ('rect'): shape type. Possible values are:  

    - rect: rounded rectangle  
    - square: square using smaller width/height value  
    - ellipse: ellipse  
    - circle: circle using smaller width/height value  
    - rhombus: axis-aligned rhombus  
    - text: force text mode even if text field is empty  
    - rects: same as rounded rectangle but use straight lines for corners  
    - other value: JS code for custom path creation, either string or local file name (dynamic reload possible)  

- grad_p ([]): gradient positions between 0 and 1  
- grad_c ([]): gradient colors for each position, as strings  
- grad_start ([]): start point for linear gradient or center point for radial gradient  
- grad_end ([]): end point for linear gradient or radius value for radial gradient  
- grad_focal ([]): focal point for radial gradient  
- grad_mode ('pad'): gradient mode. Possible values are:  

    - pad: color padding outside of gradient bounds  
    - spread: mirror gradient outside of bounds  
    - repeat: repeat gradient outside of bounds  

- text ([]): text lines (UTF-8 only). If not empty, force `shape=text`  
- font ([]): font name(s)  
- size (20): font size in percent of height (horizontal text) or width (vertical text), or absolute value if negative  
- baseline ('alphabetic'): baseline position. Possible values are:  

    - alphabetic: alphabetic position of baseline  
    - top: baseline at top of EM Box  
    - hanging: reserved, _not implemented_  
    - middle: baseline at middle of EM Box  
    - ideograph: reserved, _not implemented_  
    - bottom: baseline at bottom of EM Box  

- align ('center'): horizontal text alignment. Possible values are:  

    - center: center of shape  
    - start: start of shape (left or right depending on text direction)  
    - end: end of shape (right or left depending on text direction)  
    - left: left of shape  
    - right: right of shape  

- spacing (0): line spacing in percent of height (horizontal text) or width (vertical text), or absolute value if negative  
- bold (false): use bold version of font  
- italic (false): use italic version of font  
- underline (false): underline text  
- vertical (false): draw text vertically  
- flip (false): flip text vertically  
- extend (0): maximum text width in percent of width (for horizontal) or height (for vertical), or absolute value if negative  
- keep_ar_rep (true): same as `keep_ar` for local image in replace mode  
- txmx_rep ([]): same as `txmx` for  local image in replace mode  
- cmx_rep ([]): same as `cmx` for local image in replace mode  
- pad_color_rep ('none'): same as `pad_color` for local image in replace mode  
- rs_rep (false): same as `rs` for local image in replace mode  
- rt_rep (false): same as `rt` for local image in replace mode