Native Image Target Sample

The native Image Targets sample for iOS and Android provides a good starting point for familiarizing yourself with native Vuforia development. This guide will explain the main elements of the sample and their roles.

Datasets

The Image Targets sample contains the following two datasets:

  • StonesAndChips
  • Tarmac

Each dataset has a .dat and an .xml file that goes with it. Before running the sample, you should print the targets, which are found in the VuforiaSamples/media directory.

While the application runs on the device, you can point it at any of the targets and the device should display a teapot in the foreground. Be aware that the application allows only one dataset to be active at a time. The StonesAndChips dataset displays the stones and chips images, while the Tarmac dataset displays the tarmac image.

Menus

You can change the dataset from the context menu, which becomes available after you double-tap on the screen. The context menu also lets you:

  • Select autofocus
  • Turn the flash on and off
  • Select the Extended Tracking feature

Extended Tracking

When the Extended Tracking option is selected, a tall building is displayed as an augmentation rather than a teapot. This view demonstrates the feature much better, as it is meant to help show more immersive AR environments. See Extended Tracking Mode.

Image Targets in iOS

The Image Targets sample contains the following two classes, which represent most of the functionality of this individual Vuforia sample. The sample demonstrates how the template works:

  • ImageTargetsEAGLView
  • ImageTargetsViewController

ImageTargetsEAGLView Class

This class contains the necessary code using OpenGL ES to display an augmentation at the position defined by the pose matrix. This position is determined by Vuforia after it (does it=Vuforia, or does it=the ImageTargetsEAGLView class?) processes the Camera view. Specifically, this class can perform the following actions:

  • Set up the OpenGL ES context and buffers, plus teardown and resource handling
  • Set up the 3D models, including teapot and building
  • Create the OpenGL ES textures for the models
  • Set up the vertex shaders for OpenGL ES
  • Display the augmentation

Using the ImageTargetsEAGLView.mm file, you can identify the references to the Vuforia API by
their Vuforia:: prefix. Note also that this file has to be an .mm file because Vuforia is a C++ library.
Using an .m file leads to compilation errors.

This ImageTargetsEAGLView.h file shows that this interface derives from UIView and conforms to the UIGLViewProtocol, which contains a single method:

- (void)renderFrameVuforia;


Vuforia periodically calls this method on the background thread to display the augmentation. Study this method to learn more about how the augmentation is displayed when using OpenGL ES.

ImageTargetsViewController Class

This class provides a self-contained view controller that controls Vuforia to provide the functionality to run the Image Targets sample. This class sets up and controls the ImageTargetsEAGLView so that it functions correctly when displayed. This class also provides the link between Vuforia functionality and native iOS device.

The ImageTargetsViewController.h file shows that this interface derives from UIViewController and conforms to two protocols that are provided as part of this template:

  • SampleApplicationControl
  • SampleAppMenuCommandProtocol

These protocols mandate that the ImageTargetsViewController provide certain methods for the application to function correctly. Therefore those methods can act as a guide if you use this template.

Image Targets in Android

The Image Targets sample in Android contains two classes that represent most of the functionality of this individual Vuforia sample, and these classes demonstrate how the template works:

  • ImageTargetRenderer
  • ImageTargets

ImageTargetsRenderer Class

The OpenGL rendering is executed with the help of the following two classes:

  • GLSurfaceView
  • GLSurfaceView.Renderer

The GLSurfaceView is often the same for all the sample applications, so there is a common class for this view:
com.vuforia.samples.SampleApplication.utils.SampleApplicationGLView
This class contains all the necessary code to initialize OpenGL and you are free to reuse it or develop your own because this class is not connected with Vuforia.

The Renderer does the actual rendering of the augmentation and it is application-specific. ImageTargetsRenderer is the renderer associated to the OpenGL view, as indicated by the following constructor:
public ImageTargetRenderer(ImageTargets activity, SampleApplicationSession session)

  • Activity: provides access to the Android integration (such as displaying a dialog box or getting access to resources)
  • Session: provides access to the Vuforia integration (such as access to the projection matrix)

The rendering is performed by using the following method:

public void onDrawFrame(GL10 gl)

Study this method to learn more about how the augmentation is displayed when using OpenGL ES.

ImageTargets Class

This class provides access to the Android integration for the Vuforia application, and has the following responsibilities:

  • Takes care of the usual Android lifecycle notifications
  • Sets up the OpenGL view and its renderer
  • Creates a VuforiaSession instance and handles the notification associated to it

This class implements the SampleApplicationControl interface. This interface mandates that the ImageTargets class must provide certain methods for the application to function correctly. Therefore, the ImageTargets class can act as a guide if you wish to use this template.