forked from mia/Aegisub
230 lines
7.1 KiB
Text
230 lines
7.1 KiB
Text
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.
|
|
A Ditto, for alpha component. (Only on ARGB32 surfaces.)
|
|
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.
|