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.