Difference between revisions of "Horde3D Scene Editor"

Editor Features

The Horde3D Scene Editor offers an easy to use interface for the Horde3D graphics engine

Some of the key features are:

• Interface for creating and modifying Horde3D scene graph files
• Instant resource reloading for files modified outside the editor making it possible to use the editor for shader development
• LUA scripting support for rapid prototyping of small applications directly in the editor
• Powerful plugin architecture for integration of game engine functionality and executing game code, physics, etc. directly in the editor
• Cross-platform compatibility
• Open-source code released under the GPL

The current official version is version 0.8.0 compatible with Horde3D v.1.0.0 Beta2.

A more recent version can be found in the Community Branch that is compatible with Horde3D v.1.0.0 Beta5. In the repository there are also CMake configuration files to build the entire editor with all editor plugins and the Horde3D engine itself. Note that at least CMake 2.8.3 is required.

Thanks to our forum member Irdis, a windows binary release of the editor compatible with Horde3D Beta5 can be found here. Note that you must have OpenAL installed on your system to use it.

Preliminary Documentation

A preliminary PDF documentation can be found on the project website. In the future it will be transferred to the wiki to allow the community to improve the documentation as well.

Tutorial Video

<VideoFlv width="1024" height="768">http://hcm-lab.de/files/project_content/45/Horde3D_Editor.flv</VideoFlv> You can also download this video in an Xvid coded version!

Overview of the Horde3D Scene Editor

The Horde3D graphics engine is a SDK for rendering three dimensional data. The interface to the graphics data is defined by a Horde3D specific file format. Normally you will create a 3D model in your favourite modelling tool like 3Ds Max or Blender and export the data to a Collada file. This file can then be converted by the Horde3D Collada converter to the internal Horde3D format.

But what if you want to compose a scene where several single models should be integrated. The first possibility is to use your modelling tool, compose everything in it and export the whole scenery to create one big Horde3D file. But doing it this way suffers still from the lack of possibility to illuminate your scene with Horde3D lights and visualize it with your custom shaders. That’s why the second possibility was created: the Horde3D Scene Editor! It will create scene graph files readable by Horde3D, let you integrate your custom attachment nodes by using plugins, offers fast prototyping by pro- viding a Lua interface to all Horde3D functions and also let you instantly preview changes to shader code, materials, effects, textures and pipelines by reloading the changed files immediately and automatically after saving them.

Installation

For the Horde3D Scene Editor a graphical installer is provided for the Microsoft Windows platform. You can download the latest release from the project website. Release candidates for upcoming versions might be released in the Tools section of the forums. Currently the Editor supports two different platforms: Windows and Linux! It may be used on the Macintosh platform as well, but since I (volker) don’t have access to a Mac I haven’t tested this yet.

Windows

After downloading and extracting the compressed archive you simply have to run the Setup.exe. It will guide you through the rest of the installation procedure. After installation has been done, a Horde3D Scene Editor link has been created in your start menu and the file extension .scn has been associated with the editor. The installation directory will contain an executable as well as the source code and a Visual Studio 2005 solution.

Compiling the Editor

Visual Studio

To compile the Editor yourself with Visual Studio 2008 or 2010:

1. Download the Qt libraries for Windows. Make sure to choose the correct file (VS 2008 or VS 2010)!
2. Install the libraries and remember the path (e.g. C:\Qt )
3. Set your environment variables (Control Panel\System\Environment Variables):
   1. Add a new user-variable "QTDIR" and set it to the Qt folder (e.g. c:\Qt\4.8.2 ).
   2. Add the directory of Qt's bin-folder to the system "Path"-variable (e.g. C:\Qt\4.8.2\bin;).
4. Restart your pc.
5. Open the solution Horde3DEditor_XXXX_with_GameEngine.sln (2008/2010 depending on your VS version) and build it.

Visual Studio 2005

If you want to compile the Editor yourself with Visual Studio 2005, open the solution Horde3DEditor_2005.sln in trunk/Tools/Horde3DEditor. To build the solution you need to have Qt installed. Since installing the open source version of Qt is not entirely straightforward, here is a quick installation guide for Visual Studio 2005:

1. Download the Qt source archive from ftp://ftp.qt.nokia.com/qt/source/qt-all-opensource-src-4.5.2.zip
2. Extract it to a directory without any spaces (not something like C:\Program Files\Qt4 but rather C:\Qt4)
3. Configure Qt to use wchar_t as built-in type
   1. Open mkspecs/win32-msvc2005/qmake.conf in the Qt directory
   2. Find the line QMAKE_CFLAGS = -nologo -Zm200 -Zc:wchar_t- (around line 19) and remove the last character (the minus)
4. Launch the Visual Studio Command Prompt (can be found in the VS start menu entry under Tools)
5. Change to the Qt source directory
6. Enter configure -platform win32-msvc2005 -no-qt3support
   1. -no-qt3support is not required and is just used to speed up the build process
   2. Follow the instructions on the screen and wait until the configuration process is finished
7. Enter nmake and wait until the build process has finished (can take several hours)
8. Configure environment variables in the Windows Control Panel
   1. Add QTDIR which points to your Qt path
   2. Add the bin directory of the Qt path to the PATH variable

If you need more detailed instructions on how to install Qt, please find one of the many tutorials that are available on the net.

Linux & Mac

Requirements

For the installation under a Linux or MacOS environment you have to install at least the Qt development libraries version 4.3.3 or above and CMake 2.8.3 to be able to compile the editor. You will also need OpenAL (with development files) and ogg (also with developement files).

After checking out the whole community svn trunk (svn co http://hcm-lab.de/public/Horde3D/trunk/), you have to create some temporary build directory and call cmake from within that directory with the Tools/Horde3DEditor directory of the community branch checkout as argument.

The first start

After you called the executable, the application starts and will present you the Horde3D Scene Editor with an empty window. During the installation two test scenes have been installed to the bin\TestScene and bin\Particle folder of the Horde3D Scene Editor installation directory. They contain a small scenery to provide you with out-of-the-box examples.

Open a scene

To open it click the file menu and select Open Scene or press CTRL + O as a shortcut. For the first test, browse to the TestScene folder and choose the TestScene.scn file. After you confirmed your selection with the open button the editor will load the scene and present it to you.

Navigation

There are two possibilities to navigate through the scene. The first one is similar to most of the today’s first person shooters. With the key combination W, A, S, D and by clicking with the left mouse button in the viewport widget you can move the camera through the scene (note that you have to hold the mouse button pressed to rotate the camera). If you would like to use another mouse button you can reconfigure this in the Settings dialog accessible via the File menu.

The second possibility is to use the mouse wheel to navigate forward and backward and strafing left, right, up, down by holding the CTRL key and left mouse button pressed and moving the mouse in the direction to strafe. You can change the amount of movement between two frames by changing the Navigation Speed entry within the tool bar. Additionally if you keep the Shift button pressed the navigation speed will be increased as long as you hold it.

A third possibility was introduced with version 0.7.0 if you hold both the mouse navigation button (normally the left one) and the select button (by default the right one) pressed, you can also strafe along the X- and Y-axis of the camera.

The transformation changes to the camera are done only within Horde3D and not saved to the XML file. To change the transformation of a camera permanently you have to select it first in the scene tree and after you moved to the place you want, you have to press the Move Node To Camera Position button or activate the corresponding menu entry in the Edit menu (Shortcut: CTRL+ALT+C). Now if you press the save button, the transformation of the camera will be stored in your scene graph file.

To get a better impression of the scene you can switch the view to fullscreen mode by clicking on the fullscreen button in the toolbar or activate the corresponding entry in the View menu. To leave the fullscreen mode you have to press the Escape key on your keyboard.

Finally the Wireframe (Debug) Mode button toggles between a debug rendering mode and the normal rendering. It is especially useful if you have problems with the light and are not sure if a geometry was inserted correctly or not.

For the alignment of objects a parallel projection mode for the cameras has been integrated. You can access it using the tool buttons in the camera navigation bar. But be aware that the parallel projection might cause confusion since the distance of the camera to the objects is only observable via the near clipping plane. So if you move the camera position using the W or S key, you might get rid of you models because they are clipped by the viewing frustum. To zoom when using the parallel projection use the mouse wheel.

Customizing the editor

For a better workflow you can adjust the dock widgets of the editor to your personal preferences. To do this just click and drag the titlebar of the dock widgets and place them where you want them to be. By default the most important dock widgets are visible to you. If you want reduce the required screen space there is an option in the Windows menu to toggle the dock widget visibility depending on the selected scene graph node. By doing this the attachment widget or material widget are hidden if no editor plugin is loaded or no node with a material attribute has been selected. You can also alter the way mouse buttons are used for camera navigation and object selection in the settings dialogue you can access via the Settings entry in the file menu.

Manipulating objects

After loading the scene file, the elements of the scene are listed in the Scene Tree. By selecting one of them, the corresponding transformation - stored within the XML file - is shown in the Basic section of the Node Properties widget. If you change it, an entry in the Undo section of the Edit menu is created, allowing you to undo the change. Depending on the type of node you selected, the Node Properties widget shows you additional configuration settings. For example if you select a light node you can change the light’s color, field of view or many other settings. Nodes referencing a material file cause the Material Settings widget to display the content. But take node, that the changes you made to the materials can not be undone by using the undo/redo commands. Since the materials are separated files and not direct part of the scene graph, you have to save them manually (click on the save button) to apply the changes to the scene.

Reference Node

A Reference node represents a separate scene graph file not directly inte- grated in the currently shown scene graph tree. To view the content of this file you can double click on the reference element. The scene tree now con- tains the contents of this file and all changes made on the objects are handled within the scene graph file of this element. If you want to switch back to the parent scene graph file you can click on the Arrow at the top of the scene tree or press the backspace key. Take note, that all manipulations are done in the scene graph currently displayed in the tree view. That’s why you can only undo actions done within the currently opened scene graph. If you hold the CTRL key pressed, while double clicking on a reference node, the camera will be moved to the selected node.

Camera Nodes

n a scene you can define multiple cameras. To activate one of them you have to double click on the scene tree item in the tree view or select it in the Active Camera combobox of the navigation bar. The active camera can also be used to set transformations of other nodes. If you navigate the camera to a special point you can adjust the transformation of the currently selected node by using the Move Node To Camera Position button or by pressing the shortcut: CTRL+ALT+C Orthogonal to this you can set the camera transformation to the transformation of the currently selected node by using the Move Camera To Node button.

A new scene

Before you create a new scene you may want to configure an editor repository.

Before you start

This will be done in the Settings Dialogue you can find under the Settings menu entry in the File menu. There are six different repository paths to configure. The first is the path to Horde3D pipelines. These files configures the way Horde3D renders the scene. The next path handles the scene-graph- (Extension .scene.xml) and Horde3D geometry files (Extension .geo). The third is the path to the materials directory that contains the subfolders and material files (Extension .material.xml) for the materials of a converted 3d model. The texture directory defines the path where the textures are stored while the shaders directory points to the shader (Extension .shader.xml) and code files (Extension .glsl) used by the models stored in the repository. Last but not least for effect files (.effect.xml) a separate effect directory can be configured. By default the repository is located in the bin\Repository folder of the Horde3D scene editor and contains the Horde3D samples’ models. Next to the repository configuration you can also define a shader editor in the general tab of the settings dialogue. This editor is used when clicking on an edit button in the material editor. Other settings are the path to the plugin directory used to search for attachment plugins and the number of undo steps that will be available. Note that if you choose a great number of undo steps or even the Unlimited setting, the Horde3D Scene Editor could consume a lot of memory if you make many changes to one scene. To prevent this you can manually clean the undo stack just by reopen the current scene (every time a scene is closed the undo stack will be cleared).

Creating a scene

To create a new scene select the New Scene entry in the file menu or press the CTRL + N shortcut. A wizard will appear letting you choose a scene file name and a directory where the newly created scene will be stored. If the directory does not exist you will be prompted if you want to create it.

Depending on the editor version you're using there may be an additional wizzard page comming next, that allows you to define Horde3D's resource directories.
Since the usage of those directories is deprecated the current community branch version of the editor does not offer this page anymore (so skip this step in the video tutorial).

Otherwise after choosing the scene directory additional directories for the different scene resources have to be selected on the next page. As before directories not already existing can be created by the editor automatically. Take care that the resource directories should be placed below the parent scene directory and such should be declared relative to this folder

On the next page you have to configure a default camera used for rendering. While you can keep the default frustum settings, you have to import a ren- der pipeline from the repository configured before. By default some of the Horde3D example pipelines are listed when you select Import from repository in the combo box. You can then just press the OK Button or adjust the code in the edit window. Only the content of this window will be used for the new camera. The original file in the repository remains unchanged.

To allow you viewing the geometry placed in your scene and to configure a light source for the preview of models, you will be asked to define a default light on the next page. The settings you have to make here are depending on the pipeline configuration you made on the previous page (see the Horde3D documentation for more details). It is important that you configure this light properly since the Material, Lighting Context and Shader Context parameters are used for the standard light source in the preview window when adding new models to your scene. If your pipeline settings requires the light to have a material (e.g. when using deferred rendering), you can import one from the repository (see Before you start ). The yellow lock next to the filename indicates that the material will be imported from the model data repository you specified before. If you have not specified it properly, or do not have a light material, you have to manually copy an appropriate light material and shader file to the specific directories of your scene. Finally on the last page you can select a plugin for handling Horde3D attachments. If there have been plugins found by the editor, the selection box let you choose one of them to be the attachment controller for this scene. At the moment no public plugin is part of the editor yet.