Subject: debugging .WLD files and SPLITs

From: Chris Hand <[email-masked]>
Date: Sun, 8 Nov 92 0:09:05 GMT

I've just been hacking around getting rid of some visibility errors
in a couple of .WLD files and I think I now understand what SPLITs
are all about (except for the mysterious "flags" that don't seem to
be documented -- back to the source I suppose).

Anyway, assuming that there is at least one other person out there
who still hasn't mastered this, the following spiel on debugging
.WLD files may be of use.

Cheers,

Chris

---8x--cut-here---

DEBUGGING .WLD FILES

From time to time "visibility errors" occur when using REND386, mostly
due to objects being rendered in the wrong order.  This means that objects
that should be obscured are still visible etc.

WHAT TO DO WHEN YOU SPOT A VISIBILITY ERROR
The first thing to do is to find out where and when the error occurs. 
It will almost certainly pop up when the position of the viewpoint (the
"camera" if you like) is within a certain range.  By moving the
viewpoint around (using the arrow keys etc.) you should be able to find
an x, y or z position that makes the error appear and then disappear as
you move one way and then the other.  Once you've found it, record the
position.  Pressing 'D' gives you the exact position as x/y/z, pan/tilt/roll
and zoom values.  

Now edit your .WLD file and comment out the original line beginning with
"START" and create a new one using the values you just recorded.  Now when
you run REND386 with the world file the error will be immediately visible.

Other useful debugging techniques: 
    - Make one or more objects "glass" (select then 'Z', 'A', 'G') so you
      can see through to the other side
    - Change the colour of objects so boundaries are more distinct 
    - Move up/down (ctrl+page up or page down) until a horizontal edge
      lines up exactly with the horizon.  The height of the camera
      (given by pressing 'D') is now the Y co-ordinate of that edge.

FIXING THE ERROR
Due to the strategy used by the rendering engine, errors can occur when 
objects are drawn in the wrong order.  Defining splits helps to fix
this (see also SPLITS.DOC in the REND386 distribution).

SPLITS
A split is a plane, in other words it stretches out to infinity in 2
directions, while in the third it has zero thickness.  Defining a split
as the plane y=0 would split our world into two halves: the area above
y=0 and the area below y=0 (remember the positive y-axis points upwards
in the REND386 co-ordinate system).  The important thing about a split
is that it divides (splits) a part of 3-D space into two areas, one on
each side of the splitting plane.

Now to fix the error by adding a split.  The visibility error will
include two or more objects -- some of which will be drawn in the wrong
order (let's assume two objects here).  To fix the error we need to add
a split *between* those objects.

As an simplistic example, suppose we have a tall thin cuboid that's sitting
on a small fat cuboid (call then "Small" and "Big").

           +----+            
          / A  /|
         +----+ | <---------- "Small"
         |    | |
      +--|    | |---+  
     /   |    | +  /|
    /    |    |/  / |
   /     +----+  /  | <------- "Big"
  +-------------+   +
  |             |  /
  |             | /
  |             |/
  +-------------+

Suppose that when we move the viewpoint downwards we get an error due to
the face of Small that's resting on Big (ie. the face opposite face
marked "A") being visible when it shouldn't be.  So we need to add a
split between Small and Big.

If the co-ordinates used are as follows:

           +----+ <---------- y=300  (top face of Small)    
          / A  /|
         +----+ |
         |    | |
      +--|    | |---+ <---------- y=100  (top face of Big)
     /   |    | +  /|
    /    |    |/  / |
   /     +----+  /  |
  +-------------+   + <---------- y=0 (bottom face of Big)
  |             |  /
  |             | /
  |             |/
  +-------------+

...then the splitting plane we need will be at y=100.  We can specify the
split in the world file as

	SPLIT 0,100,0  0,1,0 

This specifies a point (x=0,y=100,z=0) and a "normal", which is a Vector
at 90 degrees to the plane.  As far as I can see the direction of the
normal is not important since we're only really specifying the plane
and not defining what is on one side or the other.  So we could have
said "0,-1,0" and it wouldn't matter.

In general, a split whose normal points along the y-axis will be defined
by:
	SPLIT 0,<y-value>,0   0,1,0

while one whose normal points along the z axis would be

	SPLIT 0,0,<z-value>   0,0,1

So we can add the line defining the split to the .WLD file.  Put the
splits before you define the objects, followed by an "ENDSPLITS"
statement.  NB: *don't* include objects in the SPLITS section unless the
object is actually "on" a split!

Once the split has been added you can run the REND386 program again and
check that the error has gone.  The procedure can then be repeated for
other errors until they've all been fixed.

-- 
Chris Hand, Lecturer                Internet mail: [email-masked]
Dept of Computing Science,          Voice: +44 533 551551 x8476
De Montfort University, The Gateway,  Fax: +44 533 541891  FIDOnet: 2:440/32.50
LEICESTER, UK   LE1 9BH             >> Linux: *free* unix for IBM PCs! <<