CCV Development Guide

From VrlWiki
Jump to navigation Jump to search

The YURT

The YURT Ultimate Reality Theatre (a recursive acronym) is a large 16'x12' virtual reality room situated in the Center for Computational Vision (CCV) building at 180 George St. The walls, floor, and most of the ceiling are screens upon which projectors display a graphical program. Head-tracking and stereo vision complete the package for a fully immersive virtual reality experience.

CCV Filesystem

The Center for Computational Vision has its own Linux filesystem. This system is entirely independent of the CS Department's filesystem. Many applications and development tools CS students usually expect to have access to are not present, and there are a few important differences in the way programs and files are organized.

Getting an Account

To request an account, go to https://web1.ccv.brown.edu/start/account

If you need help, talk to Tom Sgouros or John Huffman. Professor David Laidlaw can also help point you in the right direction.

Modules

The CCV system is a monolithic repository for a large number of different programs and projects, many of which require particular versions of dependencies. Between the accumulated legacy software and limited resources for ongoing development, attempting to synchronize dependencies (such as Python or gcc versions) is infeasible. Rather than attempt to enforce a single standard version for any given dependency, the filesystem employs a modules system.

The way the modules system works is simple. Dependencies are installed in a common shared directory. Individual users create module files that point to which specific dependencies they would like to use. The modules system then sets the environment variables to include those dependencies.

Each user has a default .modules file in their home directory. If this is not the case, copy someone else's (such as Tom Sgouros's) module file. The modules listed in this file are loaded when you log into your account. Individual modules can be loaded or unloaded by using a simple command line interface. Use module list to see all the modules you currently have loaded, and module load and module unload to change them.

Modules needed for developing YURT programs

The following is a list of modules that should be in your module list when developing VRG3D and YURT applications. Some modules may need to be changed or removed depending on the situation.

  • centos-libs/6.7 These are the updated OS libs. Check to see that your version is not 6.5.
  • vprn/7.31 VRPN is the input server for tracking the movement of input devices like wands and glasses.
  • cave/ccv Has cave modules such as VRG3D and other important libraries.
  • cave/jnh John Huffman's alternate version of the former. May be more up to date.
  • cave-utils/yurt Additional cave utils.
  • g3d/8.01 G3D dependency for VRG3D.
  • nvidia-driver/331.38 This driver may or may not be useful/required for developing.

Qt

The CCV system has a working version of Qmake installed. Unfortunately, the CCV system does not have a working version of QtCreator installed. Furthermore, Qt5 does not work with the filesystem (QtCreator 3 simply segfaults). As of May 2016, it is unclear why Qt5 does not work. The solution in the meantime is to download and install backversions of QtCreator and Qt4.

Qt and C++11/C++14

Qt4 for some reasons seems unable to recognize C++11 compiler flags, even though the gcc version it's using is supposed to support it. This is a problem worth solving for anyone coming from the CS Department, which uses C++11 as a standard.

Qt .pro Files and Qmake

QtCreator provides a tremendous productivity boost over makefiles, the traditional form of project coordination for a number of YURT applications. However, compiling and linking programs with QtCreator with VRG3D is not straightforward. The .pro file requires special attention:

  • The best way to start a new Qt project is to build off of a previous .pro file. mjm9's home directory is open, and the project contained in ~yurt/yurtcraft/project provides an example of how to properly set up a Qt .pro file in order to compile and link on development machines.
  • There are a large number of libraries required for VRG3D. These must be enclosed using -Xlinker --start-group and -Xlinker --end-group. This is slightly different from makefile templates, which include -Xlinker before every linked library in the list.
  • The G and GARCH environment variables must be set before opening QtCreator from the command line, as they are referenced from within the Qt .pro file. These are magic environment variables required by the build process. Note that these only work on the CCV machines. Use export from the command line to set the variables:
    • G=/gpfs/data/dhl/gfx/G/
    • GARCH=linux
  • To add a library to your project, right-click the .pro file in the text-editing pane (not the file icon in the file viewer). Go through the steps of adding the external library as usual, and Qt will automatically add three chunks of text to the .pro file. You must delete the last chunk. The chunk in question is commented out in mjm9's .pro file as an example.

Important Qt. pro File Data

Other demo applications come with makefiles where this information is set up for you, however converting these makefiles into the more useful Qt .pro files isn't entirely straightforward. The following is the key block of Qt .pro code required to build and link a VRG3D application. 

INCLUDEPATH += $(G)/install_linux/include
DEPENDPATH += $(G)/install_linux/include
DEPENDPATH += $(G)/install_linux/lib

INCLUDEPATH += $(G)/install_linux/include/ffmpeg
DEPENDPATH += $(G)/install_linux/include/ffmpeg

INCLUDEPATH += -I$(G)/install_linux/include -I$(G)/install_linux/include/vrg3d

LIBS += -Xlinker --start-group -ldl -lX11  \
        -lXext -lpthread -lz -ljpeg   \
        -lpng -lzip -lSDL -lvrg3d   \
        -lavutil -lavformat -lavcodec -lGLG3D \
         -lG3D -lGLU -lGL -lvrpn -lzip \
         -lglut -lXmu -Xlinker --end-group -lmplEasyBlendSDK \
        -L$(G)/install_linux/lib -L$(G)/install_linux/lib/vrg3d
  • G: Note that the environment variable must be set before starting QtCreator.
  • -Xlinker --start-group ... --Xlinker --end-group: These linker flags resolve circular/out of order library dependencies.

Compiling and Running

Compiling for a typical computer typically only requires an IDE or simple command line makefile system. Compiling for the YURT is a bit more involved.

Development Computers

There are a number of development computers in the CCV building, and many are configurely somewhat differently from one another. You must acquire a CCV account before you can use any of the machines.

dev**

These are the regular desktop computers in the room to the right of the YURT. They do not have modern graphics cards, and their drivers date to roughly 2006. As such, testing modern graphics applications on them is impossible. However, programs compiled and linked on them should be runnable on the more up-to-date computers that the YURT and wall both run on. Run your IDEs of choice and build your programs on the dev** machines, then run and test your programs on the YURT or wall.

cave**

There are 20 different Cave machines, and machines 01 through 19 run the YURT. Machine cave20 is a test machine. All cave** machines are equipped with high-powered, modern graphics cards.

It is important to note that running the YURT-kill script from the YURT kiosk will kill everything running on the cave machines 1-19, so it is not a good idea to remotely test on them during the day.

login001

Login001 is what the kiosk runs on.

Nonuniform disk images

While all of the machines are on the same filesystem, as of May 2016 not all of the disk images on each of the machines are identical. Changes made to your home directory will persist across different machines (dev, cave, etc.) however dependencies may change. To ensure that your project can run in the YURT, make sure to compile and link it on login001 to avoid any issues. You don't need to physically go to the kiosk - simply ssh in from a dev machine.

Recommended Build Process for QtCreator users

Building with Qt is a two-step process. The first step involves building from the IDE as usual. The second step involves running the makefile from login001.

The Kiosk

The YURT and the test wall each have a web kiosk that allows you to easily run programs from the browser. The most useful button for development is the kill-all button, which shuts down active user processes on each of the computers.

The Test Wall

The test wall in the common room is the best spot for developing and testing your programs. While its projectors have dead pixels and there is no curvature, it is still very easy to test whether your program is projecting everything correctly.

Useful facts:

  • The test wall has its own kiosk, which can be accessed from 172.20.8.9/wall in the web browser. The kiosk can conveniently be run from any machine.
  • In case your project continued running after you hit the kill button, you will have to ssh into dev10 and kill the processes by hand.
  • In order to run a project on the test wall, use the run-wall script, which should already be in your path, using your program name as an argument.
  • The projectors are similar to those that run in the YURT in that they burn out over time. As such, it is best not to turn them on and off very much, for the heating and cooling process erodes the hardware. Try to work in fewer, longer chunks of time rather than more numerous and shorter chunks of time.

The YURT

The YURT operates just like the wall, except it's way more awesome. Useful facts:

  • Gain access to the YURT calendar to see when it is free. Ask Tom Sgouros to add you. You will most likely have some trouble developing on it during the day for longer periods of time, as tours are always coming through and other researchers are looking to schedule time as well. The YURT is usually much freer later in the evenings and at night.
  • Use the run-cave script instead of the run-wall script. It works the same way.
  • No shoes in the YURT!

Getting Started

The best way to get started is to find an existing example project and learn from the source code. Most of VRG3D hooks into applications "at the top," by providing input and graphics information. The technical details of the program implementation after that are actually the same as for traditional flat media. After you take the wheel from VRG3D, the real (and cool) problems will be related to VR interaction, not OpenGL.

VRG3D Source Code & Documentation

VRG3D source code: https://sourceforge.net/p/vrg3d/code/HEAD/tree/

VRG3D's documentation: http://vis.cs.brown.edu/resources/doc/VRG3D/index.html

G3D's documentation: http://graphics.cs.williams.edu/courses/cs371/f10/G3D/manual/index.html

Example Projects

YURTCraft

YURTCraft is a functioning VRG3D application whose sourcecode is freely available on GitHub at https://github.com/ebirenbaum/yurtcraft. While it does not have a properly functioning Qt .pro file, it does have makefile that works. The code base is a good source of information for how to integrate VRG3D with an existing application. However, because it uses old fixed-function pipeline OpenGL, it will not compatible with any CS Department student projects without some reverse-engineering.

Shadertoy Visualizer

The Shadertoy Visualizer by mjm9 was built from the YURTCraft project skeleton. It compiles and links using QtCreator, which is conducive to porting over CS Department student projects from classes like CS123 and CS-1972. Furthermore, it uses the modern programmable shader pipeline OpenGL and contains the code for reverse-engineering VRG3D's fixed-function pipeline.

The project can be accessed in mjm9's publicly available home folder mjm9/yurt/yurtcraft/project. When you yourself log in, cd .. out of your home directory and then cd into mjm9's.

Note: VRG3D sets the framebuffer into which the program renders its output. Programs using custom framebuffers will need to back up the framebuffer which VRG3D supplies (by simply retrieving and storing its ID) before using custom ones and then rebind it at the end of their render loops.

Helpful People

In case you get stuck, which you will, the following people are extremely good friends to have.

Tom Sgouros

Tom is the manager of the YURT and has extensive knowledge of the CCV filesystem. Should this page prove insufficient, which it likely will at some point, ask Tom for help.

Ben Knorlein

Ben is an energetic and useful ally to have in the tall grasses of the CCV. He, too, can help newcomers figure out what to do.

Johannes Novotny

Johannes is a PhD student working on the YURT and is another good source of practical information.

John Huffman

John Huffman, like Tom, has extensive knowledge of the inner workings of the CCV filesystem, as well as other devices like the VRPN server.

Retrieved from "http://vrl.cs.brown.edu/wiki/index.php?title=CCV_Development_Guide&oldid=6821"