\&
.sp 1
.ce 3
\s+1\fBChapter 1\fP\s-1
\s+1\fBIntroduction to PEXlib\fP\s-1
.sp 2
.nr H1 1
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 1: Introduction to PEXlib
.XE
.LP
PEXlib is a programmer's interface to the PEX protocol.
PEX is an extension to the X window system for supporting three-dimensional
graphics.
.LP
The application can query the existence of the PEX server extension by calling
.PN XQueryExtension
using the name,
.PN PEX_NAME_STRING ,
defined in PEXlib include files.
.LP
.sp
.IN Initialization
.IN PEXlib initialization
.IN PEXInitialize
.IN Termination
.IN PEXlib termination
To begin using PEXlib, the application must initialize PEXlib by calling
.PN PEXInitialize
before calling any PEXlib function which takes a display argument.
Functions which do not take a display argument may be called prior to calling
.PN PEXInitialize.
.PN PEXInitialize
must be called for each display connection the application will use.
Failure to call
.PN PEXInitialize
will result in undefined behavior for functions which take a display argument.
Termination of PEXlib occurs implicitly at either program end or
.PN XCloseDisplay .
.LP
There are four other functions that should be called during initialization to
determine what features and parameters are supported by each particular
PEX server implementation.
.IN PEXGetExtensionInfo
.IN PEXGetImpDepConstants
.IN PEXGetEnumTypeInfo
.IN PEXMatchRenderingTargets
These functions are
.PN PEXGetExtensionInfo ,
.PN PEXGetImpDepConstants ,
.PN PEXGetEnumTypeInfo ,
and
.PN PEXMatchRenderingTargets .
.PN PEXGetExtensionInfo
returns information about the PEX server extension such as protocol version,
vendor string, release number and subset support.
.PN PEXGetImpDepConstants
returns information about supported implementation-dependent constants.
.PN PEXGetEnumTypeInfo
returns information about supported enumerated types.
.PN PEXMatchRenderingTargets
returns information about supported drawable types.
.LP
.sp
.IN Allocation
.IN Deallocation
.IN "Memory" "allocation"
.IN "Memory" "deallocation"
.IN "Memory" "XFree"
Some PEXlib functions allocate memory on behalf of the application.
Memory allocation often occurs in the case of inquiry functions where the
size of data to be returned is unknown.
Applications must use
.PN XFree
to deallocate memory that has been allocated for them by PEXlib,
unless a specific function is provided to free memory allocated for particular
PEXlib objects.
Where necessary, the specific function for deallocation is noted in the
description of the function which allocates the memory.
Memory allocated by PEXlib is considered to be `owned' by PEXlib; the
application must not modify pointers to memory returned by the library nor
attempt to free such memory except by the specified interfaces.
Data structure fields other than pointers to memory can be changed without
consequence.
.LP
.sp
.IN "Transport mechanisms"
.IN "XSync"
.IN "XSynchronize"
.IN "XNextEvent"
PEXlib is designed as an extension to Xlib using the same transport
and error mechanisms as Xlib. This includes all requests, replies, events
and errors.
This means synchronization (e.g.
.PN XSync
and
.PN XSynchronize )
will have the same effect on PEXlib requests as they do on Xlib requests.
PEX events also are treated in the same way as X events (e.g. use
.PN XNextEvent ).
.LP
.IN "Errors"
.IN "Return values"
PEXlib functions usually do not check for invalid parameters.
Applications should be careful to pass correct data to PEXlib.
Incorrect values sent to the PEX server extension will cause an error event
to be returned to the client.
These errors are asynchronous, and so are difficult to trace to a particular
Xlib or PEXlib call unless using
.PN XSync
or
.PN XSynchronize .
Note these functions should
be used with prudence, since they slow client programs significantly.
.LP
By default, when an error event is returned by the server, Xlib prints a
message and the application does not continue.
The application can register its own error handler by calling
.PN XSetErrorHandler .
.LP
.sp
The floating point format used by PEXlib is the format native to the
architecture of the client machine (i.e. the machine on which the application
executes). All floating point values are expected to be in that native format,
with a few exceptions for functions which allow the application to specify the
floating point format.
Those functions which allow the application to specify a floating point format
deal primarily with application data that is already in protocol format, or data
that the application wants to be encoded into protocol format for its own use.
.LP
When the server to which PEXlib is sending data does not support the floating
point format native to PEXlib, PEXlib will choose an appropriate format which
is supported by the server and convert into that format when formatting
protocol to send to that server.
In cases where PEXlib must choose a non-native floating point format, the
application can determine the format chosen by calling
.PN PEXGetProtocolFloatFormat .
This is useful with those functions dealing with protocol formatted data to help
avoid unnecessary format conversions when sending the data to the PEX server.
.LP
.sp
One other function is defined in this opening chapter.
.PN PEXGetSizeOCs
is a utility function for determining the protocol formatted size of output
commands. If the output command(s) plus the request header is larger than the
maximum request size supported by a particular server (see
.PN XMaxRequestSize ),
a
.PN BadLength
error will be generated.
.LP
.sp
.IN "Include files"
.IN "Header files"
.IN "Files" "header"
.IN "Files" "include"
The PEXlib specification currently defines function bindings and include files
for the C language only. The specification is intended to work for both
ANSI C and Kernighan and Ritchie (K&R) C compilers.
.LP
The
.Pn < X11/PEX5/PEX.h >
and
.Pn < X11/PEX5/PEXlib.h >
include files contain constant definitions, macros, and data
structures used by PEXlib.
.Pn < X11/PEX5/PEXlib.h >
automatically includes
.Pn < X11/PEX5/PEX.h >.
Some data structures have fields named "reserved". These fields are necessary
to align the data correctly for efficient transfer to the protocol transport
buffer. Any values assigned to these fields will be ignored.
.IN "Library name"
.IN "compilation"
.LP
The library is specified in the compilation command as "-lPEX5".
.LP
The utility functions in \fIChapter 16\fP use math functions which create a
dependency on the math library. This means that all PEXlib applications need to
be linked with the math library, typically specified in the compilation command
as "-lm".
.LP
.sp
Sincere effort has been made to adhere to the following conventions:
.ID
.IP \s-2\(bu\s+2 2
PEXlib uses mixed case for external symbols. PEXlib leaves all
lower-case for user variables and all upper-case for user macros, per
existing convention. Where acronyms are used in a symbol, all
characters of the acronym are upper-case, e.g. BF, HLHSR, LUT, OC, PC.
.IP \s-2\(bu\s+2 2
All PEXlib functions, symbols, macros, user-visible data structures
or anything a user might dereference begin with "PEX".
A single exception to this is the error constants which are prefixed with
"BadPEX" in order to be consistent with Xlib.
.IP \s-2\(bu\s+2 2
The beginnings (i.e. immediately following the "PEX" prefix) of all
function names and symbols are capitalized.
.IP \s-2\(bu\s+2 2
All fields in a data structure are in lower-case.
Compound words are constructed with underscores.
This convention overrides the capitalization of acronyms, for data structure
field names only.
.IP \s-2\(bu\s+2 2
The display argument, where needed, is always first in the argument list.
.IP \s-2\(bu\s+2 2
All resource arguments, where needed, occur at the beginning of the
argument list but after the display argument. Where a drawable
resource is needed, it will be listed before other resource arguments.
.IP \s-2\(bu\s+2 2
Source arguments always precede destination arguments.
.IP \s-2\(bu\s+2 2
Where a mask is specified, the mask always precedes the pointer to the
structure.
.IP \s-2\(bu\s+2 2
Where a count is specified, the count always precedes the pointer to the list.
.IP \s-2\(bu\s+2 2
Min always precedes max.
.IP \s-2\(bu\s+2 2
Coordinates are specified in x, y or x, y, z order.
.IP \s-2\(bu\s+2 2
Color triplets are listed in r,g,b; h,s,v; h,l,s; u,v,l; order as
appropriate for the color type.
.IP \s-2\(bu\s+2 2
PEXlib defines constants
for the user consistent with the PEX protocol. True and False are
already defined by Xlib, and are consistent with PEX protocol.
.DE
.bp
.XS
Function Descriptions
.XE
.SH
PEXFreeEnumInfo - Free Memory Allocated for Enumerated Type Information
.XS
PEXFreeEnumInfo
.XE
.IN "PEXFreeEnumInfo" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeEnumInfo\^(\^unsigned long \fIcount\fP\^, unsigned long *\fIinfo_count\fP\^, PEXEnumTypeDesc *\fIenum_info\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIcount\fP 1i
The number of enumerated types.
.IP \fIinfo_count\fP 1i
An array of counts. This corresponds to the info_count_return parameter in
.PN PEXGetEnumTypeInfo .
.IP \fIenum_info\fP 1i
An array of enumerated type descriptors. This corresponds to the
enum_info_return parameter of
.PN PEXGetEnumTypeInfo .
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
.PN PEXFreeEnumInfo
frees memory allocated by PEXlib for the return value and return parameter in
.PN PEXGetEnumTypeInfo .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXGetEnumTypeInfo
.RE
.bp
.SH
PEXGetEnumTypeInfo - Get Enumerated Type Information
.XS
PEXGetEnumTypeInfo
.XE
.IN "PEXGetEnumTypeInfo" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXGetEnumTypeInfo\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, unsigned long \fIcount\fP\^, int *\fIenum_types\fP\^, unsigned long \fIitem_mask\fP\^, unsigned long **\fIinfo_count_return\fP\^, PEXEnumTypeDesc **\fIenum_info_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.IP \fIdrawable\fP 1i
The resource identifier of a drawable.
.IP \fIcount\fP 1i
The number of enumerated types.
.IP \fIenum_types\fP 1i
A list of enumerated types for which information is to be returned. (See the Description for valid values.)
.IP \fIitem_mask\fP 1i
A mask indicating the data to be returned for each enumerated type. (See the Description for valid values.)
.IP \fIinfo_count_return\fP 1i
Returns an array of counts. For each enumerated type, there is an entry
specifying the number of descriptors in the return value array.
.IP \fIenum_info_return\fP 1i
Returns an array of enumerated type descriptors containing the enumerated type
information.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful; non-zero otherwise.
.RE
.SH
Description
.RS
.LP
.PN PEXGetEnumTypeInfo
allows the application to inquire the supported values for each enumerated type.
It returns a descriptor for each supported value of each specified enumerated
type requested.
These values will be valid for all drawables having the same root window and
depth as the specified drawable.
.LP
The standard PEX enumerated types are:
.ID
.PN PEXETATextStyle
.PN PEXETColorApproxModel
.PN PEXETColorApproxType
.PN PEXETColorType
.PN PEXETCurveApproxMethod
.PN PEXETDisplayUpdateMode
.PN PEXETEscape
.PN PEXETFloatFormat
.PN PEXETGDP2D
.PN PEXETGDP
.PN PEXETGSE
.PN PEXETHatchStyle
.PN PEXETHLHSRMode
.PN PEXETInteriorStyle
.PN PEXETLightType
.PN PEXETLineType
.PN PEXETMarkerType
.PN PEXETModelClipOperator
.PN PEXETParaSurfCharacteristics
.PN PEXETPickAllMethod
.PN PEXETPickDeviceType
.PN PEXETPickOneMethod
.PN PEXETPolylineInterpMethod
.PN PEXETPromptEchoType
.PN PEXETReflectionModel
.PN PEXETRenderingColorModel
.PN PEXETSurfaceApproxMethod
.PN PEXETSurfaceEdgeType
.PN PEXETSurfaceInterpMethod
.PN PEXETTrimCurveApproxMethod
.DE
Enumerated type descriptors are made up of an index
field and a mnemonic field. The index field contains the numeric
value of the supported type, and the mnemonic field contains a
string describing the type.
.LP
The item mask specifies which of the fields is returned
in each enumerated type descriptor. Defined values for the item mask are
.PN PEXETCounts ,
.PN PEXETIndex ,
.PN PEXETMnemonic
and
.PN PEXETAll .
If the item mask is
.PN PEXETCounts ,
no descriptor values are returned; only the counts will be returned.
If the item mask is
.PN PEXETIndex ,
the supported index values are returned in addition to the counts.
If the item mask is
.PN PEXETMnemonic ,
the mnemonic strings describing the supported values are returned in addition
to the counts.
If the item mask is
.PN PEXETAll ,
both the supported index values and the mnemonic strings are returned in
addition to the counts.
.LP
PEXlib allocates memory for the returned array of counts
and for the return value array of enumerated type descriptors.
.PN PEXFreeEnumInfo
should be called to deallocate this memory.
.LP
The following are the standard enumerated type index, mnemonic pairs which may
be returned.
.RS
.PN PEXETATextStyle
.ID
.fi
.PN PEXATextNotConnected ,
.PN PEXETMATextNotConnected
.br
.PN PEXATextConnected ,
.PN PEXETMATextConnected
.br
.DE
.PN PEXETColorApproxModel
.ID
.fi
.PN PEXColorApproxRGB ,
.PN PEXETMColorApproxRGB
.br
.PN PEXColorApproxCIE ,
.PN PEXETMColorApproxCIE
.br
.PN PEXColorApproxHSV ,
.PN PEXETMColorApproxHSV
.br
.PN PEXColorApproxHLS ,
.PN PEXETMColorApproxHLS
.br
.PN PEXColorApproxYIQ ,
.PN PEXETMColorApproxYIQ
.DE
.PN PEXETColorApproxType
.ID
.fi
.PN PEXColorSpace ,
.PN PEXETMColorSpace
.br
.PN PEXColorRange ,
.PN PEXETMColorRange
.DE
.PN PEXETColorType
.ID
.fi
.PN PEXColorTypeIndexed ,
.PN PEXETMColorTypeIndexed
.br
.PN PEXColorTypeRGB ,
.PN PEXETMColorTypeRGB
.br
.PN PEXColorTypeCIE ,
.PN PEXETMColorTypeCIE
.br
.PN PEXColorTypeHSV ,
.PN PEXETMColorTypeHSV
.br
.PN PEXColorTypeHLS ,
.PN PEXETMColorTypeHLS
.br
.PN PEXColorTypeRGB8 ,
.PN PEXETMColorTypeRGB8
.br
.PN PEXColorTypeRGB16 ,
.PN PEXETMColorTypeRGB16
.DE
.PN PEXETCurveApproxMethod
.ID
.fi
.PN PEXApproxImpDep ,
implementation-dependent string
.br
.PN PEXApproxConstantBetweenKnots ,
.PN PEXETMApproxConstantBetweenKnots
.br
.PN PEXApproxWCChordalSize ,
.PN PEXETMApproxWCChordalSize
.br
.PN PEXApproxNPCChordalSize ,
.PN PEXETMApproxNPCChordalSize
.br
.PN PEXApproxDCChordalSize ,
.PN PEXETMApproxDCChordalSize
.br
.PN PEXCurveApproxWCChordalDev ,
.PN PEXETMCurveApproxWCChordalDev
.br
.PN PEXCurveApproxNPCChordalDev ,
.PN PEXETMCurveApproxNPCChordalDev
.br
.PN PEXCurveApproxDCChordalDev ,
.PN PEXETMCurveApproxDCChordalDev
.br
.PN PEXApproxWCRelative ,
.PN PEXETMApproxWCRelative
.br
.PN PEXApproxNPCRelative ,
.PN PEXETMApproxNPCRelative
.br
.PN PEXApproxDCRelative ,
.PN PEXETMApproxDCRelative
.DE
.PN PEXETDisplayUpdateMode
.ID
.fi
.PN PEXVisualizeEach ,
.PN PEXETMVisualizeEach
.br
.PN PEXVisualizeEasy ,
.PN PEXETMVisualizeEasy
.br
.PN PEXVisualizeNone ,
.PN PEXETMVisualizeNone
.br
.PN PEXSimulateSome ,
.PN PEXETMSimulateSome
.br
.PN PEXVisualizeWhenever ,
.PN PEXETMVisualizeWhenever
.DE
.PN PEXETEscape
.ID
.fi
.PN PEXEscapeSetEchoColor
.PN PEXETMEscapeSetEchoColor
.DE
.PN PEXETFloatFormat
.ID
.fi
.PN PEXIEEE_754_32 ,
.PN PEXETMIEEE_754_32
.br
.PN PEXDEC_F_Floating ,
.PN PEXETMDEC_F_Floating
.br
.PN PEXIEEE_754_64 ,
.PN PEXETMIEEE_754_64
.br
.PN PEXDEC_D_Floating ,
.PN PEXETMDEC_D_Floating
.DE
.PN PEXETGDP2D
.ID
.fi
There are currently no standard 2D generalized drawing primitives.
.DE
.PN PEXETGDP
.ID
.fi
There are currently no standard 3D generalized drawing primitives.
.DE
.PN PEXETGSE
.ID
.fi
There are currently no standard generalized structure elements.
.DE
.PN PEXETHatchStyle
.ID
.fi
There are currently no standard hatch styles.
.DE
.PN PEXETHLHSRMode
.ID
.fi
.PN PEXHLHSROff ,
.PN PEXETMHLHSROff
.br
.PN PEXHLHSRZBuffer ,
.PN PEXETMHLHSRZBuffer
.br
.PN PEXHLHSRPainters ,
.PN PEXETMHLHSRPainters
.br
.PN PEXHLHSRScanline ,
.PN PEXETMHLHSRScanline
.br
.PN PEXHLHSRHiddenLineOnly ,
.PN PEXETMHLHSRHiddenLineOnly
.br
.PN PEXHLHSRZBufferID ,
.PN PEXETMHLHSRZBufferID
.DE
.PN PEXETInteriorStyle
.ID
.fi
.PN PEXInteriorStyleHollow ,
.PN PEXETMInteriorStyleHollow
.br
.PN PEXInteriorStyleSolid ,
.PN PEXETMInteriorStyleSolid
.br
.PN PEXInteriorStylePattern ,
.PN PEXETMInteriorStylePattern
.br
.PN PEXInteriorStyleHatch ,
.PN PEXETMInteriorStyleHatch
.br
.PN PEXInteriorStyleEmpty ,
.PN PEXETMInteriorStyleEmpty
.DE
.PN PEXETLightType
.ID
.fi
.PN PEXLightAmbient ,
.PN PEXETMLightAmbient
.br
.PN PEXLightWCVector ,
.PN PEXETMLightWCVector
.br
.PN PEXLightWCPoint ,
.PN PEXETMLightWCPoint
.br
.PN PEXLightWCSpot ,
.PN PEXETMLightWCSpot
.DE
.PN PEXETLineType
.ID
.fi
.PN PEXLineTypeSolid ,
.PN PEXETMLineTypeSolid
.br
.PN PEXLineTypeDashed ,
.PN PEXETMLineTypeDashed
.br
.PN PEXLineTypeDotted ,
.PN PEXETMLineTypeDotted
.br
.PN PEXLineTypeDashDot ,
.PN PEXETMLineTypeDashDot
.DE
.PN PEXETMarkerType
.ID
.fi
.PN PEXMarkerDot ,
.PN PEXETMMarkerDot
.br
.PN PEXMarkerCross ,
.PN PEXETMMarkerCross
.br
.PN PEXMarkerAsterisk ,
.PN PEXETMMarkerAsterisk
.br
.PN PEXMarkerCircle ,
.PN PEXETMMarkerCircle
.br
.PN PEXMarkerX ,
.PN PEXETMMarkerX
.DE
.PN PEXETModelClipOperator
.ID
.fi
.PN PEXModelClipReplace ,
.PN PEXETMModelClipReplace
.br
.PN PEXModelClipIntersection ,
.PN PEXETMModelClipIntersection
.DE
.PN PEXETParaSurfCharacteristics
.ID
.fi
.PN PEXPSCNone ,
.PN PEXETMPSCNone
.br
.PN PEXPSCImpDep ,
implementation-dependent string
.br
.PN PEXPSCIsoCurves ,
.PN PEXETMPSCIsoCurves
.br
.PN PEXPSCMCLevelCurves ,
.PN PEXETMPSCMCLevelCurves
.br
.PN PEXPSCWCLevelCurves ,
.PN PEXETMPSCWCLevelCurves
.DE
.PN PEXETPickAllMethod
.ID
.fi
.PN PEXPickAllAll ,
.PN PEXETMPickAllAll
.br
.PN PEXPickAllVisible ,
.PN PEXETMPickAllVisible
.DE
.PN PEXETPickDeviceType
.ID
.fi
.PN PEXPickDeviceDCHitBox ,
.PN PEXETMPickDeviceDCHitBox
.br
.PN PEXPickDeviceNPCHitVolume ,
.PN PEXETMPickDeviceNPCHitVolume
.DE
.PN PEXETPickOneMethod
.ID
.fi
.PN PEXPickLast ,
.PN PEXETMPickLast
.br
.PN PEXPickClosestZ ,
.PN PEXETMPickClosestZ
.br
.PN PEXPickVisibleAny ,
.PN PEXETMPickVisibleAny
.br
.PN PEXPickVisibleClosest ,
.PN PEXETMPickVisibleClosest
.DE
.PN PEXETPolylineInterpMethod
.ID
.fi
.PN PEXPolylineInterpNone ,
.PN PEXETMPolylineInterpNone
.br
.PN PEXPolylineInterpColor ,
.PN PEXETMPolylineInterpColor
.DE
.PN PEXETPromptEchoType
.ID
.fi
.PN PEXEchoPrimitive ,
.PN PEXETMEchoPrimitive
.br
.PN PEXEchoStructure ,
.PN PEXETMEchoStructure
.br
.PN PEXEchoNetwork ,
.PN PEXETMEchoNetwork
.DE
.PN PEXETReflectionModel
.ID
.fi
.PN PEXReflectionNone ,
.PN PEXETMReflectionNone
.br
.PN PEXReflectionAmbient ,
.PN PEXETMReflectionAmbient
.br
.PN PEXReflectionDiffuse ,
.PN PEXETMReflectionDiffuse
.br
.PN PEXReflectionSpecular ,
.PN PEXETMReflectionSpecular
.DE
.PN PEXETRenderingColorModel
.ID
.fi
.PN PEXRenderingColorModelImpDep ,
implementation-dependent string
.br
.PN PEXRenderingColorModelRGB ,
.PN PEXETMRenderingColorModelRGB
.br
.PN PEXRenderingColorModelCIE ,
.PN PEXETMRenderingColorModelCIE
.br
.PN PEXRenderingColorModelHSV ,
.PN PEXETMRenderingColorModelHSV
.br
.PN PEXRenderingColorModelHLS ,
.PN PEXETMRenderingColorModelHLS
.DE
.PN PEXETSurfaceApproxMethod
.ID
.fi
.PN PEXApproxImpDep ,
implementation-dependent string
.br
.PN PEXApproxConstantBetweenKnots ,
.PN PEXETMApproxConstantBetweenKnots
.br
.PN PEXApproxWCChordalSize ,
.PN PEXETMApproxWCChordalSize
.br
.PN PEXApproxNPCChordalSize ,
.PN PEXETMApproxNPCChordalSize
.br
.PN PEXApproxDCChordalSize ,
.PN PEXETMApproxDCChordalSize
.br
.PN PEXSurfaceApproxWCPlanarDev ,
.PN PEXETMSurfaceApproxWCPlanarDev
.br
.PN PEXSurfaceApproxNPCPlanarDev ,
.PN PEXETMSurfaceApproxNPCPlanarDev
.br
.PN PEXSurfaceApproxDCPlanarDev ,
.PN PEXETMSurfaceApproxDCPlanarDev
.br
.PN PEXApproxWCRelative ,
.PN PEXETMApproxWCRelative
.br
.PN PEXApproxNPCRelative ,
.PN PEXETMApproxNPCRelative
.br
.PN PEXApproxDCRelative ,
.PN PEXETMApproxDCRelative
.DE
.PN PEXETSurfaceEdgeType
.ID
.fi
.PN PEXSurfaceEdgeSolid ,
.PN PEXETMSurfaceEdgeSolid
.br
.PN PEXSurfaceEdgeDashed ,
.PN PEXETMSurfaceEdgeDashed
.br
.PN PEXSurfaceEdgeDotted ,
.PN PEXETMSurfaceEdgeDotted
.br
.PN PEXSurfaceEdgeDashDot ,
.PN PEXETMSurfaceEdgeDashDot
.DE
.PN PEXETSurfaceInterpMethod
.ID
.fi
.PN PEXSurfaceInterpNone ,
.PN PEXETMSurfaceInterpNone
.br
.PN PEXSurfaceInterpColor ,
.PN PEXETMSurfaceInterpColor
.br
.PN PEXSurfaceInterpDotProduct ,
.PN PEXETMSurfaceInterpDotProduct
.br
.PN PEXSurfaceInterpNormal ,
.PN PEXETMSurfaceInterpNormal
.DE
.PN PEXETTrimCurveApproxMethod
.ID
.fi
.PN PEXApproxImpDep ,
implementation-dependent string
.br
.PN PEXApproxConstantBetweenKnots ,
.PN PEXETMApproxConstantBetweenKnots
.DE
.RE
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
PEXEnumTypeIndex index;
char *descriptor; /* null terminated string */
} PEXEnumTypeDesc;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadMatch\fP 1i
The specified drawable is unsupported.
.IP \fIBadValue\fP 1i
A specified enumerated type is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXFreeEnumInfo
.RE
.bp
.SH
PEXGetExtensionInfo - Get Extension Information
.XS
PEXGetExtensionInfo
.XE
.IN "PEXGetExtensionInfo" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXExtensionInfo *PEXGetExtensionInfo\^(\^Display *\fIdisplay\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.RE
.SH
Returns
.RS
.LP
A pointer to the extension information; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
.PN PEXGetExtensionInfo
allows an application program to inquire the extension
information from a PEX server extension.
.LP
The major version
number, minor version number, release number, vendor name, and subset
information are returned. If the subset value is
.PN PEXCompleteImplementation ,
the extension is a full PEX implementation.
If the subset value is
.PN PEXImmediateMode ,
the extension supports only the "immediate rendering" subset of PEX.
If the subset value is
.PN PEXStructureMode ,
the extension supports only the "structure rendering" subset of PEX.
If the subset value is
.Pn ( PEXImmediateMode
&
.PN PEXStructureMode ),
the extension supports both the "immediate rendering" and the
"structure rendering" subsets of PEX.
If the subset value is
.PN PEXWorkstationOnly ,
the extension supports only the "PHIGS workstation" subset of PEX.
.LP
The memory returned by this function is private to PEXlib and must not be
modified or freed by the application.
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
unsigned short major_version;
unsigned short minor_version;
unsigned long release;
unsigned long subset_info;
char *vendor_name;
int major_opcode;
int first_event;
int first_error;
} PEXExtensionInfo;
.ft P
.DE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.RE
.bp
.SH
PEXGetImpDepConstants - Get Implementation Dependent Constants
.XS
PEXGetImpDepConstants
.XE
.IN "PEXGetImpDepConstants" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXGetImpDepConstants\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, unsigned long \fIcount\fP\^, unsigned short *\fInames\fP\^, PEXImpDepConstant **\fIconstants_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.IP \fIdrawable\fP 1i
The resource identifier of a drawable.
.IP \fIcount\fP 1i
The number of implementation-dependent constants.
.IP \fInames\fP 1i
An array of names of implementation-dependent constants to be returned. (See the Description for valid values.)
.IP \fIconstants_return\fP 1i
Returns an array of implementation-dependent constants.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful; non-zero otherwise.
.RE
.SH
Description
.RS
.LP
.PN PEXGetImpDepConstants
allows an application program to query one or more
implementation-dependent constants.
.LP
A single integer or floating-point value is
returned for each value requested. These values are returned
in order, with one return value in constants for each
item in names.
The implementation-dependent constants returned are based
on the values used for a drawable having the same
root and depth as the drawable specified.
PEXlib allocates memory for the returned constants.
.PN XFree
should be called to deallocate the memory.
.LP
The following implementation-dependent constants are standard:
.RS
.LP
.PN PEXIDBestColorApprox
(integer) -
Either
.PN PEXColorApproxPowersOf2
or
.PN PEXColorApproxAnyValues ,
depending on whether there is a significant performance gain if the number
of reds/greens/blues in the color approximation table entry is
a power of two, so pixels can be composed using shifts
and adds.
.LP
.PN PEXIDDitheringSupported
(integer) -
Either
.PN True
if the dithering hint in color approximation lookup tables is
used to control dithering,
or
.PN False ,
if the dithering hint in color approximation lookup tables is not used.
.LP
.PN PEXIDDoubleBufferingSupported
(integer) -
Either
.PN True
if the server supports double-buffering for workstation resources,
or
.PN False ,
if the server does not supports double-buffering for workstation resources.
.LP
.PN PEXIDMaxEdgeWidth
(integer) -
Width (in pixels) of widest edge that can be drawn.
.LP
.PN PEXIDMaxHitsEventSupported
(integer) -
.PN True
if the server supports the
.PN PEXMaxHitsReached
event,
or
.PN False ,
if the server does not support the event.
.LP
.PN PEXIDMaxLineWidth
(integer) -
Width (in pixels) of widest line or curve that can be drawn.
.LP
.PN PEXIDMaxMarkerSize
(integer) -
Largest dimension (either height or width, in pixels) of
largest marker that can be drawn. This maximum is exclusive
of the marker type
.PN PEXMarkerDot
which is always drawn as the smallest displayable point.
.LP
.PN PEXIDMaxModelClipPlanes
(integer) -
Maximum number of modeling clipping planes may be defined.
.LP
.PN PEXIDMaxNameSetNames
(integer) -
Maximum number of names allowed in a name set.
.LP
.PN PEXIDMaxNonAmbientLights
(integer) -
Maximum number of non-ambient light sources that can be enabled
at one time.
.LP
.PN PEXIDMaxNURBOrder
(integer) -
Maximum non-uniform rational B-spline order supported.
.LP
.PN PEXIDMaxTrimCurveOrder
(integer) -
Maximum order for trim curves.
.LP
.PN PEXIDMinEdgeWidth
(integer) -
Width (in pixels) of thinnest edge that can be drawn.
.LP
.PN PEXIDMinLineWidth
(integer) -
Width (in pixels) of thinnest line or curve that can be drawn.
.LP
.PN PEXIDMinMarkerSize
(integer) -
Largest dimension (either height or width, in pixels) of
smallest marker that can be drawn. This minimum is exclusive
of the marker type
.PN PEXMarkerDot
which is always drawn as the smallest displayable point.
.LP
.PN PEXIDNominalEdgeWidth
(integer) -
Width (in pixels) of "standard" edge.
.LP
.PN PEXIDNominalLineWidth
(integer) -
Width (in pixels) of "standard" line or curve.
.LP
.PN PEXIDNominalMarkerSize
(integer) -
Largest dimension (either height or width, in pixels) of
"standard" marker.
.LP
.PN PEXIDNumSupportedEdgeWidths
(integer) -
Number of supported edge widths. A value of 0 indicates that
all edge widths, including fractional widths, between the
minimum and maximum edge width are supported.
.LP
.PN PEXIDNumSupportedLineWidths
(integer) -
Number of supported line or curve widths. A value of 0
indicates that all line widths, including fractional widths,
between the minimum and maximum line width are supported.
.LP
.PN PEXIDNumSupportedMarkerSizes
(integer) -
Number of supported marker sizes. A value of 0 indicates that
all marker sizes, including fractional values, between the
minimum and maximum marker size are supported.
.LP
.PN PEXIDTransparencySupported
(integer) -
Either
.PN True
if the transmission coefficient is utilized in the reflectance calculations,
or
.PN False ,
if the transmission coefficient is not utilized.
.LP
.PN PEXIDChromaticityRedU
(flt_point) -
CIEYUV u chromaticity coefficient for the red channel
of the (properly adjusted) display device.
.LP
.PN PEXIDChromaticityRedV
(flt_point) -
CIEYUV v chromaticity coefficient for the red channel
of the (properly adjusted) display device.
.LP
.PN PEXIDLuminanceRed
(flt_point) -
CIEYUV luminance value for the red channel of the (properly
adjusted) display device.
.LP
.PN PEXIDChromaticityGreenU
(flt_point) -
CIEYUV u chromaticity coefficient for the green channel
of the (properly adjusted) display device.
.LP
.PN PEXIDChromaticityGreenV
(flt_point) -
CIEYUV v chromaticity coefficient for the green channel
of the (properly adjusted) display device.
.LP
.PN PEXIDLuminanceGreen
(flt_point) -
CIEYUV luminance value for the green channel of the (properly
adjusted) display device.
.LP
.PN PEXIDChromaticityBlueU
(flt_point) -
CIEYUV u chromaticity coefficient for the blue channel
of the (properly adjusted) display device.
.LP
.PN PEXIDChromaticityBlueV
(flt_point) -
CIEYUV v chromaticity coefficient for the blue channel
of the (properly adjusted) display device.
.LP
.PN PEXIDLuminanceBlue
(flt_point) -
CIEYUV luminance value for the blue channel of the (properly
adjusted) display device.
.LP
.PN PEXIDChromaticityWhiteU
(flt_point) -
CIEYUV u chromaticity coefficient for the reference white
of the (properly adjusted) display device.
.LP
.PN PEXIDChromaticityWhiteV
(flt_point) -
CIEYUV v chromaticity coefficient for the reference white
of the (properly adjusted) display device.
.LP
.PN PEXIDLuminanceWhite
(flt_point) -
CIEYUV luminance value for the reference white of the (properly
adjusted) display device.
.RE
.RE
.SH
Data Structures
.ID
.Co
typedef union {
unsigned long integer;
float flt_point;
} PEXImpDepConstant;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadMatch\fP 1i
The specified drawable is unsupported.
.IP \fIBadValue\fP 1i
A specified implementation-dependent constant name is invalid.
.RE
.SH
See Also
.RS
.RE
.bp
.SH
PEXInitialize - Initialize PEXlib display connection
.XS
PEXInitialize
.XE
.IN "PEXInitialize" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
int PEXInitialize\^(\^Display *\fIdisplay\fP\^, PEXExtensionInfo **\fIinfo_return\fP\^, int \fIlength\fP\^, char *\fIerror_string\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.IP \fIinfo_return\fP 1i
Returns a pointer to the extension information; if available (see the Description).
.IP \fIlength\fP 1i
The length, in bytes, of the memory allocated for the error string.
.IP \fIerror_string\fP 1i
A pointer to memory allocated for the error string.
.RE
.SH
Returns
.RS
.LP
Zero if successful; otherwise, one of the following return values:
.ID
.PN PEXBadExtension
.PN PEXBadProtocolVersion
.PN PEXBadFloatConversion
.PN PEXBadLocalAlloc
.DE
.RE
.SH
Description
.RS
.LP
.PN PEXInitialize
initializes PEXlib for the specified display.
.LP
.PN PEXInitialize
can be called multiple times; subsequent calls will result in the same return
value as the first call.
.LP
Standard
.PN PEXInitialize
failure return values are:
.ID
.fi
.PN PEXBadExtension
- the PEX server extension does not exist,
.br
.PN PEXBadProtocolVersion
- the PEX server extension does not support a compatible protocol version,
.br
.PN PEXBadFloatConversion
- the PEX server extension does not support a protocol floating point format
compatible with PEXlib's native format or a format to which PEXlib supports
conversion, or
.br
.PN PEXBadLocalAlloc
- PEXlib client-side allocation failed.
.DE
.LP
If
.PN PEXInitialize
is successful (return value is zero), or if the return value is
.PN PEXBadProtocolVersion ,
a pointer to the extension information is returned in info_return.
Otherwise, a NULL pointer is returned in info_return. The
extension information is private to PEXlib and must not be modified or freed
by the application.
.LP
The error string parameter specifies an address to
memory allocated by the application.
The constant
.PN PEXErrorStringLength
is defined as a guideline for the size to allocate for the error string.
If no failure occurred, the memory
addressed by the error string parameter will be unchanged.
If a failure does occur, an error string giving further information about
the failure will be copied into this memory (up to the maximum specified by the
length parameter).
.LP
The actual string returned is implementation dependent, and is provided
primarily for convenience in printing an error message for the application's
end-user.
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
unsigned short major_version;
unsigned short minor_version;
unsigned long release;
unsigned long subset_info;
char *vendor_name;
int major_opcode;
int first_event;
int first_error;
} PEXExtensionInfo;
.ft P
.DE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXGetExtensionInfo ,
.PN PEXGetEnumTypeInfo ,
.PN PEXGetImpDepConstants ,
.br
.PN PEXMatchRenderingTargets
.RE
.bp
.SH
PEXMatchRenderingTargets - Return Information about Supported Rendering Targets
.XS
PEXMatchRenderingTargets
.XE
.IN "PEXMatchRenderingTargets" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXMatchRenderingTargets\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, int \fIdepth\fP\^, int \fItype\fP\^, Visual *\fIvisual\fP\^, unsigned long \fImax_targets\fP\^, unsigned long *\fIcount_return\fP\^, PEXRenderingTarget **\fItargets_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.IP \fIdrawable\fP 1i
The drawable indicates which screen the application is interested in.
.IP \fIdepth\fP 1i
The depth of interest.
.IP \fItype\fP 1i
The drawable type of interest
.Pn ( PEXAnyDrawable ,
.PN PEXWindowDrawable ,
.PN PEXPixmapDrawable ,
.PN PEXBufferDrawable ).
.IP \fIvisual\fP 1i
The visual of interest.
.IP \fImax_targets\fP 1i
The maximum number of targets to return.
.IP \fIcount_return\fP 1i
Returns the actual number of targets in the return array.
.IP \fItargets_return\fP 1i
Returns an array of rendering target information.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful; non-zero otherwise.
.RE
.SH
Description
.RS
.LP
This function returns information about which drawable types the server
supports.
.LP
A drawable is specified only to indicate the screen for which the
returned information should apply. None of the other drawable attributes are
used.
.LP
The depth value is specified to indicate the depth for which the returned
information should apply. If the application wants information on all
supported depths, a value of zero should be specified.
.LP
The drawable type is specified to indicate the type of drawable for which
the returned information should apply.
The type field of the
.PN PEXRenderingTarget
data structure will have these same values with the exception of
.PN PEXAnyDrawable .
.LP
The visual is specified to indicate the visual for which the returned
information should apply. If the application wants information on all
supported visuals, a null pointer should be specified.
.LP
PEXlib allocates memory for the returned target values.
.PN XFree
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef struct {
int depth;
int type; /* PEXWindowDrawable, PEXPixmapDrawable, PEXBufferDrawable */
Visual *visual;
} PEXRenderingTarget;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadValue\fP 1i
The specified visual is invalid.
.RE
.SH
See Also
.RS
.RE
.bp
.SH
PEXGetProtocolFloatFormat - Return Float Format used on Specified Display Connection
.XS
PEXGetProtocolFloatFormat
.XE
.IN "PEXGetProtocolFloatFormat" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
int PEXGetProtocolFloatFormat\^(\^Display *\fIdisplay\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP
call.
.RE
.SH
Returns
.RS
.LP
Protocol floating point format (see
.PN PEXGetEnumTypeInfo );
zero if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns the protocol floating point format being used by PEXlib
on the specified display connection.
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.RE
.bp
.SH
PEXGetSizeOCs - Return the Protocol Formatted Size of Output Commands
.XS
PEXGetSizeOCs
.XE
.IN "PEXGetSizeOCs" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
int PEXGetSizeOCs\^(\^int \fIfloat_format\fP, int \fIoc_count\fP\^, PEXOCData *\fIoc_data\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIfloat_format\fP 1i
The floating point format to use in computing the formatted size.
.IP \fIoc_count\fP 1i
The number of output commands.
.IP \fIoc_data\fP 1i
An array of output command data.
.RE
.SH
Returns
.RS
.LP
The size, in bytes, of the formatted output commands; zero if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns information about the size of the protocol for the output
commands. An unsuccessful return value is possible if the specified floating
point format is invalid or unsupported by PEXlib.
.LP
.RE
.SH
Data Structures
.ID
.Co
See PEXlib.h for the definition of PEXOCData.
.ft P
.DE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.RE
.bp