core/docs/usecase5.md

Go to the documentation of this file.

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

@page core_usecase5 Context
@tableofcontents

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

The NVIDIA<sup>&reg;</sup> DriveWorks
Context module stores all global components, including:
- Pointer logging callbacks.
- NvMedia Device instance.
- Global timesource.
- Platform information.
- Virtual file system.

Every module requires a handle to a valid context instance. When a module is
created within a certain context, it functions only within that context. Outside of this context, it does not exist.

@section core_context_initalization Context Initialization

The DriveWorks SDK context must be initialized before any other DriveWorks module.
A typical context initialization looks like the following:

```{.cpp}
#include <dw/core/Context.h>
#include <dw/core/VersionCurrent.h>

...

// initialize SDK context, using data folder
dwContextParameters contextParams = {};
contextParams.dataPath            = "path/to/location/of/resource.pak/folder";
contextParams.eglDisplay          = getEGLDisplay();  // on DRIVE platforms this should point to right EGL display, on x86 just nullptr

// Initialize DriveWorks context
dwInitialize(&sdkContext, DW_VERSION, &contextParams);

...
// do processing
...

// release SDK context
dwRelease(&sdkContext);
```

@note If a `nullptr` is passed for `dataPath`, then a data folder is looked for in typical
install locations in relation to the current driveworks library install location.
If a data directory is still not found then virtual file system will be unavailable.
When that happens, modules that use certain DNN networks will not function properly.

When modules call dwInitialize(), they usually pass `DW_VERSION` as the argument
that specifies the current DriveWorks API version.
dwInitialize() uses that argument to ensure the version of the API headers and the library match.
After that, the function initializes all context subcomponents.

During the initialization phase, DriveWorks initializes:
- NVIDIA<sup>&reg;</sup> CUDA<sup>&reg;</sup>
- DLA (applies only to NVIDIA DRIVE<sup>&trade;</sup> platforms)
- OpenGL extensions, if OpenGL is available
- NvMedia components, if running on an NVIDIA DRVE<sup>&trade;</sup> platform


@section core_context_currenttime Current System Time

An SDK context provides access to the common clock used within all SDK modules.
For event timestamps, DriveWorks uses a high-resolution monotonic clock with
microseconds precision. Sensor samples are an example of event timestamps. Any
module accepting `dwTime_t` as input argument, assumes the time is in the right
units and is from the same domain.

```{.cpp}
// get current system time
dwTime_t now = 0;
dwContext_getCurrentTime(&now, sdkContext);

printf("Time now is %f [sec]\n", now / 1e6);
```

@note The returned time is based on UNIX Epoch time.

@section core_context_pva Programmable Vision Accelerator

An SDK context provides the possibility to enable PVA (Programmable Vision Accelerator) on
NVIDIA DRVE<sup>&trade;</sup> platforms.

If PVA is not enabled, modules that execute on PVA will not work properly.
PVA can be enabled during context initialization like this:

```{.cpp}

...
// other initialization parameters
...

// Enable PVA
contextParams.enablePVA           = true;

// Initialize DriveWorks context
dwInitialize(&sdkContext, DW_VERSION, &contextParams);

...
// do processing
...

// release SDK context
dwRelease(&sdkContext);
```

@note There can be maximum 8 SDK contexts with PVA running simultaneously on
an NVIDIA DRVE<sup>&trade;</sup> platform.

@section core_context_cuda_task_graph CUDA Task-Graph

An SDK context can be initialized with CUDA Task-Graph enabled.

If it is enabled, CUDA Task-Graph will be used where applicable; such as, DNN inference for models that support this sort of execution.
CUDA Task-Graph can be enabled during context initialization like this:

```{.cpp}

...
// other initialization parameters
...

// Enable CUDA Task-Graph
contextParams.enableCudaTaskGraph = true;

// Initialize DriveWorks context
dwInitialize(&sdkContext, DW_VERSION, &contextParams);

...
// do processing
...

// release SDK context
dwRelease(&sdkContext);
```