Inertia's picture

Table of Contents / Chapter Layout

Quote from the original news post: http://opentk.sourceforge.net/home/news/manual_concept

Table of Contents:

1. Installation
[Linux, Windows, compilation instructions, starting a new project]
2. A Simple Introduction
[creating a window, drawing shapes, resizing the window, user input]
3. Warming up
[common game-related tasks like framerate independence, text rendering, mode setting, projections/math, loading resources, playing sounds]
4. Putting it all Together
[show how to create a simple game, e.g. 3d pong or something of that calibre]
5. Advanced Topics
[managed/unmanaged resource pools, interop performance, the GC, scripting on .Net]
6. Advanced OpenGL
7. Advanced OpenAL
8. References


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
Inertia's picture

a different layout, as something to compare against.

1. Getting started
1.1 Overview (about OpenTK Core and Utilities, should give a clear idea what can and cannot be achieved)
1.1.1 Introducing the OpenTK Classes
1.1.2 Screenshot Gallery of existing OpenTK projects.
1.2 Installation and Compilation(mention good IDEs and how to add OpenTK.dll to GAC for each OS. Should get the user to the point where (s)he can compile and run code on any machine)
1.2.1 Linux
1.2.2 MacOS
1.2.3 Windows
1.2.4 Solaris
1.3 Getting Started
1.3.1 Starting a new Project
1.3.2 Quickstart Templates
1.3.3 links for further reading in the book

2. OpenTK Classes
2.1 OpenTK.Input (should make clear how to query and interpret the input devices)
2.2 OpenTK.Math (should make clear for what tasks the types can be used, rather than a full vector math explanation)
2.3 Rendering Context (creation, differences etc)
2.4 OpenTK.Fonts & Timing (Show how to print static text, show how to make a Frame/Sec counter)
2.5 OpenTK.OpenGL (setting up a window, Geometry, Shaders, States, Textures, Viewing etc.)
2.6 OpenTK.OpenAL (device enumeration, context creation, State, Listener, Sources, Buffers etc.)

3. Advanced Topics
3.1 Advanced C# (performance information specific to managed code, GC, pinning, handling pointers & Co)
3.2 Advanced OpenGL (popular Scenegraphs, Deferred Rendering, approximating Global Illumination etc.)
3.3 Advanced OpenAL (using EAX extensions, examine the scene and set proper reflection/occlusion for sources etc.)
3.4 GLSL

4. Putting it all Together into a simple app/game
4.1 Example A (contains many sub-pages)
4.2 Example B

5. References
5.1 Function Reference
5.2 Glossary
5.3 recommended books/webpages to read etc.

The idea is to deal with all kinds of C# beginner issues in chapter 1. No actual programming examples there except the template.
Most important is the thin line between chapter 2 and 3. Where do advanced topics start? Chapter 2 should imho stay clear of all optimization hints and just explain techniques, with as little subjective comments as possible. Chapter 3 would be rather abstract and heavily link into Chapter 2, and will focus on tradeoffs between techniques.
Chapter 4 assumes the user has read chapter 1&2.
Chapter 5 will be largely static and is more likely referenced by the other chapters.

Now is the point of time where it's no problem to change the book's layout. Please comment on either of the suggestions or make your own suggestions. Are there topics missing? Which of the chapters is your main interest in? How about GL2 vs. GL3? How do you want to see external references handled (printed Books, .PDF, whitepapers, websites)?
Thank you.

objarni's picture

My

My first-read-through-reaction to the layouts suggested:

I get a feeling Inertia's layout is easier to follow / understand / maintain than the first layout suggested.

But the name "advanced topics" is bound to create confusion. What is advanced to one person is not advanced to the next, and vice versa. Some alternative expressions and my own reaction to them:

- Performance issues (too specific)
- Pragmatic issues (too general)
- Hints and techniques (ok?)
- Tips and tricks (ok?)

Inertia's picture

What is advanced to one person is not advanced to the next, and vice versa.
Indeed, this is a tricky one. My assumption was that going through Chapter 2 will elevate the reader to Intermediate level, which is _expected_ as the very minimum for grasping the topics in Chapter 3. Actually the topics dealt with in Chapter 3 don't necessarily require OpenTK, but discuss techniques in an abstract way (basically apply for all OpenGL/AL apps).
Maybe "efficiency" would be a better keyword, since none of the topics in Chapter 3 should be required to write an OpenTK app.

Regarding the naming of the chapters, please note that english isn't my native language and I'm open for corrections/suggestions.

the Fiddler.'s picture

Good call. This outline looks cleaner and better laid out.

Chapter 2 and 3
Well the distinction between basic and advanced topics is more or less arbitrary. Is the programmable pipeline an advanced topic? GL3 won't have a fixed function pipeline anymore, so vertex/fragment shaders become the most basic building blocks, and the same holds for VBO's (vs immediate mode or vertex arrays). No clear-cut answers here. Probably best to treat low-level functionality as basic knowledge, and have the advanced chapter build on that (e.g. vs/fs == basic knowledge, parallax or anisotropic lighting effects == advanced). Advanced topics should be more general in nature (and probably more math-involved), and should also touch on performance implications. Chapter 3.1 would contain performance information specific to managed code.

Are there topics missing?
A few notes on fonts and timing would be nice (Chapter 2). Platform integration might also merit it's own space, outside of OpenTK.OpenGL that is, as there are already four methods to create windows/contexts (GameWindow, GLControl, WPF/GLControl, GLContext) and more will come in the future.

It would also be nice to think up a more concrete topic for the example/demo applications. Darxus mentioned he was working on an Arkanoid game, which might be a good candidate. Do you have any other ideas?

Inertia's picture

Updated the earlier post with the missing topics. I've stuffed timing and fonts together, since a frame/sec counter would be a good example to combine both, and both topics are rather small. A second example could be a triangle in the back of the fps counter rotate frame-rate independent.
...or to what extend should timers be covered? I'd say this is pretty much covered in MSDN.

[distinction between basic and advanced]
actually GLSL is such a big topic that it might deserve it's own primary chapter or skipping the topic largely and point users towards a good book on shaders. "GLSL Tutorial" probably belongs into the same problem category as "3D Math Tutorial". I'd like to have both in the OpenTK book, but the complexity of both topics is large enough to fill their own books.

[demo app]
Added a gallery to chapter 1. This could showcase anything from examples to final apps and would support "Overview" by showing examples. Some pretty pictures early in the lecture might be a good morale boost for the reader too.

Pool Billard. Everyone knows that. Maybe 9-Ball for a convenient single-player mode for testing.

the Fiddler.'s picture

[fonts & timers]
There's actually more to timing than meets the eye, but the more juicy bits are probably an advanced topic. Bundling with fonts is fine as an introduction though.

[GLSL]
We should cover how to load and compile shaders with OpenTK, and show a few practical examples (GLSL variables and data types, simple vertex animation, vertex lighting, pixel lighting, maybe some color keying and toon effects thrown in for good measure - ports of the Lighthouse3dmostly). I think this would be time better spent than showing yet again how to use fixed function lighting, especially this late in the GL2 timeline. These will never be a replacement for a good book (the Orange book or something else), but would definitely help a new user get on his feet.

[Applications]
I really like the Project section suggestion, I'll see what can be done (Sourceforge being the limiting factor here).

Any other suggestions regarding the manual?

Edit: (missed that point)
[Demo]
Billard! Simple physics (unless you start modelling friction coefficients and ball deformation on impact ;) ), has the potential for eye candy, is more complicated than another boring pong clone but not so large as to be infeasible.

My first idea was something like a 2-player split-screen deathmatch in the spirit of good old Starfox. Some simple heightmapped terrain, two aeroplanes, maybe some powerups and a radar for the polish, but with an eye for simplicity.

Edit 2 and slightly offtopic:
Any other usability suggestions for this site (in regards to the manual but not only)? I'm slowly adding permissions to facilitate page editing (inline images, some common html tags, edit/deletion permissions), but there are probably things I haven't thought of.

Inertia's picture

[fonts & timers]
Exactly. Chapter 3 is a good candidate for in-depth topics.

[GLSL]
The compiling should definitely be placed in C2. Maybe it's best to make a separate Chapter in C3 for GLSL, and just let it evolve from there. This kind of documentation is a long-term project anyway. I'm just trying to figure out the scope of the book (will there also be Chapters regarding OOP-, game-, content-design, deployment, etc?)

[Demo]
One doesn't exclude the other.
A single-player game (that the reader could extend to 2-player mode or snooker) like 9-Ball would also allow for easy testing. The physics bit could be simplified into 2D and the required amount of content is low.

[slightly offtopic]
Mhmmm the bar on the left side is just containing duplicate functions, maybe move the search box (and last forum topics) somewhere to the right and free that space on the left side. I've seen there are settings for this in my profile, but they had no effect. This would focus all navigation to the top and right sides and make better use of horizontal space available.
I don't want to p*ss you off by asking a 1000 things at once tho, you asked :P

the Fiddler's picture

[slightly offtopic]
I'm no webmaster, all comments welcome :)

[blocks on the left side]
You can hide them from your account settings now. Used to work till about two weeks ago when I added caching, fixed now.

I agree that removing the left bar would look cleaner. I'm working on a new lighter theme (this one is quite css heavy), should be ready quite soon.

Inertia's picture

Thanks, much less scrolling now almost like an IDE :>

Back to topic:
As a reference how the GL bit of Chapter 3 could look like topic-wise: http://www.delphi3d.net/articles.php
He deals with the topics in the abstract way I had in mind, show figures/images to support the idea but no actual implementation. If C2 is more like the Nehe-tutorials, we also have a clear distinction between basic and advanced topics: Advanced = abstract, Basic = straightforward implementation

objarni's picture

Hmm. I would like simple explanations of the differences between GameWindow, GLControl or any other "fundamental method" of using OpenTK. Maybe I've missed it in the TOC, I think it should be Ch1 or Ch2.

Aha found it. It's baked into chapter 2, section 3: Rendering contexts. Maybe then:

2.3 Rendering contexts
2.3.1 Overview & considerations (Fullscreen game? Windowed viewer?)
2.3.2 GameWindow
2.3.3 GLControl

Things like when to use SwapBuffers and when not to is especially interesting here. A super-minimal example in each section, "Hello world" or something, could be beneficial.