Foreign Function Interface

Functions for interacting with the scripting engine inside VRTree.

Functions

Type	Name
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.
char	VRFFIGetBool(HFFIVar var) Reads the boolean value contained in the FFI variable and returns it.
double	VRFFIGetDouble(HFFIVar var) Reads the double value contained in the FFI variable and returns it.
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.
int	VRFFIGetInt(HFFIVar var) Reads the integer value contained in the FFI variable and returns it.
const double *	VRFFIGetMat3(HFFIVar var) Reads the mat3 contained in the FFI variable and returns it.
const double *	VRFFIGetMat4(HFFIVar var) Reads the mat4 contained in the FFI variable and returns it.
HNode	VRFFIGetNode(HFFIVar var) Reads the node contained in the FFI variable and returns a new handle to it.
const double *	VRFFIGetPlane(HFFIVar var) Reads the plane contained in the FFI variable and returns it.
const double *	VRFFIGetQuat(HFFIVar var) Reads the quaternion contained in the FFI variable and returns it.
const double *	VRFFIGetRay(HFFIVar var) Reads the ray contained in the FFI variable and returns it.
const double *	VRFFIGetSphere(HFFIVar var) Reads the sphere contained in the FFI variable and returns it.
const char *	VRFFIGetString(HFFIVar var) Reads the string value contained in the FFI variable and returns it.
int	VRFFIGetType(HFFIVar var) Identifies the type of variable.
const double *	VRFFIGetVec2(HFFIVar var) Reads the vec2 contained in the FFI variable and returns it.
const double *	VRFFIGetVec3(HFFIVar var) Reads the vec3 contained in the FFI variable and returns it.
const double *	VRFFIGetVec4(HFFIVar var) Reads the vec4 contained in the FFI variable and returns it.
HFFIVar	VRFFIInvoke(const char * func, HFFIVar * args, int nArgs) Calls a named function in the scripting environment.
HFFIVar	VRFFIMakeAABB(const double * values) Creates an AABB (6 doubles in an array)
HFFIVar	VRFFIMakeBool(char value) Creates a boolean FFI variable and returns it.
HFFIVar	VRFFIMakeDouble(double value) Creates a number FFI variable and returns it.
HFFIVar	VRFFIMakeInt(int value) Creates a number FFI variable and returns it.
HFFIVar	VRFFIMakeMat3(const double * values) Creates a mat3 (9 doubles in an array)
HFFIVar	VRFFIMakeMat4(const double * values) Creates a mat4 (16 doubles in an array)
HFFIVar	VRFFIMakeNode(HNode handle) Wraps a node handle in an FFI variable.
HFFIVar	VRFFIMakePlane(const double * values) Creates a plane (4 doubles in an array)
HFFIVar	VRFFIMakeQuat(const double * values) Creates a quaternion (4 doubles in an array)
HFFIVar	VRFFIMakeRay(const double * values) Creates a ray (6 doubles in an array)
HFFIVar	VRFFIMakeSphere(const double * values) Creates a sphere (4 doubles in an array)
HFFIVar	VRFFIMakeString(const char * value) Creates a string FFI variable and returns it.
HFFIVar	VRFFIMakeVec2(const double * values) Creates a vec2 (2 doubles in an array)
HFFIVar	VRFFIMakeVec3(const double * values) Creates a vec3 (3 doubles in an array)
HFFIVar	VRFFIMakeVec4(const double * values) Creates a vec4 (4 doubles in an array)
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.
int	VRFFIUnregister(const char * funcName, FFIFunc func) Unregisters a previously registered FFIFunc.
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)
void	VRUnregisterEventFunction(const char * name) Unregisters a previously registered event function.

Functions Documentation

VRFFIFree

void VRFFIFree(
    HFFIVar var
)

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

VRFFIGetAABB

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

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

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

VRFFIGetBool

char VRFFIGetBool(
    HFFIVar var
)

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

Parameters:

• var FFI variant handle, must be of type Bool

Return: 0 if false, 1 if true

VRFFIGetDouble

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

Return: double value

VRFFIGetEventRegister

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

Return: a new FFI variant handle representing the value

VRFFIGetInt

int VRFFIGetInt(
    HFFIVar var
)

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

Parameters:

• var FFI variant handle, must be of type Int

Return: integer value

VRFFIGetMat3

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

Return: pointer to array of 9 doubles containing the values.

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

VRFFIGetMat4

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

Return: pointer to array of 16 doubles containing the values.

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

VRFFIGetNode

HNode VRFFIGetNode(
    HFFIVar var
)

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

See: VRCloseNodeHandle

Return: new node handle to the node contained in the var

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

VRFFIGetPlane

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

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

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

VRFFIGetQuat

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

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

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

VRFFIGetRay

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

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

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

VRFFIGetSphere

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

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

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

VRFFIGetString

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

Return: null terminated string, may be UTF-8 encoded.

Warning: 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.

VRFFIGetType

int VRFFIGetType(
    HFFIVar var
)

Identifies the type of variable.

Parameters:

• var FFI variant handle

Return: 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.

VRFFIGetVec2

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

Return: pointer to array of 2 doubles containing the values.

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

VRFFIGetVec3

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

Return: pointer to array of 3 doubles containing the values.

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

VRFFIGetVec4

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

Return: pointer to array of 4 doubles containing the values.

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

VRFFIInvoke

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

Return: 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.

VRFFIMakeAABB

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)

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeBool

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeDouble

HFFIVar VRFFIMakeDouble(
    double value
)

Creates a number FFI variable and returns it.

Parameters:

• value the value to wrap in the variant.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeInt

HFFIVar VRFFIMakeInt(
    int value
)

Creates a number FFI variable and returns it.

Parameters:

• value the value to wrap in the variant.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeMat3

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeMat4

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeNode

HFFIVar VRFFIMakeNode(
    HNode handle
)

Wraps a node handle in an FFI variable.

Parameters:

• handle valid node handle

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the node

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

VRFFIMakePlane

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)

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeQuat

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)

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeRay

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)

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeSphere

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)

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeString

HFFIVar VRFFIMakeString(
    const char * value
)

Creates a string FFI variable and returns it.

Parameters:

• value the value to wrap in the variant.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeVec2

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeVec3

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIMakeVec4

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.

See: VRFFIFree(HFFIVar)

Return: a new FFI variant handle representing the value

VRFFIRegister

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.

Return: 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.

VRFFIUnregister

int VRFFIUnregister(
    const char * funcName,
    FFIFunc func
)

Unregisters a previously registered FFIFunc.

Return: 0 if successful

VRRegisterEventFunction

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: VRUnregisterEventFunction(const char*)

VRUnregisterEventFunction

void VRUnregisterEventFunction(
    const char * name
)

Unregisters a previously registered event function.

Parameters:

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