Add description of class members to Ogre class reference

[Beauty]

Sometimes I recognize, that some class members have no description in the Ogre class reference.
This can be annoying.
One case is that somebody has no idea what's the aim of the method.
An other case is that the user knows the aim, but need to know more details about the parameters.

Examples:
Quaternion::Slerp()
Quaternion::nlerp()
Quaternion::FromAngleAxis()

I don't want to speak evil of the Ogre class reference.
It contains a huge amount of useful information.
Additional for many undocumented class members are hyperlinks to the source code. This is also useful.

I just want to motivate to improve it and fill the few information gaps.
If somebody is interested (and has the write rights), I can post all class members here when I discover it (in my daily work).

[dark_sylinc]

Code: Select all

/** Performs Spherical linear interpolation between two quaternions, and returns the result.
Slerp ( 0.0f, A, B ) = A
Slerp ( 1.0f, A, B ) = B
@remarks:
Slerp has the proprieties of performing the interpolation at constant velocity, and being torque-minimal (unless shortestPath=false). However, it's NOT commutative, which means Slerp ( 0.75f, A, B ) != Slerp ( 0.25f, B, A ); therefore be careful if your code relies in the order of the operands. This is specially important in IK animation.
*/

/** Performs Normalised linear interpolation between two quaternions, and returns the result.
nlerp ( 0.0f, A, B ) = A
nlerp ( 1.0f, A, B ) = B
@remarks:
Nlerp is faster than Slerp.
Nlerp has the proprieties of being commutative (@See Slerp; commutativity is desired in certain places, like IK animation), and being torque-minimal (unless shortestPath=false). However, it's performing the interpolation at non-constant velocity; sometimes this is desired, sometimes it is not. Having a non-constant velocity can produce a more natural rotation feeling without the need of tweaking the weights; however if your scene relies on the timing of the rotation or assumes it will point at a specific angle at a specific weight value, Slerp is a better choice.

//FromAngleAxis:
/** Setups the quaternion using the supplied vector, and "roll" around that vector by the specified radians. */

FromAxes
/** Constructs the quaternion using 3 axes, the axes are assumed to be orthonormal */

ToAxes
/** Gets the 3 orthonormal axes defining the quaternion */

xAxis
/** Returns the X orthonormal axis defining the quaternion Same as doing xAxis = Vector3::UNIT_X * this
Also called the local X-axis
 */

yAxis
/** Returns the Y orthonormal axis defining the quaternion. Same as doing yAxis = Vector3::UNIT_Y * this
Also called the local Y-axis
*/

zAxis
/** Returns the Z orthonormal axis defining the quaternion.  Same as doing zAxis = Vector3::UNIT_Z * this
Also called the local Z-axis
*/

Is this good for you?
If so, I'll check it in this weekend

[jacmoe]

Beauty is a tough customer.

[Beauty]

Good work, dark_sylinc


I have some additions:

Slerp
Look also to Quaternion::nlerp() (linear, faster, less precise) and Quaternion::squad() (non-linear rotation speed, more "natural" appearance).


nlerp
Look also to Quaternion::squad() (non-linear, smooth rotation).


Quaternion::squad
Squad or cubic interpolation allows one to specify four quaternions a,p,q,b. P and Q are used to define a curve of interpolation "velocity" between points A and B. This allows us to slowly increase speed, stay constant, then decrease it during interpolation.
Look also to Quaternion::Slerp() (linear) and Quaternion::nlerp() (linear, faster, less precise).


The information I got from the wiki page Quaternion and Rotation Primer.
Maybe you want to improve my addition.

Interpolation of rotations:
When rotating an object, we might want the object to rotate smoothly over time. We'd like to say, "From your current orientation, rotate to face this point. But take about 300 frames to do it, so only move 1/300th of the rotation right now." Interpolation with matrices is possible, but then so is anything, isn't it? Quaternions provide two methods of interpolation: linear(slerp) and cubic(squad). Ogre provides three implementations: slerp, nlerp and squad. Linear interpolation allows one to specify the percentage of interpolation between the two quaternions. Linear means your "velocity" of movement is constant, which may feel jerky if used for a camera or object. Slerp and nlerp are both linear. Slerp is more accurate, but slower. Squad or cubic interpolation allows one to specify four quaternions a,p,q,b. P and Q are used to define a curve of interpolation "velocity" between points A and B. This allows us to slowly increase speed, stay constant, then decrease it during interpolation. See the External Resources section for links that will elaborate on this.

I also found some more undocumented class members:

Quaternion::Norm()
Quaternion::Inverse()
Quaternion::UnitInverse()
Quaternion::Exp()
Quaternion::Log()
Quaternion::SlerpExtraSpins()

The decription of Quaternion::normalise() is:
Normalises this quaternion, and returns the previous length.
A quaternion has a lengh??
I just know that a vector can have a lengh and after normalisation its length is 1.
Maybe some information for this method could be useful for people who are not so familiar with quaternions (especially beginners).

[Beauty]

The description of Quaternion class is very tiny.
Implementation of a Quaternion, i.e. a rotation around an axis.

This description can be improved.
At least it would be useful to add a remark with the link to the wiki page "Quaternion and Rotation Primer"
http://www.ogre3d.org/tikiwiki/Quaterni ... ion+Primer

Some text block for creating an extended description:

Quaternion - A hypercomplex number consisting of a real part and three imaginary parts hence "quat". The quaternions with a magnitude (length) of one represent all possible orientations (thus rotations) in 3D. Quaternions are used in Ogre to represent the orientation of objects in 3D space. This orientation quaternion can be thought of as a rotational offset from an objects initial facing vector.

Quaternions are an interesting concept probably as new to you as they were to me when I first started this. As described above, when working with quaternions I find it easier to stop thinking about yaw, pitch and roll and instead think of rotation around axes. For instance, lets say we wanted to model a propeller on a jet. The jet faces down the Z axis. In euler terms the rotation would be called roll. In quaternions it is rotation around a vector pointing down the Z axis, or rotation around Vector3::UNIT_Z as we'd refer to it in Ogre.

A quaternion is composed of four components: a vector with x, y, z coordinates and a w rotation. This is an axis/angle representation just as I touched on at the end of the matrix section. Quaternion math can get quite involved, even incorporating imaginary numbers. Fortunately we don't need to use all of that math, nor understand it to work with rotations.

Try this exercise. Point your left index finger straight up. Next grab the tip of a pen with your right hand. Now by moving your wrist and hand around in a circle, try to spin the pen as flatly as possible, always perpendicular to your finger and parallel to the floor. It should look like you had just spun it on a table. Think of this as quaternion rotation around Vector3::UNIT_Y.

Now let's say we have a vector from (0,0,0) to (1,1,-1). With our finger pointing straight right, point it up 45 degrees and away from you 45 degrees. Now rotate the pen around your finger, keeping it perpendicular at all times. Notice how the angle of the axis we choose creates a different rotation.

Like matrices, we can combine quaternion rotations by multiplying them. However they are still not commutative. Q1 * Q2 != Q2 * Q1. Thus the order of application is still important. Also like matrices that represent axis/angle rotation, quaternions avoid gimbal lock.

Add a note (and also reasons?) that in several cases it's better to use Quaternions instead of Euler Angles.

Benefits of Quaternions

Quaternions do have advantages over matrices though. There are implementation pros and cons such as the number of multiplications, or additions during different operations, etc that have been discussed in the forum. Considering practical benefits though, here is a list :

* Axis/angle representation avoids gimbal lock.
* Modifying a rotation is easy. Say we have a rotation describing a -45 degree yaw (left turn). By creating a new quaternion describing a 10 degree yaw (right turn) and multiplying the two, we now have a rotation describing a -35 degree turn. You might use this when applying the same rotation to a number of different objects, or even multiple times to the same object (ie the player). The rotation factor increases or decreases depending on circumstances.
* Avoids costly alignment of matrix drift. This drift occurs when performing lots of operations on matrices using finite point precision, which is used in your computer. Rounding of real numbers graudally builds up and inevitably mucks up the matrix. Abnormalities in the rotation will start to appear due to this drift. The matrix must be normalized in order to reset this, however it is a costly operation. Quaternions on the other hand can still suffer from this drift, but it is much cheaper to normalize having only 4 values instead of 9 or more.
* Interpolation of rotations. When rotating an object, we might want the object to rotate smoothly over time. We'd like to say, "From your current orientation, rotate to face this point. But take about 300 frames to do it, so only move 1/300th of the rotation right now." Interpolation with matrices is possible, but then so is anything, isn't it? Quaternions provide two methods of interpolation: linear(slerp) and cubic(squad). Ogre provides three implementations: slerp, nlerp and squad. Linear interpolation allows one to specify the percentage of interpolation between the two quaternions. Linear means your "velocity" of movement is constant, which may feel jerky if used for a camera or object. Slerp and nlerp are both linear. Slerp is more accurate, but slower. Squad or cubic interpolation allows one to specify four quaternions a,p,q,b. P and Q are used to define a curve of interpolation "velocity" between points A and B. This allows us to slowly increase speed, stay constant, then decrease it during interpolation. See the External Resources section for links that will elaborate on this.
* Ogre uses quaternions! That's probably why you are reading this page. Often, you'll need to get the current orientation of an object, which is returned as a quaternion.

Useful:

Calculation rules:

* quaternion * vector is a vector rotationally offset by the quaternion
* quaternion * quaternion is a quaternion with both rotations combined, 'therefore:'
* rotation1 * rotation2 is a quaternion with both rotations, rotation1 is the orientation of the parent node and orientation2 is the orientation of the child node 'and'
* setOrientation(getOrientation() * rotation) == rotate(rotation)

More ideas for Quaternion description you find here: (I don't want to copy&pase it because it could be under copyright)
http://www.cprogramming.com/tutorial/3d ... nions.html
http://www.gamedev.net/page/resources/_ ... wers-r1095

[CABAListic]

Don't overdo it, though. The documentation is meant as an API reference, not as a math primer. Linking to a more thorough explanation of a quaternion is fine, but adding two pages worth of mathematical background isn't helpful, imho.

[dark_sylinc]

I agree with CABAListic, I agreed to put documentation because sometimes I forget a few bits (i.e. which one was nlerp, which one was Slerp?) and it's really annoying I have to go online and google them in math sites.

However, it's an API reference, not a math book. The API reference should assume the reader has already basic knowledge of the theory behind it. We're just saying what the implementation does.

For example saying a Quaternion has 3 imaginary components and one real isn't helpful to a C++ programmer. That belongs to a math book.
Furthermore, we use Quaternions more as stripped down 3x3 matrices, rather as a "hypercomplex number". It's a way of thinking it. The former one is more practical and game oriented, while the latter is more theory and math oriented.

Edit: Doc changes checked in rev 2678. Not everything was included, I kept the "math primer" part away, but added a few links.

[Beauty]

All right, the Quaternion class description should not be overleaded.
My intention was to post some "content ideas" as template for a description. Just as a help that you don't have to search for yourself.

Thanks again dark_sylinc for adding descriptions.

[Beauty]

Related to Ogre::Quaternion::getYaw()

Description for param reprojectAxis:

By default the method returns the 'intuitive' result that is, if you projected the local Z of the quaternion onto the X and Z axes, the angle between them is returned.

I suppose there is a mistype: The bold marked local Z text should be changed to local Y.


By some tests I found out that the co-domain of the returned value of getYaw() is from -90° to 90°.
This should be mentioned in the method description, because some people could suppose the returned value has a co-domain of -180°..180° or 0°..360°.
So the co-domain note would be a useful hint for people who doesn't know.

Proposed addition for the description of getYaw():

The co-domain of the returned value is from -90 to 90 degrees.

My personal background:
In maritime navigation it usual to use a 360° co-domain for Yaw. So I was confused because of wrong calculation values, until I recognized that getYaw() returns only a 180° co-domain.


Also the co-domain for the other getAngle methods should be documentated:

Ogre::Quaternion::getPitch()
-180°..180°

Ogre::Quaternion::getRoll()
-180°..180°

[Beauty]

Next task.

Ogre::Node::_getDerivedOrientation()
Ogre::Node::_getDerivedPosition()
Ogre::Node::_getDerivedScale()

These methods have an underscore, because the call can cause much performance.
If would be good to add some remarks about this fact to the class reference.

1) Add: A warning, that it can cause more performance

2) Add: Details, what happens when calling _getDerivedXXX()
e.g. Will the whole scene graph be updated or only the scene nodes in the upper hierarchy (parents, grand parents, ...) ?


Details are published in this topic:
get/set WorldPosition/WorldOrientation/WorldScale

[Beauty]

I'm still dogged

Quaternion::Quaternion(rfAngle, rkAxis)

Add more detailed description would be useful for people which are not yet familiar with Quaternions.

Maybe this:

Construct a quaternion from an angle/axis.
The rotation will be applied for a given angle around a given axis.

Or this:

Construct a quaternion from an angle/axis.
For this the represented coordinate system will be rotated around a given axis for a given angle.

Proposal for parameter rkAxis:

Axis which is used as basis for rotation.

or

Rotate around this axis.

[Kojack]

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

[Zonder]

One thing that I think maybe good if all classes link through to a fixed wiki page so the comunity can document and ammend information for the class as a whole or give examples of usage.

But I do point out it's a community page not somthing the core team would be reguired to update

[spacegaier]

One thing that I think maybe good if all classes link through to a fixed wiki page so the comunity can document and ammend information for the class as a whole or give examples of usage.

But I do point out it's a community page not somthing the core team would be reguired to update

Like the idea. This could actually make sense and be beneficial in many cases.

[Zonder]

forgot to say in my post that I am thinking of what should be on a method (Simple developer explanation) and further information, the detaild information that beatuy provided on quaternions

[Beauty]

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

I wrote a nested loop which creates a SceneNode and set its Orientation (quaternion) to several rotation states.
For each state it reads the yaw/pitch/roll values.
As results it shows the minimum and maximum values, that were returned by yaw/pitch/roll.
This is the investigated co-domain.

Source code of my test, witten in C#:

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 = new Quaternion(new Degree(yaw), Vector3.UNIT_Y);
        SceneNode node = new SceneNode(Smgr);
        Console.WriteLine("Start calculation ...\n");
        Console.Write("Intermediate steps: ");

        for (yaw = -200; yaw <= 400; yaw++)
        {
            for (pitch = -200; pitch <= 200; pitch++)
            {
                for (roll = -200; roll <= 200; roll++)
                {
                    node.Orientation = new Quaternion(new Degree(yaw), Vector3.UNIT_Y);
                    node.Pitch(new Degree(pitch), Node.TransformSpace.TS_LOCAL);
                    node.Roll(new Degree(roll), Node.TransformSpace.TS_LOCAL);
                    quat = node.Orientation;

                    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));

Result:

Yaw -90 .. 90
Pitch -180 .. 180
Roll -180 .. 180

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

No case of my test loop returned a Yaw value below -90 or above 90 degree.

Or is there a mistake in my test loop?

[Beauty]

I made some more experiments with my test loop.
So I found a nice example case:

When I set the orientation of a SceneNode to yaw = 120 degree by
node.Orientation = new Quaternion(new Degree(120), Vector3.UNIT_Y);
and read the orientation values, then I get this result:
Yaw = 60
Pitch = 180
Roll = 180

[Beauty]

Code: Select all

/** Performs Spherical linear interpolation between two quaternions, and returns the result.
Slerp ( 0.0f, A, B ) = A
Slerp ( 1.0f, A, B ) = B
@remarks:
Slerp has the proprieties of performing the interpolation at constant velocity, and being torque-minimal (unless shortestPath=false). However, it's NOT commutative, which means Slerp ( 0.75f, A, B ) != Slerp ( 0.25f, B, A ); therefore be careful if your code relies in the order of the operands. This is specially important in IK animation.
*/

/** Performs Normalised linear interpolation between two quaternions, and returns the result.
nlerp ( 0.0f, A, B ) = A
nlerp ( 1.0f, A, B ) = B
@remarks:
Nlerp is faster than Slerp.
Nlerp has the proprieties of being commutative (@See Slerp; commutativity is desired in certain places, like IK animation), and being torque-minimal (unless shortestPath=false). However, it's performing the interpolation at non-constant velocity; sometimes this is desired, sometimes it is not. Having a non-constant velocity can produce a more natural rotation feeling without the need of tweaking the weights; however if your scene relies on the timing of the rotation or assumes it will point at a specific angle at a specific weight value, Slerp is a better choice.

//FromAngleAxis:
/** Setups the quaternion using the supplied vector, and "roll" around that vector by the specified radians. */

FromAxes
/** Constructs the quaternion using 3 axes, the axes are assumed to be orthonormal */

ToAxes
/** Gets the 3 orthonormal axes defining the quaternion */

xAxis
/** Returns the X orthonormal axis defining the quaternion Same as doing xAxis = Vector3::UNIT_X * this
Also called the local X-axis
 */

yAxis
/** Returns the Y orthonormal axis defining the quaternion. Same as doing yAxis = Vector3::UNIT_Y * this
Also called the local Y-axis
*/

zAxis
/** Returns the Z orthonormal axis defining the quaternion.  Same as doing zAxis = Vector3::UNIT_Z * this
Also called the local Z-axis
*/

Is this good for you?
If so, I'll check it in this weekend

Doc changes checked in rev 2678. Not everything was included, I kept the "math primer" part away, but added a few links.

Today I read in the Mogre forum, that (again) somebody has problems with orientation, etc.
Now I recognized, that there is still a lack of information in the Ogre Class Reference.

dark_sylinc, did you commit your posted descriptions?
If not, please do it.
If you did, then the online documentation needs an update.

Also slerp, nlerp, etc. still have no description.
A half year ago I made several suggestions (in this topic). You just need to copy and paste them to the Ogre source code. (OK, you also need to add description tags and update the online version of the documentation.)
I would be happy when somebody do the job.
Undocumented (common used?) methods of Ogre are not very nice, especially for 3D newcomers.

[Beauty]

There was no reply to the co-domain inconsistency.
For this I created a new topic in the common Ogre section:
http://www.ogre3d.org/forums/viewtopic.php?f=1&t=66030

UPDATE
Problem was found:
The Mogre wrapper uses System.Math (.NET) instead of Ogre.Math for some calculations. For example arcus sinus of the Ogre method has different results for some special cases. This caused other co-domains.

[Beauty]

I want to remind that there are still some undocumented (and less documented) API descriptions.
It would be nice to solve the gaps.


Here are more tasks for the Math class:

* static Real Sqr (Real fValue)
It means "squared" x^2, but if the user isn't shure, it would be useful if he can read it in the API description.
Description: Squared function (fValue^2)

* static Radian Sqrt (const Radian &fValue)
* static Degree Sqrt (const Degree &fValue)
Description: Square root function

* static Real Sqrt (Real fValue)
It should be documented of the parameter will be processed as Radian or Degree.


* static Real Ceil (Real fValue)
Ceil function. Returns the smallest following integer. (example: Ceil(1.1) = 2)

* static Real Floor (Real fValue)
Floor function. Returns the largest previous integer. (example: Ceil(1.9) = 1)


Some more information would be useful:
* static Real UnitRandom ()
* static Real RangeRandom (Real fLow, Real fHigh)
* static Real SymmetricRandom ()

[Beauty]

I found a strange description for Ogre::Renderable::getRenderSystemData()

Its description is:

Sets render system private data.

Why the function name starts with "get" and the description says "set"?
If the description is wrong (means get instead of set), it would be nice if somebody update the API description.

[Beauty]

Ogre::AnimationState::addTime(Real offset ) (Link)
The description is:

Modifies the time position, adjusting for animation length.

Remarks:
This method loops at the edges if animation looping is enabled.

This description should explain which kind of time value is needed for offset.
Seconds? Milliseconds? ... I don't know. Also others could miss this important information.




The same for the constructor Ogre::AnimationState::AnimationState() (Link)
Its description is just:

Normal constructor with all params supplied.

At least for parameter timePos there should be a note about the used time value.
A description for parameter weight would be useful, too.

[Beauty]

Today I looked to the documentation again.
I'm very sad so see that after almost one year it seems so that the proposed documentation wasn't added to the Ogre code.
(At least I don't see changes in the online documentation for some members which I linked from here.)

It would be just copy and past.
And it wold be so useful ...


Also for these members a documentation is needed:

Quaternion.FromRotationMatrix (const Matrix3 &kRot) . . . . (here)
Quaternion.ToRotationMatrix (Matrix3 &kRot) . . . . (here)
Quaternion.FromAngleAxis (const Radian &rfAngle, const Vector3 &rkAxis) . . . . (here)
Quaternion.ToAngleAxis (Radian &rfAngle, Vector3 &rkAxis) . . . . (here)
Quaternion.ToAngleAxis (Degree &dAngle, Vector3 &rkAxis) . . . . (here)

Quaternion.FromAxes (const Vector3 *akAxis) . . . . . (here)
Quaternion.FromAxes (const Vector3 &xAxis, const Vector3 &yAxis, const Vector3 &zAxis) . . . . . (here)
Quaternion.ToAxes (Vector3 *akAxis) . . . . . (here)
Quaternion.ToAxes (Vector3 &xAxis, Vector3 &yAxis, Vector3 &zAxis) . . . . . (here)

Quaternion.Dot (const Quaternion &rkQ)
... Is this dot product?

Quaternion.Norm ()
... What's the difference to Quaternion.normalise() ??

Quaternion.Inverse ()
Quaternion.UnitInverse ()
Quaternion.Exp ()
Quaternion.Log ()

[Beauty]

All class members of Matrix3 have no description.
(The only exception are the class and constructor.)

http://www.ogre3d.org/docs/api/html/cla ... trix3.html

[masterfalcon]

I'm on it, sorry that it hasn't been addressed yet. And thanks for all your hard work!