[Nel] Cluster Systems

[Cyril 'Hulud' Corvazier]

Let's talk about cluster systems.

NeL provides a complete solution for indoors clipping.

- Cluster System (CS)
----

A CS is a set of clusters and portals.

A CS is associed with one Instance Group (IG). All the CS description is
saved into the IG. The CS can clip the objects referenced in its IG or 
"manually" inserted in the CS.

CS can be placed in a hierarchy of CS, ie, a CS can have one or more
children CS. The landscape is the parent of all the CS in the NeL engine. 
Links must be done by the NeL user with the method 
UInstanceGroup::linkToParentCluster ().


The objects referenced into the IG you want to clip with the CS must be
flagged as "Clusterized" with NeLExport.

- Clusters
----

A clusters is a convex polytop. It can be done in 3dsmax using a mesh
flagged as cluster with NeLExport.
All the objects referenced in the IG associed with the CS that intersect
the cluster are associed with the cluster.

At least one vertex of the mesh must be in the cluster to
consider that this mesh is in the cluster. One mesh can be shared by
more than one cluster.

When the view frustrum (VF) enter into a cluster, the object associed to
this cluster are clipped against it, ie, they are visible if they intersect the 
VF. If an object associed to a CS is never intersected by the VF,
it won't be rendered.

A cluster can be flagged as "Parent Visible" with NeLExport, it means 
that if the VF enter into this cluster, the parent CS will be visited too 
by the VF.

A cluster can be flagged as "Visible From Parent" with NeLExport, 
it means that if the VF enter into the parent CS, the cluster will be 
visited too by the VF.

Two clusters in the same CS can be linked together using a portal.

- Portal
----

A portal is a convex polygon. It can be done in 3dsmax using a mesh
flagged as portal with NeLExport.

A portal MUST be placed between two clusters, ie: all the vertices 
of the portal must be in the 2 clusters. If a VF visits a cluster, for 
each portal in this cluster, the VF will be clipped against the portal, 
and if the VF is not empty, it will visit the second cluster linked
to the portal.

A portal must be always in 2 clusters exactly.
To link up in the hierarchy, you need a cluster with the flags 
'Visible From Parent' and 'Parent Visible'. In such a
cluster you should take care of the portal(s) orientation:
The portal front face should look outside the CS.
This is the only situation the orientation of a portal is checked.

A portal can be dynamic, ie, it can be opened / closed at runtime.
(When a door is open / close for exemple). If you want set your 
portal dynamic, flag it "Dynamic portal" in NelExport. At runtime, 
you can get / set it using 
UInstanceGroup::getDynamicPortal / 
UInstanceGroup::setDynamicPortal.

- Run time
----

At run time, the only thing to do, after loading and hierarching CS, is
to place each movable instances into the good cluster system. 
NeL cluster system DOESN'T KNOW in which CS a moving object 
is.

The reason is, we prefer using PACS collision informations that are
arlready performed and fasters to check than testing cluster systems.

To do that, use an indoor collision mesh per CS. If your moving object
is over the collision mesh, then insert it into the corresponding CS. 
To place a NeL instance into a CS, use 
UTransform::setClusterSystem ().

-------

We hope this is understandable :-)

Cyril Corvazier, corrected by Matthieu Besson