Introduction

This chapter provides you with recommendations and specific details of the HP PEX implementation that affect how you will write your programs.

As a PEXlib programmer, if it is among your objectives to write programs that are portable and interoperable on a variety of workstations and graphics devices — you will want to do so without sacrificing performance. To succeed at this, you may want, for example, to add PEXlib inquiries to your program that will enable it to determine which protocol version is supported by the server, attribute values that are supported, the visuals that you may use with PEX, as well as other details of implementation such as the number of supported line widths.

The information and examples that you need to accomplish this is described in this and following chapters in this book as well as a companion publication, Portable Programming with CGE PEX 5.1. (More information and examples of specific PEXlib inquiries are provided for you in Chapter 24, "Determining a Server's Features" in PEXlib Programming Manual.)

The Portable Programming with CGE PEX 5.1 was written specifically to assist you in creating highly portable 3D graphics applications on platforms supporting the Common Graphics Environment, including HP. It contains tools and utilities that you can use to develop portable and interoperable applications more easily.

Determining A Server's Features

You can learn quite a lot about your particular system, server, and the supported X and PEX extensions with the xdpyinfo command. On Hewlett-Packard workstations this command is in the directory^[12] 〈contrib〉/bin/X11. See sample output in Appendix A “Sample Output from xdpyinfo and pexdpyinfo ”.

An HP PEX example program, pexdpyinfo, displays detailed information on the PEX extensions on your work station; information such as the enumerated types, implementation-dependent constants, lookup table entries, and supported PEX visuals for a particular display. See sample output in “pexdpyinfo”.

In order to use this utility, you'll first need to use the Makefile to build the executable. See the README file in 〈hp-examples〉 for instructions. See the file pexdpyinfo.spec for usage details. The file pexdpyinfo.design contains design information and pexdpyinfo.c, the source code, for developers interested in extending the capabilities of the utility.

PEX Extension Information

As described in the PEXlib Programming Manual, Chapter 24, the extension information returned from PEXInitialize and PEXGetExtensionInfo verifies that a PEX extension exists within the PEX server in order to set PEXlib variables and establish communication with the server.

HP PEX supports the Immediate Mode subset. HP PEX also supports the Structure Mode rendering subset of PEX functionality with all but the Search Context requests. This means that calls to SearchContext entrypoints (except to issue protocol to another server) will report a BadImplementation error. Calls to Workstation or PickMeasure entrypoints will report a BadRequest error. The Workstation and PickMeasure entry points do not emit protocol. Search context request protocol is generated and can be sent to servers that do support those requests. Errors are detected and reported by the client.

Your program can determine which subsets are supported by a PEX server in an interoperable way with PEXGetExtensionInfo:

PEXExtensionInfo *PEXGetExtensionInfo(Display *display)

This also tells what version of protocol is supported by the PEX server as well as other information that can be used for error handling.

PEXlib functions that have a display parameter are not allowed to be called before calling PEXInitialize. If the application calls a PEXlib function that is not allowed to be called before PEXInitialize is called, HP PEXlib will ignore the call.

The following table shows the HP-specific error codes that can be returned from the PEXInitialize function. We recommend that you print the error string which is returned in your program for more information needed to determine the cause of the error.

Table 6-1 PEXInitialize Error Codes

Return Value	Standard PEX Error Strings
4	`PEXlib client-side memory allocation failed during initialization`
3	`The PEX extension does not support a compatible floating-point format`
2	`The PEX extension does not support a compatible protocol version`
1	`The PEX extension does not exist or could not be initialized`
0	`successful initialization`

Table 6-2 PEXInitialize Error Codes

Return Value	HP-Specific Error Strings
-1	(The error string returned here varies according to the error condition. Print the error string which is returned in your program to learn about the actual error condition.)
-2	`The maximum number of displays have already been initialized`
-3	`Something is wrong with the X display name`
-4	(The -4 error string is not used)
-5	`Attempt to initialize a DHA connection failed`
-6	`Attempt to initialize a PEX connection failed`
-7	`Attempt to initialize a X connection failed`
-8	`Something is wrong with the X11R6 libraries` (application may be linked with pre-X11R6 libraries)

The PEX extension information pointer returned from PEXInitialize will be valid only if PEXInitialize succeeds or the error PEXBadProtocolVersion is generated. Any other error that occurs in PEXInitialize will cause the PEX extension information pointer to be NULL.

Enumerated Types

Enumerated types define values used to define attributes such as marker types (dot, asterisk, circle, or "×"). Other examples include line type, color type, and interior style. Because a PEX server may not support all enumerated types, PEX provides the PEXGetEnumTypeInfo information inquiry for determining which enumerated types are supported by the particular server.

The table below lists the enumerated types supported by HP PEX on supported graphics devices. For writing interoperable programs it is best to inquire which values are supported by using the PEXGetEnumTypeInfo inquiry rather than relying on documentation from vendors of vendor-specific support.

PEXGetEnumTypeInfo(
    Display             *display,
    Drawable            drawable,
    unsigned long       count,
    int                 *enum_types,
    unsigned long       item_mask,
    unsigned long       **info_count_return,
    PEXEnumTypeDesc       **enum_info_return)

Table 6-3 Enumerated Type Inquiry Parameters

Value	Description
`display`	A valid display pointer.
`drawable`	An example drawable indicating the screen and depth of the window for which the values will be used.
`count`	The number of enumerated types.
`enum_types`	A list of enumerated types for which information is to be returned.
`item_mask`	A mask indicating the data to be returned for each type.
`info_count_return`	Returns an array of counts. For each enumerated type, there is an entry specifying the number of descriptors in the return value array.
`enum_info_return`	Returns an array of enumerated type descriptors containing the enumerated type information.

For example, you may use the enumerated type descriptors to inquire which double-buffering escapes are supported. This information is covered earlier in this chapter in “Inquiring Supported Escapes ”.

Enumerated Types List

Information about HP-supported enumerated types is shown here. There are standard PEXlib inquiries which return HP-supported enumerated types.

CGE PEX 1.0 also defines additional enumerated types to list extension features for which PEXlib 5.1 does not define a mechanism of inquiry. For example, PEXExtETOC can be inquired to list extension OCs (Output Commands) beyond the PEXlib standard. See the PEXExt.h and PEXHPlib.h files for lists of extension enumerated types.

Table 6-4 Enumerated Types

Enumerated Type	HP PEX 5.1v4
`MarkerType`	All PEX types, plus the following: `PEXHPMarkerTriangle` `PEXHPMarkerSquare` `PEXHPMarkerDiamond` `PEXHPMarkerCrossSquare`
`PEXATextStyle`	`PEXATextNotConnected` `PEXATextConnected`
`InteriorStyle`	All styles but `Pattern`
`HatchStyle`	45 degrees, 135 degrees, plus CGE and HP types
`LineType`	All PEX, CGE, and HP types
`SurfaceEdgeType`	All PEX types
`PickDeviceType`	`DCHitbox`, `NPCHitVolume`
`PolylineInterpMethod`	`None`, `Color` (only with PowerShade)
`CurveApproxMethod`	Implementation-dependent (`AdaptiveDC`) `WCSRelative` `NPCRelative` `DCRelative`
`ReflectionModel`	All PEX types
`SurfaceInterpMethod`	`None`, `Color` (only with PowerShade)
`SurfaceApproxMethod`	Implementation-dependent (`AdaptiveDC`) `WCSRelative` `NPCRelative` `DCRelative`
`TrimCurveApproxMethod`	Implementation-dependent (adapt to surface criteria)
`ModelClipOperator`	All PEX types
`LightType`	All PEX types
`ColorType`	`Index`, `RGBFloat`, `HPRGBA`
`FloatFormat`	`IEEE_754_32`
`HLHSRMode`	`Off`,`PEXHPHLHSRZBuffer` (only with PowerShade); `PEXHPHLHSRZBufferID` (only with PowerShade); `PEXHPHLHSRZBufferReadOnly` (only with PowerShade); `PEXHPHLHSRZBufferIDReadOnly` (only with PowerShade)
`PromptEchoType`	Not Applicable
`DisplayUpdateMethod`	Not Applicable
`ColorApproxType`	`PEXColorSpace` `PEXColorRange` `PEXHPColorApproxTypeIndexed`
`ColorApproxModel`	RGB
`GDP`	No supported GDPs
`GDP3`	No supported GDP3s
`GSE`	`HP_GSE_SET_ANTIALIAS_MODE`
`RenderingColorModel`	RGB
`ParametricSurface- Characteristics`	None (default); Implementation-dependent (interior edging)
`PickOneMethod`	`PEXPickLast`
`PickAllMethod`	`PEXPickAllAll`
`Escape`	`ES_ESCAPE_DBLBUFFER` `ES_ESCAPE_ET_DBLBUFFER` `ES_ESCAPE_ET_SWAPBUFFER` `ES_ESCAPE_ET_SWAPBUFFERCONTENT` `ES_ESCAPE_SWAPBUFFER` `ES_ESCAPE_SWAPBUFFERCONTENT` `HP_ESCAPE_DFRONT` `HP_ESCAPE_ET_DFRONT` `HP_ESCAPE_ET_SET_GAMMA_CORRECTION` `HP_ESCAPE_SET_GAMMA_CORRECTION` `PEXEscapeQueryColorApprox` `PEXEscapeSetEchoColor` `PEXExtEscapeChangePipelineContext` `PEXExtEscapeChangeRenderer` `PEXExtEscapeCreateTM` `PEXExtEscapeCreateTMDescription` `PEXExtEscapeCreateTMFromResources` `PEXExtEscapeFetchElements` `PEXExtEscapeFreeTM` `PEXExtEscapeFreeTMDescription` `PEXExtEscapeGetPipelineContext` `PEXExtEscapeGetRendererAttributes` `PEXExtEscapeGetTableEntries` `PEXExtEscapeGetTableEntry` `PEXExtEscapeOpcodeChangePipelineContext` `PEXExtEscapeOpcodeChangeRenderer` `PEXExtEscapeOpcodeCreateTM` `PEXExtEscapeOpcodeCreateTMDescription` `PEXExtEscapeOpcodeCreateTMFromResources` `PEXExtEscapeOpcodeFetchElements` `PEXExtEscapeOpcodeFreeTM` `PEXExtEscapeOpcodeFreeTMDescription` `PEXExtEscapeOpcodeGetPipelineContext` `PEXExtEscapeOpcodeGetRendererAttributes` `PEXExtEscapeOpcodeGetTableEntries` `PEXExtEscapeOpcodeGetTableEntry` `PEXExtEscapeOpcodeQueryColorApprox`
`Escape` (continued)	`PEXExtEscapeOpcodeSetTableEntries` `PEXExtEscapeQueryColorApprox` `PEXExtEscapeSetTableEntries` `PEXHPEscapeOpcodeStereoMode` `PEXHPEscapeChangePipelineContext` `PEXHPEscapeChangeRenderer` `PEXHPEscapeDfront` `PEXHPEscapeGetPipelineContext` `PEXHPEscapeGetRendererAttributes` `PEXHPEscapeGetZBuffer` `PEXHPEscapeOpcodeChangePipelineContext` `PEXHPEscapeOpcodeChangeRenderer` `PEXHPEscapeOpcodeDfront` `PEXHPEscapeOpcodeGetPipelineContext` `PEXHPEscapeOpcodeGetRendererAttributes` `PEXHPEscapeOpcodeGetZBuffer` `PEXHPEscapeOpcodePutZBuffer` `PEXHPEscapeOpcodeSetGammaCorrection` `PEXHPEscapeOpcodeSetZBuffer` `PEXHPEscapePutZBuffer` `PEXHPEscapeSetGammaCorrection` `PEXHPEscapeSetZBuffer` `PEXHPEscapeEVEInformation`

Implementation-Dependent Constants

There are other PEX values in addition to enumerated types that vary among implementations, as allowed by the PEX standard. Implementation-dependent constants define things like the maximum value of a name or the number of line widths. The table "Implementation-Dependent Constants" below lists the constants that are supported in HP PEX.

As with other implementation-dependent features, it is best to inquire about supported implementation-dependent constants using the standard PEXlib inquiry, PEXGetImpDepConstants.

PEXGetImpDepConstants(
    Display             *display,
    Drawable            drawable,
    unsigned long       count,
    unsigned short      *names,
    PEXImpDepConstant   **constants_return)

Table 6-5 Implementation Dependent Constants Inquiry Parameters

Value	Description
`display`	A pointer to a display structure returned by a successful `XOpenDisplay` call.
`drawable`	The resource identifier of a drawable.
`count`	The number of implementation-dependent constants.
`names`	An array of names of implementation-dependent constants to be returned.
`constants_return`	Returns an array of implementation-dependent constants.

This table lists some of the implementation-dependent constants that are supported in HP PEX. For an exhaustive list, see the include files PEX.h, PEXExt.h, PEXlib.h, and PEXHPlib.h.

Table 6-6 Implementation-Dependent Constants

Implementation-Dependent Constant	HP PEX 5.1v4
`NumSupportedLineWidths`	No limit
`MinLineWidth`	1
`MaxLineWidth`	16383
`NominalLineWidth`	1
`NumSupportedEdgeWidth`	1
`MinEdgeWidth`	1
`MaxEdgeWidth`	1
`NominalEdgeWidth`	1
`NumSupportedMarkerSizes`	No limit
`MinMarkerSize`	1
`MaxMarkerSize`	No limit
`NominalMarkerSize`	3
CIELUV values (approximate, true values are monitor-dependent)	`red.u` = 0.450 `red.v` = 0.522 `red.l` = 1.0 `green.u` = 0.120 `green.v` = 0.561 `green.l` = 1.0 `blue.u` = 0.175 `blue.v` = 0.157 `blue.l` = 1.0 `white.u` = 0.188 `white.v` = 0.466 `white.l` = 1.0
`MaxNameSetNames`	`MAXINT`
`MaxModelClipPlanes`	With PowerShade, 6; without, `False`
`TransparencySupported`	With PowerShade, `True` without, `False`
`DitheringSupported`	`True` or `False`
`MaxNonAmbientLights`	With PowerShade, 15;
`MaxNurbOrder`	6
`MaxTrimCurveOrder`	6
`BestColorApproxValues`	0 (`PEXColorApproxAnyValues`)
`DoubleBufferingSupported`	`True`
`PEXHPIDDeformationSupported`	`True` or `False`
`PEXHPIDCappingPlanesSupported`	`True` or `False`
`PEXHPIDInterferenceSupported`	`True` or `False`
`PEXHPIDPolygonOffsetSupported`	`True` or `False`

PEX Extensions

Generalized Structure Elements (GSEs)

HP PEX supports one GSE, used to enable or disable line and edge antialiasing (see “Line Types ”). This is not a standard feature (there are no standard GSEs specified by PEX), but may have value for your application. The constants and data structure for the PEXlib interface are defined in the header file PEXHPlib.h.

Escapes

Extensions to PEX are provided by HP for capabilities beyond the standard. These are implemented, according to provisions in the PEX standard, in a way that makes for a common interface to the extensions which does not negatively affect the portability of applications.

The Evans & Sutherland escape requests are described in the section “Animation ”, later in this chapter. The section also shows an example of the syntax and return information. Other escapes are documented in other relevant sections of this manuals.

PEX Subset Lists

Immediate Mode Subset

HP PEX supports the Immediate Mode subset.

Structure Subset

HP PEX also supports the Structure Mode rendering subset of PEX functionality with all but the Search Context requests.

Search Context Requests

These functions emit protocol but the HP PEX server does not process them and will generate an error upon receiving them.

Table 6-7 Title not available (Search Context Requests )

PEXChangeSearchContext PEXCopySearchContext PEXCreateSearchContext

PEXFreeSearchContext PEXGetSearchContext PEXSearchNetwork

PHIGS Workstation Resources

HP PEX does not support the PHIGS Workstation subset because it is expected to be removed from PEX at a future version. These functions will not emit protocol and will generate a BadRequest.

This table lists the PEX functions in subsets that HP PEX does not support as allowed by the standard.

Table 6-8 Unsupported Subset Entrypoints

PEXCreateWorkstation PEXExecuteDeferredActions PEXFreeWorkstation PEXFreeWorkstationInfo PEXGetWorkstationDynamics PEXGetWorkstationInfo PEXGetWorkstationPostings PEXGetWorkstationViewRep PEXMapDCToWC PEXMapWDToDC PEXPostStructure PEXRedrawAllStructures PEXRedrawClipRegion PEXSetWorkstationBufferMode PEXSetWorkstationDisplayUpdateMode

PEXSetWorkstationHLHSRMode PEXSetWorkstationViewport PEXSetWorkstationViewPriority PEXSetWorkstationViewRep PEXSetWorkstationWindow PEXUnpostAllStructures PEXUnpostStructure PEXUpdateWorkstation PEXSetPWAttributeMask PEXGetPickDevice PEXChangePickDevice PEXCreatePickMeasure PEXFreePickMeasure PEXGetPickMeasure PEXUpdatePickMeasure

HP Implementation Details for Writing Programs

Supported PEX Subsets

The O'Reilly PEXlib Programming Manual, Chapter 3, "Getting Started," is a good starting point for learning to use features of PEXlib as well as inquiring PEX extension information, enumerated types, and specific implementation-dependent constants. You'll also need to learn HP implementation details that are covered in this and the following chapters.

Resource Sharing

Because X resources are global in the server, X window applications have been able to share resources between processes by passing the resource ID through some inter-process communications mechanism. HP PEX does not support sharing of PEX resources.

Synchronization

All the normal requirements for achieving proper ordering of rendering and windowing operations in X programs also apply to PEXlib programs. In particular, note that some kinds of requests are re-routed to the window manager (for example, XConfigureWindow). For these requests, it is good practice to wait for the proper type of X event to confirm that the operation has been completed before rendering further in the window.

^[12]The actual pathname of this directory depends on the file system structure. See the Graphics Administration Guide for details.