Getting started with the Project Looking Glass Developer's Release

Welcome to Project Looking Glass!

This document is intended to get you up and running quickly with the Project Looking Glass Developer's Release.

To get started you'll first need to set up your environment. Once you've verified that your environment is set up correctly you can download and install Project Looking Glass.

1. Platform Requirements Hardware and software requirements
2. Setting up your project Looking Glass environment Downloading and installing the required components
3. Installing the Project Looking Glass Developer's Release
4. Running Project Looking Glass How to start a Project Looking Glass desktop session
5. Troubleshooting
6. Staying connected with Project Looking Glass How to stay in touch!
7. Some final words

1. 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 Requirement
Operating System Linux on x86: Most modern linux distributions should work, although there have 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.

Solaris on amd64: Looking Glass is now supported on Solaris x86 S10_b74 (or later).
CPU 2 GHz or faster recommended
RAM 512MB
Graphics Card*
Linux x86: A 3D accelerated graphics card with driver support for OpenGL, version 1.2 or greater.
For Nvidia devices you must use at least the following driver version: 1.0-6629. Refer to here for important information on how to configure Nvidia cards for LG3D.

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.

Solaris x86: At the time of this writing, the only type of graphics cards supported on Solaris x86 are certain Nvidia cards (see below). The Nvidia driver for Solaris x86 (1.0-7664) can be downloaded from here.
Refer to here for more information.

Currently only the following Nvidia graphics devices are supported by the Solaris x86 driver.
    Quadro FX 4000
    Quadro FX 3000
    Quadro FX 1100
    Quadro FX 500
    NVS 280
IMPORTANT! 24bit display depth is required for all platforms and all devices! See the instructions below for how to configure this.
IMPORTANT! Some graphics cards require special configuration in order to run Project Looking Glass. 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

Disk Space 350MB

2. Setting up your Project Looking Glass environment

Before you can run Project Looking Glass, you need to install a number of Java components. The simplest way to do this is to download all of the components and then install them in the order listed below.

Download the components

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

  1. Java JDK, Standard Edition (J2SE)

    Linux x86: Version 5.0 or later.
    Note: The installation instructions below assume you download the RPM version of the JDK.

    Solaris x86: Version 5.0 update 3 or later.
    Note: The installation instructions below assume you download the packages version of the JDK.

    The JDK may be downloaded from http://java.sun.com/j2se/1.5.0/download.jsp

  2. Java 3D SDK 1.4 or later
    There is not yet an official release of Java3D 1.4 but stable builds are available.
    These can be downloaded from: The Java3D binary builds page.
    1.4.0-build4 or later is recommended (and required for the shader support).

    Linux x86: Download java3d-1_4_0-build4-linux-i586.zip.

    Solaris x86: Download java3d-1_4_0-build4-solaris-x86.zip.

  3. Java Advanced Imaging API (JAI) SDK 1.1.2 or later
    http://java.sun.com/products/java-media/jai/downloads/download-1_1_2.html

    Linux x86: 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).

    Solaris x86: Select the JDK(TM) Install: Bundle for installation in a JDK Download. After reading and agreeing to the Software License Agreement, choose the Solaris x86 JDK Install item (jai-1_1_2-lib-solaris-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 JDK 5.0:

    Linux x86:
    # cd /tmp
    # /bin/bash jdk-1_5_0_03-linux-i586-rpm.bin
    # rm jdk-1_5_0_03-linux-i586.rpm
    # rm jdk-1_5_0_03-linux-i586-rpm.bin


    Solaris x86:
    # cd /tmp
    # uncompress jdk-1_5_0_03-solaris-i586.tar.Z
    # tar xvf jdk-1_5_0_03-solaris-i586.tar
    # /usr/sbin/pkgadd -d . SUNWj5cfg SUNWj5dev SUNWj5dmo SUNWj5jmp SUNWj5man SUNWj5rt
    (Answer 'y' to all the questions)
    # /bin/rm -rf SUNWj5cfg SUNWj5dev SUNWj5dmo SUNWj5jmp SUNWj5man SUNWj5rt
    # /bin/rm -f jdk-1_5_0_03-solaris-i586.tar


  3. Install the Java 3D SDK:

    Linux x86:

    # cd /tmp
    # unzip java3d-1_4_0-build4-linux-i586.zip

    Then follow the instructions in the file /tmp/java3d-1_4_0-build4-linux-i586.zip/HOW-TO-INSTALL.TXT. (Answer 'y' to any questions that are asked).

    Solaris x86:

    # cd /tmp
    # unzip java3d-1_4_0-build4-solaris-x86.zip

    Then follow the instructions in the file /tmp/java3d-1_4_0-build4-solaris-x86.zip/HOW-TO-INSTALL.TXT. (Answer 'y' to any questions that are asked).

  4. Install the Java Advanced Imaging API:

    Linux x86:
    # cd /usr/java
    # /bin/bash /tmp/jai-1_1_2-lib-linux-i586-jdk.bin


    (Answer 'y' to any questions that are asked).

    Solaris x86:
    # cd /usr/java
    # /bin/bash /tmp/jai-1_1_2-lib-solaris-i586-jdk.bin


    (Answer 'y' to any questions that are asked).

  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
    PATH=$JAVA_HOME/bin:$PATH

3. Installing the Project Looking Glass Developer's Release

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.

Download the Project Looking Glass installation package

The current release of LG3D is Release 0.7.0. Before you start using this release be sure to read the Release Notes.

To download the installation package for your platform, click on this link: https://lg3d-core.dev.java.net/binary-builds.html. After the package has been downloaded, change to the directory in which you wish to install LG3D and extract the files as follows. (In this example we will use/tmp as directory where you downloaded the package and /home/username as the LG3D installation directory.
The files will be extracted into a directory named lg3d in the current directory.

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 distributions:

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.
Solaris x86 :

Solaris x86 uses the xorg.conf file to configure the display properties for the Xorg server which is used by Project Looking Glass. To change the color depth on Solaris x86:

  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" and change the DefaultDepth property to 24:

    DefaultDepth     24

  4. 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.

4. Running Project Looking Glass

There are three different ways to run LG3D:

(Note: when reporting a bug, be sure to include the mode you were running).
  1. Application Mode (lg3d-app)

    This mode is also known as "app mode." This mode is started by executing the script bin/lg3d-app from within an existing X session (such as GNOME, KDE, or CDE). In this mode LG3D runs as a normal application within the existing X session: you can move the LG3D window, resize it, or iconify it. In this mode you can run both LG3D 3D applications and native X11 applications.

    IMPORTANT NOTE! In order to run this mode, you will need to make sure you install the LG3D release on a LOCAL disk partition. Also, after you have installed it, you will need to become the root user and run bin/postinstall.

    Supported platforms: app mode is currently supported only on Linux and Solaris x86.

    (Note: At the time of this writing, app mode only works on Linux. There are some bugs which make app mode on Solaris x86 unusable).

  2. Session mode (lg3d-session)

    This mode is started by bringing down an existing X session and then by running the script bin/lg3d-session. In this mode LG3D takes over the entire screen and runs as the primary session manager. In this mode you can run both LG3D 3D applications and native X11 applications.

    Refer to Running Project Looking Glass full-screen (Session Mode) for instructions on how to configure your machine to run session mode, including how to bring down the existing X session.

    Supported platforms: session mode is currently supported only on Linux and Solaris x86.

  3. Developer mode (lg3d-dev)

    This mode is also known as "dev mode." This mode is started by running the script bin/lg3d-dev from within an existing window session (such as GNOME, KDE, CDE or Windows). In this mode LG3D runs as a normal application within the existing X session: you can move the LG3D window, resize it, or iconify it. In this mode you can ONLY run LG3D 3D applications; you cannot run any native X11 applications. This is the main difference between dev mode and app mode.

    Refer to Running Project Looking Glass within an existing desktop environment (Dev Mode) for instructions on how to configure your machine to run session mode, including how to bring down the existing X session.

    Supported platforms: dev mode is supported on any system which supports the Java JDK 1.5.0. This includes Windows, Linux, and Solaris x86. (Theoretically it will also run on Apple OSX, although this hasn't been tested).

    Note: the easiest way to verify that your Project Looking Glass installation is correct is to run the dev mode within an existing desktop. Then, once you're satisfied that it is working correctly, you can configure your system to run Project Looking Glass in session or app mode. Note that running Project Looking Glass in dev mode is a good way to develop and test 3D applications and enhancements to the Window Manager (aka Scene Manager).

Running Project Looking Glass within an existing desktop environment (Dev Mode)

In this mode, a Project Looking Glass session runs in a window in your desktop. This is the simplest way to run Project Looking Glass but this mode only allows you to run Project Looking Glass 3D applications, such as the CD viewer. X11 applications, such as xterm will appear outside the LG screen; they will appear in the X session from which you launched the Project Looking Glass session.

  1. Log into your account and change directory to where you installed Project Looking Glass:

    % cd /home/username/lg3d/bin

  2. And start the Project Looking Glass session:

    % ./lg3d-dev

If you have successfully installed Project Looking Glass you should see the familiar Project Looking Glass desktop in a window on your desktop:

Project Looking Glass Screenshot

Clicking the CD icon on the taskbar will open the CD viewer, a 3D demo application. Mouse over the stack of CDs and click on the CD images to see the application in action. For addtional operational information, click the icon to the left of the CD Viewer on the taskbar. This will open a panel that summarizes the user interface operations supported by the default Scene Manager. Note that the left-most icon, a computer, launches an xterm window. This item demonstrates X11 application integration and is only supported in sessionmode. See the next section for instructions on how to configure session mode.

Running Project Looking Glass full-screen (Session Mode)

This mode allows you to run Project Looking Glass full-screen and launch any application, including native X11 applications. You must first shutdown your X session before starting Project Looking Glass.

Bringing down your existing X session
The instructions for shutting down your X session vary by platform, so follow the instructions that apply to your platform. If your platform isn't listed, chances are the process will be very similar so use these instructions as a guide and let us know what's different!

Sun Java Desktop System/SuSE 8.1:

JDS/SuSE 8.1 uses the X Display Manager (xdm) to manage user sessions. To run Project Looking Glass you must first shut down xdm. Since this process is respawned automatically you must disable this service using the chkconfig command:

  1. First become root:

    % su root
    Password:
    enter root password
    #

  2. Disable the xdm service:

    # /sbin/chkconfig -d xdm
    xdm  0:off   1:off   2:off   3:off   4:off   5:off   6:off

  3. Now close any desktop applications and save any open files. Then shutdown the display manager:

    # pkill gdm-binary

  4. Now skip to the Starting the Project Looking Glass desktop session section.

Note: To re-activate the X Display manager, enter the following command as root, and then reboot your system:

# /sbin/chkconfig -a xdm
RedHat 9:

RedHat uses the GNOME Display Manager (gdm) to manage user sessions. It's not necessary to disable gdm, you can simply switch to a lower run level where gdm is not active:

  1. First become root:

    % su root
    Password:
    enter root password
    #

  2. Close any desktop applications and save any open files. Then switch to run level 4:

    # /sbin/init 4

    Your X session should terminate and your should return to the console prompt.

  3. Now skip to the Starting the Project Looking Glass desktop session section.

Note: To restart the GNOME Display Manager, enter the following command as root from the console:

# /sbin/init 5
Fedora Core 3 64-bit:

To run Project Looking Glass full screen on the 64-bit version of Fedora Core 3 requires a few unique changes. Note that you will need access to a 32-bit Linux system or the 32-bit X11 modules for Linux to complete this procedure.

  1. You will need to copy the contents of the /usr/X11R6/lib/modules directory from a 32-bit Linux system to the same directory on your 64-bit system. Before performing this action, make a backup of the /usr/X11R6/lib/modules directory on your 64-bit system:

    # cd /usr/X11R6/lib
    # cp -r modules modules.orig

    Next, use the scp command to securely copy the files from the 32-bit system to your 64-bit system:

    # scp -r root@32bithost:/usr/X11R6/lib/modules /usr/X11R6/lib/modules

    where 32bithost is the host name of the 32-bit Linux system.

  2. Make sure that your xorg.conf file is set for depth of 24 as shown in bold below:

    Section "Screen"
    Identifier "Screen0"
    Device "Videocard0"
    Monitor "Monitor0"
    DefaultDepth 24
    SubSection "Display"
    Viewport 0 0
    Depth 24
    Modes "1680x1050" "1280x800" "1024x768" "800x600" "640x480"
    EndSubSection
    EndSection

  3. Proceed to the next section to start the full screen session.

    [Instructions in this section courtesy of qgonjon and marve. See this support thread.]
Solaris x86:

In order to run Project Looking Glass in session mode on Solaris x86, you must first shut down CDE and disable its subsequent boot-time start up. To do this, become root and type:

# /usr/dt/bin/dtconfig -d

then reboot your computer.

Starting the Project Looking Glass desktop session

Once you have brought down your existing X session, to start Project Looking Glass in session mode do the following:

  1. Become root and change directory to where you installed Project Looking Glass:

    # cd /home/username/lg3d/bin

  2. Start the Project Looking Glass desktop session:

    # ./lg3d-session

    After a few seconds, the Project Looking Glass desktop should appear. Congratulations! If you have problems starting the desktop session, refer to the Troubleshooting section for assistance.

Explore the Project Looking Glass desktop and start dreaming of new ways to enhance the desktop user experience with 3D! When you're ready to do development, skip over to the Project Looking Glass Developer's Guide for information about developing with Project Looking Glass.

5. Troubleshooting

no core pointer

This happens on RedHat Fedora Core 2, and may happen on other configurations as well. One known workaround (from sgiunchi) is to do the following (as root user):

# ln -s /etc/X11/xorg.conf /etc/X11/XF86Config-4

The correct long term fix is to upgrade the X11 release which is included in lg3d-core. It is currently an Xorg 6.7 pre-release and it needs to be upgraded to the latest Xorg stable release.

Exception in thread "main" java.lang.UnsatisfiedLinkError: /usr/java/jdk1.5.0/jre/lib/i386/libj3dcore-ogl.so:
/usr/java/jdk1.5.0/jre/lib/i386/libj3dcore-ogl.so: symbol glMultiDrawArraysEXT, version LIBGL not defined in file libGL.so.1 with link time reference

This error occurs with ATI device drivers that are missing the glMultiDrawArraysEXT extension. The solution to this problem is to replace the Radeon device drivers with drivers from the Direct Rendering Open Source (DRI) project. For instructions on installing direct rendering drivers refer to DRI driver installation for ATI Radeon.

Note that upgrading libGL.so to the latest Mesa libraries does not solve this problem.

pkill: 27863 - Operation not permitted
java.rmi.server.ExportException: Port already in use: 1099; nested exception is:
      java.net.BindException: Address already in use...

This message indicates that an rmiregistry process is already running and lg3d-dev was unable to start a new instance. Typically this occurs when the rmiregistry process was started by root and lg3d-dev is run as a non-root user. The solution to this problem is to stop the root instance of rmiregistry. Become root and stop the process:

% su root
Password: enter root password
# pkill rmiregistry
# exit

Now re-run the lg3d-dev command as a non-root user to start Project Looking Glass.

Fatal Server error: Cannot establish any listening sockets

The following error message is displayed when you start Project Looking Glass using lg3d-session:

_XSERVTransSocketUNIXCreateListener: ...SocketCreateListener() failed
_XSERVTransMakeAllCOTSServerListeners: server already running

Fatal server error:
Cannot establish any listening sockets - Make sure an X server
isn't already running

First, make sure that you do not have an X11 session running on the display on which you're starting lg3d-session. Then check to see if you have /tmp/.X11-unix/X0 left behind from a previous session. To fix this problem, delete this file and restart lg3d-session.

Screen updates are very slow

This usually means that graphics acceleration is not correctly configured. Here are some things to check first:

libGL error: failed to open DRM: operation not permitted

(This error may be encountered when running lg3d-dev).

If Project Looking Glass runs very slowly, even though 3D acceleration is enabled, check to see if the following message appears in the console:

libGL error: failed to open DRM: Operation not permitted
libGL error: reverting to (slow) indirect rendering

This means that your user account doesn't have permission to use the DRI (Direct Rendering Infrastructure). In some cases root is the only user with access to Direct Rendering. This problem seems to only affect RedHat users, and not JDS/SuSE users. If you have this problem, you should change the DRI permissions in your XFree86Config or XF86Config file to:

Section "DRI"
Group "video"
Mode 0666
EndSection

You will also need to change the permissions of the <dri> profile in /etc/security/console.perms from 0600 to 0666:

<xconsole> 0600 <dri> 0666 root

and if you're using an NVIDIA card, change the permissions on /dev/nvidia* to 0666:

# chmod a+rw /dev/nvidia*

An unexpected exception has been detected in native code outside the VM

Project Looking Glass exits with the following exception, even though you've verified that you have 3D acceleration enabled:

An unexpected exception has been detected in native code outside the VM.
Unexpected Signal : 11 occurred at PC=0x0
Function=[Unknown.]
Library=(N/A)

Check to see if the following entries appear in the exception message:

<addr-range> r-xp 00000000 03:05 61763 /usr/lib/GL/libGL.so.1.3.mesasoft
<addr-range> rw-p 001b4000 03:05 61763 /usr/lib/GL/libGL.so.1.3.mesasoft

If so, you have the MESA software OpenGL libraries installed. Use the package tool for your distribution (e.g., rpm) to remove these libraries, and then go into /usr/lib as root and check that the following symbolic links exist and point to the correct OpenGL libraries. You should have links that look something like this (where x and y are numbers):

libGLcore.so.1 -> libGLcore.so.1.x
libGL.so -> libGL.so.x
libGLU.so -> libGLU.so.x.y.z

If these links are not correct, become root and create them. For example, if you have a libGLU.so.1 file but no libGLU.so link, then create the link:

# ln -s /usr/lib/libGLU.so.1 /usr/lib/libGLU.so

Repeat this for each of the links that are missing.

Failed to load the NVIDIA driver

There are several possible reasons for the driver failing to initialize correctly:

See also:

Project Looking Glass Developer's Release Notes

Additional information on current problems and issues can be found under lg3d-core Project Tools > Issue tracker. You can search for issues and defects or find a specific issue.

6. Staying connected with Project Looking Glass

The Project Looking Glass project is evolving continually. The best way to keep up to date with Project Looking Glass developments is by subscribing to the Project Looking Glass mailing lists. Click on Mailing lists in the Project tools section of the side bar on https://lg3d.dev.java.net/. There are several mailing lists to choose from depending on your level of interest.

7. Some final words

Thanks for getting involved with the Project Looking Glass project! We're really looking forward to your contributions in this exciting new desktop experience!

The Project Looking Glass Development Team

See also:

Project Looking Glass Developer's Release Notes
Project Looking Glass Developer's Guide
Installing and Configuring Device Drivers for 3D Desktop Project Looking Glass


$Revision: 1.33 $ $Date: 2005/06/26 00:07:01 $