Lua bindings and high-level interface for virtual experience creation, built on VR Juggler

VR JuggLua homepage on GitHub: https://github.com/vancegroup/vr-jugglua

Maintained by the Vance Research Team at Iowa State University's Virtual Reality Applications Center. Original author: Ryan Pavlik, rpavlik@iastate.edu abiryan@ryand.net

We have a Google Group that you're encouraged to use.

• Web access (to join, and optionally to post/read archives on the web): https://groups.google.com/d/forum/vr-jugglua
• Email address to use once you've joined: vr-jugglua@googlegroups.com

These are Windows automated snapshot builds, created every time the main repository is pushed to. Ready to unzip and use.

Note: If you're in the ISU Virtual Reality Applications Center, these snapshots are automatically unzipped, ready to run, in in X:\vr\apps\vrjugglua aka V:\apps\vrjugglua We recommend using that continuously-updated build instead of using a locally-unzipped snapshot when possible.

For the full change history, see the git repository. This section is a high-level overview of useful, user-facing changes by date (newest changes at the top).

• Extended functionality: A long-awaited overhaul of math operator support has landed. This means that you can just use +, -, *, -, etc. as appropriate with matrices, vectors, quaternions, and numbers: this should be much more convenient. (* is a dot product for two vectors, and ^ is a cross product for 3-dimensional vectors only)

• Additional functionality: You can now access VR Juggler/Gadgeteer "String" devices (like speech recognition devices) with gadget.StringInterface objects, that have a single string property data that changes each frame. Thanks to Patrick Carlson for the implementation of this!
• Additional functionality: For those who would like to apply lighting or other state to the entire scene, including both nodes under RelativeTo.World and RelativeTo.Room, you may now use the global GlobalStateSet to do so.

• Community change: We now use a Google Group for mailing list/forum purposes.

• Added example/template: The AppTemplate directory is intended to be copied and pasted and used as the start of your own application. It contains examples of how to make an app in a directory, with some sample features. Run it by dropping/opening main.lua. For interactive development, you can drop appdir.lua to set up the directory without running additional code. You'll want to edit the .lua files, put your models in there instead of the example, etc.

• Added module: require "AddAppDirectory" will make a function AddAppDirectory() available that adds the current file's directory to the model search path. This should replace usage of vrjLua.appendToModelSearchPath(getScriptFilename()). It issues a warning if not run from a file - call AddAppDirectory(true) to make it an error instead.

• Added default module: By default, the runfile module is now loaded creating the runfile(filename) function. The filename given will be searched for in the model search path, run if found, or an error reported if not found. This should replace most (all?) usage of dofile(vrjLua.findInModelSearchPath(...)).

• Extended functionality: At long last, there is a MatrixTransform{} constructor to match the Transform{} constructor that makes PositionAttitudeTransforms. You can pass an initial matrix similar to how you pass position to Transform: MatrixTransform{matrix = yourmatrix}

• Improved functionality: We now extract even more OpenGL defines into gldef, in particular including the blend function defines.

• Improved functionality: The Vec functions now can make copies of OSG vectors - pass an OSG vector, table, or just numbers in, and you'll be sure to get a vector out.

• Extended functionality: There's now a Switch{} constructor which behaves like Group{} except: a) it creates osg.Switch nodes, and b) you can optionally define the initial state (on or off) of children by passing them like Switch{ [myNode] = true, [myOtherNode] = false}. (Of course, just passing them in as you would with the other group nodes works fine too.)

• Added module: require "gldef" will create a table gldef containing all the potentially-useful definitions (of constants/enumerations) extracted from gl.h. These are sometimes necessary for more advanced lighting code with OSG.

• Improved error catching: Added detection for when you try to run Actions.waitFor____ when you're not in a frame action, and throw a useful error instead of the cryptic one Lua would throw about yielding through C code or something like that.

• Added examples: some basic lighting examples - thanks to Leif Berg!

• Improved/added functions: To easily construct OSG vectors of various sizes, just call Vec(x, y, z). It automatically detects the number of parameters passed and finds the correct OSG type (so for instance, that call would create an osg.Vec3d).

  • Note that if a VecXd (containing doubles) won't work for you, there are also matching functions Vecf, Vecb, Vecs, Vecus for creating osg.VecXf, osg.VecXb, osg.VecXs, and osg.VecXus objects respectively.

• Deprecated function: Vec3 is removed - just use Vec. Not sure anyone actually used Vec3 to begin with, so this should be no big deal.

• Improved structure: RelativeTo.World is now a matrix transform node, whose matrix describes the location of the World with respect to the Room. This is part of the progress for improving navigation.

• Change to defaults: The default navigation speed is halved, based on testing in METaL (one of our immersive VR facilities).

• Deprecated global variable: There is no more navtransform global, due to above restructuring. Its use had been discouraged for quite some time, so this should be very low impact.

• New interactive console feature: You can now drag and drop .lua files in to the code entry area, and Lua code to execute that file will be automatically entered. Similarly, dragging in .jconf (VR Juggler configuration) files will enter code to load that additional configuration. Note: You can drag in multiple files at once, or one after another; the entered code includes a newline so you can just drop files in one after another or in a bunch. This should save a lot of time and a lot of usage of the File menu.

• New interactive console feature: Menu item to load an additional .jconf file. Not expecting much use of this, given the feature above, but it might be useful if you can't have two windows open side-by-side easily.

• New interactive console feature: When typing in the code entry box, you can now press Ctrl-Return (Command-Return on the Mac) to run the code, instead of having to click Run. Thanks to Juan Sebastian Casallas!

• Added example: We now have an example for usage of TransparentGroup

• Improved structure (advanced): The stock navigation has now been moved into a frame action, so those interested in replacing it can call osgnav.removeStandardNavigation and then add their own frame action to move around.

• Build fix: Builds and works on Mac OS X again - thanks to Juan Sebastian Casallas!

• Improved packaging: Binary snapshots now contain a brief README file describing them (and their self-contained nature) and providing useful links.

• Improved functionality: The automatically-loaded help function now shows more detail about tables, and as a side effect correctly shows the methods of (Luabind-wrapped) VR JuggLua objects.

If you're interested in even earlier changes, please see the git repository history. Contributions of nicely-written summaries for this file are gladly accepted :D

###Source code git clone git://github.com/vancegroup/vr-jugglua.git

GitHub provides a lot of useful services for us at [project homepage][home].

• CMake 2.6 or newer (tested mainly with 2.8.3+) - build system generator

• Boost 1.35 or newer (tested mainly with 1.40 and 1.45)

• VR Juggler 3.0.x, built against the same Boost above. (Can also use VR Juggler 2.2.x (2.2.2 or newer recommended), but 3.0 is much nicer.)

• OpenSceneGraph, including osgIntrospection/wrappers (2.8.x tested)

  • Recommended to use the branch here: https://github.com/rpavlik/osg/tree/new-wrappers which is available compiled for windows here: https://github.com/rpavlik/osg-windows-binaries

• For GUI console support, highly recommended, at least one of the following:

  • Qt version 4.5 (?) or newer - best choice (don't use 4.6.2 on linux https://bugreports.qt-project.org/browse/QTBUG-8537)
  • FLTK 1.1.10 (deprecated, and probably will be removed)

LuaBind, osgLua, and Lua 5.1 are included in the source tree and integrated in to the build - you do not need to build these separately.

Just run CMake, being sure to set a build directory that is different from your source directory. Tell it where to find any dependencies it can't locate. You may wish to configure any of the build options, including but not limited to CMAKE_INSTALL_PREFIX (where you want an installed snapshot to be placed). Then, build the generated project/makefiles in the binary directory.

If you have any issues running, particularly on Windows, try building the "INSTALL" target and running it from the install location.

Visual Studio 2008 may produce a number of "Incremental Linker has stopped working" errors on clean builds. Usually, attempting the build again (without cleaning) will succeed, but this is a pain. A hotfix is available from Microsoft: http://archive.msdn.microsoft.com/KB948127 After installing the hotfix, do a clean re-build.

If you find this useful, we would appreciate hearing from you. If you use this for academic work, we would also appreciate a copy of the publication and a citation: this helps make a case for our work. You may contact the main developer, Ryan Pavlik (Iowa State University), by email at rpavlik@iastate.edu or abiryan@ryand.net.

The relevant citation is:

Pavlik, Ryan A., & Vance, Judy M. (2011). VR JuggLua: A Framework for VR Applications Combining Lua, OpenSceneGraph, and VR Juggler. Workshop on Software Engineering and Architectures for Realtime Interactive Systems (SEARIS) in IEEE Virtual Reality. Singapore.

Paper materials and copies of publications may be mailed to:

Ryan Pavlik
Virtual Reality Applications Center
1620 Howe Hall
Ames, Iowa 50011-2274
USA

The full package is free and open-source software, under a variety of licenses. The following list of licenses is not a complete list at this time. All file location references are in the source tree.

The VR JuggLua code itself (the files in vrjugglua/ and most in src/) are subject to the following license:

Copyright Iowa State University 2010-2013.

Distributed under the Boost Software License, Version 1.0.

(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Luabind is bundled in third-party/luabind/, and is subject to the following license:

Copyright © 2003-2011 Daniel Wallin and Arvid Norberg

Copyright © 2008-2013 Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

osgLua has been highly modified/improved and is bundled in third-party/osgLua, and is subject to the following license:

Copyright(C) 2006 Jose L. Hidalgo Valiño (PpluX) (pplux at pplux.com) Copyright(C) 2010-2013 Iowa State University (Author: Ryan Pavlik rpavlik@acm.org )

This library is open source and may be redistributed and/or modified under the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or (at your option) any later version. The full license is in LICENSE file included with this distribution, and on the openscenegraph.org website.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the OpenSceneGraph Public License for more details.

Lua 5.1 is bundled in third-party/lua-5.1.x, and is subject to the following license:

Copyright © 1994-2011 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction,including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Ryan Pavlik rpavlik@iastate.edu abiryan@ryand.net http://academic.cleardefinition.com/ 2009-2013 Iowa State University Virtual Reality Applications Center/Human-Computer Interaction Graduate Program