.. _camera-receive-images-label:

Receive Captured Images
~~~~~~~~~~~~~~~~~~~~~~~

The application has to be set-up to receive captures, to be able to acquire the images from the connected camera after capture.

After opening the camera, image receiving can be enabled, as follows:

.. code-tabs::

    .. include-tab:: ../../labels/cppEnableImageReceiving
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csEnableImageReceiving
        :language: csharp
        :title: C#

.. TODO: If desired, the host storage capacity can be explicitly set - see Appendix J.

Now, a capture can be triggered:

.. code-tabs::

    .. include-tab:: ../../labels/cppTriggerCapture
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csTriggerCapture
        :language: csharp
        :title: C#

To receive the image, use the ``WaitForImage`` method, as follows:

.. code-tabs::

    .. include-tab:: ../../labels/cppWaitForImage
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csWaitForImage
        :language: csharp
        :title: C#

The ``WaitForImage`` method is a blocking call, which will listen for captures as long as the application is running, or until the specified time has passed with no capture received.

The timeout can be specified as a parameter of the method. If the timeout is reached, the CameraSDK will throw an exception (in C++), or return a ``null`` value (in C#) (see :ref:`error-handling-label`). A timeout-value of "0" means "wait forever" – this is the default, if no value is specified.

.. caution:: After an image has been received, the CameraSDK "owns" the memory until a destructor is used on the ``imageFile`` object. See :ref:`camera-memory-management-label` for more.

.. note:: The ``WaitForImage`` method returns only one image for each call. Thus, every time an image is captured on the camera, the ``WaitForImage`` method has to be called to receive the image.

.. image:: image-receiving.png
    :width: 75%
    :alt: Internal image receive-queues
    :align: center

When transferring images from the camera to the application, there are two separate image queues. The queue of images from the camera to the CameraSDK is auto-handled by the CameraSDK, when ``EnableImageReceiving`` is set to "``true``". The ``WaitForImage`` method is waiting on images from the CameraSDK’s queue – not the camera’s internal queue – and returns the next image from the CameraSDK’s queue each time it is invoked, until the CameraSDK’s queue is empty.

.. note:: The queue of images in the camera can be investigated using the ``UnsavedImages`` property. The CameraSDK’s queue can only be investigated by using the ``WaitForImage`` method; if no images are returned, no images are in the CameraSDK’s queue.

All threads blocked by a WaitForImage-call are released if the camera is disconnected. The waiting thread can also be forcefully released by another thread, as defined in the following example:

.. code-tabs::

    .. include-tab:: ../../labels/cppWakeUpWaitingImageThreads
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csWakeUpWaitingImageThreads
        :language: csharp
        :title: C#

.. caution:: The ``WakeUpWaitingImageThreads`` call releases blocked threads, held in the camera’s ``WaitForImage`` **and** ``WaitForLiveView`` (see :ref:`camera-liveview-label`) methods.