Getting Started

This article illustrates how you can set up your development environment in order to be able to develop plugin apps for SCENE. Starting with the setup requires the following:

A 2.0.x version of the SCENE API App Developer Package
A Microsoft Visual C++ IDE (free 'Express' editions can also be used for the development)

Installing the Developer Package

Run the installer of the developer package and follow the on-screen installation instructions. In the installation directory of the developer package you will find additional documentation, samples and resources to get started with the app development. Directory Structure of the Developer Package The installation directory of the developer package contains the following sub-directories:

doc/: Contains a snapshot of the web documentation for the corresponding API version.
c++/: Contains the relevant SCENE API files for the development of C++ plugin apps.
- c++/samples/: Contains short app samples which illustrate certain aspects of the SCENE API.
- c++/include/: Contains the header files which you need to include in your source files to make use of the C++ interface.
- c++/lib/: Contains the library files which you need to include in your app project to be able to link against the SCENE API binaries.

Setting up a Plugin App Project

SCENE plugin apps are written in C++ and built as dynamic-link-libraries. The SCENE API provides a C++ interface which can accessed by plugin apps to make use of the API functionality. You can easily set up a new plugin app project with the following steps:

Start by setting up a new project in your Microsoft Visual C++ IDE. For a quick start, you can just use the Empty Project template which should be provided by the project wizard of the IDE.
Right-click on your project in the Solution Explorer pane and select Properties from the resulting pop-up menu.
In Configuration Properties > General, set the Configuration Type property to Dynamic Library (.dll).
In Configuration Properties > C/C++ > General, add the path to the SCENE API include directory to the Additional Include Directories, e.g. C:\SCENE API\SCENE API App Developer Package 2.0.0 x64\c++\include
In Configuration Properties > Linker > General, add the path to the SCENE API library directory to the Additional Library Dependencies, e.g. C:\SCENE API\SCENE API App Developer Package 2.0.0 x64\c++\lib\x64
In Configuration Properties > Linker > Input, add the SCENE API libraries Core_API.lib, Scanner_API.lib and Plugin_API.lib to the Additional Dependencies.

Note: In order to be able to use the SCENE API, your project has to be configured to target 64bit platforms. More Information on how to setup your project for 64bit platforms can be found at the following link: How to: Configure Visual C++ Projects to Target 64-Bit Platforms.

Providing App Startup and Shutdown Functions

Every plugin app must implement at least two fundamental functions, one which is called by SCENE when the app is activated and one which is called when it is deactivated. These functions have to match a defined signature and need to be exported to the dll interface of the app so that they can be correctly called by the hosting SCENE instance. In order to implement and expose the functions in your app project you can just add a new source file to your app project and use the code from the following code snippet:

#include <windows.h>
#include <plugin_api/lsscenecontext.h>

using namespace SCENE_API;

extern "C" __declspec(dllexport)
int lsAppStartup(
        ref_ptr<LSSceneContext> context,
        HINSTANCE hInstance)
{
    return 0;
}

extern "C" __declspec(dllexport)
void lsAppShutdown()
{

}

You can find more information on the app lifecycle and on startup and shutdown functions in the plugin app lifecycle documentation article.

Adding Metadata Files

Besides the app dll and its dependencies which make up the logical part of an app, each app has to supply additional metadata files. These files are used by SCENE to extract fundamental information such as the app name and version as well as to check whether the app is compatible with the API provided by the hosting SCENE instance. Every app must provide at least one metadata file called the app manifest which contains the essential information required by SCENE to run the app. In order to add an app manifest to your app project you need to create a new file called "AppManifest.xml" and insert the app information using a special xml syntax required by SCENE. As a starting point you can use the following xml code and replace the value properties of the appropriate xml nodes with the values that describe your app.

<?xml version="1.0" encoding="utf-8"?>
<!-- XML v. 2 -->
<!-- 'SCENE XML' -->
<!-- NEXT: XML Root Element -->
<FARO>
  <AttrContainer>
    <Attr type="String">
      <Name value="'Name'" />
      <Value value="'App name'" />
    </Attr>
    <Attr type="String">
      <Name value="'Version'" />
      <Value value="'1.0.0.0'" />
    </Attr>
    <Attr type="String">
      <Name value="'Description'" />
      <Value value="'App description'" />
    </Attr>
    <Attr type="String">
      <Name value="'App_Dll'" />
      <Value value="'App dll filename'" />
    </Attr>
    <Attr type="String">
      <Name value="'Minimum_Required_API'" />
      <Value value="'2.0.0.0'" />
    </Attr>
  </AttrContainer>
</FARO>

Creating the App Package

In order to install and run your app in SCENE you need to create an app package. App packages are special archive files which use an .fpp file ending to be identifiable by SCENE and contain all files related to the app. You can create an app package from within SCENE through the following steps:

Copy all files that are part of the app to a new directory. SCENE will pack all files which are located in that directory into the app package. Therefore make sure that the directory does not contain any files that should not become part of the app package. The directory has to contain at least the app dll file together with its dependencies as well as the app's manifest file.
In SCENE, open the app management dialog by selecting Tools > Apps.
Enable the Developer Options checkbox on the top right of the dialog to display the additional UI elements for app developers.
Click the Pack App button and select the directory which contains the files of your app which you created in step 1.
Pack the files from the directory and create the app package by clicking Pack App.

Installing and Running the App in SCENE

After the app package has been created, the app can be installed by double-clicking or dragging it onto a SCENE instance. Upon installation SCENE prompts the user for confirmation of the installation and displays a dialog containing the name and description of the app.

The SCENE App installation dialog

The contents of the prepared app package are installed to a sub-directory of the Apps directory located in the installation directory of SCENE. Once the app has been successfully installed, it will be automatically activated.