GDI+ Base Driver

This driver represents a base driver for all system-dependent drivers implemented in the Microsoft Windows system, but uses a new API called GDI+. The drivers Clipboard, Native Window, IUP, Image, Printer, EMF and Double Buffer were implemented. The driver WMF, and the function cdPlay of the Clipboard and EMF drivers were not implemented using GDI+.

It can be used only as the context plus driver of the GDI based drivers.

The main motivation for the use of GDI+ was transparency for all the primitives. Beyond that we got other features like anti-aliasing, gradient filling, bezier lines and filled cardinal splines.

This driver still does not completely replace the GDI Windows base driver, because GDI+ does not have support for XOR. Also the applications need to adapt the rendering of text that is slightly different from GDI. It is know that GDI+ can be slower than GDI in some cases and faster in other cases, Microsoft does not make this clear.

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 GDI+ for the GDI based drivers. This function affects only the cdCreateCanvas function call, once created the canvas will be always a GDI+ canvas. In fact the function affects primary the definitions CD_NATIVEWINDOW, CD_IMAGE, CD_PRINTER, CD_EMF, CD_DBUFFER and CD_CLIPBOARD, because they are function calls and not static defines.

Using GDI+ 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 GDI canvas.

To enable the use of GDI+ based drivers you must call the initialization function cdInitContextPlus once, and link to the libraries "cdcontextplus.lib" and "gdiplus.lib". Also the file "gdiplus.dll" must be available in your system. These files already came with Visual C++ 7 and Windows XP. For other compilers or systems you will need to copy the ".lib" file for you libraries area, and you will need to copy the DLL for the Windows\System (Win98/Me) or Windows\System32 (Win2000/NT4-SP6) folder. The gdiplus files can be obtained from Microsoft or from here.

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. Except when using transformations.

Primitives

• Floating point primitives are supported.
• Pixel: uses GDI. Excepting when the canvas is an image so it is done using GDI+.
• Sector: it also draws an arc in the same position to complete the size of the sector.
• Text: opaque text is simulated using a rectangle in the back.
• Begin: Beyond the standard modes it accepts the additional modes: CD_FILLSPLINE and CD_FILLGRADIENT. The C definitions of these modes are available in the cdgdiplus.h header.
  
  CD_SPLINE defines the points of a curve constructed by a cardinal spline. Uses the current line style.
  CD_FILLSPLINE defines the points of a filled curve constructed by a cardinal spline. Uses the current interior style.
  CD_FILLGRADIENT defines the points of a filled polygon. It is filled with a gradient from colors in each vertex to a color in its center. The colors are defined by the "GRADIENTCOLOR" attribute, that must be set before each cdVertex call and before cdEnd for the center color. This will not affect the current interior style.

Attributes

• WriteMode: does nothing. There is no support for XOR or NOT_XOR.
• Pattern: each pixel can contain transparency information.
• LineStyle: uses a custom GDI+ style when line width is 1. In World Coordinates the line style has its scaled changed.
• FontDim: the maximum width is estimated from the character "W".
• TextAlignment: is simulated. Although GDI+ has text alignment, the results do not match the CD text alignment.
• NativeFont: also accepts "-d"  to show the font-selection dialog box.
• Font: "System" is mapped to "MS Sans Serif", "Courier" is mapped to "Courier New", "Helvetica" is mapped to "Arial", and "Times" is mapped to "Times New Roman". Underline and Strikeout are supported.

Colors

• Palette: works only when the canvas is a server image.
• Foreground & Background: accepts the transparency information encoded in the color.

Client Images

• GetImageRGB: uses GDI. Excepting when the canvas is an image so it is done using GDI+.

Server Images

• GetImage: uses GDI. Excepting when the canvas is an image so it is done using GDI+.
• ScrollArea: uses GDI. Excepting when the canvas is an image so it is done using GDI+.

Exclusive Attributes

• "GDI+": returns "1". So the application can detect if the driver uses the GDI+ base driver. Other drivers that do not implement this attribute will return NULL.

• "HDC" or "GC": returns the HDC of the Win32 canvas. It can only be retrieved (get only). In Lua is returned as a user data. It is not NULL only in some Native Windows canvas and in the printer canvas.

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

• "TEXTANTIALIAS": controls the use of anti-aliasing for text primitives. Assumes values "1" (active) and "0" (inactive). Default value: "1". (since 5.6)

• "GRADIENTCOLOR": necessary for the creation of the gradient fill defined by a polygon (see details in the function cdBegin above). Defines the color of each vertex and the center (%d %d %d" = r g b). It can not be retrieved (set only).

• "IMAGETRANSP": defines an interval of colors to be considered transparent in client and server images (except for RGBA images). It uses two colors to define the interval ("%d %d %d %d %d %d" = r1 g1 b1 r2 g3 b3). Use NULL to remove the attribute.

• "IMAGEFORMAT": defines the number of bits per pixel used to create server images. It uses 1 integer that can have the values: "32" or "24" (%d). Use NULL to remove the attribute. It is used only in the cdCreateImage. When not defined, the server images use the same format of the canvas.

• "IMAGEALPHA":  allows the usage of an alpha channel for server images if IMAGEFORMAT=32. The attribute format is a pointer to the transparency values in a sequence of chars in the same format of alpha for client images. The attribute is used in the cdCreateImage and for every cdPutImageRect, the pointer must exists while the image exists. The alpha values are transfered to the image only in cdPutImageRect, so they can be freely changed any time. The data is not duplicated, only the pointer is stored. The size of the data must be the same size of the image. Use NULL to remove the attribute. Not accessible in Lua. For example:

 unsigned char* alpha = malloc(w * h);
myInitAlpha(w, h, alpha);
cdCanvasSetAttribute(curCanvas, "IMAGEALPHA", (char*)alpha);
cdCanvasSetAttribute(curCanvas, "IMAGEFORMAT", "32");
myImage = cdCanvasCreateImage(curCanvas, w, h);

• "IMAGEPOINTS":  define 3 coordinates of a paralelogram that will be used to warp server and client images in the subsequent calls of PutImage functions. Use 6 integer values inside a string ("%d %d %d %d %d %d" = x1 y1 x2 y2 x3 y3). Use NULL to remove the attribute. The destination rectangle of the PutImage functions will be ignored. The respective specified points are the upper-left corner, the upper-right corner and the lower left corner. In GDI+ this attribute is more complete than in GDI, because affects also client images.

• "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". (since 5.8.3)

• "PATTERNIMAGE": defines a filled interior style using a server image as pattern. Data must be a server image handle created with the GDI+ base driver. Interior style is set to CD_CUSTOMPATTERN. (since 5.12)

• "RADIALGRADIENT": defines a filled interior style that uses a radial gradient between two colors. It uses a center point and a radius ("%d %d %d" = xc yc r). It starts at the center using the foreground color, and end at the radius using the background color. If a regular interior style is set after the attribute, the gradient is lost. Interior style is set to CD_CUSTOMPATTERN.  (since 5.12)
  For example:

cdCanvasForeground(canvas, CD_YELLOW); 
cdCanvasBackground(canvas, CD_GREEN);
cdCanvasSetfAttribute(canvas, "RADIALGRADIENT", "%d %d 50", w - 125, 325);
cdCanvasSector(canvas, w - 125, 325, 50, 50, 0, 360);

• "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.

• "LINEARGRADIENT": defines a filled interior style that uses a linear 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). If a regular interior style is set, the gradient is lost. Interior style is set to CD_CUSTOMPATTERN (since 5.12).  For example:

 cdCanvasForeground(canvas, CD_YELLOW);
cdCanvasBackground(canvas, CD_GREEN);
cdCanvasSetfAttribute(canvas, "LINEARGRADIENT", "%d 200 %d 250", w - 150, w - 100); /* x1 y1 x2 y2 */
cdCanvasBox(canvas, w - 150, w - 100, 200, 250);

• "LINECAP": defines additional line cap styles. It can have the following values: "Triangle", "NoAnchor", "SquareAnchor", "RoundAnchor", "DiamondAnchor", or "ArrowAnchor". It can not be retrieved (set only).

• "UTF8MODE": enables the usage of the UTF-8 encoding for strings. It can have the following values: "1" or "0". Default is "0".

• "WINDOWRGN": set the shape of a window to the current complex clipping region (set only). If data is NULL the region is reset.