Blitz Max

wiki

Introduction

[BlitzMAX] is a fast cross-platform BASIC compiler and run-time system for Windows 98/ME/2000/XP, MacOS X and Linux. Primarily intended for game development, it offers support for 2D graphics, 3D graphics (with a module), audio and networking - [MaxGUI] is an add-on for graphical user interfaces in BlitzMAX.

BlitzMAX already contains an interface for the Lua (5.1.1) API (axe.lua, written by Thomas Mayer, Noel Cower and Simon Armstrong). The author's version is an update for Lua 5.1.2 which also contains several bugfixes, additional documentation and a slightly different string handling (see below). Currently (May 5th, 2007), the module has not yet been uploaded to the official BlitzMAX module servers - thus, you will have to download and install it manually. As soon as the module servers offer the new version, a simple "module synchronization" from within the BlitzMAX IDE will be sufficient to update the old axe.lua.

String Handling

Several Lua API functions work on or return C-style strings, containing 8-bit characters and terminated by a null byte (\0). For Lua itself, a string is nothing but a sequence of bytes (including null bytes) with a separately stored length. As a consequence, Lua strings can also be used as a buffer for arbitrary data (images, sound samples etc.)

BlitzMAX offers strong type checking and supports both 8-bit and 16-bit character strings.

In order to combine these two worlds, the actual interface uses the following rules:

• whenever the Lua API expects a string parameter without additional length information, BlitzMAX provides a "CString" containing 8-bit characters and terminated with a null byte
• whenever the Lua API returns a string value without additional length information, BlitzMAX expects a "CString" and automatically converts it into its internal format

lua_pushstring and lua_tostring are examples for these kinds of functions. Most strings are usually passed this way.

• whenever the Lua API expects a string parameter with additional length information, BlitzMAX provides its string "as is" (i.e., without any conversion, just as a sequence of bytes)
• whenever the Lua API returns a string value with additional length information, BlitzMAX takes the Lua string "as is" (i.e., without any conversion, just as a sequence of bytes) and builts an internal string from it

lua_pushlstring and lua_tolstring are examples for these kinds of functions. They are useful to pass UTF-encoded Unicode strings between Lua and BlitzMAX.

Additionally, the interface provides two functions

• function lua_pushbytearray (lua_state:byte ptr, Buffer:byte[])
• function lua_tobytearray:byte[] (lua_state:byte ptr, index:int)

which can be used to pass BlitzMAX byte arrays to and from Lua - on the Lua side, they appear as strings which are, however, never converted by the interface in any way.

Nota bene: please keep in mind, that both the Lua API and the BlitzMAX API have to copy the strings passed between Lua and BlitzMAX. Lua makes a copy in order to avoid "dangling pointers", BlitzMAX makes a copy when converting between a C string and its internal format. Passing large amounts of text could therefore require both memory and processor capacity.

Byte-array-based interface functions still copy their parameters once.

If you want to avoid copies at all, you may have to consider using (light or full) userdata objects.

Limitations

Almost every Lua API interface type and function have been replicated in BlitzMAX. However, as it seems impossible to define BlitzMAX functions with variable argument lists, the following API functions are not available under BlitzMAX:

• lua_pushfstring
• lua_pushvfstring and
• luaL_error

Additionally, the following function is also missing

• luaL_checkoption

All other functions have been replicated and are therefore available under BlitzMAX.

Download and Installation

• download the most recent version of axe.lua from http://www.Andreas-Rozek.de/BlitzMax/lua.bmx
• navigate to the folder with the original axe.lua module (i.e., <blitzmax-installation-folder>/mod/axe.mod/lua.mod/)
• make a copy of the original lua.bmx file (just in case that you want to re-install the previous version later)
• move the new lua.bmx file into that directory

Within your BlitzMAX IDE

• "build modules" either by pressing Ctrl-D (or Command-D under MacOS X) or choosing "Program"->"Build Modules"
• "document modules" by choosing "Program"->"Document Modules..."

You are now able to "import axe.lua" into your BlitzMAX code. Additionally, the module documentation now also allows to directly jump to the section within the Lua Reference Manual where a given API function is described.

Related Work

This version of axe.lua is required for BlitzLua, the author's Lua interface for BlitzMAX/MaxGUI modules. BlitzLua allows you to run (embedded or stand-alone) Lua scripts with full access to BlitzMAX's 2D and 3D graphics, sound and networking capabilities.

Acknowledgments

This work is based on the Lua API Interface written by Thomas Mayer, Noel Cower and Simon Armstrong.

References

• [1] Lua 5.1. Reference Manual
• [2] BlitzMAX Product Description
• [3] MaxGUI Product Description
• [4] BlitzMAX and MaxGUI Forums

--AndreasRozek