The Graphics Display Kit

2

Tutorials

This chapter presents a series of tutorials that provide fully worked examples of how to build applications with and use some of the Graphics Display Kit's most important features.

This chapter discusses:

• Before you begin, Section 2.1
• Creating a view, Section 2.2
• Creating an object, Section 2.3
• Creating a view's window, Section 2.4
• Adding to a view's pull-down menus, Section 2.5
• Viewing multiple objects from one set of data, Section 2.6
• Creating an object hierarchy, Section 2.7
• Creating a custom transformation editor, Section 2.8
• Adding interactors to a view, Section 2.9
• Modifying a camera for annotation, Section 2.10
• Adding a second view window, Section 2.11
• Using accelerate mode in a view, Section 2.12

2.1 Before you begin

2.1.1 Essential parts of an application

A Graphics Display Kit application consists of, at minimum, a view, a window in which to render the view, and one or more Graphics Display Kit (GD) objects:

Essential parts of an application	Description
View	Defines a view of the connected Graphics Display Kit objects, including cameras, lights, a virtual palette, and other attributes
Window	Defines the window in which the view appears
GD object	Defines a renderable Graphics Display Kit object, including data, modes, properties, and other attributes

Keep this picture in mind throughout the tutorials. A Graphics Display Kit application is not complete until it has at least these parts. An application can have other parts too, such as pull-down command lists and editors.

2.1.2 Two ways to build each part of an application

The Graphics Display Kit generally provides two ways to build each part (window, view, objects, etc.) of an application:

• From the ground up, by assembling low-level objects called base types.
• With an application component. An application component is a macro object that packages a set of Graphics Display Kit capabilities. For example, Mscene3D is a macro object that defines a view, including a 3D camera, a set of lights, and other view-related base-type objects.

When the goal of a tutorial is to focus on a particular part of an application, we build that part from the ground up, and build the other parts with application components.

In your applications, you typically do the same thing. You determine which parts of your application you can build with application components and which you need to assemble from the ground up. You can customize application components and construct your own.

2.1.3 Completed tutorials

The tutorial applications are available, in completed form, in Libraries.Examples.Graphics_Display.

2.1.4 Location of objects

Most of the objects in these tutorials are located in Libraries.Main and Libraries.Graphics_Display. The location of other objects is usually included in the text or accompanying diagrams. If you have trouble locating an object, you can use the Network Editor's object finder (Object->Find in All Libraries...).

2.2 Creating a view

In this tutorial, we create a view from the ground up.

Here is what a view definition looks like, at the base-type level, along with the Graphics Display Kit objects and window that connect into the view:

2.2.1 Starting up

1. Start AVS/Express and choose Application from the startup dialog, or if you have an existing AVS/Express session, start a new (Default)Application by selecting the appropriate entry from the File->New Application... dialog, or clear an existing Application workspace, as appropriate.

2.2.2 Create the view

The view we'll build consists of DefaultView (the view's "root" object), DefaultCamera3D, DefaultLightOn, DefaultLightInfo, and BestVirtPal. These define, respectively, root information for the view, a camera, a light, basic lighting information (such as ambient lighting), and a virtual palette. Notice how a view can have its own virtual palette; multiple views can also share virtual palettes.

2. Instance into the DefaultApplication workspace the following objects: DefaultCamera3D, DefaultLightOn, DefaultLightInfo, DefaultView, and BestVirtPal. Then connect them as shown in the diagram below.

2.2.3 Create a window

A Graphics Display Kit application requires a window in which to render the view. We create a window using the application component ViewUI. ViewUI defines a window, complete with a window panel and a UIrenderView panel in which the view appears.

3. Instance ViewUI, then connect it to DefaultView, as shown in the diagram below.

Note that ViewUI can also be found in Full_Library.Components in the Graphics_Display collection. The easiest way to find an object in Full_Library is with the Find pop-up command.

When we instance ViewUI, an empty window appears. When we connect ViewUI to DefaultView, a black window appears inside the window. This is where the data is rendered.

2.2.4 Render an object

Finally, we need to supply the Graphics Display Kit with an object to render. We can do this with Arrow2. It makes the data available both as a field (first output port) and as a Graphics Display Kit object (second output port), ready for rendering. We use the second output port.

4. Instance Arrow2 and connect it to DefaultCamera3D, as shown in the diagram below. 

The application renders an arrow in the view's window.

Notice that a Graphics Display Kit object connects to a camera (either DefaultCamera3D or DefaultCamera2D), which in turn connects to a view. You can connect several objects to a camera, and you can connect several 2D and 3D cameras to a view.

2.2.5 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CreateView.

5. Delete the application.

2.3 Creating an object

In this tutorial, we create a Graphics Display Kit object from the ground up.

Here is what the definition of a Graphics Display Kit object looks like, at the base-type level. Most of the base types defining a Graphics Display Kit object are optional. In the diagram, the object is connected into Uviewer3D, a macro that defines a full-featured renderer, including a view and a rendering window.

2.3.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, or, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.3.2 Create the data object

The data object we'll build consists of DefaultObject (the data object's "root" object), DefaultModes, and DefaultProps.

2. Instance into the SingleWindowApp workspace the following objects: DefaultModes, DefaultProps, and DefaultObject. Connect them as shown in the diagram below. 

2.3.3 Create a view and window

A Graphics Display Kit application requires a view for the Graphics Display Kit object and a window in which to render the view. For this tutorial, we create both with Uviewer3D. Uviewer3D is a full-featured 3D viewer, complete with a top-level object, a window, a view, and related editors.

3. Instance Uviewer3D and connect it to DefaultObject, as shown in the diagram below. 

When we instance Uviewer3D, a window with a black window inside it appears. This is where the data is rendered.

2.3.4 Render an object

Finally, we need to supply the Graphics Display Kit with an object to render. We can do this with Arrow1. It makes the data available both as a field (first output port) and as a Graphics Display Kit object (second output port), ready for rendering. We use the second output port.

4. Instance Arrow1 and connect it to DefaultObject, as shown in the diagram below. 

The application renders an arrow in the view's window.

2.3.5 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CreateObject.

5. Delete the application.

2.4 Creating a view's window

In this tutorial, we create a view's window.

Here is the minimum view window definition. In the diagram, the UIshell is connected to a UIrender View which is connected to the DefaultView, a view's root object.

2.4.1 Starting up

1. Start AVS/Express and choose ModuleStack from the startup dialog, or if you have an existing AVS/Express session, start a new ModuleStack application by selecting the appropriate entry from the File->New Application... dialog, or clear an existing ModuleStack workspace, as appropriate.

2.4.2 Instance and connect the UI objects

A window for a Graphics Display Kit application consists of, at minimum, a UIshell object and a UIrenderView object. Both are defined in the User Interface Kit.

2. Instance into the ModuleStack workspace the objects UIshell and UIrenderView, then connect them as shown in the diagram below. 

2.4.3 Create a view

A Graphics Display Kit application requires a view. For this tutorial, we create the view using the application component Mscene3D. Mscene3D defines a 3D view, complete with root object, related base objects, and a top-level object.

3. Instance Mscene3D, then connect UIrenderView to it, as shown in the diagram below. 

When we connect UIrenderView to Mscene3D, a black window appears inside the window we created. This is where the data is rendered.

2.4.4 Create an object and generate field data

Finally, we need to create a Graphics Display Kit object with field data. We can create both with Read Geom, using the second output port.

4. Instance Read Geom and connect it to Mscene3D, as shown in the diagram below.

5. We're now ready to specify a data file. In the ModuleStack window, select the Read Geom pull-down command. Select the Browse button. A dialog box appears. Select teapot.geo, then select the OK button.

The application renders the teapot in the view's window.

2.4.5 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CreateViewUI.

6. Delete the application. 

2.5 Adding to a view's pull-down menus

In this tutorial, we will add entries to the pull-down menu on the view's window.

Here is the basic structure of a command list. In the diagram, the command list is connected to UIshell, which defines the application's window:

Here is an illustration of what the resulting menu bar might look like:

This is just one of many possible configurations. For example, you can connect multiple UIcmdList objects to the UIcmdList that creates the menu bar. This gives you a menu bar with multiple items on it. You can use other UI objects in addition to UIcmd. For example, another UIcmdList object creates a cascading pull-down menu. A UIoption object creates a pull-down command that works like an option box.

2.5.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.5.2 Create a window and a view

We create the application's window and view with the application component Uscene3D.

2. Instance into the SingleWindowApp workspace the object Uscene3D. Uscene3D can be found in Libraries.Accessories.Graphics.Modules.

When we instance Uscene3D, a black window appears inside the SingleWindowApp. This is where the data is rendered.

2.5.3 Create view and light editors

We want our application to have view and light editors that pop up when the user selects the appropriate pull-down command. For this tutorial, we create the editors using the application components Uview_editor and Ulight_editor. Each defines an edit object and a complete user interface (panel, sliders, buttons, etc.) for the editor. We will look at editors more closely in a later tutorial.

3. Instance Uview_editor and Ulight_editor, then connect them to the other objects, as shown in the diagram below. When the editors are instanced, the UIcmd contained in the editors is automatically installed on the Editors pull-down menu.

4. Select the Editors->View and Editors->Light pull-down commands.

Notice that selecting a command displays its associated editor.

2.5.4 Create an object and generate field data

Finally, we need a Graphics Display Kit object with field data. We can create both with Read Geom, using the second output port.

5. Instance Read Geom and connect it to Uscene3D, as shown in the diagram below.

6. We are now ready to specify a data file. In the SingleWindowApp window, select the Editors->Modules pull-down command. The user interface for Read_Geom will appear. Select thr browse button. A dialog box appears. Select teapot.geo, then select the OK button.

The application renders the teapot in the view's window.

7. Select Editors->Light and try the light editor.

The light editor is connected to the view, so, for example, when we turn the ambient light off, the view is updated accordingly.

2.5.5 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CreateViewCmds.

8. Delete the application.

2.6 Viewing multiple objects from one set of data

A view can include multiple Graphics Display Kit objects. In this tutorial, we create a view consisting of four objects, each derived from the same set of data.

2.6.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.6.2 Instance Viewer3D

Uviewer3D is a full-featured 3D viewer, complete with a top-level object, a window, a view, and related editors. At the end of this tutorial, we explore the features of Uviewer3D.

2. Instance into the SingleWindowApp workspace the object Uviewer3D.

Notice in Libraries.Main.Viewers:

• There are three different full-featured viewers, called Uviewer3D, Uviewer2D, and Uviewer. They differ in how they render Graphics Display Kit objects. Uviewer3D renders all objects in 3D. Uviewer2D renders all objects in 2D. Uviewer can do both; connect objects to be rendered in 3D to Uviewer's first input port, and objects to be rendered in 2D to its second input port.

2.6.3 Create four objects

We now create four Graphics Display Kit objects, each derived from the same set of data. We use Diamond3D to create the data to render, then four instances of the Data Visualization Kit's scale object to create the four objects.

3. Instance Diamond3D and scale (four copies), then connect them together and to UViewer3D, as shown in the diagram below. 

The application renders the four objects. At first, though, it appears that only one object is present. This is because the four are overlapping.

4. Separate the four objects.

a. Select the Translate icon from the toolbar in the application window.

b. With the Control key pressed, select the first object with the left mouse button. Release the control key.

c. With the left mouse button, drag the object to a corner of the window.

d. Repeate the process for the other objects.

2.6.4 Manipulate the objects

5. Use Uviewer3D's capabilities to manipulate the objects.  For example, here is a series of steps for testing the inheritance of properties:

a. Display the object selector by pressing the SelectObject button.

b. Select the top-level object (Top3D) and select the Apply button.

c. Display the properties editor by selecting Editors->Object, then selecting Properties from the Object option menu.

d. In the properties editor, select Primary Color from the Object Color option menu. Use the dials to change the color. Notice that all objects change. By default, an object inherits the properties of its parent, so when we change the top-level object, all objects change.

e. In the object selector, select one of the other objects and select Apply. Now the properties editor shows that object's current properties. (You could also have selected the object itself using the mouse inside the view.)

f. In the properties editor, change the object's color. Notice that the color of that object changes.

2.6.5 Explore Uviewer3D's capabilities

6. Explore Uviewer3D's editors and mouse operations.  The tables below summarize Uviewer3D's capabilities.

Editors under Uviewer3D	Description
Editors->View	An editor for the view's basic information.
Editors->Transform	An editor for transforming the selected object as well as specifying interactor behavior.
Editors->Light	An editor for the view's light information..
Editors->Camera	An editor for the view's camera.
Editors->Object	An editor for the selected object's basic information, properties, modes and texture.
Editors->Datamap	An editor for controlling the conversion of scalar node or cell data to colors. Our object does not have node or cell data.
SelectObject...	A dialog box that allows you to select an object from a list of objects in the view.

Standard Mouse-controlled operations	What to do
Pick	Hold down the Control key and press the left mouse button.
XY Translate	Select Translate icon from the tool bar in the application and drag the object with the left mouse button.
Z Translate	Select Z Translate from the tool bar in the application and drag the object with the left mouse button.
Rotate	Select Rotate from the tool bar in the application and drag the object with the left mouse button.
Scale	Select Scale from the tool bar in the application and drag the object with the left mouse button.

If you have a three-button mouse, some of the standard operations can also be performed using the middle mouse button.

Accelerated Mouse-controlled operations	What to do
XY Translate	Drag the object with Control middle mouse button.
Rotate	Drag the object with the middle mouse button.
Scale	Drag the object with Shift middle mouse button.

2.6.6 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.MultipleObjs.

7. Delete the application.

2.7 Creating an object hierarchy

A Graphics Display Kit object can have zero or more child objects. You can connect multiple objects into a camera. These capabilities enable us to create elaborate object hierarchies. In this tutorial, we create a multi-level object hierarchy.

2.7.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.7.2 Instance Uviewer3D

2. Instance into the SingleWindowApp workspace the Uviewer3D object.

2.7.3 Create the object hierarchy

3. Instance several objects, then connect them, as shown in the diagram below.  After we have put the pieces together, we analyze what we have done.

The application creates the data object hierarchy shown below. Uviewer3D and the two instances of GroupObject create top-level objects that do not themselves have data:

Uviewer3D
GroupObject
GroupObject#1
scale (data from Diamond3D)
scale#1 (data from Diamond3D)
Read Geom #1
Read Geom

4. Display the modules window by selecting Editors->Modules.  Select the first Read Geom from the option menu and press the Browse butto. A dialog box appears. Select dodec.geo, then select the OK button. Repeat the procedure for the other Read Geom entry in the option menu, but select a different file.

5. The application renders four objects:

• the object created by Read Geom
• the object created by Read Geom#1
• the object created by scale
• the object created by scale#1.Notice that scale and scale#1 both use the data provided by Diamond3D.

2.7.4 Manipulate the objects

6. Use Uviewer3D's capabilities to manipulate the objects.  For example, using the object selector (Select Object...), select an object in the hierarchy. (Remember to select the Apply button when you select an object.) Point to an open area in the view and perform a translate operation. Different objects move, depending on which object in the hierarchy is selected.

2.7.5 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.ObjHierarchy.

7. Delete the application. 

2.8 Creating a custom transformation editor

Uviewer3D is a full-featured 3D viewer, complete with a top-level object, a window, a view, and related editors. In this tutorial, we add sliders to the bottom of Uviewer3D's window so the user can rotate the object.

The tutorial illustrates:

• how to customize an application component supplied by the GD Kit
• how to build editors

2.8.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.8.2 Construct the base application

2. Build an application using Read Geom and Uviewer3D, as shown in the diagram below.

3. Display the modules window by selecting Editors->Modules. Select the Browse button from the Read Geom user interface. A dialog box appears. Select teapot.geo, then select the OK button.

2.8.3 Resize the view's rendering panel

We now customize Uviewer3D. We start by resizing the view's rendering panel to create space at the bottom of the window for the sliders. AVS/Express' active execution model enables us to see the results of our changes as we make them.

4. Maximize Uviewer3D by double clicking it with the left mouse button. 

The figure below shows what Uviewer3D looks like. The annotations indicate the class name and purpose of most of Uviewer3D's objects:

Scene defines the view's window. This is the object we want to modify.

5. Find the view's panel and export it's port.

a. Open Scene in DisplayParameters mode. Open View in DisplayParameters mode. Open ViewUI in DisplayParameters mode. Open ViewPanel in DisplayParameters mode.

b. Export the output port on panel. To export the output port on the panel subobject, open its properties editor. Set Property Group to All Properties. Click NE port levels and change {0,0} to {0,6}. Click Set.

c. Close ViewPanel.

6. Decrease the view's frame height by 100 to create room for the sliders:

a. Open Scene in Display Parameters mode. Open View in Display Parameters mode. Open ViewUI in Display Parameters mode. Open ViewFrame in DisplayParameters mode. Open the height subobject to see height's value expression.

b. Change the "parent.height" value in the height subobject to "parent.height <+> - 100".

c. Press Return. The new height should appear in height's title bar.

d. Close ViewFrame.

Notice that the view window's rendering panel is now shorter, leaving room at the bottom for a set of sliders.

7. Close ViewUI. Close View. Close Scene.

We are now back to Uviewer3D's maximized window.

2.8.4 Create the transform editor

We now create a transform editor inside of Uviewer3D, which appears to the user as a set of three sliders at the bottom of the view's window.

8. Create the skeleton of the transform editor.

a. Maximize Scene_Editor. (Located in Libraries.Standard_Objects.Macros.)

b. Instance macro . Rename macro to MyXformEditor.

c. Maximize MyXformEditor.

d. Instance link located in Libraries.Standard_Objects.Links, UIpanel located in Libraries.User_Interface.Containers, GDObject_templ located in Libraries.Accessories.Graphics.Modules, and GDxform_edit located in Libraries.Accessories.Graphics.Modules.

e. Export the link so it is an input port on MyXformEditor and connect link and UIpanel as shown in the following diagram.

f. Modify UIpanel by setting its y subobject to 415 and its width subobject to =>link.clientWidth. This positions the panel just below the view window and makes the panel the same width as the view window.

g. Change GDobject_templ to a reference by setting its ref_mode property to '&' using the Properties Editor. Export GDobject_templ so it is an input port on MyXformEditor. The input port can be selected using the Object Editor of the GDobject_templ. You may have to toggle the Display Input Port checkbox.

h. Open GDobject_templ and export its xform subobject so it is an output port on GDobject_templ. To get the output port of an xform subobject, open its Properties Editor. Set Property Group to All Properties. Click on NE port levels and change {2,0} to {2,2} and click Set. Connect GDobject_templ and GDxform_edit as shown in the diagram below.

At this stage, MyXformEditor should appear as illustrated in the following figure.

i.

j. Close MyXformEditor.

k. Connect the right input port of MyXformEditor to in_view.picked_obj. This provides MyXformEditor with an object to transform.

l. Export MyXformEditor.link so it is an output port on Scene_Editor. To get the output port on the link, open its Properties Editor. Set Property Group to All Properties. Click NEportLevels and change {2,1} to {3,1} and click Set.

m. Close Scene_Editor.

n. Connect the right output port of Scene to the right input port of Scene Editor. This provides MyXformEditor's panel a parent window for the three sliders that will be added.

2.8.5 Look at MyXformEditor

Take a closer look at MyXformEditor.

1. Maximize MyXformEditor. 

The figure below shows what MyXformEditor looks like. The annotations indicate the class name and purpose of two of MyXformEditor's objects (the other two objects are references for the macro):

Although MyXformEditor so far defines just the skeleton of a fully functional editor, it does illustrate the two main components of an editor:

• An edit object - Most base objects-DefaultView, DefaultCamera3D, DefaultModes, and so forth-have companion edit objects-GDview_edit, GDcamera_edit, GDmodes_edit, and so forth. You will see how these work as we go along.
• A user interface - The user interface consists of UI widget objects, like panels, sliders, buttons, and entry fields. Many of the widgets are connected to subobjects of the edit object.

Here is how an editor works: the user modifies a UI widget that's connected to an edit object; the edit object in turn updates the base object to which it is connected.

2.8.6 Create sliders and connect them to the panel

We now create three user-interface sliders inside MyXformEditor.

2. Instance a UIslider object and connect it to UIpanel, as shown in the diagram below. 

Notice that a slider appears in the viewing window.

3. Modify UIslider.  Do the following:

a. Rename it to Xrot. (Use the Rename pull-down command.)

b. Set its x position to 10.

c. Set its y position to 10.

d. Set its width to 150.

e. Set its min value to -180 and its max value to +180.

f. Set its title to "X rot".

Notice that the slider changes accordingly.

4. Similarly, instance, connect, and modify a second UIslider.  Do the following:

a. Instance UIslider and connect it to UIpanel, just as you did for the first UIslider.

b. Rename it to Yrot.

c. Set its x position to 170.

d. Set its y position to 10.

e. Set its width to 150.

f. Set its min value to -180 and its max value to +180.

g. Set its title to "Y rot".

5. Similarly, instance, connect, and modify a third UIslider.  Do the following:

a. Instance UIslider and connect it to UIpanel.

b. Rename it to Zrot.

c. Set its x position to 330.

d. Set its y position to 10.

e. Set its width to 150.

f. Set its min value to -180 and its max value to +180.

g. Set its title to "Z rot".

2.8.7 Connect the sliders to GDxform_edit

The next step is to connect the sliders to GDxform_edit.

6. Expose GDxform_edit's x_rot, y_rot, and z_rot output ports.  Do the following:

a. Open GDxform_edit.

b. If x_rot does not already have an output port, create one with the Add Output Port pop-up command.

c. Export x_rot's output port with the Export Port pop-up command. Remember that you must position the mouse pointer over the port when selecting the pop-up command.

d. Similarly, create and export output ports for y_rot and z_rot.

e. Close GDxform_edit.

Here is what GDxform_edit should look like, both opened and closed:

7. Connect the three UIsliders to GDxform_edit, as shown in the followoung diagram. Note that objects in the diagram have been shifted to make the connection lines clearer.

2.8.8 Configure GDxform_edit

The last step is to configure the transform editor so it executes properly.

8. Open GDxform_edit.

9. Set the transform editor's shell_vis subobject to 1.

This causes the Xrot, Yrot and Zrot subobjects to be updated when the xform subobject changes. This happens when an object in the view is transformed using the mouse. The Graphics Display Kit editors typically do not update the subobjects that are normally connected to UI widgets unless shell_vis is set to 1.

10. Set the transform editor's absolute subobject to 1.

This causes the transform editor to work in absolute mode instead of relative mode. This subobject must be set to either 0 or 1 for the editor to work properly.

11. Close GDxform_edit.

2.8.9 Try the application

12. Use the sliders you created to rotate the teapot.

2.8.10 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CustomEdit.

13. Close MyXformEditor. 

14. Close Scene_Editor.

15. Close Uviewer3D. 

Note that at this point, you could rename Uviewer3D and save it back into Libraries, thereby creating a customized viewer.

16. Delete the application.

2.9 Adding interactors to a view

Interactors along with the Graphics Display Kit's virtual trackball editor allow you to directly manipulate objects in the view window. In this tutorial, we add an interactor to a view and demonstrate some of the capabilities of the virtual trackball editor.

2.9.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.9.2 Create a window and a view

We create the application's window and view with the application component Uscene3D.

2. Instance into the SingleWindowApp workspace the object Uscene3D.

When we instance Uscene3D, a black window appears inside it. This is where the data is rendered.

2.9.3 Create an object and generate field data

We need a Graphics Display Kit object with field data. We can create both with Read Geom, using the second output port.

3. Instance Read Geom and connect it to Uscene3D, as shown in the diagram below. 

4. We are now ready to specify a data file. Select Editors->Modules to display the Read Geom user interface. Press the Browse button. A dialog box appears. Select teapot.geo, then select the OK button.

The application renders the teapot in the view's window.

2.9.4 Provide access to view information

We need to provide access to some of the parameters kept inside the view.

1. Instance Uview_link from Libraries.Graphics_Display.Views.Scenes.

2. Connect Uscene3D to Uview_link.

2.9.5 Create the interactor and trackball editor

We need to have a UI interactor and the virtual trackball editor.

1. Instance UItwoPoint and GDtrack_edit and connect them (exposing ports as necessary) as shown in the diagram that follows.

a. Connect Uview_link.render_view to UItwoPoint.view. This provides the interactor with the window in which to look for the mouse gesture.

b. Connect UItwoPoint.x to GDtrack_edit.x. Connect UItwoPoint.y to GDtrack_edit.y. Connect UItwoPoint.state to GDtrack_edit.event. These provide the trackball editor with screen space XY positions and the events start, run or stop.

c. Connect UItwoPoint.time to GDtrack_edit.time. This provides the trackball editor with the time of the event. This is used to determine if track rolling should be enabled.

d. Connect Uview_link to GDtrack_edit.view. Connect Uview_link.picked_camera to GDtrack_edit.camera. Connect Uview_link.picked_obj to GDtrack_edit.obj. These provide the trackball editor with an object to edit as well as the view and camera which are needed to convert screen space XY positions into a transformation matrix.

Note that the port correspondence can be found by using the 'info' option (right mouse click) on Uview_link and GDtrack_edit objects.

With these connections made, the trackball editor should now produce a transformation matrix that causes rotation when the left mouse button is held down and dragged. This is the default for the trackball editor.

2.9.6 Explore the trackball editor's capabliities

Now that we have the interactor and the trackball editor working the view window, let's explore the capabilities of the editor.

The mode subobject in GDtrack_edit controls what type of transformation the editor performs. With the connections you have made, you can control the mode by using the Left Button option menu at the bottom of the view. By default, the value of mode should be 0 which means Rotate. The following values are valid:

Value	Meaning
0	Rotate
1	Scale
2	XY Translate
3	Z Translate

The rot_mode subobject controls what if any constraints are applied to the rotation. The following values are valid:

Value	Meaning	Symbolic constant
0	Allow arbitrary rotation.	GD_ROTATE_ARBITRARY
1	Constrain rotation to the XY axis. Select the largest angle of rotation.	GD_ROTATE_CONSTRAIN_XY
2	Constrain rotation to the Z axis.	GD_ROTATE_Z

2. Try all the valid values for the rot_mode subobject and try rotating the object in the view.

3. Set the mode subobject in GDtrack_edit to 1. Press the left mouse button and drag the mouse in the view. The object should now be scaled.

This illustrates that one instance of the GDtrack_edit module can be used to perform all possible interactions with the object. This is done by simply selecting the type of interaction you want to perform prior to making the apppropriate gesture with the mouse.

The scale_mode subobject controls what if any constraints are applied to scaling. The following values are valid:

Value	Meaning	Symbolic constant
0	Allow uniform scaling	GD_SCALE_UNIFORM
1	Allow non-uniform scaling	GD_SCALE_NON_UNIFORM

4. Try all values for the scale_mode subobject and try scaling the object in the view.

5. Set the mode subobject of GDtrack_edit to 2. Press the left mouse button and drag the mouse in the view. The object should now be translated.

The xlate_mode subobject controls what if any constraints are applied to XY translation. The following values are valid:

Value	Meaning	Symbolic constant
0	Allow arbitrary translation	GD_XLATE_ARBITRARY
1	Constrain translation to the X axis	GD_XLATE_CONSTRAIN_X
2	Constrain translation to the Y axis	GD_XLATE_CONSTRAIN_Y
3	Constrain translation to the closest axis	GD_XLATE_CONSTRAIN_CLOSE

6. Try all values for the xlate_mode subobject and try translating the object in the view.

2.9.7 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.AddInteractors.

7. Delete the application.

2.10 Modifying a camera for annotation

Many times you might like to add non-transformable annotation or simple graphics to a view. This example illustrates one way to do this by having a non-pickable 2D camera in the view and placing the annotation or simple graphics in that camera.

2.10.1 Starting up

1. Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

2.10.2 Instance Uviewer

2. Instance into the SingleWindowApp workspace the object Uviewer.

2.10.3 Create an object and generate field data

We need to create a Graphics Display Kit object.

3. Instance Read Geom and connect it to Uviewer's left input port.

4. We're now ready to specify a data file. Select Editors->Modules to display the Read Geom user interface. Select the Browse button. A dialog box appears. Select teapot.geo, then select the OK button.

The application renders the teapot in the view's window.

2.10.4 Modify the 2D camera

We need to modify the 2D camera so annotation and simple graphics will be non-transformable.

5. Select Editors->Camera to display the camera editor's user interface.

6. Select in the view's background until the 2D camera is selected.

7. Toggle the Pickable control in the camera editor's user interface so that it is set off.

This makes the camera as well as all the objects in the camera unpickable. You will be unable to directly manipulate the objects, making them effectively "non-transformable". Note however, that if the transform subobject of the object changes in some other manner, the object will still be transformed.

2.10.5 Add some annotation

We can now add some text and graphics that we want to be non-transformable to the view.

8. Instance TextString and connect it to the view as shown in the diagram below.

The text string "Hello World" will be rendered in the middle of the view. We need to move it to the top of the view, render a different string and make the font larger.

9. Change the text position.

a. Maximize TextString.

b. Open text.

c. Scroll down to find the position subobject and open it. This position represent the XY coordinates where the string will be rendered.

d. Replace the current values with -4.0 for X and 3.5 for Y. With the current string and font size, "Hello World" is rendered towards the upper left.

e. Close text.

f. Close TextString.

10. Change the text string and the font size.

a. Select Editors->Modules to display the modules window. Select TextString from the Modules option menu. The user interface for TextString appears.

b. Replace "Hello World" with "Non-Transformable Annotation".

c. Find the value 20 in the font specification and replace it with 30.

We now have a title at the top of the view that is non-transformable.

2.10.6 Add a legend

We can now add a legend to the view that will also be non-transformable.

11. Instance LegendHoriz and connect it to the view as shown in the diagram below.

12. Try transforming the objects in the view.

Notice that the only objects that you can pick are Top3D and teapot. Since the text string and legend are in a camera that is not pickable, they cannot be selected.

2.10.7 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.AnnoCamera.

13. Delete the application.

2.11 Adding a second view window

Many times in an application you may want to have more than one view window in a single user interface shell. In this tutorial, we add a second view window to an existing viewer and share all the editors among the two views.

2.11.1 Starting up

1. Start AVS/Express and choose Multi-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Multi-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing MultiWindowApp workspace, as appropriate.

2.11.2 Instance Uviewer3D

2. Instance into the MultiWindowApp workspace the object Uviewer3D.

2.11.3 Create a second view window

We need to add the second view window to Uviewer3D and configure the viewer so all the editors are shared between the views.

3. Maximixe Uviewer3D.

4. Modify the existing view so it occupies the left hand side of the view window. Make sure to keep the behavior of the view resizing when the panel resizes.

a. Open Scene in DisplayParameters mode. Open View in DisplayParameters mode. Open ViewUI in DisplayParameters mode. Open ViewFrame.

b. Change width to (<-.ViewPanel.UI.panel.width / 2).

c. Close ViewFrame. Open View Panel in DisplayParameters mode

d. Export the output port of panel by opening its Properties Editor. Set Property Group to All Properties. Click on NEportLevels and change {0,0} to {0,6} and click Set..

e. Close ViewPanel, Close ViewUI. Close View. Close Scene.

5. Create a second view and modify it to occupy the right hand side of the view window. Make sure to keep the behavior of the view resizing when the panel resizes.

a. Instance Uscene3D (from Libraries.Accesories.Graphics) into UViewer3D (which should still be maximized).

b. Open UScene3D in DisplayParameters mode. Open View in DisplayParameters mode. Open ViewUI in DisplayParameters mode.

c. Delete ViewPanel. We are reparenting the view to the existing window provided by Uviewer3D, so we need to delete this scene's original parent.

d. Open ViewFrame in DisplayParameters mode. Export the input port of parent. To export output port on parent, open its Properties Editor and set Property Group to All Properties. Click on NEportLevels and change {0,0} to {0,5} and click Set.

e. Reparent the second view by connecting the right output port of Scene (exposed in Step 4) to the newly exposed right input port of Uscene3D.

f. Set up the second view's geometry as explained below. Set x to be a reference to (parent.width / 2) . Set width to be a reference to (parent.width / 2). Set height to be a reference to parent.height. When set, the new values should appear as in the following diagram:

This causes the second view to occupy the right hand side of the shell. This also causes the view to resize when its parent resizes.

g. Close ViewFrame. Close ViewUI. Close Uscene3D.

6. Share the viewer's editors between the two views by connecting Uscene3D.View.View to Scene_Selector.input_views.

7. Export Uscene3D.Top.child_objs to be an input port on Uviewer3D.

The diagram below shows the final connections between Scene, Uscene3D and Scene_Selector inside Uviewer3D.

8. Close Uviewer3D.

2.11.4 Create two objects and generate field data

We need to create Graphics Display Kit objects and provide them with data to render.

9. Instance two copies of Read Geom.

10. Connect Read Geom to the left input port of Uviewer3D.

11. Connect Read Geom#1 to the right input port of Uviewer3D.

12. We're now ready to specify a data file. Select Editors->Modules to display the user interface for the Read Geom module appear. Select the Browse button to make a dialog box appear. Select teapot.geo, then select the OK button.

The application renders the teapot in the left view window.

13. We're now ready to specify a data file. Select Read_Geom#1 from the Modules option menu to make the user interface for the other Read Geom module appear. Select the Browse button to make a dialog box appears. Select math.geo, then select the OK button.

The application renders math in the right view window.

2.11.5 Use the editors

We can now share the editors between the two views. Any interaction in either view makes that view current and switches the editors to work with the objects in that view.

14. Select the teapot in the left view window with the left mouse button. Notice that the Current Object at the bottom of the view window says teapot.

15. Notice that the virtual trackball editor works in the left view window. The normal gestures for rotation, scale, and translation apply.

16. Select Editors->View. The view editor dialog box appears. Change the Background Color.

17. Select math in the right view window with the left mouse button. Notice that the Current Object at the bottom of the view window says math.

18. Notice that the virtual trackball editor now works in the right view window.

19. Select Editors->Object. The object editor dialog box appears. Select the Reset icon. Select the Normalize icon. Select the Center icon. Notice that these operations effect only the math object.

2.11.6 Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.TwoView.

20. Delete the application.

2.12 Using accelerate mode in a view

Accelerate mode

Rendering performance can be an issue when working with complex data sets, particularly when you need to move another smaller graphical object over or through such a data set (for example, when probing a large geometry).

In such cases you may want to take advantage of accelerate mode rendering in which objects in a view are marked as either dynamic or static and then handled differently by the renderer(s):

• Small objects that will need to be moved should be marked as dynamic.
• Large data sets should marked as static (the default). Image and z-buffer information for static object is stored by the renderer(s).

When dynamic objects are subsequently moved, only they require rerendering - into the buffers that already contain the rendered static objects. Note that if static objects are moved, they must obviously be also rerendered thus negating the performance advantages of accelerate mode.

Note: The performance of accelerate mode in renderers is highly dependent on the technique that the graphics library/hardware vendor uses for grabbing frame and Z buffers, and does not therefore always provide a significant performance advantage. For example, accelerate mode is not noticably faster on a PC than normal rendering (and in fact is slower on some machines).

This tutorial

In the following tutorial, you will move a simple 2D arrow glyph (the dynamic object) over a large 3D geometry (the static object) with accelerate mode active and inactive to compare performance in both states.

Note: In this example, because the only dynamic object is 2D, only the image buffer need be rerendered into the buffer containing the static object - the Z-buffer need not be saved.

Uviewer mouse operations

In order to perform the manipulation of the graphic objects required to complete this tutorial, you will need to use some of the basic mouse operations that control editing in the Uviewer scene window:

Mouse-controlled operations	Gesture
Select object	Press Control left button while the mouse is over an object in the view.
XY translate object	Hold down the Control key and drag the object while holding the middle mouse button.
Rotate object	Drag the mouse with the middle button held down.

2.12.1 Starting up

1. Start AVS/Express and choose None from the startup dialog, or if you have an existing AVS/Express session, delete or close any existing application workspaces that you have open.

2.12.2 Instance the example network, Accel2DGlyph

The Accel2DGlyph macro contains a complete example network complete with large and small data sets and a viewer already set up for accelerate mode.

2. Instance into the empty NE workspace the object Accel2DGlyph from the Graphics Display Examples library.

3. After the example has loaded, view the example network.

2.12.3 Investigate the controls that affect accelerate mode

The DataViewer instanced as part of the Accel2DGlyph network contains a 3D map of the Caribbean ($XP_ROOT/data/geoms/carib.geo, read in via the Read_Field module), and an instance of a simple 2D arrow (Templates.GEOMS.Arrow2). (There is also a legend for the map, but this is can be ignored for the purposes of this tutorial.)

4. Accelerate mode is controlled at the low level by the accel parameter of the DefaultView object. However, the Single Window Dataviewer used in this tutorial provides much easier access to this parameter via the Accelerate toggle button in the View Editor that forms part of it's user interface.

To look at the Accelerate control, open the View Editor by selecting Editors->View from the Dataviewer menubar and then selecting Options from the View popup at the top of the Module Panel. You will see that the Accelerate toggle button is set on, and that accelerate mode is therefore active. Later on we'll turn accelerate mode off and see the impact that this has on rendering performance.

5. The nature (dynamic or static) of an object in a view is controlled at the low level by the type parameter set on objects. However, the Viewer used in this tutorial provides much easier access to this parameter via the Dynamic toggle button in the Object Editor that forms part of it's user interface. To see the setting of Dynamic control for the Arrow2 and carib objects:

a. Open the Object Editor by selecting Editors->Object from the Dataviewer menubar.

b. Select the Arrow2 object by placing the cursor over it and control-left-clicking (when selected, "Arrow2" will replace "Top3D" on the message line below the view). You will see that the Dynamic toggle button is set on, marking the arrow as a dynamic object for accelerate mode rendering.

c. Select the carib object by placing the cursor over it and control-left-clicking (when selected, "carib" will replace "Arrow2" on the message line below the view). You will see that the Dynamic toggle button is set off, marking the carib as a static object for accelerate mode rendering.

2.12.4 Move the dynamic object

6. Reselect the Arrow2 object by placing the cursor over it and control-left-clicking.

7. Translate Arrow2D over carib by moving the mouse while holding the Control key and the middle mouse button. Note the speed at which the arrow is rerendered with accelerate mode on.

2.12.5 Compare rendering performance

8. To compare rendering performance with accelerate mode off, unset the Accelerate toggle on the View Editor and then repeat step 7. You should notice a significant decrease in performance.

9. You can obtain a more quantitative measure of the difference performance with the Timer facility (also set via a toggle button in the Options page on the View Editor), which reports rendering performance in Frames Per Second (FPS) in the VCP window, set on:

a. Activate the timer by pressing the Timer toggle so that it is set.

b. "Throw" the arrow object with accelerate mode on (by dragging the mouse with the middle button held down and realeasing the button while the mouse is still in motion). To stop rotation, left-click in the view, at which time the rendering speed will be written to the VCP.

c. Repeat the operation outlined in step b. above with accelerate mode off. The rendering speed reported by the timer should be significantly lower.

2.12.6 Clean up

This completes the tutorial.

10. Delete the example application workspace.

For more examples of the use of accelerate mode, see related examples available in the Examples.Graphics_Display library.

Copyright © 2001 Advanced Visual Systems Inc.
All rights reserved.