L3DT documentation
Large 3D terrain generator

zvar_GetValue

Description

Retrieve the value of a variable.

Files

Declaration Zeolite.h
Implementation Zeolite.cpp

Function prototype

bool zvar_GetValue(ZVAR hVar, void* pValue);

Arguments

Name Type Comment
hVar ZVAR A ZVAR handle to a variable, the value of which is to be retrieved.
pValue void* A user-supplied handle to an allocated block of memory for the appropriate data type, ready to receive the value from the ZVAR.

Return value

False if:

  1. hVar does not reference a valid variable (e.g. is null).
  2. pValue is null.
  3. The variable referenced by hVar is not initialised.
  4. The variable type of hVar cannot be copied (see comments below.)

True otherwise.

Comments

Check the variable type, or use var_GetValueEx

Before retrieving the value of a variable it is strongly recommended that you check the type using zvar_IsType (see example below.) This is to ensure that the variable type is what you think it is, so that your pValue handle is the correct storage type. If, for instance, you don't check the variable type and provide a pValue handle to a char data type (1 byte) when the variable is actually a long (4 bytes), you will have corrupted memory somewhere and the world may end.

Alternatively, you can use the zvar_GetValueEx function, which includes a test of the variable type.

Incompatible types

The following variable types are not compatible with zvar_GetValue (and zvar_SetValue, var_GetValueEx and zvar_SetValueEx):

Type Reason
VarID_void Voids contain no data, and hence no value to retrieve.
VarID_string Strings are stored in a funny way. Use the 'zstr_' API functions to read/write the values.
All class types. Class objects do not necessarily contain a single value. Use the relevant API functions to access member data instead (i.g. 'zmap_', 'zvar_', etc.).

Example

// get a variable called 'radius'
ZVAR hVar = zvar_GetSharedVar("radius");

// check it is the correct type (a double, in this example)
if(!zvar_IsType(hVar, VarID_double)) {
   zeoReportError("Incorrect variable type!");
   return false;
}

// get the value using zvar_GetValue
double radius;
if(!zvar_GetValue(hVar, &radius)) {
   ReportError("Cannot retrieve variable data!");
   return false;
}

// now use radius for something...
 
zeolite/functions/zvar_getvalue.txt · Last modified: 2017/08/31 07:16 (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