VisioMove SDK (iOS)  2.1.22
Integrating with your application

This section describes the basics on how to configure and setup VisioMove to run within your application. In general, the product will need to perform the following steps listed below:

  1. Data bundle configuration
  2. Create Application
  3. Load Configuration
  4. Select Dataset
  5. Select Layer
  6. Android Specific Info (Important)

Data bundle configuration

To create a VisioMove view, you're going to need some data. Visioglobe, in almost all circumstances, will provide you with the data you need.

For information on the sample data bundle provided with the VisioMove sample projects, please write to conta.nosp@m.ct@v.nosp@m.isiog.nosp@m.lobe.nosp@m..com.

VisioMove uses the data configuration file to "describe" what datasets are available within the provided data bundle. VisioMove also uses the data configuration to know more specific information related to each dataset, such as what layers are support and what binaries need to be loaded to support those layers.

The data configuration extract below shows the format of the xml descriptor file.

Within the data bundle provided with each of our samples, there is a configuration file, named "vg_config.xml". Generally, you won't need to tweak this file. However if you do, it is at your own risk and we suggest that you make a back-up file first.

For further information on loading configuration or selecting a dataset see Load Configuration or Select Dataset.

Create Application

Once the dataset is ready, the next step is to create an instance of the Visioglobe Application within your application.

iOS

The instance of the application is created once the VgEAGLView has been added to the view and has been started. For example, supposing in your MainWindow.nib you have added a VgEAGLView and bound it to an IBOutlet variable called m3DView.

@interface VisioMoveHelloWorldViewController : UIViewController
{
VgEAGLView* m3DView;
...
}
@property (retain) IBOutlet VgEAGLView* m3DView;
...
@end
- (void)viewDidLoad
{
[super viewDidLoad];
// Must call startAnimation before calling getApplication
[m3DView startAnimation];
mVgApp = [m3DView getApplication];
...
}

Android

The instance of the application is created once the VgSurfaceView has been created. The VgSurfaceView can be added in layouts and will be created once the layout is loaded.

// FIELDS
VgSurfaceView mVgView = null;
VgIApplication mVgApp;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
...
setContentView(R.layout.main_layout); // main_layout contains a VgSurfaceView.
mVgView = ((VgSurfaceView) findViewById(R.id.VgSurfaceView));
// All interfacing with VisioMove should be performed within it's own thread.
mVgView.queueEvent(new Runnable() {
public void run() {
mVgApp = mVgView.getApplication();
...
}
});
...
}

Other Platforms

Load Configuration

Now that we have an instance of the Visioglobe application we need to configure it. This is done via a call to loadConfiguration and passing a configuration file. The configuration file contains a set of datasets, each of them representing a coherent, packaged set of data (for example a city). See VgEngine::VgIDatabase::loadConfiguration for more information.

Note : as the code is very similar between iOS and Android, only Objective-C code will be used in coming snippets.

Select Dataset

In VisioMove v2.0, there is only support for a single dataset. Support for handling multiple datasets will arrive in later versions of the SDK. For the meantime, it is necessary to select the first dataset using VgEngine::VgIDatabase::selectDataset, passing 0 as a parameter.

bool lSuccess = mVgApp->editEngine()->editDatabase()->selectDataset(0);

Select Layer

There may be several layers within a dataset, and it's possible to hide and show each of those layers independently.

Below is a code snippet showing the first layer being set to visible.

int lFloorIndex = 0;
if (lLayers.size() > lFloorIndex)
{
lLayers[pFloorIndex]->setVisible(true);
}

Android Specific Info (Important)

Overview

Before developing for Android using VisioMove there are some things you need to know.

GL Thread

Firstly, VisioMove doesn't run on the main UI thread. It runs on the GL thread. This point is important because it implies that anytime a VisioMove API is called, it must be called from within the GL Thread. This can be done by following the below technique:

public void printVersion()
{
setContentView(R.layout.main_layout);
final VgSurfaceView lSurfaceView = (VgMySurfaceView) findViewById(R.id.VgSurfaceView);
lSurfaceView.queueEvent(new Runnable()
{
public void run()
{
Log.i("VisioMove", "Hello from the GL thread!");
Log.i("VisioMove", "VisioMove version:" + lSurfaceView.getApplication().editEngine().editLicenseManager().getVersion());
}
});
}

SUMMARY: As a rule, never call a VisioMove API from outside of the GL Thread. A VisioMove API called from any other thread will have an undefined behaviour.

GL Surface Context

On Android the interface to VisioMove is via the VgSurfaceView class, which extends the GLSurfaceView. When the activity which has loaded the VgSurfaceView is paused, the GL context of that view is not preserved.

The good news is that Visioglobe take care of saving the OpenGL context for you. If the activity containing the GLSurfaceView is paused and resumed, your map, map state, textures, will all still be available. On Android the graphics resources are reset when the GLSurfaceView is initially created. This is visible, when you look within the following method VgMySurfaceView.onSurfaceCreated(GL10 pGL, EGLConfig pGLConfig).

Object Scope and Garbage Collection

Be warned that because the VisioMove is compiled using JNI, any references VisioMove holds to external objects (such as VgPostDrawCallback) won't be counted when it comes to garbage collection. If you don't guard a reference to an object before adding it to VisioMove, it will eventually be garbage collected. This causes a dangling pointer within VisioMove and eventually a crash at some point when VisioMove tries to call it.

VisioMove 2.1.22, Visioglobe® 2016