From d2d7265f026424ab23766ec199d7d113e89fd5cc Mon Sep 17 00:00:00 2001 From: "T. van der Zwan" Date: Fri, 6 Sep 2013 19:26:58 +0000 Subject: [PATCH] Added doxygen comments --- include/dispmanx-grabber/DispmanxWrapper.h | 33 ++++++- include/hyperion/Hyperion.h | 100 ++++++++++++++++++++- include/hyperion/ImageProcessor.h | 68 ++++++++------ include/hyperion/ImageProcessorFactory.h | 20 +++++ include/hyperion/LedDevice.h | 3 + include/hyperion/LedString.h | 62 ++++++++----- include/hyperion/PriorityMuxer.h | 69 ++++++++++++++ libsrc/hyperion/LedString.cpp | 1 + 8 files changed, 301 insertions(+), 55 deletions(-) diff --git a/include/dispmanx-grabber/DispmanxWrapper.h b/include/dispmanx-grabber/DispmanxWrapper.h index 134c30cd..2d22b677 100644 --- a/include/dispmanx-grabber/DispmanxWrapper.h +++ b/include/dispmanx-grabber/DispmanxWrapper.h @@ -22,33 +22,58 @@ class DispmanxWrapper: public QObject { Q_OBJECT public: + /// + /// Constructs the dispmanx frame grabber with a specified grab size and update rate. + /// + /// @param[in] grabWidth The width of the grabbed image [pixels] + /// @param[in] grabHeight The height of the grabbed images [pixels] + /// @param[in] updateRate_Hz The image grab rate [Hz] + /// @param[in] hyperion The instance of Hyperion used to write the led values + /// DispmanxWrapper(const unsigned grabWidth, const unsigned grabHeight, const unsigned updateRate_Hz, Hyperion * hyperion); + /// + /// Destructor of this dispmanx frame grabber. Releases any claimed resources. + /// virtual ~DispmanxWrapper(); -signals: - void ledValues(const unsigned priority, const std::vector ledColors, const unsigned timeout_ms); - public slots: + /// + /// Starts the grabber wich produces led values with the specified update rate + /// void start(); + /// + /// Performs a single frame grab and computes the led-colors + /// void action(); + /// + /// Stops the grabber + /// void stop(); private: + /// The update rate [Hz] const int _updateInterval_ms; + /// The timeout of the led colors [ms] const int _timeout_ms; + /// The priority of the led colors [ms] const int _priority; + /// The timer for generating events with the specified update rate QTimer _timer; + /// The image used for grabbing frames RgbImage _image; + /// The actual grabber DispmanxFrameGrabber * _frameGrabber; + /// The processor for transforming images to led colors ImageProcessor * _processor; + /// The list with computed led colors std::vector _ledColors; + /// Pointer to Hyperion for writing led values Hyperion * _hyperion; }; - diff --git a/include/hyperion/Hyperion.h b/include/hyperion/Hyperion.h index ce4cd546..e25f1aae 100644 --- a/include/hyperion/Hyperion.h +++ b/include/hyperion/Hyperion.h @@ -19,65 +19,161 @@ class HsvTransform; class ColorTransform; +/// +/// The main class of Hyperion. This gives other 'users' access to the attached LedDevice through +/// the priority muxer. +/// class Hyperion : public QObject { Q_OBJECT public: + /// Type definition of the info structure used by the priority muxer typedef PriorityMuxer::InputInfo InputInfo; + /// + /// RGB-Color channel enumeration + /// enum Color { RED, GREEN, BLUE, INVALID }; + /// + /// Enumeration of the possible color (color-channel) transforms + /// enum Transform { SATURATION_GAIN, VALUE_GAIN, THRESHOLD, GAMMA, BLACKLEVEL, WHITELEVEL }; + /// + /// Constructs the Hyperion instance based on the given Json configuration + /// + /// @param[in] jsonConfig The Json configuration + /// Hyperion(const Json::Value& jsonConfig); + /// + /// Destructor; cleans up resourcess + /// ~Hyperion(); + /// + /// Returns the number of attached leds + /// unsigned getLedCount() const; + /// + /// Writes a single color to all the leds for the given time and priority + /// + /// @param[in] priority The priority of the written color + /// @param[in] ledColor The color to write to the leds + /// @param[in] timeout_ms The time the leds are set to the given color [ms] + /// void setColor(int priority, RgbColor &ledColor, const int timeout_ms); + /// + /// Writes the given colors to all leds for the given time and priority + /// + /// @param[in] priority The priority of the written colors + /// @param[in] ledColors The colors to write to the leds + /// @param[in] timeout_ms The time the leds are set to the given colors [ms] + /// void setColors(int priority, std::vector &ledColors, const int timeout_ms); + /// + /// Sets/Updates a part of the color transformation. + /// + /// @param[in] transform The type of transform to configure + /// @param[in] color The color channel to which the transform applies (only applicable for + /// Transform::THRESHOLD, Transform::GAMMA, Transform::BLACKLEVEL, + /// Transform::WHITELEVEL) + /// @param[in] value The new value for the given transform + /// void setTransform(Transform transform, Color color, double value); + /// + /// Clears the given priority channel. This will switch the led-colors to the colors of the next + /// lower priority channel (or off if no more channels are set) + /// + /// @param[in] priority The priority channel + /// void clear(int priority); + /// + /// Clears all priority channels. This will switch the leds off until a new priority is written. + /// void clearall(); + /// + /// Returns the value of a specific color transform + /// + /// @param[in] transform The type of transform + /// @param[in] color The color channel to which the transform applies (only applicable for + /// Transform::THRESHOLD, Transform::GAMMA, Transform::BLACKLEVEL, + /// Transform::WHITELEVEL) + /// + /// @return The value of the specified color transform + /// double getTransform(Transform transform, Color color) const; + /// + /// Returns a list of active priorities + /// + /// @return The list with priorities + /// QList getActivePriorities() const; + /// + /// Returns the information of a specific priorrity channel + /// + /// @param[in] priority The priority channel + /// + /// @return The information of the given + /// + /// @throw std::runtime_error when the priority channel does not exist + /// const InputInfo& getPriorityInfo(const int priority) const; - static LedDevice* constructDevice(const Json::Value & deviceConfig); + static LedDevice * constructDevice(const Json::Value & deviceConfig); static LedString createLedString(const Json::Value & ledsConfig); static HsvTransform * createHsvTransform(const Json::Value & hsvConfig); - static ColorTransform* createColorTransform(const Json::Value & colorConfig); + static ColorTransform * createColorTransform(const Json::Value & colorConfig); private slots: + /// + /// Updates the priority muxer with the current time and (re)writes the led color with applied + /// transforms. + /// void update(); private: + /// + /// Applies all color transmforms to the given list of colors. The transformation is performed + /// in place. + /// + /// @param colors The colors to be transformed + /// void applyTransform(std::vector& colors) const; + /// The specifiation of the led frame construction and picture integration LedString _ledString; + /// The priority muxer PriorityMuxer _muxer; + /// The HSV Transform for applying Saturation and Value transforms HsvTransform * _hsvTransform; + /// The RED-Channel (RGB) transform ColorTransform * _redTransform; + /// The GREEN-Channel (RGB) transform ColorTransform * _greenTransform; + /// The BLUE-Channel (RGB) transform ColorTransform * _blueTransform; + /// The actual LedDevice LedDevice* _device; + /// The timer for handling priority channel timeouts QTimer _timer; }; diff --git a/include/hyperion/ImageProcessor.h b/include/hyperion/ImageProcessor.h index 18747afe..642d0297 100644 --- a/include/hyperion/ImageProcessor.h +++ b/include/hyperion/ImageProcessor.h @@ -14,57 +14,71 @@ namespace hyperion { class BlackBorderProcessor; } -/** - * The ImageProcessor translates an RGB-image to RGB-values for the leds. The processing is - * performed in two steps. First the average color per led-region is computed. Second a - * color-tranform is applied based on a gamma-correction. - */ +/// +/// The ImageProcessor translates an RGB-image to RGB-values for the leds. The processing is +/// performed in two steps. First the average color per led-region is computed. Second a +/// color-tranform is applied based on a gamma-correction. +/// class ImageProcessor { public: ~ImageProcessor(); - /** - * Specifies the width and height of 'incomming' images. This will resize the buffer-image to - * match the given size. - * NB All earlier obtained references will be invalid. - * - * @param[in] width The new width of the buffer-image - * @param[in] height The new height of the buffer-image - */ + /// + /// Specifies the width and height of 'incomming' images. This will resize the buffer-image to + /// match the given size. + /// NB All earlier obtained references will be invalid. + /// + /// @param[in] width The new width of the buffer-image + /// @param[in] height The new height of the buffer-image + /// void setSize(const unsigned width, const unsigned height); - /** - * Processes the image to a list of led colors. This will update the size of the buffer-image - * if required and call the image-to-leds mapping to determine the mean color per led. - * - * @param[in] image The image to translate to led values - * - * @return The color value per led - */ + /// + /// Processes the image to a list of led colors. This will update the size of the buffer-image + /// if required and call the image-to-leds mapping to determine the mean color per led. + /// + /// @param[in] image The image to translate to led values + /// + /// @return The color value per led + /// std::vector process(const RgbImage& image); - /** - * Determines the led colors of the image in the buffer. - * - * @param[out] ledColors The color value per led - */ + /// + /// Determines the led colors of the image in the buffer. + /// + /// @param[out] ledColors The color value per led + /// void process(const RgbImage& image, std::vector& ledColors); private: + /// Friend declaration of the factory for creating ImageProcessor's friend class ImageProcessorFactory; + /// + /// Constructs an image-processor for translating an image to led-color values based on the + /// given led-string specification + /// + /// @param[in] ledString The led-string specification + /// ImageProcessor(const LedString &ledString); + /// + /// Performs black-border detection (if enabled) on the given image + /// + /// @param[in] image The image to perform black-border detection on + /// void verifyBorder(const RgbImage& image); private: + /// The Led-string specification const LedString mLedString; + /// Flag the enables(true)/disabled(false) blackborder detector bool _enableBlackBorderRemoval; /// The processor for black border detection hyperion::BlackBorderProcessor* _borderProcessor; + /// The mapping of image-pixels to leds hyperion::ImageToLedsMap* mImageToLeds; }; - diff --git a/include/hyperion/ImageProcessorFactory.h b/include/hyperion/ImageProcessorFactory.h index dc558371..3431065b 100644 --- a/include/hyperion/ImageProcessorFactory.h +++ b/include/hyperion/ImageProcessorFactory.h @@ -11,16 +11,36 @@ // Forward class declaration class ImageProcessor; +/// +/// The ImageProcessor is a singleton factor for creating ImageProcessors that translate images to +/// led color values. +/// class ImageProcessorFactory { public: + /// + /// Returns the 'singleton' instance (creates the singleton if it does not exist) + /// + /// @return The singleton instance of the ImageProcessorFactory + /// static ImageProcessorFactory& getInstance(); public: + /// + /// Initialises this factory with the given led-configuration + /// + /// @param[in] ledString The led configuration + /// void init(const LedString& ledString); + /// + /// Creates a new ImageProcessor. The onwership of the processor is transferred to the caller. + /// + /// @return The newly created ImageProcessor + /// ImageProcessor* newImageProcessor() const; private: + /// The Led-string specification LedString _ledString; }; diff --git a/include/hyperion/LedDevice.h b/include/hyperion/LedDevice.h index ea84fa7f..7c1dc6a6 100644 --- a/include/hyperion/LedDevice.h +++ b/include/hyperion/LedDevice.h @@ -6,6 +6,9 @@ // Utility includes #include +/// +/// Interface (pure virtual base class) for LedDevices. +/// class LedDevice { public: diff --git a/include/hyperion/LedString.h b/include/hyperion/LedString.h index 030dd11f..e5963440 100644 --- a/include/hyperion/LedString.h +++ b/include/hyperion/LedString.h @@ -12,49 +12,67 @@ // Forward class declarations namespace Json { class Value; } -/** - * The Led structure contains the definition of the image portion used to determine a single led's - * color. - * 
- * |--------------------image--|
- * | minX  maxX                |
- * |  |-----|minY              |
- * |  |     |                  |
- * |  |-----|maxY              |
- * |                           |
- * |                           |
- * |                           |
- * |---------------------------|
- * 
- */
+///
+/// The Led structure contains the definition of the image portion used to determine a single led's
+/// color.
+/// 
+/// |--------------------image--|
+/// | minX  maxX                |
+/// |  |-----|minY              |
+/// |  |     |                  |
+/// |  |-----|maxY              |
+/// |                           |
+/// |                           |
+/// |                           |
+/// |---------------------------|
+/// 
+///
 struct Led
 {
-	/** The index of the led */
+	///  The index of the led
 	unsigned index;
 
-	/** The minimum vertical scan line included for this leds color */
+	///  The minimum vertical scan line included for this leds color
 	double minX_frac;
-	/** The maximum vertical scan line included for this leds color */
+	///  The maximum vertical scan line included for this leds color
 	double maxX_frac;
-	/** The minimum horizontal scan line included for this leds color */
+	///  The minimum horizontal scan line included for this leds color
 	double minY_frac;
-	/** The maximum horizontal scan line included for this leds color */
+	///  The maximum horizontal scan line included for this leds color
 	double maxY_frac;
 };
 
+///
+/// The LedString contains the image integration information of the leds
+///
 class LedString
 {
 public:
-	static LedString construct(const Json::Value& ledConfig);
-
+	///
+	/// Constructs the LedString with no leds
+	///
 	LedString();
 
+	///
+	/// Destructor of this LedString
+	///
 	~LedString();
 
+	///
+	/// Returns the led specifications
+	///
+	/// @return The list with led specifications
+	///
 	std::vector& leds();
 
+	///
+	/// Returns the led specifications
+	///
+	/// @return The list with led specifications
+	///
 	const std::vector& leds() const;
 
 private:
+	/// The list with led specifications
 	std::vector mLeds;
 };
diff --git a/include/hyperion/PriorityMuxer.h b/include/hyperion/PriorityMuxer.h
index 73ca7694..2536150a 100644
--- a/include/hyperion/PriorityMuxer.h
+++ b/include/hyperion/PriorityMuxer.h
@@ -15,43 +15,112 @@
 // Hyperion includes
 #include 
 
+///
+/// The PriorityMuxer handles the priority channels. Led values input is written to the priority map
+/// and the muxer keeps track of all active priorities. The current priority can be queried and per
+/// priority the led colors.
+///
 class PriorityMuxer
 {
 public:
+	///
+	/// The information structure for a single priority channel
+	///
 	struct InputInfo
 	{
+		/// The priority of this channel
 		int priority;
 
+		/// The absolute timeout of the channel
 		int64_t timeoutTime_ms;
+		/// The colors for each led of the channel
 		std::vector ledColors;
 	};
 
+	///
+	/// Constructs the PriorityMuxer for the given number of leds (used to switch to black when
+	/// there are no priority channels
+	///
+	/// @param ledCount The number of leds
+	///
 	PriorityMuxer(int ledCount);
 
+	///
+	/// Destructor
+	///
 	~PriorityMuxer();
 
+	///
+	/// Returns the current priority
+	///
+	/// @return The current priority
+	///
 	int getCurrentPriority() const;
 
+	///
+	/// Returns the state (enabled/disabled) of a specific priority channel
+	/// @param priority The priority channel
+	/// @return True if the priority channel exists else false
+	///
 	bool hasPriority(const int priority) const;
 
+	///
+	/// Returns the number of active priorities
+	///
+	/// @return The list with active priorities
+	///
 	QList getPriorities() const;
 
+	///
+	/// Returns the information of a specified priority channel
+	///
+	/// @param priority The priority channel
+	///
+	/// @return The information for the specified priority channel
+	///
+	/// @throws std::runtime_error if the priority channel does not exist
+	///
 	const InputInfo& getInputInfo(const int priority) const;
 
+	///
+	/// Sets/Updates the data for a priority channel
+	///
+	/// @param[in] priority The priority of the channel
+	/// @param[in] ledColors The led colors of the priority channel
+	/// @param[in] timeoutTime_ms The absolute timeout time of the channel
+	///
 	void setInput(const int priority, const std::vector& ledColors, const int64_t timeoutTime_ms=-1);
 
+	///
+	/// Clears the specified priority channel
+	///
+	/// @param[in] priority  The priority of the channel to clear
+	///
 	void clearInput(const int priority);
 
+	///
+	/// Clears all priority channels
+	///
 	void clearAll();
 
+	///
+	/// Updates the current time. Channels with a configured time out will be checked and cleared if
+	/// required.
+	///
+	/// @param[in] now The current time
+	///
 	void setCurrentTime(const int64_t& now);
 
 private:
+	/// The current priority (lowest value in _activeInputs)
 	int _currentPriority;
 
+	/// The mapping from priority channel to led-information
 	QMap _activeInputs;
 
+	/// The information of the lowest priority channel
 	InputInfo _lowestPriorityInfo;
 
+	/// The lowest possible priority, which is used when no priority channels are active
 	const static int LOWEST_PRIORITY = std::numeric_limits::max();
 };
diff --git a/libsrc/hyperion/LedString.cpp b/libsrc/hyperion/LedString.cpp
index 38c1b8f9..a44a4dc5 100644
--- a/libsrc/hyperion/LedString.cpp
+++ b/libsrc/hyperion/LedString.cpp
@@ -17,6 +17,7 @@ LedString::LedString()
 
 LedString::~LedString()
 {
+	// empty
 }
 
 std::vector& LedString::leds()