WIN32 Driver
WIN32 is the default driver for PV‑WAVE running under Microsoft Windows. This driver controls graphics output from PV‑WAVE to the Windows workspace.
Selecting the WIN32 Driver
To enable WIN32 as the current graphics device, enter the following:
SET_PLOT, 'WIN32'
This causes PV‑WAVE to use the WIN32 driver for producing subsequent graphics output. Once the WIN32 driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in
"Controlling the WIN32 Driver with DEVICE Keywords" below.
note | WIN32 is the default device for Windows, so selecting WIN32 as the current graphics device is not necessary unless you have previously selected some other device and want to return to WIN32. |
Listing the Current Settings for the WIN32 Driver
Use the command:
INFO, /Device
to view the current WIN32 driver settings.
Additional Text Formatting Commands
The following text formatting commands are new and can be used with the PostScript, WIN32, WMF, and X drivers. These commands can only be used when hardware fonts are enabled (!P.Font=0).
!FB—Switch to the bold face of the current font.
!FI—Switch to the italic face of the current font.
!FU—Underline the current font.
!FN—Switch to the normal form of the current font.
!Pxx—Switch to point size
xx of the current font, where
xx is a two digit integer (01-99).
Refer to the PV‑WAVE User’s Guide for a comprehensive list of text formatting commands.
Controlling the WIN32 Driver with DEVICE Keywords
The following keywords to the DEVICE procedure provide control over the WIN32 driver:
Close_Display—Deletes all generated windows from the Windows workspace and returns PV-WAVE to the initial graphics state.
Copy—Copies a rectangular area of pixels from one region of a window to another. The argument of
Copy is a six- or seven-element array: [X
s, Y
s, N
x, N
y, X
d, Y
d, W], where: (X
s, Y
s) is the lower-left corner of the source rectangle, (N
x, N
y) are the number of columns and rows in the rectangle, and (X
d, Y
d) is the coordinate of the destination rectangle. Optionally, W is the index of the window from which the pixels should be copied to the current window. If it is not supplied, the current window is used for both source and destination.
Copy can be used to increase the pace of animation. This is described in
"Using Pixmaps to Improve Application Performance".
Cursor_Crosshair—Selects the crosshair cursor type.
Cursor_Image—Specifies the cursor pattern. The value of this keyword must be a 16-line by 16-column bitmap, contained in a 16-element short integer vector. Each line of the bitmap must be a 16-bit pattern of ones and zeros, where one (1) is white and zero (0) is black. The offset from the upper-left pixel to the point that is considered the “hot spot” can be provided via the Cursor_XY keyword.
Cursor_Original—Selects the Windows default cursor—the cursor in use by the window manager when PV-WAVE starts. This cursor pattern is used by default.
Cursor_Wait—Specifies the wait cursor, usually an hourglass icon.
Cursor_XY—A two-element integer vector giving the x, y pixel offset of the cursor “hot spot”, the point which is considered to be the mouse position, from the upper-left corner of the cursor image. This parameter is only applicable if Cursor_Image is provided. The cursor image is displayed top-down—in other words, the first row is displayed at the top.
Direct_Color—When specified with a Depth value, selects the DirectColor visual with Depth bits per pixel. For example:
Direct_Color=24
The Direct_Color keyword has effect an only if no windows have been created. The Direct_Color and True_Color keywords are essentially synonymous when used with the WIN32 driver: they perform identical functions.
Font—Specifies the name of the font used when the hardware font is selected (that is, when !P.Font=0). For example, to select the font 14 point New Times Roman bold, use the following DEVICE call:
DEVICE, Font='Times New Roman, 14, bold'
Windows provides the Character Map accessory tool that can be used by all applications to show the fonts available on your system.
note | The size of the font selected also affects the size of software-drawn text (e.g., the Hershey fonts). The “!” commands accepted for software fonts for subscripts and superscripts do not work for hardware fonts. |
TrueType hardware fonts can be rotated but not projected. When generating 3D plots, it is best to use the software characters because PV‑WAVE can draw them in perspective with the rest of the plot. For more information on software fonts, see the PV‑WAVE Programmer’s Guide.
Get_Class—The display device's color class will be returned as a LONG number whose possible values are 2 through 5.
DEVICE, True_Color=24
DEVICE, Get_Class=class
Get_Class Return Values shows the different combinations of color class settings and the return value of
Get_Class. For example, if you set
DEVICE, Static_Gray=8,
Get_Class returns 3; if you set
DEVICE, Static_Gray=24,
Get_Class returns 4. Only
Direct_Color,
Pseudo_Color, and
True_Color are available on Windows.
Get_Fontmap—Returns list of current font map settings. If /Get_Fontmap is specified, the information is printed to the screen. If a variable name is specified (e.g., Get_Fontmap=varname), a string array is returned.
The information returned by Get_Fontmap is in the same form as the strings specified with Set_Fontmap. The only exception to this pattern is that the first string returned in a string array is labeled as font 0 and is the current default font.
Get_Graphics_Function—Returns the value of the current graphics function (set with the
Set_Graphics_Function keyword). This keyword can be used to save the value of the current graphics function, change it temporarily, and then restore it. See the example in the section
"Using Graphics Functions to Manipulate Color".
Get_Window_Position—Places the x and y device coordinates (relative to the lower-left corner of the display) of the window’s lower-left corner into a named variable.
Get_Write_Mask—Specifies the name of a variable to receive the current value of the write mask. For example:
DEVICE, Get_Write_Mask=mask
Max_Lines—Sets the maximum number of identical line segments that will be cached before forcing a screen redraw. The WIN32 driver uses an internal cache for drawing line segments. Instead of drawing each line individually, lines with common characteristics are drawn as a group. This feature increases drawing efficiency and rendering speed. To disable Max_Lines, set the keyword equal to one. (Default: 500 lines.)
Max_Pens—Sets the maximum number of pens that will be cached before forcing a screen redraw. (Default: 10 pens, each of which can hold 500 line segments.) To disable Max_Pens, set the keyword equal to one.
note | The line caching feature may affect some PV‑WAVE behavior that is familiar to you. In general, this applies to any operation that depends on the order in which lines are drawn. For example, using OPLOT with the color set to the background color to erase drawn lines may not work as expected. This is because some or all of the second set of lines may be drawn before the first set they were intended to overwrite. To avoid this, use the EMPTY procedure to force the driver to empty the line cache first. |
Pseudo_Color—When specified with a Depth value, selects the PseudoColor visual with Depth bits per pixel. For example:
Pseudo_Color=8
The Pseudo_Color keyword has an effect only if no windows have been created.
Set_Character_Size—A two-element vector that changes the standard width of the vector-drawn fonts and the space allocated above the line of text. The first element in the vector contains the new character width, and the second element contains the number of pixels above the line of text. By default, characters are approximately 8-pixels wide, with 12 pixels between lines.
Set_Fontmap—Associates specific font characteristics with a particular hardware font command. This keyword can be used to specify a single string containing the information for one font, or an array of strings containing the information for multiple fonts.
For example, to associate 16 point Helvetica italic with font command !5, use the following DEVICE call:
DEVICE, Set_Fontmap='5 Helvetica, 16, italics'
Now, whenever the !5 font command appears in a text string, the text output appears in 16 point Helvetica italic. This keyword only affects hardware fonts (that is, when !P.Font=0).
note | A default font mapping is defined in a configuration file that is read when the WIN32 driver is initialized. For information on this configuration file, see the Fonts chapter in the PV‑WAVE User’s Guide. |
Set_Graphics_Function—Windows allows applications to specify the
Graphics Function. This is a logical function which specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. The complete list of possible values is given in
Graphics Function Values. The default graphics function is
GXcopy, which causes new pixels to completely overwrite any previous pixels.
note | Windows hardware fonts are not affected by the current graphics function. This means that you cannot erase drawn text with an XOR operation if hardware fonts are used. This is a limitation of Windows. The only exception is the graphics function GXnoop, which works correctly. |
Set_Write_Mask—Sets the write mask to the specified value. Under Windows, the write mask can range from 0 to 255. See also
"Write Mask and Graphics Functions to Manipulate Color".
True_Color—When specified with a Depth value, selects the TrueColor visual with Depth bits per pixel. For example: True_Color=24
The True_Color keyword has an effect only if no windows have been created. The Direct_Color and True_Color keywords are essentially synonymous when used with the WIN32 driver: they perform identical functions.
Window_State—Returns an array containing values indicating the status for all available PV‑WAVE windows. Each element of the array contains a value equal to the sum of the following values:
0—Window closed
1—Window active on display
2—Backing store active
4—Metafile active
In the following example, the fourth element of winarray contains the value 3, or 1 + 2. This indicates the window and backing store is active.
; Open window 3.
WINDOW, 3
DEVICE, Window_State=winarray
PRINT, winarray
0 | 0 | 0 | 3 | 0 | 0 | 0 | 0 | 0 |
0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
0 | 0 | 0 | 0 | 0 | | | | |
Resizing Graphics
Prior to Version 6.0 of PV‑WAVE for Microsoft Windows, it was necessary to use special keywords so that displayed graphics would resize whenever the user resized a window using its border. This is no longer the case. Window resizing is now the default behavior and is automatically provided for all normal PV‑WAVE graphics windows.
Windows Metafile Limitations
A Windows metafile is used to retain graphics in a window. The metafile is “replayed” into the graphic window whenever the window is resized. Metafiles are also used when you print the window. If you expect that your graphics might be subject to resizing, you should be aware of two limitations inherent in metafiles.
Resolution Dependency for Plots
Metafiles are limited by the resolution of the graphics window in which you initially constructed a plot. So if you draw a plot to a small (low-resolution) window and then resize that window to full screen, you will likely see “aliasing” effects due to the low resolution of the original plot. For example, you might see “stairsteps” in diagonal lines or squared-off corners in small arcs or circles. You will see similar effects if you print the plot to a printer that has a higher resolution that your graphics window.
You can solve this problem by plotting to a high-resolution (large) window when you intend to make high-resolution plots. If you do not wish to view this large window (or you need to make it larger than your display) then you can use the /Pixmap keyword with the WINDOW command to make the window invisible.
Disappearing “Dots”
Another problem with metafiles is that they cannot reproduce a “dot” (a single-pixel point). So, if you use, for example, Psym=3 (a dot) in a PLOT command, it will appear on the screen, but when you resize the window or print the graph, the dot will disappear. This is because these pixels are treated differently by the metafile. (Note that this problem does not affect images, such as those you might dispay with the TV procedure.)
To solve the disappearing-dot problem, turn off metafiles by using the /NoMeta keyword with the WINDOW command. This results in a bitmap (DIB file) being used for repainting and printing. Since bitmaps are not resizable, pixels can’t be lost. But keep in mind that when the graphic is printed, it will be scaled to fit the printed region, so you will see effects such as wider lines and possibly boxes in place of dots. This problem can also be solved by using a higher resolution window for the initial plot.
Graphics Window Commands
The following commands operate upon the contents of graphics windows. Most of these commands allow for the interchange of graphics between PV‑WAVE and other graphics applications.
For detailed information on these commands, see their individual descriptions in this Reference.
WCOPY—Copies contents of a graphics window onto the Clipboard.
WPASTE—Pastes contents of the Clipboard into a graphics window.
WREAD_DIB—Loads a Device Independent Bitmap (DIB) from a file directly into a specified graphics window.
WREAD_META—Loads a Windows enhanced metafile (EMF) into a graphics window. Note that EMF graphics are designed to be used only with 32-bit applications; they cannot be pasted into a 16-bit application.
WWRITE_DIB—Saves the contents of a graphics window into a file as a Device Independent Bitmap (DIB).
WWRITE_META—Saves the contents of a graphics window into a file as a Windows enhanced metafile (EMF). Note that EMF graphics are designed to be used only with 32-bit applications; they cannot be pasted into a 16-bit application.
WPRINT—Prints the contents of the specified graphics window.
note | You can also use the graphics window Control menu to import, export, and print graphics. |
Use of Color in the WIN32 Driver
This section discusses how color tables and color palettes are handled by the WIN32 driver. For general information on color tables and how PV‑WAVE handles color, see the PV‑WAVE Programmer’s Guide.
note | The color model used by the WIN32 driver in PV‑WAVE Version 6.0 has changed from previous releases of PV‑WAVE. Earlier releases, specifically version 4.2 and PV‑WAVE Personal Edition, used a color model that was very similar to that used by the X Windows X11 driver. For PV‑WAVE 6.0, changes to the WIN32 driver were made to support high-color Windows video drivers and required a simplification of the way color tables and palettes are handled. |
Windows Video Modes
Windows graphics output depends on a piece of software called a video driver that provides an interface between Windows Graphics Device Interface (GDI) calls and the video hardware installed in the computer. This software is usually provided by the manufacturer of the video card. Depending on the capabilities of the hardware, video drivers usually support several video modes. A video mode is a combination of screen resolution, color depth and refresh rate.
Screen resolution is usually expressed in terms of the number of horizontal and vertical pixels displayed on the screen. Common resolutions are 640x480 (VGA), 800x600, 1024x768, and 1280x1024. Higher resolutions require more memory on the video card and a more capable monitor.
Color depth refers to the number of colors that can be displayed at once on the screen. This is usually one of 16, 256, 65636 (16-bit), or 16777216 (24-bit) and is directly related to the number of bits of video memory required to store the color information for a single pixel. In combination with the resolution, this determines what video modes are available for a given amount of memory on a video card. For instance, 1024x768 resolution with 256 colors requires 768KB of memory and so should be available on most video cards with at least 1 MB of video RAM while the same resolution with 24 bits of color information would require 2304KB and would not be available unless the video card has more than 2MB of video memory.
Refresh rate refers to how often the video card transfers information to the monitor and is not relevant to this discussion.
PV‑WAVE Color Model
PV‑WAVE inherently uses an 8-bit pseudo-color model. Color values are represented as an index into the current color table. The color table consists of three byte arrays that have 256 elements; the arrays represent the relative amounts of red, green and blue in a particular color. When a particular value is placed in a PV‑WAVE graphics window (by the TV procedure, for instance) the graphics driver determines what color to display by using the value as an index into the color table arrays. When the color table changes (via the LOADCT procedure, for instance) the color represented by a particular value is likely to be different and, if so, will result in a new color being displayed in the graphics window.
In PV‑WAVE’s WIN32 graphics driver, the contents of a graphics window are stored in a DIB (Device Independent Bitmap) created using the DIB_RGB_COLORS format. This means that the window image is stored in an exact parallel to PV‑WAVE’s color model: an array of 8-bit values that act as indices into a color table which contains 8 bits each of red, green, and blue color information.
note | Interaction Between PV-WAVE and the Video Driver |
When a graphics window is painted, the DIB section is transferred from normal memory to video memory where it appears on the screen. This operation is called a blit. As part of the blit operation, the video driver and Windows determine how to map the pixel information in the DIB into the current video mode. This is usually a highly optimized operation in the video driver.
The way a pixel value in the DIB gets mapped to a color on the video screen depends on the current color depth that the video driver is using. In general, Windows will map a given pixel color to the closest matching RGB value that the video driver can display. This is likely to be an unsatisfactory match for a driver in 16 color VGA mode, while a driver in 24-bit mode will be able to match any requested color exactly.
256 Color Drivers and Palettes
When Windows is using a video mode with 256 colors, pixel values in video memory represent an index into a palette (as opposed to directly representing the color as is the case in 16- and 24-bit modes). A palette serves exactly the same function as PV‑WAVE’s color table—it allows the selection of a subset of the 16 million colors that can be represented by the RGB triple.
The palette is controlled by the application that the user is currently using—the foreground application. With certain exceptions (discussed below), the foreground application can set the palette to represent whatever set of colors it wants. Background applications try to render their data as best they can given that the foreground application controls the palette; this often results in “flashing” as applications redraw their data when they move from background to foreground. When PV‑WAVE is the foreground application, it directly maps the current color table to the Windows palette.
The exception is that Windows reserves the top and bottom 10 entries in the palette (for a total of 20 colors) for the system colors used to draw controls and window decorations. This results in less distraction for the user since only the contents of application windows will flash while window frames and controls will not.
The PV-WAVE WIN32 Driver in 256 Color Mode
The penalty for non-flashing window frames is that only 236 colors are available to PV‑WAVE while it needs 256 to represent the color table. Earlier versions of the WIN32 driver used the color limiting mechanisms implemented to support the X driver to reduce the color table size to 236. The drawback to this approach is that it makes PV‑WAVE’s behavior dependent on the current video mode—the same program will give different results with a different video mode. It also caused performance problems since it was necessary to continuously transform data transferred to and from the screen.
With PV‑WAVE Version 6.0, the WIN32 driver always indicates that PV‑WAVE has 256 colors available; if it needs to display in a palletized video mode, 20 colors evenly distributed through the color table are not mapped to the palette. The other 236 colors will be exactly represented but the 20 unmapped colors will map to the closest match available in the palette, either among the 236 PV‑WAVE colors or the 20 system colors. For most of the PV‑WAVE color tables, the closest match is immediately adjacent in the color table and the unmapped colors are very difficult to notice. Any discrepancy is purely visual; all PV‑WAVE operations, including TV and TVRD, set and return the proper color and these operations return consistent results regardless of the current video model.
Using Bitmaps
Windows can direct graphics to either windows or bitmaps:
Windows—Windows are the usual windows that appear on the screen and contain graphics. Drawing to a window produces a viewable result.
Bitmaps—Bitmaps are areas of invisible graphics memory. Drawing to a bitmap simply updates the bitmap memory.
Bitmaps are useful because it is possible to write graphics to a bitmap and then copy the contents of the bitmap to a window where it can be viewed. The process works by placing the desired images into bitmap memory and then copying them in succession to a visible window.
Creating a Bitmap
To create a bitmap, use the Bitmap keyword with the WINDOW procedure. For example, to create a 1280-by-1280 bitmap in window 1:
WINDOW, 1, /Bitmap, Xsize=1280, Ysize=1280
Once they are created, bitmaps are treated just like normal windows, although some operations (WSHOW, for instance) don’t have any noticeable effect when applied to a bitmap. Note also that the bitmap’s resolution does not have to be restricted to the size of the display’s resolution.
Example—Animating a Series of Bitmap Images
The following example shows how animation can be performed using bitmap memory. It uses a series of 15 heart images taken from the file abnorm.dat. (This file is located in the data subdirectory of the main PV-WAVE directory.) It creates a bitmap and writes all 15 images to it. It then uses the Copy keyword of the DEVICE procedure to copy the images to a visible window. Pressing any key causes the animation to halt:
; This procedure animates a series of heart data.
PRO animate_heart
; Open the file containing the images.
OPENR, u, !Data_Dir+'abnorm.dat',/Get_Lun
; Associate a file variable with the file. Each heart image
; is 64-by-64 pixels.
frame = ASSOC(u, BYTARR(64, 64))
; Window 0 is a bitmap large enough to hold one double-sized
; image tall and 15 double-sized images wide. The resized
; images will be placed in this bitmap.
WINDOW, 0, /Bitmap, Xsize=7680, Ysize=512
; Write each image to bitmap memory. SMOOTH is used to
; improve the appearance of each image and REBIN is used to
; enlarge each image to the final display size.
FOR i=0L, 15-1 DO TVSCL, $
REBIN(SMOOTH(frame(i), 3), 512, 512), i
; Close the image file and free the file unit.
FREE_LUN, u
; Window 1 is a visible window that is used to display the
; animated data, creating the appearance of a beating heart.
WINDOW, 1, Xsize=512, Ysize=512, Title='Heart'
; Load the current frame number.
i = 0L
; Display frames until any key is pressed. Copy the next
; image from the bitmap to the visible window.
WHILE GET_KBRD(0) EQ '' DO BEGIN
DEVICE, Copy=[i * 512, 0, 512, 512, 0, 0, 0]
; Keep track of total frame count.
i = (i + 1) MOD 15
ENDWHILE
END
Using the Write Mask and Graphics Functions to Manipulate Color
The write mask can be used to superimpose (overlay) one graphics pattern over another when plotting to a graphics window, allowing you to create special effects.
Another possible application for the write mask is to simultaneously manage two 4-bit-deep images in a single graphics window instead of a single 8-bit-deep image. You could use the write mask to control whether the current graphics operation operates on the “top” image or the “bottom” image.
Using Graphics Functions to Manipulate Color
The WIN32 driver provides two keywords for inquiring and manipulating the graphics function—Get_Graphics_Function and Set_Graphics_Function.
The value of the
Set_Graphics_Function keyword controls the logical graphics function; this function specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. To see a complete list of graphics function codes, refer to the
Set_Graphics_Function keyword description in the section
"X Window System".
In the following example, POLYFlLL is used to select the area to be inverted. Colors represented by color index 1 are XORed with the image currently displayed in that area.
; Set graphics function to exclusive or (GXxor), saving the old
; function.
DEVICE, Get_Graphics=oldg, Set_Graphics=6
POLYFILL, [[x0,y0], [x0,y1], [x1,y1], [x1,y0]], /Device, Color=1
; Restore the previous graphics function.
DEVICE, Set_Graphics_Function=oldg
The default value for the Set_Graphics_Function keyword is GXcopy, which means that the source graphics from the current operation get copied into the window, destroying any graphics that were previously displayed.
Interaction Between the Set_Write_Mask and the
Set_Graphics_Function Keywords
You use the Set_Write_Mask keyword to specify the planes whose bits you are manipulating or the plane you want to use for the special effects. The way the two graphics patterns are combined depends on the value you provide for the Set_Graphics_Function keyword. For example, you could use the following commands:
DEVICE, Set_Graphics_Function=6
DEVICE, Set_Write_Mask=8
to extract the fourth bit (the binary equivalent of the decimal value 8) of the image in the current graphics window. The extracted plane is XORed (XOR is the graphics function specified by setting the Set_Graphics_Function keyword equal to 6) with the source pattern (the result of the current graphics operation). After the graphics function is implemented, the result is drawn in the current graphics window using whichever color(s) in the color table match the resultant value(s).
Interaction Between the Set_Graphics_Function Keyword and and Colors
The graphics functions specified by the Set_Graphics_Function keyword operate individual colors, not on hardware pixel values as they do with the X driver.
Window IDs
The PV‑WAVE WINDOW procedure has two keywords, Get_Win_Id and Set_Win_Id that provide access to the WIN32 window handle associated with a PV‑WAVE graphics window.
Get_Win_Id returns the HWND that was returned from the WIN32
CreateWindow API call. If you are making PV‑WAVE calls from another application via a connectivity mechanism, you can use this keyword to get the window handle and then use the handle as an argument to an API call like HideWindow. You can also use the handle if you need to subclass a PV‑WAVE graphics window for any reason.
Set_Win_Id causes PV‑WAVE to use a window that already exists as a graphics window. For instance, you might have created a window in a Visual Basic form in which you would like PV‑WAVE to display graphics. You can do this by passing PV‑WAVE the window handle of the existing window at runtime using the Set_Win_Id keyword. PV‑WAVE will subclass the window referred to by the handle when the keyword is used with a WINDOW command. When the driver is closed or when PV‑WAVE exits, subclassing is removed.
note | Unlike UNIX, Windows does not allow applications to draw or interact with windows owned by other processes. In order for PV-WAVE to draw into a window created by another application via WINDOW, Set_Win_ID=<window id>, a parent-child relationship must exist between the PV-WAVE process and the process that owns the window. This may be accomplished, for example, by having the process that owns the drawing area spawn the PV-WAVE process as well. |
See the WIN32 Programmer’s Reference for more information about window handles and subclassing.
Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.