Foreign Function Interface

Functions for interacting with the scripting engine inside VRTree.

Functions


void VRFFIFree(HFFIVar var)

Deletes the memory allocated for this FFI variable and closes the handle.


const double * VRFFIGetAABB(HFFIVar var)

Reads the AABB contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type AABB

Returns

pointer to array of 6 doubles containing the values (min xyz, max xyz)

Caution

the return value is only valid until the next call to VRFFIGetAABB with ANY HFFIVar.


Reads the boolean value contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Bool

Returns

0 if false, 1 if true


double VRFFIGetDouble(HFFIVar var)

Reads the double value contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Double

Returns

double value


HFFIVar VRFFIGetEventRegister(const char * registerName)

Reads the value from an event register during a call to a registered event function. These are the equivalent to the values provided to an event script such as __Self and __Other.

Parameters
registerName

the register to get the value from

Returns

a new FFI variant handle representing the value


Reads the integer value contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Int

Returns

integer value


const double * VRFFIGetMat3(HFFIVar var)

Reads the mat3 contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Mat3

Returns

pointer to array of 9 doubles containing the values.

Caution

the return value is only valid until the next call to VRFFIGetMat3 with ANY HFFIVar.


const double * VRFFIGetMat4(HFFIVar var)

Reads the mat4 contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Mat4

Returns

pointer to array of 16 doubles containing the values.

Caution

the return value is only valid until the next call to VRFFIGetMat4 with ANY HFFIVar.


Reads the node contained in the FFI variable and returns a new handle to it.

Parameters
var

FFI variant handle, must be of type Node

Returns

new node handle to the node contained in the var

See Also

VRCloseNodeHandle

Note

the FFI var need not remain valid in order for the returned node handle to remain open.


const double * VRFFIGetPlane(HFFIVar var)

Reads the plane contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Plane

Returns

pointer to array of 4 doubles containing the values (normal xyz, distance)

Caution

the return value is only valid until the next call to VRFFIGetPlane with ANY HFFIVar.


const double * VRFFIGetQuat(HFFIVar var)

Reads the quaternion contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Quat

Returns

pointer to array of 4 doubles containing the values (vector xyz, angle)

Caution

the return value is only valid until the next call to VRFFIGetQuat with ANY HFFIVar.


const double * VRFFIGetRay(HFFIVar var)

Reads the ray contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Ray

Returns

pointer to array of 6 doubles containing the values (origin xyz, direction xyz)

Caution

the return value is only valid until the next call to VRFFIGetRay with ANY HFFIVar.


const double * VRFFIGetSphere(HFFIVar var)

Reads the sphere contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Sphere

Returns

pointer to array of 4 doubles containing the values (centre xyz, radius)

Caution

the return value is only valid until the next call to VRFFIGetSphere with ANY HFFIVar.


const char * VRFFIGetString(HFFIVar var)

Reads the string value contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type String

Returns

null terminated string, may be UTF-8 encoded.

Caution

the return value is only valid for the lifetime of the FFI variant. Using this string pointer after calling VRFFIFree on this var, without first copying it, will result in undefined behaviour.


Identifies the type of variable.

Parameters
var

FFI variant handle

Returns

the type of the variable (direct enum conversion)

Note

due to the return value being based on an enum, the representation may change between API versions. Thus, it is recommended to only use this compare types against other variants.


const double * VRFFIGetVec2(HFFIVar var)

Reads the vec2 contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Vec2

Returns

pointer to array of 2 doubles containing the values.

Caution

the return value is only valid until the next call to VRFFIGetVec2 with ANY HFFIVar.


const double * VRFFIGetVec3(HFFIVar var)

Reads the vec3 contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Vec3

Returns

pointer to array of 3 doubles containing the values.

Caution

the return value is only valid until the next call to VRFFIGetVec3 with ANY HFFIVar.


const double * VRFFIGetVec4(HFFIVar var)

Reads the vec4 contained in the FFI variable and returns it.

Parameters
var

FFI variant handle, must be of type Vec4

Returns

pointer to array of 4 doubles containing the values.

Caution

the return value is only valid until the next call to VRFFIGetVec4 with ANY HFFIVar.


HFFIVar VRFFIInvoke(const char * func,
HFFIVar * args,
int nArgs
)

Calls a named function in the scripting environment.

Parameters
func

The name of the method to call

args

Array of HFFIVar handles representing the function parameters (pushed in array order). The array may contain null entries, in which case a nil variant will be substituted for the call.

nArgs

number of arguments in the args array

Returns

a new variant handle containing the return value from the function. This will need to be VRFFIFree'd after use.

Note

this function, being C, is limited to returning only one value, so calling a FFI function that returns multiple values will only return the first value returned by the FFI function. The rest of the return values are currently discarded.


HFFIVar VRFFIMakeAABB(const double * values)

Creates an AABB (6 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 6 doubles (min xyz, max xyz)

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeBool(char value)

Creates a boolean FFI variable and returns it.

Parameters
value

the value to wrap in the variant. any value other than zero results in a true boolean value.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeDouble(double value)

Creates a number FFI variable and returns it.

Parameters
value

the value to wrap in the variant.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeInt(int value)

Creates a number FFI variable and returns it.

Parameters
value

the value to wrap in the variant.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeMat3(const double * values)

Creates a mat3 (9 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 9 doubles.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeMat4(const double * values)

Creates a mat4 (16 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 16 doubles.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


Wraps a node handle in an FFI variable.

Parameters
handle

valid node handle

Returns

a new FFI variant handle representing the node

See Also

VRFFIFree(HFFIVar)

Note

The node handle need not remain open in order for the returned var to remain valid.


HFFIVar VRFFIMakePlane(const double * values)

Creates a plane (4 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 4 doubles (normal xyz, distance)

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeQuat(const double * values)

Creates a quaternion (4 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 4 doubles (vector xyz, angle)

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeRay(const double * values)

Creates a ray (6 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 6 doubles (origin xyz, direction xyz)

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeSphere(const double * values)

Creates a sphere (4 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 4 doubles (centre xyz, radius)

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeString(const char * value)

Creates a string FFI variable and returns it.

Parameters
value

the value to wrap in the variant.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeVec2(const double * values)

Creates a vec2 (2 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 2 doubles.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeVec3(const double * values)

Creates a vec3 (3 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 3 doubles.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


HFFIVar VRFFIMakeVec4(const double * values)

Creates a vec4 (4 doubles in an array)

Parameters
values

to wrap in the variant. expects an array of 4 doubles.

Returns

a new FFI variant handle representing the value

See Also

VRFFIFree(HFFIVar)


int VRFFIRegister(const char * funcName,
FFIFunc func,
int minArgc,
void * userData
)

Registers a function as a global Lua function in the main script environment. This function becomes a first-class Lua function callable by any Lua code in events or other plugins.

Parameters
funcName

The name of the function as it should appear in the Lua state

func

The function to call when invoked from the Lua state

minArgc

minimuim number of arguments expected

userData

Userdata which is passed back to func when it is invoked.

Returns

0 if successful, non-zero if a function with this name already exists.

Note

currently you can only register functions in the global scope, and only if they don't already exist.


int VRFFIUnregister(const char * funcName,
FFIFunc func
)

Unregisters a previously registered FFIFunc.

Returns

0 if successful


void VRRegisterEventFunction(const char * name,
ScriptEventFunc func,
void * userData
)

Registers a C function with a name which can then be used to call the function in direct response to an Event (e.g. Create, Activate, Timestep, etc)

Parameters
name

The name with which to register the function.

func

The function to register

userData

arbitrary data to pass to the callback

See Also

VRUnregisterEventFunction(const char*)


void VRUnregisterEventFunction(const char * name)

Unregisters a previously registered event function.

Parameters
name

the name of the function to unregister (as it was registered).

No Results.

Getting StartedArchitectureBest PracticesHow ToAdvanced TopicsChangelogvrtree_cppCoreForeign Function InterfaceMetanodesMigrationsObserversPropertiesTreeUtilitiesAPI DefinitionsVR ExchangePluginsLua API