[Nel] Cluster Systems v2

[Cyril 'Hulud' Corvazier]

Ok, second version of this document. It should be a little less "franglais" 
with the help of Loïc.


----
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 associated with one instance group (IG). The CS description is saved 
into the IG. A CS can be used to clip objects
referenced in the associated IG or other objects, unrelated to the IG but 
explicitly inserted in the CS at runtime.

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 polyhedron. It can be done in 3dsmax using a mesh 
flagged as cluster with NeLExport. All the objects
referenced in the IG associated with the CS that intersect the cluster are 
associated with the cluster. At least one vertex of an
object must be in the cluster to consider this object is associated with the 
cluster. A given object can be associated with more
than one cluster.

At runtime, 3d objects that are not associated with a cluster are tested 
against the view frustum (VF) to check if they are visible.
In the same way, clusters are tested against the VF. When a cluster is tested 
against a VF, the objects associated with the cluster
are tested against the VF too. If an object associated with a cluster never 
intersects the VF, it won't be rendered.

If the camera is placed into a CS, the cluster that contains the camera will be 
tested against the VF. To place the camera into a
CS, use UTransform::setClusterSystem ().

A cluster can be flagged as "Parent Visible" with NeLExport, it means that if 
this cluster is tested against the VF, the parent
cluster will be tested by the VF too.

A cluster can be flagged as "Visible From Parent" with NeLExport, it means that 
if its parent cluster is tested against the VF, the
cluster will be tested by the VF too.

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

- Portal
----

A portal is a convex and flat 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 must be 
completly enclosed in the intersection of two clusters.

When a cluster is tested against the VF, for each portal in this cluster, the 
VF is clipped against the portal, and if the VF is not
empty, the second cluster is tested against the remainder of the VF. A VF 
(called vf0) clipped against a portal is the smallest VF
enclosed by vf0 that encloses the portal.

Hierarchical organization of CS depends on the properties of at least one 
cluster within the CS. A cluster with both 'Visible From
Parent' and 'Parent Visible' must exists in order for a CS to be linked with 
its parent in the CS hierarchy. This specific cluster
must also obey an additional constraint : a camera placed in the parent cluster 
should see the FRONT FACE of the portals contained
in the specific cluster and not the BACK FACE.

A portal can be dynamic, ie, it can be opened / closed at runtime. (When a door 
is open / close for exemple). If you want to set the
dynamic aspect of a portal, 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 organizing the CS into a 
hierarchy, is to place each movable instances into the
CS it belongs to.

There is no information related to moving objects in a CS, hence NeL has no way 
to know which moving object should be placed in a
given CS.

Moving objects use the PACS collision informations for this purpose. In 
addition they are pre-calculated and use less CPU than
testing intersection of the moving object with the CS.

To place a moving object within a CS, 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,
corrected by Loïc Dachary