.. _getting_started:

Installation & Setup
--------------------

Requirements
~~~~~~~~~~~~

To begin using the SDK, you need:

#. The `Beam Eye Tracker <https://beam.eyeware.tech/>`_ application version 2.6.3 or later installed and set up on your system.
#. The SDK package downloaded and unzipped on your system (:doc:`/info/download`) . If using Python, this is optional when installing from PyPI.
#. A development environment for your chosen programming language or framework.

The C and C++ SDKs ship native client libraries for Windows, Linux, and macOS.
Python bindings are available for the same platforms through PyPI and through the
``python/package`` folder in the SDK archive. These native client libraries are
thin loaders: your application ships or loads the SDK client library, while the
Beam Eye Tracker installation provides the platform runtime library containing
the implementation. The loader locates the Beam-provided runtime and verifies
supported runtime candidates before loading them. The beta JavaScript SDK is
provided as a WebAssembly-backed ES module package in the ``javascript`` folder;
its WebAssembly module contains the JavaScript runtime implementation. The C#
wrapper can be used from desktop .NET applications when the matching native
client library for the target platform is available to the application. The
Unity package and beta Godot plugin included in the archive are Windows-only.

.. _beam_sdk_integration_project_configuration:

Project configuration
~~~~~~~~~~~~~~~~~~~~~

Depending on your specific project and language, you need to follow the steps below to integrate the SDK.

.. tab-set::

    .. tab-item:: C/C++
        :sync: cpp

        #. Add the |sdk_include| directory to your project's include paths.
        
           .. note:: In case of using CMake, you can use the ``target_include_directories`` command.

        #. Add the platform-specific library directory to your project's library directories:

           * Windows: |sdk_lib_win64|
           * Linux: |sdk_lib_linux64|
           * macOS: |sdk_lib_macos|

           .. note:: In case of using CMake, you can use the ``target_link_directories`` command.

        #. Link against the platform library:

           * Windows: ``beam_eye_tracker_client.lib``
           * Linux: ``libbeam_eye_tracker_client.so``
           * macOS: ``libbeam_eye_tracker_client.dylib``

           .. note:: In case of using CMake, you can use the ``target_link_libraries`` command.

        #. Make the SDK client library available next to your application or through the platform's normal loader path:

           * Windows: copy ``beam_eye_tracker_client.dll`` from |sdk_bin_win64| to your output directory.
           * Linux: deploy ``libbeam_eye_tracker_client.so`` from |sdk_lib_linux64| with your application or configure ``rpath``/``LD_LIBRARY_PATH``.
           * macOS: deploy ``libbeam_eye_tracker_client.dylib`` from |sdk_lib_macos| with your application or configure ``rpath``/``DYLD_LIBRARY_PATH``.

        .. note:: On Windows, we also provide an alternative library build with ``/MT`` (``beam_eye_tracker_client_MT.lib`` and ``beam_eye_tracker_client_MT.dll``), which does not require the Visual C++ Redistributable on the host machine. In most cases, the default ``/MD`` build is preferred.

    .. tab-item:: Python
        :sync: python

        #. Install the ``beam-eye-tracker`` package:

            .. parsed-literal::

                |pip_install|

            .. note:: Alternatively, you can download the SDK, unzip it and add the |sdk_python_package| directory to your ``PYTHONPATH``.
        
        #. Test your installation:

            .. code-block:: python

               # This should not raise an import error:
               from eyeware.beam_eye_tracker import API

    .. tab-item:: JavaScript (Beta)
        :sync: javascript

        The beta JavaScript package is in
        |sdk_javascript|. It includes the public ES
        module entry point, TypeScript declarations, the WebAssembly runtime
        files, and browser samples. The package can be used from browsers,
        Electron renderer processes, Electron main processes, and Node.js.

        #. Install from the SDK package directory or copy it into your web app:

            .. parsed-literal::

                |npm_install_js|

        #. Import the package entry point:

            .. code-block:: javascript

                import { createSession } from "@eyeware/beam-eye-tracker";

                const api = await createSession("My JavaScript Client");
                console.log(api.getTrackingDataReceptionStatusName());
                api.destroy();

        #. If you copy files manually, keep the ``javascript/lib`` directory next
           to ``javascript/index.js``. The generated WebAssembly runtime loads
           its module and worker files from that relative layout.

        .. note:: Browser hosts must serve the application and SDK files with
           ``Cross-Origin-Opener-Policy: same-origin`` and
           ``Cross-Origin-Embedder-Policy: require-corp`` so
           ``SharedArrayBuffer`` is available to the WebAssembly pthread runtime.

        .. note:: For latency-critical desktop integrations, prefer the native
           C, C++, C#, or Python SDK clients for the target platform.

    .. tab-item:: C#
        :sync: csharp

        This assumes the project platform target is ``x64``. The C# wrapper uses
        ``DllImport("beam_eye_tracker_client")`` and loads the native Beam SDK
        client through the platform's normal native-library resolution rules.

        .. note:: The SDK archive provides the C# wrapper source file and the
           native libraries, not a NuGet package or project file that copies
           native libraries automatically. Your application build or packaging
           process must deploy the matching native library for each target
           desktop platform.

        #. Copy |sdk_csharp_wrapper| into your project directory (e.g., root or a subfolder like ``Eyeware/``).

        #. Include the ``BeamEyeTracker.cs`` file in your project.
        
            .. note:: For Visual Studio: Right-click the project in Solution Explorer, select ``Add > Existing Item``, and add ``BeamEyeTracker.cs``.

        #. Make the matching native SDK client library available next to your application or through the platform's normal loader path:

           * Windows: copy ``beam_eye_tracker_client.dll`` from |sdk_bin_win64| to your output directory.
           * Linux: deploy ``libbeam_eye_tracker_client.so`` from |sdk_lib_linux64| with your application or configure ``rpath``/``LD_LIBRARY_PATH``.
           * macOS: deploy ``libbeam_eye_tracker_client.dylib`` from |sdk_lib_macos| with your application or configure ``rpath``/``DYLD_LIBRARY_PATH``.
            
            .. note:: For Visual Studio: Add it to the project (``Add > Existing Item``), then set ``Properties > Copy to Output Directory`` to ``Copy always``.

        #. Add the using directive in your code:

           .. code-block:: csharp

               using Eyeware.BeamEyeTracker;

    .. tab-item:: Unity
        :sync: unity

        .. note:: A ready to use Windows Unity package is available. See :ref:`unity_installation` for more information.

    .. tab-item:: Godot
        :sync: godot

        .. note:: A beta Windows Godot plugin is included in ``godot/addons/beam_eye_tracker``. See :ref:`godot_installation` for more information.


Now that you have the SDK integrated into your project, you can continue to the next
section to get a general explanation of how the API is structured.
