Camera.hpp

#pragma once
/// \file Camera.hpp Header fille for the Camera functions of the BSP library.

#include <cstdint>
#include <string>
#include <map>

namespace Bsp {
  namespace Camera {

    /// \brief Get the number of cameras in the system.
    /// \return The number of cameras in the system.
    uint16_t GetNumberOfCameras(void);

    /// \brief Set up camera to take images when a particular trigger fires.
    /// \param [in] Index Index of the camera to set up.  The first
    /// camera has index 1.
    /// \param [in] Trigger Which internal trigger to use for the camera,
    /// or 0 for no trigger (disabled).  The camera will take an image
    /// whenever the specified trigger fires.
    /// \return true if the camera was set up successfully.
    bool SetupCamera(uint16_t Index, uint32_t Trigger);

    /// \brief Type definition for a callback function to receive boolean state changes from a camera.
    /// \param [in] Index Index of the camera that generated the callback.
    /// \param [in] State The new state of the boolean item.
    /// \param [in] Seconds The system time seconds when the state changed.
    /// \param [in] Microseconds The system time microseconds when the state changed.
    /// \param [in] UserData User data pointer that was provided when the callback was registered.
    typedef void (*CameraBooleanStateCallback)(uint16_t Index, bool State, uint32_t Seconds, uint32_t Microseconds,
      void* UserData);

    /// \brief Register a callback function to receive Non-Uniformity Correction (NUC) flag state changes.
    /// \param [in] CallbackFunction The function to call when the NUC flag state changes.
    /// \param [in] UserData User data pointer that will be passed to the callback function.
    /// \return true if the callback was registered successfully.
    bool RegisterNUCFlagStateCallback(CameraBooleanStateCallback CallbackFunction, void* UserData = nullptr);

    /// \brief Unregister the callback function for NUC flag state changes.
    /// \return true if the callback was unregistered successfully.
    bool UnregisterNUCFlagStateCallback();

    /// \brief Register a callback function to receive on-camera NUC state changes.
    /// \param [in] CallbackFunction The function to call when the on-camera NUC state changes.
    /// \param [in] UserData User data pointer that will be passed to the callback function.
    /// \return true if the callback was registered successfully.
    bool RegisterOnCameraNUCStateCallback(CameraBooleanStateCallback CallbackFunction, void* UserData = nullptr);

    /// \brief Unregister the callback function for on-camera NUC state changes.
    /// \return true if the callback was unregistered successfully.
    bool UnregisterOnCameraNUCStateCallback();

    /// \brief GetStatus
    /// \param [in] Index of the camera to get status for.  The first
    /// camera has index 1.
    /// \return map of status items. This will always include the following
    /// items: type, width, height, minTriggerPeriod (fractional seconds),
    /// maxTriggerPeriod (fractional seconds), nucFlagAvailable, onCameraNUCAvailable.
    std::map<std::string, std::string> GetStatus(uint16_t Index);

    /// \brief Set the state of the Non-Uniformity Correction physical flag.
    /// \details This will be used both for on-camera NUC requests and for
    /// software-based NUC (by flipping the flag up and taking images for
    /// awhile and doing processing on the images).
    /// \param [in] Flipped true to flip the flag up, false to flip it out of the way.
    /// \param [in] Index Index of the camera to set up.  The first
    /// camera has index 1.
    /// \return true if the flag was set successfully.
    bool SetNUCFlagState(uint16_t Index, bool Flipped);

    /// \brief Start the on-camera NUC process.
    /// \param [in] Index Index of the camera to set up.  The first
    /// camera has index 1.
    /// \return true if the process was started successfully.
    bool StartOnCameraNUC(uint16_t Index);

  }
}