Microsoft KB Archive/72555

= Microsoft Knowledge Base =

PD0246: GRAPHICS.COM and Graphics Profiles
Last reviewed: May 1, 1997

Article ID: Q72555

4.00 4.01 4.01a MS-DOS kbdisplay kbappnote

The information in this article applies to:


 * Microsoft MS-DOS operating system versions 4.0, 4.01, 4.01a

This Application Note, titled &quot;GRAPHICS.COM and Graphics Profiles&quot; (PD0246) contains information about the MS-DOS GRAPHICS command and graphics profiles and gives instructions on the use of the GRAPHICS command and its switches.

To obtain this Application Note, call Microsoft Product Support Services. For complete information, see the &quot;To Obtain This Application Note&quot; section at the end of this article.

THE TEXT OF PD0246
PD0246: GRAPHICS.COM AND GRAPHICS PROFILES Revision Date: 5/91
 * INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY   |
 * ACCOMPANY THIS DOCUMENT (collectively referred to as an           |
 * Application Note) IS PROVIDED &quot;AS IS&quot; WITHOUT WARRANTY OF ANY     |
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO   |
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A    |
 * PARTICULAR PURPOSE. The user assumes the entire risk as to the    |
 * accuracy and the use of this Application Note. This Application   |
 * Note may be copied and distributed subject to the following       |
 * conditions: 1) All text must be copied without modification and   |
 * all pages must be included; 2) If software is included, all files |
 * on the disk(s) must be copied without modification (the DOS       |
 * utility DISKCOPY is appropriate for this purpose); 3) All         |
 * components of this Application Note must be distributed together; |
 * and 4) This Application Note may not be distributed for profit.   |
 * Copyright 1990-1991 Microsoft Corporation. All Rights Reserved.   |
 * Microsoft and the Microsoft logo are registered trademarks of     |
 * Microsoft Corporation.                                            |
 * Microsoft Corporation.                                            |

INTRODUCTION ============ This application note contains information about the MS-DOS GRAPHICS command and graphics profiles. It gives instructions on the use of the GRAPHICS command and its switches. It provides a description of the contents of graphics profiles and instructions for creating your own graphics profile in the event that your printer is not included in the GRAPHICS.PRO profile that comes with MS-DOS versions 4.00 and 4.01.

GRAPHICS.COM ============ The GRAPHICS.COM program enables the printing of either text or graphics video screens to an attached printer. GRAPHICS.COM works with the following video hardware:

Color graphics adapter (CGA) Enhanced graphics adapter (EGA) IBM PC Convertible LCD (LCD) Video graphics array (VGA) 8514/A adapter To run GRAPHICS.COM, you can issue the GRAPHICS command either from the DOS prompt or from a batch file. The syntax for the GRAPHICS command is as follows

graphics [type] [profile] [/b] [/r] [/LCD] [/printbox:id] where:

[type] is the type of printer attached, as defined by the profile file.

The types provided in the default profile file, GRAPHICS.PRO, are:

Type          Description ---

COLOR1        Prints on an IBM Personal Computer Color Printer with black ribbon.

COLOR4        Prints on an IBM Personal Computer Color Printer with RGB (red, green, blue) ribbon.

COLOR8        Prints on an IBM Personal Computer Color Printer with CMY (cyan, magenta, yellow, and black) ribbon.

GRAPHICS      Prints on an IBM Personal Graphics Printer, IBM Proprinter, or IBM Quietwriter.

GRAPHICSWIDE  Prints on an IBM Personal Graphics Printer with an 11- inch-wide carriage.

THERMAL       Prints on an IBM PC-Convertible Thermal Printer.

[profile] is the name of the file that contains information on all supported printers. If you omit this switch, the GRAPHICS.PRO file is used. See &quot;Graphics Profiles&quot; below in this application note for a description of profile files. Valid switches for the GRAPHICS command are defined as:

Switch        Description --         ---

/b            Prints the background in color for valid printer types.

/r            Prints black and white (as seen on the screen) on the printer. The default is to print black as white and white as black.

/LCD          Prints the image using the LCD aspect ratio of the IBM PC-convertible instead of the CGA aspect ratio. This is              the same as the /printbox:LCD switch.

/printbox:id  Selects the printbox size.&quot;id&quot; should match the first operand of a PRINTBOX statement in the printer profile. The two options available with GRAPHICS.PRO are std and LCD. The abbreviated form of printbox is &quot;pb&quot;. Notes:

If neither the /printbox nor the /LCD parameter is specified, the last PRINTBOX statement for a display is used.

The screen can be printed in up to 19 shades of gray or in up     to 8 different colors, depending on the printer.

Example
In most cases, to print a video screen to the printer, enter the following command at the DOS prompt:

graphics

When the screen displays the information you want to print, press SHIFT+PRINT SCREEN.

GRAPHICS PROFILES ================= Graphics profiles are text files that contain a list of supported printers and the commands for each video mode of the printers listed.

To define each printer's characteristics, a control structure consisting of two control statements, PRINTER and DISPLAYMODE, is used.

Each printer is defined by a PRINTER control sequence, followed by a set of DISPLAYMODE control sequences. The syntax of these sequences is as follows:

PRINTER Printer description statements - COLORSELECT - COLORPRINT - DARKADJUST

DISPLAYMODE Display mode feature selection statements - SETUP - RESTORE - GRAPHICS - PRINTBOX You can insert comments into the profile entries by preceding each comment with a semicolon.

PRINTER
The PRINTER statement initializes the description of one or more printers. The syntax is as follows

PRINTER type1[,...[,typeN]] where type is the name you assign to the printer being defined.

The maximum number of PRINTER statements within one profile is 255. Each PRINTER statement has a maximum length (including leading spaces) of 128 characters.

PRINTER Description Statements
COLORSELECT

The COLORSELECT statement is an escape sequence that is sent to      the printer to select an individual color print band. The COLORSELECT statement also tells the print screen operation the order in which colors are to be printed. The COLORSELECT statement is required for all color printers but should not be      used with black-and-white printers. The syntax of the COLORSELECT statement is

COLORSELECT colorid,byte1[,...[,byteN]]

where:

colorid is a 1-byte alphanumeric code that uniquely identifies the color print band for the particular printer type. One COLORSELECT statement should be included for each color that can be selected on the printer. The maximum number of COLORSELECT statements for a given printer is eight.

Each byte value is a number ranging from 1 to 255. The string of bytes is the escape sequence for the printer to           select the color.

The maximum length (including leading spaces) of each COLORSELECT statement is 128 characters.

If multiple COLORSELECT statements are included, they must be      on consecutive lines and must appear before the COLORPRINT statements.

COLORPRINT

The COLORPRINT statement defines the RGB (red, green, blue) values for each of the possible print colors for the printer. The overlap of the printer color bands to obtain the print colors is also determined from these statements. The COLORPRINT statement is required for color printers but should not be used with black-and-white printers. The syntax for the COLORPRINT statement is

COLORPRINT red,green,blue,colorid1[,...[,coloridN]]

where:

red, green, and blue define values in the range of 0 to           63. When a screen pixel is read, its value (RGB) is           obtained from a color translation table. The screen printing program compares this value against the list of           COLORPRINT statements and chooses the &quot;best fit&quot; in the list.

colorid is a 1-byte alphanumeric code corresponding to the codes defined in the COLORSELECT statements.

A COLORPRINT statement should be included for each color that can be printed, with a minimum of one COLORPRINT statement per COLORSELECT statement. A maximum of 255 COLORPRINT statements is allowed. If more than one COLORPRINT statement is included in the printer definition, the COLORPRINT statements must be      contiguous.

There should be one COLORPRINT statement for the color white, but the statement should have only red, green, and blue values, no colorid.

DARKADJUST

The DARKADJUST statement is used to modify the darkness of a      black-and-white printer. This statement is not valid for color printers. The syntax of DARKADJUST is

DARKADJUST darkvalue

where darkvalue is an adjustment value in the range of -63 to      63. The larger the number, the lighter the printing. darkvalue has a default value of 0.

Only one DARKADJUST statement is recognized, and it must come before the DISPLAYMODE statement in the printer definition structure. If more than one DARKADJUST statement is present, the last one will be used.

DISPLAYMODE
The DISPLAYMODE statement tells the GRAPHICS command which video modes are graphics modes. Only graphics display modes should be listed, as all video modes not listed are presumed to be text modes. Multiple DISPLAYMODE statements can be used within individual printer structures. The syntax of the DISPLAYMODE statement is

DISPLAYMODE mode1[,...[,modeN]] where mode represents the video modes described by the feature selection statements that follow the DISPLAYMODE statement. The maximum number of DISPLAYMODE statements is 255, with each statement limited to a length (including leading spaces) of 128 bytes.

Feature Selection Statements
SETUP

SETUP is an optional escape sequence that is sent to the printer to initialize the printer before each print screen operation. The syntax of the SETUP statement is

SETUP byte1[,...[,byteN]]

where each byte is sent to the printer in sequence to put the printer in the proper mode (graphics, lines per inch,      characters per inch, and so forth).

Each SETUP statement is limited to 128 characters, with a      maximum of 255 SETUP statements per profile. If a printer requires a SETUP string of more than 128 characters, multiple SETUP statements can be used. In this case, the SETUP statements must be contiguous.

RESTORE

RESTORE is an optional escape sequence that is sent to the printer to reset the printer after every print screen operation. The syntax of the RESTORE statement is

RESTORE byte1[,...[,byteN]]

where each byte is sent to the printer in sequence to put the printer in normal print mode.

Each RESTORE statement is limited to 128 characters, with a      maximum of 255 RESTORE statements per profile. If a printer requires a RESTORE string of more than 128 characters, multiple RESTORE statements can be used. In this case, the RESTORE statements must be contiguous.

GRAPHICS

The GRAPHICS statement is a required statement that initializes the printer to print a line of graphics. The escape sequence specified is sent to the printer prior to every line printed. The escape character should be included in the line along with the data count (position indicated by HIGHCOUNT and LOWCOUNT      keywords). The syntax for the GRAPHICS statement is

GRAPHICS byte1[,...[,byteN]]

The keywords HIGHCOUNT and LOWCOUNT indicate the position of      the bytes that are sent to the computer representing the low- and high-byte counts of the amount of data being sent to the printer for one line.

The GRAPHICS statement is limited to 128 bytes in length.

PRINTBOX

The PRINTBOX statement specifies the number of horizontal and vertical printer dots that are needed to represent a single screen dot (pixel). A minimum of one PRINTBOX statement is      required for every display mode. The syntax of the PRINTBOX statement is

PRINTBOX id,hsize,vsize[,ROTATE]

where:

id is the size that matches the /PRINTBOX or /LCD switch in the GRAPHICS command line.

hsize and vsize represent the number of horizontal and vertical dots required to form one screen pixel on the screen. The valid combinations are as follows:

hsize    vsize -    -

2        1                 3         1                 2         2                 4         1                 4         2                 4         3

ROTATE specifies printing the screen sideways on the printer.

If no /PRINTBOX or /LCD switch is given in the GRAPHICS command, the last PRINTBOX statement for the given video graphics display mode is used. There must be a PRINTBOX statement with an id of STD.

EXAMPLES ======== The following two examples show how to read and write profile file entries. The first example comes from the GRAPHICS.PRO file. This is the file shipped with MS-DOS 4.00 and 4.01; this file has support for IBM printers. The example demonstrates how to read a profile entry involving an eight-color printer. The second example shows how to create an entry for an EPSON(c) FX-80 black-and-white printer.

EXAMPLE 1: IBM 5182 CMY RIBBON
The following is the text found in the GRAPHICS.PRO file. This is the file shipped with MS-DOS 4.00 and 4.01 for the IBM 5182 printer.

PRINTER COLOR8             ;; 5182 CMY Ribbon

; Maximum Print width: 8&quot; ; Horizontal BPI: 168 in 1:1 aspect ratio, 140 in 5:6 aspect ; ratio ; Vertical BPI: 84 ; SETUP Statements contain the following escape sequences: ;   27,51,14 = set line spacing to 14/144 ;   27,110,[0|1] = 0 sets aspect ratio to 5:6, 1 sets it to 1:1 ; GRAPHICS Statements use ESC &quot;L&quot; with the last two bytes being ;   the data count (low,high)

COLORSELECT Y,27,121       ;; yellow band COLORSELECT M,27,109       ;; magenta band COLORSELECT C,27,99        ;; cyan band COLORSELECT B,27,98        ;; black band ;;                             ;; Following RGBs represent the first ;; 16 screen colors. ;;                             ;; SCREEN COLOR     PRINT COLOR ;;     ---  COLORPRINT 0,0,0,B          ;; BLACK            BLACK COLORPRINT 0,0,42,C        ;; BLUE             CYAN COLORPRINT 0,42,0,Y,C      ;; GREEN            GREEN COLORPRINT 0,42,42,C       ;; CYAN             CYAN COLORPRINT 42,0,0,Y,M      ;; RED              RED COLORPRINT 42,0,42,C,M     ;; PURPLE           PURPLE COLORPRINT 42,21,0,Y,C,M   ;; BROWN            BROWN COLORPRINT 42,42,42        ;; LOW WHITE        WHITE (NOTHING) COLORPRINT 21,21,21,B      ;; GREY             BLACK COLORPRINT 21,21,63,C      ;; HIGH BLUE        CYAN COLORPRINT 21,63,21,Y,C    ;; HIGH GREEN       GREEN COLORPRINT 21,63,63,C      ;; HIGH CYAN        CYAN COLORPRINT 63,21,21,Y,M    ;; HIGH RED         RED COLORPRINT 63,21,63,M      ;; MAGENTA          MAGENTA COLORPRINT 63,63,21,Y      ;; YELLOW           YELLOW COLORPRINT 63,63,63        ;; HIGH WHITE       WHITE (NOTHING) COLORPRINT 42,42,0,Y       ;; This statement maps the &quot;yellow&quot; ;; in CGA palette 0 to yellow. ;; DISPLAYMODE 4,5,13,19       ;; 320x200 SETUP 27,51,14,27,110,0 ;; aspect ratio = 5:6 GRAPHICS 32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,4,2,ROTATE DISPLAYMODE 6,14           ;; 640x200 SETUP 27,51,14,27,110,0 ;; aspect ratio = 5:6 GRAPHICS 32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,4,1,ROTATE DISPLAYMODE 15,16          ;; 640X350 SETUP 27,51,14,27,110,1 ;; aspect ratio = 1:1 GRAPHICS 32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,3,1,ROTATE DISPLAYMODE 17,18          ;; 640x480 SETUP 27,51,14,27,110,1 ;; aspect ratio = 1:1 GRAPHICS 32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,2,1 The different sections are described below.

PRINTER
The PRINTER COLOR8 statement defines this profile for the IBM 5182 color printer using a CMY ribbon. This is the name that type refers to in the GRAPHICS command-line statement.

Printer Description Statements

COLORSELECT

The profile contains four COLORSELECT statements, corresponding to the four available color bands the printer is capable of      printing. The escape codes following the COLORSELECT statements tell GRAPHICS.COM how to select the individual colors. For example:

COLORSELECT Y,27,121

This statement tells GRAPHICS.COM that whenever it needs to use the color band represented by the letter Y (yellow in this      case), it must send an escape character (27), followed by 121.

COLORPRINT

The profile contains 17 COLORPRINT statements. The first 16 represent 16 common colors. More could be added. The final COLORPRINT statement is used to map the CGA palette 0 yellow to      the printer's yellow. This printer is a good example of how to      remap the screen's RGB color model to another model. The IBM 5182 color printer uses a cyan/magenta/yellow (CMY) color model. For example, for an RGB color printer to print the color green, the graphics profile would include the following statement:

COLORPRINT 0,42,0,G

Here, 0,42,0 corresponds to the screen color green, and G is      (most likely) the letter chosen to represent the green color band of the printer. With the CMY color model, however, the statement would be:

COLORPRINT 0,42,0,Y,C

This statement instructs GRAPHICS.COM to first print yellow, then cyan whenever it needs to print green.

DARKADJUST

Because this is a color printer, no value for DARKADJUST is      needed.

DISPLAYMODE

For this example, the following DISPLAYMODE statement will be       discussed:

DISPLAYMODE 4,5,13,19

Display modes 4,5,13,19 are grouped together because they all have the same screen resolution: 320 x 200. For the most part, the groupings of the DISPLAYMODE statement represented in the GRAPHICS.PRO file (see Example 1 above) will be the ones used for color printers, as they are broken down by resolution.

Feature Selection Statements
SETUP

The following SETUP escape sequence

SETUP 27,51,14,27,110,0

first puts the printer into 14/144 line spacing by sending the escape character (27), the line spacing command (51), and the line spacing value (14). Next, the aspect ratio is set to 5:6 by sending the escape character (27), the aspect ratio command (110), and the aspect ratio value (0).

RESTORE

The only change made to the printer by the SETUP command in the example above is the line spacing. Because there is no way to      obtain the line spacing value from the printer, there is no way to know what to set it back to. Therefore, no RESTORE statement is necessary.

GRAPHICS

The GRAPHICS statement contains the sequence of bytes sent to      the printer before each line of data is sent. The following statement first prints four spaces (32) to give a border, followed by the escape sequence to set the printer up for graphics printing:

GRAPHICS 32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT

The escape character (27) is followed by the GRAPHICS command (76). The LOWCOUNT and HIGHCOUNT keywords represent the order of the bytes that represent the count of the data bytes following the escape sequence. The printer expects the count to      be in the form of LOWCOUNT,HIGHCOUNT. Depending on the printer type, these values may need to be reordered or even placed in a      different location in the command sequence.

PRINTBOX

The following PRINTBOX statement describes the orientation and box size to use when printing from a standard (non-LCD) screen:

PRINTBOX STD,4,2,ROTATE

STD matches the /printbox:id switches used in the GRAPHICS command line.

4,2 represents the number of dots to print on the printer horizontally and vertically for each pixel on the screen. These dots are absolutes. This means that even if the image is      rotated (using ROTATE), the order is not changed. In this case, the image is rotated, so each pixel on the screen will actually be turned into two horizontal dots and four vertical dots on      the printed image.

EXAMPLE 2: EPSON FX-80 PRINTER
The Epson FX-80 is a black-and-white printer that has an 8-inch carriage. In double-density mode, there are 120 dots per inch horizontally and 72 dots per inch vertically. To make the printer work by printing eight pins (which is what GRAPHICS.COM expects), you must set the line spacing accordingly. The printer can print 72 dots per inch, but only eight dots at a time, so you must print those eight dots nine times per inch. Because the printer accepts line spacing in parts of 216ths of an inch, and you must set the line spacing to 1/9th inch, the vertical line spacing should be 24/216th inch.

To set the FX-80 to 24/216-inch line spacing, GRAPHICS.COM must send an escape sequence consisting of the escape character (27), the line spacing command (51), and the value of line spacing (24).

To start the profile for the Epson FX-80 printer, you must declare the name of the printer. To do this, use the following PRINTER statement:

PRINTER EPSONFX-80 There are no color options available on the Epson, and because each printer is different, the DARKADJUST option is left alone and will default to 0.

Next, you must determine the different display modes. For the example, only one display mode group will be shown. The display mode will be the CGA-resolution compatible modes (320 x 200). The display modes that have the resolution of 320 x 200 are 4, 5, 13, and 19. The DISPLAYMODE statement for this is as follows:

DISPLAYMODE 4,5,13,19 Next, the printer must have a SETUP line to set the line spacing before every print screen operation. The syntax for this line is:

SETUP 27,51,24             ; Set line spacing to 24/216&quot; Because the printer resets itself to text mode after every line of graphics has been printed, there is no need for a RESTORE command.

You must now set up the commands to tell the printer to print a line of graphics. The command sequence to put the printer into graphics mode is the escape character (27), the GRAPHICS command (76), and 2 bytes of count data in the low-count, high-count order. To give the image a border, spaces can be printed before sending the printer into graphics mode. The syntax for this statement is:

GRAPHICS 32,32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT The final step in the process is to decide how to print the image. The orientation of the screen is best represented if the image is rotated. Therefore, you must map the vertical dots on the screen (200) to horizontal dots on the printer (120 dpi) and horizontal dots on the screen (320) to vertical dots on the printer (72 dpi).

Because the area that will be printed is a result of the size of the printbox chosen, you must make the size of the printbox big enough to produce a good-sized picture, yet small enough to fit on the page. Using a horizontal box size of one printer dot per screen dot would result in 200 dots being printed and would be 1.67 inches across on the printed page. Therefore, to produce a 6.7-inch-wide picture, a horizontal box size of four printer dots per screen dot should be used. (Because the image is rotated, this 6.7-inch page width represents the height of the image.)

To calculate the vertical printbox size, you must take the horizontal box size into consideration. Because the image on the printer is 6.7 inches across, the vertical size of the image must be bigger to keep the perspective the same as it is on the screen. The screen is 320 dots wide, and the printer prints at 72 dots per inch vertically. If the vertical box size chosen is 1, then 320 dots would be printed, resulting in an image that is 4.4 inches long, which is out of proportion. However, an image that is 8.8 inches long is about the right size. 13.2 inches would not only be out of proportion but also would be too large for a standard 8.5-inch x 11-inch sheet of paper. Therefore, the horizontal and vertical box sizes for the PRINTBOX statement should be 4 and 2, respectively. The printbox id is set to STD. The syntax for the PRINTBOX statement should be:

PRINTBOX STD,4,2,ROTATE The final profile for the Epson FX-80 is:

PRINTER EPSONFX-80

DISPLAYMODE 4,5,13,19 SETUP 27,51,24 GRAPHICS 32,32,32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,4,2,ROTATE

DISPLAYMODE 6,14 SETUP 27,51,24 GRAPHICS 32,32,32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,4,1,ROTATE

DISPLAYMODE 15,16 SETUP 27,51,24 GRAPHICS 32,32,32,32,32,32,32,27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,2,1,ROTATE

DISPLAYMODE 17,18 SETUP 27,51,24 GRAPHICS 27,76,LOWCOUNT,HIGHCOUNT PRINTBOX STD,2,1,ROTATE

TO OBTAIN THIS APPLICATION NOTE

 * You can have this Application Note mailed or faxed to you by calling Microsoft Product Support Services Monday through Friday, 6:00 A.M. to 6:00 P.M. Pacific time at (425) 646-5104. If you are outside the United States, contact the Microsoft subsidiary for your area.