In Chapter 9, the six logical input device classes of PHIGS have been described using REQUEST mode for illustration. In this section, the other input modes, SAMPLE and EVENT, are described.
The discussion in Chapter 9 has concentrated on the application's view of a logical input device rather than the operator's view. In part this has been done because PHIGS standardizes much more about the application program interface than about the operator interface. However, there are some aspects of the operator interface which are standardized by PHIGS and can be controlled by the application program. The control provided over logical input devices in PHIGS is very similar to that provided in GKS. PHIGS and GKS in fact share the same input model. To explain the three modes of interaction and the control provided over the operator interface, it is convenient first to describe the input model.
When a logical input device is activated in REQUEST mode, the operator will be given some visual or other signal that the device is active and input is required from it. This is called the prompt of the device. The operator will then be able to manipulate the value of the logical input device, for example, if the physical device is a mouse which is mapped onto a LOCATOR logical input device, the operator can move the mouse around and thus change the value of the LOCATOR. PHIGS gives the operator visual feedback of the LOCATOR position through the echo of the logical input device. For a LOCATOR, one possible echo is a cursor displayed at the current LOCATOR position on the display. To convert input values from the physical input device, for example raw relative movements from a mouse, into values of the logical input device requires some processing to be performed. This processing is called the measure process. The measure of a logical input device is a conceptual process which converts the input value of the logical input device. As the operator manipulates the device, for example moves the mouse, the measure process maintains the current measure value of the logical input device, that is the logical input value corresponding to the current state of the physical input device into which it is mapped. The current measure value is echoed to the operator by the device's echo. This also can be thought of as a process which is concurrent with the measure process.
In REQUEST mode input, the operator manipulates the measure of the logical input device, and at some point has to indicate that a particular input value is the one that satisfies the request, so that the interaction can terminate and the application program resume. In the input model, the action performed to indicate that a particular value is to satisfy a request, is called the trigger. The trigger of a logical input device can be thought of as a process which runs concurrently with the measure and echo processes. In the most general form, a trigger is a condition, for example a button press, or a timer click. When the condition is satisfied, the trigger process is said to fire. In REQUEST mode, when a device's trigger fires, the current value of the measure is returned to the application and the interaction with the device terminates.
When an interaction with a logical input device is complete, an acknowledgement is provided to the operator. The disappearance of the cursor when interaction with a LOCATOR logical input device is complete is a form of acknowledgement.
There are three other components of the input model which need to be described. The application program can provide an initial value for the device's measure. This is the value to which the device's measure will be initialized when an interaction commences.
The application can control the region of the display space in which the echo of the device will be displayed. In 3D this is called the echo volume and in 2D the echo area.
Finally, a data record may be passed to a logical input device upon initialization. This provides a way of passing additional control information, usually of a device specific or implementation specific kind, to the device upon initialization.
The three operating modes are now described in terms of this input model. A more detailed discussion of the device initialization functions is postponed until Section 10.2.
Each device can be in only one mode of operation at a time. By default, the operating mode for all devices is REQUEST mode.
The mode of operation is selected by calling a function of the type:
SET XXX MODE(WS, DV, MODE, EC)
where XXX denotes a device class (LOCATOR, STROKE, VALUATOR, CHOICE, PICK, STRING). The first two parameters identify the specific device whose operating mode is to be set. The third parameter defines the mode of operation and can take one of three values REQUEST, SAMPLE, and EVENT.
The last parameter, EC, can have one of two values, ECHO and NOECHO. If ECHO is specified, the operator will be given some indication of the current value of the device, for example by displaying a cursor on the display space. If NOECHO is specified, echoing is turned off. The default setting is ECHO.
A typical REQUEST mode function is:
REQUEST CHOICE(WS, DV, ST, CH)
When REQUEST CHOICE is called, a new interaction with the logical input device commences. The measure process (initialized to the device's initial value) and trigger process for the device are started, and if echoing is enabled, the initial value will be echoed in the echo volume or area. The operator then moves the physical device (moves a mouse, rotates a tracker ball etc); the screen echo is updated accordingly. When the operator is satisfied with the current measure value, the operator can activate a trigger to indicate the input is complete. The physical trigger may be, for example, a mouse button click or a button press on a tracker ball.
A typical interaction with a CHOICE logical input device is shown in Figure 10.1 to Figure 10.4. The example is based on the lamp example from Section 9.9 in which the operator uses a CHOICE logical input device to indicate whether a rotation of the base, arm or light is to be specified next. For simplicity, only the large desk is shown with one accessory, the lamp. Figure 10.1 shows the state of the display before the interaction commences.
When REQUEST CHOICE is invoked, the echo appears on the screen, displaying the initial value of the logical input device. In this case the echo is a pop-up menu, and the initial value is CHOICE number 1 which corresponds to the 'BASE' of the lamp being selected. This is shown in Figure 10.2.
The form of the menu is primarily defined by the PHIGS implementation although the application will usually have the ability to tailor it to its own requirements, at the very least to define the text to go within the boxes. Which mouse button is used to signal the choice will be implementation dependent and may even depend on the window manager upon which the PHIGS implementation sits.
The current value of the device's measure is indicated by displaying the corresponding string in bold and emboldening the outline of the corresponding menu box; the position of the mouse device which controls the selection of menu items is shown by the cursor to the right of the menu. As the mouse is moved down, the second and then the third item of the menu is highlighted. This is shown in Figure 10.3.
As the operator moves the mouse, the selected choice is highlighted until the decision is made as to what should be rotated next.
For example, the operator selects the third choice and fires the trigger (mouse button) to indicate that it is the LIGHT that is to be rotated. At this stage the CHOICE device is completed and the light is highlighted to indicate this is the selected part for rotation. This is shown in Figure 10.4.
The REQUEST mode input functions each return a status parameter to indicate whether the request succeeded or not. For all device classes, the values OK and NONE are possible. If a REQUEST function returns the status value OK, this indicates that the operator completed the input normally and the remaining data specify a valid logical input value.
If the status value returns with the value NONE, the remaining data will not represent a valid logical input value, because the operator has terminated the REQUEST abnormally by indicating a break.
How the operator indicates a break depends on the input device. For a LOCATOR logical input device, an invalid LOCATOR position might be taken to indicate a break; alternatively the device might have two trigger conditions, one to indicate normal termination, the second to indicate a break. The left and right-hand buttons of a three button mouse might be used for this purpose.
The first LOCATOR example in Section 9.3 contained an infinite loop from which there was no exit. The device status could be used to provide an exit condition as shown below.
100 CONTINUE
REQUEST LOCATOR(WS, DV, ST, VI, X, Y)
IF(ST .EQ. NONE) GOTO 200
MVRP(X, Y)
GOTO 100
200 CONTINUE
The functions REQUEST PICK and REQUEST CHOICE can return additional status values. For PICK input, the status value NOPICK can be returned. This differs from status value NONE in that the operator can terminate a REQUEST PICK with the normal trigger, but the device may not be pointing at any pick able output primitive.
Similarly, the CHOICE logical input device can return a status value NOCHOICE when the measure of the device does not correspond to any of the possible choices.
In REQUEST mode input, either the logical input device is active or the application is active, at any time. The application is suspended while the device is active, and the entire interaction with the device is contained within the invocation of the REQUEST function.
SAMPLE mode input on the other hand allows the logical input device and the application to be active simultaneously. The operator can manipulate the device, and independently, the application can sample the current value of the device. Control returns immediately to the application, without waiting for the operator to perform any action.
An interaction with a device in SAMPLE mode is started by setting the device mode to SAMPLE. The V ALU A TOR device will be used for illustration. A device is set into SAMPLE mode by calling the function:
SET VALUATOR MODE(WS, DV, SAMPLE, EC)
The effect of setting the mode to SAMPLE is to start the measure process for the device, initialized to the initial value for the device, and to echo the measure of that device if echoing is turned on. The operator can then change the value of the device's measure by manipulating the physical input device.
The application can ascertain the current value of the device's measure by calling the function:
SAMPLE VALUATOR(WS, DV, VAL)
The SAMPLE functions for VALUATOR, LOCATOR, STRING and STROKE do not have a status parameter, but SAMPLE CHOICE and SAMPLE PICK do have status parameters:
SAMPLE CHOICE(WS, DV, ST, CH)
The SAMPLE PICK function has an additional input parameter, DEPTH, which indicates the depth of pick path to be returned and has output parameters PPD indicating the depth of pick path actually returned in the array PP:
SAMPLE PICK(WS, DV, DEPTH, ST, PPD, PP)
For SAMPLE CHOICE and SAMPLE PICK, the status value NONE cannot be returned by the functions. For SAMPLE CHOICE, the possible status values are OK and NOCHOICE and for SAMPLE PICK, OK and NOPICK.
In Section 9.8, a VALUATOR logical input device was used in REQUEST mode to control the orientation of the lamp on the desk in the work environment. The use of REQUEST mode input in such a context provides a rather unsatisfactory style of interaction. It would be more natural for the operator to be given immediate feedback, with the lamp rotating as the operator manipulates the V ALUA TOR device. This can be achieved by operating the device in SAMPLE mode as shown in the example below.
OPEN STRUCTURE(LMP)
SET EDIT MODE (REPLACE)
SET ELEMENT POINTER(1)
SET VALUATOR MODE(WS, DV, SAMPLE, ECHO)
100 CONTINUE
SAMPLE VALUATOR(WS, DV, V)
RTRP(V*2*PI/360)
GOTO 100
There is no apparent way to terminate the loop in this program. The operator cannot, for example, use a break facility to indicate that the loop is to be terminated; as would be possible for REQUEST mode input. It is most natural to terminate the interaction using a second logical input device. One way of doing this, using a CHOICE logical input device in EVENT mode, is shown in Section 10.1.7.
The above example can be extended to use three VALUATOR logical input devices, each operating in SAMPLE mode, to control the orientation of the lamp base, arm and light, as follows:
SET VALUATOR MODE(WS, DV1, SAMPLE, ECHO)
SET VALUATOR MODE(WS, DV2, SAMPLE, ECHO)
SET VALUATOR MODE(WS, DV3, SAMPLE, ECHO)
SET EDIT MODE(REPLACE)
100 CONTINUE
C
C lamp orientation controlled by DVI
C
OPEN STRUCTURE(LMP)
SET ELEMENT POINTER(1)
SAMPLE VALUATOR(WS, DV1, ROT)
RTRP(ROT*PI/180)
C
C arm orientation controlled by DV2
C
SET ELEMENT POINTER(3)
SAMPLE VALUATOR(WS, DV2, ROT)
RTPR(ROT*PI/180)
CLOSE STRUCTURE
C
C light orientation controlled by DV3
C
OPEN STRUCTURE(ARM)
SET ELEMENT POINTER(3)
SAMPLE VALUATOR(WS, DV3, ROT)
RTPR(ROT*PI/180)
CLOSE STRUCTURE
GOTO 100
The program samples the three devices in turn, updating the structure element controlling the orientation of lamp, arm and light so that the display reflects the status of the three devices. The effectiveness of this style of interaction in practice is dependent upon the ability of the implementation to display the structure network sufficiently rapidly to keep pace with the changes to the VALUATOR devices made by the operator.
As in REQUEST mode input, pairs of functions are provided for LOCATOR and STROKE logical input devices:
SAMPLE LOCATOR 3(WS, DV, VI, XPS, YPS, ZPS) SAMPLE LOCATOR (WS, DV, VI, XPS, YPS) SAMPLE STROKE 3(WS, DV, N, VI, NPTS, XPSA, YPSA, ZPSA) SAMPLE STROKE (WS, DV, N, VI, NPTS, XPSA, YPSA)
The first of each pair returns positions in 3D world coordinate space; the second returns positions in 2D world coordinate space, obtained by dropping the Z-coordinate of the 3D positions returned through the input pipeline.
An interaction with a device in SAMPLE mode is terminated by resetting the operating mode of the device by calling the appropriate SET XXX MODE function. If the SET XXX MODE function is invoked to set a device to SAMPLE mode and it is already in SAMPLE mode, the current interaction with the device will be terminated and a new interaction initiated. Setting the operating mode to REQUEST returns the device to the inactive state and is the usual way of terminating an interaction with a device which is not to be used immediately in a new interaction.
EVENT mode input is generated by the operator and entered into a central input queue. The application can asynchronously remove input events from the queue.
An input device is set into EVENT mode by calling the appropriate SET XXX MODE function with parameter EVENT. If there is an interaction with the device underway, the interaction is terminated. The device's measure process is started and initialized to the initial value; an echo process starts if echoing is enabled. The trigger process is also started unlike in SAMPLE mode.
As in REQUEST mode, the operator can change the value of the device's measure by manipulating the physical input device. When the operator has set the measure to the required value, the trigger is activated. In REQUEST mode at this point, the current measure value would be returned to the application program and the interaction with the device would terminate. In EVENT mode, an event report consisting of the identification of the logical input device (workstation identifier, device class, device identifier, logical input value, and control information) is added to the central input queue. The interaction with the device continues and a further event report is added to the queue from the device each time the trigger is activated.
There is one central input queue to which event reports from all logical input devices in EVENT mode are added.
The function A WAIT EVENT enables the application program to remove events from the event queue:
AWAIT EVENT(TIMEOUT, WS, DVCLASS, DV)
The queue is examined to see if it is empty. If it is, the application program is suspended until either an event report is added to the queue, or a maximum of TIMEOUT seconds have elapsed. If the latter condition is satisfied, DVCLASS returns the value NONE. TIMEOUT can be zero in which case the application program is not suspended and control passes back to the application immediately.
If the input queue is not empty, either when AWAIT EVENT is called or before TIMEOUT expires, the identification of the first event in the queue is returned to the application. DVCLASS specifies the input class of the event (LOCATOR, STROKE etc); WS and DV specify the device itself. The event input data are removed from the queue and transferred to the current event report.
The logical input value can be read from the current event report by the GET function corresponding to the input class of the event:
GET VALUATOR(VAL) GET CHOICE(ST, CH) GET STRING(NCHARS, STR) GET PICK(DEPTH, ST, PPD, PP)
The GET CHOICE function returns either the status value OK, in which case the parameter CH contains a valid choice number, or the status NOCHOICE. The GET PICK function returns a status value (OK or NOPICK) and if the status is OK, a pick path is returned in the parameters PPD and PP. The first parameter is an input parameter which specifies the depth of pick path to return.
For the LOCATOR input class, two GET functions are provided:
GET LOCATOR 3(VI, XPOS, YPOS, ZPOS) GET LOCATOR (VI, XPOS, YPOS)
Each function returns a view index and a position in world coordinates. The difference is that GET LOCATOR 3 returns a 3D position and GET LOCATOR a 2D position. As has been noted already, the LOCATOR logical input device is a 3D device and a 3D position is entered into the event report in the input queue. GET LOCATOR returns the X and Y-coordinates of the position only and ignores the Z-coordinate. Thus if the same event report were to be retrieved with GET LOCATOR 3 and GET LOCATOR, the view index and both X and Y-coordinates of the position would be returned with the same values by each function.
Similarly for the STROKE input class, two GET functions are provided:
GET STROKE 3(N, VI, NPTS, XPA, YPA, ZPA) GET STROKE (N, VI, NPTS, XPA, YPA, ZPA)
The second discards the Z-coordinates of each of the points in the STROKE event report.
The power of EVENT mode input really stems from the asynchronous nature of this mode, in other words the operator can generate input events independently of the application's processing of them. This is most useful when more than one device is operating in EVENT mode at the same time (the operator can generate events from the devices in any order and the application can readily process the events in the order in which they were generated). It is also useful in conjunction with SAMPLE mode input; this will be illustrated in Section 10.1.7.
The first example of EVENT mode input is a simple application which enables the operator to input a sequence of points. Although it is somewhat contrived, it illustrates a number of important considerations which apply equally to more complex examples.
The operator can input a sequence of points one at a time, and can define the symbol with which the points are to be marked. The marker symbol can be changed at any time, with the result that all points input so far and points input subsequently will be marked with the new symbol until such time as the marker size is changed again. At this point, all the symbols will take the new form.
The example uses two logical input devices, both operating in EVENT mode. A LOCATOR device allows the operator to define points and a CHOICE device enables the operator to define the symbol with which the points are to be marked and to terminate the program. A typical screen layout is shown in Figure 10.5.
The marker symbol is selected by the CHOICE device from the menu displayed on the right of the screen. Positions are input by the LOCATOR device; in the screen layout shown, the LOCATOR echo is the pair of cross hairs.
The two devices might be implemented using a mouse with the pressing of one button signalling a LOCATOR event and another giving the CHOICE event. As the echo is a pair of cross hairs extending across the menu, the horizontal cross hair could be used to define the CHOICE position irrespective of where the vertical cross hair is. Consequently, there would be no need to physically move to the right to activate the CHOICE device, it could be done from the current X-position of the mouse, the Y-position controlling the measure of the CHOICE logical input device.
One solution to the problem is the program:
SET EDIT MODE(INSERT)
OPEN STRUCTURE(SPMEG)
POST STRUCTURE(WS, SPMEG, 0.2)
SET MARKER TYPE(2)
SET LOCATOR MODE(WS, DV1, EVENT, ECHO)
SET CHOICE MODE(WS, DV2, EVENT, ECHO)
100 CONTINUE
AWAIT EVENT(60, WST, CLASS, DV)
IF(CLASS .EQ. NONE) GOTO 100
IF(CLASS .EQ. LOCATOR) GOTO 200
GET CHOICE(ST, OCHOIC)
IF(ST .EQ. NOCHOICE) GOTO 100
IF(OCHOIC .EQ. 6) GOTO 300
SET EDIT MODE (REPLACE)
SET ELEMENT POINTER(1)
SET MARKER TYPE(OCHOIC)
GOTO 100
200 CONTINUE
CLOSE STRUCTURE
OPEN STRUCTURE(SPMEG)
SET EDIT MODE(INSERT)
GET LOCATOR(VI, XA(1), YA(1))
POLYMARKER(1, XA, YA)
GOTO 100
300 CONTINUE
CLOSE STRUCTURE
SET EDIT MODE(INSERT)
STOP
C STOP option selected, terminates program
This approach uses a single structure. The first element in the structure is a set marker type element. Subsequent elements are polymarker elements, each of which marks one of the positions input. The structure is:
| 0 | SPMEG |
|---|---|
| 1 | SET MARKER TYPE |
| 2 | POLYMARKER(1, XA, YA) |
| 3 | |
| 4 |
The program structure consists of an initialization section to set up the initial structure (consisting of a single structure element to set the marker type to 2, the plus symbol, which is the default marker symbol) and initialize the logical input devices.
The main body of the program is a loop which removes events from the queue one at a time and performs the appropriate action depending on whether the event is a CHOICE or LOCATOR event. If no input arrives before the timeout expires on AWAIT EVENT, the variable CLASS will be returned with the value NONE, and the program will loop waiting for input to arrive.
For CHOICE input, choice number 6 corresponds to the menu item STOP. If this item is selected, the program terminates. Other choice numbers correspond to the selection of a new marker symbol. The choice numbers correspond to the marker type used by SET MARKER TYPE. The action of the program in processing a choice number in the range 1 to 5 is to replace the set marker type structure element at position 1 in the structure. An alternative way to position the element pointer will be shown in Section 12.4 when INQUIRY functions are described.
Although this solution works, it lacks elegance in certain respects. One structure is always open, but the position of the element pointer and the edit mode at the start of the central loop (label 100) depends on whether the previous event was a CHOICE or a LOCATOR event. This style of programming can lead to programs which are difficult to understand and consequently, to maintain.
An alternative solution is given below. This uses two structures, the first of which (SPMEG1) holds the set marker type element and executes a second structure (SPMEG2) which holds the polymarker elements.
As the second structure is undefined when SPMEG 1 is posted initially, an empty structure will be created. Each time a new polymarker position is entered, the appropriate polymarker structure element is added to the end of the structure SPMEG2.
SET EDIT MODE(INSERT)
OPEN SRUCTURE(SPMEG1)
SET MARKER TYPE(2)
EXECUTE STRUCTURE(SPMEG2)
CLOSE STRUCTURE
SET LOCATOR MODE(WS, DV1, EVENT, ECHO)
SET CHOICE MODE(WS, DV2, EVENT, ECHO)
POST STRUCTURE(WS, SPMEG1, 0.2)
100 CONTINUE
AWAIT EVENT(60, WST, CLASS, DV)
IF(CLASS .EQ. NONE) GOTO 100
IF(CLASS .EQ. LOCATOR) GOTO 200
GET CHOICE(ST, OCHOIC)
IF(ST .EQ. NOCHOICE) GOTO 100
IF(OCHOIC .EQ. 6) GOTO 300
OPEN STRUCTURE(SPMEG1)
SET EDIT MODE (REPLACE)
SET ELEMENT POINTER(1)
SET MARKER TYPE(OCHOIC)
CLOSE STRUCTURE
SET EDIT MODE(INSERT)
GOTO 100
200 CONTINUE
GET LOCATOR(VI, XA(1), YA(1))
OPEN STRUCTURE(SPMEG2)
POLYMARKER(1, XA, YA)
CLOSE STRUCTURE
GOTO 100
300 CONTINUE
C STOP option selected, terminates program
The appropriate structure is opened when each event is processed and then closed before the next event is processed. Edit mode has the value INSERT at the end of processing each event. In general it is important to consider the operations that will be performed upon a structure network when it is designed. Careful design of the structure network can lead to a tidier, easier to understand and more maintainable program structure.
PHIGS provides a useful housekeeping function to manipulate the input queue. It is possible for the operator to input more than one value from an input device when in a particular context the application program only requires one. The function:
FLUSH DEVICE EVENTS(WS, DVCLASS, DV)
removes all events from the specified logical input device from the input queue.
Section 10.1.3 showed the use of a CHOICE logical input device in REQUEST mode to select the component of an object to which a rotation, specified by a VALUATOR logical input device in REQUEST mode was to be applied. Section 10.1.5 showed the use of SAMPLE mode to achieve a smoother interaction with the V ALVA TOR device, and the use of multiple VALUATOR devices to control independent rotations in an object. The example in this section is the same lamp example as used earlier in this Chapter in which the orientation of the base, arm and light can be controlled by the operator. However this time a single VALVA TOR device is used in SAMPLE mode to control the orientation, and a CHOICE device is used in EVENT mode to determine which rotation the VALVA TOR should be coupled to. The program is as follows:
SET VALUATOR MODE(WS, DV1, SAMPLE, NOECHO)
SET CHOICE MODE(WS, DV2, EVENT, ECHO)
SET EDIT MODE (REPLACE)
OCH=1
100 CONTINUE
SAMPLE VALUATOR(WS, DV1, ROT)
GOTO(200, 300, 400), OCH
200 CONTINUE
C lamp orientation
OPEN STRUCTURE(LMP)
SET ELEMENT POINTER(1)
RTRP(ROT*PI/180)
CLOSE STRUCTURE
GOTO 500
300 CONTINUE
C arm orientation
OPEN STRUCTURE(LMP)
SET ELEMENT POINTER(3)
RTPR(ROT*PI/180)
CLOSE STRUCTURE
GOTO 500
400 CONTINUE
C light orientation
OPEN STRUCTURE(ARM)
SET ELEMENT POINTER(3)
RTPR(ROT*PI/180)
CLOSE STRUCTURE
GOTO 500
500 CONTINUE
AWAIT EVENT(0, WST, CLASS, DEV)
IF(CLASS .NE. CHOICE) GOTO 100
GET CHOICE(ST, CH)
IF(ST .EQ. NOCHOICE) GOTO 100
IF(CH .EQ. 4) GOTO 300
OCH=CH
GOTO 100
300 CONTINUE
C STOP option selected
The code structure above has been chosen for ease of explanation, clearly optimizations are possible to reduce the number of OPEN STRUCTURE and CLOSE STRUCTURE calls. For example, if the orientation of the same component is being altered on successive cycles through the central loop, it is an unnecessary overhead to close and reopen the corresponding structure. Also, if the orientation of a component is not changed from the value currently held in the structure, it is an unnecessary overhead to replace the corresponding structure element with an identical element.
On each cycle through the central loop, the VALUATOR device is sampled and a new rotation applied to the currently selected component of the lamp. The variable OCH records the current selection. By default it is the lamp base. The input queue is examined on each cycle through the loop (labelled 500) and if there is a CHOICE event in the queue, the event is retrieved from the queue and if one of the base, arm or light is selected, the variable OCH is set accordingly. If the program termination option is selected, appropriate code not shown here will be executed. The A WAIT EVENT function call has a zero timeout so that the program is not suspended awaiting event input on each cycle. The CLASS returned will be NONE until the operator triggers the CHOICE device. In this case the central loop will be executed again without changing the value of the variable OCH and hence the component whose orientation is being controlled.
The VALUATOR device is used in NOECHO mode because in this case adequate feedback is provided to the operator by the movement of the lamp itself.
One problem with this example is that when a new component is selected by the CHOICE device, the rotation applied to it will be the current value of the VALUATOR device on the next cycle through the loop, which if the operator has not altered the VALUATOR device in the meantime will be the last rotation applied to the previously selected object. This can lead to very unsatisfactory interaction. A way to overcome this problem is described in the next section on device initialization.
In Section 10.1.1, the components of the PHIGS logical input device model were described and it was stated that the application program can control some of the characteristics of each logical input device. This control is provided through the device initialization functions. PHIGS provides a pair of initialization functions for each class of logical input device. The functions for LOCATOR, STROKE, CHOICE, VALUATOR and STRING have the form:
INITIALIZE XXX 3 (WS, DV, initial value, PE, EVOL, data record)
INITIALIZE XXX (WS, DV, initial value, PE, XMN, XMX, YMN, YMX,
data record)
The pair of functions for the PICK logical input device have an additional parameter, path order, after the data record.
The first two parameters identify the device to be initialized. These are followed by one or more parameters defining the initial value of that type of device. The parameter PE defines the prompt and echo type, as described in Section 10.2.2. For the INITIALIZE XXX 3 functions, the parameter EVOL (an array with six elements) defines the echo volume as described in Section 10.2.3. For the INITIALIZE XXX functions, the parameters XMN to YMX define the echo area for the device (see Section 10.2.3). The remaining parameters define the data record for the device (see Section 10.2.4).
In describing the operation of the different operating modes for logical input devices in terms of the PHIGS input model, we have mentioned that when a measure process comes into existence it is initialized to the initial value for the device. The device initialization functions enable the application to set the initial value to which the measure process will be initialized. PHIGS provides a default value if the initialization function is not called.
An example of an initialization function is:
INITIALIZE VALUATOR(WS, DV, VALVE, ...)
When this function is invoked for a particular VALUATOR device, the effect is that the device's measure is initialized to the value specified by VALUE until the initial value is changed by a subsequent invocation of the function.
A good use for initialize is to ensure that the input resulting from one interaction is used as the initial value for the next. This mechanism provides a way to solve the problem raised at the end of Section 10.1.7, where we want an interaction to change the orientation of a component of an object to start from the current orientation. Referring to that example, if the orientation of the lamp, arm and light are stored in variables LMPROT, ARMROT and LHTROT respectively, the code after label 500 could be modified as follows to achieve the desired effect:
500 CONTINUE
AWAIT EVENT(0, WST, CLASS, DEV)
IF(CLASS .NE. CHOICE) GOTO 100
GET CHOICE(ST, CH)
IF(ST .EQ. NOCHOICE) GOTO 100
IF(CH .EQ. 4) GOTO 1000
OCH=CH
GOTO(600, 700, 800), OCH
600 CONTINUE
C base
IROT=LMPROT
GOTO 900
700 CONTINUE
C arm
IROT=ARMROT
GOTO 900
800 CONTINUE
IROT=LHTROT
900 CONTINUE
SET VALUATOR MODE(WS, DV1, REQUEST, NOECHO)
INITIALIZE VALUATOR(WS, DV1, IROT, ...)
SET VALUATOR MODE(WS, DV1, SAMPLE, NOECHO)
GOTO 100
1000 CONTINUE
C STOP option selected
Note that the current interaction with the device has to be terminated and the device restored to REQUEST mode before the INITIALIZE function can be called. When a new interaction with the device in SAMPLE mode is started, the device's measure will be initialized to the value given by the variable IROT.
The initial value specified by the INITIALIZE function must be a valid value when the function is invoked. The one exception to this is that for the LOCATOR and STROKE devices, a view index may be specified which is undefined when the function is invoked. If the view index is still undefined when a measure process comes into existence, the default view index (0) is used to transform the initial point(s).
INITIALIZE LOCATOR has initial value parameters which specify a view index and the X and Y -coordinates of an initial position. INITIALIZE LOCATOR 3 specifies an initial value consisting of a view index and 3D position. The effect of the 2D function is to set the X and Y-coordinates of the initial position to the value specified and to leave the Z-coordinate unchanged. The default value of the latter is implementation dependent. If the Z-value of the initial point is then invalid, the Z-value is set to a value corresponding to the maximum Z-value of the workstation window, which will give a valid position. The INITIALIZE STROKE function has an analogous effect.
It should be noted that some devices may not be able to use the initial value properly, for example for some types of input hardware it may not be possible to initialize the position of cross hairs. In such cases the operator will see the initial echo determined by the device hardware rather than the application program.
In the examples given earlier in this Chapter, several forms of echoing have been used, for example cross hairs for a LOCATOR device and menu for a CHOICE device. The prompt and echo type parameter enables the application program to control the form of prompting and echoing to be used.
Device hardware again poses a problem here in that a particular device may only support a limited range, or indeed only one, form of prompting and echoing. For any logical input device, the prompt and echo type 1 can be specified (parameter PE is given the value 1), for example:
INITIALIZE VALUATOR(WS, DV, IVAL, 1, ...)
The form of the echo corresponding to prompt and echo type 1 is device dependent and is the usual echo for the device. The prompt and echo types for some particular values of PE are given standard meanings by PHIGS and positive values outside this range are reserved for standardization through the Registration process. Zero and negative values of PE have implementation dependent meanings. Not all standardized values of prompt and echo type may be available for a particular device, but when the values are supported, they must have the meanings that have been standardized.
The prompt and echo types that have been standardized by PHIGS are grouped by input class. For all device classes, prompt and echo type 1 is a device dependent technique which must be available (though for the PICK logical input device some guidance is given, see below).
| 2 | crosshair cursor intersecting at the current measure |
| 3 | tracking cross with its centre at the current measure |
| 4 | rubber band line connecting the initial value to the current measure |
| 5 | rectangle with one comer at the initial value and the diagonally opposite corner at the current measure |
| 6 | a digital representation of the coordinates of the current measure |
| 2 | display a digital representation within the echo volume |
| 3 | display a marker at each point of the current STROKE |
| 4 | display a line joining successive points of the current stroke |
| 2 | display a graphical representation of the current measure within the echo volume (for example, a dial, a pointer or a sliding scale) |
| 3 | display a digital representation of the current measure within the echo volume |
| 2 | prompt using hardware built into the physical device (for example, lights associated with buttons) |
| 3 | a display of character strings displayed within the echo volume; the operator selects a string |
| 4 | similar to 3, but the operator types in from a keyboard the character string to be selected |
| 5 | prompt using a structure named in the CHOICE data record. The structure is displayed in the echo volume and the choice numbers correspond to the pick identifiers in the structure |
| 1 | highlight the picked primitive for a short period of time using a device dependent technique which must be available |
| 2 | highlight the contiguous group of primitives with the same pick identifier as the picked primitive, or highlight all primitives in the structure with the same pick identifier as the picked primitive |
| 3 | highlight the whole posted network structure containing the picked primitive |
| 1 | this is the only type defined in PHIGS |
For some prompt and echo types it is appropriate for the application program to be able to specify the region of the workstation display in which the echo will be displayed. An example is VALUATOR prompt and echo type 2 which displays a graphical representation of the current measure, for example as a dial or slider bar, within the echo volume.
An echo volume is specified in the INITIALIZE XXX functions by the parameter EVOL which is an array with six components, specifying the minimum and maximum X, Y and Z-coordinates of the volume XMN, XMX, YMN, YMX, ZMN, ZMX in that order. There is a restriction that:
XMN < XMX, YMN < YMX, ZMN ≤ ZMX
The echo volume is specified in the device coordinates of the workstation. An echo area in device coordinates of the workstation is specified by the parameters XMN, XMX, YMN, YMX of the INITIALIZE XXX functions with the restriction that:
XMN < XMX, YMN < YMX
The effect of these 2D functions is to set the X and Y-limits of the echo volume. The Z-limits remain unchanged.
The input data record is a mechanism for providing additional control information to logical input devices, which is often dependent upon the prompt and echo type. For example, LOCATOR prompt and echo type 4 is a rubber band line. Control over the linestyle with which the rubber band line is drawn can be provided through the input data record.
The precise form of the input data record is dependent upon the language binding. In Fortran, input data records are a CHARACTER*80 array (DATREC) preceded by the size of the array (LDR), for example:
INITIALIZE VALUATOR (WS, DV, VALUE, PE, XMN, XMX, YMN, YMX, LDR, DATREC)
The data record may contain INTEGER, REAL and CHARACTER entities. The routine PACK DATA RECORD is provided by the Fortran language binding to pack data entities into a data record:
PACK DATA RECORD (IL, IA, RL, RA, SL, LSTR, STR, MLDR, ERRIND, LDR, DATREC)
DATREC is the CHARACTER*80 array into which the data record is put by PACK DATA RECORD. MLDR is the size of DATREC, and the output parameter LDR is the number of array elements used in DATREC. ERRIND indicates whether any errors occurred in the packing; a value of 0 indicates successful execution. IA, RA and STR contain data (integers, reals and character strings) to be packed into the data record. IL, RL and SL are the number of integers, reals and strings, respectively. For character strings, SL indicates the number of character strings, and the array, LSTR, indicates the length of each string. The strings themselves are arranged in the single array STR.
The Fortran language binding also provides a routine, UNPACK DATA RECORD, which performs the opposite, unpacking, task.
For some logical input device classes, positions in the data record are reserved for specific items of control information. Entries in the data record fall into four categories:
STROKE, VALUATOR and STRING logical input devices have data record items of the first type:
The VALUATOR data record provides the mechanism for defining the range of the VALUATOR logical input device used in Section 9.8 and subsequent examples. The device provides angles in the range 0° to 360°, thus the low value would be set to 0 and the high value to 360. The low and high values of the range are specified by the first two elements in the real array passed to PACK DATA RECORD. The range of a VALUATOR device, DV, could be set to 0 to 360 as follows:
IL=O
RL=2
RA(1)=0
RA(2)=360
SL=0
PACK DATA RECORD(IL, IA, RL, RA, SL, LSTR, STR,
MLDR, ERRIND, LDR, DATREC)
INITIALIZE VALUATOR(WS, DV, IV AL, PET, XMN, XMX,
YMN, YMX, LDR, DATREC)
The STROKE and STRING logical input devices have data record items of the second type, concerned with editing, but these are beyond the scope of this book.
LOCATOR, STROKE and CHOICE devices have data record entries of the third type, for example for the CHOICE device, prompt and echo type 3, the list of CHOICE strings (menu items) is specified in position 1 of the data record. For prompt and echo type 5, the structure identifier is specified in position 1 and the list of pick identifiers to be associated with choice numbers is specified in position 2.
For more detailed information on input data records, the reader is referred to the documentation of the PHIGS implementation in use. If portability between PHIGS implementations is important, care should be taken in the use of facilities accessed through data records.
The INITIALIZE PICK 3 and INITIALIZE PICK functions have an additional parameter, PORDER, after the data record. This parameter determines the order in which a pick path is to be returned to the application program by the REQUEST PICK, SAMPLE PICK and GET PICK functions. Two values are possible, TOPFIRST and BOTTOMFIRST. The examples in Section 9.7 used TOPFIRST order.
For TOPFIRST order, the structure specified in any pick path item is the parent of the structure specified in the subsequent item. The first example in Section 9.7 was the pick path:
| Structure | Pick Identifier | Element Position |
|---|---|---|
| WKNV | 0 | 2 |
| DESK | 0 | 1 |
| LG | 0 | 3 |
| BLOT | 0 | 1 |
The structure WKNV is a parent of DESK, DESK is a parent of LG, and LG is a parent of BLOT.
If the order had been BOTTOMFIRST, the pick path would have been returned in the reverse order:
| Structure | Pick Identifier | Element Position |
|---|---|---|
| BLOT | 0 | 1 |
| LG | 0 | 3 |
| DESK | 0 | 1 |
| WKNV | 0 | 2 |
In this order, the structure specified in any pick path item is a child of the structure specified in the subsequent item. Thus BLOT is a child of LG, LG is a child of DESK and so on.
If only part of the pick path is to be returned by specifying a DEPTH (see Section 9.7 ) less than the maximum possible, the number of entries returned will be counted from the top so that the set of entries returned will differ depending on whether TOPFIRST or BOTTOMFIRST is defined.
The discussion of EVENT input has dealt with the case that a single event report is added to the input queue each time the operator fires a trigger. It is possible for more than one event to enter the queue per trigger firing and this is discussed next. The input queue is of finite size and Section 10.3.2 deals with overflow of the input queue.
It is possible for any trigger to be shared between a number of logical input devices. A typical example is a LOCATOR and CHOICE device, both of which are mapped onto a multi-button mouse. Clicking any button triggers the LOCATOR device. The CHOICE device is triggered by any button click, and the choice number corresponds to the individual buttons; for a three button mouse, the left-hand button might be choice 1, the centre button choice 2 and the right-hand button choice 3.
Suppose both the LOCATOR and CHOICE device are enabled in EVENT mode. If the operator clicks the left-hand button, two event reports will be added to the input queue: a LOCATOR event report and a CHOICE event report. The former contains the LOCATOR measure when the trigger fired and the latter the CHOICE measure (the choice number corresponding to the button clicked). The two events are referred to as simultaneous events because they originate from the same trigger firing. The two events enter the input queue consecutively, but in no particular order.
The function:
INQUIRE MORE SIMULTANEOUS EVENTS(ERRIND, ANYMORE)
enables the application program to discover which events originated from the same trigger action. The parameter ANYMORE can return the values MORE and NOMORE. If the next event in the input queue was generated simultaneously with the last event removed, the value MORE is returned.
If the next event was generated by a different trigger firing, the value NOMORE is returned.
The input queue is likely to be of finite size in any PHIGS implementation and it is possible that the operator may add events to the queue faster than the application removes them. Thus the input queue may overflow and input data will be lost.
When the input queue overflows, no more event reports are added to the queue until it has been completely emptied by the application program. Feedback would normally be given to the operator that events are not being added to the input queue.
The next time the application program attempts to remove input from the queue after overflow has occurred, AWAIT EVENT will report an error. This can be trapped by replacing the ERROR HANDLING procedure as described in Section 12.6.
Alternatively the inquiry function:
INQUIRE INPUT QUEUE OVERFLOW(ERRIND, WS, CLASS, DV)
can be used. If the error indicator, ERRIND, returns the value 0, input queue overflow has occurred. If the value 257 is returned, input queue overflow has not occurred. Normally this function would be called immediately after A WAIT EVENT. If overflow has occurred, the remaining parameters indicate which logical input device was attempting to add the event report which caused the overflow.
Event reports in the queue when overflow occurs are valid event reports and can be removed in the normal way by calling A WAIT EVENT. Only when the queue is empty (A WAIT EVENT returns the device class NONE), will new events start to be added to the queue. Events can also be removed from the queue using the FLUSH DEVICE EVENTS function described in Section 10.1.6.
Incremental spatial search is a special type of inquiry function on the contents of the central structure store (CSS). It is described in this Chapter because it has some similarities to pick input. The INCREMENTAL SPATIAL SEARCH function searches the CSS from a specified position, looking for a structure element which generates an output primitive which satisfies a spatial search criterion. To satisfy the search criterion, some part of the output primitive must fall within a specified region of world coordinate space.
There are two forms of the incremental spatial search function, a full 3D version and a 2D version:
INCREMENTAL SPATIAL SEARCH 3 (SRPX, SRPY, SRPZ, SDIST, SPTHSZ, SPATH, MCLIPF, SRCHCI, NFLN, NFLISX, NFLIS, NFLESX, NFLES, IFLN, IFLISX, IFLIS, IFLESX, IFLES, IPTHSZ, ERRIND, FPTHSZ, FPATH) INCREMENTAL SPATIAL SEARCH (SRPX, SRPY, SDIST, SPTHSZ, SPATH, MCLIPF, SRCHCI, NFLN, NFLISX, NFLIS, NFLESX, NFLES, IFLN, IFLISX, IFLIS, IFLESX, IFLES, IPTHSZ, ERRIND, FPTHSZ, FPATH)
The parameters SRPX, SRPY (and SPRZ in the 3D function) and SDIST in each function define the search region. SRPX, SRPY, SRPZ is a 3D or 2D position and SDIST is search distance, both expressed in world coordinates. The search region is a sphere in world coordinates; for the 2D function, the position is expanded to 3D by the addition of a Z-coordinate with value 0. SPATH is the starting path, which defines the position in the CSS at which the search will commence. SPTHSZ is the number of elements in the path. The starting path is defined in a similar way to pick path; it is a list of items, each of which consists of a structure identifier and an element position.
MCLIPF is a flag which can takes the values CLIP or NOCLIP. If the value CLIP is given, any modelling clipping operations defined in the CSS will be applied to primitives before they are tested against the search region. Thus only portions of output primitives not removed by modelling clipping are considered by the search. If the flag has the value NOCLIP, all modelling clipping is ignored.
The parameter SRCHCI specifies a search ceiling index. This index defines a position in the search path. The search will start at the position in the CSS identified by the starting path and will continue until either a structure element satisfying the search is found, or the end of the structure pointed at by the ceiling index is reached.
NFLN to NFLES and IFLN to IFLES specify a normal filter list and an inverted filter list respectively. Each filter consists of a pair of sets of names, the inclusion set and the exclusion set, exactly like the invisibility, highlighting and pick filters. To be considered for testing against the search criterion, a primitive's name set must be accepted by all the filters in the normal list and rejected by all the filters in the inverted filter list.
The binding of the filter lists is rather complicated and will be illustrated by the normal filter list. NFLN is the number of normal filters. The names in the inclusion sets of these filters are specified in the array NFLIS. The array NFLISX is an array of pointers into NFLIS, which specify the element in NFLIS at which each inclusion set ends.
Similarly, the names in the exclusion sets are specified in the array NFLES. NFLESX is an array of pointers to the end of each exclusion set. The inverted filter list is specified in an analogous manner.
ERRIND is an error indicator which has the value 0 if the function terminates successfully. If ERRIND has a non-zero value, the value indicates the reason why the function did not terminate successfully.
FPATH is the found path, which defines the position in the CSS of the structure element generating the output primitive which satisfied the search criterion. The found path is specified in exactly the same way as the starting path. If the search ceiling is reached before an output primitive satisfying the search criterion is found, a null found path is returned.
Spatial search is incremental in that the found path can be provided as a starting path for a further invocation of the function and the search will continue from that point until a further output primitive satisfying the search criterion is found or the search ceiling is reached.
An example of incremental spatial search is given, based on the structure network in Figure 10.6 and the work environment it represents shown in Figure 10.7. The circle at the bottom left-hand comer of the blotter in Figure 10.7 is a 2D projection of the search region.
The primitives representing the large desk have a name set containing the single name NL and the primitives representing the blotter have name sets containing the names NL and NB. The entry +(NL) in the structure network represents the structure element generated by the code:
NMSETA(1)=NL
ADD NAMES TO SET(1, NMSETA)
which has the effect of adding the name NL to the current name set when the structure is traversed.
Suppose the incremental spatial search function is invoked with filter lists having the following entries:
| Normal Filter List | Inverted Filter List | ||
|---|---|---|---|
| Inclusion | Exclusion | Inclusion | Exclusion |
| NL, NB | EMPTY | EMPTY | EMPTY |
and the starting path is:
| Structure | Element Position |
|---|---|
| WKNV | 1 |
Primitives representing the desk and the blotter will be considered by the search because the name sets of each are accepted by all the filters in the normal filter list (none have elements in common with the exclusion list and the desk primitives have NL in common with the inclusion set and blotter primitives have both NL and NB in common), and rejected by all the filters in the inverted filter list (none has any names in common with the inclusion set and so will be rejected). The first position encountered represents the border of the large desk. This falls within the search region and so the found path is:
| Structure | Element Position |
|---|---|
| WKNV | 2 |
| DESK | 1 |
| LG | 2 |
If the search is restarted using the found path as starting path, the next primitive encountered represents the outline of the blotter. This also satisfies the search criterion and so the found path returned is:
| Structure | Element Position |
|---|---|
| WKNV | 2 |
| DESK | 1 |
| LG | 4 |
| BLOT | 2 |
Here we have assumed that the search ceiling index is 1, so that the search terminates at the end of the structure WKNV.
Suppose in the second case the search ceiling index is 3 (terminate at the end of structure LG) and the filter lists contain the entries
| Normal Filter List | Inverted Filter List | ||
|---|---|---|---|
| Inclusion | Exclusion | Inclusion | Exclusion |
| NL, NB | EMPTY | NB | EMPTY |
Starting the search after the structure element generating the boundary of the desk, the search fails to find any primitives satisfying the search criterion. This time the primitives representing the blotter fail to satisfy the search criterion because their name sets do not satisfy the filter conditions. The name set (NL, NB) is accepted by the normal filter list. However, this name set is also accepted by the inverted filter list (the name NB is common to the name set and inclusion set) and this fails the condition to be eligible for a search, a primitive's name set must be rejected by the inverted filter list.