\&
.sp 1
.ce 3
\s+1\fBChapter 5\fP\s-1
\s+1\fBRenderers\fP\s-1
.sp 2
.nr H1 5
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 5: Renderers
.XE
.IN "renderers"
.LP
PEX deals with three-dimensional (geometric) objects and color values
specified by clients. Rendering is the process that converts geometric
information into raster (2D) coordinates and converts color values into colors
or intensities the device can display. Geometric or color data is rendered
to an X drawable after it has been transformed into raster data. The
rendering pipeline is an abstraction used to describe the order
.IN "rendering pipeline"
.IN "pipeline" "rendering"
and the semantics of functions occurring during the rendering process.
.LP
A renderer is a PEX resource containing the functionality necessary to
.IN "renderer"
perform rendering.
A renderer also contains attributes, some of which are resource identifiers for
various tables and name sets, and for the pipeline context from which initial
rendering pipeline attributes are copied.
When a renderer is created, if lookup table resources are not specified for
some lookup tables, the default value will be no lookup table. When rendering,
if a lookup table resource doesn't exist in the renderer, the default values
will be used. These defaults are given in the corresponding description of
the output commands in \fIChapter 2: Output Commands\fP.
The default name set is an empty set.
If no pipeline context is specified, the default pipeline context values will
be used. These defaults are given in \fIChapter 4: Pipeline Contexts\fP.
.LP
If a pipeline context, lookup table or name set resource is bound to the
renderer and then freed, inquiries on the renderer attributes will return
the value of
.PN PEXAlreadyFreed
for those particular resource identifiers.
.LP
.IN "immediate-mode"
.IN "retained-mode"
.IN "structure-mode"
Output commands sent to a renderer are rendered immediately.
Output commands can also be stored in a structure resource, and then the
structure traversed by a renderer.
In this way, renderers support both concepts of immediate-mode and
retained- or structure-mode graphics.
.LP
.PN PEXBeginRendering
is called to prepare a renderer for immediate-mode rendering.
.Pn ( PEXRenderNetwork
also implicitly performs a "begin rendering".)
The PEX server implementation may allow certain renderer attributes to be bound
only at the time of
.PN PEXBeginRendering
or at any time during the lifetime of the renderer resource.
.PN PEXGetRendererDynamics
can be called to obtain information about how renderer attributes are bound for
a particular PEX implementation.
.LP
If a drawable associated with a renderer is destroyed while a renderer is
rendering, an implicit
.PN PEXEndRendering
is performed by the server with the flush flag equal to
.PN False
in order to return the renderer to the
.PN PEXIdle
renderer state. All subsequent output and
traversal requests to the renderer are ignored and no error is generated.
.LP
If a drawable associated with a renderer is resized while a renderer is
rendering, an implicit
.PN PEXEndRendering
is performed by the server with the flush flag equal to
.PN False
in order to return the renderer to the
.PN PEXIdle
renderer state. All subsequent output and
traversal requests to the renderer are ignored until the next request to the
renderer to begin rendering or begin a pick operation and no error is generated.
.LP
If a drawable that is associated with a renderer is moved, exposed or occluded
while the renderer is rendering, the
server will continue to process output commands and requests using the new
drawable attributes until the rendering operation is explicitly or implicitly
terminated.
.LP
A renderer also manages the HLHSR buffer
needed for some HLHSR (hidden-line/hidden-surface removal) algorithms.
When the renderer begins rendering (either an explicit or implicit
.PN PEXBeginRendering )
and the HLHSR mode indicates z-buffering
should be performed, a z-buffer suitable for use with the specified drawable
is allocated, if necessary, and bound to the renderer. A new z-buffer is
allocated only if one does not already exist for the renderer, or if the
z-buffer currently bound to the renderer is not suitable for the specified
drawable.
If the z-buffer could not be allocated, an allocation error is generated and
the rendering is aborted. If the clear z flag is enabled, or if a new z-buffer
is allocated, then the z-buffer will be cleared to infinity in the region
specified by the renderer's current clip list. The value of infinity is
implementation-dependent. The z-buffer is not deallocated when an explicit
or implicit
.PN PEXEndRendering
occurs. The z-buffer remains bound to the renderer until the renderer is
freed or until a new one is allocated as described above. This means that
when the next
.PN PEXBeginRendering
occurs, the z-buffer will be re-used if possible. This allows the application
to control operations that require the z-buffer to remain intact between
rendering traversals and immediate-mode primitives. Some reasons why the
z-buffer may not be re-usable are the specification of a different drawable
or the previous drawable was resized.
.LP
Also, the renderer resource does not contain a double-buffer mode, whereas the
PHIGS workstation resource does. This does not preclude the use of the PEX
renderer resource in a double-buffered drawable. It is intended that
applications will use the \fIMulti-Buffer Extension\fP to X (MBX) for
double-buffering with a PEX renderer resource.
.LP
The next section describes the attributes of a renderer and their effects.
.NH 2
Renderer Attributes
.XS
\*(SN Renderer Attributes
.XE
.LP
Each renderer has the following attributes that are not directly modifiable
(via
.PN PEXChangeRenderer )
but are inquirable (via
.PN PEXGetRendererAttributes ):
.ID
renderer state
current path
.DE
.LP
The renderer state attribute is used to identify whether a renderer is currently
.PN PEXRendering ,
.PN PEXPicking ,
or
.PN PEXIdle .
Calling
.PN PEXBeginRendering
puts a renderer in the
.PN PEXRendering
state.
See \fIChapter 6: Renderer Picking\fP for more information about the picking
renderer state.
Output primitives or attributes are processed by a renderer only when the
renderer state is
.PN PEXRendering
or
.PN PEXPicking .
Calling
.PN PEXEndRendering
puts a renderer in the
.PN PEXIdle
state. Output primitives sent to an idle renderer are ignored.
.LP
.sp
.IN "current path"
.IN "path" "current"
The current path attribute contains a list of element references which
indicate paths for use by an application doing immediate-mode rendering,
or traversing structures via the "execute structure" output command.
Applications can use
.PN PEXBeginStructure
and
.PN PEXEndStructure
to maintain the current path during immediate-mode rendering.
The current path attribute is initialized to structure id 0 and offset 0.
.LP
.sp
Each renderer has the following attributes that are modifiable (via
.PN PEXChangeRenderer )
and inquirable (via
.PN PEXGetRendererAttributes ):
.ID
pipeline context
color approximation table
color table
depth cue table
edge bundle
interior bundle
light table
line bundle
marker bundle
pattern table
text bundle
text font table
view table
highlight inclusion
highlight exclusion
invisibility inclusion
invisibility exclusion
pick inclusion
pick exclusion
HLHSR mode
NPC subvolume
viewport
clip list
pick start path
background color
clear image flag
clear z flag
echo mode
.DE
.LP
.IN "pipeline context"
.IN "pipeline state"
Each renderer has a set of state information (the renderer's
pipeline state) that defines the behavior of the rendering pipeline. A
renderer's pipeline state contains all attributes stored in a PEX pipeline
context.
.PN PEXBeginRendering
copies into the renderer's pipeline state
the attributes in the pipeline context specified by the renderer's pipeline
context attribute. If the pipeline context attribute does not contain the
resource id of a valid pipeline context resource, the default values for
pipeline context attributes are copied instead.
.LP
Each time a renderer encounters an "execute structure" command, the renderer's
pipeline state is saved. When the called structure has been executed, this
saved pipeline state is restored. Note that only the pipeline state values
are saved and restored. The renderer state and current path attributes are not
saved and restored, since they are not modifiable from within a structure.
.LP
A renderer's pipeline state attributes are modified by output attribute
functions.
.LP
.sp
Each of the bundle and table attributes contains the resource id of the
specified type of
lookup table. If not set when the renderer is created, they are all NULL.
If they are NULL during the
rendering operation, the default attributes for the lookup table are used.
Pipeline attributes whose ASFs are set to
.PN PEXBundled
obtain their values from the edge bundle, interior bundle, line bundle,
marker bundle and text bundle tables.
.LP
The view table provides clipping information and the orientation and mapping
matrices. Indexed colors passed to the renderer are dereferenced using the
color table. The depth-cue table provides depth-cueing information.
The light table stores definitions for all light sources available to the
renderer. The color approximation table contains the rules and hints for
converting rendering pipeline colors into pixel values consistent with the
visual and color map for the drawable.
The text font table contains a list of X and PEX font resource identifiers.
See \fIChapter 3: Lookup Tables\fP for more details on the different types
of lookup tables.
.LP
.sp
.IN "filters"
.IN "highlight filter"
.IN "invisibility filter"
.IN "pick filter"
Each of the inclusion and exclusion attributes contains the resource id of a
name set resource which
is associated with each renderer as filters. If not set when the renderer is
created, these filters are NULL, which means they contain no names.
.LP
Highlighting is the process of drawing attention to an output primitive by
altering its visual attributes in an implementation-dependent way. Primitives
treated as invisible are simply not sent through the rendering
pipeline. Each filter consists of two name sets: an inclusion set and an
exclusion set. Another name set is maintained as part of the renderer's
pipeline state. Some output commands add and remove information from
the pipeline's name set.
.LP
For a primitive to be highlighted, the pipeline's name set must contain a
name (a 32-bit identifier) that also exists in the highlight inclusion name set. The
highlighted primitive pipeline's name set must not contain names found in the
highlight exclusion name set. For a primitive to be treated as invisible, the
pipeline's name set must contain a name that also exists in the invisibility
inclusion name set. The invisible primitive pipeline's name set must not
contain names also found in the invisibility exclusion name set. In other
words, to meet the filtering criteria for either highlighting or invisibility,
the intersection of the name set with the inclusion set must not be empty, and
the intersection of the name set with the exclusion set must be the empty set.
.LP
See \fIChapter 6: Renderer Picking\fP for information on the pick filters.
.LP
.sp
The default HLHSR mode is
.PN PEXHLHSROff.
Each renderer maintains an HLHSR mode indicating the hidden line and hidden
surface algorithm used. Each renderer also maintains an HLHSR buffer used in
the hidden line and hidden surface computations. When
.PN PEXBeginRendering
is
called, the HLHSR buffer is initialized based on the current value of the HLHSR
mode.
When
.PN PEXEndRendering
is called, if the flush flag is
.PN True ,
unprocessed output primitives are rendered using the chosen HLHSR algorithm.
If the flush flag is
.PN False ,
unprocessed output primitives are discarded.
.LP
.sp
.IN "NPC subvolume"
.IN "viewport"
.IN "clip list"
The NPC subvolume attribute contains
the normalized projection coordinates for the sub-volume space that is mapped
to the viewport.
The default NPC subvolume is [0.0, 1.0] in all three dimensions, x, y, z.
.LP
The viewport attribute describes the area within the drawable in which rendering
may appear. The viewport coordinates are specified in device coordinates, which
have an x,y offset (in pixels) from the lower-left corner of the drawable.
Note that the y-component is the reverse of the X window system coordinate
system.
It is permissible to specify a viewport with boundaries outside of the drawable.
Geometry that is mapped to values outside the drawable is clipped. Viewport z
values must be in the range of 0.0 to 1.0, where z=0.0 maps to the
device-coordinate z value representing objects that are furthest from the
viewing position, and z=1.0 maps to the device-coordinate value representing
objects that are closest to the viewing position. Depending on the dynamics of
the viewport attribute (see
.PN PEXGetRendererDynamics ),
the values that define a viewport may be bound at any time, or they may take
effect only at the time of
.PN PEXBeginRendering .
Whenever the viewport values are bound, the viewport's use drawable flag is
examined first. If it is set to
.PN True ,
the viewport width and height are obtained from the drawable's current width
and height and the viewport z values are obtained from the values specified
in the viewport structure. If the use drawable flag is
.PN False ,
the viewport width, height and z values are all set to the values in the
viewport structure. The viewport is then set to the largest rectangle, anchored
at the lower-left corner of the drawable, that achieves an isotropic mapping to
the renderer's NPC subvolume. The viewport will remain in the same position
relative to the lower-left hand corner of the drawable after a resize event
has occurred.
The default viewport size is implementation-dependent, and the default
use drawable flag is
.PN True .
.LP
The clip list contains a list of rectangles in device coordinates that define
the portions of the drawable in which rendering is allowed. If the list is
empty, the renderer will render to the entire drawable area. If the list
is not empty, only the area within the rectangles will be affected during
rendering. The rectangles must be non-overlapping or the result is undefined
and implementation-dependent. The rectangles in the clip list are defined
in device coordinates. (0,0) is the lower left corner of the
drawable and the xmax and ymax values are inclusive. These rectangles will
remain in the same position relative to the lower left
corner of the drawable after a resize has occurred. Note, if a z-buffering
algorithm is used for HLHSR, only those z-values associated with pixels that
are within the defined area of the clip list will be modified.
.LP
.sp
The pick start path is used as the starting path for "pick all".
See \fIChapter 6: Renderer Picking\fP for more information.
.LP
.sp
The background color is used to clear the drawable area when an explicit or
implicit
.PN PEXBeginRendering
occurs. The drawable will be cleared only if the clear image flag is
enabled. If the clear image flag is disabled, the drawable will not be cleared.
The default value for the clear image flag is
.PN False .
The clip list will be taken into account when clearing the drawable.
The initial index to the color approximation table is used to
map the color to a device pixel value.
.LP
.sp
The clear z flag indicates whether the z-buffer should be cleared to infinity
at the start of rendering. The value of infinity is implementation-dependent.
The default value for the clear image flag is
.PN True .
The clip list will be taken into account when clearing the z-buffer. This
attribute is ignored if the HLHSR mode is not one that requires a z-buffer.
.LP
.sp
The echo mode indicates whether rendered primitives should be echoed, unechoed
or rendered normally. The method used for echoing and unechoing primitives
is implementation-dependent and there is no guarantee that the method will
preserve temporal priority. Echoing takes precedence over highlighting.
There is a standard PEX escape for setting an echo color that will provide
more control over the echo method used, if the escape is supported. (See
.PN PEXSetEchoColor .)
.NH 2
Common Data Structures
.XS
\*(SN Common Data Structures
.XE
.LP
Below are the data structures used that are common to more than one function
described in this section.
.ID
.Co
/* renderer attributes */
.sp
typedef struct {
PEXPipelineContext pipeline_context;
PEXStructurePath current_path;
PEXLookupTable marker_bundle;
PEXLookupTable text_bundle;
PEXLookupTable line_bundle;
PEXLookupTable interior_bundle;
PEXLookupTable edge_bundle;
PEXLookupTable view_table;
PEXLookupTable color_table;
PEXLookupTable depth_cue_table;
PEXLookupTable light_table;
PEXLookupTable color_approx_table;
PEXLookupTable pattern_table;
PEXLookupTable text_font_table;
PEXNameSet highlight_incl;
PEXNameSet highlight_excl;
PEXNameSet invisibility_incl;
PEXNameSet invisibility_excl;
int renderer_state;
PEXEnumTypeIndex hlhsr_mode; /* PEXHLHSROff, PEXHLHSRZBuffer, */
/* PEXHLHSRPainters, PEXHLHSRScanline, */
/* PEXHLHSRHiddenLineOnly, */
/* PEXHLHSRZBufferID */
PEXNPCSubVolume npc_subvolume;
PEXViewport viewport;
PEXListOfClipRect clip_list;
PEXNameSet pick_incl;
PEXNameSet pick_excl;
PEXStructurePath pick_start_path;
PEXColorSpecifier background_color;
Bool clear_image; /* True or False */
Bool clear_z; /* True or False */
int echo_mode; /* PEXNoEcho, PEXEcho, PEXUnEcho */
} PEXRendererAttributes;
.sp
typedef XID PEXPipelineContext;
typedef XID PEXLookupTable;
typedef XID PEXNameSet;
typedef short PEXEnumTypeIndex;
.sp
typedef struct {
unsigned long count; /* number of elements */
PEXElementRef *elements;
} PEXStructurePath;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.sp
typedef XID PEXStructure;
.sp
typedef struct {
PEXCoord min;
PEXCoord max;
} PEXNPCSubVolume;
.sp
typedef struct {
float x;
float y;
float z;
} PEXCoord;
.sp
typedef struct {
PEXDeviceCoord min;
PEXDeviceCoord max;
PEXSwitch use_drawable; /* True or False */
unsigned char reserved[3];
} PEXViewport;
.sp
typedef struct {
short x;
short y;
float z;
} PEXDeviceCoord;
.sp
typedef unsigned char PEXSwitch;
.sp
typedef struct {
unsigned short count; /* number of device rectangles */
PEXDeviceRect *rectangles;
} PEXListOfClipRect;
.sp
typedef struct {
short xmin;
short ymin;
short xmax;
short ymax;
} PEXDeviceRect;
.sp
typedef struct {
PEXColorType type; /* PEXColorTypeIndexed, PEXColorTypeRGB, */
/* PEXColorTypeCIE, PEXColorTypeHSV, */
/* PEXColorTypeHLS, PEXColorTypeRGB8, */
/* PEXColorTypeRGB16 */
unsigned short reserved;
PEXColor value;
} PEXColorSpecifier;
.sp
typedef short PEXColorType;
.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;
.ft P
.DE
.bp
.XS
Function Descriptions
.XE
.SH
PEXAccumulateState - Accumulate Rendering Pipeline State
.XS
PEXAccumulateState
.XE
.IN "PEXAccumulateState" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXAccumulateState\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, unsigned long \fIcount\fP\^, PEXElementRef *\fIelements\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 resource.
.IP \fIcount\fP 1i
The number of elements.
.IP \fIelements\fP 1i
A pointer to the structure element reference path.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function accumulates the state that would be in effect if a traversal were
done to the element specified in the path. If the renderer state is
.PN PEXIdle ,
the request is ignored.
.LP
The accumulation of rendering pipeline state begins with the current pipeline
attributes. A linear traversal down the specified path is then made and
the structure elements that lie along the specified path are examined in order.
Any element that contains an output command that would modify the pipeline
state (i.e. output attributes) is sent to the renderer for processing. All
other output commands (i.e. output primitives and structure output commands)
are skipped. The traversal is flat meaning that the current pipeline attributes
will not be saved when a structure in the path is executed.
However, the current path offset is incremented for each output command that
is encountered during the state accumulation.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
typedef XID PEXStructure;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXPath\fP 1i
The specified path is invalid.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXBeginRendering ,
.PN PEXCreateStructure ,
.PN PEXCreateRenderer
.RE
.bp
.SH
PEXBeginRendering - Begin Rendering
.XS
PEXBeginRendering
.XE
.IN "PEXBeginRendering" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXBeginRendering\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\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 \fIrenderer\fP 1i
The resource identifier of a renderer.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function initializes the specified renderer and binds the
specified drawable to it. Subsequent output primitive commands
sent to renderer produce output to the specified drawable.
The renderer's pipeline state is initialized to the values
in its pipeline context, or to default values
if there is no pipeline context. This function causes the
renderer's renderer state to be set to
.PN PEXRendering
and its
current path to be set to <0,0>. The renderer's
HLHSR mode is used to initialize hidden surface computations.
(For example, the z-buffer is initialized if the HLHSR mode is
set to
.PN PEXHLHSRZBuffer
or
.PN PEXHLHSRZBufferID .)
.LP
If the renderer's state is
.PN PEXRendering
or
.PN PEXPicking
when this request is received, an implicit "end rendering or picking"
request is performed before the "begin rendering" request is executed.
Output commands received by a renderer are ignored if the state is
not
.PN PEXRendering
or
.PN PEXPicking .
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate the resource.
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadMatch\fP 1i
The specified drawable is unsupported, or the specified renderer resource was
not created with a compatible drawable.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXRendererState\fP 1i
The specified renderer was in an invalid state.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer ,
.PN PEXEndRendering
.RE
.bp
.SH
PEXBeginStructure - Save Rendering Pipeline State
.XS
PEXBeginStructure
.XE
.IN "PEXBeginStructure" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXBeginStructure\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, long \fIstructure_id\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 \fIstructure_id\fP 1i
A value to be used as an application-specified structure identifier.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
Application programs can use this function to simulate the
effects of the execute structure output command. This request
saves the rendering pipeline attributes in the specified
renderer. This request also increments the element offset
of the last entry in the renderer's current path.
The function then adds the structure id and an element offset
of zero to the renderer's current path.
.LP
The rendering pipeline's global transform attribute is set to the
matrix computed by concatenating the current local transform
and current global transform matrices. The local transform
matrix is then set to the identity matrix.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXEndStructure ,
.PN PEXExecuteStructure ,
.PN PEXCreateRenderer
.RE
.bp
.SH
PEXChangeRenderer - Change Renderer Attributes
.XS
PEXChangeRenderer
.XE
.IN "PEXChangeRenderer" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXChangeRenderer\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, unsigned long \fIvalue_mask\fP\^, PEXRendererAttributes *\fIvalues\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 the renderer.
.IP \fIvalue_mask\fP 1i
A mask indicating the renderer attributes to be changed.
.IP \fIvalues\fP 1i
A pointer to new values for the renderer attributes.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function modifies attributes of the specified renderer resource.
The value mask indicates the attribute values to be modified.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXRAPipelineContext
.PN PEXRAMarkerBundle
.PN PEXRATextBundle
.PN PEXRALineBundle
.PN PEXRAInteriorBundle
.PN PEXRAEdgeBundle
.PN PEXRAViewTable
.PN PEXRAColorTable
.PN PEXRADepthCueTable
.PN PEXRALightTable
.PN PEXRAColorApproxTable
.PN PEXRAPatternTable
.PN PEXRATextFontTable
.PN PEXRAHighlightIncl
.PN PEXRAHighlightExcl
.PN PEXRAInvisibilityIncl
.PN PEXRAInvisibilityExcl
.PN PEXRAHLHSRMode
.PN PEXRANPCSubVolume
.PN PEXRAViewport
.PN PEXRAClipList
.PN PEXRAPickIncl
.PN PEXRAPickExcl
.PN PEXRAPickStartPath
.PN PEXRABackgroundColor
.PN PEXRAClearImage
.PN PEXRAClearZ
.PN PEXRAEchoMode
.DE
.LP
Note that the renderer's current path and renderer state
attributes cannot be set explicitly using this function.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
.sp
See also the \fICommon Data Structures\f section.
.DE
.SH
Errors
.RS
.IP \fIBadMatch\fP 1i
The specified lookup table resource was not created with a drawable compatible
with the drawable used to create the renderer resource.
.IP \fIBadPEXLookupTable\fP 1i
The specified lookup table resource identifier is invalid.
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.IP \fIBadPEXPipelineContext\fP 1i
The specified pipeline context resource identifier is invalid.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadValue\fP 1i
A specified value is out of range, or an invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer ,
.PN PEXGetRendererAttributes ,
.PN PEXGetRendererDynamics
.RE
.bp
.SH
PEXCreateRenderer - Create Renderer
.XS
PEXCreateRenderer
.XE
.IN "PEXCreateRenderer" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXRenderer PEXCreateRenderer\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, unsigned long \fIvalue_mask\fP\^, PEXRendererAttributes *\fIvalues\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 \fIvalue_mask\fP 1i
A mask indicating the attribute values specified.
.IP \fIvalues\fP 1i
A pointer to values used to override default values in the new renderer resource.
.RE
.SH
Returns
.RS
.LP
The resource identifier of the newly-created renderer resource.
.RE
.SH
Description
.RS
.LP
This function creates a renderer and returns the resource identifier of the
newly-created renderer resource.
The value mask indicates which attribute values are specified.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXRAPipelineContext
.PN PEXRAMarkerBundle
.PN PEXRATextBundle
.PN PEXRALineBundle
.PN PEXRAInteriorBundle
.PN PEXRAEdgeBundle
.PN PEXRAViewTable
.PN PEXRAColorTable
.PN PEXRADepthCueTable
.PN PEXRALightTable
.PN PEXRAColorApproxTable
.PN PEXRAPatternTable
.PN PEXRATextFontTable
.PN PEXRAHighlightIncl
.PN PEXRAHighlightExcl
.PN PEXRAInvisibilityIncl
.PN PEXRAInvisibilityExcl
.PN PEXRAHLHSRMode
.PN PEXRANPCSubVolume
.PN PEXRAViewport
.PN PEXRAClipList
.PN PEXRAPickIncl
.PN PEXRAPickExcl
.PN PEXRAPickStartPath
.PN PEXRABackgroundColor
.PN PEXRAClearImage
.PN PEXRAClearZ
.PN PEXRAEchoMode
.DE
.LP
Fields not explicitly set have default values (see the
beginning of the chapter).
The renderer resource may only be used in conjunction
with drawables that have the same root and depth as specified drawable.
.LP
Note that the renderer's current path and renderer state
attributes cannot be set explicitly using this function.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
.sp
See also the \fICommon Data Structures\f section.
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate the resource.
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadMatch\fP 1i
The specified drawable is unsupported, or the specified lookup table resource
was not created with a drawable compatible with the specified drawable.
.IP \fIBadPEXLookupTable\fP 1i
The specified lookup table resource identifier is invalid.
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.IP \fIBadPEXPipelineContext\fP 1i
The specified pipeline context resource identifier is invalid.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadValue\fP 1i
A specified value is out of range, or an invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXFreeRenderer
.RE
.bp
.SH
PEXEndRendering - End Rendering
.XS
PEXEndRendering
.XE
.IN "PEXEndRendering" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXEndRendering\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, int \fIflush\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 \fIflush\fP 1i
.PN True
or
.PN False
- specifying whether any pending output for renderer is to be rendered onto its
associated drawable.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function terminates rendering on the specified renderer resource.
If flush is
.PN True ,
pending output is rendered onto its
associated drawable. If flush is
.PN False ,
pending output is discarded.
In either case, the renderer state
is set to
.PN PEXIdle .
If the renderer state is
.PN PEXIdle ,
the request is ignored.
If the renderer state is
.PN PEXPicking ,
then an error is generated.
.RE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXRendererState\fP 1i
The specified renderer was in an invalid state.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer ,
.PN PEXBeginRendering
.RE
.bp
.SH
PEXEndStructure - Restore Rendering Pipeline State
.XS
PEXEndStructure
.XE
.IN "PEXEndStructure" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXEndStructure\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\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 the renderer.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
Application programs can use this function to simulate the side effects
of the return from an "execute structure" output command. This request
restores the last-saved rendering pipeline attributes in renderer.
This request also removes the last element reference in the renderer's
current path. Subsequent output commands cause the element
offset of the element reference at the end of the list to be
incremented.
.RE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXRendererState\fP 1i
There is no matching begin structure.
.RE
.SH
See Also
.RS
.LP
.PN PEXBeginStructure ,
.PN PEXExecuteStructure ,
.PN PEXCreateRenderer
.RE
.bp
.SH
PEXFreeRenderer - Free Renderer
.XS
PEXFreeRenderer
.XE
.IN "PEXFreeRenderer" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeRenderer\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\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 the renderer.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deletes the renderer resource specified by renderer and
frees the memory associated with it.
.RE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer
.RE
.bp
.SH
PEXFreeRendererAttributes - Free Storage Returned by PEXGetRendererAttributes
.XS
PEXFreeRendererAttributes
.XE
.IN "PEXFreeRendererAttributes" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeRendererAttributes\^(\^PEXRendererAttributes *\fIvalues\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIvalues\fP 1i
A pointer to the renderer attribute values.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deallocates memory returned by
.PN PEXGetRendererAttributes .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXGetRendererAttributes
.RE
.bp
.SH
PEXGetRendererAttributes - Get Renderer Attribute Values
.XS
PEXGetRendererAttributes
.XE
.IN "PEXGetRendererAttributes" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXRendererAttributes *PEXGetRendererAttributes\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, unsigned long \fIvalue_mask\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 the renderer to be queried.
.IP \fIvalue_mask\fP 1i
A mask indicating attributes to be returned from the renderer.
.RE
.SH
Returns
.RS
.LP
A pointer to the renderer attribute values; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns attribute values from the specified renderer resource.
The value mask indicates the attribute values to be returned.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXRAPipelineContext
.PN PEXRACurrentPath
.PN PEXRAMarkerBundle
.PN PEXRATextBundle
.PN PEXRALineBundle
.PN PEXRAInteriorBundle
.PN PEXRAEdgeBundle
.PN PEXRAViewTable
.PN PEXRAColorTable
.PN PEXRADepthCueTable
.PN PEXRALightTable
.PN PEXRAColorApproxTable
.PN PEXRAPatternTable
.PN PEXRATextFontTable
.PN PEXRAHighlightIncl
.PN PEXRAHighlightExcl
.PN PEXRAInvisibilityIncl
.PN PEXRAInvisibilityExcl
.PN PEXRARendererState
.PN PEXRAHLHSRMode
.PN PEXRANPCSubVolume
.PN PEXRAViewport
.PN PEXRAClipList
.PN PEXRAPickIncl
.PN PEXRAPickExcl
.PN PEXRAPickStartPath
.PN PEXRABackgroundColor
.PN PEXRAClearImage
.PN PEXRAClearZ
.PN PEXRAEchoMode
.DE
.LP
PEXlib allocates the memory for the returned renderer attribute values.
.PN PEXFreeRendererAttributes
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
.sp
See also the \fICommon Data Structures\f section.
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadValue\fP 1i
An invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer ,
.PN PEXChangeRenderer ,
.PN PEXGetRendererDynamics ,
.br
.PN PEXFreeRendererAttributes
.RE
.bp
.SH
PEXGetRendererDynamics - Get Renderer Attribute Modification Dynamics
.XS
PEXGetRendererDynamics
.XE
.IN "PEXGetRendererDynamics" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXGetRendererDynamics\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, unsigned long *\fItables_return\fP\^, unsigned long *\fIname_sets_return\fP\^, unsigned long *\fIattributes_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 \fIrenderer\fP 1i
The resource identifier of the renderer.
.IP \fItables_return\fP 1i
Returns a mask describing dynamics of lookup tables associated with the renderer.
.IP \fIname_sets_return\fP 1i
Returns a mask describing dynamics of name sets associated with the renderer.
.IP \fIattributes_return\fP 1i
Returns a mask describing dynamics of other attributes associated with the renderer.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful, non-zero otherwise.
.RE
.SH
Description
.RS
.LP
This function returns the modification dynamics for all of the
attributes of the specified renderer resource. Each bit, in the
returned bitmasks, indicates the dynamics for a particular renderer attribute.
For each bit, a value of
.PN PEXDynamic
indicates that the
specified attribute may be modified at any time, and the change will
take place immediately. A value of
.PN PEXNotDynamic
indicates that the specified
attribute may not be modified dynamically. In this case, the change
is "pending" and will take effect at the next explicit or implicit
.PN PEXBeginRendering .
.LP
The pipeline context, pick start path, background color, clear image and clear
z renderer attributes all take effect only at the time of "begin rendering or
picking", and so do not have dynamics associated with them.
.LP
The bits in the tables bitmask are accessed with the following constants:
.ID
.PN PEXRDTMarkerBundle
.PN PEXRDTTextBundle
.PN PEXRDTLineBundle
.PN PEXRDTInteriorBundle
.PN PEXRDTEdgeBundle
.PN PEXRDTViewTable
.PN PEXRDTColorTable
.PN PEXRDTDepthCueTable
.PN PEXRDTLightTable
.PN PEXRDTColorApproxTable
.PN PEXRDTPatternTable
.PN PEXRDTTextFontTable
.PN PEXRDTMarkerBundleContents
.PN PEXRDTTextBundleContents
.PN PEXRDTLineBundleContents
.PN PEXRDTInteriorBundleContents
.PN PEXRDTEdgeBundleContents
.PN PEXRDTViewTableContents
.PN PEXRDTColorTableContents
.PN PEXRDTDepthCueTableContents
.PN PEXRDTLightTableContents
.PN PEXRDTColorApproxContents
.PN PEXRDTPatternTableContents
.PN PEXRDTTextFontTableContents
.DE
The bits in the name sets bitmask are accessed with the following constants:
.ID
.PN PEXRDNHighlightNameSet
.PN PEXRDNInvisibilityNameSet
.PN PEXRDNPickNameSet
.PN PEXRDNHighlightNameSetContents
.PN PEXRDNInvisibilityNameSetContents
.PN PEXRDNPickNameSetContents
.DE
The bits in the attributes bitmask are accessed with the following constants:
.ID
.PN PEXRDAHLHSRMode
.PN PEXRDANPCSubVolume
.PN PEXRDAViewport
.PN PEXRDAClipList
.PN PEXRDAEchoMode
.DE
.RE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateRenderer ,
.PN PEXChangeRenderer ,
.PN PEXBeginRendering
.RE
.bp
.SH
PEXRenderElements - Render Elements
.XS
PEXRenderElements
.XE
.IN "PEXRenderElements" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXRenderElements\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, PEXStructure \fIstructure\fP\^, int \fIwhence1\fP\^, long \fIoffset1\fP\^, int \fIwhence2\fP\^, long \fIoffset2\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 resource.
.IP \fIstructure\fP 1i
The resource identifier of a structure resource.
.IP \fIwhence1\fP 1i
A value specifying, with offset1, the first limit of the element range
.Pn ( PEXBeginning ,
.PN PEXCurrent
.PN PEXEnd ).
.IP \fIoffset1\fP 1i
An offset from whence1 specifying the first limit of the element range.
.IP \fIwhence2\fP 1i
A value specifying, with offset2, the second limit of the element range
.Pn ( PEXBeginning ,
.PN PEXCurrent
.PN PEXEnd ).
.IP \fIoffset2\fP 1i
An offset from whence2 specifying the second limit of the element range.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function processes all output commands in the specified element range
of the specified structure.
Output primitives in structure are
rendered using the specified renderer. If the renderer is not rendering or
picking, the request will be ignored. Structures referenced
through execute structure output commands are also processed.
.LP
The first limit of the range is defined by whence1 and offset1 and the second
limit of the range is defined by whence2 and offset2.
The whence values describe how to interpret the corresponding offset.
.PN PEXBeginning
means the element position is the value of offset (i.e. the offset from the
beginning of the structure).
.PN PEXCurrent
means the element position is the value of the current element pointer position
plus the value of offset (i.e. the offset from the current element pointer).
.PN PEXEnd
means the element position is the value of the last element position in the
structure plus the value of offset (i.e. the offset from the end of the structure).
Offsets can be negative values.
If after computing an element position, it
is less than zero, the position will be set to zero.
If after computing an element position, it
is greater than the number of elements in the structure, it will be set to
the last structure element in the structure.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
typedef XID PEXStructure;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXStructure\fP 1i
The specified structure resource identifier is invalid.
.IP \fIBadValue\fP 1i
The specified value for whence was invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXBeginRendering ,
.PN PEXCreateStructure ,
.PN PEXCreateRenderer
.RE
.bp
.SH
PEXRenderNetwork - Render Network
.XS
PEXRenderNetwork
.XE
.IN "PEXRenderNetwork" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXRenderNetwork\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\fP\^, PEXStructure \fIstructure\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 \fIrenderer\fP 1i
The resource identifier of a renderer resource.
.IP \fIstructure\fP 1i
The resource identifier of a structure resource.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function processes all output commands stored in structure using
the specified renderer. Output primitives in structure are
rendered to the specified drawable. Structures referenced
through execute structure output commands are also processed.
This request effectively performs an implicit
.PN PEXBeginRendering
before the traversal of the specified structure network and
an implicit
.PN PEXEndRendering ,
with a flush value of
.PN True ,
after the traversal.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXRenderer;
typedef XID PEXStructure;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate resources necessary to complete request.
.IP \fIBadDrawable\fP 1i
The specified drawable resource identifier is invalid.
.IP \fIBadMatch\fP 1i
The specified drawable is unsupported, or the specified renderer resource was
not created with a compatible drawable.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXRendererState\fP 1i
The specified renderer was in an invalid state.
.IP \fIBadPEXStructure\fP 1i
The specified structure resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXExecuteStructure ,
.PN PEXBeginRendering ,
.PN PEXEndRendering ,
.br
.PN PEXCreateStructure ,
.PN PEXCreateRenderer
.RE
.bp