Unity C++ Native Plugin Examples
October 30, 2017 Leave a comment
Unity scripting environment runs C# Mono container which supports native C/C++ plugins with Mono PInvoke. This allows easy integration of native library functions to both pass and receive data between Unity managed C# and native platform code.
Basic concept is simple. Native function descriptor that specify calling convention and dynamically loaded library (DDL) tell Mono how it’s parameters and returns values should be converted. Mono handles things mostly automatically from there on.
Some care is required to do this efficiently. C# PInvoke defines marshaling as a protocol to serialize and deserialize managed objects back and forth towards native code. This may generate lot of overhead. Mono garbage collector might accidentally destroy memory of an object while it’s used in the native code space.
Example C++ code is for a native Win32 plugin but is trivial to port to any platform.
Basic Data
Passing simple integral types, integers and arrays of them is straightforward.
Native c code.
extern "C" {
#define PLUGINEX(rtype) UNITY_INTERFACE_EXPORT rtype UNITY_INTERFACE_API
PLUGINEX(int) ReturnInt()
{
return 0xBABE;
}
PLUGINEX(void) AcceptArray1(char *arr, int length)
{
for (int i = 0; i < length; i++) {
arr[i] = 'A' + i;
}
}
}
C# declarations and example calling code.
[DllImport("ptest")]
private static extern int ReturnInt();
[DllImport("ptest")]
private static extern void AcceptArray1([In, Out] byte[] arr, int length);
void TestIntegral() {
// return int
print(ReturnInt());
// accept byte array, uses marshaling to pass array back and forth
byte[] arr1 = { 0, 0, 0 };
AcceptArray1(arr1, arr1.Length);
for (int i = 0; i < arr1.Length; i++)
{
print("arr" + i + "=" + arr1[i]);
}
}
Strings
Strings are passed and returned as character arrays. It’s possible to use automatic marshaling conversions and return dynamically allocated strings that will be automatically deallocated.
Native c code.
extern "C" {
#define PLUGINEX(rtype) UNITY_INTERFACE_EXPORT rtype UNITY_INTERFACE_API
PLUGINEX(bool) AcceptStr(LPCSTR pStr)
{
return !strcmp(pStr, "FOO");
}
PLUGINEX(LPSTR) ReturnDynamicStr()
{
LPSTR str = (LPSTR)CoTaskMemAlloc(512);
strcpy_s(str, 512, "Dynamic string");
return str;
}
PLUGINEX(LPCSTR) ReturnConstStr()
{
return "Constant string";
}
}
C# declarations and example calling code.
[DllImport("ptest")]
private static extern bool AcceptStr([MarshalAs(UnmanagedType.LPStr)] string ansiStr);
// automatically deallocates the return string with CoTaskMemFree
[DllImport("ptest")]
[return: MarshalAs(UnmanagedType.LPStr)]
private static extern string ReturnDynamicStr();
[DllImport("ptest")]
private static extern IntPtr ReturnConstStr();
void TestStrings() {
// accept string
bool r1 = AcceptStr("BAR");
bool r2 = AcceptStr("FOO");
print("r1=" + r1); // r1=false
print("r2=" + r2); // r1=true
// return dynamically allocated string
string s1 = ReturnDynamicStr();
print("s1=" + s1);
// return constant string
string s2 = Marshal.PtrToStringAnsi(ReturnConstStr());
print("s2=" + s2);
}
Arrays
Both dynamic and constant arrays can be supported but some helper functions are needed.
Native c code.
extern "C" {
#define PLUGINEX(rtype) UNITY_INTERFACE_EXPORT rtype UNITY_INTERFACE_API
PLUGINEX(void) AcceptArray1(char *arr, int length)
{
for (int i = 0; i < length; i++) {
arr[i] = 'A' + i;
}
}
PLUGINEX(void) AcceptArray2(char *arr, int length)
{
for (int i = 0; i < length; i++) {
arr[i] = 'A' + i;
}
}
PLUGINEX(int) AcceptStrArray(const char* const *strArray, int size)
{
int total = 0;
for (int i = 0; i < size; i++) {
auto str = strArray[i];
total += (int)strlen(str);
}
// return total length of the strings in the array to demonstrate that
// it was passed correctly
return total;
}
PLUGINEX(LPBYTE) ReturnDynamicByteArray(int &pSize)
{
pSize = 0xFF;
LPBYTE pData = (LPBYTE)CoTaskMemAlloc(pSize);
// fill with example data
for (int i = 0; i < pSize; i++) {
pData[i] = i + 1;
}
return pData;
}
PLUGINEX(LPSTR*) ReturnDynamicStrArray(int &pSize)
{
// Allocate an array with pointers to 3 dynamically allocated strings
pSize = 3;
LPSTR* pData = (LPSTR*)CoTaskMemAlloc((pSize)*sizeof(LPSTR));
pData[0] = (LPSTR)CoTaskMemAlloc(128);
pData[1] = (LPSTR)CoTaskMemAlloc(128);
pData[2] = (LPSTR)CoTaskMemAlloc(128);
strcpy_s(pData[0], 128, "String 1");
strcpy_s(pData[1], 128, "String 2");
strcpy_s(pData[2], 128, "String 3");
return pData;
}
}
C# declarations and example calling code.
[DllImport("ptest")]
private static extern void AcceptArray1(IntPtr arr, int length);
[DllImport("ptest")]
private static extern void AcceptArray2(IntPtr arr, int length);
[DllImport("ptest")]
private static extern int AcceptStrArray(IntPtr array, int size);
[DllImport("ptest")]
private static extern IntPtr ReturnDynamicByteArray(ref int size);
[DllImport("ptest")]
private static extern IntPtr ReturnDynamicStrArray(ref int size);
///// Helper functions for marshalling /////
// Convert and copy array of strings to raw memory
private static IntPtr MarshalStringArray(string[] strArr)
{
IntPtr[] dataArr = new IntPtr[strArr.Length];
for (int i = 0; i < strArr.Length; i++)
{
dataArr[i] = Marshal.StringToCoTaskMemAnsi(strArr[i]);
}
IntPtr dataNative = Marshal.AllocCoTaskMem(Marshal.SizeOf(typeof(IntPtr)) * strArr.Length);
Marshal.Copy(dataArr, 0, dataNative, dataArr.Length);
return dataNative;
}
// Decodes string array from raw pointer
private static string[] MarshalStringArray(IntPtr dataPtr, int arraySize)
{
var dataPtrArray = new IntPtr[arraySize];
var strArray = new String[arraySize];
Marshal.Copy(dataPtr, dataPtrArray, 0, arraySize);
for (int i = 0; i < arraySize; i++)
{
strArray[i] = Marshal.PtrToStringAnsi(dataPtrArray[i]);
Marshal.FreeCoTaskMem(dataPtrArray[i]);
}
Marshal.FreeCoTaskMem(dataPtr);
return strArray;
}
// Dellocates encoded string array
private static void CleanUpNativeStrArray(IntPtr dataPtr, int arraySize)
{
var dataPtrArray = new IntPtr[arraySize];
Marshal.Copy(dataPtr, dataPtrArray, 0, arraySize);
for (int i = 0; i < arraySize; i++)
{
Marshal.FreeCoTaskMem(dataPtrArray[i]);
}
Marshal.FreeCoTaskMem(dataPtr);
}
void TestArrays() {
// accept byte array, uses marshalling to pass array back and forth
byte[] arr1 = { 0, 0, 0 };
AcceptArray1(arr1, arr1.Length);
for (int i = 0; i < arr1.Length; i++)
{
print("arr" + i + "=" + arr1[i]);
}
// accept byte array, passes no-copy raw memory pointer
byte[] arr2 = { 0, 0, 0 };
GCHandle h = GCHandle.Alloc(arr2, GCHandleType.Pinned);
AcceptArray2(h.AddrOfPinnedObject(), arr2.Length);
for (int i = 0; i < arr2.Length; i++)
{
print("arr" + i + "=" + arr2[i]);
}
h.Free();
// return dynamically allocated byte array
int arraySize = 0;
IntPtr dataPtr = ReturnDynamicByteArray(ref arraySize);
byte[] data = new byte[arraySize];
Marshal.Copy(dataPtr, data, 0, arraySize);
Marshal.FreeCoTaskMem(dataPtr); // deallocate unmanaged memory
print("data["+arraySize+"] = [" + data[0] + ", " + data[1] + ", " + data[2] + ",...]");
// return dynamically allocated string array
arraySize = 0;
dataPtr = ReturnDynamicStrArray(ref arraySize);
String[] strArray = MarshalStringArray(dataPtr, arraySize);
print("strArray["+arraySize+"] = [" + String.Join(",", strArray) + "]");
// string array as parameter
dataPtr = MarshalStringArray(new String[] { "foo1", "foo2", "foo3" });
int len = AcceptStrArray(dataPtr, arraySize);
print("len=" + len);
CleanUpNativeStrArray(dataPtr, arraySize);
}
Structures and Arrays of Structures
Array handling is similar to the string arrays. Most objects can be passed as is but if they have array properties those must be of fixed size.
Native c code.
extern "C" {
#define PLUGINEX(rtype) UNITY_INTERFACE_EXPORT rtype UNITY_INTERFACE_API
struct ExampleStruct {
INT16 val1;
INT32 array1[3];
INT16 array2len;
INT32 array2[10];
LPSTR str1;
};
PLUGINEX(int) AcceptStruct(ExampleStruct &s)
{
// Modify struct
s.val1 -= 1111;
for (int i= 0; i < 3; i++) {
s.array1[i] += 1;
}
for (int i = 0; i < s.array2len; i++) {
s.array2[i] += 10;
}
// return length of the string in the argument struct to demonstrate that
// it was passed correctly
return (int)strlen(s.str1);
}
struct ExamplePoint {
FLOAT x;
FLOAT y;
FLOAT z;
};
PLUGINEX(ExamplePoint *) ReturnArrayOfPoints(int &size)
{
size = 4;
ExamplePoint *pointArr = (ExamplePoint*)CoTaskMemAlloc(sizeof(ExamplePoint) * size);
// fill with some example data
for (int i = 0; i < size; i++) {
pointArr[i] = { i + 0.1f, i + 0.2f, i + 0.3f };
}
return pointArr;
}
// this return type is blittable
// https://stackoverflow.com/questions/10320502/c-sharp-calling-c-function-that-returns-struct-with-fixed-size-char-array
//
PLUGINEX(ExamplePoint) ReturnStruct()
{
return { 1, 2, 3 };
}
}
C# declarations and example calling code.
[StructLayout(LayoutKind.Sequential)]
public struct ExamplePoint
{
public float x;
public float y;
public float z;
// for debugging
public override String ToString()
{
return "{" + x + ","+ y + "," + z + "}";
}
}
[DllImport("ptest")]
private static extern IntPtr ReturnArrayOfPoints(ref int size);
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
public struct ExampleStruct
{
public UInt16 val1;
[MarshalAsAttribute(UnmanagedType.ByValArray, SizeConst = 3)]
public UInt32[] array1;
public UInt16 array2len;
[MarshalAsAttribute(UnmanagedType.ByValArray, SizeConst = 10)]
public UInt32[] array2;
[MarshalAs(UnmanagedType.LPStr)]
public string str1;
}
[DllImport("ptest")]
private static extern int AcceptStruct(ref ExampleStruct s);
[DllImport("ptest")]
private static extern ExamplePoint ReturnStruct();
void TestStructures() {
// Structure as parameter
ExampleStruct s = new ExampleStruct
{
val1 = 9999,
array1 = new UInt32[3],
array2 = new UInt32[10]
};
s.array1[0] = 1;
s.array1[1] = 2;
s.array1[2] = 3;
s.array2len = 5;
s.array2[0] = 10;
s.array2[1] = 11;
s.array2[2] = 12;
s.array2[3] = 13;
s.array2[4] = 14;
s.str1 = "Cat is a feline";
len = AcceptStruct(ref s);
print("s.val1=" + s.val1 + " len=" + len);
// return struct
ExamplePoint p = ReturnStruct();
// Marshal array of point objects
arraySize = 0;
dataPtr = ReturnArrayOfPoints(ref arraySize);
ExamplePoint[] pointArr = new ExamplePoint[arraySize];
// memory layout
// |float|float|float|float|float|float|float|float|float|float..
// | ExamplePoint0 | ExamplePoint1 | ExamplePoint2 |
int offset = 0;
int pointSize = Marshal.SizeOf(typeof(ExamplePoint));
for(int i=0; i < arraySize; i++)
{
pointArr[i] = (ExamplePoint)Marshal.PtrToStructure(new IntPtr(dataPtr.ToInt32() + offset), typeof(ExamplePoint));
offset += pointSize;
}
print("pointArr["+arraySize+"]=["+pointArr[0]+", "+pointArr[1]+",...]");
Marshal.FreeCoTaskMem(dataPtr);
}
Many of these examples can be done in cleaner way using MarshalAsAttribute. Code above does show what is happening under the hood.
Get full implementation ftom https://github.com/tikonen/blog/tree/master/unityplugin
Brave New Method 