Improving the SDK

Note to moderators: I think this belongs in “Items of Importance…”. I can’t put it there. If there’s any sort of good response, I think it ought to be moved there.

Since the SDK came out, there’s been a lot of whining about how it’s not a “real” SDK. This is more or less accurate. But whining won’t fix it.

I propose that the whole OpenGL community pitch in to create the examples and tools needed for an SDK. There are lots of examples to be written, and several tools that need free cross-platform implementations. This is really outside the realm of the ARB, unless the community takes action, it’s not going to happen.

I propose a series of meetings on IRC of all parties interested in improving the SDK. If we can create a solid design with well-specified tools and examples, actually coding them won’t be hard at all.

Creating it all for Opengl 2.1 may or may not be silly - I suggest waiting until after Siggraph to see what the roadmap is for Opengl3. Once we know that roadmap, we have a better idea of whether we should hold off for a couple months, or plow ahead. Either way, some aspects of the SDK design can be figured out soon after Siggraph.

the people with the time to do that are exactly the people we don’t need spreading misinformation around through bad tutorials and bad example code.
The IHV’s should collaborate and release a unified set of tutorials and example code. They’re the only ones to know what the right thing to do is on their hardware.
Wouldn’t you just love to see nvidia and ati actually cooperate on something for a change?

I certainly would. And I have no doubt the people that do the SDK software would love to cooperate. But marketing and legal always have the final say on everything, and things like “brand integrity” and “proprietray techinques” will outweigh making a unified SDK.

As for the people that have time being the wrong people - that’s not necessarily true. I don’t expect anyone to spend huge amounts of time on the project. But an SDK doesn’t have massive programs - mostly it needs small programs to demo specific features. Each of those is going to be just a few lines of code, especially if there’s already a boilerplate that every SDK example uses. If 5 people spend an hour to write one example every week for a month, that’s 20 examples. I suspect many of the examples won’t take much longer than that once a good boilerplate is in place.

I think the real problem is going to be tools. There are already some tools by nvidia and ati, but they’re windows (and mac?) only. OpenGL’s biggest strength is cross-platform compatibility, and the tools need to show that as well IMHO. Those tools are going to take a lot more work than the examples, but they’re what the SDK really needs. Fortunately, there are already some open-source tools listed on the current SDK pages. Enhancing them is a better choice than starting from scratch, as much of the hard work has already been done.

EDIT: About optimized examples - I think the OpenGL SDK should do what the MS DX SDK does - be generic. Get OK performance on all hardware. Let the vendors’ SDKs show how to best optimize for their hardware. And when GL3 comes out, it’s supposed to have only one good path anyway, so the whole point might very well be moot.

It’s not just about code, in fact cut-and-paste code with a small amount of supporting text is the LAST thing we need. Those are possibly the worse kind of “tutorials” out there.

No, to write a decent tutorial, which teaches concepts and not just ‘heres how to use the code in this situation’ takes alot longer than an hour a week. I seem to recall the FBO tutorials I wrote for gamedev taking me a couple of weeks to write, check, check on different hardware, change to make clearer etc. That was often spending a few hours on it a day. A tutorial is not a thing you can rush.

Also getting people to agree on a boilplate is going to be hard enough; There was a plan to re-write the NeHe tutorials on gamedev.net, a team was setup and then promptly spent the next year or two trying to build a solid foundation and I believe at last count 2, maybe 3 years, after it was setup there have 5 tutorials and an overblown framework.

The DX SDK is probably something which an OpenGL SDK is modeled after but that means;

  • code examples (examples, not tutorials)
  • articles which are mostly none code
  • a generally excellent and up to date API reference (complete with some small in line examples)

It also needs to be both one a single site AND as a downloadable reference as not everyone has net access 24/7 and sometimes it’s easier to grab the stuff from your local machine.

I think the OpenGL wiki was also supposed to be helpful to people looking for information. However, it doesn’t feature very prominently on the OpenGL main page so people come to the forum where they can get a specific response to their specific question. Ideally someone (preferably the question-asker) would then update the wiki with the answer.

Tutorials and articles plus problem solutions would make a very useful wiki. However I just don’t see it happening right now. Someone would have to spend time updating it to show what it could be capable of (the ARB).

As for the “SDK”, there would be a simple way to get version 1 out. Include:
[ul][li]The API in downloadable form. Zipped HTML works nicely (look at the Java APIs) but would require some extra formatting to get the pages nicely linked together.[]The Red Book examples zipped up. They are extremely dated but I think you can already grab them somewhere. Good for newbies.[]GLUT/GLEW/whatever zipped up, source included. Preferably with example code showing basic usage.[/ul][/li]
That’s relatively trivial. The key is that it’s all downloadable in one package. After Version 1 they can start making the examples actually useful, include helpful articles (how about “How to Read the OpenGL Specifications”?). Better tool inclusions. A platform independent shader debugger.

Even Version 1 would probably be asking a lot of the ARB. So far, their speed in doing things is terrible and the quality of their webpage resources leave much to be desired (excluding this forum, of course!).

Any new SDK should be for GL 3.0. Usage of GL 2.x and below should be strongly discouraged. Documentation should remain, but the focus should be on 3.0 and above.

One of the things missing, that dx has, is a vector library (no, it’s not a valid point that that OpenSceneGraph has one, most people don’t use osg… and shouldn’t :slight_smile: )

I would like to suggest the following library: http://www2.imm.dtu.dk/~jab/software.html#cgla

Of other things essential are texture- and model-loading. I suggest either a simple .obj-reader, or, more likely to be embraced, a gl-wrapper for a collada-loader.

For textures it would be convenient to have either a libjpg-wrapper, a bmp-loader, or a wrapper for a proper library lige FreeImage.

…this is basically just stuff I would need to add to any project before I could do anything.

WHAT SDK??? Where is it?? You talk about community links?? Can we call that SDK??

No, we can’t call it an SDK. That’s been the point of the whole SDK debate since it was unveiled however many months (years?) ago.

I’ve created a document regarding the SDK. I humbly request that anyone who is interested in contributing to a community-led SDK effort, no matter how much or how little you think you can add, to read it and comment. It’s based on:

  1. The small discussion held in the GL3 announcement thread
  2. Some standard things (like common licensing) that every project needs to have
  3. My own whims and ideas

Everything (especially stuff coming from source 3) is changeable at this point. If you don’t like something, don’t get pissy. Just explain what you don’t like and why you don’t like it, and we’ll all discuss it like grown ups.

I know there aren’t many (any?) notes in the document on what came from which source. This is intentional. It’s written as a final document like that would be written.

Now that all that’s out of the way, here’s your linky

First, I think your document is a reasonable start. But the main thought I carry away from it is almost identical to something you (or someone) said, along the lines of “Sorry, but I’m not subjecting myself to styles/policies/libraries that I find personally repulsive (even if they might be better, in [somebody’s] theory), and I’m not gonna waste my time learning some library/programming-approach that I do otherwise because I much prefer it”. Damn, I almost feel guilty for also having this reaction, because in theory, I agree we should and could create a nice SDK. And I am/was even willing to help. Really.

This is a real problem, and if everyone else responds like us, and/or just advocates their favorite libraries and/or wacko-but-really-freaking-cool-programming-approaches, then everyone will run away at warp speed. Very sad, but it appears like this is true.

Therefore, my guess is, only 2 approaches might work:

#1: One person takes it upon themselves to provide the whole damn SDK project. True, we could contribute elemets, but he would immediately re-write it into his wacko but consistent personal style/approach/libraries - and we must be ready to accept that.

#2: The “lowest common denominator” approach, which means plain, vanilla, straightforward C (no C++). We all know C, even if we have moved on to supposedly/theoretically “greener pastures”.

Personally, I believe #2 is vastly superior. Why? Because it contains NOTHING that “loses people”, or bogs them down by requiring them to learn a new tool, style, library, approach, programming language. It might look a bit “ancient” to some folks, maybe even many folks, but it also looks pretty much just like OpenGL. So it is consistent and coherent in every way. And to keep things compact, which is very important in an SDK where people need to see many lines together to see how the various pieces relate, the good old K&R syntax is best:


int function (f64* mat0, f64* mat1, f64* mat2, f64* mat3, int x, int y) {
  if (x < y) {
    transpose_matrix (&mat2);
  } else {
    transpose_matrix (&mat3);
  }
  return (k3x_transform (&mat0, &mat1, &mat2, &mat3));
}

I wish I could find the article that researched and explained where the “modern” style came from that spreads everything out vertically in C/C++. The short answer is - moron professors competing for how many lines of code their students could write per unit time. Of course the easiest way to “win” is to have your students habituate the following “modern” style:


int
function (
  double* mat0,
  double* mat1,
  double* mat2,
  double* mat3,
      int x,
      int y,
         )
  {

  if (x < y)
    {
      transpose_matrix (&mat2);
    }
    else
    {
      transpose_matrix (&mat3);
    }
  }

  return (
    k3x_transform (
      &mat0,
      &mat1,
      &mat2,
      &mat3
                  )
         );

}

Justified by hyper-abstract professorial jargon-BS.

The last part is meant to be funny, not start any arguments!


As it turns out, I personally might have a way to “get off the hook” (evade these problems) by contributing my super-efficient SIMD/SSE2+ assembly language functions for the fundamental 3D transformations that get executed a zillion times (I never did like those “silly” OpenGL stacks!). But virtually everything else in the SDK runs into the problems I mention above.

I mean the above to be honest, helpful, respectful. Really. :slight_smile:

In fact, I DON’T know C and I bet most people who think they do because they know C++ don’t either (and probably don’t know all that much about C++ to boot but that’s a side issue); oh I can muddle along with C89 because it’s a subset of C++ but some of the things I don’t know about because I’ve never used the language as is.

Also SIMD/SSE2+ assembly language in an SDK is both redudant (and over kill) and locks the SDK to a single platform; not useful when OpenGL is meant to be cross platform.

So it is consistent and coherent in every way. And to keep things compact, which is very important in an SDK where people need to see many lines together to see how the various pieces relate, the good old K&R syntax is best:

Great, unless of course you have people who dislike putting the openning brace on the same line as the function/condition/whatever as it obscures your ability to spot nesting without parsing the whole line.

In short; another point of contention.

This is a real problem

Yes, it is. The fundamental issue is this:

1: I know what would be good in an SDK.

2: I don’t want to spend my precious free time writing that.

While I don’t think “K&R” syntax or pure C is the natural way to go for an OpenGL SDK, simplicity is an obvious goal. But the simple fact is that my free time is limited, and I spend enough of my non-free time working with horrific code. If I’m going to program as a hobby, I will do it in a style that I enjoy.

Which is why I say that I’m not a good candidate for helping to code this. Because I know that my style, which is reasonable when you have read a 20 page document explaining how and why it works, is not simple. It is not appropriate for an SDK.

Whatever style is agreed upon must be simple. It must adhere to certain reasonable conventions.

locks the SDK to a single platform

Except that you can always #define around these things, so that they’ll work in the absence of an appropriate build environment.

I agree with suggestion #2 of bootstrap. Of all the tutorials online, NeHe’s are the most popular, because they always contain the whole code of a project, they explain one main feature, but REPEAT at least some explanations about all the boiler-plate code, there is no complicated framework you need to learn/understand, and the code uses only very limited features of C++. All that makes it great code to learn from. Boost might be nice, but for beginners it IS a problem. Boost is huge and thus frightening to beginners, even if your projects will only use a tiny fraction of it. Also Boost contains mainly code that uses C++ features so cleverly, that most beginners would need to first look up all the C++ keywords used in there, that they have never heard of before.

Glut WOULD be a nice idea, if it wasn’t so outdated (since the SDK is supposed to only use GL3 code…).

In my opinion it would be best to have a FEW basic routines supplied by one person. For example for setting up a window with a GL context, destroying it again and maybe to load a texture from a common file-format (like TGA). Everything else should be up to the one who writes the tutorial. There could be guidelines, like “keep the code simple”, “don’t use classes” etc. And maybe a hand full of tutorials should be written by the SDK maintainers, such that others can copy their style.

I think this is a difficult task and lots of work, so don’t make it too complicated for others to help you out. If there are a few example tutorials, i am sure people will see it as an honor to contribute their tutorials in the same style.

Don’t think too much about “good programming practice”. There are way too many different opinions about it and it is not what the SDK should be about. Save yourself the trouble.

Jan.

In my opinion it would be best to have a FEW basic routines supplied by one person… Everything else should be up to the one who writes the tutorial.

An SDK is not, and should not be a bunch of tutorials. The purpose of an OpenGL SDK is as much to explain how to write GL code as to have a codebase that makes GL more usable. If you look at the DX SDK, you’ll find a lot more than just tutorials.

The fundamental beginning of any real SDK for OpenGL is an extension loading library. Especially since you can’t even get a GL 3.0 context unless you load at least one extension.

I can see how to agree and disagree with all of your points =)

bootstrap: I agree that #2 is a vastly superior option. I also think we need a unified style to keep the SDK as one solid unit rather than a bunch of example programs glommed together.

bobvodka: You may very well be correct on the “I know C if I know C++” problem. Perhaps a “C for C++ programmers” document could alleviate some of the problems there. And most C compilers these days can handle some C++ elements (especially one-line comments), so we don’t need to be too stuffy about ANSI C.

Jan: I think more than just a “few routines” would be better. We need something like the NeHe basecode, with a “setup” routine and a “render” routine that can be added to for each tutorial and example. It makes writing a tutorial much easier - you can leave out the basecode after the first few tutorials.

Korval: I agree that we need more than tutorials. A library of common routines is a must, as is a good basecode. The document didn’t describe it because it’s a prototype for a document that comes after we have that library in place - the thing new contributors get to read before we let them do anything.

All: Most people can get used to coding in a slightly different style than they’re used to (brace position, spacing) if they really care about the project. The consistant style of projects like Wine and KDE is a testament to that.

korval again: Would you be willing to be sort of a technical editor, helping to make sure that tutorials and articles are technically correct? You’re one of the most knowledgeable people about OpenGL on this board, after all.

I can start another document of things we’ll need for the boilerplate and library, if you all want a single place to look at it and have ideas listed. There are lots of logistical things that need to be sorted out as well. Perhaps a third document is in order for that.

EDIT: I updated the coding style section. I still expect that to be a point of contention, but it’s closer to a lowest-common-denominator situtation now. If any of you have google accounts and would like to be involved in this for the long haul, PM me your accounts and I can add you as collaborators for the document. I’ll do the same for any future documents that come up until we get a website with a real CMS.

I cannot imagine anyone programming with OpenGL unless they understand the fundamental features of C. I mean, all the OpenGL functions are C function calls! What documentation are they reading to program OpenGL without understanding basic C syntax?

Also SIMD/SSE2+ assembly language in an SDK is both redudant (and over kill) and locks the SDK to a single platform; not useful when OpenGL is meant to be cross platform.
You are absolutely correct. But of course I always write C functions first, make them work, then write an assembly language function that performs exactly the same. So the normal function call serves the “learning” and “understanding” aspects of the SDK, while the SIMD/SSE2+ assembly language serves the “solid core/extension code base” aspect of the SDK. At least that’s what I thought people seemed to agree were the two main goals.

Great, unless of course you have people who dislike putting the opening brace on the same line as the function/condition/whatever as it obscures your ability to spot nesting without parsing the whole line.
It does not obscure anything - only the cues are different (match the indent of the beginning of the line with the closing brace). But I do not debate the absolute fact that many of us just shudder, if not suffer epileptic seizures, when we see code organized the “wrong” way.

In short; another point of contention.
It is truly amazing and incredibly sad how bad this problem has gotten! So who is gonna write the “display processor” program that reformats the K&R “original” text into whichever style each person prefers? BTW, nobody needs to see the code for your program - so you can write it any way you wish. What a relief!

I guess I wasn’t clear, but when I said “plain, simple, vanilla C”, I mean limit the code to the absolute minimum set of the simplest C features as possible. And yes, I agree with the person who said it needs to be written very carefully so it is as clear as possible. We want someone to write code like the diametric opposite of a “show off”.

Seems like we need to find someone universally liked/admired/respected to accept this responsibility. Otherwise he/she will be torn to shreds by contradictory demands - and give up.

Sad but true; somebody should probably just take the SDK project on quietly, then drop the finished SDK on us all in 6~12 months.

----- later thoughts -----

My engine creates windows and such with GLX (on linux) and WGL (on win32). I prefer that, and it stays within the “core” too. Also, I found that easier than the alternatives - but then again, I always find the lowest-level options to be easiest and most reliable.

Here is a really impractical idea - unless it works. How about trying to get [one+] of the authors of “OpenGL SuperBible” to help with this (even oversee it perhaps), and let him include the SDK with the next (fifth) version (or simply include or reference any parts that he finds appropriate). Or pick your favorite OpenGL author (“OpenGL Distilled” is another good one).

I think the SDK proposal looks very good. C is the best language to use due to it’s simplicity IMO. You will also need to address the issue of portability framework. And by the way, GLUT is not that outdated. FreeGLUT is being maintained and new features have been added to it.

If somebody wants to contribute but must use something like C++ or boost, then some other person can take the code and port it into plain C89 (or C99). Also good idea is to fix and clean every piece of code before submitting it to the final SDK.

I have not been programming 3D graphics or OpenGL for some years, but I think I could help. If not by writing code, but fixing, cleaning up and ensuring conformity to the “SDK standarnd” maybe.

Henri: Welcome aboard. I’m sure we can find a place for you to help. Having someone dedicated to code review might be overkill right now, but if the project takes off, it could be handy. I certainly don’t want to have to vet all the code coming through.

I cannot imagine anyone programming with OpenGL unless they understand the fundamental features of C.

The main point of having an SDK is to get people who have never used OpenGL before. So they are not OpenGL programmers. Yet.

The very concept of function pointers, central to loading extensions, throws off people. They’re something that C programmers are very familiar with, but most C+±only programmers are not.