Posted on 1 Comment

Using those pointers

In my last post I outlined a way to manage native object lifecycle from C# in Unity. But I skipped one of the conveniences of calling native functions. You can call a function without matching the declared type of the pointer parameters. That means you don’t need to use CFTypeRef everywhere.

The pointer you have in C# is untyped, it is void *. That’s the same as CFTypeRef. But you can declare and call native functions which are your type. Let’s take a look at one of the classes we could build from the last post.

// nativeClass.h
@interface NativeClass
- (instancetype) init;
@end
// nativeClass.m
#import "nativeClass.h"
@implementation NativeClass
- (instancetype) init
{
  // omitted for brevity
}
@end

#if __cplusplus
extern "C" {
#endif
CFTypeRef _createNativeClass()
{
  return CFBridgingRetain([[NativeClass alloc] init]);
}

void _destroyNativeClass(CFTypeRef nativeClassInstance)
{
  CFRelease(nativeClassInstance);
}
#if __cplusplus
}
#endif
// NativeClass.cs
using System;
using System.Runtime.InteropServices;
public class NativeClass : IDisposable
{
  [DllImport("__Internal")]
  static extern IntPtr _createNativeClass();

  [DllImport("__Internal")]
  static extern void _destroyNativeClass(IntPtr nativeClassInstance);

  IntPtr m_Instance;

  public NativeClass()
  {
    m_Instance = _createNativeClass();
  }

  public void Dispose()
  {
    _destroyNativeClass(m_Instance);
  }
}

This is a very basic native class which has its lifecycle controlled from C#. But we can take things a step further with our own functions. Let’s add a method to our objective-c interface.

// nativeClass.h
@interface NativeClass
- (instancetype) init;
- (void)doSomeStuff;
@end

Now we can add an implementation, and provide a C function wrapper. Remember, C# can call C functions, but not objective-c. So we need to write a simple C wrapper for any methods we want to call from C#.

// nativeClass.m
#import "nativeClass.h"
@implementation NativeClass
- (instancetype) init
{
  // omitted for brevity
}

- (void)doSomeStuff
{
  // Only the best algorithm
}
@end

#if __cplusplus
extern "C" {
#endif
CFTypeRef _createNativeClass()
{
  return CFBridgingRetain([[NativeClass alloc] init]);
}

void _destroyNativeClass(CFTypeRef nativeClassInstance)
{
  CFRelease(nativeClassInstance);
}

void _doSomeStuffNativeClass(const NativeClass * instance)
{
  [instance doSomeStuff];
}
#if __cplusplus
}
#endif

Notice the declared pointer type in the function parameters. It is NativeClass * instead of CFTypeRef which was used last time. Yes, this actually works. Finally, let’s add the C# code for this method.

// NativeClass.cs
using System;
using System.Runtime.InteropServices;
public class NativeClass : IDisposable
{
  [DllImport("__Internal")]
  static extern IntPtr _createNativeClass();

  [DllImport("__Internal")]
  static extern void _destroyNativeClass(IntPtr nativeClassInstance);

  [DllImport("__Internal")]
  static extern void _doSomeStuffNativeClass(IntPtr instance);

  IntPtr m_Instance;

  public NativeClass()
  {
    m_Instance = _createNativeClass();
  }

  public void Dispose()
  {
    _destroyNativeClass(m_Instance);
  }

  void DoSomeStuff()
  {
    _doSomeStuffNativeClass(m_Instance);
  }
}

In C#, the pointer remains an IntPtr which is essentially a void * or CFTypeRef. But we can call functions with the proper type declared in the function parameters. That means no casting is needed when we marshal our pointer into native objective-c.

Posted on 1 Comment

Unity iOS Native Pointer Pattern

One common situation I find myself in when developing for Unity on iOS is having to integrate with native APIs. Integrating native features is a nice touch for your apps and makes them feel at home running in iOS. It keeps your users familiar with platform conventions instead of having to learn some UI or workflow specific to your app.

When doing this, you inevitably want to use an API which requires you to hold a reference to a pointer. Let’s say you want to use iCloud ubiquity containers in your app. You need to subscribe to changes in the cloud. This requires a persistent object on the native side to receive notifications from the operating system. The information then needs sent up to Unity and processed by your app. You may start with something like this on the native side.

@interface iCloudMonitor : NSObject

@end
@implementation iCloudMonitor {
	NSMetadataQuery * documentStoreMonitor;
}

-(instancetype)init
{
	if (!(self = [super init])) {
		return nil;
	}
	
	[self startSearch];
	return self;
}

-(void)queryDidUpdate:(NSNotification *)sender
{
	// Do what you need to when iCloud updates, this is just an example
	UnitySendMessage("iCloudMonitor", "DocumentsUpdated", "");
}

-(void)startSearch
{
	documentStoreMonitor = [NSMetadataQuery new];
	documentStoreMonitor.searchScopes = [NSArray arrayWithObjects:NSMetadataQueryUbiquitousDataScope,nil];
	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(queryDidUpdate:) name:NSMetadataQueryDidUpdateNotification object:documentStoreMonitor];
	[documentStoreMonitor startQuery];
}

@end

extern "C" {
	void _createICloudMonitor()
	{
		[[iCloudMonitor alloc] init];
	}
}

This lets you call _createICloudWrapper() from Unity to start monitoring for iCloud changes. But there is a problem. iOS uses a system called Automatic Reference Counting, or ARC, to keep track of when to deallocate objects from memory. I don’t want to go into great depth about ARC here as there are many articles covering it in great detail such as https://www.raywenderlich.com/2992-beginning-arc-in-ios-5-tutorial-part-1. To summarize and simplify, when an object has zero strong references it get deallocated.

The call inside _createICloudMonitor() creates an object, but doesn’t hold a reference to it. As soon as the function returns, ARC will see the object has zero references and deallocate it. You need to keep a reference to the object so it stays around. One option is to make a global variable to keep ARC happy with a reference. This brings all the issues of global variables with it. Another option is to use a singleton, which is slightly better than a global. It keeps ARC happy with a reference, but still has many of the issues of a global variable. A third option is to use the -fno-objc-arc compiler flag to disable ARC on the entire file. But that means we can’t use ARC any where in the file at all. The best option is to transfer the variable out of ARC entirely. This is done through bridging.

Bridging allows us to give the ARC system more information than it can gather on its own. Namely, whether or not the system should deallocate an object. There are two things you can tell the system. One, you can tell it to stop monitoring an object which it previously was. And two, you can tell it to start monitoring an object it wasn’t. Basically you can move ownership of objects between Objective-C land with references and reference counting, and plain old C land with pointers. The function CFBridgingRetain(id) takes a reference and converts it to a CFTypeRef, which is just an alias for void *, and adds one to the retain count. Lets see how to change our code to use this.

	CFTypeRef _createICloudMonitor()
	{
		return CFBridgingRetain([[iCloudMonitor alloc] init]);
	}

Since we have stopped ARC from deallocating this object we need to do it ourselves. Just like in the time before ARC existed, every call to retain required a corresponding call to release. Luckily That function is provided as well. Lets make a function to access it.

	void _destroyICloudMonitor(CFTypeRef monitor)
	{
		CFRelease( monitor );
	}

And that’s everything we need in objective-c land. Now we can make a C# class to use this code. Here is an example of using MonoBehaviour to control the native object. When the MonoBehaviour instance is first loaded it will call into C land to make the native object. And when it is destroyed, it will call to C land again to destroy the native object. This means the native object’s lifecycle follows the MonoBehaviour instance.

using System;
using System.Runtime.InteropServices;
using UnityEngine;

public class iCloudMonitorBehaviour : MonoBehaviour
{
	[DllImport("__Internal")]
	private static extern IntPtr _createICloudMonitor();
	
	[DllImport("__Internal")]
	private static extern void _destroyICloudMonitor();
	
	private IntPtr NativeObject;
	
	void Awake()
	{
		NativeObject = _createICloudMonitor();
	}
	
	void OnDestroy()
	{
		_destroyICloudMonitor(NativeObject);
	}
}

All of this lets us use persistent native objects whose lifecycle is controlled by an object in Unity all without needing extra variables in native land to store the variables. The basics are as follows:

  1. Have a create function to make the object instance we need which bridges that variable out of ARC and returns the pointer to it.
  2. A corresponding destroy function which releases the variable sent to it.
  3. In the C# class have an IntPtr to hold the reference to the object.
  4. Inside Awake call the create function and assign the value to our pointer field.
  5. Inside OnDestroy call the destroy function and send the pointer.

This is applicable anywhere you need to use a persistent native object. Besides that, you can add all the other functions you want.

Alternate C# class

If you want something a bit more flexible than a MonoBehaviour to control the native object, implementing the IDisposable interface works really well too.

using System;
using System.Runtime.InteropServices;

public class iCloudMonitor : IDisposable
{
	[DllImport("__Internal")]
	private static extern IntPtr _createICloudMonitor();
	
	[DllImport("__Internal")]
	private static extern void _destroyICloudMonitor();
	
	private IntPtr NativeObject;
	
	public iCloudMonitor()
	{
		NativeObject = _createICloudMonitor();
	}
	
	public void Dispose()
	{
		_destroyICloudMonitor(NativeObject);
	}
}
Posted on Leave a comment

Unity iOS Plugin Basics

One of my favorite things about Unity is how easy it is to port games to multiple platforms. The simplest of games require no work to target a new platform. Literally none. This makes developing in Unity a time saver because there are very small porting costs.

However keeping the game purely within the engine comes with drawbacks. Primarily, little system integration. Many platforms have features outside of the game which you might want to take advantage of. For instance, iOS has twitter sharing built in to the OS. This is a feature Unity does not implement. So how do we use it? Through the use of plugins.

Plugins allow you to call into code written and potentially compiled outside of Unity. This is extremely powerful because it allows you to do pretty much anything the platform you’re targeting can do. Going back to the iOS twitter example, you can call into the native Cocoa Touch APIs.

Let’s try this out by writing a simple plugin to show a dialog to post to twitter. This API is built into iOS versions 5 and newer. I will be assuming you are targeting at least that version. If you are targeting something older you will need to include checks for the iOS version before calling the API. We need two functions. The first will check whether we can post to twitter. The second to do the posting. The social sharing API is documented at https://developer.apple.com/library/ios/documentation/NetworkingInternet/Reference/SLComposeViewController_Class/Reference/Reference.html. It will come in handy.


The mono runtime makes calls into native code using C standards. Any language that follows the C calling convention can be called. Unfortunately Objective-C does not follow this convention. We will have to wrap Objective-C APIs with C code to make it available to Unity. this is done by putting our calls inside C functions and using a C compiler to compile it. Our file will contain calls into C++ so we need to use a .mm file with Extern "C" { at the top and } at the bottom to avoid name mangling issues.

// Check if c++ compiler
#if __cplusplus
Extern "C" {  // Avoid name mangling issues
#end if

#if __cplusplus
}  // Close Extern C
#endif

Put this file in the Assets/Plugins/iOS/ folder in your project. This is a special folder. When you build for iOS, any native libraries or code in this folder are copied to the Xcode project where they are compiled and linked with the rest of Unity.

Now, in Unity create a new C♯ file. This file will act as the Unity side to the plugin.

// Notice it doesn't extend MonoBehaviour
public class TwitterSharing
{
}

Let’s start by adding a simple call to find out if Twitter is available. SLComposeViewController contains a class method called isAvailableForServiceType to check the availability of a given service. The constant for Twitter is SLServiceTypeTwitter.

// In Social.framework, imports social sharing classes and constants
#import <Social/Social.h>

#if __cplusplus
Extern "C" {
#end if

bool _isTwitterAvailable()
{
    // Returns true when Twitter is available
    return [SLComposeViewController isAvailableForServiceType:SLServiceTypeTwitter];
}

#if __cplusplus
}
#endif

When calling native code, mono “marshals” the parameters and return values. Basically it copies stuff. This is needed because C and C♯ have different memory management. Primitive types, integer, floating point, and boolean, are automatically converted to and from their respective types. Because of this we can use a bool in C♯ just as we would in C. Strings work a little differently as we will see later.

using System.Runtime.InteropServices;  // For calling into native code

public class TwitterSharing
{
// The plugin is only compiled for the iOS platform, check if Unity is compiling for it.
#if UNITY_IPHONE
    // Specifies which binary file contains the function.
    // For plugins you write the library is always "__Internal".
    [DllImport("__Internal")]
    // Has the same signature as in the C file
    private extern static bool _isTwitterAvailable();
#endif

    public bool IsTwitterAvailable()
    {
#if UNITY_IPHONE
        // Calls into native code
        return _isTwitterAvailable();
#else
        // The method needs to always return something.
        return false;
#endif
    }
}

Now you can check whether Twitter is available from game code. Debug.Log(TwitterSharing.IsTwitterAvailable()); will print whether twitter is available when running on iOS. But this is no fun. We want to post to Twitter. Let’s add a function to do just that. But first, let’s cover how mono marshals strings from C♯ to C. When you send a string as a parameter mono converts it into a null terminated UTF8 character array (char[] ending with \0) for native code. The sharing service expects an NSString so we have to convert it using stringWithUTF8String.

#import <Social/Social.h>
// Contains functions to call into Unity
#include "UnityInterface.h"

#if __cplusplus
Extern "C" {
#end if

bool _isTwitterAvailable()
{
    return [SLComposeViewController isAvailableForServiceType:SLServiceTypeTwitter];
}

void _postToTwitter(char* text)  // Make note of the signature
{
    // Create a view for Twitter sharing
    SLComposeViewController* shareSheet = [SLComposeViewController composeViewControllerForServiceType:SLServiceTypeTwitter];
    // Convert characters into NSString.
    [shareSheet setInitialText:[NSString stringWithUTF8String:text]];
    // Get the Unity native view and tell it to show the twitter view.
    [UnityGetGLViewController() presentViewController:shareSheet animated:YES completion:NULL];
}

#if __cplusplus
}
#endif

Now to make the unity side.

using System.Runtime.InteropServices;

public class TwitterSharing
{
#if UNITY_IPHONE
    [DllImport("__Internal")]
    private extern static bool _isTwitterAvailable();

    // This specifies which binary file contains the function.
    // For plugins you write the library is always "__Internal".
    [DllImport("__Internal")]
    // Notice here we say the parameter is a string
    private extern static void _postToTwitter(string text);
#endif

    public bool IsTwitterAvailable()
    {
#if UNITY_IPHONE
        return _isTwitterAvailable();
#else
        return false;
#endif
    }

    public void PostToTwitter(string text)
    {
#if UNITY_IPHONE
        // Call native function
        _postToTwitter(text);
#endif
    }
}

Now we can do something like the following from within the game.

if (TwitterSharing.IsTwitterAvailable()) {
    TwitterSharing.PostToTwitter("Tweet!");
}

This will bring up a twitter share dialog for the user to tweet with the text “Tweet!” already filled in. Some things to go over in the future include performing an action when the player successfully tweets and attaching a screenshot/image.

More information is available at http://www.mono-project.com/Interop_with_Native_Libraries.

Posted on Leave a comment

Apple Sales Tax

There has been much talk lately over Apple’s recent changes to its app store guidelines. It seems apps aren’t making much profit from ebook sales. You see, anytime an app on iOS makes an ebook sale, 30% of the sale goes to Apple.

When I first heard about the rules I thought they seemed a little odd. I tried to think of an equivalent rule with brick and mortar stores. It took a long time, but finally I found something. It’s not quite the same, but it is quite similar. What I came up with is sales tax.

As with any fees, businesses have a choice to make. Are the fees passed on to customers or absorbed into costs? I can’t imagine ebook retailers having large margins. Passing fees onto customers is a risky option.

However, that’s not the main problem. The ebook retailers have a competitor who is unaffected by these fees, Apple. Apple runs its own ebook store in iBooks. But how does a company apply a fee to itself? This gives the iBooks store an unfair advantage over all other ebook retailers. This would be like the state tax department running a competitive retail store. To me that doesn’t seem fair. But then again, I’m not a retailer and don’t run a business selling ebooks.