########################
Extending HOOPS Exchange
########################

By default, HOOPS Exchange does not load all functions exposed by the API.
Some functions must be explicitly requested in order to access them.

HOOPS Exchange identifies two types of such functions: *experimental* and *extensions*.
Both are enabled by defining a C macro, either at the compiler level or within the code.

.. _ext_experimental_api:

Experimental Functions
======================

Experimental functions are available when ``A3DAPI_EXPERIMENTAL`` is defined.
This macro includes the *A3DSDKExperimental.h* header file, which is provided along with the standard headers.

When ``A3DAPI_EXPERIMENTAL`` is defined, your compiler will output a message to highlight the use of experimental features.

Since HOOPS Exchange 2024.7.0, we introduce a first experimental feature with :ref:`t_junction_removal`.

Extension Functions
===================

Extension functions are provided for specific use cases that fall outside the usual HOOPS Exchange API scope.
To enable them, define ``A3DAPI_EXTENSIONS``.

As of HOOPS Exchange |version|, no extension functions are available.

Deprecated Functions
====================

Since HOOPS Exchange 2025.1.0, the function deprecation process is:

1. In any release, the function is marked as deprecated in the documentation and header files, with a removal date.
2. In any later release, the function becomes opt-in: its name is prefixed with "deprecated_" and it is moved to the *A3DSDKDeprecated.h* header file.
3. In the release specified at step 1, the function is removed from the API.

Deprecated functions in the opt-in stage are available only when the ``A3DAPI_DEPRECATED`` macro is defined.
To use them, define the ``A3DAPI_DEPRECATED`` macro before every inclusion of the *A3DSDKDeprecated.h* header file, either directly or through the *A3DSDKIncludes.h* header.
It must also be defined beside the ``INITIALIZE_A3D_API`` macro.

When ``A3DAPI_DEPRECATED`` is defined, your compiler will output messages to highlight the use of deprecated features.

Examples
========

This code extends the example provided in :doc:`/guide/basic_operations/initialize-hoops-exchange`, enabling experimental features by defining ``A3DAPI_EXPERIMENTAL`` on line 2.

.. code-block:: c
   :emphasize-lines: 2

   #define INITIALIZE_A3D_API
   #define A3DAPI_EXPERIMENTAL
   #include <A3DSDKIncludes.h>
   #include <hoops_license.h>

   // Usual initialization code
   int main(int argc, char* argv[])
   {
     A3DBool loaded = A3DSDKLoadLibraryA(PATH_TO_A3DLIBS_DIR);
     assert(loaded);

     A3DStatus result = A3DLicPutUnifiedLicense(HOOPS_LICENSE);
     assert(result == A3D_SUCCESS);

     result = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);
     assert(result == A3D_SUCCESS);

     // HOOPS Exchange is now ready to use!

     A3DDllTerminate();
     A3DSDKUnloadLibrary();

     return EXIT_SUCCESS;
   }

``A3DAPI_EXPERIMENTAL`` and ``A3DAPI_EXTENSIONS`` must also be defined in any source file that calls one of these additional functions.

This code extends the example provided in :doc:`/guide/basic_operations/initialize-hoops-exchange`, enabling deprecated features by defining ``A3DAPI_DEPRECATED`` on line 2 and calling a deprecated function on line 19.

.. code-block:: c
   :emphasize-lines: 2

   // main.c file
   #define INITIALIZE_A3D_API
   #define A3DAPI_DEPRECATED
   #include <A3DSDKIncludes.h>
   #include <hoops_license.h>
   
   extern void CallDeprecatedFunction();

   // Usual initialization code
   int main(int argc, char* argv[])
   {
     A3DBool loaded = A3DSDKLoadLibraryA(PATH_TO_A3DLIBS_DIR);
     assert(loaded);

     A3DStatus result = A3DLicPutUnifiedLicense(HOOPS_LICENSE);
     assert(result == A3D_SUCCESS);

     result = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);
     assert(result == A3D_SUCCESS);

     // HOOPS Exchange is now ready to use!
     CallDeprecatedFunction();

     A3DDllTerminate();
     A3DSDKUnloadLibrary();

     return EXIT_SUCCESS;
   }
   
   // other.c file
   #define A3DAPI_DEPRECATED
   #include <A3DSDKDeprecated.h>

   // Call a deprecated function
   void CallDeprecatedFunction()
   {
     // Let's call a deprecated function to check
     A3DStatus result = deprecated_A3DEnableHandleSIGSEGV();
     assert(result == A3D_SUCCESS);
   }

``A3DAPI_DEPRECATED`` must also be defined in any source file that calls one of the deprecated functions.

For simplicity, you can define the macros at the compiler level using a compiler option such as ``/D`` or ``-D``.
