Commit 00420480 authored by Pascal Palenda's avatar Pascal Palenda
Browse files

Refinement and documenting

parent 1d91e1b0
......@@ -38,14 +38,20 @@ namespace ITA
class ITA_SIMULATION_SCHEDULER_API IAudibilityFilter
{
public:
///
/// \brief Usage mode for audibility filter.
///
enum class UsageMode
{
filter,
condition
filter, ///< Use the audibility filter as an actual filter.
condition ///< Use the audibility filter as a condition for following filters.
};
///
/// \brief Configuration class for an audibility filter.
/// \brief Base configuration class for audibility filter.
///
/// \note ::sFilterType is a read only property of the AudibilityFilterConfig.
/// Due to this the copy constructor and assignment operator are needed.
///
struct ITA_SIMULATION_SCHEDULER_API AudibilityFilterConfig : public IConfig
{
......@@ -77,8 +83,6 @@ namespace ITA
///
/// \brief Check if the change between \p previousState and \p newUpdate is audible.
///
/// \note Default behaviour it to return false.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check for audibility.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
......@@ -88,6 +92,7 @@ namespace ITA
protected:
///
/// \brief Checks weather the \p newUpdate happened after \p previousState.
/// \note This method should be called first in every ::changeIsAudible.
/// \throws ITAExcept when \p previousState happened after \p newUpdate.
/// \param previousState CUpdateScene of the previous state.
/// \param newUpdate new CUpdateScene.
......@@ -100,6 +105,7 @@ namespace ITA
///
/// This class implements an extensible factory for filter.
/// After a type of filter is registered with its IAudibilityFilter::createFilter, it can be created using this factory.
/// \todo Add a way to get the correct config from the type. The factory already knows of all possible filters.
///
class ITA_SIMULATION_SCHEDULER_API CAudibilityFilterFactory
{
......
......@@ -21,9 +21,20 @@ namespace ITA
namespace audibility_filter
{
///
/// \brief This class models a network of audibility filters.
///
/// It enables a easy building an evaluation of the configured network.
/// The actual network is modeled as a tree.
/// Even though in trees paths can not merge, a tree enables an easy way to model the network.
/// However, merging paths can still be modeled this way.
///
class ITA_SIMULATION_SCHEDULER_API CFilterNetwork
{
public:
///
/// \brief Configuration class for CFilterNetwork.
///
struct ITA_SIMULATION_SCHEDULER_API FilterNetworkConfig : public IConfig
{
std::vector<std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>> vpFilterConfigs;
......@@ -41,40 +52,108 @@ namespace ITA
CFilterNetwork& operator=( const CFilterNetwork& ) = delete;
CFilterNetwork ( const FilterNetworkConfig& oConfig );
///
/// \brief Constructor for CFilterNetwork.
/// \param oConfig the FilterNetworkConfig to configure the CFilterNetwork.
///
explicit CFilterNetwork ( const FilterNetworkConfig& oConfig );
///
/// \brief Evaluate the CFilterNetwork.
///
/// This method goes through the configured network and checks weather the \p newUpdate is audible.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
///
bool evaluateNetwork ( const CUpdateScene& previousState, const CUpdateScene& newUpdate );
private:
///
/// \brief Tree node used to model the actual network.
///
class NetworkTreeNode
{
public:
///
/// \brief Default constructor for NetworkTreeNode.
///
NetworkTreeNode ( ) = default;
///
/// \brief Constructor for NetworkTreeNode.
///
/// This constructor set the filter to be executed for the tree node and how it should be used.
/// \p bInvertCondition is only used if the UsageMode is set to be a condition.
/// \param pFilter the filter to be executed for the tree node.
/// \param eUsageMode the UsageMode for the filter.
/// \param bInvertCondition true, if the condition should be inverted.
///
NetworkTreeNode ( const IAudibilityFilter* pFilter, IAudibilityFilter::UsageMode eUsageMode, bool bInvertCondition );
///
/// \brief Evaluate the tree nodes filter and its children.
///
/// This method first evaluates the filter or condition for this node.
/// Depending on the result, the children of this node are evaluated next.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
///
bool evaluate ( const CUpdateScene& previousState, const CUpdateScene& newUpdate );
///
/// \brief Children of the node.
///
std::vector<NetworkTreeNode > vChildren;
private:
///
/// \brief The audibility filter of the tree node.
///
const IAudibilityFilter* m_pFilter;
///
/// \brief The usage mode for the filter.
///
IAudibilityFilter::UsageMode m_eUsageMode;
///
/// \brief True, if the condition should be inverted.
///
bool m_bInvertCondition;
};
///
/// \brief Create all the actual filter instances that were configured.
/// \param vpFilterConfigs vector of all filters that should be created.
///
void createFilters ( const std::vector<std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>>& vpFilterConfigs );
///
/// \brief Build the network tree.
/// \param oConfig configuration from which to build the tree.
///
void buildNetwork ( const FilterNetworkConfig& oConfig );
///
/// \brief Recursive helper method for building the network tree.
/// \param mConfigMap map relating the filter name to its config.
/// \param oRoot the root from which to build the tree.
/// \param oRootConfig
///
void networkBuilderHelper ( const std::map<std::string, std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>>& mConfigMap,
NetworkTreeNode& oRoot,
const IAudibilityFilter::AudibilityFilterConfig& oRootConfig );
///
/// \brief Map containing all configured filters, keyed by their names.
///
std::unordered_map<std::string, std::unique_ptr<IAudibilityFilter>> m_mAudibilityFilters;
///
/// \brief The actual network tree of the CFilterNetwork.
///
std::unique_ptr<NetworkTreeNode> m_pNetworkTree;
};
} // namespace audibility_filter
......
......@@ -30,9 +30,6 @@ namespace ITA
///
/// \brief Configuration class for the rate filter.
///
/// This is a basic overload of VistaPropertyList.
/// Its main purpose is to distinguish a rate filter config and define its property keys.
///
struct ITA_SIMULATION_SCHEDULER_API RateFilterConfig : public IAudibilityFilter::AudibilityFilterConfig
{
explicit RateFilterConfig ( );
......@@ -59,7 +56,6 @@ namespace ITA
/// \brief Check if the change between \p previousState and \p newUpdate is audible.
///
/// The change between \p previousState and \p newUpdate is audible when the time between the two updates is larger than the configured rate.
/// \remark If the conditions are not fulfilled, the change is not audible.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check for audibility.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
......
......@@ -27,9 +27,6 @@ namespace ITA
///
/// \brief Configuration class for the reverberation radius filter.
///
/// This is a basic overload of VistaPropertyList.
/// Its main purpose is to distinguish a rate filter config and define its property keys.
///
struct ITA_SIMULATION_SCHEDULER_API ReverberationRadiusFilterConfig : public IAudibilityFilter::AudibilityFilterConfig
{
explicit ReverberationRadiusFilterConfig ( );
......@@ -55,8 +52,7 @@ namespace ITA
///
/// \brief Check if the change between \p previousState and \p newUpdate is audible.
///
/// The change between \p previousState and \p newUpdate is audible when the time between the two updates is larger than the configured rate.
/// \remark If the conditions are not fulfilled, the change is not audible.
/// The change between \p previousState and \p newUpdate is audible when the receiver resides inside the configured radius around the source.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check for audibility.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
......
......@@ -22,10 +22,13 @@ namespace ITA
/// \brief Rotation filter
///
/// This class implements a simple rotation filter.
/// First, the azimuth and elevation angle for the source with the receiver as target is calculated and vice versa.
/// If the absolute delta between the previous angles and the new angles exceed the configured threshold, the update is deemed audible.
/// Depending on the rotation mode, the audibility is checked differently.
/// If the relative mode is chosen, first, the azimuth and elevation angle for the source with the receiver as target is calculated and vice versa.
/// If the delta between the previous angles and the new angles exceed the configured threshold, the update is deemed audible.
///
/// For example, consider the use of a 5x5 HRTF.
/// If the absolute mode is chosen, just the absolute rotation of source or receiver is checked against the threshold.
///
/// For an example, consider the use of a 5x5 HRTF.
/// The threshold for the receiver could be set to 2.5 degree to allow a 5 degree "inaudible" zone around the previous angle.
///
class ITA_SIMULATION_SCHEDULER_API CRotationFilter : public IAudibilityFilter
......@@ -74,7 +77,6 @@ namespace ITA
/// \brief Check if the change between \p previousState and \p newUpdate is audible.
///
/// The change between \p previousState and \p newUpdate is audible when the rotation of source and receiver exceed the configured thresholds given the configured RotationMode.
/// \remark If the conditions are not fulfilled, the change is not audible.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check for audibility.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
......
......@@ -52,8 +52,7 @@ namespace ITA
///
/// \brief Check if the change between \p previousState and \p newUpdate is audible.
///
/// The change between \p previousState and \p newUpdate is audible when the translation length of the translation vector of source or receiver is larger than the configured minimum.
/// \remark If the conditions are not fulfilled, the change is not audible.
/// The change between \p previousState and \p newUpdate is audible when the length of the translation vector of source or receiver is larger than the configured minimum.
/// \param previousState the previous state of the scene to check against.
/// \param newUpdate the CUpdateScene to check for audibility.
/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
......
......@@ -31,8 +31,6 @@ namespace ITA
///
/// \brief Configuration class for CZoneFilter.
///
/// Its main purpose is to distinguish a zone filter config and define its property keys.
///
struct ITA_SIMULATION_SCHEDULER_API ZoneFilterConfig : AudibilityFilterConfig
{
explicit ZoneFilterConfig ( );
......
......@@ -32,4 +32,4 @@ namespace ITA
} // namespace simulation_scheduler
} // namespace ITA
#endif // INCLUDE_WATINCLUDE_WATCHER_ITA_SIMULATION_SCHEDULER_CONFIG_INTERFACECHER_ITA_SIMULATION_SCHEDULER_TYPES
#endif // INCLUDE_WATCHER_ITA_SIMULATION_SCHEDULER_CONFIG_INTERFACE
......@@ -33,15 +33,16 @@ namespace ITA
namespace room_acoustics
{
///
/// \brief Primary interaction class.
/// \brief Primary interaction class for room acoustic simulations.
///
/// This class represents the interface with which external software should interact with the simulation scheduler.
/// This class represents the interface with which external software should interact with the simulation scheduler for room acoustic simulations.
/// It allows for easy interaction and configuration of the system.
/// - Updates can be issued via postUpdate().
/// - A IResultHandler can be registered via attachResultHandler.
/// - A simple replacement filter can be enabled for the CMasterSimulationController.
///
/// The actual computation takes place in its own thread (loop), see LoopBody().
/// \todo Inherit the scheduler interface? But we dont need handle simulation here :/
///
class ITA_SIMULATION_SCHEDULER_API CMasterSimulationController : public VistaThreadLoop
{
......
......@@ -22,7 +22,7 @@ namespace ITA
class CSimulationTask;
///
/// \brief Abstract base for all workers that use raven to simulate updates.
/// \brief Interface for room acoustics worker that use raven to simulate updates.
/// \todo Add functions to change the config.
///
class ITA_SIMULATION_SCHEDULER_API IRavenWorkerInterface : public IRoomAcousticsWorkerInterface
......@@ -30,7 +30,6 @@ namespace ITA
public:
///
/// \brief Configuration class for Raven worker.
/// \todo This class might be only used to hold other worker configs. See if we should keep this.
///
struct ITA_SIMULATION_SCHEDULER_API RavenWorkerConfig : public RoomAcousticsWorkerInterfaceConfig
{
......@@ -49,8 +48,6 @@ namespace ITA
///
/// \brief Constructor for a IRavenWorkerInterface.
///
/// As we always need a CRavenConfig, this constructor gets passed one.
/// \param oConfig the WorkerConfig used to configure the IWorkerInterface.
/// \param pParent the parent scheduler of the worker.
///
......
......@@ -85,10 +85,10 @@ namespace ITA
///
/// \brief Factory function for CWorkerThread.
/// \param oConfig the WorkerConfig used to configure the CWorkerThread.
/// \param pConfig the WorkerConfig used to configure the CWorkerThread.
/// \param pParent the parent scheduler of the worker.
///
static std::unique_ptr<IWorkerInterface> createWorker ( const std::shared_ptr<IWorkerInterface::WorkerConfig>& oConfig, ISchedulerInterface* pParent );
static std::unique_ptr<IWorkerInterface> createWorker ( const std::shared_ptr<IWorkerInterface::WorkerConfig>& pConfig, ISchedulerInterface* pParent );
///
/// \brief Return a unique type identifying string.
......
......@@ -44,11 +44,18 @@ namespace ITA
///
/// CScheduler is kind of the main class of the SimulationScheduler Library.
/// This scheduler runs local to where it was created.
/// Each CScheduler is responsible for one FieldOfDuty.
/// It receives updates, depending on what type od update it is, it either applies the config change (CUpdateConfig), or processes the CUpdateScene.
///
/// It allows for easy interaction and configuration of the system.
/// - Updates can be issued via postUpdate().
/// - A IResultHandler can be registered via attachResultHandler.
/// - A simple replacement filter can be enabled for the CScheduler.
///
/// It receives updates, depending on what type of update it is, it either applies the config change (CUpdateConfig), or processes the CUpdateScene.
/// For this, the CScheduler uses its audibility filters to determine if the update is indeed audible.
/// If the update is in fact audible, CScheduler distributes the update to idle workers who actually simulate the update.
/// When the update is simulated, the result is passed to all attached result handlers.
///
/// The actual computation takes place in its own thread (loop), see LoopBody().
/// \todo Determine where whe save the last simulated update, before sending it to the worker or when receiving it from the worker.
///
class ITA_SIMULATION_SCHEDULER_API CScheduler : public ISchedulerInterface, public VistaThreadLoop
......@@ -60,7 +67,7 @@ namespace ITA
struct ITA_SIMULATION_SCHEDULER_API LocalSchedulerConfig : public SchedulerConfig
{
explicit LocalSchedulerConfig ( );
bool bReplaceUpdates = true;
std::vector<std::shared_ptr<IWorkerInterface::WorkerConfig>> vpWorkerConfigs;
......@@ -109,6 +116,10 @@ namespace ITA
///
virtual void handleSimulationFinished ( std::unique_ptr<CSimulationResult> pResult ) override;
///
/// \brief Return a unique type identifying string.
/// \return a unique type identifying string.
///
static std::string getType ( );
protected:
......
......@@ -22,7 +22,7 @@ namespace ITA
class IResultHandler;
///
/// \brief
/// \brief Interface for a scheduler.
///
class ITA_SIMULATION_SCHEDULER_API ISchedulerInterface
{
......@@ -30,8 +30,8 @@ namespace ITA
///
/// \brief Base configuration class for schedulers.
///
/// This is a basic overload of VistaPropertyList.
/// Its main purpose is to distinguish a scheduler config.
/// \note ::sSchedulerType is a read only property of the SchedulerConfig.
/// Due to this the copy constructor and assignment operator are needed.
///
struct ITA_SIMULATION_SCHEDULER_API SchedulerConfig : public IConfig
{
......
......@@ -22,6 +22,9 @@ namespace ITA
namespace room_acoustics
{
///
/// \brief Field of duty of a room acoustic simulation.
///
enum class FieldOfDuty
{
directSound,
......
......@@ -41,9 +41,11 @@ namespace ITA
{
public:
///
/// \brief Configuration class for Worker.
/// \todo This class might be only used to hold other worker configs. See if we should keep this.
///
/// \brief Base configuration class for worker.
///
/// \note ::sWorkerType is a read only property of the WorkerConfig.
/// Due to this the copy constructor and assignment operator are needed.
///
struct ITA_SIMULATION_SCHEDULER_API WorkerConfig : public IConfig
{
WorkerConfig ( );
......@@ -107,6 +109,7 @@ namespace ITA
///
/// This class implements an extensible factory for worker.
/// After a type of worker is registered with its IWorkerInterface::createWorker, it can be created using this factory.
/// \todo Add a way to get the correct config from the type. The factory already knows of all possible workers.
///
class ITA_SIMULATION_SCHEDULER_API CWorkerFactory
{
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment