GreNotifyTransformChange

GreNotifyTransformChange notifies the presentation driver of a change in the transform from world coordinates to device coordinates.

This function must be supported by the presentation driver.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreNotifyTransformChange(hdc, flFlags, pXformdata, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

flFlags (ULONG) - input

Flags.

A set of flags that pass information regarding the complexity of the 2x2 matrix of the M11, M12, M21, and M22 components (of the composite transform from world coordinates to device coordinates). These flags indicate if a translation is required. If the MATRIX_SIMPLE flag is not set, none of the other flags are valid.

MATRIX_SIMPLE: Two entries are 0.

MATRIX_UNITS: All entries are +1 or -1.

MATRIX_XY_EXCHANGE: Zeros are on the diagonal.

MATRIX_X_NEGATE: X is hit by negative (see Note).

MATRIX_Y_NEGATE: Y is hit by negative (see Note).

MATRIX_TRANSLATION: Non-zero translation.

Note

MATRIX_X_NEGATE and MATRIX_Y_NEGATE are only meaningful when both MATRIX_SIMPLE and MATRIX_UNITS are set.

Examples:

Matrix = { 1.0, 0.0, 0.0, 1.0, 0, 0 } =>

Flags = MATRIX_SIMPLE | MATRIX_UNITS

Matrix = { 1.0, 0.0, 0.0, 1.0, 5, 10 } =>

Flags = MATRIX_SIMPLE | MATRIX_UNITS | MATRIX_TRANSLATION

Matrix = { 0.0, -1.0, 1.0, 0.0, 17, 5 } =>

Flags = MATRIX_SIMPLE | MATRIX_UNITS | MATRIX_XY_EXCHANGE |

MATRIX_Y_NEGATE | MATRIX_TRANSLATION

pXformdata (PNOTIFYTRANSFORMDATA) - input

Pointer to NOTIFYTRANSFORMDATA structure:

usType

Indicates fixed-point notation

xform

XFORM data structure contains fixed-point values

fxM11

Fixed-point matrix elements

fxM12

Fixed-point matrix elements

fxM21

Fixed-point matrix elements

fxM22

Fixed-point matrix elements

lM41

Long translations

lM42

Long translations

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreNotifyTransformChange.

Return Code

rc (BOOL) - returns

Return Code.

On completion, the handling routine must return a BOOLEAN value to indicate success or an error.

• TRUE Successful
• FALSE 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_BASE_ERROR
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_HDC_BUSY
• PMERR_INV_COORD_SPACE
• PMERR_INV_HDC
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_PATTERN_REF_PT_ATTR
• PMERR_INV_PICK_APERTURE_POSN
• PMERR_PATH_LIMIT_EXCEEDED

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

Remarks

This function is called by the graphics engine to provide sufficient information to allow the device to optimize its calling of the GreConvert function or, where possible, to make all point transformations itself. The minimum requirement is for the handling routine to update the current position and pattern origin, and then call back to the GreNotifyTransformChange routine in the graphics engine. Note that the handling routine must:

• Check that the new current position is valid.
• Check that the change will not cause an overflow of the 16-bit coordinates for the device space.
• Fail safe. If an error is detected or the call back to the graphics engine fails, the routine must restore the initial values before returning FALSE.

Sample Code

#define INCL_GRE_DEVMISC2
#include <os2.h>

HDC                     hdc;         /*  Device context handle. */
ULONG                   flFlags;     /*  Flags. */
PNOTIFYTRANSFORMDATA    pXformdata;  /*  Pointer to NOTIFYTRANSFORMDATA structure: */
PVOID                   pInstance;   /*  Pointer to instance data. */
ULONG                   lFunction;   /*  High-order WORD=flags; low-order WORD=NGreNotifyTransformChange. */
BOOL                    rc;          /*  Return Code. */

rc = GreNotifyTransformChange(hdc, flFlags, pXformdata, pInstance, lFunction);