GPIGuide - Presentation Spaces and Device Contexts

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

GPI Guide and Reference

How to Use the GPI Guide and Reference Graphics Functions Data Types Graphics Orders Graphics Orders Data Types Errors Area and Polygon Primitives Bit Maps Creating and Drawing Retained Graphics Character String Primitives Clipping and Boundary Determination Color and Mix Attributes Correlation Coordinate Spaces and Transformations Editing Retained Graphics and Graphics Segments Fonts Graphics Attributes Line and Arc Primitives Marker Primitives Matrix Multiplication Metafiles Print Job Submission and Manipulation Presentation Spaces and Device Contexts Paths Regions Notices Glossary

A presentation space is a data structure maintained by the operating system in which information relevant to the graphic output is stored. The information is related to both the subsequent drawings (such as colors or line styles) and the presentation space resources (such as color tables or fonts).

The first task in a graphics application is to define a presentation space, because so many of the GPI functions must operate within them. A presentation space is required for each output device currently in use by your application, including each separate window on the display screen. In almost all cases, the presentation space is set up to be device-independent, because the requirements of each possible output device are so different.

Remarks

In some cases, it is possible to disassociate a presentation space from one device and associate it with another, thereby allowing the presentation space to be shared.

To facilitate the device independence of the PM programming interface, all device-specific information is held in a device context. A device context is a data structure that identifies a particular instance of an output device and contains all the device-specific information, such as the logical name of the device and the presentation driver name. Each separate instance of an output device that you intend to use must be described in a device context. For example, if a single application uses more than one window, each of those windows must have its own window device context.

The applicable device context, then, must be associated with the presentation space in order to send graphics data to that output device.

This chapter describes presentation spaces and device contexts. The following topics are related to the information in this chapter:

• Graphics primitives
• Coordinate spaces and transformations
• Graphics segments

About Presentation Spaces

There are three types of presentation spaces:

• Standard micro
• Cached micro
• Normal

Micro Presentation Spaces

You need a micro presentation space if your application creates a separate presentation space for each output device instance and if its output is a simple drawing.

Although run time memory requirements vary according to the graphics function an application uses, a typical micro presentation space graphical application uses 315KB of GPI, engine, and display memory resource (code and data). A micro presentation space cannot be reassociated with a different device.

Standard Micro Presentation Space

Use a standard micro presentation space for drawing on any type of output device, provided the presentation space is not in retain mode or retain and draw mode.

There are two different functions you can use to access a standard micro presentation space. The following table lists both functions and their considerations.

Function Name	Usage	Closing Function
GpiCreatePS	Accepts an anchor handle, a device-context handle, and a presentation space size as parameters. Creates both normal presentation spaces and micro presentation spaces.	GpiDestroyPS destroys a presentation space and releases all resources owned by the presentation space.
WinGetScreenPS	The presentation space represents the entire display screen. Warning: Exercise caution when using this function as the graphic output can overlap individual windows.	WinReleasePS

Cached Micro Presentation Space

The window manager maintains a cache of micro presentation spaces for windows on a display screen. The cache is provided for applications that use a large number of windows, and where each window requires a temporary presentation-space device-context pair for a short sequence of output operations. These presentation spaces belong to the system rather than to your application and are allocated only on a temporary basis.

Cached micro presentation spaces are provided by the window system rather than by the GPI. Their use is synchronized with other window activities. For example, you need not associate a cached micro presentation space with the display screen. The window manager does this for you.

Cached micro presentation spaces offer the best system performance because, unlike normal presentation spaces and standard micro presentation spaces, they are not permanently allocated to an application. However, cached micro presentation spaces can be cumbersome to use because all the attributes must be initialized continually.

Use a cached micro presentation space to send output only to a window on the display device. There are three different functions you can use to access a cached micro presentation space, each with its own considerations. These functions are listed in the following table.

Function Name	Usage	Closing Function
WinBeginPaint	Accepts a NULL presentation space handle for a cached micro presentation space. The presentation space created by this function is already preassociated with the window device context, making this the easiest function to use. Usually this type of creation is in response to a WM_PAINT message.	WinEndPaint automatically releases the presentation space, no matter what type.
WinGetScreenPS	The presentation space represents the entire display screen. Warning: Exercise caution when using this function as the graphic output can overlap individual windows.	WinReleasePS
WinGetPS	The presentation space can represent the entire desktop, or any other window. The presentation space can be used to process any message, but it must be returned to the cache when message processing is complete.	WinReleasePS

In general, use a cached micro presentation space to process a single paint message when no presentation space information needs to be remembered between messages. The presentation space must be both obtained and released during the processing of that message. All application information stored in a cached micro presentation space is lost as soon as it is released to the cache.

You must provide a window handle on input to WinBeginPaint and WinGetPS. The resulting presentation space is defined specifically for that window, and cannot be reassociated.

The cached micro presentation space is always:

• Defined in pels-although you can change the units using GpiSetPS.
• Formatted GPIF_LONG
• Given a suitable size by the system.

When you finish using a cached micro presentation space, you do not have to disassociate it from the window device context because WinReleasePS or WinEndPaint performs the disassociation. This makes the cached micro presentation space available for use in other windows. The presentation space itself cannot be deleted.

Cached micro presentation spaces are used serially. The next time you need a cached presentation space, access a new one using the appropriate function. Each time you get a cached micro presentation space, graphics attributes are reset to their default values.

Normal Presentation Spaces

You must use a normal presentation space if you require your application to use the same presentation space to send output to multiple devices (a display screen and printer, for example), or if it uses the segment and retained-drawing functions to generate complex drawings.

There is only one function you can use to create a normal presentation space:

Function Name	Usage	Closing Function
GpiCreatePS	Accepts an anchor handle, a device-context handle, and a presentation space size as parameters. Creates both normal presentation spaces and micro presentation spaces.	GpiDestroyPS

If a normal presentation space is used, or if metafiling is carried out, more run time memory is used than if a micro presentation space was used. A normal presentation space requires 114KB more than a micro presentation space.

Modal Graphic Systems

The graphic output sent to the presentation space is created by graphic primitives, such as straight or curved lines. How those primitives appear depends in part on the mode of the presentation space.

In modal systems, certain information that modifies a graphic primitive is established before you use the instruction to draw the primitive. The following figure is an example of a red, solid line being drawn from (4,3) to (9,7). With PM's modal interface, the only value you need to supply to GpiLine is the end point (9,7).

The line is drawn automatically with the current color, red, in the current line type, solid, and starting from the current position, (4,3). There are separate functions for specifying the current color, line type, and position.

In nonmodal graphics systems, you supply information relevant to an instruction when you use that instruction. For example, you could use a line-drawing instruction in which you would specify that the line is to be green, dotted, and drawn from point a to point b. Those values or attributes are bound to a particular drawing instruction, and affect no other. If you are going to continue the line from point b to point c, you must again specify "green", "dotted", "point b", and finally, "point c".

For the PM programming interface, the default values for the graphics primitives (or current values if the defaults have been modified) are stored in the presentation space along with the current position. While at first it might seem like many functions are necessary to perform one step, such as drawing a line, a modal graphics system actually saves resources. After you perform the first line draw, chances are that if you draw a second or third line, the line attributes are not likely to change; that is, the mode of the presentation space remains the same. Thus, the constant repetition of attributes in a nonmodal graphics system actually uses more resources if the desired output requires more than one or two graphics functions.

It is possible to define graphics, and store their definitions, without sending them to a screen or a printer. In these situations, the concept of attribute currentness becomes relevant. The color of a line on a screen, for example, is the color that was current when you defined the line. This is not always the color that is current when the line is drawn.

Current Position

The current position is the world-coordinate space position at which the next drawing request begins. It is part of the data stored in the presentation space. When you create or obtain a presentation space, the current position is set to the origin (0,0). The current position also is reset to (0,0) whenever a presentation space is associated with a different device context.

Most drawing requests update the current position. If you draw a line from the origin to (3,5), for example, the current position is updated to (3,5). The current position also can be updated explicitly by GpiSetCurrentPosition or GpiMove. If you do not want the first drawing in a presentation space to start at (0,0), call GpiSetCurrentPosition first.

Primitive Attributes

The graphics primitives and the functions that draw them are discussed in Line and Arc Primitives through Fonts. The primitive's function allows the attributes of the primitive to be set for all subsequent use of that primitive. The attributes are stored in data structures called bundles.

There are functions that allow you to set the attributes of the primitives before the drawing of any primitive is performed. GpiSetAttrs allows you to not only specify the primitive for which the attributes are going to be set, but also, the settings for the specific attributes. GpiQueryAttrs returns the current values of specified attributes for specified primitives.

Two other functions, GpiSetAttrMode and GpiQueryAttrMode, enable you to define or query the attribute mode settings, AM_PRESERVE and AM_NOPRESERVE. The AM_PRESERVE setting preserves the value of an attribute any time that attribute is changed. The previous value can be recovered easily if, for example, you need six dotted lines, one solid line, then six more dotted lines. The AM_NOPRESERVE setting discards the previous value of an attribute once the value is changed. The values of the attributes are presentation space resources.

Using Presentation Spaces

You can use presentation-space functions to:

• Create a normal, micro, or cached micro presentation space
• Delete, save, or restore a presentation space
• Define or determine the presentation space attributes

Obtaining and Creating a Presentation Space

Normal presentation spaces and micro presentation spaces are created using GpiCreatePS. Cached micro presentation spaces are created using WinBeginPaint or WinGetPS.

Deleting a Presentation Space

A presentation space consumes a considerable amount of memory, so you should delete it when your application no longer requires it. Use GpiDestroyPS to delete either a normal or micro presentation space.

When you finish using a cached micro presentation space that you accessed with WinGetPS, release it with WinReleasePS. You need not delete a presentation space that you accessed with WinBeginPaint. PM does this for you when you call WinEndPaint.

Saving and Restoring a Presentation Space

You can save certain attributes and resources of a presentation space, modify its fields, draw in the modified presentation space, then restore it with GpiSavePS and GpiRestorePS. When you call GpiSavePS, the graphics engine copies the following items from the current presentation space onto a special stack:

• Primitive attributes
• Transformation matrixes
• Viewing limit
• Clip path
• Clip region
• Current position
• Loaded logical color table
• Loaded logical font

You can push the contents of a presentation space on the stack as many times as is necessary. GpiRestorePS pops the contents of a presentation space off the stack.

Presentation Spaces Review

The following table summarizes the features and restrictions of each type of presentation space.

Presentation Space Features and Restrictions

Feature/Restriction	Normal	Standard Micro	Cached Micro
Device types supported	Any device	Any device	Video-display window only
Number of supported devices	Multiple	One	One
Association	Associate and disassociate as required.	Associate at creation; cannot disassociate.	N/A.
Retained graphics	Yes	No	No
Available GPI functions	All functions	All except segment functions	All except segment functions
Memory considerations	Highest memory usage	Medium memory usage	Quickest allocation

About Device Contexts

Device contexts link presentation spaces to devices by converting device-independent presentation space information into device-dependent information. This conversion occurs in the presentation driver, a low-level program that is transparent to the application. A presentation driver is device-driver code that converts the application commands into output commands specific for each output device.

After creating a device context, it must be associated with a presentation space before the drawing (or primitives) can be printed or displayed. When a presentation space and a device context are associated with each other, any output you direct to the presentation space is directed automatically at the device context and displayed on the physical device. For example, before you can draw a picture in a display window, the picture's graphics presentation space must be associated with the window's device context.

Device contexts also give applications access to important device information such as screen dimensions or printer capabilities.

As with presentation spaces, there are three types of device contexts:

• Cached
• Window
• Normal

Cached Device Contexts

A cached device context is one that already is associated with a cached presentation space when that space is obtained from the cache.

Window Device Contexts

Window device contexts are a special type, in that they are the only device contexts obtained with WinOpenWindowDC. As their name implies, the output device they represent is a display window. WinOpenWindowDC accepts a window handle as input and returns the window device context handle. The window device context handle can then be associated with a standard micro presentation space or a normal presentation space.

The window device context is closed automatically when its associated window is deleted.

Normal Device Contexts

A normal device context (also called a standard or noncached device context) links a presentation space with any nonwindow output device. Use DevOpenDC to obtain a device context handle to one of the six normal device contexts listed in the following table. Each of the six normal device contexts must be closed by DevCloseDC before your application is closed.

DC Type	Purpose	Usage
Queued	Links a presentation space with a printer or plotter shared by multiple applications sending spooled print jobs to the print queue. Queued device contexts store print jobs by using a program called print spooler, which keeps track of the order in which the jobs arrive at the printer and in which they are printed.	Applications use queued device contexts to offload printing control from the application.
Direct	Links a presentation space with a printer or plotter, directly bypassing the spooler and print queue. A direct device context is used by the spooler to process jobs as they are removed from the print queue.	Applications normally do not use direct device contexts, unless they are avoiding the queue (for security reasons) or going directly to a dedicated machine.
Information	Links a presentation space with a printer or plotter, directly enabling device information to be queried, but producing no output on the device.	An application can use an information device context with lower memory overhead, rather than use a direct device context, which could provide the same information.
Memory	Links a presentation space with a bit map.	Applications use memory device contexts for drawing to the bit map and using it as a source or target of BitBlt operations.
Metafile	A special device context that enables a picture output to its associated presentation space to be recorded in a metafile for interchange for future use.	Only applications that use metafiles use metafile device contexts.
Metafile_NoQuery	Functionally identical to metafile; however, querying of presentation space attributes is not allowed.	If attributes of the presentation space are not to be queried, this device context offers improved performance over metafile.

Using Device Contexts

In addition to associating or disassociating presentation spaces with device contexts, you can use device context functions to:

• Obtain or create a device context
• Associate a device context with a presentation space
• Close a device context
• Retrieve information about a device's capabilities

Creating a Device Context

You can create a normal device context by calling DevOpenDC. This function requires that you specify one of the six normal types. It also requires that you pass certain device-initialization data, including a logical address, the device-driver name, device-driver data, a description of the device type, and information about the queue (if the device is a queued device). The device-initialization data is passed in a DEVOPENSTRUC structure.

The following figure is an example of this structure.

typedef struct _DEVOPENSTRUC {   /* dop                          */
    PSZ      pszLogAddress;      /* Logical-device address       */
    PSZ      pszDriverName;      /* Device-driver name           */
    PDRIVDATA  pdriv;            /* Pointer to extra driver data */
    PSZ      pszDataType;        /* Type of queued data          */
    PSZ      pszComment;         /* Optional spooler info        */
    PSZ      pszQueueProcName;   /* Queue-processor name         */
    PSZ      pszQueueProcParams; /* Queue-processor arguments    */
    PSZ      pszSpoolerParams;   /* Spooler arguments            */
    PSZ      pszNetworkParams;   /* Network arguments            */
} DEVOPENSTRUC;

The last four fields in this structure apply only to queued devices.

The following figure shows how to create a nondisplay device context for a printer.

HDC hdcPrinter;                     /* Handle of printer device context    */
HAB hab;                            /* Anchor-block handle                 */
DEVOPENSTRUC dop;                   /* Device information                  */

dop.pszLogAddress = "lpt1";         /* Logical-device address              */
dop.pszDriverName = "EPSON";        /* Device-driver name                  */
dop.pdriv = (PDRIVDATA) NULL;       /* Pointer to driver data              */
dop.pszDataType = "PM_Q_STD";       /* Standard queued data                */

hdcPrinter = DevOpenDC(hab,
                       OD_DIRECT,   /* Direct device type                  */
                       "*",         /* No data in OS2.INI                  */
                       4,           /* Use first 4 fields in dop structure */
                       (PDEVOPENDATA) &dop,
                       (HDC) NULL);

The following figure is an example of how to create a standard device context for a metafile.

HDC hdcMeta;                                 /* Handles of metafile       */
                                             /*    and window DCs         */
HAB hab;                                     /* Anchor-block handle       */
DEVOPENSTRUC dop;                            /* Device information        */

dop.pszLogAddress = NULL;                    /* Logical-device address    */
dop.pszDriverName = "DISPLAY";               /* Device-driver name        */

hdcMeta = DevOpenDC(hab,
                    OD_METAFILE,             /* Metafile DC               */
                    "*",                     /* No data in OS2.INI        */
                    2,                       /* Use first 2 fields in dop */
                    (PDEVOPENDATA) &dop,     /* Structure for system info */
                    NULL);                   /* Compatible with screen    */

Associating Presentation Spaces with Device Contexts

Drawing graphic objects requires a presentation space and a device context to direct output to a specific instance of an output device, such as a display window or a printer. This association enables the device context to identify the output device for that presentation space. Further, the device context identifies the particular instance of the output device, such as a printer or display window.

A presentation space can be associated with only one device context at a time. The reverse is also true: a device context can be associated with only one presentation space at a time.

The following figure shows how a presentation space is associated with a window device context. It is then disassociated from the window device context and associated with a printer device context. It cannot be associated with both device contexts simultaneously.

WM_Create:
     hdcScreen = WinOpenWindowsDC (hwnd);
     phs = GpiCreatePS (...GPIA_Assoc);
      .
      .
      .

WM_COMMAND:
  Case IDM_File PRINT:                       /* Device selection        */
     hdcPrinter = DevOpenDC (...);
     GpiAssociate (hps, NULL);               /* Disconnect from screen  */
     GpiAssociate (hps, hdcPrinter);         /* Connect to printer      */
      .
      .                                      /* Output                  */
      .
     GpiAssociate (hps, NULL);               /* Disconnect from print   */
     GpiAssociate (hps, hdcScreen);          /* Reconnect to screen     */
      .
      .
      .

WM_PAINT:
     WinBeginPaint (hwnd, hps, NULL);
      .
      .                                      /* Output                  */
      .

The following figure shows how to open a window device context and associate it with a normal presentation space.

HDC hdcWin;            /* Window device-context handle     */
HPS hpsWin;            /* Normal-presentation-space handle */
HWND hwndClient;       /* Client-window handle             */
HAB hab;               /* Anchor-block handle              */
SIZEL sizlPage;        /* Presentation page                */

hdcWin = WinOpenWindowDC(hwndClient);
hpsWin = GpiCreatePS(hab, hdcWin, &sizlPage,
                     PU_LOENGLISH | GPIA_ASSOC);

Remarks

This type of code is used when the device context is defined before the presentation space.

WinOpenWindowDC can be called only once for a particular window and returns an error if called a second time. WinQueryWindowDC can be used to obtain a window device context previously allocated using WinOpenWindowDC. The following figure shows how to create a presentation space with page units of 0.01 inch (PU_LOENGLISH) and associate it with a printer device context. As input to GpiCreatePS, you supply the height and width of the presentation page.

HAB hab;          /* Anchor-block handle         */
HPS hpsPrinter;   /* Presentation-space handle   */
HDC hdcPrinter;   /* Device-context handle       */
SIZEL sizlPage;   /* Page structure              */
.
.
.
hpsPrinter = GpiCreatePS(hab, hdcPrinter, &sizlPage,
                         PU_LOENGLISH | GPIA_ASSOC);

Closing a Device Context

To close a device context that your application opened with DevOpenDC, call DevCloseDC. However, you should not try to close a device context that you opened with WinOpenWindowDC. The operating system does this automatically when the associated window is deleted.

Determining Device Capabilities

Once you have created a device context for a particular output device, you can determine the capabilities of that device by calling DevQueryCaps. This function retrieves the following information:

• Device technology (whether the device is a raster or vector device)
• Maximized window dimensions (if the device is a video display)
• Page dimensions (if the device is a printer or plotter)
• Character-box dimensions
• Marker-box dimensions
• Pel resolution
• Color capabilities
• Mix-mode capabilities

You can use this information, for example, to select fonts, set up the presentation page, or create a new logical color table.