Extensions for OpenEngine provide a way to add functionality to the framework. The extension system is supposed to provide a fairly easy and loose way to extend the system and encourage distribution of extensions without need to modify the core library.

Some of the properties we seek are:

• Extensions link into the existing build system.

• Extensions are not depended upon by the main framework. Meaning: the framework can exists without any extensions.

• Extensions may exist in their own versioning systems.

• Extensions can depend on other extensions.

• Extensions that are seen as stable and well structured can be moved to the core framework with as little work as possible.

An easy way to create an extension is to copy the ExampleExtension to a new directory in the [browser:extensions] folder, say MyExtension. After this you just edit the necessary files for your extension.

You can use dist.py to create a new extension with:

./dist.py mkext MyNewExtension

This will create a new extension called MyNewExtension with a clean darcs repository ready to use.

Key files

README.txt

Information about the extension. You should at least mention the extension authors, a link to the extension repository/home and document its basic usage and/or provide a link to more documentation.

Setup.cmake

Setup.cmake provides a hook to the root of the OpenEngine build system. Semantically it corresponds to calling it with an INCLUDE command in the root CMakeLists.txt.

You may use the Setup.cmake file to search for external libraries and prepare variables and include directories that are needed in order for your extension to function correctly.

All usage of INCLUDE_DIRECTORIES, INCLUDE, FIND_PACKAGE, OE_ADD_SCENE_NODES and so on will typically take place in the Setup.cmake file.

The "magic variable" OE_CURRENT_EXTENSION_DIR can be used inside Setup.cmake to refer to the directory of the extension.

CMakeLists.txt

The cmake file is your link to the build system. You may use any valid cmake stuff here in order to check for extension dependencies and build the extension.

You must at least define an extension library with the ADD_LIBRARY command. Our convention is to use the prefix Extensions_ on all extensions. Your variant of the command will look something like this:

ADD_LIBRARY(Extensions_MyExtension
  # extension files
  Scene/MyNode.cpp
  Section/SomeFile.cpp
)

The first argument is the extension name. The rest are all the implementation files that your extension contains. If your extension has no implementation files you do not need to define a library. A library consisting only of templates would therefor not have a call to ADD_LIBRARY.

If your extension depends on subsystems from OpenEngine or other extensions you must specify this with the TARGET_LINK_LIBRARIES command as so:

TARGET_LINK_LIBRARIES(Extensions_MyExtension
  # depending libraries
  OpenEngine_Scene
  Extensions_MyOtherExtension
)

Conventions

As stated above, please prefix your extensions with Extensions_.

When creating an extension we wish to hide the fact that it is an extension as much as possible. This is due to several things. It should be transparent to the user and integrate smoothly with the existing documentation and so on. At some point we might want to include an extension in the core library and when this only entails changes to the build system it will minimize the changes required in user code.

Namespaces and directories

Use the existing namespaces when possible. And always use a namespace.

If you create a new node type it must be in the OpenEngine::Scene namespace. Therefor the file must be in the Scene/ sub directory of your extension.

If you create a networking system create a new namespace for the system. In this case OpenEngine::Network. The code in this namespace must now be found in the Network/ sub directory of the extension.

The reason we require the code to be in proper sub directories is that user code can then include is as expected: #include <Network/Socket.h>

Public repositories

If you wish to make your extension public we recommend using darcs to publish your extension. An easy way to make your repository public is simply to place the darcs repository in your public_html folder at daimi or some other webserver.

After creating a public extension please update the extensions list with information about it.

Creating new scene nodes

The OE_ADD_SCENE_NODES macro provides a way to add scene nodes to the existing core scene graph. All uses of this macro must occur in your extensions Setup.cmake file''

If your library defines a new node type you simple specify the namespace path to the node in this macro. If you have MyNode1 and MyNode2 and your extension is called Extensions_MyExtension you would write the following in Setup.cmake.

OE_ADD_SCENE_NODES(Extensions_MyExtension
  Scene/MyNode1
  Scene/MyNode2
)

The build system will now generate stub code for various node operations, such as Clone, GetClassName and so on, along with stubs for the ISceneNodeVisitor, allowing sub classes to define traversal operations on the new node.

The generated files are src/Scene/SceneNodes.h and src/Scene/SceneNodes.def and they are generated by src/Scene/SceneNodes.h.tpl and src/Scene/SceneNodes.def.tpl respectively.