Unity C++ Native Plugin Examples

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