Wrap gtkutil/entry
[xonotic/netradiant.git] / 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.