@c -*-texinfo-*-
@node io_scene_cs Portals, io_scene_cs ToDo, io_scene_cs Export Animesh, Blender
@subsection Exporting Portals

This section presents how portals can be created in order to link the different sectors of
a virtual environment. Each @url{http://wiki.blender.org/index.php/Doc:2.6/Manual/Interface/Scenes, Blender scene}
in the file is exported as a Crystal Space sector, and the use of specific meshes allows to
define portals between them.

This is made using the @samp{Crystal Space Portal} panel that is found in the
@samp{Object Data} context of the @samp{Properties} window:

@picturess{content,blender,io_scene_cs_portal}

@subsubheading Creating portals

In order to define a portal, you must create two meshes that will be the source and the
destination of the portal. Each mesh will be in a separate
@url{http://wiki.blender.org/index.php/Doc:2.6/Manual/Interface/Scenes, Blender scene}
so that the portal will lead from the first scene to the second one (this is not a
limitation and a portal is allowed to lead to the same sector than the starting one).

You must pay attention to the shape of your source mesh as well as to the order of its
vertices. The shape of the mesh will be used as the one of the Crystal Space portal, but
one tricky problem is that the order of creation of the vertices will also define its
orientation. For a correct behavior, be sure to create the vertices of your source mesh
in clockwise order when you look at the portal.

Unless you plan to create another portal to go back in the other direction, the actual
shape of the destination mesh has no importance at all, only its position will be important.

Once the two portal meshes are created, select the source mesh, go to the
@samp{Crystal Space Portal} panel, and activate the @samp{Portal} checkbox. A text entry
@samp{Destination mesh} appears, you must now type into it the name of the destination mesh
of the portal. Once done, the object will be exported as a portal instead of a mesh.

You must also pay attention to the relative transform of the source and destination meshes
since it will define the warping transform that is applied when crossing the portal. If the
source and the destination of the portal are the same (i.e. there is no warping transform),
then the two meshes should be at the same position.

@subsubheading The @samp{portaltut} example file

As an example we will follow the making of the file @file{portaltut.blend} that can be
found in the @url{http://trac.crystalspace3d.org/trac/CS/browser/CSAssets/trunk/blender/,
CS/browser/CSAssets/trunk/blender/} @sc{svn} repository.

The example is split in three different scenes that will correspond to three different
sectors in Crystal Space: two rooms @samp{roomA} and @samp{roomB}, to be linked by a
transitional sector @samp{Corridor}. The goal of this example will be to create the portals
in order to travel from one room to the other.

The walls of the rooms have already been created, and some holes have been dug that have to
be replaced by the portals:

@picturess{content,blender,portals_01}

Let's do the following steps:

@itemize @bullet
@item
Position the cursor where the portal will be defined: in @samp{Edit} mode, select the vertices
at the boundary of the portal, the press @samp{Shift-S} then @samp{Cursor to selected}.

@picturess{content,blender,portals_02}

@item
Create the source mesh of the portal: add a new dummy mesh, e.g. a cube, then go to
@samp{Edit} mode and remove all the vertices of the mesh.

@picturess{content,blender,portals_03}

@item
Create the vertices of the source mesh: use @samp{Ctrl-LMB} for all vertices, being sure to
turn in clockwise order. You can create a face after that.

@picturess{content,blender,portals_04}

@item
After a set of @samp{Shift-S} operations, the vertices have been aligned to the walls, and
the mesh has been renamed purposely @samp{PortalA2C}.

@picturess{content,blender,portals_05}

@item
Now we will create the destination mesh: in object mode, select your source mesh and duplicate it with
@samp{Shift-D + LMB}, create a link to it in the scene @samp{Corridor} with @samp{Ctrl-L}
then @samp{Objects to scene}, delete the copy in the first scene, then finally rename your
destination mesh into @samp{PortalC2A}.

@item
Re-orient the vertices of the destination mesh: since the mesh is a copy of the original
one, the vertices will be in counter-clockwise order when facing the portal. In order to fix
this, go to @samp{Edit} mode, select all the vertices and rotate them with @samp{R-X-180}
(or whatever rotation axis).

@picturess{content,blender,portals_06}

@item
Now that both meshes have been created, we can define them as portals. Select the source mesh,
go to the @samp{Crystal Space Portal} panel (in the @samp{Object Data} context of the
@samp{Properties} window), select the checkbox @samp{Portal}, and enter the name of the
destination mesh, i.e. @samp{PortalC2A}. Repeat the same process for the destination mesh in
order to define a portal back to the first room.

@picturess{content,blender,portals_07}

@item
Repeat the process for the other portals leading to the second room. Here is the result once
you press the @samp{Export and Run} button:

@picturess{content,blender,portaltut_run}

@end itemize

@subsubheading Troubleshooting

If some of the portals don't look ok while exporting Blender worlds, check that:

@itemize @bullet
@item
the name of the destination mesh has been accepted, i.e. the error message
@samp{ERROR: unknown mesh name} does not appear in the portal tool panel.
@item
there is no error message on the console.
@item
you have defined the vertices of the portal in clockwise order (if done wrong, you
may typically see some problems with the triangles of the portal).
@item
the destination mesh is not linked at several places in the scenes (in this case, the
script will randomly pick one of those linked meshes).
@item
the relative position of the source and the destination mesh corresponds correctly
to the warping transform of the portal (i.e. they are at the same position if the
warping is an identity transform).
@end itemize

If you still have a defective portal after you have checked those points, it is highly
probable that the relative transform of the source and destination mesh is causing
the problem. A good hint in this case is to move the destination mesh at the same position
and orientation than the source mesh in order to get a valid portal with an identity warping
transform, then, starting from this configuration, move the destination mesh by small steps
in order to visualize the changes.


@node io_scene_cs ToDo, , io_scene_cs Portals, Blender
@subsection ToDo

This section lists the main features of the exporter that are still lacking. Please
contact the Crystal Space mailing list if you wish to help and add support for them.

@itemize @bullet
@item
All lamps are exported as simple point light sources
@item
Limited support of the camera properties
@item
Limited support of the material properties
@item
No support for terrains
@item
No support for particles
@item
No support for colliders, physical properties, and iBodySkeleton
@item
No support for trees of armatures: only the root armature is exported, not the children
ones
@end itemize
