image/docs/usecase5.md

Go to the documentation of this file.

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

@page image_usecase5 Image Creation and Conversion
@tableofcontents

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

This section demonstrates the different methods to create an @ref image_mainsection.

Once an image is created, you can stream it from host (CPU) memory to device (CUDA) memory across:
- A [single process and thread](@ref image_usecase2).
- [Multiple processes](@ref image_usecase3).
- [Multiple threads](@ref image_usecase4).

@section image_usecase5_creation Creating an Image

@subsection image_usecase5_basic Basic Creation

This is the simplest method to create an image.<br>
The ownership for the image is transferred to the application, which is responsible for destroying the object when no longer needed.

```{.cpp}
    dwImageProperties imageProperties{};
    imageProperties.type = DW_IMAGE_CPU;
    imageProperties.format = DW_IMAGE_FORMAT_RGB_UINT8_PLANAR;
    imageProperties.width = 1200;
    imageProperties.height = 800;
    dwImageHandle_t image;
    dwImage_create(&image, imageProperties, ...);

    // CODE: Use image
    dwSomeDriveWorksModule_compute(image,...);

    dwImage_destroy(&image);
```

@subsection image_usecase5_buffer Creation with Provided Buffer

This method is similar to the Basic Creation. In this case, the application provides the memory buffer used to store the image.

```{.cpp}
    uint8_t* buffer[3];
    // CODE: Read some data source into buffer
    size_t* pitch[3];
    // CODE: Calculate pitch

    dwImageProperties imageProperties{};
    imageProperties.type = DW_IMAGE_CPU;
    imageProperties.format = DW_IMAGE_FORMAT_RGB_UINT8_PLANAR;
    imageProperties.width = 1200;
    imageProperties.height = 800;

    dwImageHandle_t image;
    dwImage_createAndBindBuffer(&image, imageProperties, buffer, pitch, ...);

    // CODE: Use image
    dwSomeDriveWorksModule_compute(image,...); // NOTE, buffer might be modified here

    // Destroy the image handle
    dwImage_destroy(&image);

    // Note, the user provided buffer is still available for usage
```

@section image_usecase5_access_data Accessing Data Explicitly

After creating an image through the demonstrated methods above, its content can be accessed in the following way:

```{cpp}
    dwImageCPU *imageCPU;
    dwImage_getCPU(&imageCPU, image);

    size_t planeCount;
    dwImage_getPlaneCount(&planeCount, DW_IMAGE_FORMAT_RGB_UINT8_PLANAR);

    for (uint32_t plane = 0; plane < planeCount; ++p) {
        for (uint32_t i = 0; i < imageProperties.height; ++i) {
            for (uint32_t j = 0; j < imageProperties.width; ++j) {
                imageCPU->data[plane][i * imageCPU->pitch[plane] + j] = ...; // this affects the image
            }
        }
    }
```

@note This snippet assumes the type of the image created is ::DW_IMAGE_CPU.

@section image_usecase5_conversion Converting Format

An image's format and properties can be converted in the following way:

```{.cpp}
    dwImageProperties imageProperties{};
    imageProperties.type = DW_IMAGE_CUDA;
    imageProperties.format = DW_IMAGE_FORMAT_RGBA_UINT8;
    imageProperties.width = 1200;
    imageProperties.height = 800;
    dwImageHandle_t outputImage;
    dwImage_create(&outputImage, imageProperties, ...);

    // CODE: Get some CUDA image
    dwImageHandle_t inputImage
    dwSomeDriveWorksModule_getImage(inputImage,...);

    dwImage_copyConvert(outputImage, inputImage,...);

    // CODE: Use outputImage
    ...

    // Destroy the outputing image 
    dwImage_destroy(&outputImage);
```

@note The input and output images must be of the same type.
@note This operation applies to ::DW_IMAGE_CUDA and ::DW_IMAGE_NVMEDIA only.