PDRREF:Design Considerations for All Drivers
This chapter describes various design considerations involved in creating a presentation driver. The following list includes the topics covered in this chapter:
Angles Bounds computations Clipping Closing figures in areas and paths Coordinate values Positions within text functions Return codes Transform matrix values Allocating Memory Error Strategy Presentation Manager Error Codes Exit List Processing Per-Thread Exception Management Using Macro Assembler Instructions Protecting Objects or Device Contexts
Angles
Angles are passed as signed 32-bit numbers. Zero refers to the direction of the positive X-axis; 360 represents 360ø. Positive values represent counterclockwise angles from the positive X-axis.
Bounds computations
All presentation drivers must accumulate bounds for unclipped primitives. Application bounds (COM_BOUND) are accumulated in model space. User bounds (COM_ALT_BOUND) are accumulated in device-coordinate space.
Clipping
The presentation driver must perform clipping for drawing and text functions, except for GreDrawLinesInPath and GrePolyShortLine. Clipping for these two functions is done by the graphics engine. The minimum requirement is to render each primitive clipped to a single rectangle and to clip each rectangle in turn. The rectangles can be enumerated as described in GreGetClipRects.
Note: Rectangles might not always be valid. See Drawing to Display Devices.
Closing figures in areas and paths
The graphics engine generates closure lines for figures within areas and paths unless the presentation driver has opted to hook all the path and area functions. In this case, the presentation driver is responsible for closing any figures. For details, see Area and Path Functions.
Coordinate values
All coordinates are passed to the presentation driver as 32-bit values. Unless stated otherwise, these values represent world coordinates. The graphics engine function, GreConvert, can be called to convert coordinates from one type to another. Coordinates must be converted back to world coordinates before returning to the presentation driver. Notice that screen coordinates are device coordinates to which the DC origin has been added.
Positions within text functions
When positions are used, a text function takes the position from the base line of the text box. Descenders, such as the tail of a lowercase character "y," are expressed as a negative value relative to the base line.
Return codes
The presentation driver must always return a full 32-bit (LONG) value. For example, BOOLEAN TRUE and FALSE are defined as:
#define TRUE (1L); #define FALSE (0L);
Transform matrix values
Transform matrix elements are represented in fixed point notation, that is, as a 16-bit signed integer and a 16-bit fractional part. These precision limits apply during graphics engine matrix multiplication for all initial, intermediate, and final matrix element values.
Allocating Memory
Presentation drivers can allocate and manage memory by using:
- A Dosxxx function such as DosAllocMem.
- The SSxxx functions described in System Functions.
Display drivers, or presentation drivers that share objects such as bit maps and regions, must use the SSxxx functions to allocate memory for these objects. Memory allocated through calls to these functions is "shared memory", controlled by the memory allocator component of the graphics engine. Ownership of the memory can be transferred or (when the owning device context ceases to exist) marked as having no owner.
Error Strategy
Presentation drivers support the error strategy implemented by the Presentation Manager interface. When an error occurs, the driver calls WinSetErrorInfo (see WinSetErrorInfo) to log the appropriate error code and set the return code to show that an error was detected.
The component that implements a function must provide error checking for the environment, objects, and resources associated with it. The presentation driver requires the following error checking:
- Fail-safe on routines that set attributes and transformation values. Any routine that changes attributes or transformation values must be able to restore the initial values if an error occurs during the change.
- Full error checking on symbol sets, fonts, bit maps, and regions.
- With segment drawing, drawing primitives, and primitive attributes in draw mode, unchecked parameters are passed directly to the graphics engine or the presentation driver. When one of these functions is hooked by the presentation driver, the handling routine must perform the necessary error checking and log any errors, or reset any invalid values to their defaults, as appropriate.
- For any function with coordinates as parameters, the presentation driver must check that the values passed are valid. When an invalid coordinate is detected, the handling routine must log an error or use a default coordinate value, as appropriate.
For any defined error, the application sees the same error code regardless of whether the error was logged by the Graphics Programming Interface (GPI), graphics engine, or presentation driver.
Severity
Four ascending severity levels are defined for error messages:
Warning Error Severe error Unrecoverable error
Warning
The function detected a problem, took corrective action, and was able to complete processing successfully.
Error
The function detected a problem for which no sensible corrective action is possible. The function is not executed and the system remains at the same state as when the function was requested.
Severe Error
The function detected a problem from which the system cannot reestablish its state. The function has partially executed and the application must now make some corrective action to restore the system to a known state.
Unrecoverable Error
The function detected an error from which it is impossible for the system to reestablish the state that it held at the time that the function was called. It is also impossible for the application to restore the system to a known state.
Presentation Manager Error Codes
Error codes are defined in the header file. These codes fall into general and specific groups. General error codes that are appropriate to many Grexxx functions include:
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³Error Code ³Must be logged by: ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_COORDINATE_OVERFLOW ³Functions requiring matrix ³ ³ ³computation ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_INSUFFICIENT_MEMORY ³Functions resulting in memory ³ ³ ³allocation ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_INV_HBITMAP ³Functions with hbm as an ³ ³ ³explicit or implicit parameter³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_INV_HRGN ³Functions with hrgn as an ³ ³ ³explicit or implicit parameter³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_INV_COORDINATE ³Functions with coordinate ³ ³ ³parameters ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_INV_IN_AREA ³Functions that are invalid ³ ³ ³inside an open area bracket ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_BASE_ERROR ³Functions that directly or ³ ³ ³indirectly issue DOS routines ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³PMERR_DEV_FUNC_NOT_INSTALLED ³Functions not supported by the³ ³ ³presentation driver ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
Specific error codes listed in the descriptions of each Grexxxfunction are found in Mandatory and Simulated Graphics Engine Function Reference.
To set an error code and the error's severity, the presentation driver must call WinSetErrorInfo (see WinSetErrorInfo). All error codes are listed and explained in the Presentation Manager Programming Reference.
Exit List Processing
An exit list is a list of routines that are given control when the current process ends, either normally or abnormally. The following is an example of exit list processing:
- When the presentation driver's Enable Subfunction 01H - FillLogicalDeviceBlock is called, the driver can call function DosExitList:
#define ROUTINE_ORDER 0x1000 usResult = DosExitList (EXLST_ADD | ROUTINE_ORDER, (PFNEXITLIST)MyExitProc);
This adds the function MyExitProc to the list of functions that are called when this process terminates (either normally or because of some error such as a General Protection fault).
- When MyExitProc is called, the presentation driver can perform any necessary cleanup such as releasing any semaphores. The last call in MyExitProc is another call to DosExitList:
usResult = DosExitList (EXLST_EXIT, (PFNEXITLIST)MyExitProc);
This allows the operating system to transfer control to the next function in the list of exit list processing functions for the process that has terminated. For more information, refer to DosExitList in the OS/2 Control Program Programming Reference and OS/2 Programming Guide.
At Enable time, the presentation driver must place an entry in the exit list for the application or process that opens the DC. This entry is a pointer identifying the routine in the presentation driver that releases all resources owned by the DC.
Note: When writing a presentation driver, consider what would happen if another thread of the process were to terminate.