The OpenVX Pipelining, Streaming and Batch Processing extension API. More...

#include <VX/vx.h>

Data Structures
struct	vx_graph_parameter_queue_params_t
	Queueing parameters for a specific graph parameter. More...

struct	vx_graph_parameter_config_t
	Details for a specific graph parameter. More...

struct	vx_event_graph_parameter_consumed
	Parameter structure returned with event of type VX_EVENT_GRAPH_PARAMETER_CONSUMED. More...

struct	vx_event_graph_completed
	Parameter structure returned with event of type VX_EVENT_GRAPH_COMPLETED. More...

struct	vx_event_node_completed
	Parameter structure returned with event of type VX_EVENT_NODE_COMPLETED. More...

struct	vx_event_node_error
	Parameter structure returned with event of type VX_EVENT_NODE_ERROR. More...

struct	vx_event_user_event
	Parameter structure returned with event of type VX_EVENT_USER_EVENT. More...

union	vx_event_info_t
	Parameter structure associated with an event. Depends on type of the event. More...

struct	vx_event_t
	Data structure which holds event information. More...

struct	vx_kernel_parameter_config_t
	This data structure is used to return information about kernel parameters via the vxGetKernelParameterConfig API. More...

Macros
#define	VX_LIBRARY_KHR_PIPELINING_EXTENSION (0x1)
	The Pipelining, Streaming and Batch Processing Extension Library Set.

Enumerations
enum	vx_graph_schedule_mode_enum_e { VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE = 0x21 }
	Extra enums. More...

enum	vx_graph_schedule_mode_type_e { VX_GRAPH_SCHEDULE_MODE_NORMAL = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE) + 0x0, VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE) + 0x1, VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE) + 0x2 }
	Type of graph scheduling mode. More...

enum	vx_graph_attribute_pipelining_e { VX_GRAPH_SCHEDULE_MODE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_GRAPH) + 0x5, VX_GRAPH_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_GRAPH) + 0x6, VX_GRAPH_EVENT_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_GRAPH) + 0x7, VX_GRAPH_PIPELINE_DEPTH = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_GRAPH) + 0x8 }
	The graph attributes added by this extension. More...

enum	vx_reference_attribute_pipelining_e { VX_REFERENCE_ENQUEUE_COUNT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_REFERENCE) + 0x3 }
	The reference attributes added by this extension. More...

enum	vx_event_enum_e { VX_ENUM_EVENT_TYPE = 0x22 }
	Extra type enum. More...

enum	vx_context_attribute_event_e { VX_CONTEXT_EVENT_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_CONTEXT) + 0x10 }
	The context attribute added by this extension. More...

enum	vx_event_type_e { VX_EVENT_GRAPH_PARAMETER_CONSUMED = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_EVENT_TYPE) + 0x0, VX_EVENT_GRAPH_COMPLETED = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_EVENT_TYPE) + 0x1, VX_EVENT_NODE_COMPLETED = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_EVENT_TYPE) + 0x2, VX_EVENT_NODE_ERROR = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_EVENT_TYPE) + 0x3, VX_EVENT_USER = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_EVENT_TYPE) + 0x4 }
	Type of event that can be generated during system execution. More...

enum	vx_node_state_enum_e { VX_ENUM_NODE_STATE_TYPE = 0x23 }
	Extra enums. More...

enum	vx_node_state_e { VX_NODE_STATE_STEADY = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_NODE_STATE_TYPE) + 0x0, VX_NODE_STATE_PIPEUP = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_NODE_STATE_TYPE) + 0x1 }
	Node state. More...

enum	vx_node_attribute_streaming_e { VX_NODE_STATE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0x9 }
	The node attributes added by this extension. More...

enum	vx_kernel_attribute_streaming_e { VX_KERNEL_PIPEUP_OUTPUT_DEPTH = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0x4, VX_KERNEL_PIPEUP_INPUT_DEPTH = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0x5 }
	The kernel attributes added by this extension. More...

Functions
VX_API_ENTRY vx_status VX_API_CALL	vxSetGraphScheduleConfig (vx_graph graph, vx_enum graph_schedule_mode, vx_uint32 graph_parameters_list_size, const vx_graph_parameter_queue_params_t graph_parameters_queue_params_list[])
	Sets the graph scheduler config. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGetGraphParameterRefsList (vx_graph graph, vx_uint32 param, vx_uint32 ref_list_size, vx_reference refs_list[])
	Returns the list of references allowed for queueing on a particular graph parameter. More...

VX_API_ENTRY vx_status VX_API_CALL	vxAddReferencesToGraphParameterList (vx_graph graph, vx_uint32 graph_parameter_index, vx_uint32 number_to_add, const vx_reference new_references[])
	Allows more references to be added to the list of references that may be queued on a graph parameter. This functionality allows more references to be added to those already defined by the call to vxSetGraphScheduleConfig. The function may only be called after graph verification. References in the list should be checked for compatibility so that the graphs are guaranteed to run. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGraphParameterEnqueueReadyRef (vx_graph graph, vx_uint32 graph_parameter_index, const vx_reference *refs, vx_uint32 num_refs)
	Enqueues new references into a graph parameter for processing. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGraphParameterDequeueDoneRef (vx_graph graph, vx_uint32 graph_parameter_index, vx_reference refs, vx_uint32 max_refs, vx_uint32 num_refs)
	Dequeues 'consumed' references from a graph parameter. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGraphParameterCheckDoneRef (vx_graph graph, vx_uint32 graph_parameter_index, vx_uint32 *num_refs)
	Checks and returns the number of references that are ready for dequeue. More...

VX_API_ENTRY vx_status VX_API_CALL	vxWaitEvent (vx_context context, vx_event_t *event, vx_bool do_not_block)
	Wait for a single event. More...

VX_API_ENTRY vx_status VX_API_CALL	vxEnableEvents (vx_context context)
	Enable event generation. More...

VX_API_ENTRY vx_status VX_API_CALL	vxDisableEvents (vx_context context)
	Disable event generation. More...

VX_API_ENTRY vx_status VX_API_CALL	vxSendUserEvent (vx_context context, vx_uint32 app_value, const void *parameter)
	Generate user defined event. More...

VX_API_ENTRY vx_status VX_API_CALL	vxRegisterEvent (vx_reference ref, enum vx_event_type_e type, vx_uint32 param, vx_uint32 app_value)
	Register an event to be generated. More...

VX_API_ENTRY vx_status VX_API_CALL	vxRegisterGraphEvent (vx_reference graph_or_node, enum vx_event_type_e type, vx_uint32 param, vx_uint32 app_value)
	Registers an event for a specific graph. More...

VX_API_ENTRY vx_status VX_API_CALL	vxWaitGraphEvent (vx_graph graph, vx_event_t *event, vx_bool do_not_block)
	Waits for an event from a specific graph. More...

VX_API_ENTRY vx_status VX_API_CALL	vxEnableGraphEvents (vx_graph graph)
	Enables events from a specific graph. More...

VX_API_ENTRY vx_status VX_API_CALL	vxDisableGraphEvents (vx_graph graph)
	Disables events from a specific graph. More...

VX_API_ENTRY vx_status VX_API_CALL	vxSendUserGraphEvent (vx_graph graph, vx_uint32 app_value, const void *parameter)
	Generate user defined graph event. More...

VX_API_ENTRY vx_status VX_API_CALL	vxEnableGraphStreaming (vx_graph graph, vx_node trigger_node)
	Enable streaming mode of graph execution. More...

VX_API_ENTRY vx_status VX_API_CALL	vxStartGraphStreaming (vx_graph graph)
	Start streaming mode of graph execution. More...

VX_API_ENTRY vx_status VX_API_CALL	vxStopGraphStreaming (vx_graph graph)
	Stop streaming mode of graph execution. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGetKernelParameterConfig (vx_kernel kernel, vx_uint32 num_params, vx_kernel_parameter_config_t parameter_config[])
	Returns the kernel parameter configuration. More...

VX_API_ENTRY vx_status VX_API_CALL	vxGetGraphParameterConfig (vx_graph graph, vx_uint32 num_params, vx_graph_parameter_config_t parameter_config[])
	Returns the graph parameter configuration. More...

Detailed Description

The OpenVX Pipelining, Streaming and Batch Processing extension API.

Definition in file vx_khr_pipelining.h.

Enumeration Type Documentation

◆ vx_graph_schedule_mode_enum_e

enum vx_graph_schedule_mode_enum_e

Extra enums.

Enumerator
VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE	Graph schedule mode type enumeration.

Definition at line 50 of file vx_khr_pipelining.h.

◆ vx_graph_schedule_mode_type_e

enum vx_graph_schedule_mode_type_e

Type of graph scheduling mode.

See vxSetGraphScheduleConfig and vxGraphParameterEnqueueReadyRef for details about each mode.

Enumerator
VX_GRAPH_SCHEDULE_MODE_NORMAL	Schedule graph in non-queueing mode.
VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO	Schedule graph in queueing mode with auto scheduling.
VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL	Schedule graph in queueing mode with manual scheduling.

Definition at line 61 of file vx_khr_pipelining.h.

◆ vx_graph_attribute_pipelining_e

enum vx_graph_attribute_pipelining_e

The graph attributes added by this extension.

Enumerator
VX_GRAPH_SCHEDULE_MODE	Returns the schedule mode of a graph. Read-only. Use a `vx_enum` parameter. See `vx_graph_schedule_mode_type_e` enum.
VX_GRAPH_TIMEOUT	Sets or returns the timeout value, in milliseconds, for the functions `vxWaitGraph`, `vxProcessGraph`, `vxGraphParameterDequeueDoneRef`, and `vxStopGraphStreaming`. Read-write. Use a `vx_uint32` parameter, or the implementation-defined `VX_TIMEOUT_WAIT_FOREVER`. The implementation shall initially set this attribute to `VX_TIMEOUT_WAIT_FOREVER`. Note Setting the timeout attribute `VX_GRAPH_TIMEOUT` does not set any limit upon the duration of graph execution, it merely prevents the above-mentioned functions from delaying more than the time given. There are no other requirements upon what the framework should do; it is up to the application to recognise the timeout and take appropriate action.
VX_GRAPH_EVENT_TIMEOUT	Sets or returns the timeout value, in milliseconds, for the function: `vxWaitGraphEvent`. Read-write. Use a `vx_uint32` parameter, or the implementation-defined `VX_TIMEOUT_WAIT_FOREVER`. The implementation shall initially set this attribute to `VX_TIMEOUT_WAIT_FOREVER`. Note Setting timeout attributes does not in any way change the occurrence of events, it merely prevents the above-mentioned functions from delaying more than the time given. There are no other requirements upon what the framework should do; it is up to the application to recognise the timeout and take appropriate action.
VX_GRAPH_PIPELINE_DEPTH	Set or return the graph pipeline depth; the depth used in the graph is known after graph verification. Read-write. Us a `vx_uint32` parameter. Note The framework will calculate the maximum depth of pipeline that is sensible for any given graph. It would be useful for the user to be able to obtain this data in a programmatic way and modify execution accordingly, for example to know that result dequeuing is possible after queuing a certain number of inputs. An additional attribute allows this data to be obtained from a verified graph. The attribute is made read-write, so that an application may modify pipeline behaviour. Example use cases are to save memory by restricting pipeline depth, or to effectively turn off pipelining by setting the depth to 1 for debugging purposes. If the attribute is set to a non-zero value before graph verification, the application-supplied value will be used, otherwise the value will be calculated by the framework.

Definition at line 79 of file vx_khr_pipelining.h.

◆ vx_reference_attribute_pipelining_e

enum vx_reference_attribute_pipelining_e

The reference attributes added by this extension.

Enumerator

VX_REFERENCE_ENQUEUE_COUNT

Query the number of times this reference has been enqueued; Read-only. Use a vx_uint32 parameter.

Note This attribute is provided so that an application may better manage its use of references; the specification does not require that an implementation prevents an application from queueing references on both inputs of one graph and an output of another although this may lead to unexpected results.

Definition at line 131 of file vx_khr_pipelining.h.

◆ vx_event_enum_e

enum vx_event_enum_e

Extra type enum.

Enumerator
VX_ENUM_EVENT_TYPE	Event Type enumeration.

Definition at line 481 of file vx_khr_pipelining.h.

◆ vx_context_attribute_event_e

enum vx_context_attribute_event_e

The context attribute added by this extension.

Enumerator

VX_CONTEXT_EVENT_TIMEOUT

Sets or returns the timeout value, in milliseconds, for the function: vxWaitEvent. Read-write. Use a vx_uint32 parameter, or the implementation-defined VX_TIMEOUT_WAIT_FOREVER. The implementation shall initially set this attribute to VX_TIMEOUT_WAIT_FOREVER.

Note: Setting timeout attributes does not in any way change the occurrence of events, it merely prevents the above-mentioned functions from delaying more than the time given. There are no other requirements upon what the framework should do; it is up to the application to recognise the timeout and take appropriate action.

Definition at line 489 of file vx_khr_pipelining.h.

◆ vx_event_type_e

enum vx_event_type_e

Type of event that can be generated during system execution.

Enumerator
VX_EVENT_GRAPH_PARAMETER_CONSUMED	Graph parameter consumed event. This event is generated when a data reference at a graph parameter is consumed during a graph execution. It is used to indicate that a given data reference is no longer used by the graph and can be dequeued and accessed by the application. Note Graph execution could still be "in progress" for rest of the graph that does not use this data reference.
VX_EVENT_GRAPH_COMPLETED	Graph completion event. This event is generated every time a graph execution completes. Graph completion event is generated for both successful execution of a graph or abandoned execution of a graph.
VX_EVENT_NODE_COMPLETED	Node completion event. This event is generated every time a node within a graph completes execution.
VX_EVENT_NODE_ERROR	Node error event. This event is generated every time a node returns error within a graph.
VX_EVENT_USER	User defined event. This event is generated by user application outside of OpenVX framework using the vxSendUserEvent API. User events allow application to have single centralized 'wait-for' loop to handle both framework generated events as well as user generated events. Note Since the application initiates user events and not the framework, the application does NOT register user events using vxRegisterEvent.

Definition at line 504 of file vx_khr_pipelining.h.

◆ vx_node_state_enum_e

enum vx_node_state_enum_e

Extra enums.

Enumerator
VX_ENUM_NODE_STATE_TYPE	Node state type enumeration.

Definition at line 841 of file vx_khr_pipelining.h.

◆ vx_node_state_e

enum vx_node_state_e

Node state.

Enumerator
VX_NODE_STATE_STEADY	Node is in steady state (output expected for each invocation)
VX_NODE_STATE_PIPEUP	Node is in pipeup state (output not expected for each invocation)

Definition at line 850 of file vx_khr_pipelining.h.

◆ vx_node_attribute_streaming_e

enum vx_node_attribute_streaming_e

The node attributes added by this extension.

Enumerator
VX_NODE_STATE	Queries the state of the node. Read-only. See `vx_graph_state_e` enum.

Definition at line 865 of file vx_khr_pipelining.h.

◆ vx_kernel_attribute_streaming_e

enum vx_kernel_attribute_streaming_e

The kernel attributes added by this extension.

Enumerator

VX_KERNEL_PIPEUP_OUTPUT_DEPTH

The pipeup output depth required by the kernel. This is called by kernels that need to be primed with multiple output buffers before it can begin to return them. A typical use case for this is a source node which needs to provide and retain multiple empty buffers to a camera driver to fill. The first time the graph is executed after vxVerifyGraph is called, the framework calls the node associated with this kernel (pipeup_output_depth - 1) times before 'expecting' a valid output and calling downstream nodes. During this PIPEUP state, the framework provides the same set of input parameters for each call, but provides different set of output parameters for each call. During the STEADY state, the kernel may return a different set of output parameters than was given during the execution callback. Read-write. Can be written only before user-kernel finalization. Use a vx_uint32 parameter.

Note: If not set, it will default to 1.; Setting a value less than 1 shall return VX_ERROR_INVALID_PARAMETERS

VX_KERNEL_PIPEUP_INPUT_DEPTH

The pipeup input depth required by the kernel. This is called by kernels that need to retain one or more input buffers before it can begin to return them. A typical use case for this is a sink node which needs to provide and retain one or more filled buffers to a display driver to display. The first (pipeup_input_depth - 1) times the graph is executed after vxVerifyGraph is called, the framework calls the node associated with this kernel without 'expecting' an input to have been consumed and returned by the node. During this PIPEUP state, the framework does not reuse any of the input buffers it had given to this node. During the STEADY state, the kernel may return a different set of input parameters than was given during the execution callback. Read-write. Can be written only before user-kernel finalization. Use a vx_uint32 parameter.

Note: If not set, it will default to 1.; Setting a value less than 1 shall return VX_ERROR_INVALID_PARAMETERS

Definition at line 873 of file vx_khr_pipelining.h.

Function Documentation

◆ vxSetGraphScheduleConfig()

VX_API_ENTRY vx_status VX_API_CALL vxSetGraphScheduleConfig	(	vx_graph	graph,
		vx_enum	graph_schedule_mode,
		vx_uint32	graph_parameters_list_size,
		const vx_graph_parameter_queue_params_t	graph_parameters_queue_params_list[]
	)

Sets the graph scheduler config.

This API is used to set the graph scheduler config to allow user to schedule multiple instances of a graph for execution.

For legacy applications that don't need graph pipelining or batch processing, this API need not be used.

Using this API, the application specifies the graph schedule mode, as well as queueing parameters for all graph parameters that need to allow enqueueing of references. A single monolithic API is provided instead of discrete APIs, since this allows the implementation to get all information related to scheduling in one shot and then optimize the subsequent graph scheduling based on this information. This API MUST be called before graph verify since in this case it allows implementations the opportunity to optimize resources based on information provided by the application.

'graph_schedule_mode' selects how input and output references are provided to a graph and how the next graph schedule is triggered by an implementation.

Below scheduling modes are supported:

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO:

Application needs to explicitly call vxVerifyGraph before enqueing data references
Application should not call vxScheduleGraph or vxProcessGraph
When enough references are enqueued at various graph parameters, the implementation could trigger the next graph schedule.
Here, not all graph parameters need to have enqueued references for a graph schedule to begin. An implementation is expected to execute the graph as much as possible until a enqueued reference is not available at which time it will stall the graph until the reference becomes available. This allows application to schedule a graph even when all parameters references are not yet available, i.e do a 'late' enqueue. However, exact behaviour is implementation specific.

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL:

Application needs to explicitly call vxScheduleGraph
Application should not call vxProcessGraph
References for all graph parameters of the graph needs to enqueued before vxScheduleGraph is called on the graph else an error is returned by vxScheduleGraph
Application can enqueue multiple references at the same graph parameter. When vxScheduleGraph is called, all enqueued references get processed in a 'batch'.
User can use vxWaitGraph to wait for the previous vxScheduleGraph to complete.

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_NORMAL:

'graph_parameters_list_size' MUST be 0 and
'graph_parameters_queue_params_list' MUST be NULL
This mode is equivalent to non-queueing scheduling mode as defined by OpenVX v1.2 and earlier.

By default all graphs are in VX_GRAPH_SCHEDULE_MODE_NORMAL mode until this API is called.

'graph_parameters_queue_params_list' allows to specify below information:

For the graph parameter index that is specified, it enables queueing mode of operation
Further it allows the application to specify the list of references that it could later enqueue at this graph parameter.

For graph parameters listed in 'graph_parameters_queue_params_list', application MUST use vxGraphParameterEnqueueReadyRef to set references at the graph parameter. Using other data access API's on these parameters or corresponding data objects will return an error. For graph parameters not listed in 'graph_parameters_queue_params_list' application MUST use the vxSetGraphParameterByIndex to set the reference at the graph parameter. Using other data access API's on these parameters or corresponding data objects will return an error.

This API also allows application to provide a list of references which could be later enqueued at the graph parameter. This allows implementation to do meta-data checking up front rather than during each reference enqueue.

The function vxSetGraphScheduleConfig should be called only before calling vxVerifyGraph, and the refs_list field should not be null. The implementation shall check for this.

The schedule configuration must include all graph parameters even if the intention is not to queue some of them. If any graph parameters had been added already when vxSetGraphScheduleConfig is called, they are removed and replaced with the new list. Additionally, this function is responsible for adding parameters to the graph, identifying them using the first reference in the list of references supplied for each graph parameter. The following rules apply to the list of references given: The first reference given in the list must be attached to at least one node parameter in the graph A reference may not appear as the first reference in more than one list The first reference in a list may not be NULL If a NULL reference is otherwise specified in the list, the results are implementation-dependent References in the list should be checked for compatibility so that the graphs are guaranteed to run (for example, all references may need to have the same metadata). Note that implementations may allow references of different types if connected nodes (and nodes subsequently connected to those nodes) allow a generic VX_TYPE_REFERENCE as the type. Where VX_BIDIRECTIONAL parameters are used, the direction of the graph parameter may not be the same as the direction of the parameter given on the last node to write data, due to the rules for execution precedence. The rules for direction reported in data obtained by vxGetGraphParameterConfig may differ and are given according to the connections of the reference in the following table: | Reference connection | Direction of the graph parameter | VX_INPUT only | VX_INPUT | VX_OUTPUT only | VX_OUTPUT | VX_OUTPUT & VX_INPUT(s) | VX_OUTPUT | VX_BIDIRECTIONAL only | VX_BIDIRECTIONAL | VX_BIDIRECTIONAL & VX_INPUT(s) | VX_BIDIRECTIONAL | VX_BIDIRECTIONAL & VX_OUTPUT | VX_OUTPUT | VX_BIDIRECTIONAL, VX_OUTPUT & VX_INPUT(s) | VX_OUTPUT

Note A reference will not become ready for dequeuing until all nodes to which it is attached have executed, hence a VX_OUTPUT graph parameter will become available after the execution of any node to which it is connected as a VX_BIDIRECTIONAL or VX_INPUT parameter. The graph_parameter_index given in the array of structures must be unique and must be less than the number of graph parameters required.

Parameters

[in]	graph	Graph reference
[in]	graph_schedule_mode	Graph schedule mode. See `vx_graph_schedule_mode_type_e`
[in]	graph_parameters_list_size	Number of elements in graph_parameters_queue_params_list
[in]	graph_parameters_queue_params_list	Array containing queuing properties at graph parameters that need to support queueing.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	Invalid graph parameter queueing parameters
VX_FAILURE	Any other failure.

◆ vxGetGraphParameterRefsList()

VX_API_ENTRY vx_status VX_API_CALL vxGetGraphParameterRefsList	(	vx_graph	graph,
		vx_uint32	param,
		vx_uint32	ref_list_size,
		vx_reference	refs_list[]
	)

Returns the list of references allowed for queueing on a particular graph parameter.

The function is intended to return data after a graph has been verified; if the function is called before a graph is verified, the results are not defined. The order of the references is the order given originally in the call to vxSetGraphScheduleConfig and any subsequent calls to vxAddReferencesToGraphParameterList. If in the meantime the graph has been exported and imported, the references given will be those either created by the framework or supplied by the application in place of the originals. If the references were not explicitly exported (and so not explicitly imported), then this function is required to obtain them. References obtained in this way must be released when they are no longer required. Application developers using multi-threading may encounter data races if vxAddReferencesToGraphParameterList is called on a different thread.

Parameters

[in]	graph	The verified graph to query
[in]	param	the index of the graph parameter, which must be less than the number of parameters in the graph, returned by querying the graph for the attribute VX_GRAPH_NUMPARAMETERS. If the value is incorrect, the function will return VX_ERROR_INVALID_PARAMETERS.
[in]	ref_list_size	must be valid, equal to the number returned by vxGetGraphParameterConfig for the parameter in question.
[out]	refs_list	must be an array of ref_list_size references to accept the data returned.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_GRAPH	The graph was invalid or not verified
VX_ERROR_INVALID_PARAMETERS	The graph parameter index is out of range, the size of the list is incorrect, or a NULL pointer was passed for refs_list.

◆ vxAddReferencesToGraphParameterList()

VX_API_ENTRY vx_status VX_API_CALL vxAddReferencesToGraphParameterList	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_uint32	number_to_add,
		const vx_reference	new_references[]
	)

Allows more references to be added to the list of references that may be queued on a graph parameter. This functionality allows more references to be added to those already defined by the call to vxSetGraphScheduleConfig. The function may only be called after graph verification. References in the list should be checked for compatibility so that the graphs are guaranteed to run.

Parameters

[in]	graph	- the graph whose parameter reference list is to be extended
[in]	graph_parameter_index	- index of the affected graph parameter. Must be less than the number of parameters in this graph.
[in]	number_to_add	- the number of new references to be added. Must be greater than zero.
[in]	number_to_add	- the number of new references to be added. Must be greater than zero.
[in]	new_references	- array holding the new references, must be same length as "number_to_add". There may be an implementation-dependent limit on the total number of references per graph parameter.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	- No errors.
VX_ERROR_INVALID_GRAPH	The graph was invalid or not verified
VX_ERROR_INVALID_SCOPE	One of the references is owned by another graph or context
VX_ERROR_INVALID_REFERENCE	One of the references is not valid
VX_ERROR_INVALID_TYPE	A reference does not have the same type or other metadata as expected for this parameter
VX_ERROR_INVALID_FORMAT	A reference format does not match those expected for this parameter
VX_ERROR_INVALID_DIMENSION	A reference dimension does not match that expected for this parameter
VX_ERROR_INVALID_PARAMETERS	The graph parameter index is out of range or the size of the list is zero.
VX_ERROR_NO_RESOURCES	The operation could not be completed because of a resource limit, for example a limit on the total number of references per graph parameter or per graph.

◆ vxGraphParameterEnqueueReadyRef()

VX_API_ENTRY vx_status VX_API_CALL vxGraphParameterEnqueueReadyRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		const vx_reference *	refs,
		vx_uint32	num_refs
	)

Enqueues new references into a graph parameter for processing.

This new reference will take effect on the next graph schedule.

In case of a graph parameter which is input to a graph, this function provides a data reference with new input data to the graph. In case of a graph parameter which is not input to a graph, this function provides a 'empty' reference into which a graph execution can write new data into.

This function essentially transfers ownership of the reference from the application to the graph, subject to how it is used. A reference may be enqueued on either and only: ONE OUTPUT parameter, or ONE BIDIRECTIONAL parameter, or ONE OR MORE INPUT parameters.

Consequently, the application must ensure that no access to a reference is made whilst it is queued on a graph parameter except to enqueue it to an additional input parameter; extra precautions may have to be taken if more than one thread is involved. The attribute <<VX_REFERENCE_ENQUEUE_COUNT>> may assist with this. For example, the application should not attempt to use it as an argument to any immediate mode (vxu), mapping, copying or attribute setting function when this attribute has a non-zero value.

User MUST use <<vxGraphParameterDequeueDoneRef>> to get back the processed or consumed references. The references that are enqueued MUST be the references listed by calling vxSetGraphScheduleConfig before graph verification or subsequently added by using vxAddReferencesToGraphParameterList. If a reference outside this list is provided then behaviour is undefined.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[in]	refs	The array of references to enqueue into the graph parameter
[in]	num_refs	Number of references to enqueue

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference OR reference is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Reference could not be enqueued.

◆ vxGraphParameterDequeueDoneRef()

VX_API_ENTRY vx_status VX_API_CALL vxGraphParameterDequeueDoneRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_reference *	refs,
		vx_uint32	max_refs,
		vx_uint32 *	num_refs
	)

Dequeues 'consumed' references from a graph parameter.

This function dequeues references from a graph parameter of a graph. The reference that is dequeued is a reference that had been previously enqueued into a graph, and after subsequent graph execution is considered as processed or consumed by the graph. This function essentially transfers ownership of the reference from the graph to the application.

IMPORTANT : This API will block until at least one reference is dequeued.

In case of a graph parameter which is input to a graph, this function provides a 'consumed' buffer to the application so that new input data can filled and later enqueued to the graph. In case of a graph parameter which is not input to a graph, this function provides a reference filled with new data based on graph execution. User can then use this newly generated data with their application. Typically when this new data is consumed by the application the 'empty' reference is again enqueued to the graph.

This API returns an array of references up to a maximum of 'max_refs'. Application MUST ensure the array pointer ('refs') passed as input can hold 'max_refs'. 'num_refs' is actual number of references returned and will be <= 'max_refs'.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[out]	refs	Dequeued references filled in the array
[in]	max_refs	Max number of references to dequeue
[out]	num_refs	Actual number of references dequeued.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Reference could not be dequeued.
VX_ERROR_TIMEOUT	The attribute VX_GRAPH_TIMEOUT was not set to VX_TIMEOUT_WAIT_FOREVER and the function call has not returned after VX_GRAPH_TIMEOUT milliseconds. No event is received.

◆ vxGraphParameterCheckDoneRef()

VX_API_ENTRY vx_status VX_API_CALL vxGraphParameterCheckDoneRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_uint32 *	num_refs
	)

Checks and returns the number of references that are ready for dequeue.

This function checks the number of references that can be dequeued and returns the value to the application.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[out]	num_refs	Number of references that can be dequeued using `vxGraphParameterDequeueDoneRef`

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Any other failure.

◆ vxWaitEvent()

VX_API_ENTRY vx_status VX_API_CALL vxWaitEvent	(	vx_context	context,
		vx_event_t *	event,
		vx_bool	do_not_block
	)

Wait for a single event.

After vxDisableEvents is called, if vxWaitEvent(.. ,.. , vx_false_e) is called, vxWaitEvent will remain blocked until events are re-enabled using vxEnableEvents and a new event is received.

If vxReleaseContext is called while an application is blocked on vxWaitEvent , the behavior is not defined by OpenVX.

If vxWaitEvent is called simultaneously from multiple thread/task contexts then its behaviour is not defined by OpenVX.

Parameters

context	[in] OpenVX context
event	[out] Data structure which holds information about a received event
do_not_block	[in] When value is vx_true_e API does not block and only checks for the condition

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	Event received and event information available in 'event'
VX_FAILURE	No event is received
VX_ERROR_TIMEOUT	The attribute VX_CONTEXT_EVENT_TIMEOUT was not set to VX_TIMEOUT_WAIT_FOREVER and the function call has not returned after VX_CONTEXT_EVENT_TIMEOUT milliseconds. No event is received.

◆ vxEnableEvents()

VX_API_ENTRY vx_status VX_API_CALL vxEnableEvents ( vx_context context )

Enable event generation.

Depending on the implementation, events may be either enabled or disabled by default.

Parameters

context [in] OpenVX context

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS No errors; any other value indicates failure.

◆ vxDisableEvents()

VX_API_ENTRY vx_status VX_API_CALL vxDisableEvents ( vx_context context )

Disable event generation.

When events are disabled, any event generated before this API is called will still be returned via vxWaitEvent API. However no additional events would be returned via vxWaitEvent API until events are enabled again.

Parameters

context [in] OpenVX context

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS No errors; any other value indicates failure.

◆ vxSendUserEvent()

VX_API_ENTRY vx_status VX_API_CALL vxSendUserEvent	(	vx_context	context,
		vx_uint32	app_value,
		const void *	parameter
	)

Generate user defined event.

Parameters

context	[in] OpenVX context
app_value	[in] Application-specified value that will be returned to user as part of vx_event_t.app_value NOT used by implementation.
parameter	[in] User defined event parameter. NOT used by implementation. Returned to user as part vx_event_t.event_info.user_event.user_event_parameter field

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS No errors; any other value indicates failure.

◆ vxRegisterEvent()

VX_API_ENTRY vx_status VX_API_CALL vxRegisterEvent	(	vx_reference	ref,
		enum vx_event_type_e	type,
		vx_uint32	param,
		vx_uint32	app_value
	)

Register an event to be generated.

Generation of event may need additional resources and overheads for an implementation. Hence events should be registered for references only when really required by an application.

This API can be called on graph, node or graph parameter. This API MUST be called before doing vxVerifyGraph for that graph.

Parameters

ref	[in] Reference which will generate the event
type	[in] Type or condition on which the event is generated
param	[in] Specifies the graph parameter index when type is VX_EVENT_GRAPH_PARAMETER_CONSUMED
app_value	[in] Application-specified value that will be returned to user as part of vx_event_t::app_value. NOT used by implementation.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	ref is not a valid `vx_reference` reference.
VX_ERROR_NOT_SUPPORTED	type is not valid for the provided reference.

◆ vxRegisterGraphEvent()

VX_API_ENTRY vx_status VX_API_CALL vxRegisterGraphEvent	(	vx_reference	graph_or_node,
		enum vx_event_type_e	type,
		vx_uint32	param,
		vx_uint32	app_value
	)

Registers an event for a specific graph.

Parameters

[in]	graph_or_node	the graph or node for which the event will be registered
[in]	type	only [VX_EVENT_GRAPH_PARAMETER_CONSUMED] and [VX_EVENT_GRAPH_COMPLETED] are supported if graph_or_node is a vx_graph, and [VX_EVENT_NODE_COMPLETED] or [VX_EVENT_NODE_ERROR] if graph_or_node is a vx_node
[in]	param	Specifies the graph parameter index when type is VX_EVENT_GRAPH_PARAMETER_CONSUMED
[in]	app_value	Application-specified value that will be returned to user as part of vx_event_t.app_value field. Stored by the implementation but not used for any other purpose.

Returns: a vx_status value.

Return values

VX_SUCCESS	the event was registered
VX_ERROR_NOT_SUPPORTED	type is not equal to [VX_EVENT_GRAPH_PARAMETER_CONSUMED], [VX_EVENT_GRAPH_COMPLETED], [VX_EVENT_NODE_COMPLETED] or [VX_EVENT_NODE_ERROR] or the graph is already verified.
VX_ERROR_INVALID_PARAMETERS	param out of range
VX_ERROR_INVALID_REFERENCE	graph_or_node is not a valid graph or node reference

It is not an error to call this twice for the same graph parameter; in that case the stored app_value will be updated. Notice that there is only one app_value per graph parameter.

◆ vxWaitGraphEvent()

VX_API_ENTRY vx_status VX_API_CALL vxWaitGraphEvent	(	vx_graph	graph,
		vx_event_t *	event,
		vx_bool	do_not_block
	)

Waits for an event from a specific graph.

Parameters

[in]	graph	the graph from which events are expected
[out]	event	pointer to a data structure that will hold information about the received event
[in]	do_not_block	When the value is vx_true_e the API does not block and only checks for the condition

Returns: a vx_status value.

Return values

VX_SUCCESS	an event was received
VX_FAILURE	no event was received
VX_ERROR_TIMEOUT	The attribute VX_GRAPH_EVENT_TIMEOUT was not set to VX_TIMEOUT_WAIT_FOREVER and the function call has not returned after VX_GRAPH_EVENT_TIMEOUT milliseconds. No event is received.
VX_ERROR_INVALID_REFERENCE	graph was not a valid graph reference or event was NULL

◆ vxEnableGraphEvents()

VX_API_ENTRY vx_status VX_API_CALL vxEnableGraphEvents ( vx_graph graph )

Enables events from a specific graph.

Parameters

[in] graph the graph for which events are to be enabled

Returns: a vx_status value.

Return values

VX_SUCCESS	events were enabled
VX_ERROR_INVALID_REFERENCE	graph was not a valid graph reference

◆ vxDisableGraphEvents()

VX_API_ENTRY vx_status VX_API_CALL vxDisableGraphEvents ( vx_graph graph )

Disables events from a specific graph.

Parameters

[in] graph the graph for which events are to be disabled

Returns: a vx_status value.

Return values

VX_SUCCESS	events were disabled
VX_ERROR_INVALID_REFERENCE	graph was not a valid graph reference

◆ vxSendUserGraphEvent()

VX_API_ENTRY vx_status VX_API_CALL vxSendUserGraphEvent	(	vx_graph	graph,
		vx_uint32	app_value,
		const void *	parameter
	)

Generate user defined graph event.

Parameters

graph	[in] Graph to whose queue the event will be sent
app_value	[in] Application-specified value that will be returned to user as part of vx_event_t.app_value NOT used by implementation.
parameter	[in] User defined event parameter. NOT used by implementation. Returned to user as part vx_event_t.event_info.user_event.user_event_parameter field

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS No errors; any other value indicates failure.

◆ vxEnableGraphStreaming()

VX_API_ENTRY vx_status VX_API_CALL vxEnableGraphStreaming	(	vx_graph	graph,
		vx_node	trigger_node
	)

Enable streaming mode of graph execution.

This API enables streaming mode of graph execution on the given graph. The node given on the API is set as the trigger node. A trigger node is defined as the node whose completion causes a new execution of the graph to be triggered.

Parameters

graph	[in] Reference to the graph to enable streaming mode of execution.
trigger_node	[in][optional] Reference to the node to be used for trigger node of the graph.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	graph is not a valid `vx_graph` reference

◆ vxStartGraphStreaming()

VX_API_ENTRY vx_status VX_API_CALL vxStartGraphStreaming ( vx_graph graph )

Start streaming mode of graph execution.

In streaming mode of graph execution, once an application starts graph execution further intervention of the application is not needed to re-schedule a graph; i.e. a graph re-schedules itself and executes continuously until streaming mode of execution is stopped.

When this API is called, the framework schedules the graph via vxScheduleGraph and returns. This graph gets re-scheduled continuously until vxStopGraphStreaming is called by the user or any of the graph nodes return error during execution.

The graph MUST be verified via vxVerifyGraph before calling this API. Also user application MUST ensure no previous executions of the graph are scheduled before calling this API.

After streaming mode of a graph has been started, a vxScheduleGraph should not be used on that graph by an application.

vxWaitGraph can be used as before to wait for all pending graph executions to complete.

Parameters

graph [in] Reference to the graph to start streaming mode of execution.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	graph is not a valid `vx_graph` reference.

◆ vxStopGraphStreaming()

VX_API_ENTRY vx_status VX_API_CALL vxStopGraphStreaming ( vx_graph graph )

Stop streaming mode of graph execution.

This function blocks until graph execution is gracefully stopped at a logical boundary, for example, when all internally scheduled graph executions are completed.

Parameters

graph [in] Reference to the graph to stop streaming mode of execution.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_FAILURE	Graph is not started in streaming execution mode.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference.
VX_ERROR_TIMEOUT	The attribute VX_GRAPH_TIMEOUT was not set to VX_TIMEOUT_WAIT_FOREVER and the function call has not returned after VX_GRAPH_TIMEOUT milliseconds. No event is received.

◆ vxGetKernelParameterConfig()

VX_API_ENTRY vx_status VX_API_CALL vxGetKernelParameterConfig	(	vx_kernel	kernel,
		vx_uint32	num_params,
		vx_kernel_parameter_config_t	parameter_config[]
	)

Returns the kernel parameter configuration.

This API is provided to give information in a more convenient way than is possible by obtaining parameter objects from a kernel and querying them. The meta format object (member meta of vx_kernel_parameter_config_t) may be returned so that graphs may be created using appropriate objects for imported kernels. If a meta format object is returned (i.e., meta is not NULL), it must be released using vxReleaseReference(vxCastRefFromMetaFormatP(&meta)), as there is no specific vxReleaseMetaFormat() function. An implementation is not required to return a meta format object for all or indeed any of the kernel parameters but if it does so it could allow an application to create graphs that can use different imported kernels in a dynamic fashion. When querying the meta format object the application should only query those attributes appropriate for the object type; c.f., vxQueryMetaFormatAttribute(), and The Kernel Import Extension to OpenVX 1.3. An application should check for non-null meta format objects and release them even if it does not support dynamic graph creation. The function is intended to return data after a kernel has been finalised; if the function is called before a kernel is finalised, the results are not defined.

Parameters

[in]	kernel	The kernel to query
[in]	num_params	The number of parameters required by the kernel, as returned by querying the kernel for the attribute VX_KERNEL_PARAMETERS. If the value is incorrect, the function will return VX_ERROR_INVALID_PARAMETERS
[out]	parameter_config	An array with the correct number of entries to store the returned data for all the parameters

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	The kernel was invalid or not finalised
VX_ERROR_INVALID_PARAMETERS	The number of parameters is incorrect, or a NULL pointer was passed for parameter_config

◆ vxGetGraphParameterConfig()

VX_API_ENTRY vx_status VX_API_CALL vxGetGraphParameterConfig	(	vx_graph	graph,
		vx_uint32	num_params,
		vx_graph_parameter_config_t	parameter_config[]
	)

Returns the graph parameter configuration.

This API is provided to give information in a more convenient way than is possible by obtaining parameter objects from a graph and querying them. The function is intended to return data after a graph has been verified. If the function is called before a graph is verified, the results are not defined. The number of references reported for each graph parameter will be the number of references originally supplied in the call to vxSetGraphScheduleConfig plus any references that have been added by calls to vxAddReferencesToGraphParameterList

Parameters

[in]	graph	The graph to query
[in]	num_params	the number of graph parameters in the graph, returned by querying the graph for the attribute VX_GRAPH_NUMPARAMETERS. If the value is incorrect, the function will return VX_ERROR_INVALID_PARAMETERS
[out]	parameter_config	An array with the correct number of entries to store the returned data for all the parameters.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_GRAPH	The graph was invalid or not verified
VX_ERROR_INVALID_PARAMETERS	The number of parameters is incorrect, or a NULL pointer was passed for parameter_config.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ vx_graph_schedule_mode_enum_e

◆ vx_graph_schedule_mode_type_e

◆ vx_graph_attribute_pipelining_e

◆ vx_reference_attribute_pipelining_e

◆ vx_event_enum_e

◆ vx_context_attribute_event_e

◆ vx_event_type_e

◆ vx_node_state_enum_e

◆ vx_node_state_e

◆ vx_node_attribute_streaming_e

◆ vx_kernel_attribute_streaming_e

Function Documentation

◆ vxSetGraphScheduleConfig()

◆ vxGetGraphParameterRefsList()

◆ vxAddReferencesToGraphParameterList()

◆ vxGraphParameterEnqueueReadyRef()

◆ vxGraphParameterDequeueDoneRef()

◆ vxGraphParameterCheckDoneRef()

◆ vxWaitEvent()

◆ vxEnableEvents()

◆ vxDisableEvents()

◆ vxSendUserEvent()

◆ vxRegisterEvent()

◆ vxRegisterGraphEvent()

◆ vxWaitGraphEvent()

◆ vxEnableGraphEvents()

◆ vxDisableGraphEvents()

◆ vxSendUserGraphEvent()

◆ vxEnableGraphStreaming()

◆ vxStartGraphStreaming()

◆ vxStopGraphStreaming()

◆ vxGetKernelParameterConfig()

◆ vxGetGraphParameterConfig()