Blitz Lua Function Interface

wiki

BlitzLua Function Interface

The "function interface" directly maps BlitzMAX functions to a Lua counterpart. All functions of a given BlitzMAX module reside in a Lua table whose name is that of the underlying module: e.g., under Lua, the BlitzMAX function createWindow found in module BRL.MaxGUI is replicated by brl.maxgui.createWindow (with brl being a global table). An optional "import" mechanism makes all functions of a given module global, removing the need to prefix them with their module name.

MaxGuiExample contains two simple examples which illustrate the use of this interface.

Naming Conventions

Since Lua is a case-sensitive language (whereas BlitzMAX is not) the following naming conventions apply:

• all module names are in lowercase
• the casing of BlitzMAX function names is kept - with the following exceptions:
  • names starting with a verb or an adjective begin with a lowercase letter
  • all other names start with a capital letter

In case of any incertitudes just consider the function reference which is part of the package.

Parameter Handling and Type Conversion

The Lua function parameters equal those of the corresponding BlitzMAX function, any default values are properly respected (i.e., the corresponding Lua argument may be nil). Types are converted as follows:

• BlitzMAX strings are passed to Lua as C strings - and vice-versa (this currently prevents the use of 16-bit character sets and will probably be changed in the future. For the moment, this approach has been chosen in order to avoid problems with wide-characters, which have been reported for MaxGUI)
• numeric BlitzMAX values are always passed to Lua as double-precision floating point numbers - and vice-versa (this works quite well even for "long integers" in the range -9007199254740994...+9007199254740994 [1])
• whenever BlitzMAX expects or returns a logical value, the corresponding Lua value must be (or will be) of type "boolean"
• whenever BlitzMAX expects or returns a byte array, the corresponding Lua value must be (or will be) of type "string"
• BlitzMAX objects are passed as "light userdata" (but read the note below!)

Additionally,

• "variable parameters" are returned one after the other (in the same order as they appear in the parameter list) in addition to and after the primary function return value (if such exists)
• whenever BlitzMAX expects an array of a given type (besides byte), Lua has to provide a numerically indexed table with elements of the required element type
• whenever BlitzMAX originally returns an array of values (not of type byte), the corresponding interface function passes an "unpacked" list of values to the calling Lua script

Noteworthy detail: since BlitzMAX has its own "garbage collection", any BlitzMAX object has to be explicitly referenced (from within BlitzMAX itself!) in order not to be removed shortly after its creation. This is done internally using BlitzMAX "handles" (which are one-to-one representatives of a given object) - in fact, its an object's handle which is passed to Lua rather than the object itself. As a consequence, it is now up to Lua to "destroy" any BlitzMAX object which is no longer required. Thus, every BlitzMAX "createXXX" function (or "loadXXX" or similar) which is used to create an object of type XXX now also has a "destroyXXX" counterpart (within the same module) which must be called to remove that object.

Any BlitzMAX constants are also available within the table belonging to the defining module - their names have been kept in uppercase (e.g. brl.event.EVENT_WINDOWCLOSE) as under BlitzMAX.

--AndreasRozek