image/docs/usecase2.md

Go to the documentation of this file.

# Copyright (c) 2019-2020 NVIDIA CORPORATION.  All rights reserved.

@page image_usecase2 Image Streamer
@tableofcontents

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

This tutorial demonstrates how to stream an image from host (CPU) memory, to device (CUDA) memory.<br>

The ImageStreamer module is accessed through a handle:

```{.cpp}
dwImageStreamerHandle_t streamerCPU2CUDA = DW_NULL_HANDLE;
```
@section image_usecase2_creating_image Creating an Image

To create an image for streaming:

```{.cpp}
    // the image is going to be format interleaved RGB and type UINT_8
    dwImageProperties cpuProp{};
    cpuProp.type = DW_IMAGE_CPU;
    cpuProp.width = imageWidth;
    cpuProp.height = imageHeight;
    cpuProp.format = DW_IMAGE_FORMAT_RGB_UINT8;
    cpuProp.memoryLayout = DW_IMAGE_MEMORY_TYPE_DEFAULT; // not necessary to specify if init with {}

    //Create an image with these properties
    dwImageHandle_t rgbCPU;
    dwImage_create(&rgbCPU, cpuProp, m_context);
```

@section image_usecase2_initialize Initializing the ImageStreamer Module

Once an image is creating for streaming, an ImageStreamer must be initialized to stream the CPU image to CUDA.<br>
In the following example, the ::dwImageStreamerHandle_t handle initializes the ImageCapture module to stream <br> an image with `cpuProp` image properties to type ::dwImageCUDA:

```{.cpp}
    // streamer from CPU to CUDA
    dwImageStreamerHandle_t streamerCPU2CUDA = DW_NULL_HANDLE;

    dwImageStreamer_initialize(streamerCPU2CUDA, &cpuProp, DW_IMAGE_CUDA, dwContext);
```

@section image_usecase2_streaming_image Streaming the Image

To stream the image:

```{cpp}
    dwImageStreamer_producerSend(rgbCPU,streamerCPU2CUDA);
    dwImageHandle_t rgbCUDA;
    dwImageStreamer_consumerReceive(&rgbCUDA,streamerCPU2CUDA);
```

@section image_usecase2_return Returning the Images

An image must be returned once streaming to CUDA memory is complete:

```{cpp}
    dwImageStreamer_consumerReturn(rgbCUDA,streamerCPU2CUDA);
    dwImageStreamer_producerReturn(rgbCPU,streamerCPU2CUDA);
```

@section image_usecase2_releasing_handle Releasing the Handle

To release the handle:

```{cpp}
    dwImageStreamer_release(streamerCPU2CUDA);
```

To see a full demonstration of this workflow, please refer to @ref dwx_image_streamer_simple_sample.