\&
.sp 1
.ce 3
\s+1\fBChapter 13\fP\s-1

\s+1\fBPEX Escapes\fP\s-1
.sp 2
.nr H1 13
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 13: PEX Escapes
.XE
.LP
.PN PEXEscape
and
.PN PEXEscapeWithReply
are functions which provide a standard interface to implementation-dependent
or vendor specific requests.
.PN PEXSetEchoColor
is a convenience function for easy access to the one standard PEX escape.
.bp
.XS
Function Descriptions
.XE
.SH
PEXEscape - PEX Escape
.XS
	PEXEscape
.XE
.IN "PEXEscape" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXEscape\^(\^Display *\fIdisplay\fP\^, unsigned long \fIescape_id\fP\^, int \fIlength\fP\^, char *\fIescape_data\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP 
call.
.IP \fIescape_id\fP 1i
The escape identifier.
.IP \fIlength\fP 1i
The length, in bytes, of data for the escape request.
.IP \fIescape_data\fP 1i
A pointer to data for the escape request.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
.PN PEXEscape
has an implementation-dependent effect.  It is provided as a way for
implementation-specific functionality to be accessed.  The complete
interface and behavior for each specified escape identifier should be
specified by the individual PEX server implementation.
.LP
There is one standard PEX escape, see below.
.LP
If the specified escape identifier is not supported,
a value error is generated.
.LP
Standard PEX Escape:
.RS
.LP
.PN PEXEscapeSetEchoColor
is an escape to set the echo color for use by a renderer when echoing
primitives.
.PN PEXEscapeSetEchoColor
is the name of the escape identifier and is passed as the escape identifier
to
.PN PEXEscape.
The escape data for
.PN PEXEscapeSetEchoColor
consists of a renderer resource identifier (XID) followed by
a color specifier
.Pn ( PEXColorSpecifier ).
See the
.PN PEXSetEchoColor
function for further description of this standard escape.
.RE
.RE
.SH
Errors
.RS
.IP Escape-dependent 1i
See documentation provided with the individual PEX server implementation.
.IP \fIBadValue\fP 1i
The specified escape identifier is unsupported.
.RE
.SH
See Also
.RS
.LP
.PN PEXEscapeWithReply ,
.PN PEXSetEchoColor
.RE
.bp
.SH
PEXEscapeWithReply - PEX Escape With Reply
.XS
	PEXEscapeWithReply
.XE
.IN "PEXEscapeWithReply" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
char *PEXEscapeWithReply\^(\^Display *\fIdisplay\fP\^, unsigned long \fIescape_id\fP\^, int \fIlength\fP\^, char *\fIescape_data\fP\^, unsigned long *\fIreply_length_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 \fIescape_id\fP 1i
The escape identifier.
.IP \fIlength\fP 1i
The length, in bytes, of data for the escape request.
.IP \fIescape_data\fP 1i
A pointer to data for the escape request.
.IP \fIreply_length_return\fP 1i
Returns the length, in bytes, of the reply data.
.RE
.SH
Returns
.RS
.LP
A pointer to the escape reply data; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
.PN PEXEscapeWithReply
has an implementation-dependent effect.  It is similar to
.PN PEXEscape
except it has return data.
It is provided as a way for
implementation-specific functionality to be accessed.  The complete
interface and behavior for each specified escape identifier should be
specified by the individual PEX server implementation.
.LP
There are no standard PEX escapes with replies.
.LP
If the specified escape identifier is not supported,
a value error is generated.
.LP
The reply data is returned in memory allocated by PEXlib.
.PN XFree
should be called to deallocate the memory.
.RE
.SH
Errors
.RS
.IP Escape-dependent 1i
See documentation provided with the individual PEX server implementation.
.IP \fIBadValue\fP 1i
The specified escape identifier is unsupported.
.RE
.SH
See Also
.RS
.LP
.PN PEXEscape
.RE
.bp
.SH
PEXSetEchoColor - PEX Escape to set Echo Color for Specified Renderer
.XS
	PEXSetEchoColor
.XE
.IN "PEXSetEchoColor" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXSetEchoColor\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, int \fIcolor_type\fP\^, PEXColor *\fIcolor\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP 
call.
.IP \fIrenderer\fP 1i
The resource identifier of a renderer.
.IP \fIcolor_type\fP 1i
The type of color
.Pn ( PEXColorTypeIndexed ,
.PN PEXColorTypeRGB ,
.PN PEXColorTypeCIE ,
.PN PEXColorTypeHSV ,
.PN PEXColorTypeHLS ,
.PN PEXColorTypeRGB8 ,
.PN PEXColorTypeRGB16 ).
.IP \fIcolor\fP 1i
The echo color.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function is a convenient way to access the
.PN PEXEscapeSetEchoColor
escape to set the echo color for use by a renderer when echoing primitives.
.LP
A renderer's echo color can be changed at any time during rendering and is
not inquirable through the renderer's modification dynamics (see
.PN PEXGetRendererDynamics ).
Lighting and shading for echoed primitives is implementation-dependent.
A renderer's echo color can not be inquired and the default value is
implementation-dependent.
Support of this escape is inquirable via
.PN PEXGetEnumTypeInfo .
.RE
.SH
Data Structures
.ID
.Co
typedef XID             PEXRenderer;
.sp
typedef union {
    PEXColorIndexed     indexed;
    PEXColorRGB         rgb;
    PEXColorHSV         hsv;
    PEXColorHLS         hls;
    PEXColorCIE         cie;
    PEXColorRGB8        rgb8;
    PEXColorRGB16       rgb16;
} PEXColor;
.sp
typedef struct {
    PEXTableIndex       index;
    unsigned short      reserved;
} PEXColorIndexed;
.sp
typedef struct {
    float               red;
    float               green;
    float               blue;
} PEXColorRGB;
.sp
typedef struct {
    float               hue;
    float               saturation;
    float               value;
} PEXColorHSV;
.sp
typedef struct {
    float               hue;
    float               lightness;
    float               saturation;
} PEXColorHLS;
.sp
typedef struct {
    float               x;
    float               y;
    float               z;
} PEXColorCIE;
.sp
typedef struct {
    unsigned char       red;
    unsigned char       green;
    unsigned char       blue;
    unsigned char       reserved;
} PEXColorRGB8;
.sp
typedef struct {
    unsigned short      red;
    unsigned short      green;
    unsigned short      blue;
    unsigned short      reserved;
} PEXColorRGB16;
.sp
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXColorType\fP 1i
The specified color type is invalid or unsupported.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadValue\fP 1i
The
.PN PEXEscapeSetEchoColor
escape is unsupported.
.RE
.SH
See Also
.RS
.LP
.PN PEXEscape
.RE
.bp
