lua-oocairo-scaledfont(3) [debian man page]

doc::lua-oocairo-scaledfont(3)				       Lua OO Cairo binding				    doc::lua-oocairo-scaledfont(3)

Name
       lua-oocairo-scaledfont - Scaled font face object

Introduction
       Scaled font objects represent Cairo font faces which have been scaled to a particular point size.  They can be created from a font face
       object with the "scaled_font_create" function in the main module table (see lua-oocairo(3)), or the "get_scaled_font" method on context
       objects (see lua-oocairo-context(3)).

       Scaled font objects can be compared with the "==" operator.  This will compare the identity of the objects, so different Lua objects which
       refer to the same "cairo_font_face_t" will compare as equal.

Methods
       Scaled font objects provide the following methods.

       font:extents ()
	   Returns a table containing metrics information about the font.  The return value is in the same format as that of the "font_extents"
	   method on context objects (see lua-oocairo-context(3)).

       font:get_ctm ()
	   Returns the coordinate transformation matrix (CTM) associated with the font.  This maps user coordinates into device coordinates on the
	   surface with which the font is used.  See lua-oocairo-matrix(3) for details of the return value type.

       font:get_font_face ()
	   Returns an object representing the unscaled font face used to create this font.  See lua-oocairo-fontface(3) for details of its
	   methods.

       font:get_font_matrix ()
	   Returns the matrix representing the scaling of the font into user coordinates.  See lua-oocairo-matrix(3) for details of the return
	   value type.

       cr:get_font_options ()
	   Returns a font options object (see lua-oocairo-fontopt(3)) containing the rendering options that were supplied when creating this font.

       font:get_scale_matrix ()
	   Returns a matrix table representing the scaling of the font to the coordinate space of the surface it is used on.  This is the matrix
	   obtained by multiplying the font matrix by the surface CTM.	See lua-oocairo-matrix(3) for details of the return value type.  Only
	   available with Cairo 1.8 or better.

       font:get_type ()
	   Returns a string indicating which back-end library provides the font face information.  The return value will be one of the same
	   strings returned by the "get_type" method on a font face object (see lua-oocairo-fontface(3)).

       font:glyph_extents (glyphs)
	   Same as "font:text_extents()", but instead of a string, the glyphs value should be table in the format accepted by the "show_glyphs()"
	   method on context objects (see lua-oocairo-context(3)).

       font:text_extents (text)
	   Returns a table containing measurements of the given UTF-8 text as it would be rendered in this font.  The return value is in the same
	   format as that of the "text_extents" method on context objects (see lua-oocairo-context(3)).

       font:text_to_glyphs (x, y, text)
	   Given some UTF-8 text in the string text, and starting coordinates of x and y, this works out which glyphs need to be drawn to
	   represent the text, and which glyphs correspond to the bytes in text.  The method returns two tables, the first an array of glyphs
	   suitable for supplying to methods like "show_glyphs" and "glyph_extents", and the second is a table of text clusters suitable for
	   supplying to the "show_text_glyphs" method on a context object.

	   Only available with Cairo 1.8 or better.

1.4								    2011-05-18					    doc::lua-oocairo-scaledfont(3)

doc::lua-oocairo(3)					       Lua OO Cairo binding					       doc::lua-oocairo(3)

Name
       lua-oocairo - Lua API for the Cairo vector graphics library

Introduction
       This is a Lua binding for the Cairo graphics library, with an object oriented style of API.  There is at least one other Cairo binding
       available in Lua, but it has a more C-like API and is much less complete.

Simple Example
       The code below is a complete example showing how to load this module and do some basic drawing with it.	Other features are demonstrated by
       the files in the examples directory included with the module.

       First load the module.  The module doesn't create a global variable, so you have to assign it to something.

	   local Cairo = require "oocairo"

       Create a bitmap image surface for drawing on, and create a context object which is used to do the drawing:

	   local surface = Cairo.image_surface_create("rgb24", 200, 200)
	   local cr = Cairo.context_create(surface)

       Fill whole image with white.  The "paint" method will copy the whole of the source to the surface.  In this case the source is a solid
       colour, but it can be other things like an image or gradient.  The default source is solid fully opaque black.  Since the default colour of
       the image surface is also black, nothing would happen if we didn't set the source to something else before painting.

	   cr:set_source_rgb(1, 1, 1)
	   cr:paint()

       Define an arbitrary shape, then fill it in purple.  The "move_to" and "line_to" methods, among others, define the shape of the path which
       is used for drawing operations like filling.

	   cr:move_to(0, 0)
	   cr:line_to(190, 100)
	   cr:line_to(100, 185)
	   cr:line_to(200, 200)
	   cr:line_to(30, 130)
	   cr:close_path()
	   cr:set_source_rgb(0.8, 0.4, 1)
	   cr:fill()

       Another shape, this time both filled and with a line drawn along it's edge.  The path is normally discarded after a drawing operation, so
       here "fill_preserve" is used to keep it so that it can also be stoked.  Note that the stroked line won't go all the way around the filled
       area, because the path wasn't closed with "close_path".	The black outline created by the "stroke" method will be three pixels wide, and
       will be centered on the path, half of it inside the filled area.

	   cr:move_to(180, 30)
	   cr:line_to(100, 20)
	   cr:line_to(80, 120)
	   cr:set_source_rgb(0.5, 0.7, 0.3)
	   cr:fill_preserve()

	   cr:set_line_width(3)
	   cr:set_source_rgb(0, 0, 0)
	   cr:stroke()

       Finally, write the output to a file in PNG format.

	   surface:write_to_png("simple-example.png")

Surface constructor functions
       The following functions can be accessed from the module table (the table returned from "require").  One of them must be used to create a
       surface on which to draw on before Cairo can be used for anything interesting.  These all return a surface object, for which the methods
       are documented at lua-oocairo-surface(3).  Most drawing is done through a context object, which should be constructed with a call to the
       "context_create" function (also in the module table), passing the surface object as its only argument.  The methods for context objects are
       documented at lua-oocairo-context(3).

       image_surface_create (format, width, height)
	   Return a surface object for drawing an image in memory.  The width and height values must be numbers and are measured in pixels.  The
	   value of format can be any of the following strings:

	   argb32
	       Each pixel is 32 bits, encoding both colour and alpha (transparency) values.

	   rgb24
	       Each pixel is 32 bits with only 24 bits used, encoding a colour value.  All pixels are implicitly 100% opaque.

	   a8  Each pixel is a single byte encoding the alpha (transparency) value, with no colour information.

	   a1  Each pixel is a single bit encoding whether a pixel is transparent or opaque, with no colour information.

	   The image created will be black by default, and fully transparent if the pixels have an alpha component.

       image_surface_create_from_data (data, format, width, height, stride)
	   Creates a new image surface with the size width by height pixels, using format just as the "image_surface_create" function does, but
	   the image is initialized using pixel data from the string data.  The stride value should be whatever is returned from the
	   "format_stride_for_width" function for the given width and pixel format.  The data should be encoded in the format described for the
	   "surf:get_data()" method in lua-oocairo-surface(3).

	   Note that since Lua strings are immutable, a copy of the data is made and used as the live buffer.  There is currently no support for
	   sharing an image surface buffer between Cairo and something else.

	   This binds the native Cairo function "cairo_image_surface_create_for_data", but has a slightly different name because the data you
	   provide is only used at construction time, not kept around for drawing.

       image_surface_create_from_png (file/filename)
	   Creates a new image surface containing the image in a PNG file.  The file is read from the filename or file handle specified.  See
	   below for details about what kind of file handles can be used.

       pdf_surface_create (file/filename, width, height)
	   Create a surface which writes drawing instructions out to a PDF file, at the given filename or through a file handle.  The width and
	   height values must be numbers and are measured in points.

       ps_surface_create (file/filename, width, height)
	   Create a surface which writes drawing instructions out to an Adobe(tm) file, at the given filename or through a file handle.  The width
	   and height values must be numbers and are measured in points.

       surface_create_similar (surface, content, width, height)
	   Create a new surface of the same type as surface, but with the width and height specified.  The content value indicates whether the
	   surface should include colour and/or transparency information, and must be one of the following strings:

	   color
	       Surface will have only colour content.

	   alpha
	       Surface will have only transparency content.

	   color-alpha
	       Surface will have colour and transparency content.

       svg_surface_create (file/filename, width, height)
	   Create a surface which writes drawing instructions out to an SVG file, at the given filename or through a file handle.  The width and
	   height values must be numbers and are measured in points.

Other top-level functions
       The following additional methods are available.	The are rarely needed except for "context_create" and the gradient constructors.

       BYTE_ORDER
	   Not actually a function, this is a string indicating which order colour components are stored in pixels in raw image data on this
	   platform.  This will be "argb" on big-endian systems and "bgra" on little-endian ones.  This is the order in which the bytes for each
	   pixel are stored on "rgb24" and "argb32" image surfaces.  For "a1" it indicates the order the pixels are encoded as bits.  It can be
	   ignored when the image format is "a8".

       context_create (surface)
	   Return a new context object for drawing on surface.	See lua-oocairo-context(3) for methods which can be called on this object.

       context_create_gdk (drawable)
	   Return a new context object for drawing on the GdkDrawable object drawable, which must be from the Lua-Gnome library.

	   Fails unless Lua-Gnome has been loaded and the "gtk" module is available as a global variable.

	   See example programs gtk-image.lua and gtk-drawing.lua for examples of how to use this.

       font_options_create ()
	   Returns a new Cairo font options object, with all its options set to default values.  See lua-oocairo-fontopt(3) for information about
	   what you can do with it.

       format_stride_for_width (format, width)
	   Returns the number of bytes Cairo will used for storing a single row of pixels in the raw data of an image surface.	This can be used
	   as the stride value for the "image_surface_create_from_data()" function and the image surface method "get_data()".  The format value
	   should be one of the pixel format strings such as "rgb24", and the width should be a number.

       matrix_create ()
	   Return a new copy of the identity matrix.  All transformation matrices returned to Lua are in the format of a table of six numbers.
	   See lua-oocairo-matrix(3) for methods which can be called on these.

       pattern_create_for_surface (surface)
	   Return a new pattern object representing the image on the surface.  See lua-oocairo-pattern(3) for methods which can be called on
	   pattern objects.

       pattern_create_linear (x1, y1, x2, y2)
	   Return a new pattern object representing a linear gradient, where the offset numbers go from zero at the point specified by the two
	   numbers (x1, y1) to the point (x2, y2).

       pattern_create_radial (x1, y1, r1, x2, y2, r2)
	   Return a new pattern object representing a radial gradient, where offsets move from the circle defined by the three numbers
	   (x1, y1, r1), where r1 is the radius, to the circle (x2, y2, r2).

       pattern_create_rgb (r, g, b)
	   Return a new pattern object representing a solid colour.  The red, green, and blue values specified should all be numbers in the range
	   zero to one inclusive.

       pattern_create_rgba (r, g, b, a)
	   Same as "pattern_create_rgb", but accepts an alpha value, so the solid colour can be semitransparent.

       ps_get_levels ()
	   Return a table containing a list of strings indicating what levels of PostScript are supported by Cairo.

       scaled_font_create (face, font_matrix, ctm, options)
	   Creates a new scaled font object, representing a scaled version of face.  See lua-oocairo-scaledfont(3) for information about these
	   objects.

	   The font_matrix and ctm values must be matrices (any table containing six numbers, see lua-oocairo-matrix(3) for details).  The options
	   argument can be nil for the default options, or a font options object as returned by the "font_options_create" function.

       svg_get_versions ()
	   Return a table containing a list of strings indicating what versions of SVG are supported by Cairo.

       toy_font_face_create (family, slant, weight)
	   Create and return a toy font face object (see lua-oocairo-fontface(3)).  See the context method "select_font_face" for details of the
	   arguments.  This does the same, but returns the object instead of applying it to a context.	Only available with Cairo 1.8 or better,
	   otherwise this method won't exist.

       user_font_face_create (callbacks)
	   Returns a font face object which uses the supplied callbacks for rendering and such.  This is intended to be used for creating special
	   fancy font effects or for providing access to obscure font formats which aren't supported by Cairo.	The callbacks value must be a
	   table, with string keys for the callbacks.  The "render_glyph" callback is required, the others optional.

	   See lua-oocairo-userfont(3) for details of how to write the callbacks.  Only available with Cairo 1.8 or better.

I
/O through file handles
       Functions in this module which are advertised as accepting a "file/filename" value can accept a filename (a simple string) or a Lua file
       handle.	They will also work with any other object (a userdata value or table) which provides the appropriate input or output method.

       For files which are to be used for output, a file handle object needs to provide a method called "write", which will be called with a
       single string every time more output is available.  Any return values from the method are ignored, but it can throw an exception if there's
       an error.

       For files which are used for input, a file handle needs to provide a method called "read", which will be called with a number indicating
       the number of bytes it should read.  It should return a string containing exactly that number of bytes.

       The "memoryfile" module available from LuaForge can be used to write output into a buffer in memory which can then be accessed as a Lua
       string.	This can be useful as a way to get an image into another graphics library such as GD, where it can be written in other formats
       other than PNG.

Feature flags
       When the module is compiled, it will only enable support for the features which were compiled into your copy of the Cairo library.  For
       example, if you built Cairo without the PDF backend, then the module will not include the functions for creating a PDF surface.

       There are flags in the module table which indicate which features are available.  These are all wither "true" or "false":

       HAS_PDF_SURFACE
	   Support for creating a surface which writes drawing instructions out to an SVG file.

       HAS_PNG_FUNCTIONS
	   Support for loading a PNG bitmap and creating an image surface from it, or for writing the contents of an image surface out to a PNG.

       HAS_PS_SURFACE
	   Support for creating a surface which writes to a PostScript or EPS file.

       HAS_SVG_SURFACE
	   Support for creating a surface which writes to a PDF file.

       HAS_USER_FONT
	   Support for custom fonts defined by callback functions.  If true then the "user_font_face_create" function should be available in the
	   main module table.

Copyright
       This software and documentation is Copyright (c) 2008 Geoff Richards <geoff@laxan.com>.	It is free software; you can redistribute it
       and/or modify it under the terms of the Lua 5.0 license.  The full terms are given in the file COPYRIGHT supplied with the source code
       package, and are also available here: <http://www.lua.org/license.html>

1.4								    2011-05-18						       doc::lua-oocairo(3)