Illogical locations of functions

[Laar]

Some functions and data types are from the outside placed in the 'wrong' module. For example what are Query objects doing in the PerFramgent module? On the other side sometimes it is a decision between exporting stuff to the outside versus putting it in the right place. For example where should "transformFeedbackMode" be placed by its name it should be in the module TransformFeedback but it needs a programID or programVar, which would lead to exporting stuff that shouldn't be exposed to the outside.

I think that some solution should be found for this problem. Maybe in adding an extra namespace level or so?

[dagit]

For this to be a task that people can work on you'll need to be more specific.

[Laar]

I did mean it more as a discussion/enhancement point, though the mailing list seems more appropriate for such thing.

P.S. I found another one, what is "maxTextureUnit" doing at the end of "VertexSpec"?

[svenpanne]

The OpenGL package, especially the Graphics.Rendering.OpenGL.GL module should be structured along the lines of the OpenGL spec itself. This avoids random decisions where we put some stuff (the spec writers probably have thought about that enough already) and makes it easy to look up things on the Haskell side when you have the spec at hand.

The spec itself has been heavily restructured and the Haskell side has bit-rotted a bit, so I am currently cleaning things up and track the spec on the Haskell side. The end result should be a Graphics.Rendering.OpenGL.GL module plus a module hierarchy below it that extremely closely follows the OpenGL 4.4 spec.

As Jason already said, this issue is not specific enough: If you have concrete proposals to move things around according to the OpenGL 4.4 spec, please open separate issues for them.

[Laar]

@svenpanne, I'm not sure if the spec is the best guide to where each function belongs. It does indeed avoid random decisions, and is nice when you use the spec as guide. Though there are some point you might consider

As you state the spec has been changed quite a bit. Depending on the spec for guidance on where to put what implies that this change should be followed. This results in three problems. First of all, it breaks the API for people how use one of the more internal modules. Secondly it, can only be up-to-date with a single spec, thus if you use only 2.1 features you still have to look at the 4.4 spec for the location. And thirdly, it creates quite some refactor work, as you have to look at the changes.

Thirdly, the spec is structured according to its intention, defining OpenGL. The resulting structure might not be what a programmer expects from an API. While we (implementers of the package) probably use the spec often, it might not be the case for users. An user might prefer other documentation, like to online opengl doc, tutorials and wiki's. For them the spec might be a long document where they have to search through a lot of complicated and irrelevant (for them) details to find an incomprehensible specification of the function.

This last point can probably be seen in several parts of the spec. Two examples for the 4.4 spec with compatibility profile

• The definition of several 'objects' (part 2.x) from their workings (e.g. part 6-9)
• The splitting of the programmable vertex and fragment shaders and shaders them selves.

While I do not have a better approach in mind, I think it is also necessary to realise that following the spec might have its disadvantages. Furthermore I don't think we should forget the 'user' perspective (though this is not clearly defined perspective). They will eventually decide if the implementation of OpenGL is good, or that they prefer to use OpenGLRaw and write something themselves (as many do now, partially because it's out of date).

[svenpanne]

I am quite aware of the fact that no matter how you present a complex API, the solution is never perfect. The main reason for this is that one's current point of view depends on what one is currently trying to achieve/learn/use. Taking your shader example, it very much depends on the part of the code you're writing if you are more interested in how shaders/programs/pipelines work in general (e.g. in the part of your program loading/assembling shaders from GLSL code in files) or if you are more concerned about the details of a specific kind of shader (e.g. in the part of your program setting up vertex shader data). Whatever you do, the partitioning of things into a module hierarchy will be sub-optimal for some kind of view on the API, because every hierarchy is fundamentally one-dimensional.

So instead of starting to invent a completely random new hierarchy (a.k.a. "not-invented-here-syndrome"), it is IMHO the best approach to follow what is already there in the official spec. To make other views on the API more convenient, one can add heavily cross-referenced documentation (patches are highly welcome! ;-). Furthermore I can't see why any other organization of the API following any of the dozen tutorials/wikis/... should be better. About 99% of this external (i.e. non-spec) documentation I've seen is highly incomplete and often oversimplifies things, so I am quite convinced that following the spec is the only way to go.

Regarding the volatility of the spec: The spec editors are probably not masochists, so I think it's very unlikely that the spec's structure will change radically again soon. The organization of the old specs mainly describing the fixed function pipeline was simply not a good fit anymore, so it had to change.

Regarding API change: I intend to improve several parts of the current API anyway in a non-backwards compatible way, so rearranging things a bit won't make this much worse. Furthermore, I don't see a strong reason why one should import modules deeper down the hierarchy. In any case, the resulting changes in the user code will mostly be mechanical. I know that changing an existing API is not nice, but sometimes it simply has to be done...

[Laar]

@svenpanne , a bit late, but thanks for the explanation.