Aegisub/OverLua/docs/overlua.txt

OverLua provides a Lua 5.1 runtime environment with access to all
standard libraries.


The Avisynth filter
-------------------

The Avisynth filter version of OverLua exports one function:

  OverLua(clip c, string scriptfile, string "datastring", string "vfrfile")

The clip c argument is self-explanatory, the clip to render on.

The scripfile is the path to the Lua script you want to load and run.

datastring is a freeform string to pass to the Lua script. This will often
be the path to a file with additional data for the script, such as timed
subtitles/karaoke.

vfrfile is the path to a timecode file Matroska format 1 or 2. If supplied,
it will be used to translate frame numbers to timestamps instead of relying
on the frame rate provided by Avisynth.


API the Lua script must implement
---------------------------------

Any initialisation, such as loading external data files, should be done
in the Lua script's global environment.

OverLua expects one function in the script:

function render_frame(frame, timestamp)

The function name must be literal "render_frame". It must not be local.

The "frame" parameter is a userdata object representing the video frame
there must be rendered to. Other functions take this object as parameter.

The "timestamp" parameter is a value of type "number", representing the
timestamp of the frame to be rendered, in seconds. The timestamp may be
non-integer with any precision.

The render_frame function should not return anything. Instead it modifies
the frame object.

The render_frame function should not assume that frames are requested in
any specific order.


If a "datastring" argument is supplied to the OverLua Avisynth function, the
argument value will be available through the global variable
"overlua_datastring" in the Lua script environment.


The frame object
----------------

The "frame" object passed to the render_frame function has a number of
fields accessible.

The frame is always stored as RGB. No alpha channel is supported.


frame.width

An integer number storing the width of the frame in pixels.

Read only.


frame.height

An integer number storing the height of the frame in pixels.

Read only.


red, green, blue = frame(x, y)

"red", "green" and "blue" will be numbers in range 0..255 that will receive
the respective colour channel values for the requested pixel.
"x" and "y" are the pixel coordinates for the pixel to retrieve
Pixel coordinates are counted from zero and start in the upper left corner.
A pixel with coordinates (X, Y) has pixel number Y*frame.width+X.


frame[n] = {red, green, blue}

Set the value of the given pixel.

The table on the right side of the equal sign must have at least three
entries which must all be numbers. They are taken as red, green and blue
values respectively, in regular enumeration order.
"n" is the pixel number to be set.
A pixel with coordinates (X, Y) has pixel number Y*frame.width+X.

Using a table constructor as shown is recommended.


surface = frame.create_cairo_surface()

Create a cairo rgb24 surface from the video frame. Drawing to the surface
will _not_ affect the video frame. If you want the changes to the surface
visible on the video you will need to overlay this surface on the video.


frame.overlay_cairo_surface(surface, x, y)

Overlay the given cairo surface at the video frame such that the upper,
left corner of the surface is positioned at pixel (x, y) on the video.
Only argb32 and rgb24 type surfaces are supported.
Proper alpha blending is used for argb32 surfaces.


Setting a pixel value for a pixel outside the frame has no effect.
Specifically, it will not produce an error or a warning message.

Reading a pixel value for a pixel outside the frame will return black,
ie. (0, 0, 0).


Vector graphics interface
-------------------------

OverLua uses the cairo library for all vector graphics handling, including
text handling.

See lua-cairo.txt for details.


Raster graphics processing interface
------------------------------------

A raster graphics processing interface is also provided, to post-process
the graphics produced by the vector graphics interface.

The raster graphics interface operates directly on cairo surfaces.


raster.gaussian_blur(surface, sigma)

Applies a strength sigma gaussian blur on the surface.


raster.box_blur(surface, size, repetitions)

Applies a box blur filter of variable size to the surface as many times as
specified. Please note that no specific optimisation is done for applying
box filters over more general filters and using box blur over gaussian blur
is probably no faster and might even be slower.


raster.directional_blur(surface, angle, sigma)

Apply a variable strength directional gaussian kernel blur to the image.
Also known as motion blur. The angle is given in radians.


raster.radial_blur(surface, cx, cy, sigma)

Apply a variable strength radial gaussian blur centered on pixel (cx,cy).


raster.invert(surface)

Invert the colour in the given surface.

For ARGB32 surfaces, only the colour channels are inverted, the alpha
channel is kept as-is.
For RGB24 surfaces, all channels are inverted.
For A8 and A1 surfaces the alpha is inverted.


raster.separable_filter(surface, filter, divisor)

Apply a custom separable filter over the image.

The filter must be a table of integers. After the convoluted value of each
pixel is calculated, it is divided by divisor before it's stored back to the
image.

Note that this function can only work on integers, floating point values in
the filter or divisor will be rounded first. To get higher precision, scale
up the filter and divisor. (Treat it as fixed-point math.)

The filter is one-dimensional, but is applied first horizontally and then
vertically ovre the image to get the final image.


raster.pixel_value_map(surface, expression)

Map an expression over every pixel RGB value in the surface. Only works for
ARGB32 and RGB24 surfaces.

The expression is an RPN expression in the OverLua Expression Evaluator
language, see expression-evaluator.txt for details.

No additional functions are made available to the expression evaluator by
this function.

The following new registers are made available to the expression evaluator:
  R  In range 0..1, red component. Input and output.
  G  Ditto, for green component.
  B  Ditto, for blue component.
  X  X-coordinate of pixel being processed. Input only.
  Y  Y-coordinate of pixel being processed. Input only.


raster.pixel_coord_map(surface, expression)

Map each pixel coordinate pair to a new coordinate pair in the surface. Only
works for ARGB32 and RGB24 surfaces.

The expression is an RPN expression in the OverLua Expression Evaluator
language, see expression-evaluator.txt for details.

No additional functions are made available to the expression evaluator by
this function.

The following new registers are made available to the expression evaluator:
  X  Absolute pixel X coordinate. Input and output. The output may be
     non-integer, in that case bilinear interpolation is used.
  Y Ditto, for Y coordinate.


More filtering functions are planned, though no specifics yet.

Wishes/suggestions are welcome, and so are patches to add more functions.