STFF-ImageColumn.h

Go to the documentation of this file.

///
/// @file   STFF-ImageColumn.h
///
/// Header file for the STFF::ImageColumn class.
///
/// @copyright
/// Copyright (c) 2012-2015 Sifferman Technology, LLC.  All rights reserved.
///

#ifndef STFF_ImageColumn_h_
#define STFF_ImageColumn_h_

#include "STFF-FishFinder.h"


namespace STFF {

    // forward declaration
    class STFishFinder;

    ////////////////////////////////////////////////////////////////////
    /// @class ImageColumn
    ///
    /// The ImageColumn class is a container for sample data retrieved
    /// from a single sonar ping.  
    ///
    /// The sample data is stored within each ImageColumn instance
    /// privately in packed form.
    /// The sample data may be retrieved by calling GetImageData(),
    /// at which time it is unpacked and sample-rate converted to fit
    /// the dimensions and offset required by the viewing window.
    ///
    // The  resolution of the sample data stored within instances
    // of this class might vary from one instance to the next depending
    // on the bandwidth loading of the black box fish finder and the
    // communication link.  Nevertheless, before creating instances of
    // ImageColumn, the user should request a sample resolution
    // appropriate to the screen resolution of the display device by
    // calling SetNumInputSamples().
    //
    /// @see GetImageColumn()
    ///
    class ImageColumn {

    public:

        ////////////////////////////////////////////////////////////////////
        /// @fn ImageColumn (STFishFinder*)
        ///
        /// This is the first of two @ref ImageColumn class constructors.
        /// The ImageColumn object created with this constructor
        /// is empty, containing no image data.
        ///
        /// @param[in]  pFF
        ///             pointer to the @ref STFishFinder instance with
        ///             which this ImageColumn object is associated
        ///
        /// @returns    (not applicable)
        ///
        /// @see        ImageColumn(STFishFinder*, FF_Frequency_t, FF_RangeSetting_t, uint16_t, uint16_t, uint8_t*, uint16_t)
        ///
        ImageColumn (STFishFinder *pFF);


        ////////////////////////////////////////////////////////////////////
        /// @fn ImageColumn(STFishFinder*, FF_Frequency_t, FF_RangeSetting_t, uint16_t, uint16_t, uint8_t*, uint32_t)
        ///
        /// This is a secondary @ref ImageColumn class constructor.
        /// The ImageColumn object created with this constructor
        /// is populated with the data provided in the argument list.
        ///
        /// @param[in]  pFF
        ///             pointer to the @ref STFishFinder instance with
        ///             which this ImageColumn object is associated
        ///
        /// @param[in]  frequency
        ///             the frequency context of the sample data
        ///
        /// @param[in]  inputRange
        ///             the shallow and deep Range bounds that define
        ///             the start and end of the sample data
        ///
        /// @param[in]  numInputSamples
        ///             the number of data samples recorded
        ///
        /// @param[in]  numDataBytes
        ///             the total number of contiguous bytes containing
        ///             the sample data
        ///
        /// @param[in]  pInputData
        ///             pointer to the start of the data buffer containing
        ///             the sample data to be copied into the new
        ///             ImageColumn object being created
        ///
        /// @param[in]  sequenceId
        ///             a unique number that increments with each
        ///             ImageColumn object created by the black box
        ///
        /// @returns    (not applicable)
        ///
        /// @see        ImageColumn(STFishFinder*)
        ///
        ImageColumn (STFishFinder        *pFF,
                     FF_Frequency_t      frequency,
                     FF_RangeSetting_t   inputRange,
                     uint16_t            numInputSamples,
                     uint16_t            numDataBytes,
                     uint8_t             *pInputData,
                     uint32_t            sequenceId);


        ////////////////////////////////////////////////////////////////////
        /// @fn ~ImageColumn ()
        ///
        /// This is the @ref ImageColumn destructor.
        ///
        /// @returns    (not applicable)
        ///
        ~ImageColumn ();


        ////////////////////////////////////////////////////////////////////
        /// @fn ImageColumn (const ImageColumn &)
        ///
        /// This is the @ref ImageColumn copy constructor.
        ///
        /// @param      const ImageColumn &
        ///             reference to an existing ImageColumn object
        ///
        /// @returns    ImageColumn
        ///             a new ImageColumn object that is a copy of the
        ///             original
        ///
        ImageColumn (const ImageColumn &);


        ////////////////////////////////////////////////////////////////////
        /// @fn ImageColumn &operator= (const ImageColumn &)
        ///
        /// This is the @ref ImageColumn assignment operator.
        ///
        /// @param      const ImageColumn &
        ///             reference to a first existing ImageColumn object
        ///             (right hand side of assignment)
        ///
        /// @returns    const ImageColumn &
        ///             reference to a second existing ImageColumn object
        ///             (left hand side of assignment)
        ///
        const ImageColumn &operator= (const ImageColumn &);


        ////////////////////////////////////////////////////////////////////
        /// @fn Frequency
        ///
        /// Provides the sonar frequency context when the
        /// ImageColumn sample data was collected.
        ///
        /// @returns    the frequency of the sonar ping and of the
        ///             received data for the ImageColumn object.
        ///             If the object contains no valid data, then
        ///             this function will return ::FF_INVALID_FREQUENCY.
        ///
        FF_Frequency_t  Frequency () const;


        ////////////////////////////////////////////////////////////////////
        /// @fn SequenceId
        ///
        /// Provides the Sequence ID for the ImageColumn.
        /// The Sequence ID starts at 0 and increments by 1 for each
        /// new ImageColumn transmitted by the black box.
        /// Separate sequences are used for ImageColumns having different
        /// frequencies.
        ///
        /// @returns    the Sequence ID for the ImageColumn.
        ///
        uint32_t SequenceId () const;


        ////////////////////////////////////////////////////////////////////
        /// @fn GetImageData
        ///
        /// Fills a buffer provided by the caller with a single column
        /// of sample data.  The data is sample rate converted (i.e.
        /// stretched or compressed) on the fly to fit into the
        /// specified buffer.
        ///
        /// The produced image data is not packed (i.e. each uint8_t
        /// value in the buffer contains one sample).  With a bit depth
        /// of 4 (i.e. 4 bits per sample), one of 16 colors can be
        /// represented by each sample in the buffer.
        ///
        /// @param[in]  pRangeSetting
        ///             pointer to a ::FF_RangeSetting_t struct
        ///             containing the shallow and deep range limits
        ///             (and associated depth units)
        ///             defining the depths of the first and last
        ///             samples in the @p pImageData buffer.  The
        ///             @link FF_RangeSetting_t::rangeShallow
        ///             rangeShallow @endlink and
        ///             @link FF_RangeSetting_t::rangeDeep
        ///             rangeDeep @endlink members must be provided in
        ///             hundredths of the depth units specified in the
        ///             @link FF_RangeSetting_t::units units @endlink
        ///             member.
        ///
        /// @param[in]  numSamples
        ///             the number of uint8_t samples to be copied
        ///             into the buffer
        ///
        /// @param[out] pImageData
        ///             pointer to the start of the output buffer.
        ///
        /// @param[out] pSimulated
        ///             pointer to a location that will be written with
        ///             the value @p true if the provided image data is
        ///             a simulation for demonstration purposes;
        ///             @p false otherwise
        ///
        /// @retval     ::FF_ERR_NO_ERROR
        ///             if the operation completed successfully
        ///
        /// @retval     ::FF_ERR_ARGUMENT_OUT_OF_RANGE
        ///             if any of the arguments, or any of the members
        ///             of the @p pRangeSetting parameter, are outside
        ///             the range of allowable values.
        ///
        /// @retval     ::FF_ERR_INVALID_FREQUENCY
        ///             the ImageColumn object contains no valid
        ///             sample data
        ///
        FF_Error_t  GetImageData (const FF_RangeSetting_t *pRangeSetting,
                                  uint16_t numSamples,
                                  uint8_t *pImageData,
                                  bool *pSimulated) const;

    private:

        // Default constructor is private to prevent construction of
        // ImageColumn class without parameters
        ImageColumn () {}

        class impl;
        impl *m_pimpl;

    };  // class ImageColumn

}       // namespace STFF

#endif  // defined (STFF_ImageColumn_h_)