Notes from my branch of LuaGL.
Design notes on OpenGL bindings:
- Wrapper functions should have as few return paths as is reasonable as this creates unnecessary complexity and overhead
- Under the hood, we don't need to call each type of equivalent function. The Scripting bindings are abstactions to a certain degree of the low-level OpenGL API functions. If there are many function signatures offering the same functionality we should combine them where possible. The bindings are nicely abstracted this from within Lua but in the current trunk design are not necessarily so. For example, gl.Vertex maps to glVertex2f, glVertex3f, glVertex4f, glVertex2fv, glVertex3fv, and glVertex4fv. In the C wrapper function, we only need one set of these functions, with or without 'v', not both.
- LuaGL will probably be used in many contexts since Lua is an embedding language. We should not try to predict how people will want to report errors but instead provide a default function that handles the most typical use-case scenario. For most apps this will involve calling luaL_error but other apps might have very different needs. As an example, a computer game might have it's own custom console that it would like scripting errors reported to. The authors of the game should be able to recompile LuaGL (or perhaps set it from a script at runtime?) by switching one line of code to put in place a different error function.
- We should start auto-documenting LuaGL with doxygen style comments
- the function lua_isstring coerces non-string types if it can. In wrapped functions where an actual string is the only logical input as is the case with enums in LuaGL scripts, we should instead use the idiom lua_type(L, index) == LUA_TSTRING is this will match only strings instead of strings in addition to coerces types
- LuaGL has a lot of gratuitous (i.e. obvious) comments. It's a bit messy. Also, the comments are within multiline C stye comment tokens which prevents someone working with the source from using such comments to block out large chunks of code. If a comment is a one-liner, we should use one line comments '//' instead of '/* */'. I know the Lua authors prefer the multi-line style, but I find it hurts coding efficiency when modifying source files
- To help readability, in many places we should have brackets after if/for/while loops, especially in if/else if/else blocks with more than one branch. In addition to preventing coding errors, this will eliminate potential issues from macros that expand to multiple lines from breaking when not contained in a pair of brackets.
- I personally prefer tabs for indenting as opposed to spaces as it makes navigation with the arrow keys faster
- In many places, LuaGL uses (int)lua_tonumber when it should use the built-in Lua function lua_tointeger
- Use of malloc and free should be phased out as fast as possible, especially for small amounts of memory like vectors of floats. It's much faster for a function that could have 2, 3, or 4 values in a vector to just declare a vector of the maximum size statically and pass it's pointer in to the appropriate function instead of malloc'ing the exact amount.
- Sometimes the use of malloc and free are unavoidable when the vector is of unkown size as it is for images and buffers of points. In these cases we should try to come up with some kind of buffer object to avoid constant re-/deallocation and to speed up the transfer of data from Lua to C. Possible solutions are a buffer user data class or the use of a global memory pool within Lua
- The design goals and priorities of Lua should be the following
1) Provide robust bindings to as much of OpenGL as makes sense on a nearly 1 to 1 basis with low-level functions, including most of the OpenGL extensions. This way script authors and put low-level functions together to build higher-level abstractions for dealing with complex parts of the API like textures and framebuffer objects.
2) Once the low-level bindings are in place, development should focus on constructing high-level C++ classes for encapsulating parts of the OpenGL API that make sense grouped as objects to relieve some of the burden of script authors and increase performance by moving more of the processing to C/C++. Such high-level objects should be as platform agnostic and use-case agnostic as possible provuding robust and flexible functionality. Examples would be a Texture class, Shader class, FBO class
3) In parallel to 2), developement should also bring in related APIs for 3D graphics such as Cg if it makes sense in building abstractions like a Shader object. We should not, however, include projects for model or image loading for example as these are related sister proejcts but do not have to do directly with controlling the GPU like Cg does.
4) In addition to GLUT, it would be nice to provide native OpenGL windowing bindings as an option for users. In this way, LuaGL could provide x-platform windowing with a single interface
