OGRE Meshes Exporter

Blender is an open source 3D content creation suite for modeling, animation, rendering and video post production. The OGRE Meshes Exporter is a set of python scripts to run directly within Blender. Currently it supports the export of

Table of Contents

Installation

The script needs access to standard Python modules not shipped with Blender. Consult the Blender documentation at www.blender.org how to incorporate Python with Blender.

Basic Usage

There is a one-to-one correspondence:

Blender Object (OB) ↔ Ogre::SceneNode
Blender Mesh (ME) ↔ Ogre::Entity

The OGRE Meshes Exporter maps Blender Meshes (ME) to Ogre Entities. Please refer to the OGRE Scene Exporter for the mapping of Blender Objects (OB) to Ogre SceneNodes.

To export Blender Meshes (ME) do:

You will get a detailed log of the export process. All files are exported in the OGRE XML format. Use the OgreXMLConverter of your OGRE installation to convert the generated XML files to binary .mesh and .skeleton files.

exporter screenshot

Screenshot of the exporter interface.

Options

Selected:
The pop-up menu has an entry for every object that is selected for download. Select a mesh object in order to display its animation settings in the box below.
Update
Updates the list of all objects selected for export from the currently selected objects in the "3D View". Also updates the list of possible actions, deletes animations for removed actions and sets default animations for new actions.
Animation Settings of
Shows the animations that will be exported for the given mesh. You can switch between Skeleton, Pose and Morph animations, if available.
Skeleton
Show the skeleton animations, that will be exported. Only available if the mesh is modified via an armature either as parent or as modifier.
Pose
Show the pose animations, that will be exported. Only available if the mesh has shape keys.
Morph
Show the morph animations, that will be exported. Only available if the mesh has shape keys.
Each line in the area with the scrollbar corresponds to an animation, that will be exported.
Action name
The name of the Blender action. Only available for skeleton animations.
Start:
Start frame of the animation.
End:
End frame of the animation.
Animation export name
The animation name in the exported OGRE file.
Delete
Removes the animation from export.
Add
Add another animation to be exported.
Material Settings
Material File
The name of the material script file that will be generated.
Coloured Ambient
Use scaled diffuse colour as ambient colour instead of scaled white. This does only work for materials for which TexFace is not set.
Copy Textures
Copy textures to the export path, if possible
Rendering Materials
Export materials following the rendered result. (default)
Game Engine Materials
Export materials as displayed in the game engine.
Custom Materials
Export materials using specialised material templates.
Fix Up Axis to Y
Blender uses Z as up axis. This toggle switch allows changing the mesh to use Y as up axis.
Require Materials
Generate Error message when part of a mesh is not assigned with a material.
Skeleton name follow mesh
Force skeleton name to follow mesh name. Uncheck to make it use armature name instead.
Apply Modifiers
Apply mesh modifiers before export. This option is slow and may break vert order for morph targets. Not recommended for animated meshes.
OgreXMLConverter
Convert the XML files to binary files via the OgreXMLConverter. The exporter must be able to find the converter executable. You can specify its location in the preferences.
Path
All files of the exporter are written into this directory. Mesh files are named after the mesh name in Blender with suffix ".mesh.xml". Skeleton files are named after the mesh object name and the armature name in Blender with suffix ".skeleton.xml".
Export
Export all objects in the list of objects selected for export.
Preferences
OgreXMLConverter
Auto
OgreXMLConverter is called without specifying its location. Only works if the executable is in the PATH.
Manual
Calls the executable specified in Converter.
Export Options
Please read XMLConverter documentation for more info.
Additional arguments
Additional arguments added to the converter call.
Ok
Apply changes.
Cancel
Discard changes.
Help
Display the manual in the default browser.
Quit
Exit from the export script.

The script loads and saves its options to a text buffer "OgrePackage.cfg" inside the current .blend file. You can save the current settings, if you save the .blend file after quitting the exporter.

Meshes

The script supports sticky and per face vertex uv coordinates, smoothed and non-smoothed normals, vertex colours. Each rectangle face is automatically converted into two triangle faces in the exported mesh. The exporter defaults to using 16 bit indices but if the submesh vertex count exceeds the 16 bit limit then 32 bit indices are used.

The script does not support subdivision surface (SubSurf) options. To export a SubSurf object, you have to convert it into a Mesh object, "Object → Convert Object Type... → Mesh (keep original)".

The script does not support the "Double Sided" mesh option, use the "Two Sided" face option instead.

To force the export of vertex colours, select "VCol Light" in the meshes' materials and export with "Game Engine Materials" disabled.

Materials

In contrast to OGRE, Blender treats material, uv texture and blend mode separately. Also Blender distinguishes between material appearance in the game engine and material appearance in the rendered results.

Rendering Materials

The name of the exported material is the same as in Blender. If the "Two Sided" face option is set, the suffix "/TWOSIDE" is appended. If the "TexFace" material option is set, the suffix "/TEXFACE" and the name of the texture image that is assigned with the UV/Image Editor is appended. The "Two Sided" face option has no effect in Blender's rendering results and is evaluated on export for convenience only.

material panel shaders panel links and pipeline panel

Blender's material settings that affect the exported OGRE material are marked green.

image panel

The script exports image textures with "Map Input" set to "UV" and "Map To" set to "Col" and optional "Alpha". The supported image options are marked green.

InterPol MipMap resulting filtering
yes yes trilinear
yes no linear linear none
no yes bilinear
no no none

Game Engine Materials

The material name has to be unique. Therefore, the name of the exported material consists of Blender's material name (if any), the face blend mode and texture file name (if any). If vertex colours are defined, a postfix "/VertCol" is appended. Also, if the two-sided face option is set, "/TWOSIDE" is appended.

If a material is assigned to face, only the properties that affect the appearance in the game engine are exported. These are the "Col" and "Spe" colours, the "Amb", "Spec" and "Hard" factors and the "VCol Paint" and "TexFace" options.

Textures assigned with the UV/Image Editor are exported. Note that material image textures, which can be exported as rendering engine materials, give you more control over filtering and texture address modes.

face options

Blender's face settings affect the mesh appearance only in the game engine. The properties exported by the script are marked green.

Custom Materials

The default material export works very well for simple basic materials. However, due to it's limitation, it is not feasable for any real projects. Most of the time we develope specialized material with specialized shaders for a particular project. In these circumstances, we would want to export the material files to our specialized material and shader.

Hence, Custom Materials to the rescue. Custom Materials allows you to provide template files which it will base on to generate your ideal material script.

To use it, first point the Template Path to a directory that is keeping your list of material templates.

Each template file should be named with the .tpl extension

I.E. phong.tpl
 
#import phong from "phong.material"

material %_materialName : phong
{
	set $diffuse %diffuse_tex
	set $normal %normal_tex
	set $spec %spec_tex
}

The above example uses the latest Ogre script feature(Shoggoth).

The format for the template is pretty straight forward. The first line of the template is reserved for import scripts. This is done so that the import scripts will be placed at the begining of the generated material files. Duplicated import scripts will also be removed.

The template uses key replacement to replace particular keys. The keys are defined as %key or %{key}. The second version is for when you want to concatinate a template key with a fixed constant value; I.E. %{diffuse_tex}.png

In order to tell the exporter what template to use for each material, each material has to be assigned to a template. This is done through the ID Property of the material. To access the ID Property, run "Help → ID Property Browser". For more information about ID Property in blender, see: Blender's wiki on ID Property

ID Property panel

Above is an example of ID Property in use. The most important thing is to select the right context before we edit our ID Property. Make sure the "Materials" category is selected. Then select your material (blue). Click on the "New" button to create a new property.

To make material assigned to a template, create a String property named template. The value of the property will be the template file linking to this material. I.E. phong will point to phong.tpl

There are certain case where Blender's material does not support a particular custom property that is required of our custom material. This is where custom properties come into play. As seen from the screen shot, it is possible to add custom properties to a material. To do that, make sure you create a "properties" Subgroup.

What you do inside the "properties" Subgroup is up to you. The hirachy is maintained. To give an example:

 
properties : Subgroup
  - someNumber = 123 : Int
  - someFloat = 0.234 : Float
  - someString = "Hello world" : String
  - someGroup : Subgroup
    - someIntArray = {1 2 3 4} : Int
    - someFloatArray = {0.1 0.2 0.3} : Float

From the above, to access these custom properties:

 
%someNumber => 123
%someFloat => 0.234
%someString => Hello world
%someGroup.someIntArray => 1 2 3 4
%someGroup.someFloatArray => 0.1 0.2 0.3

Bellow are a list of default properties based on Blender's material.

An important note on the (textureName). The texture name is the name defined in the Texture panel in the Material Buttons tab. It follows the convension of how it is displayed in the Texture panel; I.E. tex.123 gives tex while tex.1a2 gives tex.1a2

On certain cases, one would prefer to use texture indexing instead of (textureName) access. That being the case, you can use the _tex[#] handle to access the texture by index. I.E. _tex[0]._filtering will access the first texture's filtering mode.

Obviously, as the default properties shares the same library as the custom properties, you can actually use the custom properties to override the default properties. If you need more default properties that are not provided but can be set from Blender material, please contact Lf3T-Hn4D through the forum.

Animations

The animation speed in the export in terms of frames per second is taken from the corresponding scene render button.

format panel

Blender's format setting that affect the exported OGRE animation is marked green.

Armature Animations

Armature animation export is available if the mesh has an armature as parent deform or an armature modifier and that armature has at least one action. Armature animations are exported based upon keyframe ranges and action names. You can choose any frame as start and end frame of an animation. In order to export armature animations of a mesh you don't have to select the armature separately. On export, the script will sample the bone poses of the selected action frame by frame.

modifiers panel modifiers panel

The script supports a parented armature as well as an armature modifier.

Shape Animations

Relative shape animations can be exported as pose or morph animations. On export, the script will sample the vertex positions frame by frame.

shape panel

The script exports relative shape keys.