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 "GRAPHICS.COM and Graphics Profiles" (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 "To Obtain This Application Note" 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 "AS IS" 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. |
--------------------------------------------------------------------
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 "Graphics Profiles" 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."id" 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 "pb".
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 "best fit" 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"
; 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 "L" 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 "yellow"
;; 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"
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.
KBCategory: kbdisplay kbappnote Last reviewed: May 1, 1997 |
