Configuring Wonderland X11 Shared Applications

Introduction

This article describes the basic, high-level software architecture and means of configuring the shared application support in Project Wonderland. Currently, shared applications may only be launched on Linux and Solaris--the Shared Application mechanism uses a modified X11 Server to host the shared applications. Clients on all operating systems (Windows, Mac OSX, Linux, Solaris) are able to see and interact with shared applications in-world, however.

Figure 1 illustrates the high-level software architecture of shared applications.

This diagram highlights two different ways applications can be launched in-world: via the "server master client" (SMC) or by a Wonderland client running on Linux/Solaris. The SMC is a special instance of a Wonderland client (that you never see) whose purpose is to launch shared applications in-world so that all clients may interact with them, but is not associated with any one Wonderland client in particular (hence, it is a 'system wide' shared application). Also, any individual Wonderland client that runs on Solaris or Linux may launch its own shared applications in-world so that all clients may interact with them. The shared application is associated with the Wonderland client who launches it, so once the Wonderland client leaves the world, so does the shared application.

In Figure 1, the SMC launches and hosts the Firefox ('FF', solid rectangle) application in-world; Wonderland clients may interact with it ('FF', dashed rectangles). Wonderland clients that run on either Linux or Solaris can also launch and interact with their own shared applications, e.g. StarOffice ('SO', solid rectangle). Other clients that run on either Mac OS X or Windows may interact with these client-launched shared applications ('SO', dashed rectangle).

Sharing an Application from a Wonderland Client

Any Wonderland client can launch a shared application in-world via the Shared Apps -> Run Local Apps menu item if running on Solaris or Linux (the menu item is appropriately enabled/disabled). The Wonderland User's Guide has more details.

The list of available applications is configured via a file in the Wonderland source code: apps.xml located in either the lg3d-wonderland.dev.java.net/src/config/apps-solaris or lg3d-wonderland.dev.java.net/src/config/apps-linux directories depending upon whether the Wonderland client runs on Solaris or Linux, respectively. The apps.xml file is an XML serialization of an array of the org.jdesktop.lg3d.wonderland.appshare.AppConfigX11Example class. The header of this file is:

<?xml version="1.0" encoding="UTF-8"?> 
<java version="1.6.0-dp" class="java.beans.XMLDecoder"> 
 <array class="org.jdesktop.lg3d.wonderland.appshare.AppConfigX11Example" length="2"> 

where length="2" gives the number of shared applications configured in the menu. For each application to appear in the Shared Apps -> Run Local Apps menu, an entry that looks like the following appears next:

  <void index="0"> 
   <object class="org.jdesktop.lg3d.wonderland.appshare.AppConfigX11Example"> 
    <void property="appMenu"> 
     <object id="AppConfigX11Example$AppMenu1" class="org.jdesktop.lg3d.wonderland.appshare.AppConfigX11Example$AppMenu" method="valueOf"> 
      <string>Local</string> 
     </object> 
    </void> 
    <void property="initInBestView">
        <boolean>true</boolean>
    </void>
    <void property="cellDimensions"> 
     <object class="javax.vecmath.Vector3f"> 
      <void property="x"> 
       <float>10.0</float> 
      </void> 
      <void property="y"> 
       <float>10.0</float> 
      </void> 
      <void property="z"> 
       <float>10.0</float> 
      </void> 
     </object> 
    </void> 
    <void property="cellPosition"> 
     <object class="javax.vecmath.Point3f"> 
      <void property="x"> 
       <float>52.0</float> 
      </void> 
      <void property="y"> 
       <float>1.7</float> 
      </void> 
      <void property="z"> 
       <float>28.0</float> 
      </void> 
     </object> 
    </void> 
    <void property="cellRotateY"> 
     <float>45.0</float> 
    </void> 
    <void property="command"> 
     <string>/usr/bin/gnome-terminal</string> 
    </void> 
    <void property="name"> 
     <string>Terminal</string> 
    </void> 
    <void property="pixelScale"> 
     <object id="Vector2f0" class="javax.vecmath.Vector2f"> 
      <void property="x"> 
       <float>0.01</float> 
      </void> 
      <void property="y"> 
       <float>0.01</float> 
      </void> 
     </object> 
    </void> 
   </object> 
  </void> 

Note that the first application entry in this file should have an index of 0, the second should have an index of 1, etc. There are several important attributes to set. The name attribute specifies the name that appears in the menu, and the command attribute specifies the command that launches the application. Note: The command is interpreted relative to the path of the launching client. So, for example, if the command consists of "firefox" then the executable firefox must be in the execution path of the launching client.

You may also configure how and where the shared application appears. The cellDimensions property gives the <x, y, z> dimensions of the application, in this example 10 m x 10 m x 10m. You may leave this attribute as is -- it is simply used by the Wonderland server to coarsely determine whether your application will be visible at a distance.

There are two ways to specify the position of the application (or, more specifically, the center point of the primary window of the application).

1. Absolute positioning (Local or SMC apps)

In the first method, the property initInBestView is set to false and cellPosition is set to the desired center point (in world coordinates). In addition, cellRotateY is specified to the desired rotation angle (in degrees) around the world Y (vertical) axis. When this positioning method is used the application will appear at the specified position and have the specified rotation each time it is launched.

This positioning method may be used for both local and SMC apps.

2. Best View positioning (Local apps only)

In the second method, the property initInBestView is set to true. This will make the app appear flat in front of where the launching user is currently looking. In this method, the values of the cellPosition and cellRotateY properties are ignored.

This positioning method may be used only for local SMC apps.

Other configuration parameters include:

appMenu

For an application that is to be launched by a Wonderland user client (that is, for an app entry that is in apps.xml) the value of the appMenu property must be set to Local. All application entries in the apps.xml file must have an appMenu value of Local.

For an application that is to be launched by the SMC (that is, for an application entry that is in the apps-smc.xml file) the value of the appMenu property must be one of: Conference Room, Team Room, or Demo Floor. This specifies the Shared Apps submenu in which the menu entry for the app will be placed.

pixelScale

The pixelScale x and y properties specify the size (in meters) of each pixel of the application. The pixelScale x property specifies the pixel width and the y property specifies the pixel height.

In addition to these pre-configured applications, you can always run any application you specify from the Shared Apps -> Run Local Apps menu item on clients running Linux or Solaris.

Sharing an Application via the SMC

Applications shared via the SMC are system-wide: although they are launch by any client, they persist independently of the client and are still in-world after the client disconnects. The SMC can only run on Linux or Solaris. It is usually run on the same machine as the Wonderland server, but it does not have to be. To run the SMC on a different machine you merely need to make sure that the sgs.server and sgs.port properties are set to refer to the Wonderland server in the my.build.properties (source code) or my.run.properties (binary build) in the SMC's lg3d-wonderland directory.

If you are starting the Wonderland server using src/scripts/server.sh (source code) the SMC is started by this this script. To run the SMC separately use the following command (assuming your current working directory is lg3d-wonderland):

% src/scripts/runsmc

or (binary build):

bin/wonderland-smc.sh

Running the SMC on a Separate Machine

Running lots of SMC applications can place a significant load on your server machine. If you plan to run lots of these you should plan to run the SMC on a separate machine than the one on which the Wonderland server is running. This section describes how to configure this.

First, start up the voicebridge and the Wonderland server on one machine. This will be called the "server machine." If you are using a source tree and start up the voicebridge, Wonderland server, and the SMC automatically by running the server.sh script, you should comment out the execution of runsmc in this script. Then run the script normally. Conversely, if you normally start these by hand, just omit the starting of the SMC.

Then, on a separate machine which will be called the "SMC machine", add a "sgs.server=<ip-address-of-server-machine>" entry to your my.run.properties (for binary release) or my.build.properties (for source tree). Then run the following:

% cd <your lg3d-wonderland directory>

% ./bin/wonderland-smc.sh (for binary release)

-or-

% ./src/scripts/runsmc (for source tree)

Further Reading

• Wonderland X11 App Sharing Instructions in the Wonderland User Guide
• Developers Getting Start (tutorial) - Describes how to download, build, and run Wonderland from the source code