Microsoft Windows Base Driver Using GDI+

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+.

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, filled cardinal splines and world coordinate directly implemented by the driver.

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 available 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_IUP, CD_NATIVEWINDOW, etc, 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 cdInitGdiPlus() once and link to the libraries "cdgdiplus.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.

In CDLUA it is not necessary any additional initialization.

Exclusive Functions

int cdUseContextPlus(int use); [in C]
cdUseContextPlus(use: number) -> (old_use: number) [in Lua]

Activates or deactivates the use of an external context for the next calls of the cdCreateCanvas function. This function is declared in the "cdgdiplus.h" header, because now it is useful only for GDI+. But it is implemented in the standard library.

void cdInitGdiPlus(void); [in C]

Initializes the GDI+ driver to be used as an external context replacing the traditional GDI drivers. This function is declared in the "cdgdiplus.h" header.

Behavior of Functions

Control

• cdPlay: does nothing, returns CD_ERROR.

Coordinate System and Clipping

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

Primitives

• cdPixel: uses GDI. Excepting when the canvas is an image so it is done using GDI+.
• cdMark: is simulated.
• cdSector: it also draws an arc in the same position to complete the size of the sector.
• cdText: opaque text is simulated using a rectangle in the back.
• cdBegin: 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

• cdBackOpacity: only changes the transparency of the background color to 0 (transparent) or 255 (opaque).
• cdHatch: diagonal styles are drawn with anti-aliasing.
• cdWriteMode: does nothing. There is no support for XOR or NOT_XOR.
• cdPattern: each pixel can contain transparency information.
• cdLineStyle: uses a custom GDI+ style when line width is 1. In World Coordinates the line style has its scaled changed.
• cdFontDim: the maximum width is estimated from the character "W".
• cdNativeFont: the font string describer has the following format:
  "fontname, size [style] [-k] [-u]", where fontname is the name of the font in Windows (notice the comma after the font name), size is given in points or in pixels, style is the same as cdFont, -u means underline and -k means strikethrough, or "-d" to show the font-selection dialogue box. However, this function also accepts the font string used by the WINFONT attribute of the IUP library.
• cdTextAlignment: is simulated. Although GDI+ has text alignment, the results for the CD were poor.
• cdFont: see the font mapping table for the equivalence used to map CD fonts into Windows fonts (note that in GDI+ there is no direct mapping for the system font):

Colors

• cdPalette: works only when the canvas is a server image.
• cdForeground e cdBackground: accepts the transparency information encoded in the color.

Client Images

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

Server Images

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

Exclusive Attributes

• "HDC": 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 by the text, image zoom and line drawing primitives. Assumes values "1" (active) and "0" (inactive). Default value: "1".

• "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 also 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 only in the cdCreateImage, but 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.

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

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

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

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