API changes

There’s been some discussion on the forum about a recent change to the WebGL API. The full details are below, but the short version is that a number of methods on the GL context were merged together and changed their names; most importantly, gl.getProgrami and gl.getShaderi were merged into new functions called gl.getProgramParameter and gl.getShaderParameter respectively. Oliver Hunt alluded to these changes in a tweet on 26 November, and murphy dropped me a line to point out that this broke the lessons here. (I’ve now made the appropriate retrospective changes to sort that out — all of the lessons now work again.)

The reason behind this change hasn’t been made public, but I would guess it’s part of an adaptation of the OpenGL ES function names, which are optimised for a statically-typed language like C or C++, over to something more appropriate for a dynamic language like JavaScript.

In C++, you have to declare the type of the value a function returns, and you cannot have two functions with the same name and parameters but different return types. This means that when people want similar functions that differ only in return type, they add suffixes to the name to reflect that type; getTexParameteri returning an integer, getTexParameterfv returning a vector (array) of floats, etc.

By contrast, in dynamic languages like JavaScript there’s no need to declare your return type, so the same function can return different types depending on the circumstances. If you ask for data that is a list, you get a list. If you ask for something that’s a number, you get that instead. So there’s no need for this proliferation of names.

What the people in charge of the API have done is to merge all of the getXi, getXf, getXiv, getXfv and so on functions into simple getX functions, and then done a bit of follow-on tidying up.

Of course, in making changes like this, they’re making WebGL less of a simple JavaScript binding for OpenGL ES 2.0 — but perhaps that’s a good thing. OpenGL ES was created as a graphics library for devices that have limited processing capabilities when compared to modern desktops; for example, the iPhone. The Web has some similarities — after all, iPhones are web browsers too — but it’s not entirely the same, so there should be space for the library to grow independently. Slightly different methods names, while they might give people coming from iPhone development a moment’s pause, might also be the first signs of some level of independence for the WebGL API.

Anyway, below is the full list of the changes, derived by looking at the recent checkins for WebKit and Minefield. Minefield supports the new syntax, and also (probably temporarily) the integer (-i) versions of the old function names. Recent WebKit nightly builds only support the new syntax. The Chrome Dev channel doesn’t incorporate the latest WebKit, so it only supports the old syntax; you can work around that, at least for getShaderi and getProgrami, using this compatibility code.

  • getBoolean, getBooleanv, getFloat, getFloatv, getInteger, getIntegerv merged to getParameter
  • getBufferParameteri, getBufferParameteriv merged to getBufferParameter
  • getFramebufferAttachmentParameteri, getFramebufferAttachmentParameteriv merged to getFramebufferAttachmentParameter
  • getProgrami, getProgramiv merged to getProgramParameter
  • getRenderbufferParameteri, getRenderbufferParameteriv merged to getRenderbufferParameter
  • getShaderi, getShaderiv merged to getShaderParameter
  • getTexParameterf, getTexParameterfv, getTexParameteri, getTexParameteriv merged to getTexParameter
  • getUniformf, getUniformfv, getUniformi, getUniformiv merged to getUniform
  • getVertexAttribf, getVertexAttribfv, getVertexAttribi, getVertexAttribiv merged to getVertexAttrib
You can leave a response, or trackback from your own site.

One Response to “API changes”

  1. Alessandro says:

    Thanks for useful info ;)

    I think the name redux is a good thing.

Leave a Reply

Subscribe to RSS Feed Follow Learning WebGL on Twitter