L3DT documentation
Large 3D terrain generator



Set a variable to be a reference/alias of another variable.

Function prototype

bool CExtAPI::var_SetVarRef(ZVAR hPtrVar, ZVAR hSrcVar);


Name Type Comment
hPtrVar ZVAR A ZVAR handle to a variable, which will become the reference/alias of hSrcVar.
hSrcVar ZVAR A ZVAR handle to a variable, which is to be referenced by hPtrVar.

Return value

False if an error occurred, and true otherwise.


Use this function for...

This function is normally used to pass values by reference to functions when they either cannot be copied using var_CopyValue (such as a map), or when it is excessively wasteful to do so (such as for a very large varlist.) Please refer to the example provided below.

Automatic initialisation

If hPtrVar is not initialised as the variable type of hSrcVar, it will be automatically re-allocated as the appropriate type.

Name is not changed

This function does not change the name of hPtrVar, so hPtrVar and hSrcVar may have different names.

Using var_Delete

The var_Delete function may be safely used on variables that are references of another, as the real instance of the data is only deleted from the original variable.


This example was taken from the SphericalDistort plugin:

// create a temporary list to hold the arguments for the SphericalDistort function
ZLIST hArgs = theAPI.var_CreateTemp(VarID_varlist);
if(!hArgs) {
    return false;

// get a handle to the heightfield in the project
ZVAR hMap = theAPI.map_GetMap("project.HF");
if(!hMap) {
    return false;

// create a map handle in the function argument list
ZVAR hMap2 = theAPI.list_CreateItem(hArgs, VarID_map, "hMap");
if(!hMap2) {
    return false;

// Use SetVarRef to make "hMap" in the function argument list point to the data 
// of the map at "project.HF" (the project heightfield)
if(!theAPI.var_SetVarRef(hMap2, hMap)) {
    return false;

// set the radius
double radius = 6400*1000; // radius of earth
ZVAR hRad = theAPI.list_CreateItem(hArgs, VarID_double, "radius");
if(!hRad) {
    return false;
if(!theAPI.var_SetValue(hRad, &radius)) {
    return false;
if(!theAPI.var_EditUI(hRad, "Enter sphere radius in metres")) {
    bool TempBool = false;
    theAPI.var_SetValue(hRval, &TempBool);
    return true; // function returned safely, but the zeolite rval is OK

// now pass the argument list to the function and execute it
bool rval = SphericalDistort(hRval, hArgs);

// delete the temporary argument list

// all done, lets go home
return rval;
zeolite/functions/var_setvarref.txt · Last modified: 2017/08/31 05:43 (external edit)
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki