The OpenVX Specification  2b213f9
Object: Context

## Detailed Description

Defines the Context Object Interface.

The OpenVX context is the object domain for all OpenVX objects. All data objects live in the context as well as all framework objects. The OpenVX context keeps reference counts on all objects and must do garbage collection during its deconstruction to free lost references. While multiple clients may connect to the OpenVX context, all data are private in that the references referring to data objects are given only to the creating party.

## Macros

#define VX_MAX_IMPLEMENTATION_NAME   (64)
Defines the length of the implementation name string, including the trailing zero.

## Typedefs

typedef struct _vx_context * vx_context
An opaque reference to the implementation context. More...

## Enumerations

enum  vx_accessor_e {
VX_READ_ONLY = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_ACCESSOR << 12)) + 0x1,
VX_WRITE_ONLY = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_ACCESSOR << 12)) + 0x2,
VX_READ_AND_WRITE = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_ACCESSOR << 12)) + 0x3
}
The memory accessor hint flags. These enumeration values are used to indicate desired system behavior, not the User intent. For example: these can be interpretted as hints to the system about cache operations or marshalling operations. More...

enum  vx_context_attribute_e {
VX_CONTEXT_VENDOR_ID = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x0,
VX_CONTEXT_VERSION = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x1,
VX_CONTEXT_UNIQUE_KERNELS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x2,
VX_CONTEXT_MODULES = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x3,
VX_CONTEXT_REFERENCES = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x4,
VX_CONTEXT_IMPLEMENTATION = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x5,
VX_CONTEXT_EXTENSIONS_SIZE = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x6,
VX_CONTEXT_EXTENSIONS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x7,
VX_CONTEXT_CONVOLUTION_MAX_DIMENSION = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x8,
VX_CONTEXT_OPTICAL_FLOW_MAX_WINDOW_DIMENSION = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0x9,
VX_CONTEXT_IMMEDIATE_BORDER = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0xA,
VX_CONTEXT_UNIQUE_KERNEL_TABLE = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0xB,
VX_CONTEXT_IMMEDIATE_BORDER_POLICY = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0xC,
VX_CONTEXT_NONLINEAR_MAX_DIMENSION = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_CONTEXT << 8)) + 0xd
}
A list of context attributes. More...

enum  vx_memory_type_e {
VX_MEMORY_TYPE_NONE = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_MEMORY_TYPE << 12)) + 0x0,
VX_MEMORY_TYPE_HOST = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_MEMORY_TYPE << 12)) + 0x1
}
An enumeration of memory import types. More...

enum  vx_round_policy_e {
VX_ROUND_POLICY_TO_ZERO = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_ROUND_POLICY << 12)) + 0x1,
VX_ROUND_POLICY_TO_NEAREST_EVEN = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_ROUND_POLICY << 12)) + 0x2
}
The Round Policy Enumeration. More...

enum  vx_termination_criteria_e {
VX_TERM_CRITERIA_ITERATIONS = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_TERM_CRITERIA << 12)) + 0x0,
VX_TERM_CRITERIA_EPSILON = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_TERM_CRITERIA << 12)) + 0x1,
VX_TERM_CRITERIA_BOTH = ((( VX_ID_KHRONOS ) << 20) | ( VX_ENUM_TERM_CRITERIA << 12)) + 0x2
}
The termination criteria list. More...

## Functions

vx_context VX_API_CALL vxCreateContext ()
Creates a vx_context. More...

vx_context VX_API_CALL vxGetContext (vx_reference reference)
Retrieves the context from any reference from within a context. More...

vx_status VX_API_CALL vxQueryContext (vx_context context, vx_enum attribute, void *ptr, vx_size size)
Queries the context for some specific information. More...

vx_status VX_API_CALL vxReleaseContext (vx_context *context)
Releases the OpenVX object context. More...

vx_status VX_API_CALL vxSetContextAttribute (vx_context context, vx_enum attribute, const void *ptr, vx_size size)
Sets an attribute on the context. More...

vx_status VX_API_CALL vxSetImmediateModeTarget (vx_context context, vx_enum target_enum, const char *target_string)
Sets the default target of the immediate mode. Upon successful execution of this function any future execution of immediate mode function is attempted on the new default target of the context. More...

## Typedef Documentation

 typedef struct _vx_context* vx_context

An opaque reference to the implementation context.

vxCreateContext

Definition at line 226 of file vx_types.h.

## Enumeration Type Documentation

A list of context attributes.

Enumerator
VX_CONTEXT_VENDOR_ID

Queries the unique vendor ID. Read-only. Use a vx_uint16.

VX_CONTEXT_VERSION

Queries the OpenVX Version Number. Read-only. Use a vx_uint16

VX_CONTEXT_UNIQUE_KERNELS

Queries the context for the number of unique kernels. Read-only. Use a vx_uint32 parameter.

VX_CONTEXT_MODULES

Queries the context for the number of active modules. Read-only. Use a vx_uint32 parameter.

VX_CONTEXT_REFERENCES

Queries the context for the number of active references. Read-only. Use a vx_uint32 parameter.

VX_CONTEXT_IMPLEMENTATION

Queries the context for it's implementation name. Read-only. Use a vx_char[VX_MAX_IMPLEMENTATION_NAME] array.

VX_CONTEXT_EXTENSIONS_SIZE

Queries the number of bytes in the extensions string. Read-only. Use a vx_size parameter.

VX_CONTEXT_EXTENSIONS

Retrieves the extensions string. Read-only. This is a space-separated string of extension names. Each OpenVX official extension has a unique identifier, comprised of capital letters, numbers and the underscore character, prefixed with "KHR_", for example "KHR_NEW_FEATURE". Use a vx_char pointer allocated to the size returned from VX_CONTEXT_EXTENSIONS_SIZE.

VX_CONTEXT_CONVOLUTION_MAX_DIMENSION

The maximum width or height of a convolution matrix. Read-only. Use a vx_size parameter. Each vendor must support centered kernels of size w X h, where both w and h are odd numbers, 3 <= w <= n and 3 <= h <= n, where n is the value of the VX_CONTEXT_CONVOLUTION_MAX_DIMENSION attribute. n is an odd number that should not be smaller than 9. w and h may or may not be equal to each other. All combinations of w and h meeting the conditions above must be supported. The behavior of vxCreateConvolution is undefined for values larger than the value returned by this attribute.

VX_CONTEXT_OPTICAL_FLOW_MAX_WINDOW_DIMENSION

The maximum window dimension of the OpticalFlowPyrLK kernel. The value of this attribute shall be equal to or greater than '9'.

VX_KERNEL_OPTICAL_FLOW_PYR_LK. Read-only. Use a vx_size parameter.
VX_CONTEXT_IMMEDIATE_BORDER

The border mode for immediate mode functions.

Graph mode functions are unaffected by this attribute. Read-write. Use a pointer to a vx_border_t structure as parameter.

Note
The assumed default value for immediate mode functions is VX_BORDER_UNDEFINED.
VX_CONTEXT_UNIQUE_KERNEL_TABLE

Returns the table of all unique the kernels that exist in the context. Read-only. Use a vx_kernel_info_t array.

Precondition
You must call vxQueryContext with VX_CONTEXT_UNIQUE_KERNELS to compute the necessary size of the array.
VX_CONTEXT_IMMEDIATE_BORDER_POLICY

The unsupported border mode policy for immediate mode functions. Read-only.

Graph mode functions are unaffected by this attribute. Use a vx_enum as parameter.

Note
The assumed default value for immediate mode functions is VX_BORDER_POLICY_DEFAULT_TO_UNDEFINED.
VX_CONTEXT_NONLINEAR_MAX_DIMENSION

The dimension of the largest nonlinear filter supported. See vxNonLinearFilterNode.

The implementation must support all dimensions (height or width, not necessarily the same) up to the value of this attribute. The lowest value that must be supported for this attribute is 9. Read-only. Use a vx_size parameter.

Definition at line 766 of file vx_types.h.

 enum vx_memory_type_e

An enumeration of memory import types.

Enumerator
VX_MEMORY_TYPE_NONE

For memory allocated through OpenVX, this is the import type.

VX_MEMORY_TYPE_HOST

The default memory type to import from the Host.

Definition at line 1139 of file vx_types.h.

The termination criteria list.

Optical Flow Pyramid (LK)
Enumerator
VX_TERM_CRITERIA_ITERATIONS

Indicates a termination after a set number of iterations.

VX_TERM_CRITERIA_EPSILON

Indicates a termination after matching against the value of eplison provided to the function.

VX_TERM_CRITERIA_BOTH

Indicates that both an iterations and eplison method are employed. Whichever one matches first causes the termination.

Definition at line 1278 of file vx_types.h.

 enum vx_accessor_e

The memory accessor hint flags. These enumeration values are used to indicate desired system behavior, not the User intent. For example: these can be interpretted as hints to the system about cache operations or marshalling operations.

Enumerator

The memory shall be treated by the system as if it were read-only. If the User writes to this memory, the results are implementation defined.

VX_WRITE_ONLY

The memory shall be treated by the system as if it were write-only. If the User reads from this memory, the results are implementation defined.

The memory shall be treated by the system as if it were readable and writeable.

Definition at line 1316 of file vx_types.h.

 enum vx_round_policy_e

The Round Policy Enumeration.

Enumerator
VX_ROUND_POLICY_TO_ZERO

When scaling, this truncates the least significant values that are lost in operations.

VX_ROUND_POLICY_TO_NEAREST_EVEN

When scaling, this rounds to nearest even output value.

Definition at line 1333 of file vx_types.h.

## Function Documentation

 vx_context VX_API_CALL vxCreateContext ( )

Creates a vx_context.

This creates a top-level object context for OpenVX.

Note
This is required to do anything else.
Returns
The reference to the implementation context vx_context. Any possible errors preventing a successful creation should be checked using vxGetStatus.
Postcondition
vxReleaseContext
 vx_status VX_API_CALL vxReleaseContext ( vx_context * context )

Releases the OpenVX object context.

All reference counted objects are garbage-collected by the return of this call. No calls are possible using the parameter context after the context has been released until a new reference from vxCreateContext is returned. All outstanding references to OpenVX objects from this context are invalid after this call.

Parameters
 [in] context The pointer to the reference to the context.
Postcondition
After returning from this function the reference is zeroed.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_ERROR_INVALID_REFERENCE If context is not a vx_context.
Precondition
vxCreateContext
 vx_context VX_API_CALL vxGetContext ( vx_reference reference )

Retrieves the context from any reference from within a context.

Parameters
 [in] reference The reference from which to extract the context.
Returns
The overall context that created the particular reference. Any possible errors preventing a successful creation should be checked using vxGetStatus.
 vx_status VX_API_CALL vxQueryContext ( vx_context context, vx_enum attribute, void * ptr, vx_size size )

Queries the context for some specific information.

Parameters
 [in] context The reference to the context. [in] attribute The attribute to query. Use a vx_context_attribute_e. [out] ptr The location at which to store the resulting value. [in] size The size in bytes of the container to which ptr points.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_ERROR_INVALID_REFERENCE If the context is not a vx_context. VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect. VX_ERROR_NOT_SUPPORTED If the attribute is not supported on this implementation.
 vx_status VX_API_CALL vxSetContextAttribute ( vx_context context, vx_enum attribute, const void * ptr, vx_size size )

Sets an attribute on the context.

Parameters
 [in] context The handle to the overall context. [in] attribute The attribute to set from vx_context_attribute_e. [in] ptr The pointer to the data to which to set the attribute. [in] size The size in bytes of the data to which ptr points.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_ERROR_INVALID_REFERENCE If the context is not a vx_context. VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect. VX_ERROR_NOT_SUPPORTED If the attribute is not settable.
 vx_status VX_API_CALL vxSetImmediateModeTarget ( vx_context context, vx_enum target_enum, const char * target_string )

Sets the default target of the immediate mode. Upon successful execution of this function any future execution of immediate mode function is attempted on the new default target of the context.

Parameters
 [in] context The reference to the implementation context. [in] target_enum The default immediate mode target enum to be set to the vx_context object. Use a vx_target_e. [in] target_string The target name ASCII string. This contains a valid value when target_enum is set to VX_TARGET_STRING, otherwise it is ignored.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS Default target set. VX_ERROR_INVALID_REFERENCE If the context is not a vx_context. VX_ERROR_NOT_SUPPORTED If the specified target is not supported in this context.