Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / XDUMP.ZIP / XDUMP.DOC < prev next >

Wrap

Text File | 1988-08-17 | 31.6 KB | 837 lines

XDUMP V1.03 A Scaling Screen Dump Program Copyright (c) 1988 by Michael Day Original release: 28 July 1988 This release: 17 August 1988 XDUMP was designed to allow a program to print an area of the screen to the printer in graphics mode. The screen is automatically scaled to/from the specified screen size to the target printer size. XDUMP can handle both color and monochrome, is capable of handling any screen size upto 32K x 32K and upto 256 colors. What XDUMP is and what it isn't: XDUMP is a graphics screen dump program. XDUMP was written in Turbo Pascal V4.0. Version 1.xx of XDUMP was designed to be incorporated into another program and consists of two sections. The first section is the screen dump program itself. This was designed to be as independent from the calling program as possible. It was also designed to be as small and quick as possible given the constraints it was written under. Because of this, the actual screen dump portion of the program is rather dumb, and is driven from predefined tables. The definition section is what defines what the screen dump is supposed to do. The programmer provides the information about the system to the definition section which then sets up the screen dump section. Because of its isolated nature XDUMP can be tied into the INT 5 print screen interrupt as an ISR if so desired (with a slight modification) that will run for the duration of the program. Later versions of XDUMP will be capable of operating as a stand-alone TSR. Currently XDUMP is written to run on an Epson compatible graphics printer. Since the source code is provided, any competent programmer can quickly adapt the program to a non- compatible printer. What the printer driver needs to know: The screen dump section of XDUMP is a very dumb program, it assumes that someone else has told it what it is to do. Invoking the screen dump section will then cause it to read the screen and dump it to the printer based on the information it was told. It is up to the definition section to provide the correct information. It was implemented this way so that XDUMP would emulate the standard print screen function. Defining things: You must provide XDUMP with information about what you want it to do. This means that you must run the definition section before XDUMP is invoked. When the definition is run, it will attempt to figure out what kind of setup is out there, and use those values as defaults. You can then change or override the standard defaults. Part of the reason that XDUMP is so flexible is because all of the major machine dependent code has been left in the definition section. This allows a simplified interface between the screen and printer making the installation much simpler. It also provides the calling program with the ability to specify to XDUMP exactly how it wants the dump to appear. This is something that most other screen dump programs are simply not able to do. The only interface that XDUMP has to the screen is through one simple TP4 graph routine "GetPixel." This limits you to the displays supported by the BGI, and it prevents using XDUMP as a TSR since the graph unit is not compatible with TSRs. It is somewhat faster than the BIOS call though. You can use the BIOS call (the Read Dot function in INT 10) if you wish. This is how XDUMP is capable of handling any size screen (even the new 600x800 super VGAs). Be aware that your display BIOS must support the ReadDot (ah=13) function of INT 10 for it to work though. You may find problems with Hercules cards, many of which do not provide the BIOS function. Scaling between the screen and the printer: The big problem with many screen dump programs is that they do not provide any way to deal with different sized screens. This becomes very apparent with EGA which does not have an easily definable screen to printer translation. The end result is that the EGA screen usually comes out squashed on the printer. This problem was in fact the original impetus behind XDUMP. In default mode the display and printer are assumed to both provide a picture that is eight inches wide by six inches tall. While the actual sizes will vary, 8 x 6 is the reference used by the default standard. This works out very well because the standard narrow carriage printer uses eight inch wide paper, and the standard display monitor has an 8 x 6 screen. The only problem is that the display often is not exactly 8 x 6. This can be because the tube is larger than normal as with most multi-sync and class-room display monitors. Or it can simply be caused by the monitor adjustments being incorrectly setup. However, except in a few special cases, such as page display monitors, the size or adjustment of the crt is usually not a problem as they are all designed around an aspect ratio of 4x3 (thus the 8 x 6 inch configuration). There are two components to the aspect ratio of both the printer and the display. There is the overall aspect ratio of the printer or display, this is what defines the actual size of the overall display or print out. This is generally defined in inches (i.e. eight inches by 6 inches), or in centimeters (i.e. 20cm by 15cm). The other component of the display is the individual pixels that make up the picture. The pixels have their own aspect ratio, and usually it is not related to the overall aspect ratio of the picture that they represent. This is particularly true on the CRT where the pixel aspect ratio will change depending on the mode in which the display is being used. There is a further complication in that the number of pixels used in the display and the printer seldom is the same, so translation from the display pixel format to the printer format is typically required. The translation factor is setup when the printer driver is initialized. The information is provided to the initialization routine by giving it the display's width and height, and the printer's width and height. (Width is 'X', height is 'Y'.) Normally the display values would represent the full display size, such as X=0,640, and Y=0,200 for a CGA 640x200 display, however since XDUMP will automatically scale the picture These values can be anything within the operational limits of the screen and printer. XDUMP is not limited to full screen print dumps. Any area within the limits of the display or printed page can be defined. The two areas do not have to be related, thus the display area could start at 100,50 and the printer area at 16,20. Each area is defined in its own pixel definition. Further, you should be aware that the printer pixel definition will normally change between landscape and upright modes, and therefore the printer definition will need to be changed if you switch modes. How the translation is done: The smallest area in which a displayed or printed picture can be broken down to is the "pixel". The pixel can be easily defined as a point on an X and Y axis. Normally the X axis is defined as going from left to right, and the Y axis as going from top to bottom. This is not always the case, such as Cartisian coordinates which go from bottom to top. But we will be dealing with the top to bottom world coordinate system because that is how the hardware on the PC is setup. Since both the display and the printer can be broken down into their individual pixel representations, this makes it possible to perform the scaling as a table lookup thereby significantly speeding up the process over directly calculating the address of each pixel on the fly. Using a translation table also provides the added benefit of allowing any sort of arbitrary translation desired, even non- linear. The disadvantage is that the table must be setup before the screen dump program can be used or anytime there is a translation change. This is the purpose of the definition program section. Another disadvantage (or advantage depending on what side of the street you're standing on) is that the screen must be defined as a pixel definition which is different and separate from the printer pixel definition which also must be defined. This can be easily handled in the definition section by providing additional translation from inches or centimeters to pixels. This of course assumes that you know what the translation factor is. By using only pixel definition at the low level there is no need to know the aspect ratio of the pixels. It is assumed that that information was known by the definition program. How the program works: XDUMP is a scaling print screen utility provided as a unit to be used with Turbo Pascal Version 4.0. To use the XDUMP utility add XDUMP to your USES statement in the calling program. XDUMP uses a record pointed at by PSR to maintain all information required to perform it's functions. This allows several different print screen definitions to reside in memory without having to redefine the PSR record. Such as one for LPT1 and a second different record for LPT2. Normally this isn't needed and would be a waste of memory since it is easy enough to redefine a record for the other printer port, but the capability is there if it is needed. To ease in the description, I will be using "PSR" or PSR record" to refer to the print screen record containing the variables that it uses. In order to reduce memory overhead, the PSR record is configured to be defined by the user program. It can be either a local variable (by passing the variable address to the print screen procedures) or it can be a variable created on the heap. This requires three steps to be performed to actually do a print screen. The first is to allocate a PSR record on the heap (See StartPrn in PD.PAS). Next the PSR record must be initialized to the desired values (See StartPrn again, and InitPrn in XDUMP.PAS). Finally, the screen is printed at the desired time by calling the PScreen procedure (see PScreen in XDUMP.PAS). There are two steps to initializing the PSR record. The first is to provide the information needed by XDUMP to know what the printout is supposed to look like and the printer port to be used. There are six primary and eight secondary variables that must be predefined. 1. GPage : This variable defines the screen page that the print dump will be performed from. This variable should be within the range of the display board being used. If the display board has only one page then it should be initialized to zero. 2. LPTnum : This variable defines the printer port to use. A zero will select LPT1, a one will select LPT2, and a two will select LPT3. 3. ScrnType : This variable defines the screen type that is currently in use. Currently this is a copy of the TP4 BGI "grdriver" variable. It is used to determine the color selection table. This currently is an area that needs to be improved. The color selection section should be split off to a separate unit so that code isolation can be maintained. It also would provide a mechanism to reduce code size in situations where only a single screen type is used. 4. PStype : This variable selects the style of the print screen that will be used. Currently there are four types available. Mode one (1) is the standard (STDmode) mode which selects the Epson printer to a pixel ratio of 120/inch horizontal by 72/inch vertical. Mode two (2) is the quick mode which selects the Epson printer to a pixel ratio of 60/inch horizontal by 72/inch vertical. Mode three is a special mode used for printing VGA screens undistorted. This mode requires a late model Epson printer that can be selected for 72 pixels per inch horizontally by 72 pixels per inch vertically. This mode only works undistorted when the landscape print direction is selected. Mode four is provided for use when a Hercules display is to be printed. This mode is only ment to be used when the landscape print direction is selected. 5. LandScape : This variable determines the direction in which the display will be directed to the printer. When false the display will print in the upright direction (the same as it appears on the screen). When it is set to true the display will be rotated sideways on the printer. 6. Mono : This variable defines whether the display is to be printer in color (false) or monochrome (true). When color mode is selected, it is assumed that you have a color printer compatible to the Epson EX-800 or JX-80 printers. There are eight other secondary variables that must also be setup before the InitPrn procedure is to be called. These secondary variables define the screen and printer dimensions that are to be used for the screen dump operation. The definitions are rectangles which define the area to be used in device pixels. The rectangle is defined as Xmin, Ymin, Xmax, Ymax. Xmin sets the first pixel in the horizontal direction to be used (left side). Ymin sets the first pixel in the vertical direction to be used (top). Xmax sets the last pixel in the horizontal direction to be used (right side). Ymax sets the last pixel in the vertical direction to be used (bottom). 1. PrnArea : This rectangle sets the definition of the printer in printer pixels. It is up to you to know what number of pixels you want to define as being the print area. 2. ScrnArea : This rectangle sets the definition of the screen area to read in screen pixels. It is up to you to know what number of pixels you want to define as being the screen area to print. Any area of the screen can be selected simply by defining it in the ScrnArea rectangle. Once these variables have been defined, the InitPrn procedure is called to finish the initialization of the print screen driver. The InitPrn procedure uses the preset information to finish the definition. Currently this includes initializing the printer select strings and color translations. InitPrn also sets up a pixel translation table based on the information provided in the screen and printer rectangle definitions. By preinitializing a screen to printer table there is no need to do the definition on the fly which allows for faster print time. When InitPrn is finished you can do a print screen at any time by calling the PScreen procedure. If you wish to change the screen area to be printed, or how it is to be displayed on the printer you will need to call the InitPrn procedure again after changing the definition. Color translations are performed via a table lookup. Currently the color print is primitive, only the base colors provided by the printer itself are printable. A bit dithering procedure needs to be added to the printing routines to provide an additional range of printer colors. When a monochrome print is performed from a color screen, the defined background color will not be printed and all foreground colors will be printed. In the current definition this means that the screen color black will not print, but all other colors will print as black. In color print out a simple color translation is performed to come as close as possible to the screen color on the printer. There is a further translation which causes the screen black to not be printed, and screen white to be printed as black. If you don't like the color translation you can either change the color translation table after calling Initprn, or change the InitPrn procedure to set up a different color translation table. XDUMP Screen Dump Modes The screen dump program is designed to provide a fast and accurate printed copy of the screen contents. Version 1.01 of XDUMP is limited to Epson compatible printers. It uses the normal and double density graphics print modes. The printout may be obtained as either landscape (sideways) or upright (normal). The following describes a particular implementation of the XDUMP program. It assumes that a full screen dump is being performed. The screen size is specified as a part of the screen mode, and the printer size is fixed based on the mode it is in. All the modes may be performed in either upright or landscape mode. However, VGA and Hercules are recommended in Landscape mode only. There are two primary modes referred to as Standard (STDmode), and Quick (QICmode). Standard mode uses double density printing mode, while Quick mode uses the Epson's "normal" print density. In normal upright mode the printer pixel width is 960. The vertical dimension is 432. In quick upright the horizontal pixel count is reduced to 480. Note that for most displays this means that some data will be lost. In normal landscape mode The printer pixel width is 800. The vertical dimension is 640 pixels. In Quick landscape the horizontal pixel count is reduced to 400 pixels. In VGA Landscape mode the printer width is set to 480. The vertical dimension is set to 640 pixels. In Hercules Landscape the printer width is set to 800, and the vertical dimension is set to 720. The screen dump works with the following display types: Display Resolution CGA 320x200 CGA 640x200 EGA 640x350 VGA 640x480 Herc 720x348 Modes: L=Landscape Q=Quick V=VGA Landscape U=Upright H=Hercules Landscape The CGA mode will print without pixel distortion in the landscape mode. The EGA mode will distort no mater what direction you print it. The VGA can only be printed well in VGA landscape mode. The VGA aspect ratio will distort by 10% in upright mode. The Herc mode will be larger in landscape mode than other display types. The VGA LandScape mode is designed to provide printouts that are undistorted in either aspect ratio or pixels for VGA displays. To operate in the VGA landscape mode the printer must be capable of operating in the 1:1 print mode (mode 5). The VGA mode is intended primarily for VGA displays in the 640x480 mode. It will provide a printout with a pixel for pixel relationship from display to the printer. The modes: The modes are controlled by several flags and identifiers. The desired mode is specified with the Init procedure. The print mode may be re-initialized at any time (other than when printing of course). LandScape mode: Initializing to LandScape mode will cause the display to be printed in the landscape configuration (sideways). This is the preferred method as it provides the least amount of pixel distortion and retains proper aspect ratio. The picture will however be slightly larger than the standard display size. The printout size will be the same for the display modes that use 320 or 640 horizontal pixels (8.9"x6.7"). The printout will be slightly larger for the Hercules display mode which uses 720 pixels (10"x7.5"). The pixels will be undistorted in the display's horizontal direction (which is the printer's vertical direction). CGA will be undistorted in the display's vertical direction (which is the printer's horizontal). EGA, VGA, and Hercules displays will have some pixel distortion (unless VGA landscape mode is used for VGA). VGA Landscape mode: The VGA landscape mode requires that the printer be capable of handling print mode 5 which sets it for a 1:1 pixel aspect ratio. This mode is provided specifically for VGA 640x480 displays so that they can be displayed without error. Normally it should not be used with other display modes since sever aspect ratio distortion will result in any of the other display modes. Hercules Landscape mode: The Hercules landscape mode is a specialized version of the normal landscape mode designed for use with the Hercules display. Normally it should not be used with other display modes since sever aspect ratio distortion will result in any of the other display modes. Quick LandScape mode: Initializing to Quick LandScape mode will cause the display to be printed in the LandScape mode, but at a slightly faster speed. This is performed by reducing the horizontal print resolution. Using this mode will cause greater pixel distortion since there is less resolution to adjust the pixels. Upright mode: The upright mode will provide a printout that is the same size as a standard display (8"x6"). This is sacrificed at the cost of pixel distortion. Pixels will be distorted in both directions in all modes. The upright mode is used to provide an overall one to one printout of the display. The print size is eight inches horizontally as is a standard display. The vertical direction is six inches as is the standard display. Quick Upright mode: Initializing to Quick Upright mode will cause the display to be printed in the upright mode, but at a slightly faster speed. This is performed by reducing the horizontal print resolution. Using this mode will cause greater pixel distortion since there is less resolution to adjust the pixels. Display Modes CGA 320x200 mode: In the LandScape and Quick LandScape modes There is no pixel distortion, and the aspect ratio is correct. Quick landscape is the preferred mode since it will print faster and there is little difference from normal landscape mode. In Upright mode and Quick upright mode there is pixel distortion in both directions, which is required to maintain the correct aspect ratio. The VGA LandScape mode should not be used, since the aspect ratio will be significantly distorted. In the LandScape mode there is a two for one pixel transfer in the printer's vertical direction. The printer's horizontal direction will have four dots for every single pixel that is displayed. In the Quick LandScape mode the printer's vertical direction is still two for one transfer, but the printer's horizontal direction will have only two dots for every single pixel that is displayed (but they will be twice as far apart as in the normal LandScape mode). In Upright mode the printer's horizontal direction will have six dots for every two pixels that were displayed. And the vertical direction will have two dots for every single pixel displayed. In Quick Upright mode the printer's horizontal direction will have three dots for every single pixel that is displayed. The vertical direction will have 13 dots for every 3 pixels displayed. LandScape print size is ---------- 8.9" x 6.7" Upright print size is ------------ 8" x 6" CGA 640x200 mode: In the LandScape and Quick LandScape modes there is no pixel distortion, and the aspect ratio is correct. Quick landscape is the preferred mode since it will print faster and there is little difference from normal landscape mode. In Upright mode and Quick upright mode there is pixel distortion in both directions, which is required to maintain the correct aspect ratio. The VGA LandScape mode should not be used, since the aspect ratio will be significantly distorted. In the LandScape mode there is a one for one pixel transfer in the printer's vertical direction. The printer's horizontal direction will have four dots for every single pixel that is displayed. In the Quick LandScape mode the printer's vertical direction is still one for one transfer, but the printer's horizontal direction will have only two dots for every single pixel that is displayed (but they will be twice as far apart as in the normal LandScape mode). In Upright mode the printer's horizontal direction will have three dots for every two pixels that were displayed. And the vertical direction will have two dots for every single pixel displayed. In Quick Upright mode the printer's horizontal direction will have three dots for every two pixels that are displayed. The vertical direction will have 13 dots for every 6 pixels displayed. LandScape print size is ---------- 8.9" x 6.7" Upright print size is ------------ 8" x 6" EGA 640x350 mode: In the LandScape and Quick LandScape modes there is some pixel distortion in the vertical display direction, but the aspect ratio is correct. The normal landscape mode is recommended for minimal pixel distortion. Pixel distortion will be noticeable in Quick landscape mode, but it will be consistent. In Upright mode there is pixel distortion in both directions. Which is required to maintain the correct aspect ratio. The VGA LandScape mode should not be used, since the aspect ratio will be significantly distorted. In the LandScape mode there is a one for one pixel transfer in the printer's vertical direction. The printer's horizontal direction will have 16 dots for every 7 pixels that are displayed. In the Quick LandScape mode the printer's vertical direction is still one for one transfer, but the printer's horizontal direction will have only 8 dots for every 7 pixels that are displayed (they will be twice as far apart as in the normal LandScape mode). In Upright mode the printer's horizontal direction will have 3 dots for every 2 pixels that were displayed. And the vertical direction will have 5 dots for every 4 pixels displayed. In Quick Upright mode the printer's horizontal direction will have three dots for every two pixels that are displayed. The vertical direction will have 21 dots for every 17 pixels displayed. LandScape print size is ---------- 8.9" x 6.7" Upright print size is ------------ 8" x 6" VGA 640x480 mode: In the LandScape and Quick LandScape modes there is some pixel distortion in the vertical display direction, but the aspect ratio is correct. The normal landscape mode is recommended for minimal pixel distortion, or the VGA Landscape mode, if possible, for no distortion. Pixel distortion will be noticeable in Quick landscape mode, but it will be consistent. If possible the VGA LandScape mode should be used, since the aspect ratio will be correctly maintained and there will be no distortion of the pixels. In Upright and Adjusted upright modes there is pixel distortion in both vertical and horizontal directions. The horizontal direction will maintain the proper pixel ratio, but the vertical direction of the printout will be 10% longer in the vertical direction in both modes. It is not possible to maintain correct aspect ratio in the upright modes. In the LandScape mode there is a one for one pixel transfer in the printer's vertical direction. The printer's horizontal direction will have 5 dots for every 3 pixels that are displayed. The Quick LandScape mode should not be used as the printer's horizontal axis cannot provide the proper resolution to hold the correct aspect ratio. The printer's vertical axis will still hold a one to one transfer, put the horizontal axis will be 20% longer than normal. The Upright mode transfers exactly the same as the normal upright mode. Neither upright mode is recommended since there will be a 10% aspect ratio error in the vertical direction. In Quick Upright mode the printer's horizontal direction will have three pixels for every two pixels that are displayed. The vertical direction will have a one to one transfer, but it cannot hold a correct aspect ratio. The printer's vertical axis will be 10% longer than normal. Only the VGA Landscape mode will provide correct aspect ratio in the VGA 640x480 display mode. VGA LandScape print size is ------ 8.9" x 6.7" LandScape print size is ---------- 8.9" x 6.7" Upright print size is ------------ 8" x 6.7" Herc 720x348 mode: In the LandScape and Quick LandScape modes there is some pixel distortion in the vertical display direction, but the aspect ratio is correct. The normal landscape mode is recommended for minimal pixel distortion. Pixel distortion will be noticeable in Quick landscape mode, but it will be consistent. The Landscape and Quick Landscape modes will be slightly larger than in the 640 modes because the printer is limited to 72 dots per inch in the vertical print direction. This will not affect the overall aspect ratio, but the printout will be larger overall. In Upright mode there is pixel distortion in both directions. Which is required to maintain the correct aspect ratio. The VGA LandScape mode should not be used, since the aspect ratio will be significantly distorted. In the LandScape mode there is a one for one pixel transfer in the printer's vertical direction. The printer's horizontal direction will have 18 dots for every 7 pixels that are displayed. In the Quick LandScape mode the printer's vertical direction is still one for one transfer, but the printer's horizontal direction will have only 9 dots for every 7 pixels that are displayed (twice as far apart as in normal LandScape mode). In Upright mode the printer's horizontal direction will have 4 dots for every 3 pixels that were displayed. And the vertical direction will have 5 dots for every 4 pixels displayed. In Quick Upright mode the printer's horizontal direction will have four dots for every three pixels that are displayed. The vertical direction will have 21 pixels for every 17 pixels displayed. LandScape print size is ---------- 10" x 7.5" Upright print size is ------------ 8" x 6" Printer Support Epson printers: Currently the only printer supported is the Epson series or compatible printers. The screen dump program can use any of the printers from the MX-80 (with graftrax) on up.