Framework: Node Callbacks

Detailed Description

Allows Clients to receive a callback after a specific node has completed execution.

Callbacks are not guaranteed to be called immediately after the Node completes. Callbacks are intended to be used to create simple early exit conditions for Vision graphs using Return code action values return values. An example of setting up a callback can be seen below:

    vx_graph graph = vxCreateGraph(context);
    status = vxGetStatus((vx_reference)graph);
    if (status == VX_SUCCESS) {
        vx_uint8 lmin = 0, lmax = 0;
        vx_uint32 minCount = 0, maxCount = 0;
        vx_scalar scalars[] = {
            vxCreateScalar(context, VX_TYPE_UINT8, &lmin),
            vxCreateScalar(context, VX_TYPE_UINT8, &lmax),
            vxCreateScalar(context, VX_TYPE_UINT32, &minCount),
            vxCreateScalar(context, VX_TYPE_UINT32, &maxCount),
        };
        vx_array arrays[] = {
            vxCreateArray(context, VX_TYPE_COORDINATES2D, 1),
            vxCreateArray(context, VX_TYPE_COORDINATES2D, 1)
        };
        vx_node nodes[] = {
            vxMinMaxLocNode(graph, input, scalars[0], scalars[1], arrays[0], arrays[1], scalars[2], scalars[3]),
        };
        status = vxAssignNodeCallback(nodes[0], &analyze_brightness);
        // do other
    }

Once the graph has been initialized and the callback has been installed then the callback itself will be called during graph execution.

#define MY_DESIRED_THRESHOLD (10)
vx_action VX_CALLBACK analyze_brightness(vx_node node) {
    // extract the max value
    vx_action action = VX_ACTION_ABANDON;
    vx_parameter pmax = vxGetParameterByIndex(node, 2); // Max Value
    if (pmax) {
        vx_scalar smax = 0;
        vxQueryParameter(pmax, VX_PARAMETER_REF, &smax, sizeof(smax));
        if (smax) {
            vx_uint8 value = 0u;
            vxCopyScalar(smax, &value, VX_READ_ONLY, VX_MEMORY_TYPE_HOST);
            if (value >= MY_DESIRED_THRESHOLD) {
                action = VX_ACTION_CONTINUE;
            }
            vxReleaseScalar(&smax);
        }
        vxReleaseParameter(&pmax);
    }
    return action;
}

Warning

This should be used with extreme caution as it can ruin optimizations in the power/performance efficiency of a graph.

The callback must return a vx_action code indicating how the graph processing should proceed.

• If VX_ACTION_CONTINUE is returned, the graph will continue execution with no changes [R00127].
• If VX_ACTION_ABANDON is returned, execution is unspecified for all nodes for which this node is a dominator. Nodes that are dominators of this node will have executed [R00128]. Execution of any other node is unspecified.

Node Callback Sequence

Modules
	Return code action values
	Possible return values from a vx_nodecomplete_f during execution.

Typedefs
typedef vx_enum	vx_action
	The formal typedef of the response from the callback. More...
typedef vx_action(*	vx_nodecomplete_f) (vx_node node)
	A callback to the client after a particular node has completed. More...

Functions
vx_status VX_API_CALL	vxAssignNodeCallback (vx_node node, vx_nodecomplete_f callback)
	Assigns a callback to a node. If a callback already exists in this node, this function must return an error [R00782]. The user may clear the callback by passing a NULL pointer as the callback [R00783]. More...
vx_nodecomplete_f VX_API_CALL	vxRetrieveNodeCallback (vx_node node)
	Retrieves the current node callback function pointer set on the node. More...

Typedef Documentation

vx_action

typedef vx_enum vx_action

The formal typedef of the response from the callback.

See also

Return code action values

Definition at line 440 of file vx_types.h.

vx_nodecomplete_f

typedef vx_action( * vx_nodecomplete_f) (vx_node node)

A callback to the client after a particular node has completed.

See also

vx_action

vxAssignNodeCallback

Parameters

[in]

node

The node to which the callback was attached.

Returns

An action code from Return code action values.

Definition at line 449 of file vx_types.h.

Function Documentation

vxAssignNodeCallback()

vx_status VX_API_CALL vxAssignNodeCallback	(	vx_node	node,
		vx_nodecomplete_f	callback
	)

Assigns a callback to a node. If a callback already exists in this node, this function must return an error [R00782]. The user may clear the callback by passing a NULL pointer as the callback [R00783].

Parameters

[in]	node	The reference to the node [R00784].
[in]	callback	The callback to associate with completion of this specific node [R00785].

Warning

This must be used with extreme caution as it can ruin optimizations in the power/performance efficiency of a graph.

Returns

A The vx_status Constants value.

Return values

VX_SUCCESS	Callback assigned; and other value indicates failure [R00786].
VX_ERROR_INVALID_REFERENCE	node is not a valid vx_node reference.

vxRetrieveNodeCallback()

vx_nodecomplete_f VX_API_CALL vxRetrieveNodeCallback

(

vx_node

node

)

Retrieves the current node callback function pointer set on the node.

Parameters

[in]

node

The reference to the vx_node object [R00787].

Returns

vx_nodecomplete_f The pointer to the callback function.

Return values

NULL	No callback is set [R00788].
*	The node callback function [R00789].