Content Slice and Updates

Note

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

As described in Map Request 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.

dwStatus dwMapProvider_getContentLayers(dwMapsContentLayerBuffer* layers,
                                        dwConstMapsProviderHandle_t providerHandle);

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

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.

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:

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:

// 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:

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 */
    }
}