Tutorials Wishlist

Posted Thursday, 28 February, 2008 - 19:06 by Inertia in

This is a gathering topic for recommendations/requests/contributions of OpenTK Tutorials that should be added. Please keep this sane (noone will port Quake III's source code for a tutorial) and be verbose what the tutorial should achieve, i.e. with that knowledge the reader should end up with after reading the source code.

There's no limit how small or big the tutorial should be, but some things need to be part of a larger tutorial (e.g. load a texture and draw a textured quad - makes little sense separated)

Also note that the tutorials on this list will not necessarily be finished tomorrow, it's more a list of feedback from users to get an idea what is missing and which areas require improvements. Posts like "I second [name]'s suggestion" are very welcome too, as this helps to set priorities! Thank you :)

Free your mind ...

Edit: this topic isn't much for discussion of the suggestion's details, so don't be confused if you get no reply. All suggestions will be read and considered.

Don't be afraid to add wishes that might sound trivial or stupid, the tutorials are supposed to help beginners get a good start with OpenTK and without you voicing the problems there cannot be done anything about this.

‹ Simple FBO render to texture German Translation ›

Comments

Feb 28
 20:45:25
Re: Tutorials Wishlist
posted by Mincus

Running through a simple game with a tutorials for each part might be a big help.
Wouldn't have to be anything complicated. Something like a pong clone.
For example:
Tutorial 1: 3 coloured rectangles (2 bats, 1 ball) on the screen, no movement, just general "set up and draw" tutorial.
Tutorial 2: Input example, one bat controlled by keyboard, one by mouse. Have the ball moving as well, so basic collision detection.
Tutorial 3: Add textures.
Tutorial 4: Add scores (text/font tutorial).
Tutorial 5: Add sounds for the ball bouncing, maybe losing and possibly music to demonstrate both WAV and OGG loading.

Possibly it could move 3D and maybe move closer to an "air hockey" table at some point.

For VBOs a possible particle generation example might work.

That's a start anyway. I understand that would be a lot of work, but I think the basic idea of adding bits to a simple game is sound.

Feb 29
 16:26:38
Re: Tutorials Wishlist
posted by objarni

I think the build-a-simple-game idea is great!

3d-pong is also a good idea. Or missile attack (cannon protects city from falling bombs/missiles).

I think it is a good idea to keep such a tutorial to the GameWindow style of OpenTK usage, since it is simpler to use than GLControl IMHO.

Basically, to build such a game, you would need the following "mini tutorials":

1. How to initialize / shutdown a GameWindow in OpenTK
2. How to read keyboard input
3. How to read mouse input
4. How to clear screen / swap buffers / draw colored triangles
5. How to generate sound samples and play them

Notice no files apart from OpenTK.dll is needed by any of 1-5. This is good since it saves the beginner lots of hassle.

After the "mini tutorials" have been read through, you might be ready for "3d pong":

6. Building 3d pong

After that, more intricate topics like texturing, WAVs, ogg, performance etcetera things might be added. I think 1-6 will get very many started with OpenTK development!

I don't think physics/modelling/collision detection/design patterns/performance should be adressed by the "basic game tutorial". That's why Pong is the best bet since it is so simple nothing fancy need to be done.

Feb 29
 16:38:39
Re: Tutorials Wishlist
posted by objarni

Here is my previous wish list:

1) Simple VBO usage (two-three triangles are perfect; more and it becomes unecessarily complex)
2) Loading WAV / other supported formats (don't know which are supported)
3) Loading and displaying an image over the screen
4) Displaying Hello World and responding to any key (exits)
5) Using Mouse (moving triangle or something)
6) Going into / out of Fullscreen

Mar 06
 13:13:08
Re: Tutorials Wishlist
posted by Stevo14

@objarni

As far as I know, number 2 will be really easy. Something like this:

uint bufferID;
uint sourceID;
AL.GenBuffers(out bufferID);
AL.GenSources(out sourceID);

WaveSound FooSound = new WaveSound("Foo.wav");
FooSound.WriteToBuffer(bufferID);
AL.BindBufferToSource(sourceID, bufferID);
AL.SourcePlay(sourceID);

A total of 8 lines of code (including declarations).

Mar 06
 16:34:34
Re: Tutorials Wishlist
posted by objarni

Inertia: how likely are Stevo14's example of being OpenTK's official way of playing a .WAV? The reason I'm asking, is because I might spend some time trying/putting this example up among the tutorials of opentk.net then.. (or Steve14 maybe you want to do it?)

Mar 06
 16:59:00
Re: Tutorials Wishlist
posted by Inertia

It's really that simple - his code will compile and play a sound. (assuming a valid ALContext, speakers turned on etc.)

You could change AL.BindBufferToSource into
AL.Source( sourceID, ALSourcei.Buffer, (int)bufferID );
(which is done by the AL.Bind helper internally)

AL.Delete* should be called for cleanup of the reserved handles before exiting and there's no error-checking, but that's it.

PlayStatic.cs demonstrates exactly this functionality, why write another example? I'll edit http://www.opentk.com/node/209 accordingly to work with AudioContext and WaveSound, once 0.9.1 is there.

Edit: Since I've already broken my plan not to comment in this topic, might aswell mention that an "OpenTK sample game" is in the works. It will come with full source code, and a couple of book pages giving insight into the 'making of'. There is not only 1 single way to make a game, so it's kinda impossible trying to make it a step-by-step tutorial. The book pages will be more about considerations and choices made rather than trying to explain how to draw a textured quad. It will be a little more complex than pong, in order to deal with performance considerations aswell (after all, OpenTK is built around OpenGL)

Mar 06
 19:16:48
Re: Tutorials Wishlist
posted by objarni

Great news about the sample game!

I prefer online samples / documentation of things, that's why I'm asking for it. IntelliSense (what you've sometimes referred to as 'docu') is great for details / reminders while coding. Example programs are great for demonstrations and testing the library on different platforms.

I thought the topic of this thread was "Tutorials Wishlist"?

Mar 07
 17:03:00
Re: Tutorials Wishlist
posted by Inertia

Well it has been a week, and very few requests for tutorials were posted. If anyone has troubles getting started, it's usually the best approach to search/post in the forum to check if anyone has encounter similar difficulties before.

I prefer a 50 lines source code over a 5 page abstract talk about the problem, so the Source/Examples directory helped me getting started with OpenTK way better than if Fiddler had written a dozen tutorials. Guess it depends if you have an academic or autodidact background.

The VBO tutorial is only so verbose, because the topic is neither covered in the red nor orange book, but it's a really important concept to understand for programming GL. VBO questions were frequently asked at the Tao forums, so it was a good candidate to start with.

The term "book" might be misleading in context with OpenTK, at least I do understand it to be more of a manual for things too complex to deal with through Intellisense (which is imho the best thing that could happen to programmers besides home-pizza-delivery ;) ). It was agreed even before the "book" was created, that we won't bother rephrasing or c&p anything from already available resources.

Mar 07
 22:42:57
Re: Tutorials Wishlist
posted by AstroMag

Here is my wish list:

1) How to get computer Total Physical Memory and Free Physical Memory size in MONO/NET?
2) Geting microphone - output (OpenAL)

Mar 07
 05:18:56
Re: Tutorials Wishlist
posted by Mincus

AstroMag: I don't think getting the memory requirements is within the scope of OpenTK.
However under Windows (not tested this under Mono) you can add the reference "Microsoft.VisualBasic" then use the class "Microsoft.VisualBasic.Devices.ComputerInfo" to get the Total/Free RAM amounts.

Mar 08
 07:10:00
Re: Tutorials Wishlist
posted by the Fiddler

Interesting suggestions, hadn't considered these before. :)

As Mincus said, there's a line we need to draw somewhere between the "necessary" and the "nice, but beyond our scope" tutorials. For example, for OpenGL topics you can refer to the Red Book (available online), the OpenGL SDK, online tutorials etc. Our tutorials only need to show how to transfer this knowledge to OpenTK ("necessary" category) - everything else should fall on the "beyond our scope" category. This doesn't mean that we won't add such material to the manual, if someone takes the time to write it, but rather that we wouldn't spend much time on this ourselves. :)

In this light, getting the amount of physical memory does fall outside the scope of OpenTK. Fortunately, this is a topic covered on MSDN page and by onlie tutorials. (These links point to System.Diagnostics.PerformanceCounters, which should be supported on Mono.)

Audio input on the other hand (microphone/line in) is "necessary" material, in part because OpenTK will provide support through a "CaptureDevice" class and in part because the existing documentation is not clear enough (judging from the OpenAL mailing list).

Mar 08
 08:25:11
Re: Tutorials Wishlist
posted by Mincus

Going a bit off topic now with this, but had a look at the performance counter stuff.
2 things: Neither the Microsoft.VisualBasic.Devices.ComputerInfo or the PerformanceCounter seem to be implemented in Mono (at least not in 1.2.4, will check in 1.2.6 later).
To get the system RAM with the PerformanceCounter under Vista you require administrator access, which obviously isn't something you want to force on users. The VisualBasic object doesn't require this.

I also note the PerformanceCounter only gives the currently available, not the total RAM (VisualBasic gives both) and seems to use an additional 4-5MB of memory under Vista. :o/

Anyway, I've dropped the code here if anyone wants a look.

Mar 08
 08:51:53
Re: Tutorials Wishlist
posted by the Fiddler

Thanks for investigating. Checking the source in Mono, confirms that these aren't implemented (ComputerInfo and PerformanceCounters).

It looks as if there is not way to get this info in a cross-platform manner...

Mar 08
 09:13:00
Re: Tutorials Wishlist
posted by Inertia

[memory]
System.Environment.WorkingSet returns the total available RAM allocated for the process of your app, while System.GC.GetTotalMemory() returns the amount of allocated memory known to the GC inside the app. Don't quote me on this though, never ran into any memory problems so far and kinda trusted in Fiddlers 'marketing promise' that the limitation is 1GB RAM or more (~4GB in 32-Bit OS, a number larger than I can count for 64-Bit) ;)

I totally agree with that question being out of the scope of OpenTK's manual (or "book"), but ofcourse they can be asked in the forums.

[audio capture]
The OpenAL 1.1 SDK contains a sample how to capture audio data and save it into a .wav file, however it did not use Alut functions, but a custom .wav writer for this. I didn't port that library and the example, but you can take a look at the SDK, the file is /samples/capture/source/capture.cpp
I'll cite some pieces from the sample:

// Open the default Capture device to record a 22050Hz 16bit Mono Stream using an internal buffer
// of BUFFERSIZE Samples (== BUFFERSIZE * 2 bytes)
pCaptureDevice = alcCaptureOpenDevice(szDefaultCaptureDevice, 22050, AL_FORMAT_MONO16, BUFFERSIZE);
....
// Start audio capture
alcCaptureStart(pCaptureDevice);
....
// give it time to record something from the mic
....
// Stop capture
alcCaptureStop(pCaptureDevice);
....
// Find out how many samples have been captured
alcGetIntegerv(pCaptureDevice, ALC_CAPTURE_SAMPLES, 1, &iSamplesAvailable);
....
// Consume Samples
alcCaptureSamples(pCaptureDevice, Buffer, BUFFERSIZE / sWaveHeader.wfex.nBlockAlign);
....
// Close the Capture Device
alcCaptureCloseDevice(pCaptureDevice);

Needless to say, this won't compile and does 0 errorchecks, but should give an idea what commands are involved. The functions are all available in OpenTK and it should be possible to AL.Bufferdata what you recorded to play it back. (The above commands are not resembling the program from the SDK.)

Edit: Mincus request has been done as a dynamic VBO example showing a possible implementation, will be in 0.9.1. (Google shows 50k+ particle system tutorial related pages)