Examples & demos
- "test" applications are *not* documentation. Users should not have to use "grep -r" to find documentations tests.
- Examples, demos, and tutorials are key to the sucess of OpenSG. Examples show what OpenSG can do. Demos show off OpenSG. Tutorials allow other people to learn OpenSG.
- We need good examples and demos to show off the capabilities of OpenSG. We should *never* be in the position where we have a new feature and can't demonstrate it to someone easily.
- Start collecting tests & make them into small examples.
- Get examples into or cross-referenced from documentation
- Create example directory off of base directory. This is the location for all application examples.
- When a new feature is added, add an example. No more "tests" that show how to use things. There should be examples for everything.
- Get rid of "test" examples entirely. Tests should only be unit-test or very low-level tests. Everything else should be an example.
- Examples & demos would then serve as larger 'system'-tests. Make sure they also work before posting new nightlybuilds.
- See also marketing / demos.
The examples don't need fully documented (like a tutorial), but they should have some basic documentation that says what they are demonstrating and standard inline documentation about the calls they are making.
What is an example, tutorial, and demo
Relatively short program showing how to use a capability. An example should be *real* and not just some contrived system. As much as possible an example should be usable to show how a new capability or feature works and should be useful as a small demonstration. Examples should be built as part of the standard build to make sure they keep working and that the code interfaces have not broken. They can be considered as an extension of the unittests and should be used by developers to test and refine capabilities as they add new features.
It would be good if examples could be included in the documentation, either inside the docs for the class they demonstrate or at least linked from them. --DR
I like the idea of linking. I have tried to use inclusion before and it is more pain with doxygen then it is worth. Linking to an example that is syntax highlighted and has links back to the relevant classes seems to work well for me. Also, the example should have basic documentation to describe what it is doing. -AB
A full blown singing and dancing extravaganza. Think of something like the nvidia or ATI technology demos that show off the capabilities of a card. These will most likely contain many files and are meant for showing off OpenSG to potential users and at trade shows.
I like the ATI ones better, as they show off the technology and how things are done more than just the wow. They also have some simple UI. The main thing with demos is getting good test data, that is the real difference between an example and a demo. --DR
An application designed to help new users learn the OpenSG APIs. These applications will be documented thoroughly as a walk through with comments to hand-hold users to learn OpenSG.
Nitpick: Current tutorials/tests often have a huge init-function. I think they could benefit from being split into logical steps such as 'setupThis()' and 'setupThat()' and 'constructThingy()'. /ML
Agreed. Make the tutorials logical and organized. Maybe even reuse code. -AB
What directory structure to use?
- Source - Base - System - WindowSystem - Examples - Culling - ParDraw - Tutorials - 01_loading.cpp, 02_transform.cpp - Demos - DancingCow - MarketingKitchenSink
I would put the examples in the root, too. Otherwise they're too hard to find. --DR
There is one problem with this. If we put them in root they are hard to build in the build dir as part of the standard build. I almost think we need to restructure the 'Source' directory into 'libs','tests','examples' or something similar. -AB
How to build the apps
Built as part of standard build in build directories using SCons. Provide flag to disable if needed.
Standalone build using osg-config against inst-links.
Use standalone build (probably scons) that uses osg-config to find options for OpenSG.
All of these go into dists. Maybe split into code and data, to keep sizes smaller and prevent having to download the data over and over.