Set a variable to be a reference (alias) of another variable.
Declaration | Zeolite.h |
---|---|
Implementation | Zeolite.cpp |
bool zvar_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. |
False if an error occurred, and true otherwise.
This function is normally used to pass values by reference to functions when they either cannot be copied using zvar_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.
If hPtrVar is not initialised as the variable type of hSrcVar, it will be automatically re-allocated as the appropriate type.
This function does not change the name of hPtrVar, so hPtrVar and hSrcVar may have different names.
The zvar_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 = zvar_Create(VarID_varlist); if(!hArgs) { return false; } // get a handle to the heightfield in the project ZVAR hMap = zproj_GetMap("HF"); if(!hMap) { return false; } // create a map handle in the function argument list ZVAR hMap2 = zlist_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 "HF" (the project heightfield) if(!zvar_SetVarRef(hMap2, hMap)) { return false; } // set the radius double radius = 6400*1000; // radius of earth ZVAR hRad = zlist_CreateItem(hArgs, VarID_double, "radius"); if(!hRad) { return false; } if(!zvar_SetValue(hRad, &radius)) { return false; } if(!zvar_EditUI(hRad, "Enter sphere radius in metres", NULL, NULL)) { bool TempBool = false; zvar_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 zvar_Delete(hArgs); // all done, lets go home return rval;