#################
Programming Guide
#################

***************
Getting Started
***************

The Envision Result Calculator Framework is a part of the "|ProductName|" distribution and can be downloaded from 
https://developer.techsoft3d.com. The result calculator framework is found in the **ResultCalculatorFramework** folder 
in the Envision distribution. The result calculator  framework is provided as source code so you can compile with your 
favorite compiler and settings.

To compile the framework, example plugins and example apps, we recommend using CMake. Download CMake from 
https://cmake.org/download/.

To build and run the examples, please follow the steps below:

-   Unzip the "|ProductName|" distribution file info a folder
-   Go to the ResultCalculatorFramework folder in the distribution.
-   Create a build folder (e.g. Build on the same level as ResultCalculator)
-   `> cd Build`
-   `> cmake ../ResultCalculator`

On Linux/mac, build the solution with:

::

    > make

On Windows, open the project file and build with the selected compiler (e.g. Visual Studio).

The build step will build:

-   ResultCalculatorHostLib
-   MinimalPlugin
-   TestDriver

To Run the Test Driver:

::

    cd ExampleApps/TestDriver/
    ./TestDriver ../../ExamplePlugins/MinimalPlugin/crc_MinimalPlugin

.. note::
    The binaries may be stored in a sub Debug or Release folder on some platforms

*********************************
Creating a ResultCalculatorPlugin
*********************************

There are three steps to creating a ResultCalculatorPlugin

**Step 1: Create the Plugin**

The main file defines the plugin. You define a version and a method for creating the Factory. The 
:func:`CRCResultCalculator::initializeResultCalculatorPlugin` method is called by the host to initialize the calculator.

Example: MinimalPlugin.cpp

**Step 2: Create the Result Calculator Factory**

The factory is responsible for instantiation and deletion of the ResultCalculator and providing information about the 
calculator. 
To create the factory, derive from :class:`CRCResultCalculatorFactory` and implement the pure virtual methods.

Example: MinimalCalculatorFactory.h/cpp

**Step 3: Create the Result Calculator**

The calculator is where the meta data (input results, name etc) are communicated to the host and where the actual result 
calculation occur.
To create a calculator, derive from :class:`CRCResultCalculator` and implement the pure virtual methods.

Example: MinimalCalculator.h/cpp

*********************************************
Using Result Calculator in |WebProductName|
*********************************************

The Result Calculator can be used with the RemoteModel server (CeeCloudServer). To load your Result Calculator, set the 
`C3_UG_RESULT_CALCULATOR_FOLDER` environment variable to point to the folder with your Result Calculator(s). The 
CeeCloudServer will load all the Result Calculators in the specified folder. The Result Calculators needs to comply to 
the following naming scheme:

::

    crc_{PROVIDER_NAME}.[dll|so|dylib]

Example:

::

    crc_MyResultCalculator.dll (Windows), crc_MyResultCalculator.so (Linux)

The server will list the registered Result Calculator when a file is opened.

.. note::
    A given Result Calculator may be ignored when loading a model if it's considered to be invalid, e.g. the requested 
    input results don't exist or have mismatching result types and such.

********************************************
Using Result Calculator in Envision Analyzer
********************************************

To use your Result Calculator with HOOPS Envision Analyzer for Desktop, define the environment variable 
`CEE_RESULT_CALCULATORS_FOLDER` to point to the folder where your Result Calculator is located.
HOOPS Envision Analyzer will load all Result Calculator in the specified folder. The Result Calculator file needs to follow the 
same naming scheme as described above.  
