Ogre Forums

General thread about documentation efforts for 2.1.

I've been working on a quick reference page which shows the most important parts of the API on one page. It's not quite done yet but here is what I have so far:
https://pastebin.com/ndLP224Y (doxygen source)
https://pastebin.com/3qppnF9y (html)

After looking through the API for this I've got a few questions:
Why is getSkeletonInstance part of MovableObject? Only Item seems to have a skeleton.
Is setEnabled the main way to play a skeletal animation?
v1::Animation doesn't seem to work with the current classes. Is there anything else that can be used to interpolate SceneNodes or should users do this themselves?

I'd like it if you could look through what I've got and let me know if anything important is missing or if any description is wrong. Especially for HlmsMacroblock I had to guess what a few things did and I haven't really taken the time to test anything.

Beyond the quick reference page I'm also planning to do the following documentation work:
- A page that succinctly details the start-up procedure and how to do the things the configuration files are used for yourself.
- A page on how to use Ogre within Qt.
- Reference pages for all scripts: .material.json, compute jobs, shaders
- A page that succinctly explains how to upload a mesh.
- A page that explains how to do various decal techniques.
- Change the version name in doxygen from 2.1.0unstable to something else.
- Maybe pages for all the various features in the samples. Alternatively direct people to the sample source code.
- Maybe remove the logo, I'm honestly not a huge fan of the graphic design.
If someone else would like to do one of these, I'm fully open to not having to do work myself.

Nicely done. I'm not sure how people get access to edit the wiki (used to be user login) but it might be useful if you could get access.

I was planning to put this along with the doxygen API, actually. I wasn't really planning on updating the wiki.

I forgot to ask: When does a Resource need to be touched?

Yeah doxygen would be better.

zvd2 wrote: ↑Wed Sep 12, 2018 6:07 pmWhy is getSkeletonInstance part of MovableObject? Only Item seems to have a skeleton.

"Performance reasons" is the answer.
The OOP (Object Oriented Programming) way would be to use a virtual function which does nothing in the base class, and Item overrides it.
Ogre 1.x did this in Renderable::getWorldTransforms and Renderable::getNumWorldTransforms (these functions are still kept in 2.1 for some legacy paths), in which most Renderable implementations would only write one world matrix, but those with skeletons would write multiple world matrices (one per bone).

While this is "clean" and "OOP", it's also terribly inefficient because we have one/two virtual calls per submesh to render on screen, for all instances, not just those with skeleton animations. This is really a critical place.

Since Skeleton animations are such an important feature in a rendering engine, it was best to just have add a pointer to all MovableObjects (most of them will be Items anyway) and have nullptrs on them if Skeletons are not used.

zvd2 wrote: ↑Wed Sep 12, 2018 6:07 pmIs setEnabled the main way to play a skeletal animation?

Yes

v1::Animation doesn't seem to work with the current classes. Is there anything else that can be used to interpolate SceneNodes or should users do this themselves?

Mmm... I don't remember. IIRC v1::NodeAnimationTrack still works on regular SceneNodes, but I could be wrong.

Cheers
Matias

In case anyone is interested, the pull request for the quick reference and sdl guide have been up since last week:
https://bitbucket.org/sinbad/ogre/pull-requests/837
I'm not sure when mr. Goldberg will merge it, but you can read it from the diff just fine, albeit without hyperlinks.

Thanks for this. I can use any help I can get to better understand 2.1.