Getting Started with Vuforia for iOS Development


Setting Up the iOS Development Environment

The Vuforia SDK for iOS currently supports the majority of iOS devices including:

  • iPhone 6/6+ & 6S
  • iPhone 5
  • iPhone 4S
  • iPad 2, 3 & 4
  • iPad mini
  • iPod Touch 4G and later

Vuforia officially supports iOS 7 devices and above, and Mac OS X Lion or Mountain Lion development platforms.

Follow the steps below to:

  1. Become an iOS Developer
  2. Install XCode and the iOS SDK
  3. Set up a Provisioning Profile

Become an iOS developer

Vuforia applications must be deployed to a device to run; they cannot be run in the iOS simulator. You must enroll in the iOS Developer program to deploy applications to an iOS device. You can enroll here:https://developer.apple.com/programs/ios/

Install XCode and the iOS SDK

Once you have enrolled in the iOS Developer program, you should have access to the iOS Dev Center:http://developer.apple.com/devcenter/ios

Go to the Dev Center or the Mac AppStore to download XCode. The download should include the latest version of the iOS SDK.

We have tested Vuforia with XCode 4.5 and iOS SDK 6.0 or above; however, it should be possible to set the Deployment Target to 4.3 or above from within XCode.

Set up a Provisioning Profile

From the iOS Dev Center, you can go to your iOS Provisioning Portal, where you can follow the steps to set up your development machine to build and deploy iOS applications. Also, follow the process to:

  • Obtain a certificate
  • Assign a device
  • Create an App ID
  • Create a provisioning profile
  1. When choosing an App ID, pick something generic enough to work throughout your development process. See the Apple Developer Provisioning Portal for more details about choosing App IDs.
  2. Create a Development Provisioning Profile using the App ID you created, and be sure to add the devices you wish to test.
  3. Download the provisioning profile to your computer and double-click it to install.
  4. Test that a simple non-Vuforia application, possibly one of the samples in the iOS SDK, can run on the device. If you experience problems, it is a good idea to search the web for solutions, as there is plenty of advice available.

Installing the Vuforia iOS SDK

  1. Download the archive file from the Downloads page.
  2. Unarchive the file.

Resulting directory structure

Once you have unarchived the file, Vuforia will be installed in a directory which will hereafter be referred to as the vuforia-sdk directory and which should look something like the image below:

We recommend developing your own applications outside of the SDK directory, to make it easier to upgrade to future versions of the SDK.


How To Install the Vuforia iOS Samples

The Vuforia iOS Samples need to be added to the samples directory of the Vuforia iOS SDK installation.

  1. Download the Vuforia Samples that come in a compressed archive and expand these into their own directory.
  2. Copy the samples into the Vuforia installation directory so it looks like this:

Compiling and Running a Vuforia iOS Sample

We are now going to build the Vuforia Samples application which shows detection and tracking of natural features using a variety of targets supported by Vuforia. This section shows you how to build the project in XCode and deploy to the device.

Configuring the project in XCode

  1. Open the Vuforia Samples XCode project, located in the VuforiaSamples directory as shown below.
    Note: Vuforia applications do not build or work with the Simulator.
  2. You must select a device to build and run any Vuforia application.
  3. Ensure that your iOS device is connected to your computer via a USB cable and that XCode can recognize it as being usable for development (as highlighted in the Organizer window by a green light next to it).
  4. Select the device via the dropdown selector at the top left of the XCode window as shown here:

Set the bundle identifier

To set your bundle identifier so it matches the provisioning profile you have set up on the Apple Developer Provisioning Portal:

  1. Click the Vuforia Samples target to make it active.
  2. Replace com.vuforia.sample.testapps with your own bundle identifier, as shown here:

Set the Code Signing Identity

  1. In Xcode, click the Active Target, and then click the Build Settings tab, as shown here:
  2. Under Code Signing Identity, ensure that the right identity is selected. This usually happens by default, and if everything is OK, the message currently matches will display. This validates that the provisioning profile matches the code signing identity as set on the Apple Developer Portal.

Run the sample application

Print the image target

Print all image targets in vuforia-sdk directory /ImageTargets/media from any of the formats onto a US Letter or A4-size paper with the page scaling 'none' option, keeping the original aspect ratio of the image intact.

Typically there are three image targets as shown here.

Deploy and run the application

  1. Connect your iOS device to your computer via the USB connector.
  2. Deploy the application to the device using the Build and Run button in XCode, which will do exactly this and install it on the device, assuming there are no problems.

After a splash screen, the live camera image is shown.

Use your device to look at the chips or stones printed target, and you should see a textured teapot centered on top of the target, grounded to the plane.

You have successfully deployed your first application with the Vuforia SDK!

Double-tap the screen to reveal a menu, and select Select Target > Tarmac to switch datasets. The teapot will no longer appear on the Stones target. This is because the Tarmac image is stored in a different database. Now, point your device towards the tarmac printed target and you will see the teapot again.

This app shows how the SDK can detect and track a single image from a pre-defined set of images. The app also shows how to switch between databases without too much effort, as well as how to deal with camera settings, such as autofocus. With a small code change, it can also be compiled to detect and track multiple images simultaneously.

Next Steps

Feel free to explore the remaining functionality contained within the Vuforia Samples app.

Further detail about this sample application is contained within the downloadable archive.


Support for iOS Metal

Apple's Metal rendering API is supported for iOS devices running iOS 8 and above when using Vuforia SDK version 5.5 and above.

This article describes how to configure native iOS apps that use the Vuforia iOS SDK to use Metal. Vuforia Unity iOS apps do not need to use the Vuforia API to configure Metal support, Metal is supported by default as the Auto Graphics API setting in Build Settings.

Configuring Metal support in native iOS apps

To use Metal in your iOS apps, you will need to pass the Metal initialization flag to Vuforia::setInitParameters in order to configure your app's rendering context before initializing the SDK.

The METAL initialization flag is defined in the Vuforia.h header file.

enum INIT_FLAGS {
    GL_20 = 1,          ///< Enables OpenGL ES 2.x rendering (not available on UWP platforms)
    METAL = 2,          ///< Enables Metal rendering (available on Apple platforms)
    DX_11 = 4,          ///< Enables DirectX 11 rendering (available only on UWP platforms)
    GL_30 = 8,          ///< Enables OpenGL ES 3.x rendering (not available on UWP platforms)
};

In order to utilize the Metal API in your app, you will need to pass the METAL INIT_FLAGS value to the SDK using the Vuforia::setInitParameters method.

Vuforia::setInitParameters(Vuforia::METAL,"");

Note: Vuforia::setInitParameters() must be called before calling Vuforia::init() to commence with the initialization of the Vuforia SDK. The correct call sequence for initializing your app to use Metal is demonstrated in the ImageTargetsMetal Advanced Topics sample project for iOS. Metal API support can be configured by assigning the mVuforiaInitFlags variable the value Vuforia::METAL on line 144 in SampleApplicationSession.mm.

Vuforia::setInitParameters(mVuforiaInitFlags,"");

mVuforiaInitFlags can be defined when calling initAR or later in initVuforiaInBackground in the sample code.

See: Changes in Vuforia 5.5 for more information on how support for the iOS Metal APIs has been introduced the Vuforia SDK.


iOS 64-Bit Migration

As Apple announced on October 20, 2014:
Starting February 1, 2015, new iOS apps uploaded to the App Store must include 64-bit support and be built with the iOS 8 SDK, included in Xcode 6 or later. To enable 64-bit in your project, we recommend using the default Xcode build setting of Standard architectures to build a single binary with both 32-bit and 64-bit code.

What does this mean for you Vuforia developers?

As of February 1st 2015, newly released apps will need to take advantage of the iOS 8 SDK and the new 64-bit ARM chips in newer iOS devices.

Vuforia SDK 4.0 fully supports iOS 8 and 64-bit ARM architecture, and the Vuforia iOS samples have also been updated to correctly build and run in 64-bit mode.
In particular, the newly released Vuforia Sample projects already come with the correct Xcode Build Settings to support both the 32-bit (armv7, armv7s) and the 64-bit (arm64) modes.

You can obtain the Vuforia 4.0 SDK and samples with iOS 64bit support in the downloads section of the Developer Portal.

If you are creating an app using Vuforia and iOS 8, you should also make sure to apply the same build settings to your own project, in order to be able to upload your App to the Apple App Store. There are instructions for configuring Unity iOS 64bit builds at the end of this article.

It is also recommended that you test your App on both at least one 64-bit and one 32-bit device, before submitting it to the App store; for example, the iPhone 5S is equipped with 64-bit CPU, whereas the iPhone 4S has a 32-bit chip. An App must be able to correctly run on both platforms (32 and 64-bit).

Do I need to build two distinct apps?

You do not need to build two distinct apps, i.e. one App in 32-bit mode and another in 64-bit mode. Simply build your Xcode project with the recommended Build Settings, which include both the armv7/armv7s (32-bit) and the arm64 architectures; this will ensure that your App will be packaged with all the necessary artifacts to be able to run on both 32-bit and 64-bit devices.

Coding guidelines

When writing an iOS App with the Vuforia SDK targeting the 64-bit architecture, you should generally follow the same general guidelines that apply to any iOS App. Vuforia does not introduces any additional requirements or constraints.

Two Conventions: ILP32 and LP64

The 32-bit runtime uses a convention called ILP32, in which integers, long integers, and pointers are 32-bit quantities. The 64-bit runtime uses the LP64 convention; integers are 32-bit quantities, and long integers and pointers are 64-bit quantities.

One of the most important and obvious recommendations stemming from the above is to avoid casting pointers to integers. If your app code does cast pointers to integers, your code may behave correctly in 32-bit mode but it may result in a crash or other runtime misbehavior when executed in 64-bit mode, as soon as a pointer exceeds the 32-bit scope.

Also, an array containing elements of type long will be double its size in bytes when the code is built in 64-bit mode, with respect to the 32-bit case. For large data arrays this may also result in a significantly increased memory usage. Keep this in mind when creating large arrays and choose the appropriate type; in many cases, 32-bit integers may be sufficient to represent common data values.

NSInteger data type:

The NSInteger type is a 32-bit integer in the 32-bit runtime and a 64-bit integer in the 64-bit runtime. When receiving an NSInteger data from a method or code expression, you should use the NSInteger type to hold the result; for example, casting an NSInteger to an int might result in truncation of the original value (data loss) when in 64-bit mode, so in general this should be avoided, unless the value in question is known / guaranteed to always be within 32-bit boundaries.

CGFloat data type:

CGFloat changes size in 64-bit code. The CGFloat type changes to a 64-bit floating point number. As with the NSInteger type, you cannot assume that CGFloat is a float or a double. So use CGFloat consistently.

For a complete guide on 64-bit transition, please refer to the official iOS 64-bit migration guidelines published in the Apple website:

https://developer.apple.com/library/ios/documentation/General/Conceptual/CocoaTouch64BitGuide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40013501-CH1-SW1

https://developer.apple.com/library/ios/documentation/General/Conceptual/CocoaTouch64BitGuide/Major64-BitChanges/Major64-BitChanges.html#//apple_ref/doc/uid/TP40013501-CH2-SW1

https://developer.apple.com/library/ios/documentation/General/Conceptual/CocoaTouch64BitGuide/ConvertingYourAppto64-Bit/ConvertingYourAppto64-Bit.html#//apple_ref/doc/uid/TP40013501-CH3-SW1

Unity iOS

Follow these instructions to ensure you build with Unity iOS 64bit support

  • Use the latest Unity release *
  • Select the iOS build target in Build Settings.
  • In Other Settings , set the Scripting Backend to IL2CPP
  • The Architecture setting must be set to Universal

User-added image

Note: Unity 64bit support was original introduced in the Unity 4.6.1p5 patch release. This is the earliest version that can support the Vuforia iOS 64bit Unity extension.