\&
.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