GreDrawLinesInPath

GreDrawLinesInPath draws a sequence of one or more straight lines from the sequence of linked structures addressed by pLine.

This function must be supported by all presentation drivers. However, it is not called by any specific function. GreDrawLinesInPath is used by the filing routines and the path rendering routines within the graphics engine to produce output.

Simulation support: None. This function is mandatory for all drivers.

Syntax

GreDrawLinesInPath(hdc, prclBound, pLine, cLines, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

prclBound (PRECTL) - input

Pointer to a bounding box for the lines.

Pointer to a RECTL structure

pLine (PCURVE) - input

Pointer to the first of a series of linked structures.

A pointer to the first structure in the path definition containing the lines that have to be drawn. The LINE structure, shown below, is an example of the more general CURVE structure. These two structures and the FILLETSHARP structure are defined in the header file. They all take the same general form and are distinguished by the value of bType.

The LINE structure is defined as:

bIdent Identifier. This value has no significance for the presentation driver.

bType Structure type. The only significant value is LINE_IDENTIFIER, which indicates that this structure is a LINE structure. If any other value is detected, the handling routine should skip to the structure addressed by npcvNext.

ulStyle Line style. See Line Attributes.

fl Flags. The only flag is:

CURVE_DO_FIRST_PEL When set, the handling routine must draw the first pel in the line. See also First and Last Pel Considerations.

pcvNext Pointer to next structure in the sequence.

pcvPrev Pointer to previous structure.

Reserved1[2] Reserved parameter.

ptfxA Start of the already clipped line (inclusive).

ptfxC End of the already clipped line (inclusive).

ptlA Start point of unclipped line (inclusive).

ptlC End point of unclipped line (inclusive).

lRslope Ignored by the presentation driver.

Reserved2[4] Reserved parameter.

cLines (ULONG) - input: Count of LINE structures to draw.
pInstance (PVOID) - input: Pointer to instance data.
lFunction (ULONG) - input: High-order WORD=flags; low-order WORD=NGreDrawLinesInPath.

Returns

rc (LONG) - returns

Return Codes.

On completion, the handling routine must return an integer (cHits) indicating, where appropriate, whether correlation hits were detected:

GPI_OK Successful
GPI_HITS Successful with correlation hit (returned by display drivers when the correlation flag is ON, and a hit is detected)
GPI_ERROR Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

PMERR_BITMAP_NOT_SELECTED
PMERR_COORDINATE_OVERFLOW
PMERR_DEV_FUNC_NOT_INSTALLED
PMERR_HDC_BUSY
PMERR_INV_COLOR_DATA
PMERR_INV_COLOR_INDEX
PMERR_INV_COORD_SPACE
PMERR_INV_HDC
PMERR_INV_IN_AREA
PMERR_INV_IN_PATH
PMERR_INV_LENGTH_OR_COUNT
PMERR_INV_PICK_APERTURE_POSN

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

#define INCL_GRE_LINES
#include <os2.h>

HDC       hdc;        /*  Device context handle. */
PRECTL    prclBound;  /*  Pointer to a bounding box for the lines. */
PCURVE    pLine;      /*  Pointer to the first of a series of linked structures. */
ULONG     cLines;     /*  Count of LINE structures to draw. */
PVOID     pInstance;  /*  Pointer to instance data. */
ULONG     lFunction;
LONG      rc;         /*  Return Codes. */

rc = GreDrawLinesInPath(hdc, prclBound, pLine, cLines, pInstance, lFunction);

Remarks

The structures can be a mixture of LINE, CURVE, and FILLETSHARP structures. These have similar forms and the second field, bType, identifies the type of the structure.

Starting at the structure addressed by pLine, the handling routine examines the bType field of each structure in turn. If bType is LINE_IDENTIFIER, the handling routine draws the line. Otherwise, it uses the value of the npcvNext field to skip to the next structure. This process continues until the handling routine has drawn the number of lines specified by cLines. Before drawing a line, the handling routine must check the CURVE_DO_FIRST_PEL flag to determine whether it should draw the first pel of the line. When the line passes between two pel positions, the presentation driver should round down to the nearest pel for values of 0.5 or less.

The call to GreDrawLinesInPath in the presentation driver is made by the graphics engine. Note that the coordinates are passed as screen coordinates (device coordinates + DC origin), and the lines are already completely clipped.