regression_tests/q3map2/snap_plane/README.txt

   1 DESCRIPTION OF PROBLEM:
   2 =======================
   3
   4 The example map, maps/snap_plane.map, contains an example of some bugs.
   5 The green brush with the red face is transformed into something totally
   6 unexpected.
   7
   8 To trigger the bug, compile the map; you don't need -vis or -light.  Only
   9 -bsp (the first q3map2 stage) is necessary to trigger the bug.  The only
  10 entities in the map are a light and a info_player_deathmatch, so the map will
  11 compile for any Q3 mod.
  12
  13
  14 SOLUTION TO PROBLEM:
  15 ====================
  16
  17 I actually came up with this regression test after reading the code to
  18 SnapPlane() and SnapNormal().  I decided to make this map as a test of
  19 whether or not I understand how the code is broken.  Sure enough, the map
  20 is broken in the same way that I would expect it to be broken.
  21
  22 The problem is that the red face of the green brush in the center of the room
  23 is very close to being axially aligned, but not quite.  This plane will
  24 therefore be "snapped" to become axial.  This is not the problem.  The
  25 problem is that after the snap, the plane will be shifted a great deal,
  26 and the corner of the green brush will no longer come even close to meeting
  27 the corner of the other cube brush next to it (the two corners of the two
  28 brushes will drift apart a great deal).
  29
  30 If you study the legacy SnapPlane() code, you will see that planes are
  31 defined as a unit normal and distance from origin.  Well, because
  32 of the position of this brush on the side of the world extents (far from
  33 the original), the snap will cause drastic effects on the points that the
  34 plane was supposed to approximate.
  35
  36 Another problem with SnapPlane() is that SnapNormal() snaps too liberally.
  37 Once SnapNormal() is changed to only snap normals that are REALLY close
  38 to axial (and not anything within 0.25 degrees), this bug will no longer
  39 appear, but the SnapPlane() problem will still be present.  So, this
  40 regression test should be fixed BEFORE SnapNormal() is fixed, otherwise
  41 create another regression test with a red face that is much much closer to
  42 being axially aligned.  We want to make sure that SnapPlane() is fixed when
  43 things actually do get snapped.
  44
  45 The code to address these issues is currently being worked on.