Context is the implicit owner of objects created when it's active and their properties. More...

Data Structures
struct	VPIParallelForConfig
	Stores the ParallelFor configuration. More...

Macros
#define	VPI_INVALID_CONTEXT ((VPIContext)-1)
	Represents a context was destroyed or is invalid for some other reason.

Typedefs
typedef void(*	VPIParallelTask) (int taskId, int threadId, void *vpiData)
	Parallel task function pointer type.

typedef void(*	VPIParallelForCallback) (VPIParallelTask task, int taskCount, void vpiData, void userData)
	Parallel for callback function pointer type. More...

typedef void *	VPINativeThreadHandle
	A handle to OS-specific thread handle.

typedef struct VPIContextImpl *	VPIContext
	A handle to a context.

Functions
VPIStatus	vpiContextCreate (uint64_t flags, VPIContext *ctx)
	Create a context instance. More...

VPIStatus	vpiContextCreateWrapperCUDA (uint64_t flags, CUcontext cudaCtx, VPIContext *ctx)
	Create a context instance that wraps a CUDA context. More...

void	vpiContextDestroy (VPIContext ctx)
	Destroy a context instance as well as all resources it owns. More...

VPIStatus	vpiContextSetParallelFor (VPIContext ctx, const VPIParallelForConfig *config)
	Controls low-level task parallelism of CPU devices owned by the context. More...

VPIStatus	vpiContextGetParallelFor (VPIContext ctx, VPIParallelForConfig *config)
	Returns parameters set by vpiContextSetParallelFor. More...

VPIStatus	vpiContextGetCurrent (VPIContext *ctx)
	Gets the context for the calling thread. More...

VPIStatus	vpiContextSetCurrent (VPIContext ctx)
	Sets the context for the calling thread. More...

VPIStatus	vpiContextPush (VPIContext ctx)
	Pushes the context to a per-thread context stack and sets this context as the current context for the calling thread. More...

VPIStatus	vpiContextPop (VPIContext *ctx)
	Pops a context from a per-thread context stack and saves it to the ctx variable. More...

VPIStatus	vpiContextGetFlags (VPIContext ctx, uint64_t *flags)
	Get the current context flags. More...

Special contexts

#define	VPI_GLOBAL_CONTEXT ((VPIContext)0x610BA1C1D)
	Global context identifier.

Detailed Description

Context is the implicit owner of objects created when it's active and their properties.

This is a top-level class that manages the lifetime and properties of all other API objects. Specifically, it has the following properties:

Thread-specific - every thread within an application has one current VPIContext instance set. If no instance has been explicitly set for a particular thread, all API calls from this thread will use a process-specific default context instance instead.
Configurable - the user can specify during construction which kinds of backends are enabled for this context. This effectively allows to mask support for a particular hardware. For example, creating a VPIStream instance for a CUDA backend will fail if the current context doesn't have the VPI_BACKEND_CUDA flag set. When no backends are passed to context creation, all backends supported by the running platform are enabled in it. For example, when passing '0' as context flags (no backends) and only CPU and CUDA backends are available, vpiContextGetFlags will return \ref VPI_BACKEND_CUDA|\ref VPI_BACKEND_CPU flags.
Allows for association with a specific CUDA driver API CUcontext instance - this should permit multi-GPU processing.
Sharing buffers between different contexts is not permitted.

Data Structure Documentation

◆ VPIParallelForConfig

struct VPIParallelForConfig

Stores the ParallelFor configuration.

Definition at line 198 of file Types.h.

Collaboration diagram for VPIParallelForConfig:

Data Fields
int	maxThreads	The maximum number of threads used by the parallel_for implementation code. Has to be larger than 0. Setting the number to N means that the parallel for implementation will call task functors with task id between 0 and N-1. Calling task functors with thread id outside of this range is not legal and will result in undefined behavior.
VPIParallelForCallback	callback	A pointer to the parallel_for implementation. If null is passed, the context will fallback to the default internal parallel_for implementation. parallel_for implementation is required to be thread-safe. Internal API implementation might call this function from different threads at the same time.
void *	userData	A user defined opaque pointer passed to callback function unaltered.

Typedef Documentation

◆ VPIParallelForCallback

typedef void(* VPIParallelForCallback) (VPIParallelTask task, int taskCount, void *vpiData, void *userData)

#include </opt/nvidia/vpi2/include/vpi/Types.h>

Parallel for callback function pointer type.

A serial (reference) implementation of this function might looks as follows:

void parallel_for(VPIParallelTask task, int taskCount, void *vpiData, void *userData)
{
   for (int i = 0; i < taskCount; ++i)
   {
     task(i, 0, vpiData);
   }
}

Parallel implementation should have equivalent behavior; that is, run all tasks between 0 and taskCount-1 and block the calling thread until all tasks have been completed. threadId parameter should be between 0 and maxThreads-1 (

See also: vpiContextSetParallelFor). Implementations that have maxThreads set to zero can pass an arbitrary threadId value to task functions.

Definition at line 191 of file Types.h.

Function Documentation

◆ vpiContextCreate()

VPIStatus vpiContextCreate	(	uint64_t	flags,
		VPIContext *	ctx
	)

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Create a context instance.

The context owns the following objects that are created when it is active:

The backends enabled in the context restrict the allowed backends that can be enabled when creating the objects when context is active.

The context is created and internal resources are allocated. It isn't assigned to the calling thread, though. For that, use either vpiContextSetCurrent or vpiContextPush.

Parameters

[in]	flags	Bit field specifying the desired characteristics of the context. The field must be a combination of zero or more of the following flags: VPIBackend flags. Defines the set of backends that can be enabled during object creation when this context is active. If no backend flags are given, VPI will enable all backends supported by the running platform. Context-specific flags. Common object flags. If backends are given, their corresponding hardware must be available.
[out]	ctx	Pointer to memory that will receive the new context handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `ctx` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`flags` is invalid.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't available in current system.
VPI_SUCCESS	Operation executed successfully.

◆ vpiContextCreateWrapperCUDA()

VPIStatus vpiContextCreateWrapperCUDA	(	uint64_t	flags,
		CUcontext	cudaCtx,
		VPIContext *	ctx
	)

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Create a context instance that wraps a CUDA context.

CUDA operations will all under the wrapped context whenever the created context is active.

Note: Currently VPI doesn't do anything with the CUDA context, so currently the call performs exactly like vpiContextCreate.

Behavior regarding objects created when this context is active is same as vpiContextCreate.

Parameters

[in]	flags	Bit field specifying the desired characteristics of the context. The field must be a combination of zero or more of the following flags: VPIBackend flags. Defines the set of backends that can be enabled during object creation when this context is active. If no backend flags are given, VPI will enable all backends supported by the running platform. Context-specific flags. Common object flags. If backends are given, their corresponding hardware must be available.
[in]	cudaCtx	CUDA context handle to be wrapped. Mandatory, it can't be NULL. It must be a valid CUDA context.
[out]	ctx	Pointer to memory that will receive the created context handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `ctx` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`flags` is invalid.
VPI_ERROR_INVALID_ARGUMENT	`cudaCtx` is NULL or doesn't represent a valid CUDA context.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to create context.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't available in current system.
VPI_SUCCESS	Operation executed successfully.

◆ vpiContextDestroy()

void vpiContextDestroy ( VPIContext ctx )

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Destroy a context instance as well as all resources it owns.

The context will be destroyed regardless of how many threads it is active in. It is the responsibility of the calling function to ensure that no API call issues using ctx while vpiContextDestroy is executing.

Upon context destruction, all streams associated with it will be synced, then all objects associated with it will be destroyed.

If context is current to the calling thread, then it will also be popped from the current thread's context stack as though vpiContextPop was called. If the context is current to other threads, then it'll will remain current to those threads, and attempting to access it from those threads will result in the error VPI_ERROR_INVALID_CONTEXT.

Parameters

[in] ctx Context handle. Passing NULL is allowed, to which the function simply does nothing. Passing VPI_GLOBAL_CONTEXT also makes it do nothing as it's impossible to destroy the global context.

◆ vpiContextSetParallelFor()

VPIStatus vpiContextSetParallelFor	(	VPIContext	ctx,
		const VPIParallelForConfig *	config
	)

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Controls low-level task parallelism of CPU devices owned by the context.

This function allows the user to overload the parallel_for implementation used by the CPU backend. Changing this parallel_for implementation on a context that is performing CPU processing is undefined and might lead to application crashes.

When a context is created, the parallel_for implementation used is the default. It allows for each CPU task to equaly use all cores available.

Parameters

[in]	ctx	Context handle. Mandatory, it can't be NULL or invalid.
[in]	config	A pointer to parallel_for configuration. Passing NULL will make the context to fallback to its default internal implementation.

Return values

VPI_ERROR_INVALID_ARGUMENT	`ctx` is NULL or invalid.
VPI_SUCCESS	Operation executed successfully .

◆ vpiContextGetParallelFor()

VPIStatus vpiContextGetParallelFor	(	VPIContext	ctx,
		VPIParallelForConfig *	config
	)

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Returns parameters set by vpiContextSetParallelFor.

Parameters

[in]	ctx	Context handle. Mandatory, it can't be NULL or invalid.
[out]	config	A pointer to parallel_for configuration. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `config` pointer is NULL.
VPI_ERROR_INVALID_ARGUMENT	`ctx` is NULL or invalid.
VPI_SUCCESS	Operation executed successfully.

◆ vpiContextGetCurrent()

VPIStatus vpiContextGetCurrent ( VPIContext * ctx )

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Gets the context for the calling thread.

Parameters

[out]

ctx

Pointer to a context handle.

Mandatory, it can't be NULL or invalid.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `ctx` is NULL.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_SUCCESS	Operation executed successfully

◆ vpiContextSetCurrent()

VPIStatus vpiContextSetCurrent ( VPIContext ctx )

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Sets the context for the calling thread.

If the context stack isn't empty, this function will replace the top of the stack (current context) of thread.

Parameters

[in]

ctx

Context handle.

Mandatory, it can't be NULL or invalid;

Return values

VPI_ERROR_INVALID_ARGUMENT	`ctx` is NULL or invalid value.
VPI_SUCCESS	Operation executed successfully.

◆ vpiContextPush()

VPIStatus vpiContextPush ( VPIContext ctx )

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Pushes the context to a per-thread context stack and sets this context as the current context for the calling thread.

At most 8 contexts can be pushed to the stack.

Parameters

[in]

ctx

Context handle.

Mandatory, it can't be NULL.
It must be a valid context.

Return values

VPI_ERROR_INVALID_CONTEXT	`ctx` is invalid.
VPI_ERROR_INVALID_ARGUMENT	`ctx` is NULL.
VPI_ERROR_INVALID_OPERATION	Stack size outside valid range.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_SUCCESS	Operation executed successfully

◆ vpiContextPop()

VPIStatus vpiContextPop ( VPIContext * ctx )

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Pops a context from a per-thread context stack and saves it to the ctx variable.

After the pop operation, the context on top of context stack is current (active) for the calling thread.

The context stack cannot be empty.

Parameters

[out] ctx Pointer to a context handle that receives the popped context. If NULL, it'll still pop the context, but won't return it.

Return values

VPI_ERROR_INVALID_OPERATION	Cannot pop from empty stack.
VPI_SUCCESS	Operation executed successfully.

◆ vpiContextGetFlags()

VPIStatus vpiContextGetFlags	(	VPIContext	ctx,
		uint64_t *	flags
	)

#include </opt/nvidia/vpi2/include/vpi/Context.h>

Get the current context flags.

This function can be used to verify underlying backend support of current context.

Parameters

[in]	ctx	Context handle. Mandatory, it can't be NULL or invalid;
[out]	flags	Pointer to a variable which will be set to the current context flags. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `flags` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`ctx` is NULL.
VPI_ERROR_INVALID_CONTEXT	`ctx` is invalid.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_SUCCESS	Operation executed successfully.

VPI - Vision Programming Interface

2.4 Release

Data Structures

Macros

Typedefs

Functions

Special contexts

Detailed Description

Data Structure Documentation

◆ VPIParallelForConfig

Typedef Documentation

◆ VPIParallelForCallback

Function Documentation

◆ vpiContextCreate()

◆ vpiContextCreateWrapperCUDA()

◆ vpiContextDestroy()

◆ vpiContextSetParallelFor()

◆ vpiContextGetParallelFor()

◆ vpiContextGetCurrent()

◆ vpiContextSetCurrent()

◆ vpiContextPush()

◆ vpiContextPop()

◆ vpiContextGetFlags()