2.2 Manual Errata

General Box2D issues or C++ specific issues
Posts: 132
Joined: Wed Oct 28, 2009 6:14 pm

confusing raycast documentation

Postby Storyyeller » Sun Oct 23, 2011 1:24 pm

The manual entry on raycasting is a little confusing.

Suppose I want to find the closest point among fixtures meeting some criteria. In my callback, I return fraction if the fixture is acceptable and 1.0f if not. However, this occasionally produces incorrect results.

After reading it more closely and doing some experimentation, my theory is that this is a result of the callback being called out of order, and returning a higher value causes stuff to be unfiltered. So if it was called on a good fixture of distance 10, then a bad fixture of distance 8, and then a good fixture of distance 12, the second call would unfilter the last one and the final result would be 12.

It seems like this is a dangerous pitfall that should be emphasized more clearly in the documentation. It is not immediately obvious that you have to keep track of the cumulative cutoff if you want things to remain filtered.

irresistible force
Posts: 1991
Joined: Tue Jun 24, 2008 8:25 pm
Location: Tokyo

Re: confusing raycast documentation

Postby irresistible force » Sun Oct 23, 2011 11:25 pm

I agree. Generally most concepts can be understood by taking a look at the demo test and its source code, but with this one I found myself still unclear about what was going on.

I think many people may not realize the flexibility the callback method provides and they are expecting to be restricted to only getting the closest fixture (the standard ray cast), so the fact that the fixtures are reported in an undetermined order should be mentioned. It would also be good to know what this means for the most common practical uses, ie:

To find only the closest intersection:
- return the fraction value from the callback
- use the most recent intersection as the result
To find all intersections along the ray:
- return 1 from the callback
- store the intersections in a list
To simply find if the ray hits anything:
- if you get a callback, something was hit (but it may not be the closest)
- return 0 from the callback for efficiency


Personally I think most of my confusion would have been taken care of if the on-screen display in the testbed's Ray-cast test was fleshed out a little more, like:

m_debugDraw.DrawString(5, m_textLine, "Current mode: %s",
m_mode == e_closest ? "find the closest fixture along the ray":
m_mode == e_any ? "stop searching after finding any fixture (but maybe not the closest)":
"record intersections with all fixtures along the ray");
m_textLine += 15;
m_debugDraw.DrawString(5, m_textLine, "Note: the larger triangle fixture is filtered out and is always ignored.");
m_textLine += 15;

A common question is how to find an 'exit point', so a pre-emptive mention this can be done by simply reversing the ray might be helpful too.

By the way Storyyeller I think you should be returning -1 for the case where you want to completely ignore a fixture.

Posts: 11
Joined: Sat Nov 26, 2011 12:36 pm

Re: 2.2 Manual Errata

Postby gerald » Sat Nov 26, 2011 8:28 pm

Erin Catto wrote:Please post any errors or feedback on the 2.2 C++ manual in this thread.

It would be nice if there was something that explained the relationship between body positions and
shape positions. I couldn't find anything that stated whether we're working with relative or world coordinates.


Posts: 341
Joined: Fri May 16, 2008 10:09 am

Re: 2.2 Manual Errata

Postby dc443 » Sat Dec 10, 2011 2:58 pm

This is not about the manual, but the API documents that come with the 2.2.1 distribution.

b2Body::SetAwake() and b2Body::IsAwake() both function as they should but the descriptions have not been changed from referring to what I imagine used to be IsAsleep and SetSleep and so they are backwards.

Posts: 11
Joined: Fri Feb 10, 2012 4:08 am

Re: 2.2 Manual Errata

Postby BoxMan » Sat Feb 11, 2012 3:04 pm

Page 54.

b2Body* body1 = point->shape1->GetBody();
b2Body* body2 = point->shape2->GetBody();

should be

b2Body *body1 = point->fixtureA->GetBody();
b2Body *body2 = point->fixtureB->GetBody();

Posts: 11
Joined: Tue Aug 30, 2011 1:21 am

Re: 2.2 Manual Errata

Postby pagekalisedown » Thu Apr 04, 2013 3:53 pm

manual.pdf, page 55 of 66:

"This class requires you to implement a ShouldCollide function that receives two b2Shape pointers. Your function returns true if the shapes should collide."

Should be:

"This class requires you to implement a ShouldCollide function that receives two b2Fixture pointers. Your function returns true if the fixtures should collide."

The file:


Also mentions shapes instead of fixtures here:

Code: Select all

/// Joints and fixtures are destroyed when their associated
/// body is destroyed. Implement this listener so that you
/// may nullify references to these joints and shapes.
class b2DestructionListener

and here:

Code: Select all

/// Return true if contact calculations should be performed between these two shapes.
/// @warning for performance reasons this is only called when the AABBs begin to overlap.
virtual bool ShouldCollide(b2Fixture* fixtureA, b2Fixture* fixtureB);

Posts: 11
Joined: Tue Aug 30, 2011 1:21 am

Re: 2.2 Manual Errata

Postby pagekalisedown » Thu Jul 03, 2014 2:41 pm

In the section "8.2 The Joint Definition" here:


In the following sentence, the last "to" either needs to be removed or replaced by "two":

"This is actually the default behavior and you must set the collideConnected Boolean to allow collision between to connected bodies."

Return to “Bugs, Requests, and Feedback”

Who is online

Users browsing this forum: No registered users and 1 guest