VERY simple, beginner question re: documentation:

Post Reply
mscottveach
Posts: 6
Joined: Sat Nov 30, 2013 9:31 am

VERY simple, beginner question re: documentation:

Post by mscottveach »

I've done some googling and searched these forums and skimmed the manuals but
haven't found what I'm looking for:

I was trying to make some primitive shapes and can see that they often take some
vector where the components of the vector correspond to attributes of the shape.
I'm having trouble finding docs that specify with components correspond to which
attributes for each class. I was able to just experiment to figure it out for cylinders
and box shapes but I thought it would be good for me to know where I can find
this kind of information in case I run into similar ambiguities on classes less easy
to experiment with--

--does this kind of comprehensive api documentation exist somewhere? Or do I
need to just look through the code base and suss it out on a case by case by basis?
No worries if it's the latter just checking to see in case...
benelot
Posts: 350
Joined: Sat Jul 04, 2015 10:33 am
Location: Bern, Switzerland
Contact:

Re: VERY simple, beginner question re: documentation:

Post by benelot »

Hello and welcome to the forum!
Can you give us an example code segment of which vector you mean? The best documentation of how to do most things are thr examples that come with your distribution of bullet. That is where you should find simple setups of different shapes and a lot more.

Cheers
User avatar
drleviathan
Posts: 849
Joined: Tue Sep 30, 2014 6:03 pm
Location: San Francisco

Re: VERY simple, beginner question re: documentation:

Post by drleviathan »

First there is the online documentation. I usually start here and just navigate to the class of interest:

http://www.continuousphysics.com/Bullet ... tated.html

The documentation may be thin, but at least the class methods and arguments are listed and one can usually figure out how the arguments are supposed to be used based on their names. For example:

Code: Select all

btCylinderShape (const btVector3 &halfExtents)
The btCylinderShape ctor takes a vector that is its half extents.

Second, as benlot pointed out, there is example code.
mscottveach
Posts: 6
Joined: Sat Nov 30, 2013 9:31 am

Re: VERY simple, beginner question re: documentation:

Post by mscottveach »

drleviathan wrote: The btCylinderShape ctor takes a vector that is its half extents.
Hi, thanks for the replies. So, this btCylinderShape is a perfect example of the
kind of thing I'm asking about.

I can see that it wants a vector that defines the cylinder but it doesn't actually
tell me which components represent which aspects of a cylinder shape.

I took a guess that it would want radius and height (half those values since it's a
halfExtantVec) and put them in x and y. Eventually, I realize it was a diameter not a radius
in the x component and a height in the y component and after a fair amount of guessing
and experimentation I am still at a loss for what it is doing with the z component (if
anything).

So, obviously in this case it's not that big of a deal. It's not hard to do some experimentation.
But I keep running into these kinds of questions and wasn't sure what my best way of
answering them was -- it's beginning to look like experimentation, the example code
and the source code is the way to do it. Not a bad thing just wanted to make sure I
wasn't missing something!

PS. I am still curious what the z component in the cylinder constructor does if anyone
happens to know!
User avatar
drleviathan
Posts: 849
Joined: Tue Sep 30, 2014 6:03 pm
Location: San Francisco

Re: VERY simple, beginner question re: documentation:

Post by drleviathan »

Looking at the code for btCylinderShape I find that it does "use" the Z component of the halfExtents in that it computes values directly from the argument without bothering to verify that the Z component is equal to the X. Specifically, it uses it to compute a reasonable collision margin and also when computing btConvexInternalShape::m_implicitShapeDimensions which, AFAICT is only used in some import/export logic. Ultimately I think what this means is you should, in good faith, provide a vector3 with equal X and Z components and expect the code to do the right thing. If you provide a bad Z value then the shape may get an unusually large margin and maybe some import/export stuff will go bad.

The code is open and while it isn't necessarily convenient documentation it has the final say.
mscottveach
Posts: 6
Joined: Sat Nov 30, 2013 9:31 am

Re: VERY simple, beginner question re: documentation:

Post by mscottveach »

drleviathan wrote:The code is open and while it isn't necessarily convenient documentation it has the final say.
Right. In a lot of ways, thin documentation can be a good thing. Forces you to really figure out what's going on inside the library.
Post Reply