PDDR/2 - 32-Bit Plotter Presentation Driver

The Plotter Presentation Driver is a 32-bit vector graphics driver. Vector graphics drivers use drawing primitives, such as lines, arcs, boxes, circles, and area fills, to draw complex graphics images. The Plotter Presentation Driver relies on the graphics language capabilities of the printer or plotter to do the actual drawing.

For example, to draw a circle, the plotter driver sends the circle command with radius information to the printer. The printer has the responsibility of drawing the circle on the device.

The vector graphics languages that this driver supports are Hewlett-Packard Graphics Language (HP-GL and HP-GL/2) and IBM Graphics Language (IBM-GL). If the device or graphics language does not support the OS/2 drawing function, the driver will either call back to the graphics engine for simulation or convert the drawing function to a supported primitive. For example, an OS/2 FillPath call might be converted to a HP-GL/2 FillPolygon.

The Plotter Presentation Driver can also support devices that can mix HP-GL/2 and raster data such as laser printers or raster plotters. In the DEBUG version of the driver, a sample PCL laser printer is supported. The RETAIL and DEBUG versions of the driver support raster plotters using the HP-RTL language.

The files that comprise the Plotter Presentation Driver are PLOTTERS.DRV and PLOTTERS.HLP. PLOTTERS.DRV is the executable code and data of the driver. The PLOTTERS.DRV file exports OS2_PM_DRV_ENABLE, OS2_PM_DRV_DEVMODE, and OS2_PM_DRV_DEVICENAMES entry points. PLOTTERS.DRV has an extended attribute (EA) that must be present for the driver to be installed correctly. The PLOTTERS.HLP file contains the help panels for the Job Properties and Printer Properties dialog boxes of the driver.

Generic Printer Library (GenPLib)
The Generic Printer Library is a set of subroutines that are useful for 32-bit presentation drivers. The Plotter Presentation driver takes advantage of the following GenPLib functions: For further information about the Generic Printer Library, see Generic Printer Library.
 * Memory management routines
 * Multi-threading output capabilities
 * Error and debugging support routines

Font Support
The example plotter driver code supports only one device font. The HP-GL/2 or IBM-GL font named Stick is the plotter driver's default font. This font is a fixed-spaced, scalable font. A fixed-spaced, scalable font is one that can be scaled to any character width and height by setting the character attribute CBB_BOX. As soon as the font is scaled, the width of all characters will be constant.

Changing the code to support another fixed-spaced, scalable font is not difficult and can be achieved through the following steps:
 * 1) Add a data structure to enumerating the FONTMETRICS information of each supported font.
 * 2) Change the PlotterClass data structure in to include a bit fields defining which fonts each device supports and the appropriate default font.
 * 3) Modify the function in  to set the correct default device font.
 * 4) In, make return the additional fonts and make  select the font.

Adding proportional-spaced fonts requires the following additional changes: The plotter driver uses a combination of the device name and the device class to support printers. The device name is the name of the device that is used to look up the corresponding device class information in the plotter driver's plotter definition table, PlotterDef[].
 * 1) In, modify to scale the width of all the characters in the font.
 * 2) Change the character positioning functions, , and to use the proportional font character width and kerning information.

The PlotterClass data structure contains all the information describing the characteristics of the of the device.

The plotter driver currently supports the following devices and corresponding device classes:
 * IBM6180 CLASS_HP7440A
 * IBM6182 CLASS_HP7550A
 * IBM6184 CLASS_HP7570A
 * IBM6186 CLASS_HP7595A
 * IBM6186 CLASS_HP7596A
 * IBM7371 CLASS_HP7470A
 * IBM7372 CLASS_HP7475A
 * IBM7374 CLASS_HP7580B
 * IBM7375-1 CLASS_HP7585B
 * IBM7375-2 CLASS_HP7586B
 * HP7440A CLASS_HP7440A
 * HP7470A CLASS_HP7470A
 * HP7475A CLASS_HP7475A
 * HP7550A CLASS_HP7550A
 * HP7570A CLASS_HP7570A
 * HP7580A CLASS_HP7580A
 * HP7580B CLASS_HP7580B
 * HP7585A CLASS_HP7585A
 * HP7585B CLASS_HP7585B
 * HP7586B CLASS_HP7586B
 * HP7595A CLASS_HP7595A
 * HP7596A CLASS_HP7596A
 * PaintJet XL HP-GL/2 CLASS_PAINTJET_XL
 * DesignJet 600 CLASS_DESIGNJET600
 * DesignJet 650C CLASS_DESIGNJET650
 * DraftMaster SX CLASS_DRAFTMASTER_SERIES
 * DraftMaster RX CLASS_DRAFTMASTER_SERIES
 * DraftMaster MX CLASS_DRAFTMASTER_SERIES

To add a new device that will be supported by an existing class, complete the following steps: To add a new device class to the plotter driver, complete the following steps:
 * 1) Add the device name to the PlotterDef[] table in.
 * 2) Add a define in DIALOG.H that defines a numeric constant for your device. The numeric constant will be used to load the device description string that you must add to the PLTUS.RC file.
 * 1) Add a new PlotterClass structure to PLOTTERS.C defining your new class.
 * 2) Add a define in PLOTTERS.H for the class.
 * 3) Add an entry to the PlotterDef[] table along with a device name that uses the class.

Plotter Modules and Functions
This section provides a layout of the Plotter Presentation Driver source code. Refer the DDK CD for the Plotter Presentation Driver source code and to the "Using Your DDK", also available on the DDK CD, for a roadmap of the file structure used by the source code.

The first part of this section lists in alphabetical order all functions found in the Plotter code. The module in which each function is found is listed next to the function.

The second part of this section lists the modules that comprise the Plotter driver and the functions that comprise each module. Each function is followed by a description.

Function List
=Module and Function Descriptions= This section describes the modules that comprise the Plotter driver and the functions that comprise each module. Each function is followed by a description. The functions in each module are listed in alphabetical order.

ATTRIBS.C
This module contains plotter driver attributes.

DeviceGetAttributes
Gets plotter driver attributes. This function is the entry point for external processes to obtain information about the current attributes of the plotter driver.

DeviceSetAttributes
Sets plotter driver attributes. This function is the entry point for external processes to modify the current plotter driver attributes.

DeviceSetDCOrigin
Sets the DC origin. The device origin is 0,0 when enabled. The device is responsible for adding this offset to all transformed coordinates. The plotter driver returns errors because SetDCOrigin is not journaled and would cause problems in color-sorting mode.

DeviceSetGlobalAttribute
Sets the global attributes of different types of attributes.

ErasePS
Resets the presentation space.

get_area_attr_bundle
Returns information from the current area attribute bundle according to the AttrsMask parameter.

get_char_attr_bundle
Returns information from the current characterattribute bundle according to the AttrsMask parameter.

get_image_attr_bundle
Returns information from the current image attribute bundle according to the AttrsMask parameter.

get_line_attr_bundle
Returns information from the current line attribute bundle according to the AttrsMask parameter.

get_marker_attr_bundle
Returns information from the current marker attribute bundle according to the AttrsMask parameter.

GetDCOrigin
Gets the Device Context origin. Assigns values to the coordinates.

GetStyleRatio
Used for banding printers that use the display driver for writing into bit maps. The plotter returns 1:1.

initialize_ddc
Initializes device driver instance. Resets the device driver instance data structure to its base state.

LockDevice
Locks a device.

set_area_attr_bundle
Sets area attributes.

set_char_attr_bundle
Sets information from the current character attribute bundle according to the AttrsMaskparameter.

set_image_attr_bundle
Sets image attributes.

set_line_attr_bundle
Sets line attributes.

set_marker_attr_bundle
Sets marker attributes.

SetStyleRatio
Sets the style ratio.

UnlockDevice
Allows all pending screen input or output operations that were blocked by to continue.

validate_any_color
Validates color.

validate_background_color
Validates background color.

validate_background_mix
Validates background mix.

validate_foreground_color
Validates foreground color.

validate_foreground_mix
Validates foreground mix.

BAND.C
This module contains the callback function passed to GenPLib banding routines.

band
Retrieves surfacebitmapinfo and fills the appropriate structures to internally call the function to output the surface.

BITMAP.C
This module contains bit-map related functions.

begin_raster_graphics
Sends the necessary commands to get into raster graphics transfer mode.

Note: Raster Mode may be either PCL or RTL.

bin_output_bytes
Outputs binary data by calling the thread code to output the data on the second thread.

Note:This function should only be called after output_bytes has been called at least once. output_bytes makes sure the header information has been sent.

Bitblt
HPGL-1 devices

Transfers bit maps directly from memory. The plotter driver supports Bitblt only to bypass an optimization in the engine. This optimization causes the engine to use the driver's Bitblt function to perform area fills. Therefore, you must verify that the function is the area fill (ROP_PATCOPY), verify the options, and then continue. Anything else is rejected as if the function is not installed.

Note: This function was completely rewritten to support the Raster Operations.

HPGL-2 devices

The BitBlt function copies a bitmap from one presentation space to another. It can also modify the bitmap within a rectangle in a presentation space. The exact operation carried out by BitBlt depends on the raster operation specified by the Mix parameter.

If Mix directs BitBlt to copy a bitmap, the function copies the bitmap from a source presentation space specified by hdcSrc to a target presentation space specified by hDC. Each presentation space must be associated with a device context for the display, for memory, or for some other suitable raster device. The target and source presentation spaces can be the same if desired. The pXY parameter points to an array of points that specify the corners of a rectangle containing the bitmap in the source presentation space as well as the corners of the rectangle in the target presentation space to receive the bitmap. If the source and target rectangles are not the same, BitBlt stretches or compresses the bitmap to fit the target rectangle.

If Mix directs BitBlt to modify a bitmap, the function uses the raster operation to determine how to alter the bits in a rectangle in the target presentation space. Raster operations include changes such as inverting target bits, replacing target bits with pattern bits, and mixing target and pattern bits to create new colors. For some raster operations, the function mixes the bits of a bitmap from a source presentation space with the target and/or pattern bits.

bitblt2
This function is hooked for PCL color devices. If bitmap stretching is necessary, this function gets the bits from a bitmap and sends them to the device. If bitmap stretching is not necessary, this function calls back to the engine to get.

Build_Palette
Sets the PCL/RTL Palette and outputs the necessary escape sequences to the device to build the Color Palette in the device.

convertbgr_to_rgb
Converts a source scan line from BGR format and to RGB order.

DeviceCreateBitmap
Creates a plotter driver bit map. This function is called to create a bit map of the specified form and to obtain its handle.

DeviceDeleteBitmap
Deletes a plotter driver bit map. This function is called to destroy a specified bit map created by.

DeviceSelectBitmap
Selects a plotter driver bit map. This function tells the device driver that a new bit map is being selected into the given DC.

DeviceSetCursor
Sets the cursor bit map that defines the cursor shape. This function will return an error.

download_pattern
Downloads a user-defined pattern to the device for area fills. This function is called from in.

DrawBits
Draws a rectangle of bits.

DrawBorder
Draws a border inside a rectangle and optionally fills the interior. This is a accelerator and will return an error.

DrawImage
Projects the image of a rectangle onto the source DC's bit map and onto the printer.

end_raster_graphics
Sends the necessary commands to get out of raster graphics transfer mode.

Note: Raster Mode may be either PCL or RTL.

enter_PCL_or_HPRTL
Sends the necessary commands to get the plotter into PCL or HPRTL mode. This is necessary to setup the device for a raster transfer.

fill_pattern
Called from for ROP_PATCOPY. Fills a rectangle specified by the rclDst with the pattern bits in pBits.

fill_pattern_Use_Device
Handles both HPGL2 and PCL to fill a rectangle with patterns. This function is called from for ROP_PATCOPY with user pattern.

GetBitmapBits
Transfers bit map data from the specified DC to application storage. The DC must be a memory hDC with a bit map currently selected.

GetBitmapHandle
Returns the bit map handle.

GetGreyPattern
Returns the pattern byte to the caller.

GetNextColor
Reads source color bits and determines the number of pels that are the same color as the first pel. This function enables you to greyscale many pels at one time. This function returns the current RGB color and updates the pointers to the source bits, the current pel position, and the total number of continuous pels of the current RGB color.

GetPel
Gets a pel from a position specified in world coordinates. This function returns -1 for error. Otherwise, it returns the color table index value for the pel.

greyscalesourcebits
Takes the current source bit map and converts the bit map into a greyscaled 1,1 bits into pBits.

ImageData
Draws a row of image data.

image_scan
Outputs the commands to transfer data to the device and transfers the data.

ImageScan
Outputs the commands to transfer data to the device and transfers the data.

locate_rfpen
Takes a color value in RGB format, looks through the currently defined pens for the color, and returns the pen number. If a pen with the same RGB color is not found, this function defines a new pen for the given color and returns that pen number.

sdBitBlt
Called from the new raster GRE if we hooked the function. This function prints an array of pre-clipped and pre-stretched bit maps.

set_graphics_position
Sends the necessary commands to set the position while in PCL or HPRTL mode.

set_raster_width_and_height
Sends the necessary commands to set the source width. The destination width and height will only be set if you are scaling the bitmap.

Set_RFIndex
Sets the Raster Fill index and the height and width of the rectangle. This function is called from.

RestoreScreenBits
Restores a rectangle of bits saved by. Because this is a printer, the driver logs and error.

return_to_HPGL2
Sends the necessary commands to get the plotter back into HPGL mode from raster mode.

Note:Raster Mode may be either PCL or RTL.

rotate_4bpp_90
Called from, this function rotates a bitmap 4 bits-per-pel by 90 degrees. This function assumes that the source is byte aligned.

rotate_8bpp_90
Called from, this function rotates a bitmap 8 bits-per-pel by 90 degrees. This function assumes that the source is byte aligned.

rotate_bmap_90
Depending on the number of bits per pel, this function calls the appropriate function to rotate a bitmap by 90 degrees. This function currently supports only four and eight bit-per-pel bitmaps. This function is called from and.

SaveScreenBits
Saves a rectangle of bits from the screen. The plotter driver returns an error.

SetBitmapBits
Sets a plotter driver bit map. This function transfers bit map data from application storage to the specified DC. The DC must be a memory hDC, with a bit map currently selected.

SetPel
Sets a pel from a position specified in world coordinates. The plotters driver returns OK for this function.

Set_Palette
Controls the PCL/RTL palette. This function performs the following:
 * 1) Saves the HPGL2 Palette, if it is not already saved.
 * 2) Sends the necessary configure image data command to the device. The configure image data command is based on the cBitCount of the bit map.
 * 3) Sets the number of bits per index in the Configure Image data command.
 * 4) Calls the Build_Palette to build the Palette.

vector_bitmap
Turns the bitmap into line commands for non-raster devices (pen plotters).

BOUNDS.C
This module contains functions that control bounds accumulation.

AccumulateBounds
Adds the given bounds into the existing bounds.

accumulate_line_bounds
Determines the bounding box of the line whose end points are passed.

GetBoundsData
Returns bounds data to user. The units that are returned are specified by the parameters.

ResetBounds
Resets either or both sets of bounding data.

BOX.C
This module contains functions associated with drawing boxes.

BoxBoth
Draws the edges of a box and fills the interior. One corner is the current position, the other corner is supplied. The box can have rounded corners.

BoxBoundary
Draws the boundary lines of a box. The box can have rounded corners.

BoxInterior
Draws the interior of a box. The box is drawn from the current position to a position supplied to the function. The box can have rounded corners.

calc_bounds
Determines the bounding rectangle for the array of POINTLs given.

draw_box
Generates the plotter command to draw a box from the current position to the given end point. The box can be a filled box or a boundary box.

CHARGEN.C
This module contains output functions for device font characters.

construct_char
Generates a sequence of commands to produce the desired character. Any manipulation that is required is performed, including switching to another character set.

CLIP.C
This module contains clipping routines for the OS/2 Plotter Presentation Driver.

apply_clipping
Determines the overall clipping rectangle and returns it to the caller. If the prIn of the passed-in rectangle is not zero, it is included. If the prIn of the passed-in rectangle is zero, it is ignored. The basic clipping information is obtained from the DDC.

Following are the three states of the clipping handles:
 * AC_RECT0 (Effectively) no clipping. prResult untouched.
 * AC_RECT1 One clip rectangle, returned in prResult.
 * AC_RECT2 Multiple clipping rectangles.

choose_endpoints
When this function is given the horizontal components (x) of four co-linear points that intersect a quadrilateral's extended boundary walls, it returns the values of the innermost two (those that span the interior of the figure ).

get_bounds
Returns the rectangular bounds (bounding box) of a point list.

get_quad_clip
Returns a rectangle of an arbitrary height extending above a given scan line. When bStart is true, the first scan line is processed. When bStart is false, the next scan line is processed.

init_quad_clip
Initializes the QCINFO structure supplied by the caller.

merge_clip_rect
Merges the myriad of clip rectangles to produce the largest single rectangle that covers the area.

NotifyClipChange
Called whenever an application requests to change any of the clipping bounds for the current PS/DC pair.

output_clip_rect
Sets the current soft clip limits at the plotter device.

Notes
 * 1) This routine is called from multiple locations within the driver. It is important not to modify the pClipRect data fields within the pPDevice portion of the driver instance data.
 * 2) If ClipComplexity == 0 and pPDevice->ClipComplexity == 1, the rectangle is a null rectangle.

prdl_MemClipChange
Sets the clipping region of the shadow memory DC. This function copies the DC region of the DC and sets the same in the shadow memory DC. Therefore, both will be in sync.

quad_sort
Sorts the corner points of a quadrilateral into counter-clockwise order. The result is returned in the original array.

rectl_intersect
Intersects the last two parameters and returns the result in the first parameter.

set_clip_rectangle
Sets the current soft clip limits at the plotter device.

COLOR.C
This module contains color/pen and pattern support functions for the OS/2 Plotter driver.

check_area_background_color
Checks the area background color and validates the capability of the plotter to output the current area fill color.

check_area_color
Checks the area color and validates the capability of the plotter to output the current area fill color.

check_char_background_color
Checks char background color and validates the capability of the plotter to output the current charbackground fill color.

check_char_color
Checks the character color and validates the capability of the plotter to output the current character color.

check_color_sorting
Determines the available pen color that is nearest to the requested color and uses this pen in direct mode. If you are playing back the journal file, you can only record the information.

check_line_color
Checks the line color and validates the capability of the plotter to output the current line color.

check_marker_color
Checks the marker color and validates the capability of the plotter to output the current marker color/marker.

color_distance
Returns the distance between two colors based on the HLS or RGB squaring system.

constrain_hls
Constrains an HLS color to certain regions of the color wheel. If the color is grey, it is forced to white or black. If not, it is forced out to the rim of the wheel.

convert_color
Accepts a color in the current device format and returns the RGB color.

create_default_color_table
Generates the default color table. This function is called at enable_dc time to create the default color table information. It can be called at reset_dc time to reinitialize the color table to its default state.

CreateLogColorTable
Creates a logical color table for the current device context.

devicepalette
This function currently does nothing except return true; however, it must remain hooked for the new graphics engine.

get_closest_color
Gets the closest color to the RGB value passed in and returns the closest match currently available.

get_closest_pen
Returns the stall number of the pen that most closely matches the specified color. If RGBIn == WHITE, it returns 0.

get_color_group
Gets the color group and returns information about whether a pen is a paper pen, a transparency pen, or something else.

locate_HPGL2pen
Finds the currently defined HPGL2 pen. If the pen is not yet defined, define a new pen. No priority is given to usage. This function should be called only if the user is using application colors (if (pSetup->usFlags & FL_USEAPPCOLORS) is set.

locate_pen
Finds the closest available pen color. Priority is assigned as follows:
 * 1) Lines
 * 2) Fills
 * 3) Text

QueryColorData
Queries the current color data and returns information regarding the currently selected color support for the driver.

QueryColorIndex
Queries the color index and returns the index of the RGB color value that most closely matches the RGBColorparameter.

QueryLogColorTable
Queries the logical color table.

QueryNearestColor
Returns the available color nearest to the specified color on the currently associated device even if it is not available in the logical color table.

QueryRealColors
Returns an array of the distinct colors available on the device.

QueryRGBColor
Returns the actual RBG color that results from the specified index. If the color index is in RGB mode, the nearest RGB color is returned.

RealizeColorTable
Realizes the color table.

return_rf_fill_pen
Returns the pen number for the RF instruction.

rgb_to_hls
Converts an RGB color value to HLS format.

Note: Application colors should never be set with color sorting ON.

select_fill_pen
Selects the fill pen.

select_fill_type
Selects the HPGL fill type that most closely matches the OS/2 pattern. Sets the direction of fill lines if this is supported on the particular plotter. Deciding whether or not to fill depends on the shape of the area being filled and the orientation of the paper. The fill type is a function of the direction to fill, the spacing between lines (currently 0 to default to pen thickness), and the type of line to draw (bi-directional). Bi-directional lines are not as precise as uni-directional, but uni-directional lines are much faster because the pen does not have to be lifted.

select_HPGL2pen
Selects the pen using the HPGL2 pens in the Dynamic Pen Palette (not the Carousel pens). This function is called when (pSetup->usFlags & FL_USEAPPCOLORS) is set. This function generates the HPGL command to select a specified pen from the palette.

select_line_pen
Selects the line pen and returns the stall number of the pen that most closely matches the Color parameter.

select_text_pen
Selects the text pen.

select_user_defined_pen
Generates the HPGL command to select a specified pen.

set_HPGL2_color_palette
Called during processing for HPGL2 devices only. Sets number of pens with the NPn; command, where n is the number of pens in the palette. If n is not a power of 2, the plotter uses the next larger power of 2.

set_mix_mode
Sets the Merge Control (ROP) in the device.

set_pen
Sets the RGB of pen.

set_pen_width
Generates the HPGL1 or HPGL2 command to set the pen width for HPGL2 or pen thickness for HPGL1.

set_transparency_mode
Checks and sets the transparency mode (TR). TR defines how the white areas of graphics images are plotted. IN (initialize) and DF (default condition) instructions return TR to its default. White is defined as the white reference specified by the CR (color range) instructions.

setup_raster_fill_index
Determines if the device supports user-defined patterns for area fills. If the device supports these patterns, this function gets the pattern bitmap handle from the graphics engine and calls the appropriate function to download the pattern bitmap to the device for area filling.

start_color_sorting
Sets up PLOTTERS to begin color sorting. Ensures the correct mode is not the first pass from spooler queue processor and that the user has selected color_sorting from the dialog box. This function is called to enable journaling for color sorting. It is called at enable time, and at each new page.

stop_color_sorting
Stops color sorting. This function is called at the end of a page and the end of a frame. Its basic operation is to replay the journal file and perform only those operations requiring the current pen. Thus, all drawing operations are completed for each pen in one operation, thereby reducing the number of (slow) pen change operations. This function processes the color sorting information and is called at the end of a page. This function will stop journaling, then play the journal file for each pen used in the carousel. It will set the current pen based on lightness to darkness for a given carousel. If an ABORTDOC signal is received, the bEnableOutput flag will be cleared, further output will cease (output_bytes will stop sending), and the rest of the journal file replay will be skipped.

UnrealizeColorTable
Unrealizes the color table.

COMPRESS.C
This module contains bit-map compression routines.

compress_adaptive
Block-based adaptive.

Compression for RTL.

compress_any_supported_mode
Row-based compression.

Function will select the best compression supported by the device select the mode and output the data. This function will work for both RTL and PCL devices.

DEVMODE.C
This module contains the functions for the Job Propertiesand Printer Propertiesdialog boxes.

build_app_name
Builds the app name from the printer driver and device names. For example, an app name of

PM_DD_Printer,PLOTTERS.LaserJet 4 HP-GL/2

is built from:

Printer name Printer

Driver name PLOTTERS

Device name Laserjet 4 HP-GL/2

check_menuitem
Checks or unchecks a menu item in a menu. If status is TRUE, the menu item is checked. If status is FALSE, the menu item is unchecked.

check_pen
Sets the check status in the PenColor and Type menu to bStatus. The check status is set only if a single pen is selected in the carousel configuration list box because this is the only time the items in these two pop-up menus will be checked.

check_pens
Check the currently selected pens to see if the menu items must be enabled or disabled.

CleanUpHelpStubHook
Exit list routine that ensures the removal of the stub HK_HELP hook before exiting.

clear_entries
Turns all items in the PenColor, Type, and Options menus to inactive (gray). This is required either when a new carousel is selected or the user does not have a pen selected in the carousel configuration list box.

display_carousel
Displays the currently selected carousel information in the static fields.

display_colors
Determines the allowable colors and types that can be selected in the PenColor and Type pop-up menus. On entry, the menu status table for the PenColor menu is set to all TRUE (indicating any pen can be selected). The Type menu status table is initialized according to the pen types supported by the current plotter. Then, each pen that is selected in the carousel configuration list box is examined. If no pen is in the stall, no operation is performed. Otherwise, all PenColor menu items that the selected pen type does not support are made inactive (grayed). Likewise, all Type menu items that do not support the color of the given pen are made inactive (grayed). Finally the update menu function is called for the PenColor and Type pop-up menus.

display_paper_size
Displays the current paper size in the main dialog box. If the paper size is A thru E or A4 thru A0, the dialog elements for the determination of the roll length are hidden and the current paper size is shown through static text. If the paper size is either a 24-inch or 36-inch roll, the paper size static message is hidden and the dialog elements for the roll length are shown. If roll feed is selected, the input focus of the main dialog is set on the roll length input box. The current paper size is then checked in the pop-up menu.

display_pen
Displays a pen description for the given pen in the carousel text fields. The pen description consists of the pen color and the pen type.

display_pens
Resets the contents of the carousel configuration list box for the current carousel. Because the display_pen function inserts its pen description at the specified position, a "dummy" string must be created for the duration of the carousel configuration construction. Once completed, this string is deleted. If any pens were selected prior to this construction, the check marks must be removed from the PenColor and Type menus and the PenColor, Type, and Options pop-up menus must be made inactive (grayed).

EA_GetVersion
Retrieve the EA.VERSION from driver file.

get_group
Returns the group in which a pen is classified. (For example, P3 and P7 are paper pens; T3 and T6 are transparency pens.)

get_module_dir
Returns the size of the directory path.

get_string
Loads the string number message from the resources file and places it in the message buffer in the DEVMODE structure. Returns the address of the string buffer in DEVMODE.

GetMeasureItemInfo
Calculates the height and width of the text string for the WM_MEASUREITEM message.

help_dialog_proc
Dialog procedure for help.

HelpErrorFilter
Checks for a recoverable help manager initialization error. If a recoverable error is detected, a message box pops up. The message box describes the error and asks if the user wants to retry.

HelpStubHook
This hook is placed in the HK_HELP hook chain to catch the first time that the user presses PF1 or selects a Help push button. The driver then initializes the help instance and gets the user's help request passed back into the HK_HELP chain again by making a call to the private function WinCallHelpHook.

init_dialog
Initializes the main dialog box. This initialization is done upon entry and when the user changes the current plotter. This function performs the following duties:
 * Sets the window caption to the current plotter and checks it in the Plotter menu.
 * Checks the current and active carousels and displays the current carousel above the carousel configuration list box.
 * Initializes the paper feed selections and options.
 * Initializes the orientation selections.
 * Displays the current paper size.
 * Disables the PenColor, Type, and Options pop-up menus.
 * Constructs the carousel configuration list box.
 * Determines paper size support and updates the Size pop-up menu.

InitializeHelp
Initializes help. If an attempt to create a help instance has already been made, return immediately.

list_pen_options
Displays (in the Pen Options dialog box) the value for the given option for each pen selected from the carousel configuration list box. The following are the available pen options: Speed and acceleration are true values. Force is an index in a table of values that is dependent upon the current plotter.
 * Speed
 * Force
 * Acceleration

list_pen_priority
Displays (in the Pen Options dialog box) the priority for each pen selected from the carousel configuration list box. The following are the possible priorities:
 * NONE
 * LINE
 * FILL
 * TEXT

main_dialog_command
Handles the user interface of the main dialog box. This dialog box can only be enabled by the exported function DeviceMode. If something is processed, TRUE is returned. If nothing is processed, FALSE is returned.

main_dialog_proc
Main dialog box window procedure where all window functions are processed. WM_COMMAND type functions are passed to the local function main_dialog_ command.

options_dialog_proc
Handles the user interface of the pen options display and modification dialog box. The options that apply are:
 * Speed
 * Force
 * Acceleration

OS2_DevPostDeviceModes
Called by applications that want to change the attributes of the driver, such as the device and pen configuration. OS2_DevPostDeviceModes gets the values based on the pszDeviceName passed from the OS2.INI file. The flags passed in determine the type of operation required by the caller, where bits 0-1 mean the following:
 * %00 - Display dialog, no update to the INI file
 * %01 - Display dialog, update INI file
 * %10 - Do not display dialog, just return INI information
 * %11 - reserved

pencolor_dialog_proc
Handles the user interface for selecting the pen color. Displays a list box of available pen colors and updates the main dialog with the color selection.

priority_dialog_proc
Handles the user interface for the display and modification of the pen priority. Each pen selected in the carousel configuration list box can be tagged with any of the following priorities:
 * None
 * Lines/Text
 * Fill

For all fill output, a pen that has fill priority will be selected over another pen of the same color that does not have fill priority. Likewise, for all lines and text output, a pen that has lines and text priority will be selected over another pen of the same color that does not have lines and text priority.

ReleaseHelpStubHook
Removes the stub HK_HELP hook from the hook chain, if it has been successfully added via.

reset_entries
Updates the PenColor and Type pop-up menus through a call to display colors, determines the options supported by the current plotter, and updates the Optionspop-up menu.

save_profile
Saves the setup data in OS2SYS.INI. The setup data is placed in a private section of PLOTTERS and the record is identified by pszDeviceName. pszLogAddress (for example "IBM6180.PLOTTER1").

SetHelpStubHook
Adds the stub HK_HELP hook to the hook chain. This addition allows the driver to gain control the first time that the user presses PF1 or selects a Help push button.

switchbetween_rgb_carousel
Switches between RGB and carousel modes, depending on the user's choice in printer properties dialog box.

szStrCopy
Copies a string from the source to the destination. If the string is null terminated, the copy stops when the terminator is hit. Otherwise, the copy continues for the number of bytes passed in.

update_menu
Sets the status of a pop-up menu to the menu status table given by pMenuList. The three pop-up menus with menu status tables are:
 * PenColor
 * Type
 * Options

DISPATCH.C
This file contains functions and macros that hook and unhook entries in the dispatch table.

exchange_dispatch
Modifies the engine-supplied dispatch table.

Hook_UnHook
UnHooks all the functions that are not mandatory and hooks all the mandatory functions. Provides support for bit map handling and memory DC.

DOSIO.C
This module contains the high-level output functions that communicate with the output thread code to output data to a file or device. See Output- Thread Management for further details.

close_file_or_device
Closes the output device.

get_ieee_addr
Returns the IEEE address from the argument.

get_ini_comm_info
Extracts COM port modes from the OS2SYS.INI file.

get_new_outbuff
Gets an output buffer from the head of the free queue or allocates a new one if no buffers are available on the free queue.

initialize_comm_port
Sets the COM port to the conditions determined from the OS2.INI file.

initialize_outputinfo
Initializes outputinfo semaphores.

open_file_or_device
Opens the file name or device passed in. This file name or device is where the output will go. It can be a COM port, an IEEE port, or a disk file.

open_spooler_queue
Sets up the connection to the spooler that the output has been sent to.

output_bytes
This function is a call that the driver uses to output data. This function calls Thread_Fill_Outbuff to put data on the output thread.

perform_std_spooling
At the end of the spooling activities this function writes the metafile data to the spooler.

putbuff_on_dataqueue
Puts the buffer on the end of the data queue (OutputInfo.obqData).

ENABLE.C
This module contains functions that are used when the device context is initialized or disabled.

disable_dc_begin
This ENABLE subfunction is called before a DC starts its disable process. This function initiates any final clean up prior to the full disable, such as closing journaling, performing color sorting, and closing the spooler.

disable_dc_complete
This ENABLE subfunction is called when a DC has completed the disable process. This function releases any memory that was allocated for the DC instance (pDDC).

disable_pdev
This ENABLE subfunction is called when a physical device block is to be deleted. This function releases any memory that was allocated in and closes the pathway to the device.

enable
This function is the entry point OS2_PM_DRV_ENABLE for the plotter driver. This ENABLE function is exported by the device driver and performs the initialization of the device driver, the physical driver, and device contexts.

enable_dc_begin
This ENABLE subfunction is called each time a DC is created. This is the first time the DC handle is presented and is the time to allocate the DC. The corresponding physical device pointer is the one that was returned in.

enable_dc_complete
This call informs the driver that the DC has been created by the graphics engine. It is the first time the pDDC that was returned in EnableDC is presented. At this time, this function opens the spooler if it is handling a queued DC. Any metafiles or journaling is started in this function.

fill_ldev
This ENABLE subfunction is called when the driver is loaded and initializes the logical device block. This initialization includes setting some bits telling the engine that the driver needs a PDEV per DC and hooking the functions the driver will support.

fill_pdev
This ENABLE subfunction is called each time a DevOpenDC is requested by the application. This function creates and allocates a physical device block, which should contain any information needed to perform I/O to the specified device.

fill_pdev_save_dc_data
Allocates memory from the pdevice block and saves the spooler parameters (if they exist) from the enable dc structure.

initialize_pdevice
Initialize the device instance (PDevice) fields.

querydevicesurface
This routine is used by the graphics engine to query the device surface information. This function fills the DEVICESURFACE structure to be used by both the graphics engine and the device driver.

reset_dc_state
This ENABLE subfunction is called to reset a DC to its original initialized state.

restore_dc_state
This ENABLE subfunction is called when the engine wants the device driver to POP a saved DC or to POP to a specified DC.

save_dc_state
This ENABLE subfunction is called when the engine wants a device driver to save all DC information. This function can be called multiple times, and the driver should push the DDC in LIFO order.

setup_colors
This function is called from and sets up the color information for the selected plotter.

ESCQUERY.C
This module contains the functions for the exported entry points DevEscape,, , and.

Escape
Provides device-specific interface to the driver.

GetPageData
Gets information on the physical page size.

Extracts information about the physical page size. pPDevice points to the relevant entry in the PaperResTable and PrintOffTable for this particular plotter. The form is the number for the particular paper size. These range from 0 to 4 for sizes A to E (imperial), 5 to 9 for A4 to A0 (metric), 10 for a 24-inch roll, and 11 for a 36-inch roll.

number_of_hardcoded_forms
Returns the number of forms available on this particular device.

QueryDeviceBitmaps
Returns a list of bit map formats supported by the device. The plotter driver supports no bit maps, so this function sets the return data to zero out the return data area, as required.

QueryDeviceCaps
Returns information about the device capabilities.

Information is returned to the caller in pData. Count items are returned, starting with the value Index. Values that are transform-sensitive are returned in DEVICE UNITS, such as the character size.

QueryDeviceNames
Returns information about the device names available from this driver, and about the datatypes handled. QueryDeviceNames is a direct entry point into the driver. It bypasses the dispatch table mechanism because many applications will call this function without calling the enable functions to initialize the driver.

QueryDeviceResource
Called by the user at the time of setup to load all pointers and bit maps and called by the engine to load the default fonts, if any. This is a required function. The plotter driver returns zero, for "resource not available".

querydevresource2
This function is called by the user on setup to load all pointers and bitmaps, and by the engine to load the default fonts (if there are any). This is a required function.

QueryHardcopyCaps
Returns information about the hardcopy capabilities of the device. Function either returns the number of forms available, or returns information about (selected) forms available.

FONT.C
This module contains the code and data for font support.

cpxfm_metrics
Copies fontmetrics from source to destination, up to count bytes. Any required transformations are applied.

Warning: This function overwrites the data at pMetricsSrc. If this data is valuable, it should be copied before this function is called.

DeviceQueryFontAttributes
Returns the font metrics for the currently selected font. If this is an engine font, the driver calls back. Otherwise, the driver copies to a local buffer, and then transforms the values from font notational to world space.

DeviceQueryFonts
Returns information about the plotter's built-in fonts.

FindVectorLength
Finds the length of a given vector.

GetExtraIncrements
Calculates the amount of the space to increment between each character in a string. The application must use GpiSetCharExtra or GpiSetCharBreakExtra to enable the extra spacing.

GetHorizTextAlignShift
Finds the text alignment shift in the horizontal direction, based on the usTextAlignment.

GetStandardAlignment
Finds the standard text alignment, based on the direction of the text.

GetVertTextAlignShift
Finds the text alignment shift in the vertical direction, based on the usTextAlignment.

QueryCharPositions
Determines the origin of each character in the given string and adjusts for the character direction.

QueryTextBox
Queries text box for the given char string and returns the coordinate of the text box.

QueryWidthTable
Returns information about the width of the characters in the currently selected font. If the current font is the hardware font of the plotter, information is returned from QueryWidthTable. Otherwise, the call is passed onto the engine because the engine knows more about fonts than QueryWidthTable.

RealizeFont
Performs the following four functions:
 * 1) Realizes a device font.
 * 2) Realizes an engine font as a device font.
 * 3) Deletes a device font.
 * 4) Deletes an engine font realized as a device font.

FORMS.C
This module contains functions that handle user-defined forms.

add_user_form
Queries the dialog. If the information is valid, it inserts that information into the linked list.

add_user_forms_to_list
Determines how many user-defined forms exist for an application name, and then inserts each user-defined form name into the given list box. This function also allocates a user-defined form element and associates it to the newly created list box item.

convert_list
Walks through the linked list and converts the integer measurements into a string form for the user to eventually see.

delete_user_form
Queries the dialog for the current form, and then searches the linked list for that form. If it finds the form, it will delete it from the linked list.

delete_user_forms_from_list
Deletes any item that has a handle from the given list box. (Only user- defined forms should have this property.) Any user-defined form will be deleted from the list box and its associated memory will be freed.

display_error
Displays a message box that contains the string ErrorName with the ID ErrorMessage.

display_form_id
Given a linked list element, this function updates the window's name with that element's ID.

display_user_form_paper_size
Given an element in a linked list, this function updates the dialog with the correct information.

find_user_form_size
Searches the INI file for that user-defined form ID and updates the printable X and Y mm sizes.

HeightNumericSubProc
Subclassing procedure for an entry field. Its purpose is to allow only numeric input.

id_conflicts
Walks through the linked list and searches for an element that has the same ID (it will not check against itself). If there is a conflict, it will return that element's form name.

IDNumericSubProc
Subclassing procedure for an entry field. Its purpose is to allow only numeric input.

initialize_user_forms
Reads the user-defined forms into a linked list and returns the current unit of measurement and the number of forms that have been defined.

llAddElement
Adds an element that contains the given information into a linked list. To do this, the function creates an element, copies the information to it, and adds it to the linked list.

llCreateElement
Allocates a linked list element off the heap in the instance data and initialize that element.

llDeleteElement
Given a linked list and a pointer to one of its elements, this function deletes that element from the linked list. This function also cleans up any resources used by that element.

llFindElement
Searches through the linked list for an element whose form name matches the form name that was given. If successful, it returns a pointer to that element.

llFreeAllElements
Given a linked list, this function deletes every element in that linked list.

measurement_to_string
Converts an integer (in hundredths of a millimeter) into a string of a real numbers.

modify_user_form
This function performs the following:
 * 1) Queries the dialog for the information that the user has entered
 * 2) Validates the information
 * 3) Searches the linked list for the form
 * 4) Changes the data that was stored in the linked list element to the data that the user has entered.

name_conflicts
Walks through the linked list and searches for an element that has the same form name (it will not check against itself). If there is a conflict, it will return that element's form name.

number_user_forms_defined
Searches the OS2SYS.INI for the AppName entry and returns the number of forms that have been defined.

return_flat_user_forms_list
Searches the OS2SYS.INI for the application name and the user-defined forms entry. If there are no user-defined forms, it will return NULL. Otherwise, it will return the contents of the INI file entry.

save_user_form
Given a linked list, this function writes out the user-defined forms into the OS2SYS.INI file. If the number of forms is 0, it will delete the user- defined form information from the OS2SYS.INI file.

string_to_measurement
Converts the string representation of a real number into an integer representation. This integer will be in hundredths of a millimeter.

user_defined_forms_dialog_proc
This is the dialog procedure for the user-defined forms.

user_form_exists_exists
Searches the user-defined forms in the INI file under the application name for the given form name.

WidthNumericSubProc
Subclassing procedure for an entry field. Its purpose is to allow only numeric input.

GLIB.ASM
This file contains trigonometric functions to calculate the sine, cosine, and arc tangent of an angle.

arc_tan
Returns the angle of the point in dx,ax in ax scaled by 10. The point is first scaled by Xaxis and Yaxis in order to handle an elliptical arc.

Arctan
Given an origin and a point this function returns the arc tangent of point to the nearest tenth of a degree.

Cosine
Given an Angle (0 - 3600) this function returns the cosine of the angle. The angle is assumed to be in tenths of a degree. The calculated cosine is scaled by 16384.

get_angle
Given a point in ax,dx, this function determines arc tangent or angle of the given point. The angle is returned in ax.

get_quadrant
Determines the quadrant of ax,dx and returns in cl.

icos
Given a degree in si, this function returns cosine in ax scaled by 16384. Degrees range from 0 - 3600. bx,cx,dx are destroyed.

isin
Given a degree in si, this function returns sine in ax scaled by 16384. Degrees range from 0 - 3600. bx,cx,dx are destroyed.

reduce_angle
Reduces the angle in si to the range 0 - 90 * 10. It also determines the quadrant of the angle which is returned in cl.

Sine
Given an Angle (0 - 3600) this function returns the sine of the angle. The angle is assumed to be in tenths of a degree. The calculated sine is scaled by 16384.

INIT.ASM
This file contains ASM utility routines.

copymem
Copies memory is a manner similar to memcpy;.

Int3
Debugging routine to issue a software interrupt 3.

PSZ ENGENTRY SetMem
Sets memory to a value.

setmem
The plotter version of memset;.

INITTERM.C
This module contains the DLL initialization and termination functions.

_DLL_InitTerm
Initializes the PMPLOT.DRV. Saves the HMODULE assigned from the operating system.

LOCKDDC.C
This file contains the lock and unlock code for the driver's instance data.

EnterDriver
Entry to a hooked Gre function. Protects the pDDC while it is in the driver.

initfsrsem
Initializes the semaphore structure.

LeaveDriver
Works with EnterDriver to ensure that threads with different IDs are not accessing the same pDDC. Exits from a hooked Gre function.

MARKER.C
This module contains functions used to draw the supported marker types. Only PolyMarker is exported to the world.

draw_polymarker_circle
Draws a small filled circle marker.

draw_polymarker_cross
Draws a crosshaired PolyMarker.

draw_polymarker_diamond
Draws a diamond PolyMarker.

draw_polymarker_dot
Draws a small filled circle marker.

draw_polymarker_eightpointstar
Draws an eight-pointed PolyMarker.

draw_polymarker_plus
Draws a plus-sign PolyMarker.

draw_polymarker_sixpointstar
Draws a six-pointed PolyMarker.

draw_polymarker_solidsquare
Draws a filled square marker.

draw_polymarker_soliddiamond
Draws a filled diamond marker.

draw_polymarker_square
Draws a square PolyMarker.

PolyMarker (Exported)
Draws a series of Markers at the specified locations.

NEW.ASM
This module contains functions that perform mathematical operations.

addfxquad
Adds two quad numbers.

fx_fxmulfx
Prepares the stack for fxmultiply and calls fxmultiply to multiply two FIXED numbers.

fxmultiply
Multiplies two 32-bit fixed point numbers and returns a FIXED. FIXED is a signed 32-bit number with 16-bits of integer and 16-bits of fraction.

fxtofxquad
Converts a fixed long value to a fixed quad value.

l_ldivfx
Computes the SIGNED LONG quotient of a SIGNED LONG and a SIGNED FIXED.

quad_square_root
Approximates the square root of an unsigned BIGFIXED.

sroot
Returns the square root of the given positive 32-bit value.

OUTPARC.C
This file contains all the drawing routines used to create arc primitives for the plotter.

Arc (Exported)
Creates an arc using the current arc parameters and a pointer to two x,y coordinate pairs. The arc is drawn from the current position (a) through the first coordinate pair (b) to the second coordinate pair (c). Upon completion, the current position is updated to the end of the arc (c).

construct_chord_tolerance
Outputs the chord tolerance for the Circle and Arc commands to the plotter, based on the radius received.

ConvertArcParams
Converts the lQ and lP arc parameter values using the fixed multiplier and the current transform.

draw_fullarc
Draws a fullarc (circle or ellipse), given its center point and a radius. If Fill is TRUE, the fullarc is filled. Otherwise, it is outlined. Upon completion, the current physical pen position is at the center of the circle.

Note: This function should only be called for circles and not for ellipses.

FullArcBoth
Creates a FILLED and OUTLINED full arc with its center at the current position. A multiplier can be specified to apply to the current arc parameters. Upon completion, the current x,y position is not changed.

FullArcBoundary
Creates an outlined full arc with its center at the current position. A multiplier can be specified to apply to the current arc parameters. Upon completion, the current x,y position is not changed.

FullArcInterior
Creates a FILLED full arc with its center at the current x,y position. A multiplier might be specified to apply to the current arc parameters. Upon completion, the current x,y position is not changed.

get_angle
Returns the angle of a line in tenths of a degree.

get_arc_center
Sets the center point of a circle defined by three points on the circumference of that circle.

get_distance
Returns the distance, in specified coordinates, between the two given points.

get_line_intersection
Returns the intersection point of two lines defined by pPtsAB[0], pPtsAB[1], pPtsCD[0], and pPtsCD[1]. This function returns TRUE if successful. Otherwise, it returns FALSE for "lines are parallel".

get_perpendicular_bisect
Returns line CD, which runs perpendicular to and bisects line AB.

is_elipse
Determines if an ellipse will be drawn instead of a circle.

Note: This code is copied from draw_fullarc. Any changes to draw_fullarc might have to be duplicated here.

PartialArc
Draws two figures: A sweep angle of greater than 360 degrees is valid. After the line is drawn, a full arc is drawn, followed by a partial arc with a sweep angle of (sweep MOD 360) degrees. The current position is updated to the final point of the arc.
 * A straight line from current position to the starting point of the partial arc
 * The arc, with its center at the specified point

PolySpline
Draws a sequence of one or more Bezier splines starting at the current position. As each spline is drawn, the specified end point of the spline becomes the start point for the next spline. Upon completion, the current position is the end point of the last spline.

set_arc_scale
Sets up the scaling for the arc parameters.

SetArcParameters
Sets the arc parameters for subsequent arc, fullarc, partialarc functions.

OUTPLINE.C
This file contains all the primitive line drawing functions used by the Plotter.

DisJointLines
Draws a sequence of disjoint straight lines. This is an optional function.

DrawLinesInPath
Loops through the given path and draws all lines it finds in that path. This is a required function.

GetCurrentPosition
Returns the logical pen position to the (X,Y) pointed to by pPts. The physical pen position (the actual location of the pen) might be different.

GetLineOrigin
Returns the logical pen position to the (X,Y) pointed to by pPts. The physical pen position (the actual location of the pen) might be different.

PolyLine
Draws a series of connected lines, starting at the current position. The input is in world coordinates and the final position is at the last point.

PolyScanline
Fills an area lying between polyshortline pairs by using the current pattern attribute. Notice that coordinates are passed as unclipped screen coordinates. Filling is inclusive at the left boundaries and exclusive at the right boundaries. The scan lines are ordered from bottom-to-top and from left-to-right.

PolyShortLine
Processes polyshortlines. A pointer to the shortline header is passed. Within the header, start points and stop points are specified. Following the header is an array of Xs (currently 16 bits). The curve starts at x0,y0 and ends at x1,y1. The number of x values is then determined by the absolute value of y1-y1+1. If y1 is greater than y0, y0 is incremented until it equals y1. If y1 is less than y0, y0 is decremented until it equals y1. The current position is not affected by this call.

SetCurrentPosition
Sets the current position to the supplied position. This value is recorded in both world and device coordinates, so that, if required, the values can be transformed into device coordinates.

SetLineOrigin
Sets the current position to the supplied position. This value is recorded in both world and device coordinates, so that, if required, the values can be transformed into device coordinates.

OUTPUT.C
This module contains utility routines for producing output on a vector plotter that supports HPGL.

check_fill_type
Checks the currently set fill type.

check_line_construction
Determines if the PS/DC pair has a line currently in construction.

check_string_construction
Determines if a string label is currently in construction. If so, terminate the string label.

construct_fixed
Given a fixed point number, this function outputs it as a floating number with up to 4 digits following the decimal point. Trailing zeroes after the decimal point are truncated. A simple 0 is output if the converted number is zero.

construct_float
Generates a formatted floating point number for output to the plotter as part of command string. The number received by this function can have any number of decimal places. The multiplier parameter will determine the number of decimal places. For example, 2000 with a multiplier of 1000 = 2.0 and 2000 with a multiplier of 10000 = .20.

construct_point
Outputs an (x,y) coordinate pair to the plotter, applying any needed transformation.

convert_point
Converts a point to a different coordinate system.

draw_line
Draws a line.

draw_point
Draws a single point.

end_doc
When the end of the current document has been reached, this function sends the necessary sequence of commands to prepare for the next document.

end_job
When the current plot job has ended, this function closes the relevant path.

end_page
If the current page of output is full, this function sends the appropriate command sequence to obtain a new page, and initializes it for output.

get_closest_point
Given the three points A, B, and C, this function determines if B is closer to A than C.

lift_pen
Lifts the pen if it is not already lifted.

move_pen
Updates the current physical position of the plotter pen or, if an area fill is being performed, updates the DDC's physical pen position information.

next_band
Enables a new band or calls end page if on the last band. Only roll feed plotters are banded.

output_comma
Outputs a comma.

output_number
Outputs a number (integer implied) to the plotter as part of a command string.

output_point
Outputs a standard coordinate pair (x,y).

plot_line
Plots a line from the current physical position or queues the line for later output if an area fill is currently in effect.

send_header
Sends prerequisite commands to the plotter to initialize the device for the next or new page.

send_trailer
Sends a command string that terminates a single page of output to the plotter.

set_default_p1p2
Initializes the default plotting extents.

set_default_scale
Sets the default scale for the current hardcopy device and media size.

set_empty_rect
Initializes a rectangle (RECTL) structure to enclose a null (unit) rectangle.

set_line_type
Sets up the active line type, such as dot-dash and dash.

set_p1p2
Sets the current plotting extents.

set_scale
Sets the current values for plotter-applied scaling.

set_rotation
Rotates the plotter coordinate system 90, 180, and 270 degrees.

start_doc
Sets up the plotter for a new document. This function is called by start page, and is the second highest level initialization call. It initializes the beginning of a document (which is different from the beginning of a page because multiple pages might exist in a document).

start_job
Sends the necessary command sequence to start a plotter job.

start_page
Sends the necessary commands to setup the plotter for a new page of output.

PATHS.C
This module contains path-related functions.

BeginArea
Indicates the beginning of a set of drawing operations to define an area boundary.

clear_patsym_area
Called only for HPGL2 devices. This function depends on the code "set_color _palette" in to set pen 0 to white. If the area is not complex, it fills the area with a rectangle command. If the area is complex, it draws a series of horizontal white lines into the current clip path.

draw_patsym_diag
Draws a series of diagonal lines into the current clip path.

draw_patsym_horiz
Draws a series of horizontal lines into the current clip path and sets up line endpoints, adding 1 to the right and subtracting 1 from the left to ensure that joining lines are clipped out.

draw_patsym_vert
Draws a series of vertical lines into the current clip path.

draw_pattern_lines
Draws a series of line patterns.

EndArea
Indicates the end of the drawing operations defining the area.

fill_clip_area
Fills the currently selected clip path or clip region.

fill_polygon
Fills the area by querying the outline of the path and filling the outline as a HPGL polygon. This function only fills the area if: Current plotters can only handle 1 clip rectangles.
 * Clipping is simple. (1 clip)
 * Fill mode is alternate (FPATH_ALTERNATE)
 * Engine version is 2.02 or later

Notes:
 * 1) Because older plotters have small polygon buffers, this method might not always work.
 * 2) On the 32-bit Engine (version 2.02 or greater), calling GreOutlinePath with the new option (NO_CLIPPING_REQD) results in a call to the DrawLinesInPath function for each unclipped subpath. On the 16-bit Engine, calling GreOutlinePath results in many calls to the PolyShortLine function for each subpath. Because the end of the subpath is too difficult to predict on the 16-bit engine or older versions of the 32-bit engine, the polygon filling method is used only on engine versions 2.02 or later.

fill_the_clip_rectangles
Fills the area by filling the clip rectangles.

This code improves the speed of filling large simple areas.

Six clip rectangles was chosen for plotters because it included wide line boxes which produce four clip rectangles. More complex areas are not filled on plotters because filling an area with boxes does not optimize pen up (PU ) commands on normal plotters.

On HPGL2 devices, complex areas are filled entirely with this method.

FillPath
Fills the path specified by the user.

PaintRegion
Paints the specified region using the current area foreground and background colors. Mixing is controlled by the area foreground mix only.

The driver could handle the PaintRegion by calling GreGetRegionRects and filling the rectangles itself.

PolygonSet
Draws a set of closed polygons. The polygons are filled using the current AREABUNDLE structure values. For the first polygon, the current position is the first point. For all subsequent polygons, all points that define the polygon are given explicitly. If necessary, the polygons are automatically closed by drawing a line from the last vertex to the first.

Notes: This function is called as a result of GpiPolygonSet and is called internally by DevicePolygonSet.
 * Polygons can overlap, if necessary.
 * This is a new function for 2.0.
 * GrePolygonSet is not valid when the COM_AREA or COM_PATH flag is set.

StrokePath
Converts the path to a wide line.

Note: The select_pen function in will set the pen width to the geometric width if the instance variable pDDC->DCState.bWideLines is true. lineend and linejoin will be set in set_line_type if pDDC->DCState. bWideLines is set.

PLOTTERS.C
This module contains definitions of plotter characteristics for all supported plotters. The following structures are included in PLOTTERS.C:
 * PlotterClass
 * PlotterDef
 * usPlotterCount
 * PrintOffTable
 * PhysicalPageSize

PRDMATH.ASM
This file contains ASM functions for data type FIXED point math.

frdiv
Computes the FIXED quotient of two FIXED numbers.

frmul
Computes the FIXED product of two FIXED values.

frsqrt
Computes the Fixed square root of a Fixed. This routine simply pulls the parameter off the stack, puts it in EAX, and calls the square_root function.

iq_div
Keeps track of the signs and calls idiv to perform the processing.

square_root
Computes the FIXED square root of a FIXED number.

ulNormalize
Normalizes a ULONG so that the highest order bit 1 and returns the number of shifts performed. Also returns ZF=1, if the ULONG was zero.

PROFILE.C
This module is the interface to plotter-specific data. These functions access the information stored in the global data structures defined in PLOTTERS.C and retrieve and store data in the OS/2 INI file.

copy_device_info
Returns the device characteristics for the requested plotter index.

copy_pen_option_info
Returns the pen option characteristics for the requested plotter index.

get_defaults
Fills the default set up data for the given plotter ID.

get_device_id
Matches the given name with the names of known devices, and then return the desired information.

get_printer_name
Scans the PM_SPOOLER_PRINTER section of the OS2.INI file, looking for a printer attached to either the queue or logical address pointed to by pszLogAddress, and then looks for the queue name if this is a queued DC.

The format of OS2.INI file is:

Device_name;PORT;Driver.Type;Queue;; Where:
 * device_name is the name in the Control Panel "Printer Connections" section
 * PORT is the serial/parallel port to which the device is connected, such as COM1
 * Driver.Type is the name of the driver (PLOTTERS in our case)
 * Type is the particular type of plotter, such as IBM6180
 * Queue is the name of the spooler queue associated with this device

get_profile
Looks for the entry pDeviceName.pPrinter in the private section of the OS2SYS.INI file. This function contains initialization data for the particular type of plotter being used. A typical name is "IBM6180.PLOTTER1".

TEXTOUT.C
This module contains OS/2 plotter presentation driver text output functions and internal and external text-related output functions.

adjust_char_attrs
Adjusts the current character size and angles using the currently defined transforms.

calc_QTB
Computes the character cell size for clipping purposes.

CharString
Outputs a character string, starting at the current position.

CharStringPos
Outputs a character string at the specified point.

clip_char
Handles complex clipping of a single character.

GetCodePage
Returns the current code page.

GetPairKerningTable
This function is required to hook, but it is not supported.

set_cell_angle
Sets the angle character attribute.

set_cell_shear
Sets the shear angle character attribute.

set_cell_size
Sets the cell size character attribute.

set_char_angle
Sets the anglecharacter attribute.

set_char_italic_bold
Sets the italic and bold character attributes.

SetCodePage
Sets the current code page.

string_clip
Determines the clip limits of the supplied string information.

UTILS.C
UTILS.C is a general utilities module.

clear_memory
Clears Size bytes of memory.

compare_memory
Compares memory at address pAddr1 with the memory at pAddr2, for Size bytes.

ConvertWithRotation
Converts an X length and a Y length, accounting for rotation.

copy_memory
C function to copy memory.

Note: The Assembler function cpymem is preferred.

distance
Returns a value proportional to the plot distance between 2 points. The plot distance is defined as the larger of (delta x, delta y). This concept works with plotters because the pen can move in both directions at the same time. Therefore the time to move to a new position is determined solely by the larger of the X or Y distance.

fill_opt_end
Flushes any remaining buffered lines and releases memory.

fill_opt_init
Initializes the fill-optimization code.

find_device_name
Given a logical address (queue name, port name, or file name), this function returns the string containing the spooler's printer name. The caller must free this string (it is allocated off of the heap).

find_printer_name
Given a logical address (spooler printer name, spooler device name, port name, or a UNC name), this function returns the string containing the spooler's printer name. The caller must free this string (it is allocated off of the heap).

flush_opt_buffer
Processes the contents of the area fill optimization buffer, drawing a minimal (not minimum) path through the accumulated line segments.

free_memory
Deallocates memory from the heap or frees the memory from system.

C/Set Conversion: Four extra bytes from memory have been allocated to store a flag and the size of memory required.

get_mod_handle
Returns the module handle (hModule).

int_to_str
Converts the given integer to its character representation and returns the length of the string representing the integer. The integer can be positive or negative. The resulting string is assumed to describe a string of a length sufficient to hold the character representation of the integer and a trailing NULL. The resulting string will be at least MinDigitsin length.

IsIta_COM_Port_Name
Checks the physical port name. Any port name that begins with "COM" and is appended with any integer greater than or equal to 1 will be valid.

IsIta_Device_Name
Checks that the physical device name is supported.

lstrcmp
Compares the two strings for equality. This function ignores the case.

lstrcpy
Copies from string pFrom to pTo.

lstrlen
Returns the length of the NULL-terminated string passed.

lstrncmp
Compares the two strings for equality for a given length. This function ignores the case.

lstrtoksrch
Searches for the Char token in the string pointed to by the input pointer, replaces this with a NULL, and updates the pointer past the NULL.

prompt_for_carousel
Prompts the user to insert the specified carousel.

prompt_for_page
Prompts the user to insert a sheet of paper.

queue_opt_buffer
Records a pair of points (line segment) in the area fill optimization buffer for processing when the buffer fills and is flushed.

return_driver_data
Given a logical address (queue name, port name, or file name), this function searches for a plotter device name. It will place the device name string in pszDeviceName. If multiple plotter devices are attached to the printer (spooler term), the function will return the first one because there is no way to determine the proper one to select.

round_divide
Divides two numbers and rounds up or down.

save_mod_handle
Called from the initialize routine when the driver is loaded. Its purpose is to save the handle to the module in a ring 2 data segment.

str_to_int
Converts an integer string to an integer value. The integer value is passed back through pInt. A pointer to the first position past the integer value in the string is returned as a result. Leading spaces are ignored and overflow is accounted for by this function.

to_upper
Converts a character from uppercase to lowercase. This function will return valid driver data. It will also allocate a copy of driver data and initialize it to its default state. It is the caller's responsibility to free this data. If driver data was passed in, the function will check to see how much of that data can be copied over its initialized driver data.

XFORMS.C
This module contains conversion and transformation functions.


 * f_ldivf:Divides a long by a FIXED, returning a FIXED.
 * Limitations This function was written specifically for generating the sine and cosine values in a triangle. As such, it might have restrictions not suitable for general use. The result is assumed to be less than or equal to 1.0000.


 * f_lsqrt:Returns the square root of the unsigned long argument. The value is returned as a FIXED number.
 * get_angle_xform:Generates a rotation matrix from character direction data.
 * newton_f_lsqrt:Evaluates a square root using Newton's approximation method, using a fixed number of guesses.
 * NotifyTransformChange:Handles changes to the transformation matrixes as reported from the engine and returns the result of an indirect call to the GreNotifyTransformChange.

This function is called when the world->device transform is changed. Processing is as follows:
 * 1) Transform the current position.
 * 2) Then,
 * If it is outside the allowed 16-bit range, return an error.
 * If the position is OK, call the engine's entry point.

The pXformData structure specifies the new transform matrix.