This is the README file for the PEXlib programming utilities provided by Hewlett-Packard. This file has the following major sections: General Information Colormap and Visual Utilities for PEXlib Double-Buffering Utilities for PEXlib Motif Widget for PEXlib (c) Copyright Hewlett-Packard Company, 1993, Fort Collins, Colorado Permission to use, copy, modify, and distribute this documentation, and its associated software, for any purpose and without fee is hereby granted provided that the above copyright notices appear in all copies and that both the copyright notices and this permission notice appear in supporting documentation, and that the name of Hewlett-Packard not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS SOFTWARE, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance or use of this software. General Information ------------------- The PEXlib programming utilities provided in this directory are intended to ease the task of producing portable and interoperable PEXlib applications. The utilities are provided as C source. Please read the copyright notice above regarding this source code. IMPORTANT NOTE: At the time of this release of HP-PEXlib, interoperability conventions for PEX clients and servers in the areas of Visual and color approximation selection are not yet firmly established. Hewlett-Packard and other PEX-IC participants have been working together in the first part of 1993 to establish conventions. As these conventions are defined, and in order to make defect fixes to the utility code, updated versions of the source will be made available via anonymous ftp from the export.lcs.mit.edu system. Due to these evolving conventions and the source changes they will require, applications developers are cautioned that they may need to track upcoming changes, and therefore it may be more practical to create program link sequences that include the utilities as a library, rather than embedding or modifying the utility procedures in other application source files. In the PEXlib community, there is also an intent to develop a utility interface that could become part of the PEXlib standard. How closely it might resemble the interface provided by these HP-furnished utilities is not yet known. You can use the following sequence of commands to fetch the updated source into a directory on your system (say, $PEXUTILS): cd $PEXUTILS ftp export.lcs.mit.edu cd /contrib/PEXlib binary get HP.PEXUt.tar.Z bye The compressed tar(1) archive can be uncompressed and unpacked as follows: uncompress HP.PEXUt.tar.Z tar -xvf HP.PEXUt.tar Individual man pages for each utility function are provided in $PEXUTILS/man3. These man pages can be accessed using the man(1) command by adding the parent directory to your MANPATH shell environment variable. For example, in /bin/sh: MANPATH=$MANPATH:$PEXUTILS export MANPATH man PEXUtDBConfig Alternatively, the pages can be formatted using nroff -man, e.g. nroff -man $PEXUTILS/man3/PEXUtDBConfig.3g You can build the utilities library file, pexut.a, in the $PEXUTILS directory by using the provided Makefile, as follows: cd $PEXUTILS make This will also make the example PEXlib Motif widget object file, PEXSimple.o, and a simple demonstration program. You may want to edit the Makefile to change the compile options, or you can override them from the command line or from enviroment using the -e option. Specifically, if you are on a non-HP system, you may need to modify the MYCFLAGS and DEFINES variables in the Makefile. In the Makefile, the MBX_HEADER_FILE_NOT_INSTALLED symbol is defined because HP does not ship the multibuf.h include file. If the symbol is defined, the utilities will obtain the necessary include file contents from the pexutdbint.h file. However, if your system has the multibuf.h include file installed, you should not define the MBX_HEADER_FILE_NOT_INSTALLED symbol so that the utilities will include the installed include file. See the Makefile for comments on other options. Note that the directory is writeable so that the various .o and .a files can be created here. Be careful that you do not unintentionally remove the source or header files. If you plan to modify the source, it is recommended that you modify a copy of the source in another directory. However, it is recommended that you use the utilities in an unmodified form if possible, because future releases may include defect fixes and/or additional functionality. If you copy the source, you may need to track defect fixes and improvements in your copy later. To use these utilities in your application, you will need include the appropriate header files that are named in the sections below. You can use the -I option of the C compiler to access the header files: cc ... -I$PEXUTILS ... You must include the pexut.a file in your link sequence before the PEXlib library. The pexut.a file also requires the Xext library (or whatever library implements the MBX extension library entrypoints) to be included in your link sequence: ld ... myprogram.o ... $PEXUTILS/pexut.a -lXext ... -lPEX5 ... The example PEXlib Motif widget will also be built by the "make" command shown above, but will not be included in pexut.a. You must explicitly link $PEXUTILS/PEXSimple.o into your application in order to utilize it. Notes about this Release dated June 18, 1993 -------------------------------------------- Here is a list of known problems and deviations in this code, and changes from the first release dated March 2, 1993. 1. This code makes use of the PEXEscapeQueryColorApprox opcode on 5.1 servers that support it, using the 6/10/93 specification. 2. Also in the most recent color interoperability discussions, a set of standard colormap properties has been mentioned for use in aiding clients in using PEX, but the exact set and search order of the properties have not been defined. These utilities search the following properties in the listed order: RGB_BEST_MAP, RGB_DEFAULT_MAP. 3. It has been agreed that it is improper for a standard colormap property to exist without a Colormap resource ID in it. The Hewlett-Packard server in first release possesses properties that have ID None in them. To handle this case, these utilities contain code to create and initialize a Colormap when no ID is found in the standard colormap property. Separately, a well-known contributed client program (xstdcmap) has been modified to generate standard colormap properties describing color space samplings that are supported for PEX color approximation. The source for this client and the procedures it uses is available from export.lcs.mit.edu: ~ftp/contrib/PEXlib/pexstdcmap.tar.Z. 4. It is known that the relative priority of red, green, and blue in the setup of a color "ramp" varies from vendor to vendor. In other words, some vendors require a ramp where red values vary the slowest and blue the fastest (we will term this "red-major"), others where blue varies the fastest, and yet others where green varies the fastest. This utility source has code to support some cases, but it has not been tested. It is recommended that the xstdcmap client mentioned in item three be used to create properties and colormaps. It supports a -ramp option that allows any color channel ordering in PseudoColor Colormaps. 5. It is generally agreed that static Visuals are preferable to dynamic Visuals, because they reduce Colormap flashing. This implementation of PEXUtFindVisual does implements this preference. 6. It should be noted that at the time of this release of HP-PEX, complete interoperability conventions regarding PEX color issues have not yet been established. The released source for the utilities supports conventions that have been discussed and tentatively adopted within the PEX community. Also, be aware that no guarantee can be made that other vendors' implementations of PEX or PEXlib are well-supported by the utilities as released. HP is working together with other PEX vendors to refine the interoperability conventions and the utility code needed to support them. As these conventions evolve, HP may make updated versions of the utility source code available. These utilities conform to the conventions that have been established: - Standard colormap properties can be used to acquire a color "ramp" description and Colormap ID. The properties used are RGB_BEST_MAP and RGB_DEFAULT_MAP. (The application must include PEXUtStandardColormapProperty as a criterion to ensure use of properties in the Visual selection utilities.) - The PEXEscapeQueryColorApprox is used to verify the support for a color approximation "ramp". This code is included in order to interoperate well with systems that have restrictions on color approximation, including HP systems.) - No ordering is implied in either the targets returned by PEXMatchRenderingTargets, nor the entries in a multiple-entry property such as RGB_DEFAULT_MAP. - All else being equal, TrueColor Visuals are preferred over DirectColor in order to avoid color flashing. 7. A defect in the first release involving inadvertent freeing of a Colormap on TrueColor, StaticColor, and StaticGray Visuals has been corrected. 8. Use of MBX has been disallowed on 5.0 servers. Colormap and Visual Utilities for PEXlib ---------------------------------------- Introduction ------------ Programming a PEXlib application to handle the variations in PEX support for visuals and color approximation, and setting up color maps that match the supported color approximation, are all difficult problems that can complicate the programming task. Porting programs from one vendor's implementation of PEXlib to another can be especially difficult, especially if a particular vendor's implementation does not support the assumptions made in the PEXlib program source. However, even on a single vendor's platforms, there may be enough variation in color capabilities to require significant programming effort. This utility interface is intended to provide a stable and usable interface to code that solves these programming tasks. The implementation of the utilities can be modified as necessary to solve problems and expand interoperability; as long as the interface is stable, user source programs will not have to be changed. The interface addresses these common PEXlib color programming tasks: * Given an X connection on which PEXlib has been successfully initialized, find a Visual that supports PEX and meets some set of criteria specified by the application. Some criteria may be "hard", i.e. it is considered a failure if they cannot be met. Other criteria may be "soft". (The requirement that PEXInitialize be called before the utilities allows them to make PEXlib inquiries in the process of accomplishing their tasks.) * Determinine and set up a PEX color approximation method that is supported on a chosen Visual and meets the application's needs. * Create and set up an X Colormap that matches a chosen color approximation method. * Support and allow for colormap sharing among X and PEX clients via standard colormap properties. * Adjust colormap contents for vendor-dependent idiosyncrasies in Visual, color approximation, and Colormap support. * Create a window in a chosen Visual, with a PEX-usable Colormap. Overview of the Colormap and Visual Utilities --------------------------------------------- The $PEXUTILS/pexutcmap.h include file defines constants and structure types for use with the utility functions, and includes extern function prototypes for all the procedures. These utilities are organized into a two-level hierarchy. The higher level only has two utility procedures defined right now. * PEXUtCreateWindowAndColormap This procedure is intended to be a one-call interface that satisfies the needs of many PEXlib applications. It chooses a PEX-capable Visual based on criteria passed in, together with interoperability conventions used to guide Visual selection. It generates a PEX color approximation Lookup Table entry that represents a supported colormap setup, creates a Colormap for use in that Visual, and initializes the Colormap to match the color approximation entry. Finally, it creates a Window that uses the Colormap. * PEXUtCreateColormap Given a color approximation entry and a Visual, this procedure accomplishes the three steps of creating a writeable Colormap, modifying it for vendor dependencies, and converting to read-only. This procedure is useful in many applications that have chosen a Visual themselves. The lower level of the utilities consists of building-block procedures that have a one-to-one correspondence to programming tasks for color interoperability. A programmer who does not wish to use the higher-level utility may be able to use some subset of these building-block routines. Here is the natural sequence in which they are intended to be used: * PEXUtFindVisual takes a specification for hard and soft criteria, selects a Visual according to the criteria and PEX interoperability conventions, and returns an XStandardColormap structure and a color approximation entry that matches it. * PEXUtGetStandardColormapInfo takes a preselected Visual, fetches standard colormap information (if any is available), and returns an XStandardColormap structure and a color approximation entry that matches it. * PEXUtVerifyColorApproximation takes a PEXColorApproxEntry structure, tries to determine if the specified color approximation method and color "ramp" is supported, and returns a success/failure flag. * PEXUtCreateWriteableColormap takes a PEXColorApproxEntry description of a ramp and information about the corresponding Visual, creates a Colormap, initializes the ramp, returns the Colormap ID. * PEXUtModifyColormapForVendorDependencies takes a Colormap ID and other info, and makes any adjustment to its contents due to color idiosyncrasies of the particular hardware and software configuration. * PEXCopyColormapAsReadOnly takes a Colormap that has been set up correctly, but in which all cells are read/write, and makes an equivalent colormap that has read-only cells so that XAllocColor can succeed. * PEXUtCreateWindow takes a Colormap ID, Visual, and window setup information, and creates and maps a Window. External Specification ---------------------- Please see the individual man pages for each function provided in $PEXUTILS/man3. There are nine files: PEXUtCopyColormapAsReadOnly.3g PEXUtCreateColormap.3g PEXUtCreateWindow.3g PEXUtCreateWindowAndColormap.3g PEXUtCreateWriteableColormap.3g PEXUtFindVisual.3g PEXUtGetStandardColormapInfo.3g PEXUtModifyColormapForVendorDependencies.3g PEXUtVerifyColorApproximation.3g Example Usage ------------- Here is an example usage of the main "do-it-all" utility, PEXUtCreateWindowAndColormap. This example uses the recommended criteria set to a cause a relatively unrestricted search for the "best" Visual for PEX rendering (see the man page for more details): #include "pexutcmap.h" ... main( ... ) { Display *display; Window window; PEXExtensionInfo *ext_info; XVisualInfo vis_info; XStandardColormap cmap_info; PEXColorApproxEntry capx_info; int screen; XSizeHints hints; PEXUtVisualCriteria criteria; PEXUtWindowSpecification window_info; unsigned int unmet; Atom prop_atom; int result; XColor returned_background; ... /* Open display. */ ... if (PEXInitialize (display, &ext_info, 0, NULL)) { fprintf (stderr, "ERROR: PEXInitialize failed on %s\n", getenv("DISPLAY")); exit (1); } ... /* Verify subset support, etc. */ ... screen = DefaultScreen(display); hints.x = XPOS; hints.y = YPOS; hints.width = WIDTH; hints.height = HEIGHT; hints.flags = (USSize|USPosition); criteria.hard_criteria_mask = 0; criteria.soft_criteria_mask = PEXUtStandardColormapProperty; criteria.standard_colormap_property = True; window_info.attr_mask = 0; window_info.title = "PEXlib Demo"; window_info.size_hints = hints; window_info.parent = RootWindow (display, screen); window_info.border_width = 0; window_info.background_color_name = "black"; window_info.border_color_name = "white"; result = PEXUtCreateWindowAndColormap (display, screen, &criteria, &window_info, &window, &vis_info, &cmap_info, &capx_info, &unmet, &prop_atom, &returned_background); if ((result != PEXUtSuccess) && (result != PEXUtQualifiedSuccess)) { fprintf (stderr, "ERROR: Failed to create window\n"); exit (1); } ... /* Go on to use the Window for PEX rendering and picking. Don't forget to free the created Colormap when it is no longer needed. */ ... } As an additional example of how the criteria structure might be used, these lines would add a hard requirement for PEX double-buffering capability to the Visual selection criteria shown in the example. criteria.hard_criteria_mask = PEXUtDoubleBufferingCapability; criteria.double_buffering_capability = PEXUtDbufferPEX; criteria.soft_criteria_mask = PEXUtStandardColormapProperty; criteria.standard_colormap_property = True; Double-Buffering Utilities for PEXlib ------------------------------------- Introduction ------------ PEXlib currently has no portable interface for double-buffering. This lack is caused by the failure of the Multi-Buffering extension to X (MBX) to stabilize in time for some vendors to ship MBX implementations with PEX and PEXlib, resulting in the introduction of non-portable methods for double-buffering. The utilities proposed here provide a portable interface to double-buffering of X and PEX rendering. The utilities support the use of the Multi-Buffering extension to X (MBX), the PEX escapes defined by Hewlett-Packard and Evans&Sutherland, and the use of pixmaps. The functions in the utility are: * PEXUtDBConfig - configure the specified window for turning double- buffering on or off * PEXUtDBSwap - display the window's back buffer * PEXUtDBClear - clear the window's back buffer * PEXUtDBFront - reconfigure the window for rendering into the front or back buffer * PEXUtDBResize - reconfigure window buffers in response to a change in the window's size The pexutdb.h include file defines constants for use with the utility functions. Requirements Addressed by the Utilities --------------------------------------- * Provide a simple interface for double-buffering. Target the utilities for usability in the most common cases (yes, this is ill-defined). Users with complex requirements will not be able to use these utilities without modification. Assertion: users with complex requirements are willing to do the extra work. * Hide, as much as possible, the details related to the type of drawable used to perform double-buffering. This includes the idiosyncrasies of clearing the buffers. * Enable, where possible, the usage of X rendering, in addition to PEX, into the double-buffered window. * Support both 5.0 and 5.1 PEX servers. External Specification ---------------------- Please see the individual man pages for each function provided in $PEXUTILS/man3. There are five files: PEXUtDBConfig.3g PEXUtDBSwap.3g PEXUtDBClear.3g PEXUtDBFront.3g PEXUtDBResize.3g Example Usage ------------- #include ... #include "pexutdb.h" static Display *dpy; static Window window; static Drawable rendering_buffer; static PEXRenderer renderer; redraw( ... ) { ... /* ** redraw into the off-screen buffer */ PEXBeginRendering( dpy, rendering_buffer, renderer ); ... /* render attributes and primitives */ PEXEndRendering( dpy, renderer, True ); /* ** display the new image */ rendering_buffer = PEXUtDBSwap( dpy, window, False ); } main( ... ) { ... XColor bg_color; PEXRendererAttributes rattrs; unsigned long mask; /* ** open display, initialize PEX, verify subset support, determine ** best visual to use, get colormap for visual, set up color ** approximation, allocate background color, create window and ** renderer */ ... /* ** turn double buffering on */ if ( PEXUtDBConfig( dpy, window, True, &bg_color, False, &rendering_buffer )) { fprintf( stderr, "No double-buffering available.\n" ); exit( 1 ); } /* ** set renderer's background color and clear-image flag */ rattrs.clear_image = True; rattrs.background_color.type = PEXColorTypeRGB; rattrs.background_color.value.rgb.red = (float)bg_color.red/65535; rattrs.background_color.value.rgb.green = (float)bg_color.green/65535; rattrs.background_color.value.rgb.blue = (float)bg_color.blue/65535; mask = PEXRAClearImage | PEXRABackgroundColor; PEXChangeRenderer( dpy, renderer, mask, &rattrs ); /* ** main loop */ ... /* ** exit program */ PEXUtDBConfig( dpy, window, False, &bg_color, False, &rendering_buffer ); XCloseDisplay( dpy ); exit( 0 ); } Decisions on Issues ------------------- The only way to correctly clear on 5.1 servers when using the PEX escapes is to do PEXBeginRendering with clear_image set to True, so the application should call PEXEndRendering before swapping buffers (PEXUtDBSwap) or clearing the back buffer (PEXUtDBClear). This is actually only necessary if the PEX server is 5.1 and the escapes are being used, but the decision was made to impose this restriction in order to meet the requirement of hiding the details. A renderer is maintained internal to the utilities (only if using the escapes). Note that the utilities recommend against clearing in PEXUtDBSwap if the PEX server is version 5.1. The window's background attribute cannot be inquired, so the application has to specify the background color to PEXUtDBConfig. The decision to have the application specified an XColor was made because this data should be available to the application (should have determined it during window creation and set up). PEXUtDBFront can be called between PEXBeginRendering and PEXEndRendering on HP; but has undefined behavior on other platforms. So, a restriction was imposed that PEXUtDBFront can not be called between PEXBeginRendering and PEXEndRendering. Motif Widget for PEXlib ----------------------- Introduction ------------ This widget is provided to ease the task of integrating PEXlib and Motif. XgPEXSimple has not yet been reviewed or accepted by other PEXlib vendors and is in a preliminary form. However, though internal implementation of the widget may change (and such actions as visual selection may produce different results in future implementations of the widget), the interface to the PEXSimple widget should be upwards-compatible to any future implementations. Additionally, developers can leverage the PEXSimple widget source code to implement PEXlib Motif widgets of their own if needed, using other names for these new widgets. An example program that uses the widget, widgetdemo.c, is also provided. External Specification ---------------------- See the man page for the widget provided in $PEXUTILS/man3: XgPEXSimple.3g