====== atFuncBrowser ======



===== Plugin information ===

^  Author | [[user>Aaron]] |
^  Description | atFuncBrowser is a simple plugin that lets you view the available zeofunc extension functions, which may by called by other plugins using [[bundydocs>zeolite:functions:zeofunc_Execute|zeofunc_Execute]]. |
^  Menu option | '//Extensions->atFuncBrowser->Function browser//' |
^  Download link | Included with L3DT. |
^  Source code | //[[bundydocs>zeolite:downloads:examples|Over here]]//. |




===== About atFuncBrowser =====

The functions provided in the Zeolite API ([[bundydocs>zeolite:functions|see here]]) are the low-level 'core' functions used to manipulate maps and other data. Complex calculations such as heightfield erosion or texture generation are not included in the core API functions, but may be accessed using the [[bundydocs>zeolite:functions:zeofunc_GetFunc|zeofunc_GetFunc]] and [[bundydocs>zeolite:functions:zeofunc_Execute|zeofunc_Execute]]/[[bundydocs>zeolite:functions:zeofunc_ExecuteThreaded|zeofunc_ExecuteThreaded]] API functions. These 'zeofunc' extension functions may be provided by L3DT, or they may be provided by other plugins. 

However, whilst the core API functions are listed in the [[bundydocs>zeolite:functions|documentation wiki]], there is currently no list of available zeofunc extension functions. Fortunately, the atFuncBrowser plugin can help here. Selecting the '//Extensions->atFuncBrowser->Function browser//' menu option will open the function browser dialog, shown below:

{{ :plugins:general:atfuncbrowser:funcbrowser.png |:plugins:general:atfuncbrowser:funcbrowser.png}}

In this dialog you can see the prototypes of all the available zeofunc extension functions. Note that the functions are nested in a tree, which represent the //namespaces// used to categorize zeofunc extension functions.

For example, the highlighted function:

<code>
string GetBaseTextureNameByID(short InputCode);
</code>

...is nested in the 'classes.landtype' namespace, indicating that it is a member function of the class 'landtype'. To get the function handle for this function, you can do the following:

<code>
ZFUNC hFunc = zfunc_GetFunc("classes.landtype.GetBaseTextureNameByID");
</code>

or, using the CzFunc wrapper:

<code>
CzFunc myfunc;
myfunc.GetFunc("classes.landtype.GetBaseTextureNameByID");
</code>

The argument and return types are given in the function prototype shown in the dialog. In this particular example, the function takes as an argument a 16-bit short integer (an attributes map pixel) and returns a string (containing the full filename of the base texture for the corresponding land type).  This function is used in the [[plugins:calc:atFilterAM]] plugin, and following [[http://www.bundysoft.com/L3DT/downloads/zeolite/atFilterAM-src.zip|this link]] will take you to the source code. File in which the function is used is 'atFilterAM.cpp', and the function is 'ExtAlphaExpress'. That plugin shows how the function is called, but below I will provide a rough example:

<code="C">
// getting a pixel from the attributes map (x=5,y=10 in this example)
CzMap AM;
unsigned short tempshort;
AM.Attach(zproj_GetMap("AM"));
AM.GetPixel(5, 10, &tempshort); 

// getting the function handle
CzFunc landtype_GetBaseTextureNameByID;
landtype_GetBaseTextureNameByID.GetFunc("classes.landtype.GetBaseTextureNameByID");

// declare a string to hold the return value of the function
CzStr Filename;

// setting the argument value
landtype_GetBaseTextureNameByID.SetArgI(0, VarID_ushort, &tempshort);

// calling the function (see 'Execute()'), and attaching Filename to the return value
Filename.Attach(landtype_GetBaseTextureNameByID.Execute());

// showing the return value in a dialog box
AfxMessageBox((LPCSTR)FileName);
</code>

===== Changes =====

**2010/06/01**
  * Alpha-sorted function list.

**2007/10/09**
  * Added function counter.

**2007/07/01**
  * Updated to use L3DT icon.
  * Changed extension to '.zeo'.

**2007/01/01 **
  * Initial release.