OpenTK 5.0 TODO list #1207

Tasks list

• Color overloads [only needs a few manual overloads for GL.ClearColor(ColorX)
• Add typesafe gl handles.
• Fix the native method _ postfix (something is not working correctly here right now. Not sure what it is)
• Move to Opentk.Mathemathics.Half
• Write apple stuff for GLHandleARB
• Documentation for all the overloads (This probably requires a tick list by itself as we havent even started on this step yet)
• Merge master into the otk 5 branch to get all the math fixes pushed to both branches.
• Fix all warnings and FIXME's in the generator and the generated code.
• Lots of field testing
• Fix any spec errors we might find (this is reoccurring and will probably never be completed).

For future updates?

• New windowing system

Source Location

The source code for the new generator is currently located at:

https://github.com/frederikja163/opentk/tree/generator

How to contribute to the OpenTK 5.0 Bindings Generator

To help with XML issues

There are mismatches between the XML version of the spec and the official documentation.
These cause the bindings generator to generate incorrect values or less convenient types than we expect.
These issues mostly are missing metadata about how parameters and information relate to one another.

To improve this, we need to fix the upstream XML version of the spec.

Fixing XML Guide:

Using the example function: glNamedFramebufferDrawBuffers

1) Look up the OpenGL function signature in the reference documentation.

The parameters section contains the information we're concerned with.
For example, see: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glDrawBuffers.xhtml

Pay attention to the parameter listing:

framebuffer
    Specifies the name of the framebuffer object for glNamedFramebufferDrawBuffers.
n
    Specifies the number of buffers in bufs.
bufs
    Points to an array of symbolic constants specifying the buffers into which fragment colors or data values will be written.

2) Look up the OpenGL Function signature in the Khronos XML specification:

This is available here: https://raw.githubusercontent.com/KhronosGroup/OpenGL-Registry/master/xml/gl.xml
It's a huge file, so download it into a text editor and use Ctrl+F (Search) to navigate to the function you want.

We're concerned mostly with the <command> section.

at the time of writing, this looks something like this:

<command>
    <proto>void <name>glNamedFramebufferDrawBuffers</name></proto>
    <param class="framebuffer"><ptype>GLuint</ptype> <name>framebuffer</name></param>
    <param><ptype>GLsizei</ptype> <name>n</name></param>
    <param group="ColorBuffer">const <ptype>GLenum</ptype> *<name>bufs</name></param>
</command>

This is ALMOST correct, but there is no information to indicate that n corresponds to the length of the bufs array.

3) Add missing metadata:

To fix this, we need to add a len property to the bufs parameter. This tells us that the n property corresponds
to the length of the buffer pass in. This change is on the last <param> line.

<command>
    <proto>void <name>glNamedFramebufferDrawBuffers</name></proto>
    <param class="framebuffer"><ptype>GLuint</ptype> <name>framebuffer</name></param>
    <param><ptype>GLsizei</ptype> <name>n</name></param>
    <param len="n" group="ColorBuffer">const <ptype>GLenum</ptype> *<name>bufs</name></param>
</command>

4) Now, make a PR to the Khronos Repo with your changes.

This repo is available here: https://github.com/KhronosGroup/OpenGL-Registry

To help with code issues:

TODO

FAQ:

Is there any documentation on the XML tags?

Yes there is. A full PDF is available here listing all of the properties and what they mean:
https://raw.githubusercontent.com/KhronosGroup/OpenGL-Registry/master/xml/readme.pdf