maps/docs/usecase2.md

Go to the documentation of this file.

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

@page maps_usecase2 Map Request

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

Map data is accessed by making requests to the map Provider including desired bounds or route
coverage for the Map and all desired Content Layers e.g. localization images, point clouds.

All Map requests include the Core Layer contained directly by the returned Map object which
includes Road Segments, Lane Groups, Lanes, Lane Divider Groups, Lane Dividers and Features.

Available Content Layers are obtained from the Map Provider.

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

The two supported APIs for launching a map request are shown below.

```{.cpp}
   dwStatus dwMapProvider_requestMapForBounds(
       dwMapsRequestToken* requestToken,
       const dwMapsBounds* bounds,
       const dwMapsContentLayerBuffer* layers,
       dwMapProviderHandle_t providerHandle);

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

The system returns a request token that can be used later to try and retrieve the requested Map.

```{.cpp}
   dwStatus dwMapProvider_tryGetRequestedMap(
       dwConstMapHandle_t* mapHandle,
       dwMapsRequestToken requestToken,
       dwMapProviderHandle_t providerHandle);
```

This is an asynchronous polling API, since it may take significant time to complete a Map request.
While the requested Map is still being prepared for the client, this method returns DW_NOT_READY.
Once the requested Map is available, the above method returns DW_SUCCESS along with the Map handle.

It is important to understand that the Map memory is "owned" by the Map Provider.
Applications should not directly destroy a Map handle, but release it directly to the Map Provider.
This enables the Map Provider to reuse the allocated memory for the Map to service future requests.

```{.cpp}
   dwStatus dwMapProvider_releaseMap(
       dwConstMapHandle_t mapHandle,
       dwMapProviderHandle_t providerHandle);
```

For more information see @ref dwx_hd_map_access_sample .