Updating the Scene

Visualize is a retained mode (as opposed to an immediate mode) graphics system, which means it retains an internal database of the scene it is expected to render. During a display update, Visualize traverses the scene graph and ensures the picture on the screen or specified output context matches the contents of the scene graph. It follows that changes to the scene graph as a result loading a file, altering geometry, or modifying segment attributes are not reflected until you request an update by calling HPS::WindowKey::Update or HPS::WindowKey::UpdateWithNotifier. All display contexts, including offscreen windows and hardcopy contexts, derive from HPS::WindowKey, so the same method is used to update a scene regardless of the type of output device. In some cases, Update is called indirectly:

• If you are using the view hierarchy classes, the scene is updated in a slightly different way. See this page on view hierarchy for details.

• If you are utilizing an operator, each operator method will typically call HPS::WindowKey::Update inside each of its mouse, keyboard, or touch screen event handlers, so there is no need to manually call it again. See our section on operators and refer to each operator’s reference manual entry for details.

Update Notification

Visualize will perform an asynchronous update by default, so the call to the Update method will return immediately even though the scene may not be finished rendering. However, it is often necessary to know when rendering is complete. HPS::UpdateNotifier allows you to be notified when the update is completed:

C++C#

    HPS::UpdateNotifier notifier = myWindowKey.UpdateWithNotifier();
    notifier.Wait();

    // when you get to this point, the scene is rendered

It may also be desirable to know the status of an update before it finishes. In this case, you can use the UpdateNotifier to inform you of the update progress.

C++C#

    HPS::UpdateNotifier notifier = myWindowKey.UpdateWithNotifier();
    HPS::Window::UpdateStatus status = notifier.Status();

    if (status == HPS::Window::UpdateStatus::InProgress) {
        // update is in progress
    }

    if (status == HPS::Window::UpdateStatus::Completed) {
        // update is finished
    }

For many situations, UpdateWithNotifier will be the preferred choice because once HPS::UpdateNotifier::Wait returns, you are guaranteed that the Visualize database matches what is shown on the screen. However, for some situations, asynchronous updates are recommended. For example, during file I/O, it is probably better to keep other parts of the program responsive and not waiting for a long operation to finish.

Controlling Updates

Normally, when you make a change to the scene graph (by deleting geometry, moving objects, etc.) Visualize marks the modified segments as requiring a redraw. Upon the next display update, Visualize traverses the list of segments requiring redraws. By default, Visualize will draw as little as possible to ensure a correctly drawn scene is displayed. This could mean overlaying geometry over an old buffer, simply redrawing the back buffer, or doing a complete update. The end result is that after the update call, the picture on the screen matches the picture described by the scene graph.

Visualize offers some control over how updates are performed, in order to ensure a correct result or boost performance in specific situations. Updates can be manually controlled by passing one of the HPS::Window::UpdateType enums to the HPS::WindowKey::Update method.

C++C#

    myWindowKey.Update(); // simply call this if you want a default update
    myWindowKey.Update(
        HPS::Window::UpdateType::Complete); // this might be necessary to call in a GUI toolkit's 'window expose' event

Other types of updates are described in the reference manual and are generally not required except in special situations.

Timed Updates

It may be desirable to have Visualize spend a fixed amount of time for an update. The HPS::WindowKey::Update function accepts an optional argument that represents a time value in seconds. The value imposes a hard limit on how long Visualize will spend rendering before aborting and starting on the next frame.

C++C#

    // max 0.75 seconds spent on rendering
    myWindowKey.Update(HPS::Window::UpdateType::Default, 0.75);

Timed-updates are internally utilized by Visualize’s fixed framerate support, to ensure that a fixed number of frames are drawn per second during user interaction. Fixed framerate is covered in this section.