forked from mia/Aegisub
0211960d8e
Originally committed to SVN as r1475.
133 lines
3.9 KiB
Text
133 lines
3.9 KiB
Text
OverLua provides a Lua 5.1 runtime environment with access to all
|
|
standard libraries.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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.box3(surface, repetitions)
|
|
raster.box5(sutface, repetitions)
|
|
raster.box15(surface, repetitions)
|
|
|
|
Applies a box filter (blur) of various sizes 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.
|
|
|
|
|
|
More filtering functions are planned, though no specifics yet.
|
|
|
|
Wishes/suggestions are welcome, and so are patches to add more functions.
|