Overview of View Model Derived Data

XGL defines a conceptual view model consisting of a number of coordinate systems in which an application can specify certain operations. These coordinate systems are Model Coordinates (MC), World Coordinates (WC), Virtual Device Coordinates (VDC), and Device Coordinates (DC). Examples of the usage of coordinate systems in the 3D view model include specification of geometry in MC, lights and model clip planes in WC, view clip planes and depth cue reference planes in VDC, and the pick aperture in DC. The coordinate systems are related by a sequence of transformations. The Local Model and Global Model Transforms are concatenated to form the Model Transform, which maps geometry from MC to WC. The View Transform maps geometry from WC to VDC. The VDC map, VDC orientation, VDC window, DC orientation, DC viewport, and jitter offset collectively define a mapping between VDC and DC. This view model is conceptual because an application can think of an operation as occurring in the coordinate system where it is specified, but a pipeline actually may implement the operation in another coordinate system for improved performance as long as the results are equivalent.

XGL provides a facility to assist pipelines with implementation of the view model's operations. The facility is named view model derived data or simply derived data. Derived data maintains a cache of items derived from a Context's view model attributes. The derived items include Transforms for mapping geometry between coordinate systems as well as items in various coordinate systems such as the view clip bounds, lights, eye positions or eye vectors, model clip planes, and depth cue reference planes. For example, derived data calculates the VDC-to-DC Transform from the Context attributes for the VDC map, VDC orientation, VDC window, DC viewport, and jitter offset, and the Device attribute for DC orientation. In turn, the MC-to-DC Transform is the concatenation of the Model, View, and VDC-to-DC Transforms. This illustrates that a derived item can depend on only API attributes, on only derived items, or on a combination of both.

---

Note - Pipelines have the option of not using the derived data facility if and only if the pipeline never falls back on the software pipeline. If the pipeline does fall back on the software pipeline, for example for the processing of annotation text, markers, 2D circles and arcs, or NURBS curves and surfaces, it must use derived data. See "Entry of Geometry from Multiple Coordinate Systems" on page 126 for information.

---

Derived data implements a large collection of items. The items were selected by analyzing the requirements of a theoretical pipeline and by looking at the needs of several graphics devices. The theoretical pipeline employs two coordinate systems that are not exposed at the API level: Lighting Coordinates (LC)¹ and Clipping Coordinates (CC). It also performs operations in several coordinate systems; for example, model clipping operations occur in four coordinate systems so the clip planes are needed in each of these.

Derived data is efficient and easy for device pipelines to use. In particular, derived data is designed for hardware devices that retain the state of the view model such as matrices and clip planes. These device pipelines need to know when a derived item has changed so that the pipeline can reload the item into the device. The calculations are transparent to pipelines, and the design avoids redundancies and extraneous evaluation of derived data items.

The XGL software pipeline also uses derived data. The only difference between many device pipelines and the software pipeline is that the latter does not retain state so it does not need to be informed of changes to derived items. The software pipeline simply gets a derived item as needed, but this does not necessarily cause re-evaluation since the item may be valid already.

Design Goals of Derived Data

The design goals of derived data are:

1. Support geometry entering LI-1 from other coordinate systems (in addition to Model Coordinates) with a simple interface for pipelines.

2. Provide a fast test to inform a pipeline of changes to derived items of concern to that pipeline and minimize data transfer to devices that retain state.

3. Defer calculation of a derived item until a pipeline requests that item, and avoid redundant calculations.

---

1. For information on Lighting Coordinates, see Salim S. Abi-Ezzi and Michael J. Wozny, "Factoring a Homogeneous Transformation for a More Efficient Graphics Pipeline," Computer Graphics Forum, North-Holland, Vol. 9, 1990, pp. 245-255.

Entry of Geometry from Multiple Coordinate Systems

The need to support entry of geometry to LI-1 primitives from coordinate systems other than Model Coordinates greatly complicates the design of derived data. As an example, consider the NURBS surface code in the software pipeline. The software pipeline's 3D LI-1 NURBS surface primitive takes control points and knots in MC and produces polylines, triangles, and quadrilateral meshes in LC, CC, and DC. This geometry enters the LI-1 primitives of a number of devices. Rather than force device pipeline developers to produce an LI-1 primitive for each coordinate system from which geometry can enter, derived data "fools" pipelines into "thinking" that they are always getting geometry in MC, even when geometry enters from another coordinate system.

Consider a simple example of 2D annotation text in the software pipeline. The application passes a character string and a reference point to XGL at the API level. If the device pipeline cannot handle annotation text at LI-1, the software pipeline transforms the reference point from MC to VDC, checks that the point is within the view clip bounds, and constructs a polyline description of the text based on information stored in font files. Derived data provides functions so that a primitive can push the current coordinate system onto a stack and set it to another: VDC in the case of annotation text. Then the primitive can call LI-1 multipolyline. When the multipolyline function requests a transform, for example the MC-to-CC Transform, derived data returns the appropriate transform for the current coordinate system: in this case, the VDC-to-CC Transform. The LI-1 multipolyline primitive doesn't need to be aware that the current coordinate system is VDC instead of MC. When control returns from the LI-1 polyline primitive to the software pipeline's LI-1 annotation text primitive, the latter can pop the coordinate system to restore the original one (which should be MC).

For certain primitives, the software pipeline uses derived data to transform the geometry through part of the pipeline before changing the coordinate system and passing the partially processed geometry on to another LI-1 primitive. An important corollary is that if a device pipeline ever falls back on the software pipeline, the device pipeline must use derived data. If a device pipeline never falls back on the software pipeline, then the device pipeline has the option of using or not using derived data.

Changes to Derived Items

Derived data has a fast test to allow pipelines to determine when at least one derived item has changed since the last time that the pipeline accessed any item. This test especially benefits pipelines whose devices retain view model state. A pipeline can express concern about changes to a specified set of items. This allows pipelines to filter out irrelevant changes, which is important because derived data consists of a large number of items and pipelines typically need only a few items.

A derived item can change as a result of an application changing a view model attribute. A derived item may depend directly or indirectly on that attribute. An attribute change invalidates some previously calculated items.

A change to a derived item can also be the result of a change in the current coordinate system. In the annotation text example in the previous section, derived data returns the VDC-to-CC Transform when the current coordinate system is VDC and the pipeline requests the MC-to-CC Transform. If the previous coordinate system was MC when the pipeline requested the MC-to-CC Transform, the actual MC-to-CC matrix would have been loaded into the device. The change in coordinate system from MC to VDC means that the pipeline needs to load a difference matrix to achieve the MC-to-CC mapping. Hence, a change in the current coordinate system results in changes to derived items even though no items have been invalidated, as in the case of API attribute changes. A pipeline does not need to be aware of the reason for a change in an item. Derived data simply informs the pipeline when an item must be reloaded into a device that retains state.

In addition to the fast test for the whole set of specified items, derived data has a test for each individual item. If the fast test is positive, then at least one of the specified items has changed. The pipeline then needs to check each of the specified items for changes. The pipeline should get a changed item from derived data and reload that state into the device.

The fast test never misses a change to a derived item resulting from a change to an API view model attribute or a change in the current coordinate system. However, the test may be falsely positive because changes to items resulting from changes in the coordinate system cannot be determined quickly with complete accuracy. Hence, the test is overly cautious. Fortunately, the tests for the individual items are quick and completely accurate so derived data eliminates extraneous transfers of state to devices. Since pipelines typically need only a few items, the overhead is not large.

Deferred Calculation

Derived data defers calculations until a pipeline requests a particular item. Each item is a node in an acyclic directed graph of dependencies with API view model attributes at the bottom. When a pipeline requests a particular item, derived data descends the graph until it finds valid items (API view model attributes are always valid) and ascends the graph as it performs calculations until it reaches the requested item. Consequently, if that item is already valid, then no calculation is required. A pipeline's request for a particular item is the trigger for any necessary calculations.

Deferred evaluation has the advantage of eliminating unnecessary calculations. Derived data calculates an item only when a pipeline explicitly requests that item (or one that depends on it) and that item needs to be reloaded into a device because of a change to a relevant API attribute or a change in the current coordinate system. A pipeline is not penalized with expensive calculations if it does not use derived data.

Derived Data Items

Derived data maintains transformations between coordinate systems and maintains a variety of other items that change when Context or Device attributes change.

Coordinate Systems and Transforms

The majority of items in derived data are Transforms for mapping geometry between pairs of coordinate systems. Each Transform has a name of the form "AcToBc" for transforming points from the "A" coordinate system to the "B" coordinate system. For 3D, the "AcToBc" Transform can be used to transform normal and direction vectors from BC to AC by applying these vectors as 3.1 column vectors to the 3.3 upper-left submatrix of AcToBc's 4.4 matrix.

Table 6-1 lists the coordinate systems that derived data supports in 2D.

Table 6-1

Mnemonic	Name
MC	Model Coordinates
GMC	Global Model Coordinates
WC	World Coordinates
VDC	Virtual Device Coordinates
CC	Clipping Coordinates
DC	Device Coordinates

Table 6-2 lists the coordinate systems that derived data supports in 3D.

Table 6-2

Mnemonic	Name
MC	Model Coordinates
GMC	Global Model Coordinates
WC	World Coordinates
LC	Lighting Coordinates
IC	Intermediate Coordinates
VDC	Virtual Device Coordinates
CC	Clipping Coordinates
DC	Device Coordinates

---

Note - GMC is the coordinate system after the Local Model Transform and before the Global Model Transform.

---

In 3D the view-clipping volume in Clipping Coordinates has the boundaries [-1,1] . [-1,1] . [-1,1] with the clip planes at the boundaries. The x-, y-, and z-axes are parallel to those in VDC and DC. The orientation always has the x-axis pointing right, the y-axis pointing up, and the z-axis pointing toward. This is independent of the orientations of VDC (specified by the application) and DC (specified by the device). 2D is similar except that there is no z-axis.

In 3D the View Transform often can be factored into the following form:

V = EQG

where E is Euclidean (meaning that it preserves the distances between points and the angle between direction vectors), and Q and G are sparse. See the paper by Abi-Ezzi and Wozny for a full description of the decomposition and properties of the coordinate systems. The coordinate system between E and Q is called Lighting Coordinates, and the one between Q and G is called Intermediate Coordinates. The software pipeline NURBS primitives use these coordinate systems, and device pipelines may benefit from them as well.

Other Derived Items

Derived data maintains a number of items other than Transforms. The view clip bounds in MC, VDC, CC, and DC, and the viewport in DC are available to both 2D and 3D pipelines. 3D pipelines can also access the lights in MC and LC, the eye vector or position in MC, LC, VDC, and CC, a flag indicating when the view projection is parallel as opposed to perspective, the model-clip planes in MC, LC, CC, and DC, the depth cue planes in CC and DC, and a flag indicating when the View Transform can be factored. Table 6-3 lists the items other than Transforms that derived data maintains.

Table 6-3

Mnemonic	Name
VclipBoundsMC	View-clip bounds in MC
VclipBoundsVdc	View-clip bounds in VDC
VclipBoundsCc	View-clip bounds in CC
VclipBoundsDc	View-clip bounds in DC
ViewportDc	Viewport in DC
LightsMc	Lights in MC
LightsLc	Lights in LC
EyeMc	Eye vector or point in MC
EyeLc	Eye vector or point in LC
EyeVdc	Eye vector or point in VDC
EyeCc	Eye vector or point in CC

Table 6-3 (Continued)

Mnemonic	Name
ParallelProj	Parallel projection flag
MclipPlanesMc	Model-clip planes in MC
MclipPlanesLc	Model-clip planes in LC
MclipPlanesCc	Model-clip planes in CC
MclipPlanesDc	Model-clip planes in DC
DcuePlanesCc	Depth cue planes in CC
DcuePlanesDc	Depth cue planes in DC
ViewCanonical	View canonical flag

Overview of Derived Data's Implementation

The view model derived data facility consists of a set of four classes for each of 2D and 3D. Table 6-4 lists the class names.

Table 6-4

Generic Name	2D C++ Class Name	3D C++ Class Name
View cache	XglViewCache2d	XglViewCache3d
View group configuration	XglViewGrp2dConfig	XglViewGrp3dConfig
View group interface	XglViewGrp2dItf	XglViewGrp3dItf
View concern	XglViewConcern2d	XglViewConcern3d

A view cache object consists of derived items and functions for deferred evaluation of the items. Each Context has a pointer to its own view cache object, which maintains the derived items specific to that Context.

A view group configuration object holds the static configuration information for each coordinate system from which geometry can enter LI-1. Each view cache has an array of view group configuration objects, one for each coordinate system that the view cache supports. A 2D view cache supports MC, VDC, CC, and DC. A 3D view cache supports these four as well as LC. The configuration information is static: it is invariant once initialized and is common to all view caches of a particular dimension.

A view group interface object is a pipeline's interface to the view model derived data. This object informs a pipeline when derived items have changed as a result of either the application changing a view model attribute or a pipeline changing the coordinate system from which geometry enters the next LI-1 primitive. The view group interface also maintains functions for returning the items appropriate to the current coordinate system.

A view concern object is a description of all the derived items whose changes a pipeline is concerned with. This object is a parameter of the view group interface's fast test for changes to derived items.

Each pipeline has a pointer to a view group interface object. The view group interface has functions for creating and destroying view concern objects. A pipeline may create as many view concern objects as it needs. For example, it can have one for stroke primitives and one for surface primitives. The view cache and view group configuration objects are inaccessible to pipelines so their interfaces are not described in this document; see XGL Architecture Guide or the appropriate header files for more information.

Accessing Derived Data

The pipeline has access to member functions of the view group interface object. Each pipeline is provided with a pointer to its view group interface object by the pipeline context classes. The 2D pipeline context class, XglPipeCtx2d, has a member datum of type XglViewGrp2dItf* called viewGrpItf. Likewise, XglPipeCtx3d has a member datum of type XglViewGrp3dItf* called viewGrpItf. The constructors of XglPipeCtx2d and XglPipeCtx3d create a new view group interface object for each Context. In general, the software pipeline and device pipeline access member functions of the view group interface with viewGrpItf-> as a prefix, as in the following example.

xform = viewGrpItf->getMcToDc();

---

Note - The pipeline can access transforms and view model attributes via the Context object if the pipeline never falls back on the software pipeline. If, in fact, the pipeline never uses the software pipeline, it can access the Local Model Transform using XglTransform* mt = ctx->getModelTrans(). Even in this case, however, it is a good idea for pipelines to use derived data so that they work consistently with other pipelines. So the preferred way to access the Local Model Transform is to use derived data, as in

mt = viewGrpItf->getMcToWc.

---

Registration of Concerns

A device pipeline for a device that retains view model state can create view concern objects to keep track of the derived items that the pipeline is concerned about. Typically, a pipeline's concerns vary from primitive to primitive. Surfaces are more complex than stroked primitives such as polylines and markers, so a pipeline might have more concerns for surfaces. A pipeline can create its view concern objects in its constructors.

The following example shows the constructor and destructor of the 3D device pipeline for a sample pipeline (SampDp). The constructor creates view concern objects for the stroke and surface primitives. Registration of the concerns consists of two steps:

1. Define the view flag by combining bits corresponding to the derived items that the device pipeline loads into the device for a particular primitive or group of primitives.

2. Create a view concern object from the view flag.

Note that the pipeline needs only a few items from among the large selection available in derived data. This is typical for many devices. Those devices that accelerate more functionality usually need to keep track of more derived items.

#include "xgli/Context3d.h" #include "xgli/DpCtx3d.h" #include "xgli/ViewGrp3dItf.h" #include "DpCtx3dSampDp.h" #include "DpDevSampDp.h" XglDpCtx3dSampDp::XglDpCtx3dSampDp(XglContext3d* ctx, XglDpDevSampDp* dp_dev) :

XglDpCtx3d(ctx), XglDpCtxSampDp((XglContext*)context), dp_dev) { // Define view flag for polylines and markers. // Xgli_view_flag_3d XglDpCtx3dSampDp::strokeViewFlag; // strokeViewFlag.a =XGLI_VIEW_A_MC_TO_CC | XGLI_VIEW_A_CC_TO_DC; strokeViewFlag.b = NULL; strokeViewFlag.c = XGLI_VIEW_C_PARALLEL_PROJ; // Create a view concern object for polylines and markers. // XglViewConcern3d* XglDpCtx3dSampDp::strokeConcern; // XglViewGrp3dItf* XglPipeCtx3d::viewGrpItf; // strokeConcern = viewGrpItf- >createViewConcern(strokeViewFlag); // Define view flag for surfaces. // Xgli_view_flag_3d XglDpCtx3dSampDp::surfViewFlag; // surfViewFlag.a = strokeConcernBits.a | XGLI_VIEW_A_MC_TO_WC; surfViewFlag.b =strokeConcernBits.b | XGLI_VIEW_B_MC_TO_LC | XGLI_VIEW_B_LC_TO_MC | XGLI_VIEW_B_LC_TO_CC; surfViewFlag.c = strokeConcernBits.c | XGLI_VIEW_C_LIGHTS_MC | XGLI_VIEW_C_EYE_MC | XGLI_VIEW_C_LIGHTS_LC | XGLI_VIEW_C_EYE_LC; // Create a view concern object for surfaces. // XglViewConcern3d* XglDpCtx3dSampDp::surfConcern; // surfConcern = viewGrpItf->createViewConcern(surfViewFlag); // Set this context as the last one used for rendering to the // device. // XglContext3d* XglDpCtx3dSampDp::lastXglCtx; // lastXglCtx = ctx; // Assume that we last performed lighting in MC.

// Xgli_sam_light_coord_sys XglDpCtx3dSampDp::lastLightCoordSys; // lastLightCoordSys = SAMPDP_LIGHT_MC; } XglDpCtx3dSampDp::~XglDpCtx3dSampDp() { // Destroy view concern objects. // viewGrpItf->destroyViewConcern(strokeConcern); viewGrpItf->destroyViewConcern(surfConcern); }

Bit Definitions for the View Flag

The bit definitions for the view flag have the prefixes XGLI_VIEW_A_, XGLI_VIEW_B_, and XGLI_VIEW_C_. The bits with the prefix XGLI_VIEW_A_ correspond to items common to both 2D and 3D. The bits with the prefixes XGLI_VIEW_B_ and XGLI_VIEW_C_ are available only for 3D.

In 2D, the view flag has the type Xgl_usgn32, and any combination of the bits with the prefix XGLI_VIEW_A_ can be stored in the view flag. In 3D, the view flag has the type Xgli_view_flag_3d:

typedef struct { Xgl_usgn32 a; // Part "a" for XGLI_VIEW_A_... Xgl_usgn32 b; // Part "b" for XGLI_VIEW_B_... Xgl_usgn32 c; // Part "c" for XGLI_VIEW_C_... } Xgli_view_flag_3d;

The 3D view flag consists of three parts: a, b, and c. Any combination of bits with the prefix XGLI_VIEW_A_ can be stored in part "a" of the view flag; likewise for XGLI_VIEW_B_ in part "b" and for XGLI_VIEW_C_ in part "c".

In addition to being created, a view concern can be set with a new view flag, and it can be destroyed when a pipeline no longer needs it. The 2D view group interface functions for view concerns are:

XglViewConcern2d* createViewConcern (const Xgl_usgn32); void setViewConcern (XglViewConcern2d*, const Xgl_usgn32); void destroyViewConcern (XglViewConcern2d*);

The 3D view group interface functions for view concerns are:

XglViewConcern3d* createViewConcern (const Xgli_view_flag_3d&); void setViewConcern (XglViewConcern3d*, const Xgli_view_flag_3d&); void destroyViewConcern (XglViewConcern3d*);

---

Note - Setting a view concern frequently is inadvisable because the process for "compiling" a view flag into a view concern is time-consuming.

---

Table 6-5 lists the bits that a pipeline can define in the view flag.

Table 6-5

View Flag Masks for 2D/3D Part a	View Flag Masks for 3D Part b	View Flag Masks for 3D Part c
XGLI_VIEW_A_MC_TO_DC XGLI_VIEW_A_MC_TO_CC XGLI_VIEW_A_CC_TO_DC XGLI_VIEW_A_MC_TO_WC XGLI_VIEW_A_VDC_TO_CC XGLI_VIEW_A_CC_TO_VDC XGLI_VIEW_A_WC_TO_CC XGLI_VIEW_A_VDC_TO_DC XGLI_VIEW_A_DC_TO_VDC XGLI_VIEW_A_WC_TO_DC XGLI_VIEW_A_DC_TO_CC XGLI_VIEW_A_MC_TO_VDC XGLI_VIEW_A_DC_TO_MC XGLI_VIEW_A_MC_TO_GMC XGLI_VIEW_A_GMC_TO_WC XGLI_VIEW_A_WC_TO_VDC XGLI_VIEW_A_VCLIP_BOUNDS_VDC XGLI_VIEW_A_VCLIP_BOUNDS_CC XGLI_VIEW_A_VCLIP_BOUNDS_DC XGLI_VIEW_A_VCLIP_BOUNDS_MC XGLI_VIEW_A_VIEWPORT_DC	XGLI_VIEW_B_LC_TO_VDC XGLI_VIEW_B_VDC_TO_LC XGLI_VIEW_B_CC_TO_LC XGLI_VIEW_B_LC_TO_DC XGLI_VIEW_B_MC_TO_LC XGLI_VIEW_B_LC_TO_MC XGLI_VIEW_B_LC_TO_CC XGLI_VIEW_B_WC_TO_MC XGLI_VIEW_B_WC_TO_LC XGLI_VIEW_B_LC_TO_IC XGLI_VIEW_B_IC_TO_VDC XGLI_VIEW_B_VDC_TO_WC XGLI_VIEW_B_CC_TO_WC XGLI_VIEW_B_DC_TO_LC XGLI_VIEW_B_DC_TO_WC XGLI_VIEW_B_LC_TO_WC XGLI_VIEW_B_CC_TO_MC	XGLI_VIEW_C_LIGHTS_MC XGLI_VIEW_C_LIGHTS_LC XGLI_VIEW_C_EYE_MC XGLI_VIEW_C_EYE_LC XGLI_VIEW_C_EYE_VDC XGLI_VIEW_C_EYE_CC XGLI_VIEW_C_PARALLEL_PROJ XGLI_VIEW_C_MCLIP_PLANES_MC XGLI_VIEW_C_MCLIP_PLANES_LC XGLI_VIEW_C_MCLIP_PLANES_CC XGLI_VIEW_C_MCLIP_PLANES_DC XGLI_VIEW_C_DCUE_PLANES_CC XGLI_VIEW_C_DCUE_PLANES_DC XGLI_VIEW_C_VIEW_CANONICAL

Determining Whether Derived Items Have Changed

A device pipeline can detect changes to derived items with a sequence of tests at three levels: messages, the composite, and the individual item. In general, a device pipeline needs to know quickly when no changes have occurred so that it can proceed directly to sending geometry to the device. Accordingly, each successive level of detection involves more effort to gain more accuracy.

Messages

Derived items can change when the application changes a view model attribute or a pipeline changes the current coordinate system. Each type of event causes a message to be sent to the device pipeline at the time of the event; notification is not deferred. The message types are

XGLI_MSG_VIEW_CTX_ATTR and XGLI_MSG_VIEW_COORD_SYS for context attribute changes and current coordinate system changes, respectively. See "Handling Derived Data Changes" on page 81 for additional information on messages. Messages of the two types above give advance warning that the next primitive may need to get derived items. A pipeline may choose to deal with the messages simply by setting its own flag at the time of the notification, then deferring action until the next primitive when it would need to interrogate the composite at the next level.

The Composite

If a message reports that a change has occurred, a device pipeline can test for changes to the derived items about which it is concerned by checking the composite. The composite records the state changes of all derived items. The changes could be caused either by the application changing view model attributes or by a pipeline changing the current coordinate system. The composite can be thought of as all the separate derived items joined into a single unit.

Detecting Changes With the Composite

The function that checks the composite has the following definition:

Xgl_boolean      changedComposite(const XglViewConcern{2,3}d*);

This function is the fast test described in "Changes to Derived Items" on page 127. The view group interface tests the composite to detect changes to derived items of concern to the device pipeline.

The view concern acts as a filter on the composite so that changedComposite() returns TRUE only when an item of interest to the pipeline has changed. If the test is TRUE, the pipeline needs to check each of the individual items for changes. The tests for individual items comprise the third level, and they are described in the section "Detecting Changes to Individual Derived Items" on page 140.

Recall that changedComposite() sometimes errs on the cautious side so that changedComposite() can be fast. It never misses a change in state caused by invalidation of relevant view model attributes or changes in the current coordinate system, but it may incorrectly return TRUE after a change to the current coordinate system. The tests at the third level for detecting changes to

individual items are fast and accurate, so extraneous reloading of view model state to a device would not occur even if changedComposite() incorrectly returns TRUE.

A device pipeline should call changedComposite() whenever one of its primitives regains control from the application. Typically, this is at the beginning of an LI-1 primitive. If a primitive changes the coordinate system and calls a secondary LI-1 primitive, then the original primitive should restore the original coordinate system when the secondary returns, and the original should call changedComposite().

Setting the Composite

The view group interface can notify a device pipeline when its concerns have changed, but it cannot detect context switches. A context switch occurs when an application renders to a device with an XGL Context after having previously rendered to the same device with a different XGL Context. If a device has only one hardware context, a context switch requires the retained state to be updated with the corresponding information of the new XGL Context. If a device has multiple hardware contexts, a device pipeline may be implemented so that an XGL Context has a one-to-one mapping with a hardware context such that a context switch does not result in reloading of retained state. Since each device handles of context switches in its own way, the view group interface does not react automatically to context switches. Instead, the view group interface provides a function to set the composite:

void    setComposite();

When a context switch occurs, a device pipeline can call setComposite() to force the next call to changedComposite() and each of the tests for changes to individual items to be TRUE. Consequently, a device pipeline would reload its derived items into the device.

Clearing the Composite

In certain situations a device pipeline may want to ignore changes to its concerns. The view group interface provides a function to clear the composite. For 2D and 3D, this function is:

void    clearComposite(const XglViewConcern{2,3}d*);

This function forces the next call to changedComposite() to return FALSE if there have been no further changes to the API view model attributes or to the current coordinate system. A pipeline may gain performance with this function because it allows primitives to ignore changes deemed to be irrelevant. But it should be used with great caution because it clears the record of inconsistencies between the state stored in the device and the actual state, which may cause a pipeline to miss a change when it becomes relevant. It should be called after changedComposite().

Detecting Changes to Individual Derived Items

If changedComposite() returns TRUE, a device pipeline needs to check for changes to individual items. The view group interface provides a function for each item to return the change status of that item. These functions should be called only after calling changedComposite(). After doing so, a pipeline may call any change function for individual items, even those that are not registered as concerns. Calling these functions does not reset the flags stored in the composite. These functions return the correct change status of individual items even when changedComposite() errs on the cautious side.

See the sections "Coordinate Systems and Transforms" and "Other Derived Items" for naming conventions.

Table 6-6 lists the functions to check individual items for 2D and 3D.

Table 6-6

2D and 3D	3D only
Xgl_boolean changedMcToDc() Xgl_boolean changedMcToCc() Xgl_boolean changedCcToDc() Xgl_boolean changedMcToWc() Xgl_boolean changedVdcToCc() Xgl_boolean changedCcToVdc() Xgl_boolean changedWcToCc() Xgl_boolean changedVdcToDc() Xgl_boolean changedDcToVdc() Xgl_boolean changedWcToDc() Xgl_boolean changedDcToCc() Xgl_boolean changedMcToVdc() Xgl_boolean changedDcToMc() Xgl_boolean changedMcToGmc() Xgl_boolean changedGmcToWc() Xgl_boolean changedWcToVdc() Xgl_boolean changedVclipBoundsVdc() Xgl_boolean changedVclipBoundsCc() Xgl_boolean changedVclipBoundsDc() Xgl_boolean changedVclipBoundsMc() Xgl_boolean changedViewportDc()	Xgl_boolean changedLctoVdc() Xgl_boolean changedVdcToLc() Xgl_boolean changedCcToLc() Xgl_boolean changedLcToDc() Xgl_boolean changedMcToLc() Xgl_boolean changedLcToMc() Xgl_boolean changedLcToCc() Xgl_boolean changedWcToMc() Xgl_boolean changedWcToLc() Xgl_boolean changedLcToIc() Xgl_boolean changedIcToVdc() Xgl_boolean changedVdcToWc() Xgl_boolean changedCcToWc() Xgl_boolean changedDcToLc() Xgl_boolean changedDcToWc() Xgl_boolean changedLcToWc() Xgl_boolean changedCcToMc() Xgl_boolean changedLightsMc() Xgl_boolean changedLightsLc() Xgl_boolean changedEyeMc() Xgl_boolean changedEyeLc() Xgl_boolean changedEyeVdc() Xgl_boolean changedEyeCc() Xgl_boolean changedParallelProj() Xgl_boolean changedMclipPlanesMc() Xgl_boolean changedMclipPlanesLc() Xgl_boolean changedMclipPlanesCc() Xgl_boolean changedMclipPlanesDc() Xgl_boolean changedDcuePlanesCc() Xgl_boolean changedDcuePlanesDc() Xgl_boolean changedViewCanonical()

Getting Derived Items

If an individual derived item has changed as reported by the corresponding function, a device pipeline should get the item and reload the state into the hardware. The view group interface provides a function for each item to get that item. Calling one of these functions triggers any deferred calculations that may be necessary to bring the item up to date. Therefore, a pipeline should not retain a pointer to a derived item after a primitive has finished execution because accessing the derived item with the pointer without calling the function for getting the item means that the item will not be evaluated if necessary.

The view group interface returns the requested item that is appropriate to the current coordinate system. For example, if the current coordinate system is LC and the pipeline requests the McToCc Transform, then getMcToCc() returns the LcToCc Transform because the geometry is in LC. A device pipeline does not need to be aware of the current coordinate system. An LI-1 primitive can be written as if geometry always enters from MC as long as it uses derived data. If a pipeline is using derived data, it must get all its Transforms from the view group interface instead of the Context. For example, a pipeline should use viewGrpItf->getMcToGmc() instead of

ctx->getLocalModelTrans(). The only exception is when a pipeline wants to get the actual Transform visible at the API level with the knowledge that it may not be applicable to the current coordinate system maintained by derived data. A change in the current coordinate system is another reason that a pipeline should not retain a pointer to a derived item after a primitive has finished execution: the item returned by the view group interface may differ between primitive calls when the current coordinate system changes.

When a pipeline calls a function for getting an item, that function clears the bit in the composite that corresponds to the item. If a pipeline gets all the items that have changed, then changedComposite() returns FALSE until the pipeline's concerns change again. A pipeline can clear bits in the composite without getting changed items by calling clearComposite().

Pipelines that do not retain state (such as the software pipeline) can get derived items without checking the composite or any of the individual items. While this is true of any pipeline, even those that retain state, checking the composite and individual items eliminates unnecessary loading of data into the device.

Note that if a pipeline uses derived data, it can ignore most Context view model attributes. For example, it can ignore the value of the Context attribute XGL_CTX_VDC_MAP because derived data takes into account the value of the VDC map when it calculates the VDC-to-DC Transform. Consequently, all Transforms derived from the VDC-to-DC Transform have the VDC mapping taken into account.

Getting Derived Transforms

The view group interface allows pipelines to access numerous Transforms for mapping points forward (toward DC) and backward (toward MC); for brevity, we call these point-forward and point-backward Transforms, respectively. The point-backward Transforms can be used to map normal and direction vectors forward. Thus, the point-backward Transforms are normal-forward Transforms, and the point-forward Transforms are normal-backward Transforms.

The view cache computes the normal-forward Transforms by inverting point-forward Transforms. If an application specifies a singular¹ Local Model, Global Model, or View Transform, the view cache cannot compute unique normal-forward Transforms and certain derived items such as eye positions or vectors, model clip planes, and lights. Derived data currently does not claim to support singular Transforms so it is the application's responsibility to avoid singular Transforms. However, if a pipeline needs to determine if a normal-forward Transform obtained from the view group interface is valid, it should get the McToWc, LcToVdc, and VdcToDc Transforms after getting the normal-forward Transform and confirm that all three are nonsingular.

The view cache in 3D automatically adjusts for the effect of XGL_3D_CTX_JITTER_OFFSET so pipelines using derived data do not need to take this into account.

See Chapter 5, "Getting Information from XGL Objects" for information on getting data from Transform objects.

---

1. A singular matrix has no unique inverse.

Table 6-7 lists the functions for getting derived transforms for 2D and 3D.

Table 6-7

2D and 3D	3D only
XglTransform* getMcToDc() XglTransform* getMcToCc() XglTransform* getCcToDc() XglTransform* getMcToWc() XglTransform* getVdcToCc() XglTransform* getCcToVdc() XglTransform* getWcToCc() XglTransform* getVdcToDc() XglTransform* getDcToVdc() XglTransform* getWcToDc(); XglTransform* getDcToCc() XglTransform* getMcToVdc() XglTransform* getDcToMc() XglTransform* getMcToGmc() XglTransform* getGmcToWc() XglTransform* getWcToVdc()	XglTransform* getLctoVdc() XglTransform* getVdcToLc() XglTransform* getCcToLc() XglTransform* getLcToDc() XglTransform* getMcToLc() XglTransform* getLcToMc() XglTransform* getLcToCc() XglTransform* getWcToMc() XglTransform* getWcToLc() XglTransform* getLcToIc() XglTransform* getIcToVdc() XglTransform* getVdcToWc() XglTransform* getCcToWc() XglTransform* getDcToLc() XglTransform* getDcToWc() XglTransform* getLcToWc() XglTransform* getCcToMc()

Getting Boundaries

The view group interface offers the functions listed in Table 6-8 for getting the DC viewport and the view clip bounds in MC, VDC, CC, and DC.

Table 6-8

Dimension	Function
2D	const Xgl_bounds_d2d& getViewportDc() const Xgl_bounds_d2d& getVclipBoundsMc() const Xgl_bounds_d2d& getVclipBoundsVdc() const Xgl_bounds_d2d& getVclipBoundsCc() const Xgl_bounds_d2d& getVclipBoundsDc()
3D	const Xgl_bounds_d3d& getViewportDc() const Xgl_bounds_d3d& getVclipBoundsMc() const Xgl_bounds_d3d& getVclipBoundsVdc() const Xgl_bounds_d3d& getVclipBoundsCc() const Xgl_bounds_d3d& getVclipBoundsDc()

See the man page for XGL_CTX_DC_VIEWPORT for a description of the DC viewport. A pipeline should not use the DC viewport for view clipping; instead, it should use the view clip bounds in DC.

The view clip bounds in VDC may differ from the value of XGL_CTX_VIEW_CLIP_BOUNDS as specified by the application. The view cache ensures that the view clip bounds are entirely within the value of XGL_CTX_VDC_WINDOW in VDC and the viewport in DC. The view clip bounds in CC is always [-1,1] . [-1,1] in 2D and [-1,1] . [-1,1] . [-1,1] in 3D. A pipeline should ensure that geometry never extends outside the view clip bounds.

The value of the view clip bounds in MC is the smallest rectangular parallelepiped whose edges are parallel to the coordinate axes of MC such that the parallelepiped contains the actual view clip bounds transformed into MC. This is a useful form for fast bounding-box checking in MC, but it is not particularly useful for view clipping.

If the current coordinate system is LC, getVclipBoundsMc() returns an incorrect value because the view cache currently has no function for evaluating the view clip bounds in LC.

Getting 3D Viewing Flags

The 3D view group interface has two functions for getting more information about the WcToVdc Transform. These functions are:

Xgl_boolean      getParallelProj()
Xgl_boolean      getViewCanonical()

A pipeline can determine if the WcToVdc Transform is configured for parallel projection by calling getParallelProj(), which returns TRUE for parallel projection and FALSE for perspective projection.

A pipeline can call getViewCanonical() to determine if the view cache successfully factored the View Transform to extract Lighting Coordinates. The function returns TRUE when the decomposition is successful and FALSE for unsuccessful. For the unsuccessful case, LC is the same as WC and IC is the same as VDC.

Getting Lights

The 3D view group interface has two functions for getting lights in MC and LC. These functions are:

const XglLight* const *getLightsMc();
const XglLight* const *getLightsLc();

A pipeline should get the number of lights from the Context (see XGL_3D_CTX_LIGHT_NUM(3)) to access the array of XglLight pointers.

A pipeline can always perform lighting calculations in WC and LC to obtain correct results. Performing lighting calculations in MC may be faster because normal vectors do not need to be transformed, but lighting calculations in MC are correct only when the McToWc Transform preserves angles. The reason is that dot products in MC are different than those in WC when the McToWc Transform does not preserves angles. See the Transform section in Chapter 5, "Getting Information from XGL Objects" for information on how to determine whether a Transform preserves angles.

The view cache calculates the lights in MC by inverting the McToWc Transform. If the application has specified a singular matrix for the Local or Global Model Transforms, then the view cache is unable to calculate the lights in MC. A pipeline can determine if the lights in MC are valid by getting the McToWc Transform after getting the lights, then checking if it is nonsingular.

If the current coordinate system is VDC, CC, or DC, then getLightsMc() and getLightsLc() return incorrect results because the view cache currently has no functions for calculating the lights in VDC, CC, and DC. In general, lighting calculations would not be correct in these coordinate systems because the Transform from WC to VDC, CC, or DC often involves anisotropic scaling and perspective, which do not preserve angles.

See the Light section in Chapter 5, "Getting Information from XGL Objects" for information on getting data from Light objects.

Getting Eye Positions or Vectors

The 3D view group interface has four functions for getting eye positions or vectors in MC, LC, VDC, and CC. These functions are:

const Xgl_pt_d3d&     getEyeMc()
const Xgl_pt_d3d&     getEyeLc()
const Xgl_pt_d3d&     getEyeVdc()
const Xgl_pt_d3d&     getEyeCc()

Eye points or vectors may be used for facet orientation and lighting. Eye vectors point from eye to object along the line of sight, and the eye is located infinitely far away. Eye vectors returned by these functions have unit length.

The eyes in VDC and CC are always vectors. A pipeline can determine whether the eyes in MC and LC are positions or vectors by calling getParallelProj(); a parallel projection means that the eyes are vectors, while perspective means the eye are positions.

The view cache calculates eyes by inverting various Transforms. If the application has specified a singular matrix, then the view cache is unable to calculate some eyes. A pipeline can determine if the eyes in VDC and CC are valid by getting the VdcToDc Transform after getting the eyes, then checking if it is nonsingular (see the Transform section in Chapter 5, "Getting Information from XGL Objects"). For the eye in LC, a pipeline needs to check the LcToVdc and VdcToDc Transforms for nonsingularity. For the eye in MC, a pipeline needs to check the McToWc, LcToVdc, and VdcToDc Transforms for nonsingularity.

If the current coordinate system is DC, then these four functions return incorrect values because the view cache currently has no function for calculating the eye in DC. However, the value of the eye vector in DC is always (0, 0, 1).

Getting Model Clip Planes

The 3D view group interface has four functions for getting the model clip planes in MC, LC, CC, and DC.

const Xgli_plane*     getMclipPlanesMc()
const Xgli_plane*     getMclipPlanesLc()
const Xgli_plane*     getMclipPlanesCc()
const Xgli_plane*     getMclipPlanesDc()

A pipeline should get the number of model clip planes from the Context (see XGL_3D_CTX_MODEL_CLIP_PLANE_NUM(3)) to access the array of Xgli_plane. The structure definition is:

struct Xgli_plane {
   Xgl_pt_d3d    pt;
   Xgl_pt_d3d    normal;
   double        p_dot_n;
};

The value of pt is a point on the plane. The normal vectors point in the direction of accepted geometry (see XGL_3D_CTX_MODEL_CLIP_PLANES(3)). Normal vectors have unit length as long as the application specifies model clip planes in WC with unit normal vectors. The value of p_dot_n is the dot product of pt and normal.

The view cache calculates model clip planes by inverting various Transforms. If the application has specified a singular matrix, then the view cache will be unable to calculate some or all model clip planes. A pipeline can determine if the model clip planes in MC are valid by getting the McToWc Transform after getting the model clip planes, then checking if it is nonsingular. For the model clip planes in CC and DC, a pipeline needs to check the LcToVdc and VdcToDc Transforms for nonsingularity.

If the current coordinate system is VDC, then getMclipPlanesMc() and getMclipPlanesLc() return incorrect values because the view cache currently has no function for calculating the model clip planes in VDC.

Getting Depth Cue Reference Planes

The 3D view group interface has two functions for getting the depth cue reference planes in CC and DC.

void    getDcuePlanesCc(double [])
void    getDcuePlanesDc(double [])

Pipelines should pass an array of 2 doubles to these functions. The value at index 0 is the front depth cue reference plane's Z-value; the value at index 1 is the back depth cue reference plane's Z-value. See XGL_3D_CTX_DEPTH_CUE_REF_PLANES.

Example of Detecting Changes and Getting Derived Items

In this example of a device pipeline for li1TriangleStrip(), the pipeline determines whether any Context attributes or derived items have changed by checking the flag that the pipeline sets upon receiving a message of the types XGLI_MSG_VIEW_CTX_ATTR or XGLI_MSG_VIEW_COORD_SYS. If the flag is set, the pipeline determines whether any derived items have changed by calling viewGrpItf->changedComposite(surfConcern). The parameter is an XglViewConcern3d*, which was created in the example constructor on page 133. If changedComposite() indicates that derived data items have changed, the pipeline checks whether individual items have changed, and if so, it gets them from the view group interface object and loads them into the device.

You can copy or modify this source code sample as long as the resulting code is used to create a loadable pipeline for XGL.

#include "xgli/Context3d.h" #include "xgli/DpCtx3d.h" #include "xgli/Transform.h" #include "xgli/ViewGrp3dItf.h" #include "DpCtx3dSampDp.h" XglDpCtx3dSampDp::li1TriangleStrip(XglPrimData* pd) { // Check for context switch // if (lastXglCtx != ctx) { // Force reloading of attributes and derived items //

udTable.setAllGroupsAsChanged(); viewGrpItf->setComposite(); lastXglCtx = ctx; } // Check if any view-change messages have been received // if (viewMsgReceived) { // Clear flag viewMsgReceived = FALSE; // Check composite for changes to surface concerns if (viewGrpItf->changedComposite(surfConcern)) { if (viewGrpItf->changedMcToCc()) { XglTransform* trans; const Xgli_matrix_f4x4* matrix; trans = viewGrpItf->getMcToCc(); matrix = (const Xgli_matrix_f4x4*) trans->getMatrixFloat(); // Write the matrix into the device SAMPDP_WRITE_MC_TO_CC(matrix); } if (viewGrpItf->changedCcToDc()) { XglTransform* trans; const Xgli_matrix_f4x4* matrix; trans = viewGrpItf->getCcToDc(); matrix = (const Xgli_matrix_f4x4*) trans->getMatrixFloat(); // Write the matrix into the device SAMPDP_WRITE_CC_TO_DC(matrix); } if (viewGrpItf->changedParallelProj()) { // Write the flag into the device SAMPDP_WRITE_PARALLEL_PROJ (viewGrpItf->getParallelProj()); } if (viewGrpItf->changedEyeMc()) {

// Write the eye into the device SAMPDP_WRITE_EYE_MC(viewGrpItf->getEyeMc()); } if (lastLightCoordSys == SAMPDP_LIGHT_MC) { // We performed lighting in MC last time if (viewGrpItf->changedMcToWc()) { if (viewGrpItf->getMcToWc()->getMemberRecord() & XGL_TRANS_GROUP_ANGLE_PRESERV) { // McToWc changed, but it still preserves // angles so we can continue to // perform lighting in MC. const XglLight* const * lights; lights = viewGrpItf->getLightsMc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); } else { // McToWc changed and it doesn't preserve // angles so we have to switch to performing // lighting in LC. const XglLight* const * lights; lights = viewGrpItf->getLightsLc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); // Switch lighting coordinate system SAMPDP_WRITE_LIGHT_COORD_SYS(SAMPDP_LIGHT_LC); lastLightCoordSys = SAMPDP_LIGHT_LC; } } else { // McToWc didn't change, but the lights // may have changed. // if (viewGrpItf-changedLightsMc() { const XglLight* const * lights;

lights = viewGrpItf->getLightsMc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); } } } else { // We performed lighting in LC last time if (viewGrpItf->changedMcToWc()) { if (viewGrpItf->getMcToWc()->getMemberRecord() & XGL_TRANS_GROUP_ANGLE_PRESERV) { // McToWc changed and it preserves angles so // we can switch to performing lighting in MC. const XglLight* const * lights; lights = viewGrpItf->getLightsMc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); // Switch lighting coordinate system SAMPDP_WRITE_LIGHT_COORD_SYS(SAMPDP_LIGHT_MC); lastLightCoordSys = SAMPDP_LIGHT_MC; } else { // McToWc changed, but it still doesn't // preserve angles so we have to // continue lighting in LC. const XglLight* const * lights; lights = viewGrpItf->getLightsLc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); } } else { // McToWc didn't change, but the lights may have // changed. if (viewGrpItf-changedLightsLc() {

const XglLight* const * lights; lights = viewGrpItf->getLightsLc(); // Write the lights into the device Xgl_usgn32 num; num = ctx->getLightNum(); SAMPDP_WRITE_LIGHTS(num, lights); } } } if (lastLightCoordSys == SAMPDP_LIGHT_LC) { // We have to perform lighting in LC so we need to // write some additional items into the device. if (viewGrpItf->changedMcToLc()) { XglTransform* trans; const Xgli_matrix_f4x4* matrix; trans = viewGrpItf->getMcToLc(); matrix = (const Xgli_matrix_f4x4*) trans->getMatrixFloat(); // Write the matrix into the device SAMPDP_WRITE_MC_TO_LC(matrix); } if (viewGrpItf->changedLcToMc()) { XglTransform* trans; const Xgli_matrix_f4x4* matrix; trans = viewGrpItf->getLcToMc(); matrix = (const Xgli_matrix_f4x4*) trans->getMatrixFloat(); // Write the matrix into the device SAMPDP_WRITE_LC_TO_MC(matrix); } if (viewGrpItf->changedLcToCc()) { XglTransform* trans; const Xgli_matrix_f4x4* matrix; trans = viewGrpItf->getLcToCc(); matrix = (const Xgli_matrix_f4x4*)

trans->getMatrixFloat(); // Write the matrix into the device SAMPDP_WRITE_LC_TO_CC(matrix); } if (viewGrpItf->changedEyeLc()) { // Write the eye into the device SAMPDP_WRITE_EYE_LC(viewGrpItf->getEyeMc()); } } } } // Ready to send geometry to device // return sendLi1TriangleStrip(pd); }

Current Coordinate System

A pipeline can get and set the current coordinate system. The current coordinate system is a member datum of the view cache, which maintains a stack exclusively for tracking the current coordinate systems of LI-1 primitives pending completion of execution. Pushing the current coordinate system onto the stack does not change the value of the member datum. Popping the top element from the stack changes the current coordinate system to that element; the value returned is the popped value.

The view group interface provides functions for manipulating the current coordinate system. For 2D, these functions are:

Xgli_li1_2d_coord_sysgetCurCoordSys() const void setCurCoordSys(Xgli_li1_2d_coord_sys) void pushCurCoordSys() Xgli_li1_2d_coord_syspopCurCoordSys()

where Xgli_li1_2d_coord_sys is defined as:

enum Xgli_li1_2d_coord_sys { XGLI_LI1_2D_COORD_SYS_MC = 0, XGLI_LI1_2D_COORD_SYS_VDC,

enum Xgli_li1_2d_coord_sys { XGLI_LI1_2D_COORD_SYS_CC, XGLI_LI1_2D_COORD_SYS_DC };

For 3D, these functions are:

Xgli_li1_3d_coord_sysgetCurCoordSys() const void setCurCoordSys(Xgli_li1_3d_coord_sys) void pushCurCoordSys() Xgli_li1_3d_coord_syspopCurCoordSys()

where Xgli_li1_3d_coord_sys is defined as:

enum Xgli_li1_3d_coord_sys { XGLI_LI1_3D_COORD_SYS_MC = 0, XGLI_LI1_3D_COORD_SYS_LC, XGLI_LI1_3D_COORD_SYS_VDC, XGLI_LI1_3D_COORD_SYS_CC, XGLI_LI1_3D_COORD_SYS_DC };

This example from the software pipeline's 2D annotation text primitive shows how a device pipeline can handle changes in the coordinate system. The software pipeline produces annotation text in VDC, so it pushes the current coordinate system (which is MC), sets the current coordinate system to VDC, calls the li1MultiPolyline() function (will render the strokes for the annotation text), and then pops the coordinate system to restore the previous one.

viewGrpItf->pushCurCoordSys(); viewGrpItf->setCurCoordSys(XGLI_LI1_2D_COORD_SYS_VDC); itfMgr->li1MultiPolyline(&pd, FALSE, do_retained); viewGrpItf->popCurCoordSys();