|
MinVR
0.9.0
A multi-platform virtual reality library
|
|
MinVR
0.9.0
A multi-platform virtual reality library
|
The MinVR core library is designed for interfacing with multiple VR input devices and display configurations. To use additional graphics toolkits, the library includes specific AppKits. For example, to use the G3D Graphics library (http://g3d.sourceforge.net/) with MinVR, you would use the AppKit_G3D9. Although, we have written AppKits for several common graphics libraries, this document specifies how to create a new one.
AppKits are stored in the AppKits directory at the root of the source tree. Start by creating new directories that look like this:
There are two MinVR classes that every AppKit must subclass: AbstractMVREngine and AbstractWindow.
Because most graphics toolkits have the functionality to create their own window, AbstractWindow has been designed to be as flexible as possible. Each AppKit should subclass AbstractWindow and fill in the following methods:
virtual int getWidth() = 0;
virtual int getHeight() = 0;
virtual int getXPos() = 0;
virtual int getYPos() = 0;
virtual void swapBuffers() = 0;
virtual void pollForInput(std::vector<EventRef> &events) = 0;
virtual void makeContextCurrent() = 0;
virtual void releaseContext() = 0;
Ideally, the constructor will take the WindowSettings object and create a graphic toolkit specific window object accordingly. Most of the other methods that must be overridden are self explanatory.
The pollForInput method should handle window-system keyboard, mouse, and joystick events. For a list of specific event names, see Handling MinVR Events.
The AppKit specific MVREngine must at a minimum override virtual WindowRef createWindow(WindowSettingsRef settings, std::vector<AbstractCameraRef> cameras) in order to create an AppKit specific window object.
Depending on the graphics toolkit, other objects may need be be initialized in the virtual void initializeContextSpecificVars(int threadId, WindowRef window) method. This is called by each renderthread to initialize thread specific variable that depend on the OpenGL context being current.
To build your AppKit with the default cmake build system, you need to include a CMakeLists.txt file in your AppKit directory. In the following code, we will take you through the process of creating the GLFW AppKit's CMakeLists.txt. The full source can be found in MinVR/AppKits/AppKit_GLFW/CMakeLists.txt
First, define the project name and any cmake specific variables
Then, define the source and header files:
Most AppKits will have a library dependency for the specific graphics toolkit. Although you can include the library in your code directories, if the library is publicly available, it is better to just link to it. This can be accomplished using CMake's externalproject_add module. Here, we are downloading a slightly modified version of the glfw library. If you don't need a modified version, a better practice would be first to find whether the dependency library already exists on the system using a cmake find module.
Include the dependency directories and preprocesser defines
Set the output of the build to the correct directories and handle library naming schemes for debug, etc.
To make your AppKit build with the rest of the library, you need to modify the CMakeLists.txt at the root level of the MinVR repository.
Open MinVR/CMakeLists.txt. At the top of the file define a new option to specify whether your AppKit should be built:
option(USE_APPKIT_<appkit name> "Enable to use the <appkit name> app kit" OFF)
At the bottom of the file, specify your new AppKit directory:
if (USE_APPKIT_<appkit name>)
add_subdirectory (AppKits/AppKit_<appkit name>)
endif()
Finally, add your example to the build examples if statement:
if (BUILD_EXAMPLES) add_subdirectory(AppKits/AppKit_GLFW/example) add_subdirectory(AppKits/AppKit_G3D9/example) add_subdirectory(AppKits/AppKit_<appkit name>="">/example) endif()
The cmake build system will automatically generate MinVR cmake find modules that make it easier for external projects to find and link against the library. In order for people to use your new AppKit, it should be added to these files.
Open MinVR/cmake/minvr_minvrconfig.cmake. In the section titled "Handle AppKit components and dependencies", add the following lines:
Then, open MinVR/cmake/MinVRConfig.cmake.in. Find the 3rdparty libraries macro section. Add a new macro for each library dependency your appkit has. For example, the GLFW appkit depends on the glfw library, so the added macro looks like this:
Finally, add a new else statement to the find_external_library macro to reference the dependency macro. For example, the glfw one listed above looks like this:
If your AppKit requires special build instructions, make sure to update or add to the documentation in MinVR/doc.
Once your AppKit is finished, make sure to test that it works and your example builds correctly. When you are happy with it, please contribute it back to the MinVR repository so that others may use it as well. This is accomplished by creating a Git pull request. For information on how to do this, see How to Contribute.
1.8.4