Wrap gtkutil/entry
[xonotic/netradiant.git] / regression_tests / q3map2 / plane_aliasing / README.txt
1 DESCRIPTION OF PROBLEM:
2 =======================
3
4 This example map demonstrates what a relatively large value for plane distance
5 epsilon can do as far as destroying draw surfaces.  The plane distance
6 epsilon was 0.01 at the time of this writing.  This means that two planes
7 with the same normal and a distance 0.00999 apart are considered to be the
8 same plane.
9
10 The recommended value of plane distance epsilon is more along the lines of
11 0.001; however, we can't currently change this epsilon to that value due to
12 lack of resolution in 32 bit floating point integers in the 2^16 number range.
13 The smallest epsilon in 32 bit float land that can be added to 2^16 that
14 results in a value greater than 2^16 is approximately 0.007, which is already
15 practically the current default plane distance epsilon (0.01).
16
17 Brush 0 in the example map is a 6-sided brush with red top face.  The red top
18 face is defined such in the .map file:
19
20   ( -127 256 513 ) ( -127 384 513 ) ( 1 384 512 )
21
22 During the -bsp stage,
23
24   In ParseRawBrush() for brush 0
25       Side 4:
26           (-127.000000 256.000000 513.000000)
27           (-127.000000 384.000000 513.000000)
28           (1.000000 384.000000 512.000000)
29           normal: (0.0078122616 0.0000000000 0.9999694824)
30           dist: 511.9921875000
31
32 Now brush 1, the 4-sided brush with the red top face, has the following
33 defined as the red top face:
34
35   ( -128 0 513 ) ( -128 128 513 ) ( 0 128 512 )
36
37 It's almost the same plane, only off by a distance of about 0.01.
38
39 During compiling:
40
41   In ParseRawBrush() for brush 1
42       Side 1:
43           (-128.000000 0.000000 513.000000)
44           (-128.000000 128.000000 513.000000)
45           (0.000000 128.000000 512.000000)
46           normal: (0.0078122616 0.0000000000 0.9999694824)
47           dist: 511.9921875000
48
49 Note that the normal and dist are identical to the plane above, even though
50 the two are different.  This leads to multiplying errors later on, when this
51 side is intersected with the bottom green face.  In particular, the blue face
52 disappears from the map.  The blue face:
53
54   In CreateBrushWindings() for brush 1
55       Handling side 2 on the brush
56           Before clipping we have:
57               (-262144.00000000 0.00000000 262144.00000000)
58               (262144.00000000 0.00000000 262144.00000000)
59               (262144.00000000 -0.00000000 -262144.00000000)
60               (-262144.00000000 0.00000000 -262144.00000000)
61           After clipping w/ side 0 we have:
62               (-262144.00000000 0.00000000 262144.00000000)
63               (262144.00000000 0.00000000 262144.00000000)
64               (262144.00000000 0.00000000 -19977.00073172)
65               (-262144.00000000 0.00000000 20983.00073758)
66           After clipping w/ side 1 we have:
67               (262144.00000000 0.00000000 -1535.99218726)
68               (262144.00000000 0.00000000 -19977.00073172)
69               (-128.11106773 0.00000000 513.00868046)
70           After clipping w/ side 3 we have:
71               (0.00000000 0.00000000 503.00000293)
72               (-128.11106773 0.00000000 513.00868046)
73               (-0.00000000 0.00000000 512.00781274)
74
75 We see the error is greater than 0.1 in the X value -128.11106773.  This
76 causes the draw surface to be discarded in processing later on.  We must
77 not allow such a great error.  An error greater than or equal to 0.1 is
78 considered to be very bad.
79
80 This disappearing blue triangle can be fixed simply by deleting brush 0,
81 the 6-sided brush that causes the bad plane alias.  I would suggest deleting
82 this brush by editing the .map file manually (and then renumbering the brushes
83 manually).
84
85 After deleting this brush:
86
87   In ParseRawBrush() for brush 0
88       Side 1:
89           (-128.000000 0.000000 513.000000)
90           (-128.000000 128.000000 513.000000)
91           (0.000000 128.000000 512.000000)
92           normal: (0.0078122616 0.0000000000 0.9999694824)
93           dist: 511.9843750000
94
95   In CreateBrushWindings() for brush 0
96       Handling side 1 on the brush
97           Before clipping we have:
98               (262132.00000000 262136.00000000 -1535.90625143)
99               (262132.00000000 -262136.00000000 -1535.90625143)
100               (-262124.00048828 -262136.00000000 2559.84375238)
101               (-262124.00048828 262136.00000000 2559.84375238)
102           After clipping w/ side 0 we have:
103               (262132.00000000 262136.00000000 -1535.90625143)
104               (262132.00000000 -262136.00000000 -1535.90625143)
105               (-127.99993289 -262136.00000000 512.99999805)
106               (-127.99993289 262136.00000000 512.99999805)
107           After clipping w/ side 2 we have:
108               (262132.00000000 262136.00000000 -1535.90625143)
109               (262132.00000000 -0.00000000 -1535.90625143)
110               (-127.99993289 -0.00000000 512.99999805)
111               (-127.99993289 262136.00000000 512.99999805)
112           After clipping w/ side 3 we have:
113               (0.00000000 0.00000000 511.99999857)
114               (-127.99993289 -0.00000000 512.99999805)
115               (-127.99993289 127.99993289 512.99999805)
116
117 Note that we're way more accurate now, and we're nowhere near to approaching
118 the 0.1 error.  All it took was the deletion of a seemintly unrelated brush.
119
120
121 SOLUTION TO PROBLEM:
122 ====================
123
124 The suggested fix is to increase the resolution of plane distance from 32 bit
125 float to 64 bit float for the relevant brush processing operations.  After that
126 is done, decrease the default plane distance epsilon from 0.01 to 0.001.  Note
127 that even though plane distance epsilon can be specified on the command-line,
128 it will do no good (even if set to 0) if the plane distance is close to
129 2^16.