CAIRO Base Driver

This driver represents a basic driver for all system-dependent drivers implemented in the X-Windows and MS-Windows systems. The implementation uses the Cairo API functions and Pango functions to support Unicode text. This driver can be compiled and used in all systems Cairo is supported. The drivers Native Window, Image, Printer and Double Buffer were implemented.

The main motivation for the use of Cairo was transparency for all the primitives. Beyond that we got other features like anti-aliasing, gradient filling, transformations and back-ends (support to rendering: PDF, PS, SVG and PNG surfaces).

This driver still does not completely replace the X-Windows and GDI Windows base drivers, because Cairo does not have support for bitwise XOR operations and for complex clipping regions.

So we let the programmer to choose what to use. We created the function cdUseContextPlus that allows to activate or to deactivate the use of Cairo for the available GDK, Win32 or X-Windows based drivers. This function affects only the cdCreateCanvas function call, once created the canvas will be always a Cairo canvas. In fact the function affects primary the definitions CD_NATIVEWINDOW, CD_IMAGE and CD_DBUFFER, because they are function calls and not static defines.

Using Cairo it is allowed to create more that one canvas at the same time for the same Window. And they can co-exist with a standard GD, Win32 or X-Windows canvas.

To enable the use of Cairo based drivers you must call the initialization function cdInitContextPlus() once and link to the libraries "cdcairo" and "cairo". When using the GDK base driver you do not need to link with the "cdcairo" library. Also the Cairo library must be installed in your system.

In CDLua it is not necessary any additional initialization, but the application must still be linked with the cdcontextplus.lib library or a require"cdluacontextplus" can be used when using dynamic libraries.

Behavior of Functions

Control 

• Play: does nothing, returns CD_ERROR.

Coordinate System and Clipping

• UpdateYAxis: the orientation of axis Y is the opposite to its orientation in the CD library.

Primitives

• Begin: CD_PATH is supported.
• Floating point primitives are supported.

Attributes

• WriteMode: does nothing. There is no support for XOR or NOT_XOR.
• NativeFont: also accepts the X-Windows font string format.
• Font: "Courier" is mapped to "Courier New", "Helvetica" is mapped to "Arial", and "Times" is mapped to "Times New Roman". Underline and Strikeout are NOT supported.

Colors

• Palette: NOT supported.

Exclusive Attributes

• "ANTIALIAS": controls the use of anti-aliasing for the text and drawing shapes. Assumes values "1" (active) and "0" (inactive). Default value: "1".

• "CAIRODC": returns the Cairo drawing context (get only). In Lua is returned as a user data.

• "CAIROVERSION": returns a string with the Cairo version number. It is empty if the Cairo is not available.

• "HATCHBOXSIZE": defines the size of smallest hatch box pattern. This affects the spacing between the hatch lines. The value passed must be a string containing an integer ("%d"). If the value of the attribute passed is NULL, the value is rest to the default. When consulted returns the current value ("%d"). Default: "8".

• "IMGINTERP": changes how interpolation is used in image scale. Can be "BEST" (highest-quality), "BILINEAR" (linear interpolation), "GOOD" (quality similar to BILINEAR), "NEAREST" (nearest-neighbor filtering) or "FAST" (quality similar to NEAREST). Default: "GOOD".

• "LINEGRADIENT": defines a filled interior style that uses a line gradient between two colors. It uses 2 points ("%d %d %d %d" = x1 y1 x2 y2), one for the starting point using (using the foreground color), and another one for the end point (using the background color).

• "PATTERNIMAGE": defines a filled interior style using a server image as pattern. Data must be a server image handle created with he Cairo base driver.

• "POLYHOLE": defines the index of the vertex where there is a hole in a closed polygon. It will affect the next cdEnd. Can be called several times between cdBegin and cdEnd to define holes. The value passed must be a string containing an integer ("%d"). If the value of the attribute passed is NULL, all holes will no longer be considered. When consulted returns the current number of holes ("%d"). It can have a maximum of 500 holes. Default: NULL.

• "RADIALGRADIENT": defines a filled interior style that uses a radial gradient between two colors. It uses 2 points and 2 radius ("%d %d %g %d %d %g" = x1 y1 rad1 x2 y2 rad2), one for the starting point using (using the foreground color), and another one for the end point (using the background color).

• "ROTATE":  allows the usage of 1 angle and 1 coordinate (x, y), that define a global rotation transformation centered in the specified coordinate. Use 1 real and 2 integer values inside a string ("%g %d %d" = angle x y). Can not be set if a transformation is already set.