Introduction

The OpenWindows server provides the basic infrastructure for the OVL GPI in the OVL package. Your X11 client can create and configure overlay windows, and use backing store and gravity. These features are exported by the X11 client libraries libX11 (the core Xlib library) and libXext (the Xlib extension library).

In addition to overlay window manipulation, the server provides a means for rendering transparent pixels into overlay windows. An extension routine that specifies an X11 GC paint type attribute is provided. The behavior of the core X11 rendering routines is extended to use this attribute while rendering. For more specific information, see the OpenWindows Server Programmer's Guide which is part of the SDK (Software Developer's Kit).

These capabilities are made available on all device types. However, some devices can optimize the overlay window manipulation and rendering. This is exported to the client through a visual in the screen's list of visuals. The client then creates optimal overlay windows on these visuals. However, the client still

needs to know what is the best visual to use as a matching overlay/underlay visual for the exported visual. The Overlay Window API provides this information, but the server gets this information from the device.

Also, some devices specify their own functions to process the requests in the overlay extension. This interface, called the Overlay GPI, presents a solution to these problems.

---

Note - The OVL package is dependent on the Multiple Plane Group (MPG) package (see Chapter 5, "Multiple Plane Group Interface").

---

Device Setup

The OpenWindows server fully implements overlay windows and renders transparency. Device setup for overlay windows is done with the MPG package. This section provides examples of different device types and how to set them up for optimal performance.

The four basic types of devices are as follows.

1. Transparent Pixel

   The transparent pixel device renders into a drawable plane group with a special value to provide transparency. The special value causes a different drawable plane group to show through.

2. Control Plane Group

   The control plane group device has a special plane group that specifies which drawable plane group is currently visible. This plane group is often referred to as the control plane group. It could be a 1-bit enable plane, a multi-bit WID plane group, or some other type of control plane group.

3. Shared

   The shared device has the overlay windows and the underlay windows coexisting in the same drawable plane group.

4. Custom

   The custom device is different than the above device types--it could be a device with some or all overlay and underlay plane groups are not memory mapped, or a device that can render into image and control plane groups simultaneously.

Overlay window processing and rendering transparency is dependent on how the devices different physical plane groups are presented to MPG. In general, rendering transparency can be thought of as making the window behind the overlay window visible. So, all mpg setup should follow the guideline of attaching all plane groups to an MPG info structure that would allow a window associated with that MPG info to be visible. In the following sections, each device type is presented with the appropriate plane group partitioning that would facilitate overlay window processing and rendering transparency.

Transparent Pixel

A transparent pixel device has the following plane groups:

• a 24-bit drawing plane group (DRAW_A),
• an 8-bit drawing plane group (DRAW_B), and
• another 8-bit drawing plane group that can render transparency by rendering one of several set pixel values (OVERLAY).

Also, a given transparent pixel value may be different depending on what plane group is expected to show through. For DRAW_A, the pixel value is 254 and for DRAW_B, the pixel value is 255. The question now is what should the mpg setup look like.

The transparent pixel device has three MPG infos. The overlay MPG info has just the OVERLAY plane group with a type of MPG_VISIBLE_DRAWABLE and an op of MPG_DRAW. The other two MPG infos have specific MPG_DRAWABLE plane groups and an OVERLAY plane group as well; however, the OVERLAY plane group is of type MPG_VISIBLE and the op is MPG_FILL. For DRAW_A, the fill value is 254 corresponding to the pixel value needed to make DRAW_A visible. For the same reason, the fill value for DRAW_B should be 255. The calls to mpgInsertPlaneGroup are shown below.

MPG infoRec pseudo_color_info, true_color_info, overlay_info; /* Overlay Window Plane group */ mpgInsertPlaneGroup(&overlay_info, OVERLAY, 0, MPG_VISIBLE_DRAWABLE, MPG_DRAW, 0); /* 24 bit plane group */ mpgInsertPlaneGroup(&true_color_info, DRAW_A, 0, MPG_DRAWABLE, MPG_DRAW, 0); mpgInsertPlaneGroup(&true_color_info, OVERLAY, 0, MPG_VISIBLE, MPG_FILL, 254); /* 8 bit plane group */ mpgInsertPlaneGroup(&pseudo_color_info, DRAW_B, 0, MPG_DRAWABLE, MPG_DRAW, 0); mpgInsertPlaneGroup(&pseudo_color_info, OVERLAY, 0, MPG_VISIBLE, MPG_FILL, 255);

A transparent pixel device is one of the more difficult devices to set up. The other device types should be easier.

Control Plane Group

The control plane group device requires no special MPG setup for overlay window processing. Use the standard MPG setup facilities and overlay window processing and rendering transparency work properly.

For example, a device with a 24-bit image plane group (DRAW_A), an 8-bit image plane group (DRAW_B), an 8-bit overlay plane group (OVERLAY), and a control plane group (WID), has the following segmentation:

MPG infoRec pseudo_color_info, true_color_info, overlay_info; /* Overlay Window Plane group */ mpgInsertPlaneGroup(&overlay_info, OVERLAY, 0, MPG_DRAWABLE, MPG_DRAW, 0); mpgInsertPlaneGroup(&overlay_info, WID, 0, MPG_VISIBLE, MPG_FILL_WID, 0); /* 24-bit plane group */ mpgInsertPlaneGroup(&true_color_info, DRAW_A, 0, MPG_DRAWABLE, MPG_DRAW, 0); mpgInsertPlaneGroup(&true_color_info, WID, 0, MPG_VISIBLE, MPG_FILL_WID, 0); /* 8-bit plane group */ mpgInsertPlaneGroup(&pseudo_color_info, DRAW_B, 0, MPG_DRAWABLE, MPG_DRAW, 0); mpgInsertPlaneGroup(&pseudo_color_info, WID, 0, MPG_VISIBLE, MPG_FILL_WID, 0);

Shared

If the shared device is a memory-mapped device with the pScreen->devPrivate pointing to a screen pixmap that can address the device, the OVL package is automatically initialized. This enables overlays to be available on that screen.

Custom

The custom device is the most difficult to use in the OVL package. If the device almost adheres to one of the above device types, it can initialize everything, and then wrap all of the necessary rendering/window manipulation components to complete its processing. For overlay window requests that are not a part of the core protocol, a wrapping mechanism is provided in this GPI. See "ovlWrapDevFuncs" on page 68 for a complete description of this wrapping process.

A device able to port using this method is one that has an extra plane group that requires special processing that MPG does not provide.

Initializing Overlays

The server implements all of the functionality for overlay window processing and rendering transparency. There are three basic steps required to use this feature on a device. First, the device must describe its plane groups appropriately to the MPG package. This was discussed in the previous section. The last two steps are described here. They are combined into a single initialization function, ovlScreenInit.

Once a device has described its plane groups to the MPG package, the OVL package can create and process overlay windows on any visual supported by the device. However, some of the visuals may be more optimal than others for overlay window processing. For example, a device may have a plane group that has special features for rendering transparency or is simply a dedicated overlay plane group to facilitate minimum damage to its underlay plane groups. The device needs a method to hint to the client that this visual is more optimal for overlay windows than other visuals.

In the Overlay Window API there are portable visual queries that allow the client to query which visual pairs are optimal for overlay window processing. If the device has specified that there are no optimal visual pairs, the portable visual queries return regular visuals that match the clients request. See the OpenWindows Server Programmer's Guide for a complete description of the portable visual queries.

The second step for enabling overlay window processing is to describe all of the overlay and underlay combinations that are optimally supported by the device. An overlay/underlay combination is called a pair. The second step is combined with the third step, calling the overlay initialization function ovlScreenInit.

ovlScreenInit is called to initialize overlay window processing and describe the set of optimal overlay/underlay pairs supported by the device. This routine is given a list of pairs and the number of pairs. It must be called during screen initialization and it must be called after the MPG package has been initialized.

Each pair in the list has an overlay and underlay MPG info structure. All visuals pairs that may be derived from the MPG info pairs are then used to signify an optimal pair of overlay/underlay visual pairings. Because of the matching scheme used in the API, devices are encouraged to submit the pair list in most optimal to least optimal order.

Some device may not have any optimal overlay/underlay pairs. This is the case on shared pixel devices described above. If this is the case, ovlScreenInit() should still be called to initialize overlay window processing, but there should be no pairs passed into the function. This will indicate to the OVL package that no pairs are optimal.

Overlay GPI Specification

The following functions and data types define the Overlay GPI specification.

OvlPairs

typedef struct { mpgInfoPtr pOvMpgInfo; /* overlay mpgInfo */ mpgInfoPtr pUnMpgInfo; /* underlay mpgInfo */ } OvlPair;

DescriptionovlScreenInit	Specifies to the system a particular overlay/underlay pair that the device optimally supports.
Bool
Description	This is the screen initialization function for Overlay Window support. The given set of pairs is exported to the client as the optimal pairs. If the device has no optimal pairs, pass in 0 for numPairs and null for pPairs.
Results	Initializes overlay support on the given screen.
Returns	TRUE on success otherwise FALSE
Arguments	pScreen is the screen structure for the device.

numPairs is the number of overlay/underlay pairs.

pPairs is a list describing the pairs.

OvlPair points to the MPG infos of the optimal overlay/underlay pair.

ovlWrapDevFuncs

void ovlWrapDevFuncs (ScreenPtr pScreen, OvlDevFuncs *newfuncs, long funcmask, OvlDevFuncs *oldfuncs)

Description..This function allows devices to wrap the requests associated with the overlay window extension. A full description of all the wrappable functions is given below.

This routine should only be needed by custom devices. The default functions handle all processing for devices that are supported by MPG.

Results	Wraps the overlay request dispatch functions.
Arguments	pScreen is the screen structure for the device.

newfuncs is a pointer to the new OvlDevFuncs to be instantiated.

funcmask is a mask of all the functions specified in newfuncs. funcmask indicates which functions in newfuncs are to be wrapped. If a given mask bit in funcmask is set, the appropriate field in newfuncs must be filled in with a valid function pointer. If a given mask bit in funcmask is not set, the appropriate field in newfuncs will not be accessed

oldfuncs (return) A pointer to the OvlDevFuncs previously instantiated.

The previously instantiated OvlDevFuncs is returned in oldfuncs, if provided. OvlDevFuncs is a structure containing pointers to the wrappable functions.

Valid values for funcmask are:

#define CopyPaintTypeMask (1<<0) #define CopyAreaAndPaintTypeMask (1<<1) #define GetClutInfosMask (1<<2) #define ReadScreenInitMask (1<<3) #define ReadScreenMask (1<<4) #define ReadScreenUninitMask (1<<5)

ovlGetPaintType

XSolarisOvlPaintType ovlGetPaintType (GCPtr pGC)

Description	XSolarisOvlPaintOpaque is returned unless a client has explicitly set the paint type to XSolarisOvlPaintTransparent.
ReturnsovlIsOverlay	Current paint type of the given GC.
Bool
Description	Specifies whether the given window is an overlay window.
Returns	TRUE if the window is an overlay window FALSE otherwise.
Arguments	pWin is the specified window.

XOvlClutInfo

typedef struct { VisualID vid; int pool; int count; } XOvlClutInfo;

DescriptionOvlDevFuncs	A structure containing color lookup table information.
typedef struct {
Description	Defines the function vector of DDX handler functions for devices that want to wrap the overlay requests.

The following definitions are of data types in OvlDevFuncs.

CopyPaintType

RegionPtr (*CopyPaintType) (OvlDevFuncs * devfuncs, DrawablePtr src, DrawablePtr dst, GCPtr pGC, int src_x, int src_y, unsigned int width, unsigned int height, int dest_x, int dest_y, unsigned long action, unsigned long plane)

Description..If a device wraps the CopyPaintType request, their CopyPaintType function should take this form. This function uses the paint type information of the specified rectangle of src to control fill operations in the specified

rectangle of dst. src can be any type of drawable. If src is not an overlay window, plane specifies which bit-plane to use for paint type data. dst can be any type of drawable. The region of dst that corresponds to opaque pixels in src is filled with the current fill attributes of pGC. If dst is an overlay, then the region of dst that corresponds to transparent pixels in src is filled with transparent paint. If dst is not an overlay, then the region of dst that corresponds to transparent pixels in src is filled with the fill attributes of pGC, but with the fg and bg pixel values reversed. The function must restrict its fills according to the specified action which is one of

                  XSolarisOvlCopyOpaque,
                  XSolarisOvlCopyTransparent, or
                  XSolarisOvlCopyAll referring to the filling of just the
                  opaque pixels, just the transparent pixels, or both.

Results	Fills the appropriate regions of dst depending on the paint type data of src and the indicated action. Returns the region for which GraphicsExpose events must be generated.
Arguments	devfuncs is the current set of ovldevfuncs.

src is the source drawable.

dst is the destination drawable.

pGC is the GC to use for the fills. It has the same depth as dst.

src_x and src_y are the X and Y coordinates of the upper-left corner of the source rectangle relative to the origin of the source drawable.

width and height are the dimensions in pixels of both the source and destination rectangles.

dest_x and dest_y are the X and Y coordinates of the upper-left corner of the destination rectangle relative to the origin of the destination drawable.

action specifies which regions of dst should be filled.

plane specifies which plane of src should be used if it is not an overlay window. 1 means opaque, 0 means transparent.

CopyAreaAndPaintType

void (*CopyAreaAndPaintType) (OvlDevFuncs * devfuncs, DrawablePtr colorsrc, DrawablePtr painttypesrc, DrawablePtr colordst, DrawablePtr painttypedst, GCPtr colorgc, GCPtr painttypegc, int colorsrc_x, int colorsrc_y, int painttypesrc_x, int painttypesrc_y, unsigned int width, unsigned int height, int colordst_x, int colordst_y, int painttypedst_x, int painttypedst_y, unsigned long action, unsigned long plane, RegionPtr *colorexposergn, RegionPtr *painttypeexposergn)

Description..If a device wraps the CopyAreaAndPaintType request, their CopyAreaAndPaintType function should take this form. This function copies the specified area from colorsrc to the specified area in colordst and copies the paint type area specified in painttypesrc to the specified paint type area of painttypedst. If painttypesrc is not an overlay window, plane specifies which bit-plane to use for paint type data. colordst may be any drawable of the same depth as colorsrc. painttypedst may be any type of drawable. If colordst is an overlay, then painttypedst will be the same overlay. If painttypedst is not an overlay, then painttypegc is used to fill the opaque and transparent regions of painttypedst. Opaque regions are filled according to the fill attributes of painttypegc while transparent regions are filled similarly but with the foreground and background pixel values reversed. This function must also handle the specified action. An action may be one of XSolarisOvlCopyOpaque, XSolarisOvlCopyTransparent, or XSolarisOvlCopyAll referring to the copying of just the opaque pixels, just the transparent pixels, or both. A pointer to a region indicating which areas must be exposed on the colordst drawable due to incomplete color or paint type

information is returned in the location pointed to by colorexposergn. A pointer to a region indicating which areas must be exposed on the painttypedst drawable due to incomplete paint type information is returned in the location pointed to by painttypeexposergn.

Results	Copies the given area and paint type data from one drawable to another. Returns the regions for which GraphicsExpose events must be generated.
Arguments	devfuncs is the current set of ovldevfuncs.

colorsrc is the color information source drawable. It can be any type of drawable.

painttypesrc is the paint type source drawable. It can be any type of drawable.

colordst is the color information destination drawable. It must be the same depth as colorsrc. It may be any type of drawable.

painttypedst is the paint type destination drawable. It can be any type of drawable. If colordst is an overlay, this parameter will be the same as colordst.

colorgc is the GC to use for copying the color information. It has the same depth as colordst.

painttypegc is the GC to use for rendering the opaque and transparent regions of the paint type information if painttypedst is not an overlay.If colordst and painttypedst are an overlay, this parameter will be the same as colorgc. It has the same depth as painttypedst.

colorsrc_x and colorsrc_y are the X and Y coordinates of the upper-left corner of the source rectangle relative to the origin of the color source drawable.

painttypesrc_x and painttypesrc_y are the X and Y coordinates of the upper-left corner of the source rectangle relative to the origin of the paint type source drawable.

width and height are the dimensions in pixels of all the source and destination rectangles.

colordst_x and colordst_y are the X and Y coordinates of the upper-left corner of the destination rectangle relative to the origin of the color destination drawable.

painttypedst_x and painttypedst_y are the X and Y coordinates of the upper-left corner of the destination rectangle relative to the origin of the paint type destination drawable. If colordst and painttypedst are an overlay, these values will be the same as colordst_x and colordst_y.

action specifies which portions of the paint type should be copied.

plane specifies which painttypesrc plane to use as paint type information if it is not an overlay window. 1 means opaque, 0 means transparent.

colorexposergn is a pointer to a location in which to store a pointer to the region that is to be exposed on the colordst drawable.

painttypeexposergn is a pointer to a location in which to store a pointer to the region that is to be exposed on the painttypedst drawable.

GetClutInfos

int (*GetClutInfos)(OvlDevFuncs * devfuncs, ScreenPtr pScreen, XOvlClutInfo ** pClutInfos)

Description..If a device does not use the Multiple Hardware Colormap (MHC) package to maintain its hardware colormaps, it needs to wrap this function. This information is used by the portable visual queries documented in the OpenWindows Server Programmer's Guide.

This function should allocate a XOvlClutInfo structure for each visual that it exports. Each structure should contain the visual id, a unique pool identifier, and the number of hardware color look up tables that are available to the visual. The pool identifier will only be used to uniquely identify the group. This function should return the number of structures that are being returned. The calling function will free the data returned in pClutInfos.

Results	Gets hardware color lookup table information.
Arguments	devfuncs is the current set of ovldevfuncs.

pScreen points to the ScreenRec structure for which information is needed.

pClutInfos (return) is a pointer to be assigned the array of XOvlClutInfo structures returned.

XOvlClutInfo is a structure containing color lookup table information and is defined on page 70.

ReadScreenInit

int (*ReadScreenInit)(OvlDevFuncs * devfuncs, WindowPtr pWin, int x, int y, unsigned int width, unsigned int height, Bool includeCursor)

Description..If a device wants to wrap the ReadScreen request, it should wrap this function, as well as ReadScreen and ReadScreenUninit. If a device wraps the ReadScreen request, their ReadScreenInit function should take this form. This function is responsible for any initialization that the device needs to prepare for the ReadScreen request. The region of interest is specified by x, y, width, and height. x and y are relative to pWin. This function could, for example, take the cursor down if the cursor were a software cursor, intersected the region of interest, and includeCursor was set to xFalse.

Results	Prepares for getting the color data displayed in a specified area.
Returns	Success if no errors were encountered, !Success otherwise
Arguments	devfuncs is the current set of ovldevfuncs.

pWin points to the WindowRec structure used to compute the area of interest.

x and y specify the X and Y coordinates of the upper-left corner of the area to be read.

width and height are the dimensions of the area to be read.

includeCursor specifies whether or not to include the cursor image in the image.

ReadScreen

int (*ReadScreen)(OvlDevFuncs * devfuncs, WindowPtr pWin, int x, int y, unsigned int width, unsigned int height, Bool includeCursor, pointer pBuffer)

Description..If a device wants to wrap the ReadScreen request, it should wrap this function, as well as ReadScreenInit and ReadScreenUninit. If a device wraps the ReadScreen request, their ReadScreen function should take this form. This function is responsible for getting the color information of the area specified by x, y, width, and height. x and y are relative to pWin. pBuffer is a pointer to an area of memory big enough to store width*height number of long integers. It is important to note that this function copies into pBuffer the actual theoretical colors that can be displayed in the area and not the pixel values. Each long stored in pBuffer is of the form XXBBGGRR, where XX is unused, BB is a 16-bit intensity of blue, GG is a 16-bit intensity of green, and RR is a 16-bit intensity of red. pBuffer is allocated and freed by the calling function.

Called by	More than once for a single ReadScreen request. It will always be called within a ReadScreenInit/ReadScreenUninit block.
Results	Gets the color data displayed in a specified area.
Returns	Success if no errors were encountered, an X protocol error otherwise
Arguments	devfuncs is the current set of ovldevfuncs.

pWin points to the WindowRec structure used to compute the area of interest.

x and y specify the X and Y coordinates of the upper-left corner of the area to be read.

width and height are the dimensions of the area to be read.

includeCursor specifies whether or not to include the cursor image in the image.

pBuffer (return) points to an area of memory that is guaranteed to be large enough to hold the color data.

ReadScreenUninit

void (*ReadScreenUninit)(OvlDevFuncs * devfuncs, WindowPtr pWin, Bool includeCursor)

Description

If a device wants to wrap the ReadScreen request, it should wrap this function, as well as ReadScreenInit and ReadScreen. If a device wraps the ReadScreen request, their ReadScreenUninit function should take this form. This function is responsible for doing any cleanup necessary after ReadScreen processing has completed. This could include putting the cursor back up, if it was previously taken down.

Results

Cleans up after getting the color data displayed in a specified area.

Arguments..devfuncs is the current set of ovldevfuncs.

pWin points to the WindowRec structure used to compute the area of interest.

includeCursor specifies whether or not to include the cursor image in the image.