VisionPlus_V3.0/DependentLibrary/BaslerCamera/SDK/include/pylon/StreamGrabber.h

//-----------------------------------------------------------------------------
//  Basler pylon SDK
//  Copyright (c) 2006-2021 Basler AG
//  http://www.baslerweb.com
//  Author:  Hartmut Nebelung
//-----------------------------------------------------------------------------
/*!
\file
\brief    Low Level API: Definition of IStreamGrabber interface

\attention
The Low Level API has been deprecated in pylon 6.0. It is recommended
to use the Instant Camera classes instead.
*/
#ifndef __ISTREAMGRABBER_H__
#define __ISTREAMGRABBER_H__

#if _MSC_VER > 1000
#pragma once
#endif //_MSC_VER > 1000

#include <pylon/Platform.h>

#ifdef _MSC_VER
#   pragma pack(push, PYLON_PACKING)
#endif /* _MSC_VER */

#include <GenICamFwd.h>
#include <pylon/stdinclude.h>

namespace Pylon
{
    /*!
    \ingroup Pylon_LowLevelApi
    \brief Used to configure how starting and stopping of streaming are handled.
           If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.
    */

    class GrabResult;
    class WaitObject;
    /// This opaque type represents a registered buffer.
    typedef void* StreamBufferHandle;

    // -------------------------------------------------------------------------
    // interface IStreamGrabber
    // -------------------------------------------------------------------------
    /*!
        \ingroup Pylon_LowLevelApi
        \interface IStreamGrabber
        \brief Low Level API: Interface to an (input) data stream

        \attention
        The Low Level API has been deprecated in pylon 6.0. It is recommended
        to use the Instant Camera classes instead.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.
    */
    interface IStreamGrabber
    {
        /*!
        \brief Opens the stream grabber.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \pre
        <ul>
        <li> The corresponding device is open.
        <li> The stream grabber is closed.
        </ul>

        \post
        <ul>
        <li> The stream grabber is open.
        <li> If the device is closed while the stream grabber is open, the stream grabber is closed automatically.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber is already open or prepared. The stream grabber remains in the same state after raising the exception in this case.
        <li> Throws an exception if the stream grabber is closed and opening the stream grabber fails. The stream grabber remains closed after raising the exception.
        </ul>
        */
        virtual void Open() = 0;


        /*!
        \brief Closes the stream grabber.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        This method calls FinishGrab() automatically if needed.

        \post
        <ul>
        <li> Any running grab has been stopped by calling FinishGrab().
        <li> The stream grabber is closed.
        <li> All results waiting in the output queue are discarded.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        Does not throw C++ exceptions.
        */
        virtual void Close() = 0;


        /*!
        \brief Retrieve whether the stream grabber is open.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \return Returns true if the stream grabber is open.

        \threading
        This method can be synchronized using an internal stream grabber lock.

        \error
        Does not throw C++ exceptions.
        */
        virtual bool IsOpen() const = 0;


        /*!
        \brief Registers a buffer for subsequent use.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \param[in] pBuffer The pointer of the buffer that is to be used for grabbing e.g., for grabbing images.
        \param[in] bufferSize The size of the provided buffer in bytes.
        \return Returns a handle for the registered buffer that can be used in subsequent calls.

        \pre
        <ul>
        <li> pBuffer must not be NULL.
        <li> The buffer size must not exceed the value of the node map integer parameter MaxBufferSize specified when PrepareGrab was called.
        <li> Less buffers are already registered than value of the node map integer parameter MaxNumBuffer specified when PrepareGrab was called.
        <li> The stream grabber is prepared, see PrepareGrab().
        <li> The buffer has not been registered already.
        </ul>

        \post
        <ul>
        <li> The buffer is registered.
        <li> Transport Layer specific preparations have been executed e.g., locking the memory pages of the buffer.
        <li> The buffer must not be freed while being registered.
        <li> If the stream grabber requires the additional streaming state, streaming must not be started, see IsStartAndStopStreamingMandatory() and StartStreamingIfMandatory().
        </ul>

        \threading
        This method can be synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if registering the buffer fails. The buffer is not registered after raising an exception.
        </ul>
        */
        virtual StreamBufferHandle RegisterBuffer( void* pBuffer, size_t bufferSize ) = 0;


        /*!
        \brief Deregisters the buffer.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \param[in] hStreamBuffer The handle of a buffer that has been provided by RegisterBuffer()
        \return Returns the pointer of the corresponding buffer.

        \pre
        <ul>
        <li> The buffer is registered.
        <li> The buffer is not queued. Either it has not been queued yet, see QueueBuffer(), or it has been retrieved after grabbing using RetrieveResult().
        <li> FinishGrab() or Close() have not been called for the grab session yet.
        <li> If the stream grabber requires the additional streaming state, streaming must not be started, see IsStartAndStopStreamingMandatory() and StartStreamingIfMandatory().
        </ul>

        \post
        <ul>
        <li> Transport layer-specific preparations have been reversed.
        <li> The buffer is deregistered.
        <li> The buffer can be freed if needed e.g., by calling delete.
        </ul>

        \error
        Throws an exception if deregistering the buffer fails.
        */
        virtual const void* DeregisterBuffer( StreamBufferHandle hStreamBuffer ) = 0;


        /*!
        \brief Prepares grabbing

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \note pylon uses a pool of buffers with a fixed amount of buffers to grab images. This is required because certain
        preparations e.g., locking the buffer's memory pages, must be made by the driver to be able to grab images into a buffer.
        Thus, using a pool of buffers is much more efficient than allocating a new buffer for every grabbed image.

        The node map integer parameters MaxBufferSize and MaxNumBuffer need to be set before calling PrepareGrab().

        MaxNumBuffer should be set to the number of buffers you plan to use for grabbing.
        \note There can be limitations depending on the transport layer technology used when using a large amount of buffers.

        MaxBufferSize needs to be set according to the PayloadSize parameter of the camera device or the stream grabber.
        If the stream grabber provides a PayloadSize parameter, the MaxBufferSize must be at least the size reported
        by the stream grabber payload size. This is the case if for instance a frame grabber or additional preprocessing
        is used.
        If the stream grabber does not provide a PayloadSize parameter, the MaxBufferSize must be at least the size reported
        by the camera device PayloadSize parameter.

        \pre
        <ul>
        <li> The node map integer parameter MaxBufferSize is set, see GetNodeNap().
        <li> The node map integer parameter MaxNumBuffer is set, see GetNodeNap().
        <li> The stream grabber is open.
        <li> No grab session is currently in progress.
        </ul>

        \post
        <ul>
        <li> Resources required for grabbing are allocated.
        <li> The camera is set up for grabbing.
        <li> Critical camera parameters, provided by IPylonDevice::GetNodeMap(), are locked.
        <li> The stream grabber is prepared.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if preparing the stream grabber fails. The stream grabber is not prepared after raising the exception.
        </ul>
        */
        virtual void PrepareGrab() = 0;


        /*!
        \brief Returns true if the Stream Grabber requires calling StartStreamingIfMandatory() for operation.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        Does not throw C++ exceptions.
        */
        virtual bool IsStartAndStopStreamingMandatory() = 0;


        /*!
        \brief Starts streaming for the stream grabber if this is mandatory for operation.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        Some stream grabbers e.g., some stream grabbers based on GenTL, have limitations on when buffers can
        be registered. For these stream grabbers it is mandatory to register all buffers first and
        call StartStreamingIfMandatory() aftwards.
        Between the StartStreamingIfMandatory() and StopStreamingIfMandatory() calls no buffers can be
        registered or deregistered if such a limitation exists.

        \note This method has been added in pylon 6.0 for supporting CoaXPress. Prior implementations
              of pylon stream grabbers did not require calling start and stop streaming.
              The IsStartAndStopStreamingMandatory(), StartStreamingIfMandatory(), and StopStreamingIfMandatory()
              methods allow backward-compatible operation.

        \pre
        <ul>
        <li> The stream grabber is prepared.
        </ul>

        \post
        <ul>
        <li> If the stream grabber does not require StartStreamingIfMandatory(), nothing is done.
        <li> Streaming is started. For GenTL-based stream grabbers DSStartAcquistion is called
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if start streaming fails. The stream grabber is not streaming after raising the exception.
        </ul>
        */
        virtual void StartStreamingIfMandatory() = 0;


        /*!
        \brief Stops streaming for the stream grabber if this is mandatory for operation.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        Some stream grabbers e.g., some stream grabbers based on GenTL, have limitations on when buffers can
        be registered. For these stream grabbers it is mandatory to call StopStreamingIfMandatory to be able to deregister buffer afterwards.

        \pre
        <ul>
        <li> The stream grabber is in streaming mode if start and stop streaming is mandatory.
        </ul>

        \post
        <ul>
        <li> If the stream grabber does not require StopStreamingIfMandatory(), nothing is done.
        <li> Streaming is stopped. For GenTL-based stream grabbers DSStopAcquistion is called.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if stop streaming fails. The stream grabber is not streaming after raising the exception.
        </ul>
        */
        virtual void StopStreamingIfMandatory() = 0;


        /*!
        \brief Stops grabbing finally

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        This method calls FlushBuffersToOutput() automatically if needed.

        \pre
        <ul>
        <li> The stream grabber is prepared.
        </ul>

        \post
        <ul>
        <li> Resources required for grabbing are freed.
        <li> The camera is not set up for grabbing anymore
        <li> Critical camera parameters, provided by IPylonDevice::GetNodeMap(), are unlocked.
        <li> The stream grabber is open.
        <li> Queued buffers are available in the output queue of the stream grabber and can be retrieved calling RetrieveResult().
        <li> All buffers are deregistered.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if finishing the grab fails. The stream grabber is in open state after raising the exception.
        </ul>
        */
        virtual void FinishGrab() = 0;


        /*!
        \brief Enqueues a buffer in the input queue.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \param[in] hStreamBuffer The handle of a buffer that has been provided by RegisterBuffer().
        \param[in] pContext A user-provided pointer passed along with buffer in the internal input and output queues.

        \pre
        <ul>
        <li> The buffer is registered, see RegisterBuffer().
        <li> The stream grabber is prepared.
        <li> The buffer has not been queued for grabbing yet.
        <li> The buffer is not waiting in the output queue of the stream grabber. The buffer can be queued again after it has been retrieved using RetrieveResult().
        </ul>

        \post
        <ul>
        <li> The buffer is queued to input queue of the stream grabber.
        <li> The buffer cannot be deregistered until it has been retrieved using RetrieveResult().
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if queuing the buffer fails.
        </ul>
        */
        virtual void QueueBuffer( StreamBufferHandle hStreamBuffer, const void* pContext = NULL ) = 0;


        /*!
        \brief Cancels grabbing the current buffer and flushes all buffers to the output queue.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \pre
        <ul>
        <li> The stream grabber is prepared.
        </ul>

        \post
        <ul>
        <li> All queued buffers are placed in the output queue of the stream grabber and can be retrieved using RetrieveResult().
        <li> Buffers that have not been grabbed completely before calling FlushBuffersToOutput are marked with the EGrabStatus Canceled.
        <li> The stream grabber is prepared.
        <li> Buffers can be queued again to continue grabbing.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if canceling the grab fails.
        </ul>
        */
        virtual void FlushBuffersToOutput() = 0;
        ///This method has been renamed to FlushBuffersToOutput(). Calling CancelGrab calls FlushBuffersToOutput();
        virtual void CancelGrab() = 0;


        /*!
        \brief Retrieves one grab result from the output queue.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        param[out] grabResult The object the grab result data is returned in if true is returned. The \c grabResult remains unchanged if false is returned.
        \return Returns true when result was available.

        \pre
        <ul>
        <li> The stream grabber is open.
        </ul>

        \post
        <ul>
        <li> If a grab result was available, it has been removed from the ouput queue.
        <li> The corresponding buffer can be queued again for grabbing.
        </ul>

        \threading
        This method is synchronized using an internal stream grabber lock.

        \error
        <ul>
        <li> Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
        <li> Throws an exception if retrieving the result fails. This does not change the stream grabber state.
        </ul>
        */
        virtual bool RetrieveResult( GrabResult& grabResult ) = 0;


        /*!
        \brief Returns the result event object of the stream grabber.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        This object is associated with the output queue of the stream grabber.
        The event is signaled when output queue is non-empty.

        \return Returns the result event object of the stream grabber.

        \threading
        This method can be synchronized using an internal stream grabber lock.

        \error
        Does not throw C++ exceptions.
        */

        virtual WaitObject& GetWaitObject() const = 0;


        /*!
        \brief Returns the associated stream grabber parameters.

        \note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects.
              If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

        \return Returns the associated stream grabber parameters. The returned pointer is never NULL.

        \threading
        This method can be synchronized using an internal stream grabber lock.

        \error
        Does not throw C++ exceptions.
        */
        virtual GenApi::INodeMap* GetNodeMap() = 0;
    };

}

#ifdef _MSC_VER
#   pragma pack(pop)
#endif /* _MSC_VER */

#endif //__ISTREAMGRABBER_H__