The papercuts initiative

Minor issues with the Ogre API that can be trivial to fix
OGRE Retired Team Member
OGRE Retired Team Member
Posts: 2903
Joined: Thu Jan 18, 2007 2:48 pm
x 57

The papercuts initiative

Post by CABAListic »

Hey everyone.

A while ago I needed to destroy a RenderWindow I had previously created via Root::createRenderWindow, and it is at that point that I noticed that there is no corresponding Root::destroyRenderWindow function. This left me puzzled for a moment until I looked into the Ogre codebase and found that I could detach the RenderTarget and then manually delete it. For reasons of consistency and ease of use there should be a destroyRenderWindow function which does exactly that. It's a simple fix.
But did I add that function? No. Because it's such a minor issue, it was out of my mind the instant that I found the correct workaround and I was back to my actual project. As a consequence this minor annoyance still exists.

Now, I'm sure many of you have found similar minor issues in your daily use of Ogre; given a sufficiently complex codebase this is basically unavoidable. But today I'm proposing to you a small experiment: The next time you encounter (or remember) an inconsistency / quirk / annoyance in the Ogre API, we want you to file a bug report in our bugtracker. This will only take a minute of your time, and then it's off your mind but documented. That way it won't get lost again, and we will actively try to remove as many of those small annoyances as we can.

In a shameless ripoff from the Ubuntu project :) we are going to call any such annoyance a papercut. A papercut is any little obstacle that you encountered when using the Ogre API - this can be a missing function that you would have expected (like the Root::destroyRenderWindow), a misleading function documentation or really anything else that wasn't as you would have expected. For example, did you notice how the Vector classes have a dotProduct function, but the same functionality is named Dot for the Quaternion class? A papercut should be trivial to fix and not prevent you from doing what you need to do (i.e. a papercut is not a showstopper).
If you found something that you think qualifies as a papercut, please file a report in our bugtracker, whereby you should prefix the title of the report with "[Papercut]" so that we can easily spot them.
Some changes (like the mentioned inconsistency between Quaternion and Vector) may warrant a discussion by the community about what is the desired change. For this purpose we have created a special forum - whenever you find that a reported papercut warrants a discussion, please open a thread in that forum.

Please note that the initiative is targeted at the Ogre Byatis 1.8 release. Although we may decide to apply some fixes to the stable branch if appropriate, the focus lies on the unstable branch. As such interface breaking changes are fine if they make sense.

Thank you all for your participation. Let's iron out some rough edges from the Ogre :)