the Fiddler's picture

(blog) Thoughts on OpenTK documentation

This question makes me think. Do you consider OpenTK well-documented? What parts do you consider lacking? What would you like to see?

I don't really know where OpenTK is standing in the documentation issue. According to Ohloh, 30% of all source code lines are comments, which is higher than average (22%). Considering OpenTK contains around 850000 lines of code, this number is nothing to laugh at. (Yeah, the numbers are probably overblown, no I have no idea how they are calculated :-).)

OpenTK is built on the premise that you are using an IDE with code-completion and documentation tooltips. Used on its own, it is actually more complex than straight OpenGL or OpenAL. This additional complexity is spent on type-safety and function overloads that smooth the differences between .Net and native code, which is a major win when using a .Net IDE like Visual Studio, MonoDevelop or SharpDevelop.

Is OpenTK usable without an IDE? Certainly, but the experience will not be as smooth. Strongly-typed parameters and function overloads won't help if you cannot discover them in the first place. So if gedit and make are your cup of tea then OpenTK might not be the optimal choice (but do check whether your editor supports .Net code completion - many do!)

Of course this doesn't say anything about the quality or usefulness of the documentation, so if you have any thoughts or suggestions I'd love to hear them.


Comments

Comment viewing options

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

My 2 Cents: I am using Monodevelop and code completion has worked for me flawlessly. Can't say much about coding without IDE, and I wonder whether it would be worth "redocumenting" the project. However, I have quite a fixed opinion about non-IDE programming - in my opinion its neglecting all that we have got since the 80's. Modeling, painting, writing, web development, map editing for games, music/video editing, file management: they all have made big steps in handling the complexity by having their own project file formats and quite advanced GUIs. For programming its syntax highlighting, code completion and maybe a fancy tree view for classes, that tries to make you forget that you are writing ASCII files. Insert a descriptive picture? ASCII art, please. Have a dedicated way for comments, like text boxes and different fonts/colors/aligning? No way. Some sort of data flow/logic illustration? Dive into some obscure UML tools, buddy!
Ehm... I am getting off topic but it bugs me to no end that the underlying file format of even largest projects are still nothing but .txt files. So I would appreciate OpenTK to making use of the little that we have won so far and continue having easy to grasp names and descriptions in code completion.

swiftcoder's picture

By and large, I find that the intellisense and matching online API docs are quite thorough, at least as thorough as most projects of this type.

However, API docs are only half of the picture, being used primarily within the IDE, while coding. For learning OpenTK and planning out one's project, the conceptual documentation is just as important, and there we have some definite lacks, such as the input documentation ( http://www.opentk.com/doc/input )...

--
Tristam MacDonald - swiftcoding

Trillian's picture

I find that the OpenTK documentation has fulfilled all my needs. However, I was quite familiar with OpenGL (both from C++ and the old .NET Tao bindings) so I didn't really learn to use OpenGL through OpenTK. The API feels and behaves like I'm expecting it. Really, I find that the library has a great overall quality. Like boogiwoogie, I wouldn't consider coding out of an IDE so the code completion-centricness is a non-issue to me.

Inertia's picture

Please keep the opinions coming, even if you simply agree with others. Right now we cannot tell if it's 1 out of 1000 who has troubles with documentation or 1 out of 10. If you do not voice your opinions we have to assume that everyone who doesn't say a word has nothing to complain about and is happy with how things are.

Starting a poll may be an option, but that'd limit your freedom of speech to a multiple choice dialogue...

flopoloco's picture

I have never used OpenTK without an IDE. I will never try to implement code without an IDE, from scripting to compiled languages.

My mentor is my experience, and it says that the best software is that one, that is well written and implemented. Instead of adding any bloat for memorizing any implementation details, it's better to focus on the creative and productive side and keep the big picture in mind. I tried hardcore notepad programming in work as a starter and it was very exhausting, so much brainpower lost for nothing, I do not recommend it. :)

LikeTK's picture

I would not recommend using it without IDE and Intellisense. When I started using OpenTK, setting the texture and lighting parameters may not be intuitive even with Intellisense.

E.g. the 3rd parameters, the intellisense suggest float, int, float* and int*)

GL.TexParameter(TextureTarget.Texture2D, TextureParameterName.TextureMagFilter,

But the right answer is

(int)TextureMagFilter.Linear

POSSIBLE IMPROVEMENT:

(a)Supplement the existing documents with footnotes and side Tips.
That are frequently asked questions from the users in forum

(b) Frequently request codes.
There are frequently discussed topics in the forum that sometimes do not arrive at the conclusion or "Official" ways to do it.

e..g How to draw certain geometries e.g. Cylinder. Many replied that it is very easy, with some psuedo codes and extension from drawing spheres.

In the end, after searching codes, I have to followed others and use glut32.dll

Basic Geometry is needed especially deal with Physics. The ".NET" physics bullet has only one example on OpenTK. One main challenge for beginner-Intermediate programmers to extend the OpenTK example is the lack of "Official OpenTK geometry methods for cylinder and other geometries that will be useful for physics engine".

Another example is TextPrinter, which is depreciated, so , what is the "OpenTK" official way to draw either 2D and 3D string on the screen.

(c) So, in my view, the way to improve documentation is have a list of wishlist on the areas of documentation that needed to be done.

e.g. what I discussed in (b).

(d) One more section on Documentation

What one should do when one is porting OpenGL codes that are based on other libraries e.g.

In SUmmary: OpenTK is the BEST LIB to help beginner to get into OpenGL using dotNET platform. It should continue to improve, not only to keep up with the new features, but to help the transition from the abundant example codes based on c++ openGL to OpenTK.

nythrix's picture

1) I have the impression that OpenTK is not here to "teach" OpenG/A/CL and it probably is the right thing to do.
2) I don't see why someone would NOT use an IDE. Even if they did, why should such an edge case have any impact on the documentation?

LikeTK: There are a lot of areas that need improvements, no questions about that. Unfortunately, OpenTK lacks manpower. TextPrinter was deprecated because no one was/is willing to take over. Same goes for the basic geometry or a collection of tools built on top of OpenTK (search OpenTK Framework). So, given that almost everyone ending up here needs to *USE* OpenTK for whatever they're working on, the real question is simple: how many of them would temporarily put aside (or even drop) their own project and join OpenTK in order to push things forward?

Tal's picture
nythrix wrote:

LikeTK: There are a lot of areas that need improvements, no questions about that. Unfortunately, OpenTK lacks manpower. TextPrinter was deprecated because no one was/is willing to take over. Same goes for the basic geometry or a collection of tools built on top of OpenTK (search OpenTK Framework). So, given that almost everyone ending up here needs to *USE* OpenTK for whatever they're working on, the real question is simple: how many of them would temporarily put aside (or even drop) their own project and join OpenTK in order to push things forward?

I try to create an engine which may(not 100% sure) said your point above. I think that OpenTK should not be like XNA, but more like SlimDX(which it is). Engines an frameworks should created separately. It's name is MaxDream.
The global idea is that it does not limit the developer, as describe in the "About" page.
It still lacks of documentions and is at GL 1.1 level(not completly yet), but I hope it may interest you all and ask for your help.

kwaegel's picture

I have been relatively happy with the documentation so far, dispute my general lack of knowledge of OpenGL. The one thing that threw me for a loop was the OpenTK.Compute section of the online documentation. The homepage describes OpenTK as having bindings for OpenCL, but clicking on the link to that section of the docs results in a page containing the line "[Describe the OpenTK.Compute namespace]" and nothing else. It would be nice to at least have a message describing the status of that feature, even if just mentioning it is not finished yet or providing a link to Cloo. The empty page is just confusing.

the Fiddler's picture

You are right, added a link to Cloo.