Inertia's picture

Chapter 2 - OpenGL

I've started creating some pages in the Book, basically the Chapter 2 - OpenGL - Geometry. Topics are covered where I believe they will still be valid in GL3 and only require changing a few enums. Some topics are incomplete, as in placeholders.

http://opentk.sourceforge.net/home/?q=node/141

Honest Changes/Additions/Feedback are welcome, but I think it'd be best if you correct spelling mistakes directly in the book, and also if you feel a line is missing, feel free to add to the page. I know there's too many commata and probably quite some upper cases letters are wrong. Please do correct that if english is your native language, Thanks!

I've tried to follow Fiddlers guidelines: The reader is assumed to have an intermediate understanding of C# (IntPtr, Structs and Arrays in that specific case) but no understanding of OpenGL. I'm assuming some fantasy to imagine points in space though. If the pages are read in incremential order, they should give all necessary information to draw a Mesh without touching any Textures or Shaders. Geometry is supposed to be the 3rd Chapter of OpenGL, where window/viewing/orientation related topics are covered in the first Chapter and State related things like Stencil/Scissor etc. in Chapter 2.

Some questions though:
-How should the reader be adressed? "you" or "we"?
-Are there any major logic errors contained? Some of this was ported from Tao and may still include something overlooked.
-Did I miss anything major? This is always difficult to judge when being the Author of something, because for you it all makes sense ;) The people I asked to proofread neither have english as native language nor any concept of C#, so the only useful feedback so far was regarding the Geometric Primitives Image ><
-How far are my personal opinions acceptable in the text? I do have my preferences and couldn't resist writing them down, if someone really is new to something it is always helps to have an opinion to judge against. It'd be np with me to reduce my comments, for the sake of keeping the pages more in MSDN style. Just say so, or edit as you see fit.
-Consider this my X-Mas gift to the OpenTK team :o)


Comments

Comment viewing options

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

Nice work! Documentation is a very important part of a library/API/SDK, especially in the long run. (one could see the documentation of a project as the 'contract' and as such should be one of the first parts to be 'developed', and be 'developed' continously as the library evolves..)

-How should the reader be adressed? "you" or "we"?
The red book uses 'you'. I think that is ok if you are writing a 'guide' or 'howto', that is 'a little less formal'.
But if you can, avoid it altogether. For example see opengl's ref.pages here: http://opengl.org/sdk/docs/man/

Anyway, my favorite manual all-time is allegro.txt (available online at http://www.allegro.cc/manual/). It is written at the 'right level' I believe - both appropriately detailed, high level enough and in an easy to understand language.

the Fiddler.'s picture

Out of jail at last :) Thanks for the articles, that's quite a lot of stuff! I've skimmed through them, no logic errors I can think of, good work.

-How should the reader be adressed? "you" or "we"?
Between the two, I think 'you' sounds better.

-How far are my personal opinions acceptable in the text?
Perfectly acceptable. Even better if they are backed up by facts :)

I agree with objarni about the allegro manual, it really is one of the best of its kind. It covers both specific programming tasks (timing, input, sound etc) and more general ideas (buffering, dirty rectangles etc), and is really well-written and understandable.

I'll try to proofread the articles, but I don't think I have time for anything else right now :/

Inertia's picture

Thanks for the reply, I was getting worried that it's catastrophic and you don't know how to tell me without p*ssing me off :P

Between the two, I think 'you' sounds better.
Is that a "make it so." or just your personal preference? It's no biggie changing this, just would like to have this consistent throughout the Articles.

allegro manual
That separation is included into the OpenTK manual's layout too. What I really like about the allego manual is that forum topics/links are listed below, so you have some links to follow if you wish to learn more about the topic (I've started adding this into the OpenTK articles too)

I'll try to proofread the articles
Hint: Print them, rather than reading online. It helped me find alot of spelling errors (I don't think there's any left now). What I'm looking for the most is suggestions/additions what is missing in the topics. I tried to keep them compact and focused, but it's always a different thing teaching how something works as opposed to knowing how something works.

the Fiddler.'s picture

[you vs we]
Just a personal preference. Material is more important than style at this point in time :)

Inertia's picture

I believe sources/links should be included wherever possible, just like wikipedia does. For example the page about vertex cache optimizations will not include a tutorial, but rather links to research papers and a sample implementation. Since it is the end of the Geometry chapter it gives some more things to research if there's interest.

the Fiddler.'s picture

Yeah, that's a very good idea, cover the basic idea here and link to further resources.

Inertia's picture

This will also keep the book achievable in a sane timeframe. However it will be inevitable that you write the bits about GLControl&contexts&C#, rather than answering the questions in the forums over and over again (this is also why I started with the chapter Geometry, several people had troubles getting started. Now you can forward them to the book. One other thing would be good for the book is with Shaders, people had troubles with the null-terminated strings. This is the kind of thing should be dealt with in the Shader chapter, not what gl_Vertex is.

objarni's picture

Yeah I agree with Inertia here; it is natural for the Fiddler/StApostol to write the "mental model guides" -- what his design ideas/thoughts are about GLControl/GameWindow. In my experience, GameWindow is much simpler and maybe should be explained first. GLControl has lots of "gotchas" that I've stumbled upon -- things that differ from how you think when you design a main-loop-c-ish-game using for example SDL/C/OpenGL.

my 2 cc..

the Fiddler.'s picture

You are right. With the site out of the way, I can finally devote some time on documentation/examples to exlpain the logic behind each available class. Regarding GameWindow/GLControl for example, the idea is that GameWindow follows the main-loop-c-ish-game paradigm (with C# events for usability), while GLControl is purely event driven and more suitable for GUI's rather than games.

Inertia's picture

Don't get my last post wrong, this wasn't a request. Just a statement that I think those topics are best dealt with by you, because it's your design.

Things like hooking the KeyDown event is something one can easily figure out by looking at the source code (basically what I was missing was the information what parameters a function added to the event accepts. I'm using it now rather than the helper in Torusknots, but it wasn't obvious when I touched the input class first), but the classes which provide contexts really require an overview.