Zeolite API overview

Zeolite is the name of the C++ programming interface for writing extension plugins for L3DT.

1. Map function library. Zeolite includes a comprehensive yet easy to use library of functions for accessing and manipulating map data, including all mosaic map functions for handling ultra-large maps.
2. Full data access. Zeolite has complete access to the map data in L3DT, including the maps themselves, the settings used to create them, flags, etc.
3. Extensible file format support. All file formats supported by L3DT are handled by Zeolite plugins, and all Zeolite plugins can load/save maps in these formats using a simple function interface (e.g. zmap_LoadFile / zmap_SaveFile).
4. Direct memory access. Although Zeolite provides safe interfaces for accessing data, it also allows you to directly access memory for maps and other data (e.g. zmap_GetDataPtr and zvar_GetDataPtr). This may be useful in time-critical sections, or when dealing with 3rd-party libraries that use memory access, such as image and compression libraries.
5. Extensibile function support. All plugins can add functions that can be called by other plugins. Thus, developers can easily share functions with other developers. Importantly, to use a function from another plugin, you don't have to link to that plugin or the libraries that it uses; all function access is through the Zeolite interface (e.g. zfunc_Execute).
6. C++ wrappers. To enable simple object-oriented programming, the Zeolite API includes several C++ 'wrapper' classes for common data types, such as maps, file formats, variable lists, buffers, etc.

Zeolite is written in an API style similar to that of the Win32 API. Data is referenced by handles (ZVARs), which are passed as arguments to API functions that manipulate the data. For example, to get the value of the first pixel in the heightfield, the following code is used:

ZVAR hMap = zproj_GetMap("HF"); // get the heightfield handle
float f;
zmap_GetPixel(hMap, 0, 0, &f); // get the pixel value at coord 0,0

Architecturally, ZVAR is a handle to a polymorphic variable object in L3DT that may contain many different types of data. The currently defined list of types (listed here) contains basic data types such as int, float, etc. Also defined are class data types such as map, list, string, etc. In general, you can directly set/get the data from basic types (using zvar_GetValue / zvar_SetValue), but to access class types you must use the relevant API functions (e.g. zstr_SetText, to set the value of a string).

In dealing with polymorphic variables, it is often necessary to determine the actual data type of the variable. For this we use the zvar_GetTypeID function, which returns an integer containing the type ID number of the variable. The same variable IDs are used when creating or getting/setting variable data (e.g. zvar_Create, zvar_GetValueEx / zvar_SetValueEx). Several handle types have also been defined that correspond to particular variable type IDs. For example, a ZMAP handle is a typedef of a ZVAR handle to a variable that has been initialised with a type of VarID_map. Similarly, there are specific handles for lists (ZLIST), file formats (ZFORMAT), extension functions (ZFUNC), etc. However, it should be noted that these data handles are just for display purposes, as they are all in fact typedefs of void*. Thus, casting from one type of handle to another (e.g. ZMAP to ZFORMAT) will have no affect on the data referenced by the variable handle.

Included with the Zeolite API are wrapper classes, which are analogous to the familiar MFC classes that wrap the Win32 API functions and data. These classes, such as CzVar, CzMap, CzList, etc allow programmers to use the Zeolite API in the familiar object-oriented paradigm. They contain a variable handle and the relevant member functions required to manipulate that data (e.g. CzList::nItems is a wrapper for the zlist_nItems function).

Plugins are compiled Windows dynamic linked libraries with an extension of '.dll', '.zeo' or '.x64.zeo' (case insensitive).

• The complete list of Zeolite API functions is on-line here.
• The complete list of Zeolite API classes is on-line here.
• A tutorial on how to build a new plugin is on-line here.