Improving the SDK

Thank you. I will be watching this thread with interest. When you need my involvement, you may drop me a private message.

Korval: I think we’re going to try to hide function pointers behind a nice extension loader. I agree most new programmers aren’t going to know about them.

OK, I’ve got a list up of basic components needed before we can even write the boilerplate code. . Questoins, comments, and suggestions are, as always, welcome.

Well okay. It came to my mind that we could perhaps use mixed C and C++. C++ classes for the math system and C for some others. Do you think this could work? I would have some code for math classes, such as vectors and matrices. Althought, we could code this in C too.

For the file system abstraction, we could implement some function that translates the path to the OS path.

Other issues: We should also decide on the naming convention of functions and classes (if we use C++).

So who is gonna write the “display processor” program that reformats the K&R “original” text into whichever style each person prefers?

Already written. The Eclipse IDE has that feature. Much more importantly, however, is to NOT worry about style. As with any project, if you get too “low level” before you even know what you want, you’re screwed.

Style… libraries… What do you WANT from an SDK first?

Here’s what I would do if I were to start that project.

  1. Look at existing examples of 3D SDKs. There’s the DX beast. Both nvidia and AMD put out DX/GL SDKs (no, ATI’s GL SDK hasn’t been updated since 2005). What do you like about these SDKs? What do you not like? What do they provide?
  2. After doing that research, come up with a list of what you think should be in the GL SDK. Think high level: Documentation, tutorials, full source demos, utility libraries, tool utilities.
  3. Refine your list into more specificity:
    3.1) What tutorials? Tutorials for beginners? For tools? For performance? For advanced topics? Should the tutorials include a “tutorial framework”?
    3.2) What documents? Reformatted man pages? Annotated spec? Extension guide? Performance guides? Pretty pictures?
    3.3) What demos? What are the licensing arrangements for using nvidia demos/amd demos/GPU Gems demos/user xyz’s demos?
    3.4) What utility libraries should be included? GLUT? GLew? Links to nvidia/AMD debuggers/analyzers/composers? A simple GL modeler? Model/texture importers?
    3.5) Could be more things to list…
  4. Task assignments to further research items in #3. Tutorial submission requests. Demo licensing investigation. Document gathering and formatting… Tons of tasks… BEFORE A SINGLE LINE OF CODE IS WRITTEN!!!

Debate style, and hell, language too, when you actually know what you want.

If you jump right into coding tutorials you’ll at best duplicate the NeHe effort, not create an “SDK”. At worst you’ll waste time at work trolling this thread with arguments about your favorite C++ feature/style.

Sure, OpenGL is an API for CODE but please, stop talking about code IMPLEMENTATION until you figure out what you want in an API.

There is also a UNIX tool called ‘indent’ which is able to transfer code between various coding styles.

Standard C is probably better. We won’t have operator overloading for vectors (which is unfortunate), but it’s the lower common denominator.

A gl-inspired naming scheme for functions would probably be best. Perhaps “glsdkAwesomeFunction” (the prefix is up for debate).

Can we all agree that hungarian notation should be avoided, except in OS-specific code where it’s standard (namely Windows/WGL code).

If there’s going to be a serious effort to achieve this, then we probably need a SourceForge project or something similar for it. That way, we can have a place for discussing this, as well as a place for donating code.

Also, I offer my services as a document writer. I love DocBook XML, and I can do some pretty amazing things with it in terms of documentation (making HTML in virtually any format you would like to see, PDF versions for printing, etc).

  1. Look at existing examples of 3D SDKs. There’s the DX beast. Both nvidia and AMD put out DX/GL SDKs (no, ATI’s GL SDK hasn’t been updated since 2005). What do you like about these SDKs? What do you not like? What do they provide?
  2. After doing that research, come up with a list of what you think should be in the GL SDK. Think high level: Documentation, tutorials, full source demos, utility libraries, tool utilities.

I agree on some level that research should be done into other SDKs to see what they offer, but there are enough tasks that any reasonable OpenGL SDK should cover (extension loading, for example) that it’s something that can be put off until later. Those tasks should be broken down and assigned fairly early on.

I agree on the hungarian notation. However I would not recommend a naming prefix for tutorial/example code. We could use the GNU naming like_this.

pudman also has good points there. We should first think about the content and the design of the SDK first before anything.

Edit: I see the naming prefix overly verbose and redundant without any benefits for sample code.

pudman: Thanks for the reality check. I tend to get bogged down in details too soon, as you noticed =).

I’m on Linux, so I can’t look at the DX SDKs. And NVIDIA’s linux SDK is pretty much a collection of examples. It’s not a good reference point. Someone one windows needs to do that bit for me, I’m afraid.

From what they say on their websites, and from what we’ve discussed here, I think we need something like this:

[ul][li] An API reference (like the manpages, only includes non-deprecated 3.0 stuff)[] A series of tutorials on the basic concepts needed to get an OpenGL program running. This is rather involved, since fixed-functionality is gone[] Annotated examples and/or tutorials on higher-level concepts. Things like lighting equations and other fun graphics math that everyone needs to know[] A set of libraries for matrix math, extension loading, context management, and filesystem abstraction[] Fancier less-documented demos purely for showing off what GL can do.[/ul][/li]
Does everyone agree with this? Questions, comments and concerns are welcome, as always.

OK, responses to all the cross-posts:

Sourceforge project: I can go with sourceforge. I’d prefer git to SVN, but I’ll survive with SVN.

Henri: The prefix would only be for library functions that come with the SDK - image loading, extension management, and that sort of stuff. Functions within examples don’t need any particular prefix.

Korval: Docbook is a pain to learn. I think we’d all be grateful to be able to use a system like that and have somone on the team who knows what’s actually going on with it.

EDIT: If there are no objections by this time tomorrow night, I’m going to request the sourceforge project

It looks good. I have a Windows machine at my disposal, I may check the DXSDK. I read from somewhere that ARB is updating the manpages to conform to GL3. I am not sure can we use them for the copyright reasons. We could also write our own pages.

I am willing to put time and effort for implementing the math libraries or some parts of them. First, we need to agree on them and design them. Put it is not the time for them yet.

An API reference (like the manpages, only includes non-deprecated 3.0 stuff)

I think that one we should take from the ARB. When they update the “not-SDK”, we can just use their HTML.

Docbook is a pain to learn.

No, it isn’t. You’re just not using the right tools. The writing of a DocBook document is simplicity itself; it’s more the use of it that takes some effort.

A set of libraries for matrix math, extension loading, context management, and filesystem abstraction

No filesystem stuff. All the SDK should do is take a string (UTF-8) that represents a path and use it using standard reading functions. Anything more than that is well beyond the scope of an SDK.

I think Korval meant that he can write the DocBook files. We can send him the raw text in plain ASCII format etc. and he does the conversion into DocBook.

I think we’ll need to write our own pages. I’d rather they be in docbook, or some other low-level format like that. That way we can create a PDF, HTML, and all sorts of other formats very easily.

The math libraries are on the list of things to do once we have a plan and some idea of how we want to code things. They’re one of the first pieces of code we’re going to need to write, so it might not be too early to start designing them.

EDIT: cross-posted with korval on this one. We migh have licensing issues with the ARB-released manpages. We need to verify we can use them before we copy them.

OK, these cross-posts are getting kind of ridiculous. Can we switch to IRC or something like that?

IRC is fine. Lets choose Freenode server and #glsdk channel.

The DirectX SDK is a big thing containing many things. The documentation is split into parts, each part describing one subsystem of DX. Each part has somewhat these basic things:

  • Programming guide
  • API reference
  • Tools
  • Tutorials and samples

I think we should do some sort of Programing guide also, describing some basic 3D graphics and math background, like matrices, 3D transforms and coordinate systems. Another good one is a section devouted to our portability layer.

OK, I’m in the channel. And your list of sections looks good to me. Next step is to prioritize them, and break them down into subsections

I am going to throw this out there, what about just using SDL? It covers all platforms. Plus it will load textures instead of messing with a texture loader to complicate the SDK for new coders. We can just concentrate on the API and leave a basic operational framework working with SDL… The whole point is to get this out to as many platforms as possible, and if you can read some C/C++ code I hope you can at least follow a simple SDL app with very few lines of code, vs. the nature of win32 or Cocoa…

As I said before, what about a webpage on for this SDK? Or there is going to have to be a sourceforge page for this then…

I have no preference for C or C++, as was stated with function pointers by Korval, for C, C++ uses virtual functions instead, but GL uses function pointers, but couldn’t we get around this with just using a extension loader? Then what would the user really need to mess with function pointer for?

Mars_999: If we’re gonna have all sorts of samples and examples, we need a VCS. If khronos is willing to set that up on their servers, we can have a page on Otherwise we can start on sourceforge, and maybe move to our own server if necessary.

As for SDL… it’s big. It covers a lot of things not related to OpenGL, and there are some idiosyncracies (like texture coordinates) that make mixing the two kind of strange.