From 9cf8a800fdca65977c426968ce9be1c319940bdb Mon Sep 17 00:00:00 2001 From: Mathew Sutcliffe Date: Tue, 26 Mar 2013 00:19:12 +0000 Subject: [PATCH] initial doxygen comments and minor cleanup --- src/blackcore/simulator.cpp | 2 +- src/blackcore/simulator.h | 171 +++++++++++++++++++++++------------- 2 files changed, 113 insertions(+), 60 deletions(-) diff --git a/src/blackcore/simulator.cpp b/src/blackcore/simulator.cpp index 20f76662c..b4e68ebd5 100644 --- a/src/blackcore/simulator.cpp +++ b/src/blackcore/simulator.cpp @@ -43,7 +43,7 @@ namespace BlackCore { ISimulator *result = NULL; getDriverVersionMajor driverVersionMajor; - getDriverVersionMinor driverVersionMinor; + //getDriverVersionMinor driverVersionMinor; createISimulatorInstance createDriver; switch (sim) diff --git a/src/blackcore/simulator.h b/src/blackcore/simulator.h index f74b4791d..b1db49fff 100644 --- a/src/blackcore/simulator.h +++ b/src/blackcore/simulator.h @@ -6,17 +6,21 @@ #ifndef SIMULATOR_H #define SIMULATOR_H -#include -#include - #include "blackcore/sim_callbacks.h" #include "blackcore/vector_geo.h" #include "blackcore/vector_3d.h" +#include +#include + #define SHARED_LIBRARY_NAME_FS9 "bb_driver_fs9" #define SHARED_LIBRARY_NAME_FSX "bb_driver_fsx" #define SHARED_LIBRARY_NAME_XPLANE "bb_driver_xplane" +/*! + * \file Simulator driver interface. + */ + namespace BlackMisc { class IContext; @@ -25,144 +29,193 @@ namespace BlackMisc { namespace BlackCore { + /*! + * A struct to hold data about an aircraft model and repaint. + */ class CPlaneModel { public: - QString name; - QString typeCode; - QString airlineCode; + QString name; //!< full name of the aircraft model, arbitrary string (hopefully unique) + QString typeCode; //!< ICAO aircraft type code + QString airlineCode; //!< ICAO air operator code }; + /*! + * A struct for passing around the physical state of an aircraft. + */ class CPhysicalState { public: + //! Constructor, initialize to zero. CPhysicalState() : headingDegrees(0), pitchDegrees(0), bankDegrees(0), groundSpeedKnots(0) {} - CVectorGeo position; - float headingDegrees; - float pitchDegrees; - float bankDegrees; - float groundSpeedKnots; - CVector3D trueSpeedMetersPerSec; + CVectorGeo position; //!< geographical position + float headingDegrees; //!< heading in degrees + float pitchDegrees; //!< pitch in degrees + float bankDegrees; //!< bank in degrees + float groundSpeedKnots; //!< ground speed in knots + CVector3D trueSpeedMetersPerSec; //!< needed by FSX }; + /*! + * A struct for passing around the avionics state of an aircraft. + */ class CAvionicsState { + //! Constructor, initialize to zero. CAvionicsState() : squawkCode(0), squawkModeC(false), squawkIdent(false), com1FreqHz(0), com2FreqHz(0) {} - qint16 squawkCode; - bool squawkModeC; - bool squawkIdent; - qint32 com1FreqHz; - qint32 com2FreqHz; + qint16 squawkCode; //!< decimal squawk code + bool squawkModeC; //!< true if squawking mode C + bool squawkIdent; //!< true if squawking ident + qint32 com1FreqHz; //!< COM1 radio frequency in Hz + qint32 com2FreqHz; //!< COM2 radio frequency in Hz }; + /*! + * A struct for passing around the animation state of an aircraft. + */ class CAnimationState { public: + //! Constructor, initialize to zero. CAnimationState() : gearPercent(0), flapsPercent(0), landingLights(false), taxiLights(false), navLights(false), strobeLights(false), beaconLights(false) {} - qint8 gearPercent; - qint8 flapsPercent; - bool landingLights; - bool taxiLights; - bool navLights; - bool strobeLights; - bool beaconLights; + qint8 gearPercent; //!< 0 = retracted, 100 = extended + qint8 flapsPercent; //!< 0 = ratracted, 100 = extended + bool landingLights; //!< true if landing lights on + bool taxiLights; //!< true if taxi lights on + bool navLights; //!< true if nav lights on + bool strobeLights; //!< true if strobe lights on + bool beaconLights; //!< true if beacon lights on }; + //! A callback that is called when the simulator is started. typedef std::tr1::function cbSimStarted; - typedef std::tr1::function cbChangedAvionicsState; - typedef std::tr1::function cbChangedAnimationState; - typedef std::tr1::function cbChangedModel; - typedef std::tr1::function cbSendTextMessage; + //! A callback that is called when the user's plane changes its avionics state. + typedef std::tr1::function cbChangedAvionicsState; + + //! A callback that is called when the user's plane changes its animation state. + typedef std::tr1::function cbChangedAnimationState; + + //! A callback that is called when the user's plane changes its model. + typedef std::tr1::function cbChangedModel; + + /*! + * The interface that is implemented by each simulator driver. + * + * Simulator drivers are responsible for communicating with the simulator on the user's + * computer and keeping it in sync with the client. + */ class ISimulator { public: - - /// Version of the driver interface. To increment when the interface change. + // Version of the driver interface. To increment when the interface change. static const quint32 InterfaceVersionMajor; static const quint32 InterfaceVersionMinor; + //! Enumeration to describe which simulator is desired. enum ESimulator { - FS9 = 0, - FSX, - XPLANE, + FS9 = 0, //!< Microsoft Flight Simulator 9 + FSX, //!< Microsoft Flight Simulator 10 + XPLANE, //!< X-Plane }; + //! Constructor. ISimulator() {} + + //! Destructor. virtual ~ISimulator() {} + //! Provide the driver with a pointer to the global context. virtual void setLibraryContext(BlackMisc::IContext *context); + //! Factory method. static ISimulator *createDriver(ESimulator sim); - //////////////////////////////// - // Global section - //////////////////////////////// - + //! Initialize the driver. virtual int init() = 0; + //! Connect to the simulator. virtual int connect() = 0; - // Callback when the Simulation starts + //! Provide a callback to be called when the simulation starts. virtual void setcbSimStarted(const cbSimStarted &func); + //! Query whether the driver is connected to the simulator. virtual bool isConnected() = 0; + //! If there has been an error, return the associated message. virtual QString getLastErrorMessage() = 0; - //////////////////////////////// - // User plane section - //////////////////////////////// - - // Callback avionics state + //! Provide a callback to be called when the user plane changes avionics state. virtual void setcbChangedAvionicsState(const cbChangedAvionicsState &func); - // Callback animation state + //! Provide a callback to be called when the user plane changes animation state. virtual void setcbChangedAnimationState(const cbChangedAnimationState &func); - // Callback, when the Aircraft is set or gets changed + //! Provide a callback to be called when the user plane changes model. virtual void setcbChangedModel(const cbChangedModel &func); - // Not const because it may need to mutate state in order to communicate with the sim + //! Returns true if the user plane is in contact with the ground. virtual bool isOnGround() = 0; - // This might block - use QtConcurrent::run if that is a problem + /*! + * Returns the physical state of the user plane. + * \warning This might block - use QtConcurrent::run if that is a problem. + */ virtual CPhysicalState getPhysicalState() = 0; - //////////////////////////////// - // Remote plane section - //////////////////////////////// - - // This might block - use QtConcurrent::run if that is a problem + /*! + * Adds a plane to the simulator traffic and returns its handle. + * \warning This might block - use QtConcurrent::run if that is a problem + */ virtual qint32 addPlane(const QString &callsign) = 0; + /*! + * Remove a plane from the simulator traffic. + * \param planeID a handle that was returned by addPlane(). + */ virtual bool removePlane(const qint32 planeID) = 0; + /*! + * Set the model of an aircraft in the simulator traffic. + * \param planeID a handle that was returned by addPlane(). + */ virtual void setModel(const qint32 planeID, const CPlaneModel &model) = 0; + /*! + * Set the physical state of an aircraft in the simulator traffic. + * \param planeID a handle that was returned by addPlane(). + */ virtual bool setPhysicalState(const qint32 planeID, const CPhysicalState &state) = 0; + /*! + * Set the animation state of an aircraft in the simulator traffic. + * \param planeID a handle that was returned by addPlane(). + */ virtual bool setAnimationState(const qint32 planeID, const CAnimationState &state) = 0; - // Calls the supplied visitor function once for every model available in the simulator. + //! Calls the supplied visitor function once for every model available in the simulator. virtual void visitAllModels(const std::tr1::function &visitor) = 0; - // Fills container with all models. Works for any container that supports push_back. + /*! + * Fills container with all models. + * Class T must be a container of CPlaneModel objects and must support push_back. + */ template void getAllModels(T &container) { visitAllModels(std::tr1::bind(T::push_back, container)); } protected: - BlackMisc::IContext *m_libraryContext; + BlackMisc::IContext *m_libraryContext; //!< The global context. - cbSimStarted m_cbSimStarted; - cbChangedAvionicsState m_cbChangedAvionicsState; - cbChangedAnimationState m_cbChangedAnimationState; - cbChangedModel m_cbChangedModel; + cbSimStarted m_cbSimStarted; //!< Callback to call when the sim starts. + cbChangedAvionicsState m_cbChangedAvionicsState; //!< Callback to call when the user plane changes avionics state. + cbChangedAnimationState m_cbChangedAnimationState; //!< Callback to call when the user plane changes animation state. + cbChangedModel m_cbChangedModel; //!< Callback to call when the user plane changes model. }; } //! namespace BlackCore