/dvs/git/dirty/gitlab-master_av/dw/sdk/src/dwvisualization/maps/mapsrenderer/docs/usecase1.md

Go to the documentation of this file.

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

@page renderer_usecase3 Maps Renderer

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

The Maps Renderer
- renders map data contained in the NVIDIA<sup>&reg;</sup> DriveWorks Maps module
- renders objects defined in WGS84 coordinates on top of the map

It uses the Render Engine to render the data.


## General Usage

```{.cpp}
    // init map

    // init maps renderer module
    dwMapsRenderer_initialize(...);

    while (...)
    {
        //
        // orthographic top down rendering
        //

        // select render engine tile
        dwRenderEngine_setTile(...)

        // setup camera for top down view onto map data
        dwMapsRenderer_setTopDownProjection(...); // camera zoom
        dwMapsRenderer_setTopDownModelView(...);  // camera position

        // render
        dwMapsRenderer_renderMap(...)
        dwMapsRenderer_renderLanePlan(...)
        dwMapsRenderer_renderPolylines(...)
        dwMapsRenderer_renderOrientedBox(...)
        dwMapsRenderer_renderBox(...)



        //
        // perspective rendering
        //

        // select render engine tile
        dwRenderEngine_setTile(...)

        // set camera zoom
        dwRenderEngine_setPerspectiveProjection(...)

        // set camera position and orientation
        dwMapsRenderer_setLookAt(...)

        // render
        dwMapsRenderer_renderMap(...)
        dwMapsRenderer_renderLanePlan(...)
        dwMapsRenderer_renderPolylines(...)
        dwMapsRenderer_renderOrientedBox(...)
        dwMapsRenderer_renderBox(...)
    }

    // release module
    dwMapsRenderer_release(...);
```


## Initialization

The Maps Renderer is initialized with a map handle of the DriveWorks Maps module and initializes a render buffer using the Render Engine. That render buffer gets filled with lines for all lane dividers in the map. Additionally, a buffer gets allocated for additional renderings during runtime. The user has to specify the maximum number of lines that will be needed during one of the render calls that render additional data (all render calls other than dwMapsRenderer_renderMap()).
Also, it can be chosen whether the line directions of the map should be visible, so that it can be seen where lines start and end. When setting `showMapLineDirections` to true, the lines will be shaded (darker to brighter) to show the line directions.

```{.cpp}
dwStatus dwMapsRenderer_initialize(dwMapsRendererHandle_t* mapsRenderer,
                                   uint32_t maxRenderBufferLineCount,
                                   uint32_t maxRenderBufferPointCount,
                                   bool showMapLineDirections,
                                   dwRenderEngineHandle_t renderEngine,
                                   dwConstMapHandle_t map);
```


## dwRenderEngine

The Maps Renderer uses the Render Engine. It renders any lines with the current setting of the Render Engine. That means, it renders into the active tile, using its projection and modelView matrix and with line width settings. Color handling is different depending on the render call. There are helper functions to set up the projection and modelView matrices for the Maps Renderer.



## Render Functions

The Maps Renderer provides the following render functions:

```{.cpp}
dwMapsRenderer_renderMap
```

Renders all map lane dividers.


```{.cpp}
dwMapsRenderer_renderLanePlan
```

Render the lines of a lane plan from the DriveWorks Lane Planner module.


```{.cpp}
dwMapsRenderer_renderGeoPolylines
```

Render a list of polylines of WGS84 points.


```{.cpp}
dwMapsRenderer_renderOrientedGeoBox
```

Render an oriented box, defined by a WGS84 point, a bearing (clockwise angle to north) in radian, length and width in meters, optionally with a center cross and/or an arrow towards the bearing direction.


```{.cpp}
dwMapsRenderer_renderGeoBox
```

Render an axis-aligned square box defined by a WGS84 point and a size in meters, optionally with a center cross.


## Camera setup

There are helper functions to set up projection and modelview matrices.

```{.cpp}
dwMapsRenderer_setTopDownProjection
```

Set the projection matrix in the renderEngine tile such that the active tile height covers a given distance of map data in meters.


```{.cpp}
dwMapsRenderer_setTopDownModelView
```

Set the modelView matrix in the renderEngine tile such that the given WGS84 coordinate is in the tile center.


```{.cpp}
dwMapsRenderer_moveTopDownModelView
```

Move the modelView matrix by a given delta in meters. This assumes the current modelView matrix is already set up for top-down orthographic view.


```{.cpp}
dwMapsRenderer_setLookAt
```

Set up the modelView matrix such that the camera is at a given WGS84 point, looking towards another WGS84 point.


## Pixel Queries

There are helper functions to check whether a screen pixel is within a box that is defined by WGS84 coordinates:

```{.cpp}
dwMapsRenderer_isPixelCoordInOrientedBox
dwMapsRenderer_isPixelCoordInBox
```


## Coordinate Queries

There are helper functions to transform between different coordinates.

```{.cpp}
dwMapsRenderer_getRenderCoord
```

Returns the internally used render coordinate of a WGS84 point. This can be used to externally render lines into the same coordinate system.


```{.cpp}
dwMapsRenderer_getWGS84CoordFromRenderCoord
```

Returns the WGS84 coordinate for a point given in the internal render coordinate system.


```{.cpp}
dwMapsRenderer_getWGS84Coord
```

Returns the WGS84 coordinate that corresponds to a screen pixel. This can be used to localize mouse clicks on the screen, for example.


```{.cpp}
dwMapsRenderer_getWGS84CoordNDC
```

Returns the WGS84 coordinate that corresponds to a Normalized Display Coordinate system, with (0,0) in the center of the screen, going from (-1,-1) to (1,1). This can be helpful when selecting a point at a given position on the screen, e.g. screen center.

For more information see @ref dwx_hd_map_access_sample .