maps/docs/usecase8.md

Go to the documentation of this file.

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

@page maps_usecase8 Content Slice and Updates

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

As described in @ref maps_usecase2 the Core Layer data is contained directly by the Map object
returned as the result of a map request. Content Slice provides a complementary mechanism
to access data-intensive Content Layer data per application and driving domain requirements.

Available Content Layers are obtained from the Map Provider interface.

```{.cpp}
   dwStatus dwMapProvider_getContentLayers(dwMapsContentLayerBuffer* layers,
                                            dwConstMapsProviderHandle_t providerHandle);
```

As mentioned in @ref maps_usecase2, desired Content Layers may be specified when launching a map
request, along with a geographic bounds or a planned route defined by WGS84 waypoints.

```{.cpp}
   dwStatus dwMapProvider_requestMapForRoute(
       dwMapsRequestToken* requestToken,
       const dwMapsRoute* route,
       const dwMapsContentLayerBuffer* layers,
       dwMapProviderHandle_t providerHandle);
```

Completion of a map requests provides a data guarantee for the requested Content Layers, subject to
availability for the requested Map. Map requests shall not fail in general due to limited coverage
of requested Content Layers because we cannot guarantee full coverage for all layers, however
local views into a Content Layers with sparse coverage may appear "empty" to the application.

This contract may change in future versions of the DriveWorks SDK, for example if applications
are found to require complete coverage of requested Content Layers for safety reasons. Consuming
code should not be harmed by this change if implemented, although more frequent map request
failures may be observed for map requests in regions with limited Content Layer coverage.

The runtime mechanism for accessing Content Layers is called the Content Slice. This object is
responsible for asynchronous retrieval of "layer slices" of selected Content Layers to provide
local views into layer data for the client application.

Initialization of the Content Slice requires a list of Content Layers and a LocalLayout "scope"
parameter defined as a maximum number of road segments per Local Layout. Those parameters are
used internally to allocate memory as needed for the requested layers.

```{.cpp}
    dwStatus dwMapsContentSlice_initialize(
        dwMapsContentSliceHandle_t* contentSliceHandle,
        const dwMapsContentLayerBuffer* layers,
        size_t maxSegmentsPerLayout,
        dwMapProviderHandle_t providerHandle);
```

In the future we will add an explicit memory allocation cap to ContentSlice for improved control.

A typical application of ContentSlice is to retrieve local views of point clouds, localization
images and other data-intensive content. Since these objects may not all be stored in memory for
the full map, they are loaded from disk on demand and therefore accessed by asynchronous APIs.

The Content Slice object provides local view APIs to access the currently loaded content:

```{.cpp}
    dwStatus dwMapsContentSlice_getImageLayerView(
        dwConstMapsImageLayerViewHandle_t* imageLayerViewHandle,
        dwConstMapsContentLayerHandle_t imageLayerHandle,
        dwMapsContentSliceHandle_t contentSliceHandle);

    dwStatus dwMapsContentSlice_getPointCloudLayerView(
        dwConstMapsPointCloudLayerViewHandle_t* pointCloudLayerViewHandle,
        dwConstMapsContentLayerHandle_t pointCloudLayer,
        dwMapsContentSliceHandle_t contentSliceHandle);
```

In order to load Content Layer data two objects are needed, Content Slice and Local Layout.
Here is a partial use case for initialiation of these objects:

```{.cpp}
    // Create content slice object including all layers
    dwMapsContentSliceHandle_t contentSliceHandle = nullptr;
    dwMapsContentSlice_initialize(
        &contentSliceHandle,
        &layerBuffer,
        MAX_ROAD_SEGMENTS,
        providerHandle);

    dwMapsLocalLayoutHandle_t localLayoutHandle = DW_NULL_HANDLE
    dwMapsLocalLayout_initialize(
        &localLayoutHandle,
        MAX_ROAD_SEGMENTS,
        10); /* maxComponents */
```

There is requirement for asynchronous updates, to avoid blocking the calling thread which
in general may have real-time execution constraints. In addition it is required to use
a polling API instead of callbacks to simplify application-side threading concerns.

This makes the full use for updating a Content Slice a bit complex:

```{.cpp}
    std::vector<dwMapsRoadSegment> roadSegments(MAX_ROAD_SEGMENTS);

    dwMapsRoadSegmentBuffer roadSegmentBuffer = {0};
    roadSegmentBuffer.buffer  = roadSegments.data();
    roadSegmentBuffer.maxSize = roadSegments.capacity();
    roadSegmentBuffer.size    = 0;

    dwMaps_getRoadSegments(
        &roadSegmentBuffer,
        layoutBounds, /* required bounds for Content Layers */
        mapHandle);

    dwMapsLocalLayout_addRoadSegments(
        roadSegmentBuffer.buffer,
        roadSegmentBuffer.size,
        localLayoutHandle);

    dwMapsLocalLayout_build(
        &layoutOrigin,
        localLayoutHandle);

    // Update loaded content asynchronously
    dwMapsContentUpdateToken updateToken = 0;
    dwMapsContentSlice_updateAsync(
        &updateToken,
        localLayoutHandle,
        0,
        contentSliceHandle);

    bool updateCompleted = false;

    // Wait for completion of content update
    while (!updateCompleted)
    {
        std::this_thread::yield();

        /* At this point content is loading in the background
         * It should not be available until dwMapsContentSlice_tryCompleteUpdate() succeeds.
         * "Completion" of the update triggers a swtich all layer views to present updated content. */
        status = dwMapsContentSlice_tryCompleteUpdate(
            updateToken,
            contentSliceHandle);

        if (status == DW_SUCCESS)
        {
            /* Now the application can access the updated content */
            updateCompleted = true;
        }
        else (status = DW_NOT_READY)
        {
            /* This is OK, it means the update is still pending */
        }
        {
            /* This is an error case */
        }
    }
```