Getting started

Licensing
Package hierarchy
Sandboxes
Library descriptions

Platform-specific notes


Licensing

You must specify a valid Visualize license in your application code in order to use the Visualize product. The license key is a character sequence either directly provided by Tech Soft 3D or generated using the "Generate Key" button located on the Visualize downloads page in the Developer Zone.

If an invalid or expired license is set, your Visualize-based application will exit when Visualize attempts to start. If you are using a time-bound evaluation license, the Visualize viewport will display a small piece of text indicating that it's an evaluation license, and also display the number of days remaining until expiration.

Setting the License

The license should be compiled into your application via the HPS::World object, which initializes HOOPS Visualize. In C++, the license is delivered in a file called hoops_license.h. In C#, the license is set in a file called hoops_license.cs. Paste your license string into the HPS::World constructor.

[snippet 1.1.1.a]
World world("[your unique license string]");
World world = new World("[your unique license string]");

Alternatively, users have the option of replacing the existing hoops_license.h or hoops_license.cs files in the include directory with the one from the Developer Zone, and passing the defined variable HOOPS_LICENSE to the HPS::World constructor.

The various samples and sandbox projects already reference hoops_license.h or hoops_license.cs for convenience, and you can simply copy your license file to your Visualize installation's include directory.

IMPORTANT: Your application must instantiate the HPS::World object before interacting with Visualize, and the object must stay in scope as long as the application continues to use Visualize. For C# users, a static HPS::World object at the module level is recommended, due to the unpredictable nature of the .NET garbage collector.


Package hierarchy

  • <hoops_visualize_hps root directory>
    • bin (dynamic build resources, sandboxes)
    • docs
    • include
    • lib (static build resources)
    • samples
      • <gui>_sandbox
      • code
      • data (sample models, images)
      • cc_exchange (Windows only)
      • mfc_sandbox (Windows only)
      • qt_sandbox
      • wpf_sandbox (Windows only)
      • wx_sandbox


Sandboxes

Note that the hierarchy above includes <gui>_sandbox. Each platform includes a Sandbox, which is a sample application intended to be used as a starting point for prototyping, testing, and learning the API. Each sandbox contains a viewport and a set of manipulations operators, such as rotation, pan, and zoom.

Project name Description
mfc_sandbox Windows: MFC GUI framework for C++
wpf_sandbox Windows: WPF GUI framework for C#
cocoa_sandbox OSX: Cocoa GUI framework for C++
qt_sandbox Windows/OSX/Linux: QT GUI framework for C++. The Qt Sandbox is not supported on Visual Studio 2015.
wx_sandbox Windows/OSX/Linux: WxWidgets GUI framework for C++
ios_sandbox iOS: Cocoa-Touch framework for Objective-C/C++
android_sandbox Android: Android SDK framework for Java/C++ and Android Studio

Segment browser

The segment browser is a Microsoft tree control that is included in both the WPF and MFC sandboxes.

The segment browser is a GUI control that allows you to inspect the segment structure of the loaded model. SceneTree and SceneTreeItem facilitate populating the tree-view, and they have derived classes located in CHPSSegmentBrowserPane.cpp (for MFC), or SegmentBrowser.cs (for WPF).

Model browser

The model browser is a Microsoft tree control that is included in both the WPF and MFC sandboxes. It is provided in source code form as a reference, to facilitate adding a custom model browser to your application.

The model browser is a GUI control that allows you to inspect the Component hierarchy of models loaded with either the Exchange or Parasolid interface. Right-clicking on an item in the tree-view brings up a context menu which allows you to show, hide, or isolate an item in the viewport. Selecting an item in the viewport will highlight its corresponding item in the tree-view, and vice versa.

ComponentTree and ComponentTreeItem facilitate populating the tree control, and they have derived classes located in CHPSModelBrowserPane.cpp (for MFC), or ModelBrowser.cs (for WPF). Note that the model browser is only applicable when a Component hierarchy is present, such as when a model is loaded using one of the Component integrations.

Sandboxes with third-party integration

HOOPS Exchange: If you have a HOOPS Exchange license, Exchange support can be added to the MFC, WPF, Cocoa, Qt, and Wx sandboxes.

To use Exchange with the WPF sandbox, you must add USING_EXCHANGE to the list of "Conditional Compilation Symbols" in the WPF Visual Studio project file. You must also add a Reference in the Visual Studio project to hps_cs_sprk_exchange.dll. In the properties for the Reference to hps_cs_sprk_exchange.dll, set the Copy Local property to False.

To enable Exchange support in all other sandboxes, the project must be compiled with the USING_EXCHANGE preprocessor flag, and must be linked to hps_sprk_exchange.lib.

When using the sandboxes with Exchange, you need to locate the Exchange libraries for the application by calling HPS::World::SetExchangeLibraryDirectory.

If you load an Exchange file which has configurations, the "Configurations" tab of the model browser will display a list of the configurations in the file. If you double-click on a configuration, that configuration will be loaded from the file, replacing the currently loaded model.

HOOPS Publish: If you have a HOOPS Publish license, Publish support can be added to the MFC, WPF, Qt, and Wx sandboxes. In order to be able to save 3D PDFs you will need to rebuild the sandbox with the USING_PUBLISH preprocessor definition. You will also need to link against sprk_publish.

When USING_PUBLISH is defined, the sandboxes look for the HPUBLISH_INSTALL_DIR environment variable, which needs to be set by the user to point to the Publish installation directory.

Note that the 3D PDF export is only enabled when those sandboxes are run in Windows, since Publish is currently not supported anywhere else when integrated into HPS.

Parasolid: To enable Parasolid support, the MFC sandbox must be compiled with the USING_PARASOLID preprocessor flag, and must be linked to hps_sprk_parasolid.lib. The WPF sandbox requires that you add USING_PARASOLID to the list of "Conditional Compilation Symbols" in its project file, and you must add a reference to cs_sprk_parasolid. Additionally, some Parasolid files require schema files for import. For those files, it is necessary to either set the schema directory using either HPS::World::SetParasolidSchemaDirectory or the P_SCHEMA environment variable. Alternatively, you may or have a the schema subdirectory in the same folder as the executable.

Notes on WPF Sandbox

The WPF Sandbox supports both WinForms and D3DImage canvases with either DX9 or DX11. For an example on how they are used, see SprocketsWPFControl.cs in the wpf_sandbox project. WinForms is the default. If you want to use D3DImage, you'll have to define the USE_D3D_IMAGE_CANVAS variable as shown in the code. Other relevant lines are:

public SprocketsWPFControl(HPS.Window.Driver driver, string canvasName)
{
_canvas = new HPS.D3DImageCanvas(driver, canvasName);
// the following line sets the D3D image source
Source = _canvas.ImageSource;
Stretch = Stretch.Fill;
AllowDrop = true;
SizeChanged += SprocketsWPFControl_SizeChanged;
HPS.View view = HPS.Factory.CreateView(canvasName);
Canvas.AttachViewAsLayout(view);
}

Lastly, you must add a reference to the sprk_d3dimage library in order to use D3DImage.



Library descriptions

The following libraries are provided with HOOPS Visualize. You only need to include those libraries that your application uses:

Library nameDescriptionRequired?
hps_coreCore Graphicsalways
hps_sprkSupporting classeswhen using view hierarchy, or any module listed below
hps_sprk_opsStandard operatorswhen using operators
hps_sprk_exchangeVisualize-Exchange interface modulewhen using HOOPS Exchange
hps_sprk_publish Visualize-Publish interface modulewhen using HOOPS Publish

Windows

The officially supported platform and development environment for Windows is noted here. You can choose to develop in either C++ or C#. The solution file is called visualize_vc<version>.sln; it contains all the projects you might need to compile during the course of your development cycle, including the MFC Sandbox, a WPF Sandbox, and the sample code. The default installation directory is of the form hoops_visualize_hps<version>_vc<version>.

Tech Soft provides Visualize libraries as pre-compiled binaries, thus, there is nothing extra that needs to be built. Your application links to the Visualize libraries during the build process and subsequently to the DLLs at runtime.

C++

A few modifications must be made to a clean project file in order to compile a HOOPS Visualize application:

  1. The first step is to set the include file path in the project. It should be set to the include subdirectory of the root install location.
  2. Add the desired Visualize libraries to the project
  3. Ensure the dynamic libraries are in the environment PATH or your application's working directory. The DLLs are found in %install_dir%\bin<platform_name>, and the names correspond with the library names from step 2. For example, if you are using functionality found in hps_sprk.lib, the DLL is named hps_sprk.dll.

When running your Visualize application, the operating system will need to locate the Visualize DLLs in the environment PATH or the application's directory.

Conflicting macros in Windows C++ builds

There is a macro conflict that occurs frequently with certain Windows headers. The problem is that these headers #define a number of common names. Since #define can't be scoped by a namespace or class, they cause conflicts with other code. The most commonly encountered conflicts are min, max, and Window.

The solution is to simply include the HPS header file after any Windows headers. This will enable Visualize to determine if _WINDOWS_ is defined, and if so, it will undefine the conflicting macros.

C#

Similar to C++, your C# application must reference the Visualize C# assemblies that it requires. They are located in in %install_dir%\bin\<platform_name> The assembly names correspond to the C++ DLLs noted in the previous subsection, with one minor difference. The names include cs - for example, hps_core.dll becomes hps_cs_core.dll

The C# assemblies depend on the corresponding C++ DLLs. Thus, when using the hps_cs_core.dll assembly, the supporting C++ binary called hps_core.dll must also be in the environment PATH or the application's directory. The C++ DLLs are also located in in %install_dir%\bin<platform_name>.

Additionally, when compiling, the platform target must be either 32 or 64-bit. The "Any CPU" target will not work.

Redistributables

If you are using one of the DirectX drivers (DX9 or DX11) and wish to support Windows Vista, you must ensure that the Microsoft DirectX End-User Runtime is installed on the target machine. Microsoft provides both a redistributable standalone installer and a web installer.



Linux

The officially supported platform and development environment for Linux is noted here. There is a makefile for the sample applications (hps_samples), and a subdirectory for the QT sandbox (qt_sandbox).

For the samples, users can navigate to samples/code/cpp and run

 make <platform>

...where <platform> is one of [linux32, linux32-debug, linux64, linux64-debug].

For the QT sandbox, there is a qt_sandbox.pro file which can be used to build the application using QtCreator.

If you are using HPS on a Linux / Unix platform and directly or indirectly invoking the X11 API outside of HPS, please see the Special Platform Initialization section.



OSX

The officially supported platform and development environment for OSX is noted here. There is a workspace for the sample applications (hps_samples_osx), and subdirectories for the Cocoa sandbox (cocoa_sandbox) and QT sandbox (qt_sandbox).




Mobile Support: General Notes

The Visualize Mobile development framework allows you to code once for both systems to maintain platform-independent Visualize code.

This applies especially to events and event handling, where the interface related to user input is abstracted from platform-specific GUI or language. The sandboxes are set up so that the platform-specific events will trigger Visualize function calls:

If you choose not to use the framework provided by the sandboxes, you will have to coordinate this event handoff yourself.



iOS

The officially supported platform and development environment for iOS is noted here. There is no top-level workspace. The iOS package provides three library files, libhps_core.a, libhps_sprk.a, and libhps_sprk_ops.a.

In addition to the Visualize libraries mentioned above, your application should also link to these third-party libraries:

  • quartzcore.framework
  • opengles.framework
  • libz.1.2.5.dylib

NOTE: You must be registered in the iOS developer program. This step is required in order to run on a physical iOS device (as opposed to just running on the simulator).

The Sandbox

The iOS Sandbox is a sample application which shows how to integrate Visualize into an iOS app. It can be found at <HPS_install_dir>/samples/ios_sandbox/iOS-Sandbox.xcodeproj. iOS developers are encouraged to review it or use it as a template when writing their own Visualize application.

Of particular interest is the MobileSurfaceView class, which provides the infrastructure. MobileSurfaceView is a subclass of the Cocoa UIView class. Here, we are specifying that we want a CAEGLLayer as the view's layer type. Your application will need to do something similar:

+ (Class)layerClass
{
// Indicate that we will be using OpenGL ES
return [CAEAGLLayer class];
}

Additionally, the MobileSurfaceView init function includes the following initialization. If you create a custom view class you will need to do this as well:

CAEAGLLayer * eaglLayer = static_cast<CAEAGLLayer*>(self.layer);
eaglLayer.opaque = TRUE;
eaglLayer.drawableProperties = [NSDictionary dictionaryWithObjectsAndKeys:
[NSNumber numberWithBool:FALSE],
kEAGLDrawablePropertyRetainedBacking,
kEAGLColorFormatRGBA8,
kEAGLDrawablePropertyColorFormat, nil];

Any model that is to be loaded by the iOS Sandbox must be added to the Xcode project.

Handling input events

The iOS Sandbox will listen for events generated by the operating system, use them to build Visualize events, then inject the event objects into the Visualize event queue. If you do not use the iOS Sandbox as a template, you will have to make these connections yourself in order for Visualize to receive user input. You can see how input events are passed to Visualize by inspecting the sandbox code. For example, the sandbox injects a touch-down event in this way:

// MobileSurfaceView.mm (iOS-specific code)
- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event {
int xPosArray[MAX_TOUCHES];
int yPosArray[MAX_TOUCHES];
int idArray[MAX_TOUCHES];
int numTouches = [self buildTouchEvent:touches
withXArray:xPosArray
withYArray:yPosArray
withIdArray:idArray];
self.surfacePointer->touchMove(numTouches, xPosArray, yPosArray, idArray);
}

self.surfacePointer->touchMove refers to the following platform-independent function:

// MobileSurface.cpp (platform-independent code)
void MobileSurface::touchMove(int numTouches, int xposArray[], int yposArray[], int idArray[])
{
InjectTouchEvent(HPS::TouchEvent::Action::Move, numTouches, xposArray, yposArray, idArray);
}

As mentioned above, you are encouraged to use the iOS Sandbox as a template for your own application, as it will maintain platform independence related to events and event handling. All the platform-independent code related to the iOS Sandbox can found in <HPS_install_dir>/samples/shared.



Android

The officially supported platform and development environment for Android is noted here. When starting a new project using Android Studio, be sure to set the NDK directory before importing the Android Sandbox source. The following line needs to be added to your Application.mk file:

NDK_TOOLCHAIN_VERSION := clang

You must also have Python in your environment's PATH.

The Android package provides four binary libraries, libhps_core.so, libhps_sprk.so, libhps_sprk_ops.so, and libhps_sprk_exchange.so.

The libraries mentioned above are C++ native binaries. As such, all of your Visualize function calls must be made in C++. However, since the Android SDK is provided in Java, all GUI instantiation / interaction is written in Java. An example of how to combine the C++ and Java code into an application can be found in the Android Sandbox project.

The Sandbox

The Android Sandbox is a sample application which shows how to integrate Visualize into an Android app. It can be found at <HPS_install_dir>/samples/android_sandbox. Developers are encouraged to review it or use it as a template when writing their own Visualize application. If you do not start with the Sandbox, you will have to create much of the "glue" code yourself (see "Android Sandbox-Specific notes" below).

Android Sandbox requirements

In addition to the requirements listed on the Supported Platforms page, the sandbox project also requires:

Android Sandbox-specific notes

Any model that is to be loaded by the Android Sandbox must be present in the hps/samples/android_sandbox/app/src/main/assets/datasets.

Since Visualize is written in C++ and Android uses Java, the JVM must use JNI to call Visualize methods from Java. For event handling, Visualize handles this process for you during the build using a Python script. The script examines your C++ event handler declarations, creates corresponding Java functions, and sets up the JNI calls. The benefit of this system is that you can do all of your programming in C++ and you don't have to worry about JNI. Additionally, platform-independence is maintained.

As mentioned above, you are encouraged to use the Android Sandbox as a template for your own application, as it will maintain platform independence related to events and event handling. All the platform-independent code related to the Android Sandbox can found in <HPS_install_dir>/samples/android_sandbox/app/src/main/jni/shared.

You may notice that after opening the sandbox project in Android Studio, the project structure looks familiar. The jni folder contains the Java-C++ interface. The jni/shared directory contains files common to all mobile platforms. Of particular interest is UserMobileSurface.h. In that file, you'll see the GUI event handler function declarations are all preceded by the SURFACE_ACTION identifier. During the build process, the Python script sip.py (requires Python 2.7+) uses these tags to automatically generate the Java-C++ interface wrappers. In UserMobileSurface.cpp, you'll see the implementation function of each SURFACE_ACTION. Any new GUI component you add to your application should follow this paradigm when calling Visualize.

You should not modify any of the files that are auto-generated. Auto-generated files all have a comment near the top that looks like this:

// Auto-generated file

Any parameters present in your C++ event function declarations will be marshalled by sip.py into a form that is usable by C++:

  • char const * becomes String
  • char * becomes StringBuffer
  • int [] becomes arrays and 'out' parameters

Instructions on using Visualize operators for handling user input events can be found in the Programming Guide, section 6.

Using the Android Sandbox with Exchange

While the HPS Android package includes libhps_sprk_exchange.so, the Android Sandbox does not link against it by default. To enable this, we must first inform the Android Sandbox of where your HOOPS Exchange installation is. This can be done by setting the HEXCHANGE_INSTALL_DIR environment variable on your machine, which points to your local HOOPS Exchange installation.

Next, we need to inform the C++ code / makefiles that HOOPS Exchange is being used; this can be done by modifying hps/samples/android_sandbox/app/src/main/jni/hps.mk to include the following line at the top of the file: USING EXCHANGE := 1

Lastly, we need to tell the Java code to load the Exchange shared objects, which can be done by navigating to hps/samples/android_sandbox/app/src/main/java/com/techsoft3d/hps/sandbox/ViewerUtils.java and setting the USING_EXCHANGE variable to true.

Limitations

Any SURFACE_ACTION function declaration must be written on a single line. sip.py cannot process multiline function declarations.



Xamarin

As of Visualize 2017, HPS officially added Xamarin support for iOS and Android. Xamarin wraps the native iOS and Android SDKS in C# as well as providing platform agnostic GUI abstractions via Xamarin.Forms. The xamarin_sandbox projects included in Visualize 2017 utilizes Xamarin.Forms to isolate all application code (including the creation of GUI controls & HPS usage) into a single place, allowing users to approach a "code once, deploy everywhere" workflow.

The xamarin sandbox is split into several components.

  • xamarin_sandbox: Contains logic & interfaces generic to all platforms.
  • xamarin_sandbox.Droid: Contains Android-specific implementations of interfaces defined in xamarin_sandbox for usage in the generic codebase.
  • xamarin_sandbox.iOS: Contains iOS-specific implementations of interfaces defined in xamarin_sandbox for usage in the generic codebase.

Caveats / Shortcomings

  • Even though Xamarin does its best to limit executable size / runtime boot overhead by aggressively stripping symbols, the resulting application will be larger and slower to boot than its native counterpart due to the overhead of the .NET runtime.
  • Xamarin defines some reflection-based APIs which may provide some initial difficulties on platforms (like iOS) where Xamarin is performing aggressive symbol stripping and removes functions / members that are indirectly referenced via reflection.

Building the Xamarin package

In order to build the xamarin_sandbox you will need to download the HPS package(s) for the architecture(s) you are targeting in addition to the supplemental HPS Xamarin package. For example, if you're targeting Android, you'll need the HPS package for Android, along with the Xamarin package. If you're targeting both iOS and Android, you'll need the iOS HPS package, the Android HPS package, and the Xamarin package.

Once all these packages are downloaded, unzip / copy the root of each archive on top of each other. Then navigate to /samples/xamarin_sandbox and open xamarin_sandbox.sln in either Visual Studio or Xamarin Studio.

Targeting Android

To build the xamarin_sandbox target for Android, select xamarin_sandbox.Droid as your active project and make sure that your target configuration is 'Any CPU'. Once that is selected, you are ready to build and deploy.

If you want to use xamarin_sandbox_exchange instead, then select xamarin_sandbox_exchange.Droid as your active project instead. The exchange project only requires that you have the exchange root defined in the HEXCHANGE_INSTALL_DIR environment variable.

Targeting iOS

WARNING: It is recommended for users targeting iOS to use Xamarin Studio as their IDE for this project. Visual Studio is not recommended for building / deploying this app as it requires a remote OSX build machine to link in the iOS SDK Frameworks. This process is problematic as it requires the HPS libs to be copied over to the OSX build machine for linking which may take a long time given the size of the HPS binaries.

To build the xamarin_sandbox target for iOS, select xamarin_sandbox.iOS as your active project. If you are targeting a physical device, set your configuration to 'iPhone', and if you are targeting a simulator set your configuration to 'iPhone Simulator'. Once that is selected, you are ready to build and deploy.

If you want to use xamarin_sandbox_exchange instead, then select xamarin_sandbox_exchange.iOS as your active project. The Exchange project only requires that you have the HOOPS Exchange root defined in the HEXCHANGE_INSTALL_DIR environment variable.