Ogre 2.1 documentation effort

Discussion area about developing with Ogre-Next (2.1, 2.2 and beyond)


Post Reply
zvd2
Gnoblar
Posts: 15
Joined: Mon Jun 25, 2018 7:05 pm
x 3

Ogre 2.1 documentation effort

Post by zvd2 »

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.
Slicky
Bronze Sponsor
Bronze Sponsor
Posts: 614
Joined: Mon Apr 14, 2003 11:48 pm
Location: Was LA now France
x 25

Re: Ogre 2.1 documentation effort

Post by Slicky »

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.
zvd2
Gnoblar
Posts: 15
Joined: Mon Jun 25, 2018 7:05 pm
x 3

Re: Ogre 2.1 documentation effort

Post by zvd2 »

I was planning to put this along with the doxygen API, actually. I wasn't really planning on updating the wiki.
zvd2
Gnoblar
Posts: 15
Joined: Mon Jun 25, 2018 7:05 pm
x 3

Re: Ogre 2.1 documentation effort

Post by zvd2 »

I forgot to ask: When does a Resource need to be touched?
User avatar
Zonder
Ogre Magi
Posts: 1168
Joined: Mon Aug 04, 2008 7:51 pm
Location: Manchester - England
x 73

Re: Ogre 2.1 documentation effort

Post by Zonder »

Yeah doxygen would be better.
There are 10 types of people in the world: Those who understand binary, and those who don't...
User avatar
dark_sylinc
OGRE Team Member
OGRE Team Member
Posts: 5296
Joined: Sat Jul 21, 2007 4:55 pm
Location: Buenos Aires, Argentina
x 1278
Contact:

Re: Ogre 2.1 documentation effort

Post by dark_sylinc »

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
zvd2
Gnoblar
Posts: 15
Joined: Mon Jun 25, 2018 7:05 pm
x 3

Re: Ogre 2.1 documentation effort

Post by zvd2 »

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.
Slicky
Bronze Sponsor
Bronze Sponsor
Posts: 614
Joined: Mon Apr 14, 2003 11:48 pm
Location: Was LA now France
x 25

Re: Ogre 2.1 documentation effort

Post by Slicky »

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