Improving the SDK

That’s not really a problem, is it? Both the C and C++ file I/O libraries accept forward slashes on most (all?) platforms. They’ll also accept back slashes on Windows, in case you’re accepting user input.

Oh, somebody also mentioned that modern C compilers “accept” C+±style comments. Actually, C+±style comments have been standard since C99; you can use them and be guilt-free.

What about glfw? (http://glfw.sourceforge.net) It’s as simple and light-weight as you can get, like FreeGLUT but with a saner API.

Glee or glew would also be very valuable, but otherwise it would be a good idea to keep dependencies to a minimum.

I really like GLFW too, but it lacks UI and text, contrary to FreeGLUT.

Maybe both could be used, GLFW for games and visual demos, *GLUT for apps with menus and buttons.

Yes, glfw is very nice - I think it’s the best choice actually. No unnecessary stuff :slight_smile:

As for math library - I could provide C++ classes for vectors, matrices and math functions that have syntax identical to GLSL. I allready use such classes in my applications. Yes, swizzling is also included, so you can do this:

vec3 a;
vec4 b;
a.zxy *= clamp(b.yyz, 0.0f, 1.0f);

directly in you C++ application.

They require some more work. Vectors are mostly compatible with GLSL and most math fnctions from GLSL are implemented but matrices need quick rewrite.
There are still some cases when compiler requires explicit typecast when using swizzlers, but I believe that can be solved, too (partially solved allready).

The main problem is that I don’t have time right now to work on this. Perhaps someone would take over?

Is this SDK supposed to be online-only (like the current SDK/wiki), or is it supposed to be downloadable or both ?

I like downloadable SDKs, but then there is the problem to support all the different platforms with an installer (WE cannot ignore Linux…).

Jan.

EDIT: It could be distributed as a simple zip-archive.

As for me, if it’s not downloadable then it’s not an SDK :slight_smile:

I assume both, given the talk about using DoxyGen.

In the case of DX, I like having both. I use the downloadable DX SDK because its sample browser is a convenient way to browse the sample binaries, but I use the web-based SDK to look up code samples and function docs, because Google is a much better search engine than Microsoft’s crappy help system.

Of course, the actual DX library is distributed through the SDK, so you don’t have much choice but to download it.

Which brings up an interesting question: will FreeGLUT/GLFW/Glee/Glew/whatever be distributed with the SDK? That would certainly be convenient on Windows, although *nix systems are probably better served by their own package management systems.

This is what I meant; C++ style comments have been standard since C99 as opposed to C89. C99 is not, however, necessarily that widely adopted. GCC lacks some of its features.


We had a brainstorming session with PaladinOfKaos last night and we did some designing. He will probably post some topic you to comment about once he gets all that stuff organized.

Edit: the main focus was the math library and we decided to stick with plain C. C++ wrappers can be done later on.

A tangential question is, will the samples be precompiled, or distributed in source form? If the dependencies are kept to a minimum and the build system is simple enough, the latter may actually be easier to support.

But that’s actual a little less important than deciding to what is going to be in the samples; how it will be presented (NeHe style? shudder); by whom it will be written. (First decide the scope of the material and then how to implement it).

My opinion is that each sample should present a concept in written form, accompanied by a short program that contains the minimal amount of code that implements the concept. A “sample explorer” would list all available samples, possibly with links to further information, articles etc.

It would also be great to have the online function reference available offline. I don’t know if there are legal issues with this, but seeing that PyOpenGL (and other bindings) already provide their own versions of the online docs, it should be possible.

One more thing: should the sdk provide its own utility functions, or should it link/use existing libraries? For practicality’s shake, I think the latter approach might be better: collect the “best of breed” libraries for each category (e.g. math, windowing, texture loaders, GUI, fonts, etc. taking maturity, usability, community and license into account).

Edit:

This is what I meant; C++ style comments have been standard since C99 as opposed to C89. C99 is not, however, necessarily that widely adopted. GCC lacks some of its features.

The only C compiler I’ve used that didn’t support C++ style comments was written in '88 for DOS. GCC 2.95 supports these and VC6 does too - there’s absolutely no reason to worry about this.

Using other C99 features however is probably a no-go.

Edit 2:

the main focus was the math library and we decided to stick with plain C.

What about existing math libraries? Intel/AMD both provide such libraries and there are many more to be found in the web. Is there really a need to write a new one from scratch? Yeah, I’ve been guilty of that thrice, in C, C++ and C# - but I think we should avoid unnecessary complexity wherever possible :).

Another thing to note is that we could modify/wrap existing APIs to make them fit together in a nicer way.

We don’t know this at this point yet for certain, but I suppose that for Windows we should come up with both. For Linux, it would be source package mainly.

My opinion is that each sample should present a concept in written form, accompanied by a short program that contains the minimal amount of code that implements the concept. A “sample explorer” would list all available samples, possibly with links to further information, articles etc.

It would also be great to have the online function reference available offline. I don’t know if there are legal issues with this, but seeing that PyOpenGL (and other bindings) already provide their own versions of the online docs, it should be possible.

These are also my thoughts and I agree with you completely.

One more thing: should the sdk provide its own utility functions, or should it link/use existing libraries? For practicality’s shake, I think the latter approach might be better: collect the “best of breed” libraries for each category (e.g. math, windowing, texture loaders, GUI, fonts, etc. taking maturity, usability, community and license into account).

We are considering options. I think we will be choosing some existing utility libraries and write some of our own.

What about existing math libraries? Intel/AMD both provide such libraries and there are many more to be found in the web. Is there really a need to write a new one from scratch? Yeah, I’ve been guilty of that thrice, in C, C++ and C# - but I think we should avoid unnecessary complexity wherever possible :).

Another thing to note is that we could modify/wrap existing APIs to make them fit together in a nicer way.

While I am not completely aware of existing math libraries, I think we should do a “native” OpenGL math library that looks and feels like OpenGL. I am talking something like D3DX has.

In the mean time while Paladin gets stuff organized, take a look at this draft.

OpenGL SDK Math library draft

We will be staying in touch…

The math library draft looks nice for me as it is intuitive and recall the Opengl style.

For tutorial, I don’t know your opinion, but I always really hated the NeHe layout. A bit of text, a bit of code, a bit of text, a bit of code… this is very difficult to read I think.

I would rather have tutorials, with many explanations and especially illustrations with almost no code or only the important parts not the details. Details will be in the well commented attached source code

I tend to agree. The source code should have normal amount of comments and the detailed explanation somewhere else.

I really liked the Nehe tutorials when I was first learning, all those years ago. It coincided with the way I like to use tutorials, which is to copy each line of code manually, making sure I understand what each line does.

Once I had learned enough that I could diverge from the tutorials, though, it became less useful. I would rather have had a tiny example showing only the feature in question.

Nehe is going to rewrite their tutorials for OpenGL 3, though, so there’s no need to duplicate their work.

Precompiled binaries are definitely appreciated on Windows. They’re appreciated on Linux too, but again, that’s something best left to each flavour’s packaging system.

I don’t think there’s much point to distributing demos in the SDK if people can’t pick them apart and see how they work, so source code is a must. We can discuss binary packaging on all platforms once we actually have source that can be turned into binaries.

Even though NeHe does exist, I think we need to have a set of clear tutorials in the SDK that use the utility libraries we distribute. That way when someone goes from the tutorials to the examples, they’re not wondering what glmVecTransform() does, and why it exists. We can certainly included NeHe in a list of “other resources”, along with Gamedev, this forum, and the ARB’s erm… “SDK”

One suggestion for improving the SDK; provide the DocBook source files for the man-pages in a downloadable form. At least, it would certainly make it easier for me to produce 3.x documentation for PyOpenGL :slight_smile: . The board obviously has at least 2.1 docbook available (since they use it to produce the online SDK). Doesn’t need to be pretty, just the raw docbook files would be sufficient.

Rick, personnaly, I don’t think that copy and paste is a good way to learn. This way you don’t really understand the details, I think it is better to first read an abstract explanation with good illustrations (which heavily lack in NeHe tutorials) and then apply this theory coding with OpenGL. This way learning Opengl is more intuitive IMHO and you don’t get stuck in a way of thinking bound to the code.

Mike: I’d like to get the DocBook source into the SDK VCS so we can update and clarify the docs outside of the ARB’s decisions to do so. so the raw source would be available.

dletozeun: Clear and consistent with OpenGL is what we were going for with the design. I’m glad we achieved that.

Tutorial layout is going to be something to debate later (but soon later, not way later). I think the NeHe style is going to be best for the basic stuff (the DX tutorials use that same format). More advanced things should have textual articles with example code.

One problematic of the SDK is that if we are going to make utility libraries of our own, development cycles of them can be tricky and rapid.

I think a better option would be to develelop the libraries as a separate projects in Sourceforge etc. then just link them in the main SDK project. In this way, people could continue on the library development independently from the main SDK and also download them as separate packages if they so desire.

Of course, we should agree on some general guidelines and conventions to make all look clean and mean, and generally agree on the directions we are taking, but I think making a separation could be good idea?

We should think what utility libraries are we going to use in the SDK and what we need to do ourselfves. I recommend using freeglut or GLFW as somebody did mention it. The OpenGL math library I think is generally a good idea. Also, perhaps we should use GLEW as the extension library if they get to update it to OpenGL3.

Also, we need to decide some sort of SDK devteam structure, assign responsibilites etc… At this moment, we are not properly organized.

Edit: Or maybe we should do like they do in boost, organize the project into subprojects, which may be downloaded and developed independently…

We can get the devteam structure and responsibilites assigned through the Sourceforge tools.

I think we should keep the full SDK, including libraries, in one SVN repository. that way we can easily make the bundles for an SDK release. We can, however, tag the libraries for releases more often than we tag the full SDK.

I’m OK with using GLEW, although I think we should mirror it in our repository and keep our own .spec file (that only contains post-3.0 features). GLFW is a C++ library, so I think we should prefer GLUT over it, if possible. I’ll shoot an email to the freeGLUT developers about GL3 support.

Is there consensus on what the right starting point should be ? One triangle? Teapot? Ocean waves with froth ?

There might also be an opportunity here to be forward looking - to anticipate some common questions that are going to come up for future GL as deprecations take hold.

One example I’m strongly familiar with is efficient transport of CPU-sourced dynamic data using MapBufferRange - some of the known problems in emulating glVertex*** have to do with efficiently managing transient vertex storage without blocking or being forced to allocate buffers on the fly. This would be a great GL3 focused example.