VPI - Vision Programming Interface

1.0 Release

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 (uint32_t flags, VPIContext *ctx)
 Create a context instance. More...
 
VPIStatus vpiContextCreateCudaContextWrapper (uint32_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, uint32_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:


Data Structure Documentation

◆ VPIParallelForConfig

struct VPIParallelForConfig

Stores the ParallelFor configuration.

Definition at line 139 of file Types.h.

+ Collaboration diagram for VPIParallelForConfig:
Data Fields
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.

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.

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 <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);
}
}
void(* VPIParallelTask)(int taskId, int threadId, void *vpiData)
Parallel task function pointer type.
Definition: Types.h:108

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 132 of file Types.h.

Function Documentation

◆ vpiContextCreate()

VPIStatus vpiContextCreate ( uint32_t  flags,
VPIContext ctx 
)

#include <vpi/Context.h>

Create a context instance.

Parameters
[in]flagsContext flags. User can pass a set of VPIBackend flags or-ed together. This will restrict the enabled backends of objects created while this context is active.
[out]ctxPointer to memory that will receive the new context handle.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiContextCreateCudaContextWrapper()

VPIStatus vpiContextCreateCudaContextWrapper ( uint32_t  flags,
CUcontext  cudaCtx,
VPIContext ctx 
)

#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 the call performs exactly like vpiContextCreate().
Parameters
[in]flagsContext flags. It's assumed that VPI_BACKEND_CUDA is always enabled.
[in]cudaCtxCUDA context handle to be wrapped.
[out]ctxPointer to memory that will receive the new context handle.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextDestroy()

void vpiContextDestroy ( VPIContext  ctx)

#include <vpi/Context.h>

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

The context ctx 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.

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

Parameters
[in]ctxContext handle. Passing NULL is accepted. In this case no operation is performed.

◆ vpiContextGetCurrent()

VPIStatus vpiContextGetCurrent ( VPIContext ctx)

#include <vpi/Context.h>

Gets the context for the calling thread.

If there is no error and current context is NULL, the thread is using the global context.

Parameters
[out]ctxpointer to a context handle
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextGetFlags()

VPIStatus vpiContextGetFlags ( VPIContext  ctx,
uint32_t *  flags 
)

#include <vpi/Context.h>

Get the current context flags.

This function can be used to verify underlying backend support.

Parameters
[in]ctxa context handle
[out]flagsa pointer to a variable which will be set to the current context flags
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextGetParallelFor()

VPIStatus vpiContextGetParallelFor ( VPIContext  ctx,
VPIParallelForConfig config 
)

#include <vpi/Context.h>

Returns parameters set by vpiContextSetParallelFor.

Parameters
[in]ctxContext handle
[out]configA pointer to parallel_for configuration.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextPop()

VPIStatus vpiContextPop ( VPIContext ctx)

#include <vpi/Context.h>

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

The top of the context stack is set as the current context for the calling thread.

Parameters
[out]ctxpointer to a context handle
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextPush()

VPIStatus vpiContextPush ( VPIContext  ctx)

#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.

Parameters
[in]ctxContext handle
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextSetCurrent()

VPIStatus vpiContextSetCurrent ( VPIContext  ctx)

#include <vpi/Context.h>

Sets the context for the calling thread.

If there are items on the context stack this will replace the top of the stack. If ctx is NULL this will clear the context stack and make the thread use the global context.

Parameters
[in]ctxa context handle
Returns
an error code on failure else VPI_SUCCESS

◆ vpiContextSetParallelFor()

VPIStatus vpiContextSetParallelFor ( VPIContext  ctx,
const VPIParallelForConfig config 
)

#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 CPU devices. Changing this parallel_for implementation on a context that is performing CPU processing is undefined and might lead to application crashes.

Parameters
[in]ctxContext handle.
[in]configA pointer to parallel_for configuration. Passing NULL will make the context to fallback to its default internal implementation.
Returns
an error code on failure else VPI_SUCCESS