Building and Running Project Looking Glass with NetBeans

Platform Requirements

Before you start setting up your Project Looking Glass development environment, first check to make sure your system meets the following minimal requirements.

Component	Linux Platform
Operating System	Most modern linux distributions should work, although there has been problems experienced when running it on a portage-based java-install. We suggest following this guide for installing all components listed manually instead of using portage.
CPU	2 GHz or faster recommended
RAM	512MB recommended
Graphics Card	3D accelerated graphics card, with at least 16MB VRAM and driver support for OpenGL, version 1.2 or greater. 16bit or 32bit color. IMPORTANT! 24-bit display depth is required! See instructions below for how to configure this.
Disk Space	350MB

Tested Video Cards

• NVIDIA GeForce 2 or equivalent cards using version 1.0-5336 and 1.0-6629 of the NVIDIA drivers.

  Please see NVIDIA Driver Installation Tips below.

  NOTE: It is especially important to consult these instructions if you have recently upgraded your driver to 1.0-6629, because LG3D requires additional configuration steps for 1.0-6629.

• ATI Radeon 7500 with DRI drivers. Please see DRI Driver installation for ATI Radeon.
• For device driver configuration instructions for specific cards refer to: Installing and Configuring Device Drivers for 3D Desktop Project Looking Glass

  If you are successful in getting Project Looking Glass to run on other cards, or want to report problems with specific cards, please let us know using the discussion forum

Download the components

Note: The installation instructions assume that you download all of the components into /tmp.

1. Java 2 SDK, Standard Edition 1.5.0 or later.
   http://java.sun.com/j2se/1.5.0/download.jsp
   
   Note: The installation instructions below assume you download the RPM version of the JDK.
   
   
2. NetBeans 4.1 IDE
   http://www.netbeans.info/downloads/download.php?type=4.1
   
   Note: Unless you are planning to do J2EE development, you can download the NetBeans 4.1 installer, the linux.bin version.
   
   
3. Java 3D SDK 1.3.2 or later
   https://j3d-core.dev.java.net/servlets/ProjectDocumentList
   
   Note: Navigate to the j3d-core/Release_Builds/1.3.2 sub-folder and download java3d-1_3_2-linux-i586.zip.
   
   
4. Java Advanced Imaging API (JAI) 1.1.2 JDK
   http://java.sun.com/products/java-media/jai/downloads/download-1_1_2.html
   
   Note: Select the JDK(TM) Install: Bundle for installation in a JDK Download. After reading and agreeing to the Software License Agreement, choose the Linux JDK Install item (jai-1_1_2-lib-linux-i586-jdk.bin).
   

Install the Components

After downloading all of the components, install them by following the instructions below.

1. First become root:
   
   % su root
   Password: enter root password
   #
   
   
2. Install the Java 2 SDK:
   
   # cd /tmp
   # /bin/bash jdk-1_5_0_02-linux-i586-rpm.bin
   # rm jdk-1_5_0_02-linux-i586.rpm
   # rm jdk-1_5_0_02-linux-i586-rpm.bin
   
   
3. Install the Java 3D SDK:
   
   # cd /tmp
   # unzip java3d-1_3_2-linux-i586.zip
   # cd /usr/java/jdk1.5.0/jre
   # unzip /tmp/java3d-1_3_2-linux-i586/j3d-132-linux-x86.zip
   # cd /tmp
   # rm -r java3d-1_3_2-linux-i586/
   
   
4. Install the Java Advanced Imaging API:
   
   # cd /usr/java/jdk1.5.0
   # /bin/bash /tmp/jai-1_1_2-lib-linux-i586-jdk.bin
   
   
5. Exit from the root shell:
   
   # exit
   %
   
   
6. Several environment variables now need to be set in your shell profile. Here are examples appropriate for bash(1):
   
   JAVA_HOME=/usr/java/jdk1.5.0
   PATH=$JAVA_HOME/bin:$PATH
   
   
7. Install the NetBeans IDE:
   
   % cd /tmp
   % chmod +x netbeans-<version>-linux.bin
   % ./netbeans-<version>-linux.bin
   % rm netbeans-<version>-linux.bin
   

   where netbeans-<version>-linux.bin is the filename of the version of NetBeans you are using, eg netbeans-4_1-linux.bin or similar.

Register at the java.net web site

If you haven't previously registered at java.net then you'll need to create an account:

1. Navigate to http://www.java.net and click on the Register link at the top of the page.
2. Enter your preferred user name and e-mail address and then press the [Register] button.
   
3. You'll receive an e-mail message with instructions on how to set a password for your account. Once you've entered your password and accepted the java.net website terms of participation you'll be logged in.
   

Configure the color depth of your display

The Project Looking Glass Developer's Release requires a color depth of at least 24 bits. Many systems are configured by default with 16 bit color depths and the Project Looking Glass Developer's Release will not run correctly at this depth. You can identify the current display depth by running the following command:

% xdpyinfo | grep "depth of root"
depth of root window:   24 planes

If you see a value lower than 24, you must change the color depth. The process for changing the color depth varies by platform. Refer to the configuration instructions for your platform below:

Java Desktop System 1 and 2, and SUSE8.1:

1. From within a desktop session, run the sax2 command:
   
   % /usr/X11R6/bin/sax2
   SaX: root Password: enter root password
   
   
2. In the SaX2 application, click on Color and Resolution then click the [Properties...] button for the currently configured desktop.
3. In the Color selection... panel, click on the the menu and choose 16.7 Mio. [24 Bit].
   
4. On the Resolution(s) for 16.7 Mio. [24 Bit] colors tab, select the preferred resolution for your desktop and press [Ok].
   
5. Click the [Finish] button, then [Finalize>>].
   
6. The SaX2 final steps... dialog will open. Click the [Test...] button to test the new resolution.
   
7. A blue test screen should appear, click the [Save] button if the display appears to be stable, and then [Ok] when you return to the SaX2 window, followed by [Yes] to exit from SaX2.
8. If the test screen did not appear correctly, the test will exit after 30 seconds and your previous desktop session will be restored. You should then try alternate resolutions at the 24 bit color depth to find a resolution that works for your system.
   
9. When you are satisfied with the settings, log out and re-login to your desktop session and verify that the color depth is now 24 bit or higher using the xdpyinfo command above.

RedHat Fedora 2:

1. First become root:
   
   % su root
   Password: enter root password
   #
   
   
2. Edit the file: /etc/X11/xorg.conf
3. Locate the section of the file labeled: Section "Screen"
   
4. Within this section, locate the entry: Identifier "Screen0"
   Change the DefaultDepth and DefaultFbBpp properties to:
   
   DefaultDepth 24
   DefaultFbBpp 32
   
   
5. Save the file and then logout and re-login to your desktop session and verify that the color depth is now 24 bit or higher using the xdpyinfo command above.
   

RedHat 8, RedHat 9 and other Linux platforms:

Many Linux platforms use the XF86Config file to configure the display properties. To change the color depth on these systems:

1. First become root:
   
   % su root
   Password: enter root password
   #
   
   
2. Edit the file: /etc/X11/XF86Config
3. Locate the section of the file labeled: Section "Screen" and change the DefaultDepth property to 24:
   
   DefaultDepth     24
   
   
4. Within this section, locate the sub-section labeled "Display":
   
   SubSection "Display"
   
   and change the Depth property to:
   
   Depth     24
   
   
5. Save the file and then logout and re-login to your desktop session and verify that the color depth is now 24 bit or higher using the xdpyinfo command above.

Launching NetBeans

To launch NetBeans, simply type netbeans at the command prompt in a terminal window:

% netbeans

The above command will launch the NetBeans IDE.

Getting the Looking Glass Source Code

The next step is to configure the NetBeans IDE to retrieve the Looking Glass source code from the java.net CVS repository. There are two Looking Glass CVS repositories which you must retrieve source file from, lg3d-core and lg3d-demo-apps. The steps to setup and retrieve source files in NetBeans is described in the next two sub-sections, Getting the lg3d-core source and Getting the lg3d-demo-apps source.

Getting the lg3d-core source

In the NetBeans IDE, from the main menu select Versioning > CVS > Check Out as shown in Figure 1 below.

Figure 1 Versioning > CVS > Check Out

After you have select the Versioning > CVS > Check Out menu item, the you will see the "Enabling Advanced CVS Command Options" dialog as shown in Figure 2.

Figure 2 Enabling Advanced CVS Command Options

Mark the checkbox next to the label "Do Not Show This Dialog Box Again" as shown in Figure 2 above and press the "Check Out" button.

Next you will see the "CVS Checkout" dialog. There are several values you will need to enter on this screen. Each of the values below should be entered in this screen.

    Working Directory: <source path where to place Looking Glass source files>

Remember this directory path, you will need to enter it again later

    CVS Server Type: pserver
    CVS Server Name: cvs.dev.java.net
    Port: 2401
    User Name: <enter your java.net user name>
    Repository Path: /cvs

Select the 'Use Built-in CVS Client

    Password: <enter your java.net password>

Select the "Module(s)" button

    Module(s): lg3d-core
    Revision or Tag: dev-0-6-2

dev-0-6-2 is the current branch as of April 3, 2005.

Your CVS Checkout form should look very similar to the one shown in Figure 3 below.

Figure 3 CVS Checkout

Notice the label "You are not logged in." below the Password field and Login botton. Press the Login button now. The label will change to "You are logged in".

The CVS Checkout form from my development is shown in Figure 4 below.

Figure 4 CVS Checkout logged in

Once you have the CVS Checkout form completed and it says you are logged in, press the "Ok" button.

After you have pressed the "Ok" button, the CVS Checkout form will go away and you will notice the output window, the bottom portion of the NetBeans IDE, will display the VCS Output from running your CVS checkout. The output in this VCS Output window should look very similar to that shown in Figure 5 below.

Figure 5 VCS Output Window - click for full size image

When the CVS checkout is completed, the status message at the bottom of the VCS Output window will say it has finished the Check Out.

From the main menu, select Window > Versioning > Versioning. A Versioning window will now appear in the upper left hand portion of the NetBeans IDE such as the one shown in Figure 6 below.

Figure 6 Versioning Window

Getting the lg3d-demo-apps source

As you did in the previous section "Getting the lg3d-core source", from the main menu select Versioning > CVS > Check Out as shown in Figure 7 below to initiate the sequence to retrieve the source code for the lg3d-demo-apps.

This will again display the "CVS Checkout" window. Fill in the values on the "CVS Checkout" form as shown in Figure 8 below.

IMPORTANT: Be sure to use the same working directory you specified in the "Getting the lg3d-core source" section and update the Module(s) field so that it reads "lg3d-demo-apps".

Figure 8 CVS Checkout (lg3d-demo-apps)

After specifying the values in the CVS Checkout window, press the "Ok" button to initiate the CVS check out of the lg3d-demo-apps source.

Again, you will notice the output window of the NetBeans IDE will display VCS Output for the lg3d-demo-apps as shown in Figure 9 below.

Figure 9 VCS Output (lg3d-demo-apps) - click for full size image

Open the Looking Glass Project in NetBeans

You are now ready to open the Looking Glass project in NetBeans.

In the NetBeans IDE, select the File > Open Project menu item as shown in Figure 10 below.

Figure 10 File > Open Project

This will display the "Open Project" dialog. Traverse to the working directory you specified in the CVS Checkout and select the lg3d-core project. Notice there is a small icon on the lg3d-core folder and next to the name lg3d-core indicating it is a NetBeans project. An example "Open Project" dialog is displayed in Figure 11 which shows a working directory of /home/huntch/my-lg3d.

Figure 11 Open Project - click for full size image

After selecting the lg3d-core project, press the "Open Project Folder" button to load the Looking Glass NetBeans project into the NetBeans IDE.

In the projects window of the NetBeans IDE you will see the "lg3d-core" project as show in Figure 12 below.

Figure 12 lg3d-core

You now have successfully loaded the Looking Glass project into NetBeans. You are now ready to build Looking Glass in NetBeans.

Building the Looking Glass Project in NetBeans

In the NetBeans project window, right click on the lg3d-core project and select "Build Project as shown in Figure 13 below.

Figure 13 Build Project

This will initiate a build of the Looking Glass project. You will notice in the bottom of the NetBeans IDE, the output window will show the results of building the Looking Glass source files. An example NetBeans output window from building Looking Glass is shown in Figure 14 below.

Figure 14 Looking Glass build output - click for full size image

When the build of Looking Glass has completed, you will see a status message at the bottom of the output window saying it has finished building Looking Glass.

You have now successfully built Looking Glass in NetBeans. Next you will run the Looking Glass window manager from NetBeans.

Running Looking Glass Project in NetBeans

To run the Looking Glass window manager from NetBeans, right click on the lg3d-core project and select the "Run Project" option as shown Figure 15 below.

Figure 15 Running Looking Glass

If you have configured your environment for running the Looking Glass window manager as described in this document and you have successfully built Looking Glass in NetBeans, you will see a window running the Looking Glass window manager which is very similar to that shown in Figure 16 below. There are additional applications being added to the Looking Glass window manager at the time of this writing. So, the applications shown on the task bar may differ slightly from those shown in Figure 16.

Figure 16 Looking Glass Window Manager - click for full size image

Notice that by clicking the CD icon on the taskbar it will open the CD viewer, a 3D demo application. If you mouse over the stack of CDs and click on the CD images you will see the application in action.

For additional operational information, click the icon to the right of the CD Viewer on the taskbar. This will open a panel that summarizes the operations supported by the demo. Note that the left most icon, a computer, launches an xterm window. This item demonstrates X11 application integration and may not work in all configurations.

The far right icon, skull and cross bones, when clicked will exit the Looking Glass window manager.

That's all there is to having an environment where you can build and run the Looking Glass window manager. Fun isn't it?

Setting up a NetBeans Project for Looking Glass Demo Apps

Now that you have enjoyed the ease at which you can build and run Looking Glass in NetBeans, it is time to setup a NetBeans project so you can make modifications to the lg3d-demo-apps in addition to being able to modify the source code of lg3d-core.

Early in this document you retrieved the source files for lg3d-demo-apps in the section title, "Getting the lg3d-demo-apps source". In this section you will setup a NetBeans project so you can make modifications to the lg3d-demo-apps, see those changes by rebuilding and running Looking Glass in NetBeans.

To setup a NetBeans project for lg3d-demo-apps, you tell NetBeans to create a new project as shown in Figure 17 by selecting File > New Project from the main menu.

Figure 17 Create a New Project

After selecting the File > New Project menu item, the NetBeans IDE will launch the New Project wizard. In the New Project wizard select the General Category and Java Project with Existing Sources project type as shown in Figure 18.

Figure 18 Choosing a General Java Project with Existing Sources - click for full size image

Press the Next button to go to the Name and Location screen of the New Project wizard. Enter a project name. I chose a project name of "lg3d-demo-apps". Enter the path to the directory of the lg3d-demo-apps source. The lg3d-demo-apps source is the directory you specified  in the "Getting the lg3d-demo-apps source" section. Then, uncheck the "Set as Main Project" button.

An example screen shot of the New Project wizard for the directory where I placed the lg3d-demo-apps source is shown in Figure 19.

Figure 19 New Project Name and Project Location - click for full size image

Press the Next button to go to the Existing Sources screen of the New Project wizard. On the Existing Sources screen you tell NetBeans where to find source files for the lg3d-demo-apps.

Add the lg3d-demo-apps source folder by clicking on the Add Folder button for the Source Package Folders. Traverse to and select the lg3d-demo-apps/src/classes directory. Example screen shot for my development environment is shown in Figure 20.

Figure 20 Location of lg3d-demo-apps sources - click for full size image

Press the Finish button to leave the New Project wizard.

In order to leverage NetBeans syntax highlighting, code completion and instant compilation, we need to tell NetBeans where to find the lg3d-core class files which the lg3d-demo-apps depends upon. You do this by right clicking on the newly created project for lg3d-demo-apps in the projects window and selecting the "Properties" option as shown in Figure 21.

Figure 21 Selecting lg3d-demo-apps project properties

Tell tell NetBeans where to find the dependent lg3d-core class files, on the Project Properties window, select "Libraries" for Categories and select the "Compile" tab as shown in Figure 22.

Figure 22 Selecting compile time libraries - click for full size image

Click on the "Add Jar/Folder" button to add the lg3d-core/build/classes directory.  Traverse to and select the lg3d-core/build/classes directory. The path to this directory will be the one you specified as the directory in the "Getting the lg3d-core source" section earlier.

An example screen shot showing the path to lg3d-core directory I used is shown in Figure 23.

Figure 23 Selecting compile time libraries - click for full size image

Press the "Ok" button to leave the "Project Properties" wizard. You will see NetBeans update lg3d-demo-apps classpath information with the lg3d-core class files.

Expand the lg3d-demo-apps project to the source file org.jdesktop.lg3d.apps.tapps.WebIcon.java as shown in Figure 24.

Figure 24 Expanding the lg3d-demo-apps source tree

Double click on the WebIcon.java file to load it in the NetBeans editor. You can make edits to this file and compile it directly by either pressing the shortcut key "F9" or by selecting the Build > Compile menu item.

You can edit any file under the newly created lg3d-demo-apps project and compile it. To test your modifications or changes to any of the lg3d-demo-apps source code in the Looking Glass window manager, just right click the lg3d-core project in the projects window and select "Run Project" or select "Run > Main Project" from the main menu.  Or, you can simply press "F6" to compile the edited file. Remember the lg3d-core project is the project you run the Looking Glass window manager with. It will automatically pick up your modifications to the lg3d-demo-apps projects.