Added doxygen comments

This commit is contained in:
T. van der Zwan 2013-09-06 19:26:58 +00:00
parent 3187fc84a6
commit d2d7265f02
8 changed files with 301 additions and 55 deletions

View File

@ -22,33 +22,58 @@ class DispmanxWrapper: public QObject
{ {
Q_OBJECT Q_OBJECT
public: 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); 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(); virtual ~DispmanxWrapper();
signals:
void ledValues(const unsigned priority, const std::vector<RgbColor> ledColors, const unsigned timeout_ms);
public slots: public slots:
///
/// Starts the grabber wich produces led values with the specified update rate
///
void start(); void start();
///
/// Performs a single frame grab and computes the led-colors
///
void action(); void action();
///
/// Stops the grabber
///
void stop(); void stop();
private: private:
/// The update rate [Hz]
const int _updateInterval_ms; const int _updateInterval_ms;
/// The timeout of the led colors [ms]
const int _timeout_ms; const int _timeout_ms;
/// The priority of the led colors [ms]
const int _priority; const int _priority;
/// The timer for generating events with the specified update rate
QTimer _timer; QTimer _timer;
/// The image used for grabbing frames
RgbImage _image; RgbImage _image;
/// The actual grabber
DispmanxFrameGrabber * _frameGrabber; DispmanxFrameGrabber * _frameGrabber;
/// The processor for transforming images to led colors
ImageProcessor * _processor; ImageProcessor * _processor;
/// The list with computed led colors
std::vector<RgbColor> _ledColors; std::vector<RgbColor> _ledColors;
/// Pointer to Hyperion for writing led values
Hyperion * _hyperion; Hyperion * _hyperion;
}; };

View File

@ -19,65 +19,161 @@
class HsvTransform; class HsvTransform;
class ColorTransform; class ColorTransform;
///
/// The main class of Hyperion. This gives other 'users' access to the attached LedDevice through
/// the priority muxer.
///
class Hyperion : public QObject class Hyperion : public QObject
{ {
Q_OBJECT Q_OBJECT
public: public:
/// Type definition of the info structure used by the priority muxer
typedef PriorityMuxer::InputInfo InputInfo; typedef PriorityMuxer::InputInfo InputInfo;
///
/// RGB-Color channel enumeration
///
enum Color enum Color
{ {
RED, GREEN, BLUE, INVALID RED, GREEN, BLUE, INVALID
}; };
///
/// Enumeration of the possible color (color-channel) transforms
///
enum Transform enum Transform
{ {
SATURATION_GAIN, VALUE_GAIN, THRESHOLD, GAMMA, BLACKLEVEL, WHITELEVEL 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); Hyperion(const Json::Value& jsonConfig);
///
/// Destructor; cleans up resourcess
///
~Hyperion(); ~Hyperion();
///
/// Returns the number of attached leds
///
unsigned getLedCount() const; 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); 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<RgbColor> &ledColors, const int timeout_ms); void setColors(int priority, std::vector<RgbColor> &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); 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); void clear(int priority);
///
/// Clears all priority channels. This will switch the leds off until a new priority is written.
///
void clearall(); 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; double getTransform(Transform transform, Color color) const;
///
/// Returns a list of active priorities
///
/// @return The list with priorities
///
QList<int> getActivePriorities() const; QList<int> 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; 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 LedString createLedString(const Json::Value & ledsConfig);
static HsvTransform * createHsvTransform(const Json::Value & hsvConfig); static HsvTransform * createHsvTransform(const Json::Value & hsvConfig);
static ColorTransform* createColorTransform(const Json::Value & colorConfig); static ColorTransform * createColorTransform(const Json::Value & colorConfig);
private slots: private slots:
///
/// Updates the priority muxer with the current time and (re)writes the led color with applied
/// transforms.
///
void update(); void update();
private: 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<RgbColor>& colors) const; void applyTransform(std::vector<RgbColor>& colors) const;
/// The specifiation of the led frame construction and picture integration
LedString _ledString; LedString _ledString;
/// The priority muxer
PriorityMuxer _muxer; PriorityMuxer _muxer;
/// The HSV Transform for applying Saturation and Value transforms
HsvTransform * _hsvTransform; HsvTransform * _hsvTransform;
/// The RED-Channel (RGB) transform
ColorTransform * _redTransform; ColorTransform * _redTransform;
/// The GREEN-Channel (RGB) transform
ColorTransform * _greenTransform; ColorTransform * _greenTransform;
/// The BLUE-Channel (RGB) transform
ColorTransform * _blueTransform; ColorTransform * _blueTransform;
/// The actual LedDevice
LedDevice* _device; LedDevice* _device;
/// The timer for handling priority channel timeouts
QTimer _timer; QTimer _timer;
}; };

View File

@ -14,57 +14,71 @@ namespace hyperion {
class BlackBorderProcessor; class BlackBorderProcessor;
} }
/** ///
* The ImageProcessor translates an RGB-image to RGB-values for the leds. The processing is /// 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 /// performed in two steps. First the average color per led-region is computed. Second a
* color-tranform is applied based on a gamma-correction. /// color-tranform is applied based on a gamma-correction.
*/ ///
class ImageProcessor class ImageProcessor
{ {
public: public:
~ImageProcessor(); ~ImageProcessor();
/** ///
* Specifies the width and height of 'incomming' images. This will resize the buffer-image to /// Specifies the width and height of 'incomming' images. This will resize the buffer-image to
* match the given size. /// match the given size.
* NB All earlier obtained references will be invalid. /// NB All earlier obtained references will be invalid.
* ///
* @param[in] width The new width of the buffer-image /// @param[in] width The new width of the buffer-image
* @param[in] height The new height of the buffer-image /// @param[in] height The new height of the buffer-image
*/ ///
void setSize(const unsigned width, const unsigned height); 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 /// 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. /// 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 /// @param[in] image The image to translate to led values
* ///
* @return The color value per led /// @return The color value per led
*/ ///
std::vector<RgbColor> process(const RgbImage& image); std::vector<RgbColor> process(const RgbImage& image);
/** ///
* Determines the led colors of the image in the buffer. /// Determines the led colors of the image in the buffer.
* ///
* @param[out] ledColors The color value per led /// @param[out] ledColors The color value per led
*/ ///
void process(const RgbImage& image, std::vector<RgbColor>& ledColors); void process(const RgbImage& image, std::vector<RgbColor>& ledColors);
private: private:
/// Friend declaration of the factory for creating ImageProcessor's
friend class ImageProcessorFactory; 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); 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); void verifyBorder(const RgbImage& image);
private: private:
/// The Led-string specification
const LedString mLedString; const LedString mLedString;
/// Flag the enables(true)/disabled(false) blackborder detector
bool _enableBlackBorderRemoval; bool _enableBlackBorderRemoval;
/// The processor for black border detection /// The processor for black border detection
hyperion::BlackBorderProcessor* _borderProcessor; hyperion::BlackBorderProcessor* _borderProcessor;
/// The mapping of image-pixels to leds
hyperion::ImageToLedsMap* mImageToLeds; hyperion::ImageToLedsMap* mImageToLeds;
}; };

View File

@ -11,16 +11,36 @@
// Forward class declaration // Forward class declaration
class ImageProcessor; class ImageProcessor;
///
/// The ImageProcessor is a singleton factor for creating ImageProcessors that translate images to
/// led color values.
///
class ImageProcessorFactory class ImageProcessorFactory
{ {
public: public:
///
/// Returns the 'singleton' instance (creates the singleton if it does not exist)
///
/// @return The singleton instance of the ImageProcessorFactory
///
static ImageProcessorFactory& getInstance(); static ImageProcessorFactory& getInstance();
public: public:
///
/// Initialises this factory with the given led-configuration
///
/// @param[in] ledString The led configuration
///
void init(const LedString& ledString); 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; ImageProcessor* newImageProcessor() const;
private: private:
/// The Led-string specification
LedString _ledString; LedString _ledString;
}; };

View File

@ -6,6 +6,9 @@
// Utility includes // Utility includes
#include <utils/RgbColor.h> #include <utils/RgbColor.h>
///
/// Interface (pure virtual base class) for LedDevices.
///
class LedDevice class LedDevice
{ {
public: public:

View File

@ -12,49 +12,67 @@
// Forward class declarations // Forward class declarations
namespace Json { class Value; } namespace Json { class Value; }
/** ///
* The Led structure contains the definition of the image portion used to determine a single led's /// The Led structure contains the definition of the image portion used to determine a single led's
* color. /// color.
* <pre> /// <pre>
* |--------------------image--| /// |--------------------image--|
* | minX maxX | /// | minX maxX |
* | |-----|minY | /// | |-----|minY |
* | | | | /// | | | |
* | |-----|maxY | /// | |-----|maxY |
* | | /// | |
* | | /// | |
* | | /// | |
* |---------------------------| /// |---------------------------|
* <endpre> /// <endpre>
*/ ///
struct Led struct Led
{ {
/** The index of the led */ /// The index of the led
unsigned index; 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; 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; 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; 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; double maxY_frac;
}; };
///
/// The LedString contains the image integration information of the leds
///
class LedString class LedString
{ {
public: public:
static LedString construct(const Json::Value& ledConfig); ///
/// Constructs the LedString with no leds
///
LedString(); LedString();
///
/// Destructor of this LedString
///
~LedString(); ~LedString();
///
/// Returns the led specifications
///
/// @return The list with led specifications
///
std::vector<Led>& leds(); std::vector<Led>& leds();
///
/// Returns the led specifications
///
/// @return The list with led specifications
///
const std::vector<Led>& leds() const; const std::vector<Led>& leds() const;
private: private:
/// The list with led specifications
std::vector<Led> mLeds; std::vector<Led> mLeds;
}; };

View File

@ -15,43 +15,112 @@
// Hyperion includes // Hyperion includes
#include <hyperion/LedDevice.h> #include <hyperion/LedDevice.h>
///
/// 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 class PriorityMuxer
{ {
public: public:
///
/// The information structure for a single priority channel
///
struct InputInfo struct InputInfo
{ {
/// The priority of this channel
int priority; int priority;
/// The absolute timeout of the channel
int64_t timeoutTime_ms; int64_t timeoutTime_ms;
/// The colors for each led of the channel
std::vector<RgbColor> ledColors; std::vector<RgbColor> 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); PriorityMuxer(int ledCount);
///
/// Destructor
///
~PriorityMuxer(); ~PriorityMuxer();
///
/// Returns the current priority
///
/// @return The current priority
///
int getCurrentPriority() const; 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; bool hasPriority(const int priority) const;
///
/// Returns the number of active priorities
///
/// @return The list with active priorities
///
QList<int> getPriorities() const; QList<int> 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; 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<RgbColor>& ledColors, const int64_t timeoutTime_ms=-1); void setInput(const int priority, const std::vector<RgbColor>& 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); void clearInput(const int priority);
///
/// Clears all priority channels
///
void clearAll(); 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); void setCurrentTime(const int64_t& now);
private: private:
/// The current priority (lowest value in _activeInputs)
int _currentPriority; int _currentPriority;
/// The mapping from priority channel to led-information
QMap<int, InputInfo> _activeInputs; QMap<int, InputInfo> _activeInputs;
/// The information of the lowest priority channel
InputInfo _lowestPriorityInfo; InputInfo _lowestPriorityInfo;
/// The lowest possible priority, which is used when no priority channels are active
const static int LOWEST_PRIORITY = std::numeric_limits<int>::max(); const static int LOWEST_PRIORITY = std::numeric_limits<int>::max();
}; };

View File

@ -17,6 +17,7 @@ LedString::LedString()
LedString::~LedString() LedString::~LedString()
{ {
// empty
} }
std::vector<Led>& LedString::leds() std::vector<Led>& LedString::leds()