TIOVX User Guide
|
The OpenVX Pipelining, Streaming and Batch Processing extension API. More...
#include <VX/vx.h>
Go to the source code of this file.
Data Structures | |
struct | vx_graph_parameter_queue_params_t |
Queueing parameters 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... | |
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 } |
The graph attributes added by this extension. More... | |
enum | vx_event_enum_e { VX_ENUM_EVENT_TYPE = 0x22 } |
Extra enums. 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 | vxGraphParameterEnqueueReadyRef (vx_graph graph, vx_uint32 graph_parameter_index, 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 | 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... | |
The OpenVX Pipelining, Streaming and Batch Processing extension API.
Definition in file vx_khr_pipelining.h.
Extra enums.
Enumerator | |
---|---|
VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE | Graph schedule mode type enumeration. |
Definition at line 48 of file vx_khr_pipelining.h.
Type of graph scheduling mode.
See vxSetGraphScheduleConfig
and vxGraphParameterEnqueueReadyRef
for details about each mode.
Definition at line 59 of file vx_khr_pipelining.h.
The graph attributes added by this extension.
Enumerator | |
---|---|
VX_GRAPH_SCHEDULE_MODE | Returns the schedule mode of a graph. Read-only. Use a |
Definition at line 77 of file vx_khr_pipelining.h.
enum vx_event_enum_e |
Extra enums.
Enumerator | |
---|---|
VX_ENUM_EVENT_TYPE | Event Type enumeration. |
Definition at line 309 of file vx_khr_pipelining.h.
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.
|
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.
|
Definition at line 318 of file vx_khr_pipelining.h.
enum vx_node_state_enum_e |
Extra enums.
Enumerator | |
---|---|
VX_ENUM_NODE_STATE_TYPE | Node state type enumeration. |
Definition at line 572 of file vx_khr_pipelining.h.
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 581 of file vx_khr_pipelining.h.
The node attributes added by this extension.
Enumerator | |
---|---|
VX_NODE_STATE | Queries the state of the node. Read-only. See |
Definition at line 596 of file vx_khr_pipelining.h.
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_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 bufers 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
|
Definition at line 604 of file vx_khr_pipelining.h.
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
:
vxVerifyGraph
before enqueing data referencesvxScheduleGraph
or vxProcessGraph
When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL
:
vxScheduleGraph
vxProcessGraph
vxScheduleGraph
is called on the graph else an error is returned by vxScheduleGraph
vxScheduleGraph
is called, all enqueued references get processed in a 'batch'.vxWaitGraph
to wait for the previous vxScheduleGraph
to complete.When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_NORMAL
:
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 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.
When this API is called before vxVerifyGraph
, the 'refs_list' field can be NULL, if the reference handles are not available yet at the application. However 'refs_list_size' MUST always be specified by the application. Application can call vxSetGraphScheduleConfig
again after verify graph with all parameters remaining the same except with 'refs_list' field providing the list of references that can be enqueued at the graph parameter.
[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. |
vx_status_e
enumeration. 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. |
VX_API_ENTRY vx_status VX_API_CALL vxGraphParameterEnqueueReadyRef | ( | vx_graph | graph, |
vx_uint32 | graph_parameter_index, | ||
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.
User MUST use vxGraphParameterDequeueDoneRef
to get back the processed or consumed references.
The references that are enqueued MUST be the references listed during vxSetGraphScheduleConfig
. If a reference outside this list is provided then behaviour is undefined.
[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 |
vx_status_e
enumeration. 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. |
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'.
[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. |
vx_status_e
enumeration. 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_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.
See also vxGraphParameterDequeueDoneRef
.
[in] | graph | Graph reference |
[in] | graph_parameter_index | Graph parameter index |
[out] | num_refs | Number of references that can be dequeued using vxGraphParameterDequeueDoneRef |
vx_status_e
enumeration. 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. |
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.
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 |
vx_status_e
enumeration. VX_SUCCESS | Event received and event information available in 'event' |
VX_FAILURE | No event is received |
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.
context | [in] OpenVX context |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
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.
context | [in] OpenVX context |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_API_ENTRY vx_status VX_API_CALL vxSendUserEvent | ( | vx_context | context, |
vx_uint32 | app_value, | ||
const void * | parameter | ||
) |
Generate user defined event.
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 |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
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.
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. |
vx_status_e
enumeration. 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. |
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.
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. |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | graph is not a valid vx_graph reference |
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.
graph | [in] Reference to the graph to start streaming mode of execution. |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | graph is not a valid vx_graph reference. |
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.
graph | [in] Reference to the graph to stop streaming mode of execution. |
vx_status_e
enumeration. 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. |