Add description of class members to Ogre class reference

[Beauty]

I'm happy to hear that you are on the job.

To improve documentation (mostly in the wiki) is my main focus to support the Ogre community.

[masterfalcon]

I couldn't find what exactly the final answer was on the co-domains question. Is it -180,180 for pitch, roll and yaw?

[masterfalcon]

Well, I haven't gotten filled in all of the suggestions. But a big portion at least. I've also fixed a number of doxygen and spelling issues. I will push my changes in a few minutes.

[Beauty]

Good boy.
Thanks for your efforts

I couldn't find what exactly the final answer was on the co-domains question. Is it -180,180 for pitch, roll and yaw?

Just in the moment I compared the Ogre and Mogre source code.
I recognized differences and found a related forum topic.

For the Ogre documentation only the Ogre behaviour is interesting.

Kojack tested getYaw():

getYaw() is -180 to 180. I just tested it and it returned values below -90 and above 90 fine.

Unfortunately I don't find co-domains for other angles in the related forum topics.
For me it's difficult to test, because of my bad C++ knowledge.

Here is a C# testing code.
Just port it to C++ and run it. Then you will get a report for the resulting co-domains.
(In comparison to my previous version, now you don't need a SceneNode, no an initialized SceneManager.)

Code: Select all

Single yaw = 0;
Single pitch = 0;
Single roll = 0;

Single ymin = 0;
Single ymax = 0;
Single pmin = 0;
Single pmax = 0;
Single rmin = 0;
Single rmax = 0;

Single y, p, r;

Quaternion quat;
Console.WriteLine("Start calculation ...\n");
Console.Write("Intermediate steps: ");

for (yaw = -200; yaw <= 200; yaw++)
{
    for (pitch = -200; pitch <= 200; pitch++)
    {
        for (roll = -200; roll <= 200; roll++)
        {
            quat = new Quaternion(new Degree(yaw), Vector3.UNIT_Y) 
                   * new Quaternion(new Degree(pitch), Vector3.UNIT_X) 
                   * new Quaternion(new Degree(roll), Vector3.UNIT_Z);
            
            y = quat.Yaw.ValueDegrees;
            p = quat.Pitch.ValueDegrees;
            r = quat.Roll.ValueDegrees;

            if (y < ymin)
                ymin = y;
            if (y > ymax)
                ymax = y;
            if (p < pmin)
                pmin = p;
            if (p > pmax)
                pmax = p;
            if (r < rmin)
                rmin = r;
            if (r > rmax)
                rmax = r;

        }

    }
    Console.Write(".");
    if ((yaw % 10) == 0)
        Console.Write(yaw); // show current state of calculation

}
Console.WriteLine("\n\nCalculation ready.\n");

Console.Write("co-domains:\n");
Console.Write(String.Format("Yaw    {0} .. {1} \n", ymin, ymax));
Console.Write(String.Format("Pitch  {0} .. {1} \n", pmin, pmax));
Console.Write(String.Format("Roll   {0} .. {1} \n", rmin, rmax));

Note: As far as I know, the datatype "Single" is called "real" in C++.

[Beauty]

Next task:

bool ManualObject::ManualObjectSection::get32BitIndices
Current description + my addition (bold):

Get whether we need 32-bit indices. If false, 64-bit indices are needed.

void ManualObject::ManualObjectSection::set32BitIndices ( bool n32)
Current description + my addition (bold):

Set whether we need 32-bit indices. If false, 64-bit indices are needed.

[CABAListic]

Are you sure about 64bit? Indices are usually either 16 or 32 bits, so the function should return whether 32 bits are needed or if 16 bits are sufficient.

[masterfalcon]

I agree with Cabal here. Ogre doesn't support 64 bit indices anyway.

Code: Select all

		    enum IndexType {
			    IT_16BIT,
			    IT_32BIT
		    };

[Beauty]

Are you sure about 64bit?

Oh, thanks for this note. You are right.
In the polygon raycasting code of the wiki an UInt64 was used for indices. So I assumed the "oposite" of 32 bit would be 64 bit.
After using my brain, now I know the real reason of 64 bit usage in the raycasting code. (It's used to address the indices of all SubMeshes.)


Proposal:
Ogre::Quaternion::equals (const Quaternion & rhs, const Radian & tolerance)
The first parameter could be renamed to "other".
This is more intuitive then "rhs".

[Beauty]

Today I need math calculations again.
Unfortunately there are many undocumented methods in class Matrix3.
For example Matrix3::ToEulerAnglesXYZ(...)
It would be nice if someone writes descriptions for that.


By the way - You (masterfalcon) pushed your edits to the repository.
But it seems so, that the online documentation wasn't updated yet.
Who does the job? Perhaps somebody only needs to start a build script on the server?

[Mikachu]

But it seems so, that the online documentation wasn't updated yet.

It's because the version of doxygen doc on the Ogre Site has been generated with Ogre 1.7.1, as stated here.
tdev and I are currently trying to configure a continuous integration server for ogre binary SDKs and online API documentation... that may help with these kinds of issues.

[Mikachu]

@Beauty : here is an updated version of the API reference.

It has been generated from the latest 1.8 source (don't bookmark it, the site location will probably get modified)

I've also put online the Ogre 1.8 Manual, which already comes inside Ogre's source.

[Beauty]

Oh, very nice - thank you