forked from mia/Aegisub
292 lines
7.5 KiB
Text
292 lines
7.5 KiB
Text
Documentation for the Cairo interface provided in OverLua
|
|
=========================================================
|
|
|
|
First, this file will mostly attempt to describe the differences between the
|
|
Cairo C API and the provided Lua API. If you want more general and in-depth
|
|
information on Cairo, please see the documentation for the C API:
|
|
|
|
<http://cairographics.org/manual/>
|
|
|
|
|
|
Note that almost all of the *_reference functions are unimplemented currently.
|
|
They should not be explicitly needed since Lua does its own management on
|
|
objects as well, you can just copy and keep a Lua Cairo object and be
|
|
guaranteed the underlying Cairo object won't be deleted until all Lua objects
|
|
referring to it are gone.
|
|
There are no *_destroy and *_get_reference_count functions either,
|
|
for this reason.
|
|
|
|
Finally the *_user_data functions are also removed from the API.
|
|
|
|
|
|
Conventions in this file
|
|
------------------------
|
|
|
|
Variable name Cairo object
|
|
|
|
surf Surface (cairo_surface_t)
|
|
ctx Context (cairo_t)
|
|
face Font face (cairo_font_face_t)
|
|
sf Scaled font (cairo_scaled_font_t)
|
|
fo Font options (cairo_font_options_t)
|
|
mat Matrix (cairo_matrix_t)
|
|
path Path (cairo_path_t)
|
|
pat Pattern (cairo_pattern_t)
|
|
x, y Coordinates
|
|
r, g, b, a Colour values (red, green, blue, alpha)
|
|
|
|
|
|
If more than one of an object type is used they will get numeric suffixes.
|
|
For matrix operations you might also see "matR", this is "result matrix".
|
|
|
|
|
|
More "OO-like" syntax
|
|
---------------------
|
|
|
|
This Lua Cairo API provides a more common "OO-like" syntax for calls.
|
|
For example, the cairo_set_source_surface(ctx, surf, x, y) function maps to
|
|
ctx.set_source_surface(surf, x, y).
|
|
|
|
|
|
Creating initial objects
|
|
------------------------
|
|
|
|
Many of the objects you will use are created from or by other objects, but
|
|
you will need to create some non-dependant objects, most importantly image
|
|
surface objects. All the object creation functions live in the global "cairo"
|
|
table.
|
|
|
|
|
|
surf = cairo.image_surface_create(width, height, pixel_format)
|
|
|
|
Create a blank image surface object.
|
|
|
|
width and height are in pixels. pixel_format is a string and must be one
|
|
of "argb32", "rgb24", "a8" and "a1".
|
|
|
|
|
|
fo = cairo.font_options_create()
|
|
|
|
Create a new font options object.
|
|
|
|
|
|
mat = cairo.matrix_create()
|
|
|
|
Create a new matrix. It is initially the identity matrix.
|
|
|
|
|
|
pat = cairo.pattern_create_rgb(r, g, b)
|
|
pat = cairo.pattern_create_rgba(r, g, b, a)
|
|
pat = cairo.pattern_create_for_surface(surf)
|
|
pat = cairo.pattern_create_linear(x0, y0, x1, y1)
|
|
pat = cairo.pattern_create_radial(x0, y0, r0, x1, y1, r1)
|
|
|
|
Create various kinds of pattern objects.
|
|
|
|
|
|
ctx = surf.create_context()
|
|
|
|
Not strictly an "initial object", but Cairo context objects are important
|
|
enough to explicitly list here. They are created by calling the
|
|
create_context() method in a surface object. This will create a context
|
|
object that draws to the surface it was created with.
|
|
|
|
|
|
Other functions that have changed API
|
|
-------------------------------------
|
|
|
|
Some functions have changed API to better match the Lua programming model.
|
|
|
|
|
|
ctx.set_dash()
|
|
ctx.set_dash(0)
|
|
ctx.set_dash(num[, offset])
|
|
ctx.set_dash(dashes[, offset])
|
|
|
|
There are several forms of the set_dash function. The two first disable
|
|
dashing entirely.
|
|
|
|
The third creates a repeating pattern of equal length on and off potions,
|
|
each "num" units long. The offset argument is optional, its default is 0.
|
|
|
|
The last creates a complex pattern. "dashes" must be a table of numbers
|
|
describing the dashing pattern. offset is optional, default is 0.
|
|
|
|
|
|
dashes, offset = ctx.get_dash()
|
|
|
|
Returns current dashing setting, in same format as the last form of set_dash
|
|
takes. If dashing is disabled, dashes will be an empty table.
|
|
|
|
(You won't need to use the ctx.get_dash_count() function.)
|
|
|
|
|
|
x0, y0, x1, y1 = ctx.clip_extents()
|
|
x0, y0, x1, y1 = ctx.fill_extents()
|
|
x0, y0, x1, y1 = ctx.stroke_extents()
|
|
|
|
Return the smallest rectangle bounding the area that would be affected if
|
|
performing a clip/fill/stroke operation.
|
|
|
|
|
|
x, y = ctx.get_current_point()
|
|
|
|
Get the current point for path gneration operations.
|
|
|
|
|
|
mat = ctx.get_matrix()
|
|
|
|
Get the current geometry transformation matrix.
|
|
|
|
|
|
x, y = ctx.user_to_device(x, y)
|
|
x, y = ctx.user_to_device_distance(x, y)
|
|
x, y = ctx.device_to_user(x, y)
|
|
x, y = ctx.device_to_user_distance(x, y)
|
|
|
|
Returns the transformation of a point between device and user-space
|
|
coordinates.
|
|
|
|
|
|
offset, r, g, b, a = pat.get_color_stop_rgba(index)
|
|
|
|
Returns nothing if the pattern is not a gradient pattern or the stop index
|
|
is out of range.
|
|
|
|
|
|
r, g, b, a = pat.get_rgba()
|
|
|
|
Returns nothing if the pattern is not a solid colour fill pattern.
|
|
|
|
|
|
surf = pat.get_surface()
|
|
|
|
Returns nothing if the pattern is not a surface pattern.
|
|
|
|
|
|
x0, y0, x1, y1 = pat.get_linear_points()
|
|
|
|
Returns nothing if the pattern is not a linear gradient pattern.
|
|
|
|
|
|
x0, y0, r0, x1, y1, r1 = pat.get_radial_circles()
|
|
|
|
Returns nothing if the pattern is not a radial gradient pattern.
|
|
|
|
|
|
extents = ctx.font_extents()
|
|
extents = sf.font_extents()
|
|
|
|
Get extents metrics for current font. The returned object is a Lua table
|
|
with fields identical to the C struct cairo_font_extents_t.
|
|
|
|
|
|
extents = ctx.tex_extents(utf8)
|
|
extents = sf.text_extents(utf8)
|
|
|
|
Get extents metrics for writing text given in utf8 with current font. The
|
|
returned object is a Lua table with fields identical to the C
|
|
struct cairo_text_extents_t.
|
|
|
|
|
|
fo = sf.get_font_options()
|
|
|
|
Get font options for a scaled font.
|
|
|
|
|
|
mat = sf.get_font_matrix()
|
|
|
|
Get text transformation matrix.
|
|
|
|
|
|
mat = sf.get_ctm()
|
|
|
|
Get the CTM. (Character transformation matrix?)
|
|
|
|
|
|
fo1.merge(fo2)
|
|
|
|
Merge font options fo2 into fo1.
|
|
|
|
|
|
hash = fo.hash()
|
|
|
|
Returns a hexadecimal string hash of fo.
|
|
|
|
|
|
fo1.equal(fo2)
|
|
|
|
Return true is fo1 equals fo2.
|
|
|
|
|
|
fo = surf.get_font_options()
|
|
|
|
Get current font options for surface.
|
|
|
|
|
|
x, y = surf.get_device_offset()
|
|
|
|
Get current device offset for surface.
|
|
|
|
|
|
a, r, g, b = surf.get_pixel(x, y)
|
|
r, g, b = surf.get_pixel(x, y)
|
|
a = surf.get_pixel(x, y)
|
|
|
|
Get colour value of a pixel on an image surface. This function replaces the
|
|
cairo_image_surface_get_data(surf) function for reading surface contents.
|
|
The number and meanings of return values depend on the surface pixel format.
|
|
|
|
surf.set_pixel() is not implemented yet.
|
|
|
|
|
|
matR = mat.copy()
|
|
|
|
Duplicate a matrix. Not in Cairo C API.
|
|
|
|
|
|
mat.xx, mat.yx, mat.xy, mat.yy, mat.x0, mat.y0
|
|
|
|
Access the individual numbers in a matrix. These are both read and write.
|
|
|
|
|
|
Functional programming on path objects
|
|
--------------------------------------
|
|
|
|
The path object still hasn't been completely implemented, but two useful
|
|
functions do exist for it. These are functional programming style map and
|
|
fold functions.
|
|
|
|
|
|
path.map_coords(func)
|
|
|
|
Transform every coordinate pair in path using func.
|
|
|
|
func must be a function of type (x,y)->(x,y) ie. takes two arguments which
|
|
are the x and y coordinates of the point and returns two numbers which are
|
|
the new x and y coordinates of the point.
|
|
|
|
Example: Produce a "wavy" effect.
|
|
path.map_coords(function(x,y) return math.sin(x), math.cos(y) end)
|
|
|
|
|
|
res = path.fold_coords(func, start)
|
|
|
|
Produce a value by combining all the coordinate pairs using func.
|
|
|
|
func must be a function of type (r,x,y)->(r) ie. takes three argument which
|
|
are the current result and the x/y coordinates of the point, and returns a
|
|
new result.
|
|
When all points have been processed path.fold_coords returns the final result.
|
|
|
|
Example: Find the maximum X coordinate.
|
|
maxx = path.fold_coords(
|
|
function(maxx,x,y)
|
|
if not maxx then
|
|
return x
|
|
elseif x > maxx then
|
|
return x
|
|
else
|
|
return maxx
|
|
end
|
|
end, nil)
|