####################
Programming Language
####################

HOOPS Luminate is a C++ API. Therefore, HOOPS Luminate gets used after inclusion of header files that are all located in the 'HOOPS Luminate.m' module of HOOPS Luminate under the product installation filetree:

.. figure:: api_location.png
  :align: center
  
  **Location of the HOOPS Luminate 4.0 header files under the installation filetree**

There are two categories of objects in HOOPS Luminate:

    1. Atomic classes, such as: ``RED::Matrix``, ``RED::StateShader`` or ``RED::String``
    2. Interfaces, such as ``RED::IShape``, ``RED::ISoftLight`` or ``RED::IDataManager``

Atomic classes are generally used a method parameters and can generally be created on the stack and destroyed after use. For example:

.. code:: cpp 

    // Example of a matrix created locally to the method, and used in a method:
    {
        RED::Matrix matrix;
        matrix.SetTranslation( RED::Vector3( 1.0f, 10.0f, 100.0f ) );

        // As an example, set the matrix as a transform node pivot matrix. 'itransform' is a RED::ITransformShape
        // interface, 'iresmgr' is our cluster's resource manager interface:
        RC_TEST( itransform->SetPivotAxis( matrix, iresmgr->GetState() ) );

        // On exiting this code block, 'matrix' is released from memory.
    }

Interfaces are accessed from HOOPS Luminate objects. Many API methods are manipulating ``RED::Object`` pointers. These objects are often returned by HOOPS Luminate creation methods (such as the ``RED::Factory::CreateInstance`` call). Given the object, it generally implements a set of services that can be accessed through interfaces:

.. include:: /tasks/ta_ca/ta_ca_application/tk_accessing_to_red_object_interfaces.rst

These interfaces allow a smooth evolution of the HOOPS Luminate services at a minimal change cost for the calling applications over the successive API versions.


**************************
Cross Platform Compilation
**************************

HOOPS Luminate builds on Windows x64; Linux x64 and MacOSX x64. Some #define statements are required to ensure a proper compilation of HOOPS Luminate under each platform:

    * _WIN32 and _WIN64 on Windows x64
    * _LIN32 and _LIN64 on Linux x64
    * _MAC32 on Mac OSX x64

Please make sure that the right set of #define values are activated for each platform. If these statements are not properly defines, HOOPS Luminate *may* compile in your software, but run-time errors will probably crash your application, due to incorrect virtual tables or wrong objects byte sizes.


***************************
Linking with HOOPS Luminate
***************************

To link HOOPS Luminate with an application, please refer to the :doc:`/book/subjects/bk_ba/bk_ba_deployment` page.


*****************
Coding Principles
*****************

The HOOPS Luminate API is quite small and compact. This is by design choice. We have tried to follow a few rules in the definition of the API and in the names of API parameters:

    * Method input parameters have names starting with a lowercase 'i' letter
    * Method output parameters have names starting with a lowercase 'o' letter
    * Generally speaking, output parameters come first in the method's parameters, before input parameters

.. code:: cpp

    RED_RC MyMethod( RED::Object*& oParameterOutput, unsigned int iParameterInput );


* Most SDK methods do return a ``RED_RC`` return code value: HOOPS Luminate does not use any C++ exception, not to interfere with the hosting application exception management policy. Checking ``RED_RC`` returned values is *vital* for any HOOPS Luminate application. There are many return codes, and ensuring that applications don't raise unexpected return codes is a mandatory step for a proper HOOPS Luminate usage.

**************
API Evolutions
**************

The HOOPS Luminate API is not frozen. This means that each new version of HOOPS Luminate will deliver new APIs needed to use the new features that were implemented by the Tech Soft 3D team. Besides that, the Tech Soft 3D team may change existing APIs over the time. This may require some changes in the HOOPS Luminate client applications. Our objective is to keep the HOOPS Luminate API clear and usable to all. Therefore, there's no API deprecation in HOOPS Luminate: we do remove a method if it has become useless or if it's replaced by a newer more efficient other service.

In all cases, we publish a HOOPS Luminate migration guide to follow to successfully migrate from a HOOPS Luminate version to another one. 
