S3D exporter for Blender

From VRwiki
Jump to: navigation, search
S3d exporter.png

This page describes a Blender script that allows Blender to be used to preview XVR Procedural Objects. This is useful when you have to deal with complex objects and you want to have a visual cue of the final appearance, without losing the advantages of procedural objects. The exported file is a S3D script file, containing actual XVR code, that must be included and called from your project.

Installation

Prerequisites

The Blender Python API is constantly evolving, so it is advisable to version-match the script in order to avoid unexpected failures. The current version of the script has been written and tested against Blender version 2.43.

The availability of a full Python install is not required.

Getting the exporter

The exporter is a Python script. You can download it from here.

Installing the exporter

To install the exporter, just drop it in the scripts directory, which is usually placed in C:\Program Files\Blender Foundation\Blender\.blender\scripts unless you decided to install it in your home, in which case you should find the .blender directory among your documents.

Alternatively, in Blender, go to the File Paths tab, in the User Preferences window, and select a custom additional script directory in the Python text field. After saving your User Preferences (from the File menu or pressing CTRL+U), it is advisable to reload the program.

Afterwards, the S3D exporter should be available in the File > Export menu.

Running the exporter

If correctly installed, you can find the script in the usual File > Export menu.

The operation is pretty straightforward. The exporter operates only on selected meshes and does not require any options.

Please note that the exporter won't allow any file overwrite. This is a deliberate design choice: overwriting code files is just too risky, even though a safe programmer should protect his efforts with backups and code versioning.

Using the exported code

In the main script, add:

#include "<name>.s3d"

where <name> of course represents the name of the exported file. In OnInit call:

init_proc_<name>();

In OnFrame call:

proc_<name>.Draw();

(of course inside a SceneBegin()/SceneEnd() block). In general proc_<name> is the name of the root object of the procedural hierarchy. You can call all the usual CVmObj methods on it. Remember to download any additional file that you need - that is, textures needed by the exported objects.

Supported Objects

Of course not every object can be accurately described as an XVR procedural object. Procedural objects are usually simple primitives combined in possibly complex ways.

To recognize which shape to use in XVR, we followed a pretty simple approach: we look at names and only at names. If an object's name starts with a particular string, than it is a particular type of object. Other object properties are looked up as well, in particular position, rotation, scale; also materials and modifiers may be looked up if available.

Please note that the actual geometry of the object is ignored; only the number of vertex is sometimes looked up to infer how many segments to employ.

Currently supported objects are:

  • Plane*
  • Cube*
  • Sphere*
  • Cylinder
    • please note that the default Blender cylinder has its pivot in the middle, why XVR places it at the bottom; take care of this
  • Arch
    • there is no Blender Arch primitive, but a renamed cube can be used instead as its bounding box; please note, though, that XVR's Arch has its pivot in the front

More objects will be added in the future. In particular, with Blender 2.44, we will take advantage of the new Python slot in the "Add Mesh" menu, so that we can create all XVR primitives matching XVR pivots and parameters directly into Blender.

An object with a fancy array modifier exported in XVR.

Supported Features

Array Modifier

The recently added Array modifier comes in handy when dealing with procedural objects. With it, a base mesh can get replicated a number of time in a regular fashion. This exporter supports all three types of displacements, including the incredibly useful "Object" displacement type, that allows not only to translate but also to rotate and scale. Interestingly enough, an Array Modifier becomes a loop in S3D code.

Limitations

Unfortunately, due to limitations in the Python API, it's not possible to read the current states of the toggle, so take care of zeroing out all of the fields that you don't need. Length limit, curve follow, and vertex merge are not supported. Bear in mind that this modifier acts on a mesh in Blender, while it acts on objects in XVR.

Materials

There's basic support for materials too.

Face textures

If an object has a materials and has an image assigned to its faces, that's the texture that gets exported and forced onto the XVR object. No other parameter is taken into account.

Objects with different U_TILING settings.

Textures with UV tiling parameters

If an object has a material with a texture in the first slot, the image name is read from there, and the SizeX/SizeY parameters are exported as U_TILING, V_TILING parameters in XVR. No other parameter is taken into account.

Future Work

As stated in section Supported Objects, we plan to take advantage of the new Python slot in the "Add Mesh" menu that will be available in Blender 2.44, in order to create all XVR primitives matching XVR pivots and parameters directly into Blender.

Bug reports

Please post bug reports in the XVR user forums.

Changelog

Ver. 0.01.200700509

  • support for cube, plane, sphere, cylinder and arch
  • support for array modifier
  • basic materials support

See also