Debian Codegraph @

Documentation/Overview/collision_detection.xml

raw
1 <xml>
2 <head>
3 <title>Collision Detection</title>
4 </head>
5 <body>
6
7 <p>As of release 0.7.8 ClanLib comes with collision detection support. The
8 collision system works by checking for intersections between line segments in
9 line-loops surrounding the objects to collide. The advantage of this method
10 over traditional methods, such as pixel based collision detection, is that the amount of data
11 that needs to be worked with when checking for collisions and when doing
12 transformations is very low. This enables besides fast collision
13 testing also fast rotation and scaling of outline geometries.</p>
14
15 <h3>Collision Outlines</h3>
16
17 <p>Outlines can be generated from RGBA images by following the edge between
18 transparent and opaque pixels. <p>
19
20 <p>To generate an outline from a RGBA image stored as image.png the following can be used:<p>
21
22 <code>
23 CL_CollisionOutline outline("image.png");
24 </code>
25
26 <p>Generating outlines from bitmaps can be quite expensive causing long load
27 times. To battle that CL_CollisionOutline has a save function and constructors which
28 can load saved outlines:</p>
29
30 <code>
31 CL_CollisionOutline generated("image.png");
32 generated.save("image.out");
33
34 CL_CollisionOutline loaded("image.out");
35 </code>
36
37 <p>Initially the contour following algorithm adds every pixel along
38 the edge to the outline. This results in a lot of redundant information
39 being added to the outline, but that can be optimized away without reducing
40 the accuracy of the outline too much. The constructor which creates outlines
41 from RGBA images takes a CL_OutlineAccuracy parameter which specifies how
42 much to optimize the outline.</p>
43
44 <code>
45 CL_CollisionOutline generated("image.png", accuracy_high);
46 </code>
47
48 <p> The values for CL_CollisionAccuracy are:
49 <ul>
50 <li>accuracy_raw</li>
51 <li>accuracy_high</li>
52 <li>accuracy_medium</li>
53 <li>accuracy_low</li>
54 <li>accuracy_poor</li>
55 </ul>
56
57 and their affects on generated outlines:
58 <br>
59 <br>
60 <img src="Images/outline_accuracy.png">
61 <br>
62
63 The optimization causes errors mostly in the round parts.
64 <br>
65 </p>
66
67 <h3>Testing for collisions</h3>
68
69 <p>Once the collision outlines have been positioned using the
70 transformation function (translate, rotate and scale) checking for a
71 collision is simply a matter of calling the collide function. In a game
72 one might have code similar to this:</p>
73
74 <code>
75 if( outline.collide(outline2) )
76 {
77 foo();
78 }
79 </code>
80
81 <p>It's also possible to test if a point is inside an outline:</p>
82
83 <code>
84 if( outline.point_inside( CL_Mouse::get_x(), CL_Mouse::get_y() )
85 {
86 bar();
87 }
88 </code>
89
90 <p>When checking for a collision a bounding circle test is always performed
91 first.
92 The way the collision testing is done can be adjusted by
93 enabling/disabling completely inside test, and by
94 enable/disable the object bounding box test.</p>
95
96 <p>When using the inside test,
97 outlines completely inside another outline (or completely surrounding) will report
98 a collision. If either of the objects being tested has inside_test set to
99 true, the inside test will be done for both objects.</p>
100
101 <p>Object bounding box (obb) test uses a rotated tightly computed rectangle
102 around the outline, and the obb is tested against the other obb first before
103 any further (more detailed) collision detection tests are performed. For
104 long narrow outlines an obb will give a lot more tighter bounds than a
105 bounding circle, effectively eliminating further redundant checks.</p>
106
107 <code>
108 outline.set_inside_test(true);
109 outline.set_obb_test(false);
110 </code>
111
112 <h3>Internal operation</h3>
113
114 <p>The structure of the collision data structures is as follows:
115
116 <code>
117 CL_CollisionOutline
118 CL_Contour(s)
119 vector<CL_Pointf> points
120 vector<CL_CollisionCircle> subcircles
121 </code>
122
123 <p>Collisions are checked for by checking each line-segment forming the outline,
124 against the line-segments of the other collision outline. If the number of
125 line segments is big this will be somewhat slow. To eliminate checks that
126 are sure to fail, the line-segments have been grouped into circles which
127 hold a start and end index in the point array.</p>
128
129 <p>These sub-circles are collided against each other before any line-line intersection tests take
130 place. Line-segments encapsulated in subcircles are only checked
131 when two subcircles collides with each other. If the subcircles don't collide
132 there is no chance that the line-segments inside them will collide either.</p>
133
134 <br>
135 <img src="Images/outline_subcircles.png">
136 <br>
137
138 <p>If an outline is created manually by adding a contour to the outline and points
139 into the contour, it's necessary to calculate the subcircles and the radius
140 before collision tests can be performed. It should also be noted that the points of the contour is
141 assumed "closed" that is, you do not need to specify the same point as both first and last. And the
142 points must be added to the contour in counter-clockwice order.</p>
143
144 <code>
145 CL_SurfaceOutline outline;
146
147 CL_Contour contour;
148 contour.points.push_back( CL_Pointf(0.0f,0.0f) );
149 contour.points.push_back( CL_Pointf(0.0f,100.0f) );
150 outline.get_contours().push_back(contour);
151 outline.calculate_radius();
152 outline.calculate_sub_circles();
153 </code>
154
155 <p>If your contours are rather small, you can optimise them to only have one (sub)circle.
156 This circle is calculated to be as small as possible, and still contain all the points. It can be done with
157 the following code.</p>
158
159 <code>
160 [... create the outline in some way ...]
161 // Use this in-stead of "calculate_sub_circles()";
162 outline.calculate_smallest_enclosing_discs();
163 </code>
164
165 <h3>Collision Info</h3>
166 <p>If you have enabled any kind of collision info (with <em>enable_collision_info(points,normals,metadata)</em>) then
167 you can retrieve this information with the method <em>get_collision_info</em>. What will be returned is a vector with
168 <em>CL_CollidingContours</em>-structures. Each representing the collision of two contours.
169
170 <p>These structures contain the information you asked the outlines to collect. They always contain two pointers to the
171 colliding contours. These are called: <em>contour1</em> and <em>contour2</em>. If you told it to collect
172 collision-points, then these can be found as the "<em>point</em>" property of all the <em>CL_CollisionPoint</em> stored
173 in the vector <em>points</em>. If you told it to collect normals then they can be found as the "<em>normal</em>"
174 property of all the <em>CL_CollisionPoint</em> stored in the vector <em>points</em>.
175
176 <p>The following code demonstrates how you can access the information.
177
178 <code>
179 outline.enable_collision_info(true, true, false);
180 if( outline.collide(outline2) )
181 {
182 const std::vector<CL_CollidingContours> &amp;colpointinfo = outline.get_collision_info();
183 // Loop through all pairs of colliding contours
184 for(int c = 0; c &lt; colpointinfo.size(); c++)
185 {
186 const CL_CollidingContours &amp;cc = colpointinfo[c];
187 for(int p = 0; p &lt; cc.points.size(); p++)
188 {
189 std::cout &lt;&lt; "Collision: Point(" &lt;&lt; cc.points[p].point.x &lt;&lt; "," &lt;&lt; cc.points[p].point.y &lt;&lt; ")\n";
190 std::cout &lt;&lt; "Collision: Normal(" &lt;&lt; cc.points[p].normal.x &lt;&lt; "," &lt;&lt; cc.points[p].normal.y &lt;&lt; ")\n";
191 }
192 }
193 }
194 </code>
195
196 <h4>Collision Metadata</h4>
197
198 <p>The metadata-part of a collision takes a bit more explaination. It is used to keep track of where the intersections
199 between two contours occured. That is they keep track of what linesegments generated the collision-points. They also keep
200 track of wether the collision point is an entry or an exit point (Note this works because all contours are describes as a
201 list of points in counter-clockwice order). The metadata is mainly intended to calculate the depth of a penetration.
202 Since contours only store the points, and not the linesegments, we have to store the two indexes of the two points that
203 represent the linesegment. And we have to do this for both linesegments.
204
205 <p>The following peace of code shows how to access the metadata.
206
207 <code>
208 outline.enable_collision_info(true, true, true);
209 if( outline.collide(outline2) )
210 {
211 const std::vector<CL_CollidingContours> &amp;colpointinfo = outline.get_collision_info();
212 // Loop through all pairs of colliding contours
213 for(int c = 0; c &lt; colpointinfo.size(); c++)
214 {
215 const CL_CollidingContours &amp;cc = colpointinfo[c];
216 for(int p = 0; p &lt; cc.points.size(); p++)
217 {
218 const CL_CollisionPoint &amp;colp = cc.points[p];
219 std::cout &lt;&lt; "LineSegment1:"
220 &lt;&lt; "(" &lt;&lt; cc.contour1->points[colp.contour1_line_start].x
221 &lt;&lt; "," &lt;&lt; cc.contour1->points[colp.contour1_line_start].y &lt;&lt; ") - "
222 &lt;&lt; "(" &lt;&lt; cc.contour1->points[colp.contour1_line_end].x
223 &lt;&lt; "," &lt;&lt; cc.contour1->points[colp.contour1_line_end].y &lt;&lt; ")\n";
224 std::cout &lt;&lt; "LineSegment2:"
225 &lt;&lt; "(" &lt;&lt; cc.contour2->points[colp.contour2_line_start].x
226 &lt;&lt; "," &lt;&lt; cc.contour2->points[colp.contour2_line_start].y &lt;&lt; ") - "
227 &lt;&lt; "(" &lt;&lt; cc.contour2->points[colp.contour2_line_end].x
228 &lt;&lt; "," &lt;&lt; cc.contour2->points[colp.contour2_line_end].y &lt;&lt; ")\n";
229 }
230 }
231 }
232 </code>
233
234
235 </body>
236 </xml>