Click or drag to resize

Getting Started

This document describes how to get started with using STK Components in your application.

Adding STK Components to an Application

In order to use STK Components in your own application, perform these steps:

  1. Obtain a valid license file (either a temporary license from AGI support or the license you purchased) and place it in the same directory as the STK Components assemblies: [Install Directory]\Assemblies. The file should have a .lic file extension. You can request a temporary development license from AGI Technical Support by e-mailing your request to support@agi.com.

  2. Add references to the STK Components assemblies to your project. In Visual Studio, this is easily accomplished by right-clicking your project and then clicking Add Reference. Then, navigate to [Install Directory]\Assemblies and select the assemblies you would like to use in your application.

  3. Add the licenses.licx file, which is found with the STK Components assemblies as well, to your project. Adding this file to your project tells Visual Studio to look for the .lic file at compile time and embed it in your application. This way, your application can be deployed without the need for an external license file. See the Licensing and Deployment topic for details and advanced scenarios.

For a detailed walkthrough of building an application with STK Components, see the Tutorial.

Insight3D®

Using the Insight3D visualization component requires that you perform some additional steps beyond the ones described above:

  1. Run the vcredist_x86.exe located in the root directory of your STK Components installation.

  2. Run the vcredist_x64.exe if you are developing on a 64-bit operating system.

  3. Configure your application to run as a 32-bit/64-bit process.

  4. Add the Insight3D control to the Windows Forms toolbox.

  5. If using .NET 4, configure your project to work with Insight3D.

Running vcredist_x86.exe and vcredist_x64.exe

In order to use Insight3D in the Visual Studio designer, you must install the correct version of the Visual C++ Redistributable, vcredist_x86.exe and additionally vcredist_x64.exe if you are developing on a 64-bit system. For convenience, they are included in the root directory of your STK Components installation.

Configuring your application for various CPU architectures

Default - Configuring your application to run as a 32-bit or 64-bit process (Any CPU)

By default, a .NET application created with Visual Studio uses the Any CPU configuration. This means that it will run as a 64-bit process on a 64-bit operating system and a 32-bit process on a 32-bit operating system. Insight3D uses different libraries for 32 and 64 bit processes, so some configuration is required for a .NET application to choose the correct library at runtime. This configuration is done via an application configuration file (app.config). If your project does not already have an app.config file you can create one by right clicking on your application's project in visual studio and choosing Add -> New Item.... When the Add New Item dialog box appears choose Application Configuration File.

Creating an app.config file

The following xml snippet needs to be added to the configuration block in the app.config file. This tells your application to load the 64-bit AGI.Foundation.Graphics.x64.dll when running on a 64-bit operating system. Otherwise the 32-bit version is loaded.

<configuration>
  <runtime>
    <asm1:assemblyBinding xmlns:asm1="urn:schemas-microsoft-com:asm.v1">
      <asm1:dependentAssembly>
        <asm1:assemblyIdentity name="AGI.Foundation.Graphics" publicKeyToken="46f7a65aaf1b26a0" processorArchitecture="amd64" />
        <asm1:codeBase version="1.0.0.0" href="AGI.Foundation.Graphics.x64\AGI.Foundation.Graphics.x64.dll" />
      </asm1:dependentAssembly>
    </asm1:assemblyBinding>
  </runtime>
</configuration>
Important note Important

1.0.0.0 needs to be replaced with the version of the assembly you are using. You can get the assembly's version through Windows Explorer by right clicking on AGI.Foundation.Graphics.dll, choosing Properties, and then selecting the Details tab.

Important note Important

When using the Any CPU configuration, only the 32-bit version of AGI.Foundation.Graphics.dll should be added as a reference in your application's Visual Studio project. The 64-bit version should be copied into a folder named AGI.Foundation.Graphics.x64 in your application's build output directory. This can be done by either a post-build event or by adding AGI.Foundation.Graphics.x64.dll as a content link as shown below.

Adding x64 Assembly as Link

Optional - Configuring your application as a 32-bit only process (x86)

By default, a .NET application created with Visual Studio uses the Any CPU configuration. Building a 32-bit only application requires configuring your project to use the x86 platform instead of Any CPU. Open the Configuration Manager from the Build menu in Visual Studio. Click the drop-down under Active solution platform and select <New...>.

Creating a new Solution Platform

On the New Solution Platform panel, select x86 in the Type or select the new platform drop-down and click OK. Close the Configuration Manager. When built using this new configuration, your application will run as a 32-bit process.

Add the 32-bit Insight3D assembly (AGI.Foundation.Graphics.dll) as a reference to your project.

Optional - Configuring your application to run as a 64-bit only process (x64)

Configuring a 64-bit only application is similar to configuring an Any CPU application, but with some additional steps.

  1. Follow the configuration for an Any CPU application.

  2. Like the 32-bit configuration, a new platform configuration is required. Choose x64 when creating the new platform configuration.

  3. Because Microsoft Visual Studio is a 32-bit process, the 32-bit Insight3D assembly is still required for the Visual Studio designer to work properly. However, the 32-bit Insight3D assembly is not required at runtime. You can prevent the 32-bit Insight3D dll from being copied to the output directory by changing the assembly's Copy Local property to false.

Setting Copy Local to false

Adding the Insight3D control to the Windows Forms toolbox

Open the Windows Forms designer by double-clicking a form in your project. Make sure the toolbox is shown by choosing Toolbox from the View menu. Then, add the Insight3D control to the toolbox by right-clicking in the toolbox and selecting Choose Items....

Adding Insight3D to the Toolbox

On the Choose Toolbox Items panel that pops up, select the .NET Framework Components tab and then click the Browse... button in the lower right-hand corner of the panel. Browse to the Assemblies directory underneath where you installed STK Components. Select the AGI.Foundation.Graphics.dll assembly and click Open. Note that because Visual Studio is a 32-bit process, the Visual Studio Designer requires the 32-bit assembly to be used regardless of your build configuration (Any CPU, x86, x64). Insight3D will appear in the list of .NET Framework Components. Click OK. Insight3D will appear in the toolbox.

Insight3D in the Toolbox

The Insight3D control can now be dragged onto your form, just like any other Windows Forms control.

Enabling Video Textures Feature

Insight3D has the ability to use videos as 2D textures. To enable this feature, Insight3D must be able to load the FFMpeg video processing libraries (avcodec, avformat, avutil and swscale). These libraries are contained in the same directory as the Insight3D libraries. If your build/deployment process copies the Insight3D libraries to some other directory, the FFMpeg libraries must also be copied.

Configuring your .NET 4 project to work with Insight3D

Note Note

The instructions in this section only apply to .NET 4. Insight3D works in .NET 2.0, 3.0, and 3.5 without any of the additional steps described below.

By default, a new project created with Visual Studio 2010 will be configured to use the .NET 4 Client Profile. Insight3D, however, requires the full version of .NET 4. If you try to build a project that uses Insight3D against the client profile, you will see a warning about a missing System.Design assembly and the project will not build.

.NET 4 Client Profile error

To solve this problem, change the "Target Framework" property on the Application tab of your project's properties to ".NET Framework 4." With that change, your project should build successfully. However, at runtime, you will receive a FileLoadException saying, "Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information."

.NET 4 Mixed Mode Exception

The additional configuration you need is to add an "Application Configuration File" (app.config) to your project, if it doesn't exist already. In the app config file, add a useLegacyV2RuntimeActivationPolicy attribute to the startup element, as follows:

<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0"/>
  </startup>
</configuration>