As the class tree in Figure 12-1 suggests, sensors are placed in one of two queues:

When processing of either queue begins, all sensors in that queue are processed once, in order (see “Using a Field Sensor”).

The following discussion of data and timer sensors uses a few new terms.

The following sequence describes the necessary steps for setting up a data sensor:

Callback functions, as their name suggests, allow Inventor to call back to the application when some predefined event occurs. A callback function usually takes a single argument of type void* that can be used to pass extra user-defined data to the function. Callback functions used by sensors also have a second argument of type SoSensor*. This argument is useful if the same callback function is used by more than one sensor. The argument is filled with a pointer to the sensor that caused the callback.

In C++, a sensor callback function can be declared as a static member function of a class. In this case, because static functions have no concept of this, you need to explicitly pass an instance of the class you want to modify as user data:

colorSensor->setData(this);

Nonstatic C++ member functions are not suitable for use as callback functions.

Classes derived from SoDelayQueueSensor use priorities to maintain sorting in the delay queue. The following methods are used to set and obtain the priority of a given sensor:

A sensor with a priority of 0 has the highest priority. It triggers as soon as the change to the scene graph is complete. If two sensors have the same priority, there is no guarantee about which sensor will trigger first.

The SoXtRenderArea has a redraw data sensor with a default priority of 10000. You can schedule other sensors before or after the redraw by choosing appropriate priorities.

For example, to set the priority of a sensor so that it is triggered right before redraw:

SoNodeSensor   *s;
SoRenderArea   *renderArea;
s->setPriority(renderArea->getRedrawPriority() - 1);

When data in the sensor's field, node, or path changes, the following things happen:

Example 12-1 shows attaching a field sensor to the position field of a viewer's camera. A callback function reports each new camera position.

#include <Inventor/SoDB.h>
#include <Inventor/Xt/SoXt.h>
#include <Inventor/Xt/viewers/SoXtExaminerViewer.h>
#include <Inventor/nodes/SoCamera.h>
#include <Inventor/nodes/SoSeparator.h>
#include <Inventor/sensors/SoFieldSensor.h>

// Callback that reports whenever the viewer's position changes.
static void
cameraChangedCB(void *data, SoSensor *)
{
   SoCamera *viewerCamera = (SoCamera *)data;

   SbVec3f cameraPosition = viewerCamera->position.getValue();
   printf("Camera position: (%g,%g,%g)\n",
            cameraPosition[0], cameraPosition[1],
            cameraPosition[2]); 
}

main(int argc, char **argv)
{
   if (argc != 2) {
      fprintf(stderr, "Usage: %s filename.iv\n", argv[0]);
      exit(1);
   }

   Widget myWindow = SoXt::init(argv[0]);
   if (myWindow == NULL) exit(1);

   SoInput inputFile;
   if (inputFile.openFile(argv[1]) == FALSE) {
      fprintf(stderr, "Could not open file %s\n", argv[1]);
      exit(1);
   }
   
   SoSeparator *root = SoDB::readAll(&inputFile);
   root->ref();

   SoXtExaminerViewer *myViewer =
            new SoXtExaminerViewer(myWindow);
   myViewer->setSceneGraph(root);
   myViewer->setTitle("Camera Sensor");
   myViewer->show();

   // Get the camera from the viewer, and attach a 
   // field sensor to its position field:
   SoCamera *camera = myViewer->getCamera();
   SoFieldSensor *mySensor = 
            new SoFieldSensor(cameraChangedCB, camera);
   mySensor->attach(&camera->position);

   SoXt::show(myWindow);
   SoXt::mainLoop();
}

You can use one of the following methods to obtain the field, node, or path that initiated the notification of any data sensor:

These methods work only for immediate (priority 0) sensors.

The trigger path is the chain of nodes from the last node notified down to the node that initiated notification. To obtain the trigger path, you must first use setTriggerPathFlag() to set the trigger-path flag to TRUE since it's expensive to save the path information. You must make this call before the sensor is notified. Otherwise, information on the trigger path is not saved and getTriggerPath() always returns NULL. (By default, this flag is set to FALSE.) The trigger field and trigger node are always available. Note that getTriggerField() returns NULL if the change was not to a field (for example, addChild() or touch() was called).

Example 12-2 shows using getTriggerNode() and getTriggerField() in a sensor callback function that prints a message whenever changes are made to the scene graph.

#include <Inventor/SoDB.h>
#include <Inventor/nodes/SoCube.h>
#include <Inventor/nodes/SoSeparator.h>
#include <Inventor/nodes/SoSphere.h>
#include <Inventor/sensors/SoNodeSensor.h>

// Sensor callback function:
static void
rootChangedCB(void *, SoSensor *s)
{
   // We know the sensor is really a data sensor:
   SoDataSensor *mySensor = (SoDataSensor *)s;
    
   SoNode *changedNode = mySensor->getTriggerNode();
   SoField *changedField = mySensor->getTriggerField();
    
   printf("The node named '%s' changed\n",
            changedNode->getName().getString());

   if (changedField != NULL) {
      SbName fieldName;
      changedNode->getFieldName(changedField, fieldName);
      printf(" (field %s)\n", fieldName.getString());
   } 
   else 
      printf(" (no fields changed)\n");
}

main(int, char **)
{
   SoDB::init();

   SoSeparator *root = new SoSeparator;
   root->ref();
   root->setName("Root");

   SoCube *myCube = new SoCube;
   root->addChild(myCube);
   myCube->setName("MyCube");

   SoSphere *mySphere = new SoSphere;
   root->addChild(mySphere);
   mySphere->setName("MySphere");

   SoNodeSensor *mySensor = new SoNodeSensor;

   mySensor->setPriority(0);
   mySensor->setFunction(rootChangedCB);
   mySensor->attach(root);

   // Now, make a few changes to the scene graph; the sensor's
   // callback function will be called immediately after each
   // change.
   myCube->width = 1.0;
   myCube->height = 2.0;
   mySphere->radius = 3.0;
   root->removeChild(mySphere);
}

The following sequence describes the necessary steps for setting up one-shot and idle sensors:

Note that these sensors must be scheduled explicitly. Use the unschedule() method to remove a sensor from the queue.

An SoOneShotSensor invokes its callback once whenever the delayed sensor queue is processed. This sensor is useful for a task that does not need to be performed immediately or for tasks that should not be performed immediately (possibly because they are time-consuming). For example, when handling events for a device that generates events quickly (such as the mouse), you want to be able to process each event quickly so that events don't clog up the event queue. If you know that a certain type of event is time-consuming, you can schedule it with a one-shot sensor. For example:

handleEvent(SoHandleEventAction *action)
{ 
   //Check for correct event type ...
   .
   .
   .
   // Remember information from event for later processing
   currentMousePosition = event->getPosition();

   // Schedule a one-shot sensor to do hard work later
   SoOneShotSensor oneShot = new SoOneShotSensor(
         OneShotTriggerCallback, NULL);
   oneShot->schedule();
}
void OneShotTriggerCallback(void *userData, SoSensor *) 
{
   // Do lengthy operation based on current mouse position;
}

Note that sensors that invoke their callback one time only, such as SoOneShotSensor, SoIdleSensor, and SoAlarmSensor, continue to exist after their callback has been executed, but they do not trigger again unless they are rescheduled. Use the unschedule() method to stop any sensor from invoking its callback when it is scheduled.

The following example uses an SoOneShotSensor to delay rendering until the CPU is idle.

SoOneShotSensor *renderTask;

main() {
   ...
   renderTask = new SoOneShotSensor(doRenderCallback, NULL);
   // ... set up events, UI, which will call changeScene()
   // routine.
}

void
changeScene()
{
   // ... change scene graph ...
   renderTask->schedule();
}

void
doRenderCallback(void *userData, SoSensor *)
{
   // ... does rendering ...
}

An SoIdleSensor invokes its callback once whenever the application is idle (there are no events or timers waiting to be processed). Use an idle sensor for low-priority tasks that should be done only when there is nothing else to do. Call the sensor's schedule() method in its callback function if you want it to go off repeatedly (but beware, since this keeps the CPU constantly busy). Note that idle sensors may never be processed if events or timers happen so often that there is no idle time; see “Processing the Sensor Queues” for details.

The following sequence describes the necessary steps for setting up timer-
queue sensors:

Timing parameters (when and how often the sensor is triggered) should not be changed while a sensor is scheduled. Use the unschedule() method to remove a sensor from the queue, change the parameter(s), and then schedule the sensor again.

An SoAlarmSensor, like an alarm clock, is set to go off at a specified time. When that time is reached or passed, the sensor's callback function is invoked. A calendar program might use an SoAlarmSensor, for example, to put a flag on the screen to indicate that it's time for your scheduled 2 o'clock meeting.

Use one of the following methods to set the time for this sensor:

The time is specified using the SbTime class, which provides several different formats for time. Use the getTime() method of SoAlarmSensor to obtain the scheduled time for an alarm sensor.

Example 12-3 shows using an SoAlarmSensor to raise a flag on the screen when one minute has passed.

static void
raiseFlagCallback(void *data, SoSensor *)
{
   // We know data is really a SoTransform node:
   SoTransform *flagAngleXform = (SoTransform *)data;
   
   // Rotate flag by 90 degrees about the z axis:
   flagAngleXform->rotation.setValue(SbVec3f(0,0,1), M_PI/2);
}

{
   ...

   SoTransform *flagXform = new SoTransform;

   // Create an alarm that will call the flag-raising callback:
   SoAlarmSensor *myAlarm =
       new SoAlarmSensor(raiseFlagCallback, flagXform);
   myAlarm->setTimeFromNow(60.0);
   myAlarm->schedule();
}

An SoTimerSensor is similar to an SoAlarmSensor, except that it is set to go off at regular intervals—like the snooze button on your alarm clock. You might use an SoTimerSensor for certain types of animation, for example, to move the second hand of an animated clock on the screen. You can set the interval and the base time for an SoTimerSensor using these methods:

Before changing either the interval or the base time, you must first unschedule the sensor, as shown in Example 12-4.

Example 12-4 creates two timer sensors. The first sensor rotates an object. The second sensor goes off every 5 seconds and changes the interval of the rotating sensor. The rotating sensor alternates between once per second and ten times per second. (This example is provided mainly for illustration purposes. It would be better (and easier) to use two engines to do the same thing (see Chapter 13).

// This function is called either 10 times/second or once every
// second; the scheduling changes every 5 seconds (see below):
static void
rotatingSensorCallback(void *data, SoSensor *)
{
   // Rotate an object...
   SoRotation *myRotation = (SoRotation *)data;
   SbRotation currentRotation = myRotation->rotation.getValue();
   currentRotation = SbRotation(SbVec3f(0,0,1), M_PI/90.0) *
            currentRotation;
   myRotation->rotation.setValue(currentRotation);
}

// This function is called once every 5 seconds, and
// reschedules the other sensor.
static void
schedulingSensorCallback(void *data, SoSensor *)
{
   SoTimerSensor *rotatingSensor = (SoTimerSensor *)data;
   rotatingSensor->unschedule();
   if (rotatingSensor->getInterval() == 1.0)
      rotatingSensor->setInterval(1.0/10.0);
   else 
      rotatingSensor->setInterval(1.0);
      rotatingSensor->schedule();
}

{
   ...

   SoRotation *myRotation = new SoRotation;
   root->addChild(myRotation);

   SoTimerSensor *rotatingSensor =
      new SoTimerSensor(rotatingSensorCallback, myRotation);
   rotatingSensor->setInterval(1.0); //scheduled once per second
   rotatingSensor->schedule();

   SoTimerSensor *schedulingSensor =
   new SoTimerSensor(schedulingSensorCallback, rotatingSensor);
   schedulingSensor->setInterval(5.0); // once per 5 seconds
   schedulingSensor->schedule();
}

The following descriptions apply only to applications using the Inventor Component Library with the Xt toolkit. Other window system toolkits may have a different relationship between processing of the different queues. If you aren't interested in the details of how timers are scheduled, you can skip this section.

The general order of processing is event queue, timer queue, delay queue. A slight deviation from this order arises because the delay queue is also processed at regular intervals, whether or not there are timers or events pending. The sequence can be described as follows:

SoXt main loop calls XtAppMainLoop:

BEGIN:
If there's an event waiting:
Process all pending timers.
Process the delay queue if the delay queue time-out is
         reached.
Process the event.
Go back to BEGIN.
else (no event waiting)
if there are timers,
   Process timers.
   Go back to BEGIN.
else (no timers or events pending)
Process delay queue.
Go back to BEGIN.

When the timer queue is processed, the following conditions are guaranteed:

For example, in Figure 12-2, at time A after the redraw, the timer queue is processed. Three timers have been scheduled in the queue (timers 0, 1, and 2). Timers 0 and 1 are ready to go off (their trigger time has already passed). Timer 2 is set to go off sometime in the future. The sequence is as follows:

The delay queue is processed when there are no events or timer sensors pending or when the delay queue's time-out interval elapses. By default, the delay queue times out 30 times a second. You can change this interval with the SoDB::setDelaySensorTimeout() method. Idle sensors are ignored when the delay sensor causes processing of the delay queue (because the CPU is not really idle under this condition).

When the delay queue is processed, the following conditions are guaranteed: