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.

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

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

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

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.

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

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.

int VRFFIGetType(

HFFIVar

var

)

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)

HFFIVar VRFFIMakeNode(

HNode

handle

)

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).