ARToolKit for Unity on Android
From ARToolworks support library
Main Page > ARToolKit for Unity > ARToolKit for Unity on Android
Contents |
Requirements
You must have a Unity Pro with Android Pro license to be able to export projects from Unity that use the ARToolKit for Unity plugins.
Player Settings
When exporting to Android, some Player Settings must be configured as follows to work correctly with ARToolKit for Unity (settings not mentioned can be adjusted to suit the user):
Access the Player settings menu:
- Resolution and Presentation
- Orientation: "Landscape Left" - required so that the live video is oriented to match the screen.
- Use 32-bit Display Buffer: ticked (checked)
- Other Settings:
- Bundle Identifier: For testing, set to "com.mycompany.myapp". Note however that this will need to be changed before deployment of your finished application, or else it will lead to conflicts when other ARToolKit for Unity applications are installed on the device. See below for instructions on how to change prior to deployment of your finished application.
- Minimum API Level: "Android 2.3.1 'Gingerbread' (API Level 9)" or higher, or if using only square tracking "Android 2.2 'Froyo' (API Level 8)" or higher
- Graphics Level: OpenGL ES 2.0
- Internet Access: "Require" (as of ARToolKit v5.1.0, used to be "Auto").
Setting the Bundle Identifier
All Android applications must be uniquely identified by a bundle identifier. ARToolKit for Android is supplied with a default bundle ID of "com.mycompany.myapp" but this will need to be changed before deployment of your finished application, or else it will lead to conflicts when other ARToolKit for Unity applications are installed on the device.
Note that when using ARToolKit for Unity, the bundle ID has to be set in two places: the Unity Player settings, and in the file Assets/Plugins/Android/AndroidManifest.xml.
First set the bundle ID in Unity (replacing com.mycompany.myapp with your chosen ID):
Secondly, the bundle ID must be manually changed in the Android manifest. To do this, look inside your Unity project folder, for the file Assets/Plugins/Android/AndroidManifest.xml. Open the file in a text editor and locate the text package="com.mycompany.myapp", editing the "com.mycompany.myapp" to match the bundle identifier set in Unity.
Tested Devices
Unity maintains its own list of Android devices which have been tested with Unity alone: here. You should verify that your device works with Unity at all before attempting to use the ARToolKit for Unity plugin.
Known Issues
ARToolKit for Unity release 2.0.3 was unable to be verified on an Android OS v2.2 device, and we caution against attempting to support Android OS 2.2 devices with this release. We hope to restore 2.2 support in a future release.
On Android OS releases v2.2.x and earlier, a defect in the handling of compressed resources inside .jar files embedded in .apks limits the size of compressed resources to as little as 1.0 megabyte (although this can be higher on some variants of the 2.2 OS series, depending on the device manufacturer). This imposes a limitation on the size of the NFT datasets which can be used if targeting Android 2.2 to 1.0 megabyte. This limitation was removed in Android OS 2.3.
Using ARToolKit for Unity in a larger Android project
It is possible to modify the Android Java portion of ARToolKit for Unity to allow for incorporation into a larger Android application, or any other type of conceivable customisation.
Unity for Android comes bundled with the source code for its outermost Activity subclass (UnityPlayerActivity). ARToolKit for Unity subclasses this in a new class UnityARPlayerActivity. This class is packaged as a .jar file and provided in ARToolKit for Unity at path Assets/Plugins/Android/UnityARPlayer.jar. It is linked into the final product by Unity.
Since ARToolKit for Unity v5.0.8, source for UnityARPlayerActivity is also supplied. You can find it in ARToolKit for Unity at path extras/Android UnityARPlayer source/.
The following images show how to package this source into the .jar file.
First, ensure that the project correctly references the locations of android.jar (from the Android SDK) and the classes.jar provided by Unity.
classes.jar is part of the Unity installed package on your system. On OS X this is typically inside the Unity application package at path /Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/bin/classes.jar and on Windows at path C:\Program Files\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\bin\classes.jar.
Next, invoke an export jar operation in Eclipse (File->Export...)
The correct classes must be exported. This includes
com/artoolworks/ar/base/NativeInterface.class
com/artoolworks/ar/unity/CameraSurface.class
com/artoolworks/ar/unity/UnityARPlayerActivity.class
. See the following image for how to select the classes.
Once the jar has been exported, place it in your Unity project at path Assets/Plugins/Android/UnityARPlayer.jar
