.\" @(#)intro.3 1.3 95/03/24 SMI;
.so man3/pex.macs
.TH intro 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
intro \- introduces the PEXlib graphics library
.SH DESCRIPTION
.\" indexing
.IX Introduction
.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
.B XQueryExtension
using the name,
.B PEX_NAME_STRING,
defined in PEXlib include files.
.IX Initialization
.IX "PEXlib initialization"
.IX PEXInitialize
.IX Termination
.IX "PEXlib termination"
.LP
To begin using PEXlib, the application must initialize PEXlib by calling
.BR PEXInitialize (3)
before calling any PEXlib function which takes a display argument.
Functions which do not take a display argument may be called prior to calling
.BR PEXInitialize (3) .
.BR PEXInitialize (3)
must be called for each display connection the application will use.
Failure to call
.BR PEXInitialize (3)
will result in undefined behavior for functions which take a display argument.
Termination of PEXlib occurs implicitly at either program end or
.B 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.
.IX PEXGetExtensionInfo
.IX PEXGetImpDepConstants
.IX PEXGetEnumTypeInfo
.IX PEXMatchRenderingTargets
These functions are
.BR PEXGetExtensionInfo (3) ,
.BR PEXGetImpDepConstants (3) ,
.BR PEXGetEnumTypeInfo (3) ,
and
.BR PEXMatchRenderingTargets (3) .
.BR PEXGetExtensionInfo (3)
returns information about the PEX server extension such as protocol version,
vendor string, release number and subset support.
.BR PEXGetImpDepConstants (3)
returns information about supported implementation-dependent constants.
.BR PEXGetEnumTypeInfo (3)
returns information about supported enumerated types.
.BR PEXMatchRenderingTargets (3)
returns information about supported drawable types.
.IX Allocation
.IX Deallocation
.IX "Memory" "allocation"
.IX "Memory" "deallocation"
.IX "Memory" "XFree"
.LP
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
.B 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.
.IX "Transport mechanisms"
.IX "XSync"
.IX "XSynchronize"
.IX "XNextEvent"
.LP
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.
.B XSync
and
.B 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
.B XNextEvent
).
.IX "Errors"
.IX "Return values"
.LP
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
.B XSync
or
.B 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
.B XSetErrorHandler .
.LP
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.
.IX "Include files"
.IX "Header files"
.IX "Files" "header"
.IX "Files" "include"
.LP
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
.B < X11/PEX5/PEX.h >
and
.B < X11/PEX5/PEXlib.h >
include files contain constant definitions, macros, and data
structures used by PEXlib.
.B < X11/PEX5/PEXlib.h >
automatically includes
.B < 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.
.IX "compilation"
.LP         
The library is specified in the compilation command as "-lPEX5".