Import Object

Macros
#define	VX_IX_USE_APPLICATION_CREATE   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x0)
#define	VX_IX_USE_EXPORT_VALUES   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x1)
#define	VX_IX_USE_NO_EXPORT_VALUES   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x2)
#define	VX_TYPE_IMPORT   0x814

Typedefs
typedef struct _vx_import *	vx_import

Functions
VX_API_ENTRY vx_import VX_API_CALL	vxImportObjectsFromMemory (vx_context context, vx_size numrefs, vx_reference *refs, const vx_enum *uses, const vx_uint8 *ptr, vx_size length)
VX_API_ENTRY vx_status VX_API_CALL	vxReleaseImport (vx_import *import)
VX_API_ENTRY vx_reference VX_API_CALL	vxGetImportReferenceByName (vx_import import, const vx_char *name)
VX_API_ENTRY vx_status VX_API_CALL	vxExportObjectsToMemory (vx_context context, vx_size numrefs, const vx_reference *refs, const vx_enum *uses, const vx_uint8 **ptr, vx_size *length)
VX_API_ENTRY vx_status VX_API_CALL	vxReleaseExportedMemory (vx_context context, const vx_uint8 **ptr)

Detailed Description

Import objects.

Macro Definition Documentation

#define VX_IX_USE_APPLICATION_CREATE   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x0)

How to export and import an object.

The application will create the object before import.

Definition at line 45 of file vx_import.h.

#define VX_IX_USE_EXPORT_VALUES   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x1)

How to export and import an object.

Data values are exported and restored upon import.

Definition at line 49 of file vx_import.h.

#define VX_IX_USE_NO_EXPORT_VALUES   (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x2)

How to export and import an object.

Data values are not exported.

Definition at line 53 of file vx_import.h.

#define VX_TYPE_IMPORT   0x814

The Object Type Enumeration for import.

A vx_import.

Definition at line 68 of file vx_import.h.

Function Documentation

VX_API_ENTRY vx_status VX_API_CALL vxExportObjectsToMemory	(	vx_context	context,
		vx_size	numrefs,
		const vx_reference *	refs,
		const vx_enum *	uses,
		const vx_uint8 **	ptr,
		vx_size *	length
	)

Exports selected objects to memory in a vendor-specific format.
.

A list of references in the given context is supplied to this function, and all information required to re-create these is stored in memory in such a way that those objects may be re-created with the corresponding import function, according to the usage specified by the uses parameter[REQ].
The information must be context independent in that it may be written to external storage for later retreival with another instantiation of a compatible implementation[REQ].
The list of objects to export may contain only valid references (i.e. vxGetStatus() will return VX_SUCCESS) to vx_graph and non-virtual data objects or the function will fail[REQ]. (Specifically not vx_context, vx_import, vx_node, vx_kernel, vx_parameter or vx_meta_format)
Some node creation functions take C parameters rather than OpenVX data objects (such as the gradient_size parameter of vxHarrisCornersNode that is provided as a vx_int32), because these are intended to be fixed at node creation time; nevertheless OpenVX data objects may be assigned to them, for example if the vxCreateGenericNode API is used. A data object corresponding to a node parameter that is intended to be fixed at node creation time must not be in the list of exported objects nor attached as a graph parameter or the export operation will fail[REQ].
The uses array specifies how the objects in the corresponding refs array will be exported. A data object will always have its meta-data (e.g. dimensions and format of an image) exported, and optionally may have its data (e.g. pixel values) exported, and additionally you can decide whether the importing application will create data objects to replace those attached to graphs, or if the implementation will automatically create them:

• VX_IX_USE_APPLICATION_CREATE
  Export sufficient data to check that an application-supplied object is compatible when the data is later imported[REQ].

  Note

  This value must be given for images created from handles, or the the export operation will fail[REQ]

• VX_IX_USE_EXPORT_VALUES
  Export complete information (for example image data or value of a scalar)[REQ].
• VX_IX_USE_NO_EXPORT_VALUES
  Export meta-data only; the importing application will set values as applicable[REQ]

The values in uses are applicable only for data objects and are ignored for vx_graph objects[REQ].
If the list refs contains vx_graph objects, these graphs will be verified during the export operation and the export operation will fail if verification fails; when successfully exported graphs are subsequently imported they will appear as verified [REQ].

Note

The implementation may also choose to re-verify any previously verified graphs and apply optimisations based upon which references are to be exported and how.
Any data objects attached to a graph that are hidden, i.e. their references are not in the list refs, may be treated by the implementation as virtual objects, since they can never be visible when the graph is subsequently imported.
Note that imported graphs cannot become unverified. Attempts to change the graph that might normally cause the graph to be unverified, e.g. calling vxSetGraphParameterByIndex with an object with different metadata, will fail.
The implementation should make sure that all permissible changes of exported objects are possible without re-verification. For example:

• A uniform image may be swapped for a non-uniform image, so corresponding optimisations should be inhibited if a uniform image appears in the refs list
• An image that is a region of interest of another image may be similarly replaced by any other image of matching size and format, and vice-versa

If a graph is exported that has delays registered for auto-aging, then this information is also exported[REQ].
If the function is called with NULL for any of its parameters, this is an error [REQ].
The reference counts of objects as visible to the calling application will not be affected by calling this function [REQ].
The export operation will fail if more than one object whose reference is listed at refs has been given the same non-zero length name (via vxSetReferenceName)[REQ].
If a graph listed for export has any graph parameters not listed at refs, then the export operation will fail[REQ].

Note

The order of the references supplied in the refs array will be the order in which the framwork will supply references for the corresponding import operation with vxImportObjectsFromMemory.
The same length of uses array, containing the same values, and the same value of numrefs, must be supplied for the corresponding import operation.

For objects not listed in refs, the following rules apply:

1. In any one graph, if an object is not connected as an output of a node in a graph being exported then its data values will be exported (for subsequent import)[REQ].
2. Where the object in (1) is a composite object (such as a pyramid) then rule (1) applies to all of its sub-objects[REQ].
3. Where the object in (1) is a sub-object such as a region of interest, and the composite object (in this case the parent image) does not meet the conditions of rule (1), then rule (1) applies to the sub-object only[REQ].

   Parameters

   [in]	context	context from which to export objects, must be valid [REQ].
   [in]	numrefs	number of references to export [REQ].
   [in]	refs	references to export. This is an array of length numrefs populated with the references to export[REQ].
   [in]	uses	how to export the references. This is an array of length numrefs containing values as described above[REQ].
   [out]	ptr	returns pointer to binary buffer. On error this is set to NULL[REQ].
   [out]	length	number of bytes at *ptr. On error this is set to zero[REQ].

   Returns

   A vx_status value.

   Return values

   VX_SUCCESS

   If no errors occurred and the objects were sucessfully exported[REQ]. An error is indicated when the return value is not VX_SUCCESS. An implementation may provide several different return values to give useful diagnostic information in the event of failure to export, but these are not required to indicate possible recovery mechanisms, and for safety critical use assume errors are not recoverable.

   Postcondition

   vxReleaseExportedMemory is used to deallocate the memory.

VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName	(	vx_import	import,
		const vx_char *	name
	)

Get a reference from the import object by name.
.

All accessible references of the import object created using vxImportObjectsFromMemory are in the array refs, which is populated partly by the application before import, and partly by the framework. However, it may be more convenient to access the references in the import object without referring to this array, for example if the import object is passed as a parameter to another function. In this case, references may be retreived by name, assuming that vxSetReferenceName was called to assign a name to the reference. This function searches the given import for the given name and returns the associated reference[REQ].
The reference may have been named either before export or after import[REQ].
If more than one reference exists in the import with the given name, this is an error[REQ].
Only references in the array refs after calling vxImportObjectsFromMemory may be retrieved using this function[REQ].
A reference to a named object may be obtained from a valid import object using this API even if all other references to the object have been released[REQ].

Parameters

[in]	import	The import object in which to find the name; the function will fail if this parameter is not valid[REQ].
[in]	name	The name to find, points to a string of at least one and less than VX_MAX_REFERENCE_NAME bytes followed by a zero byte; the function will fail if this is not valid[REQ].

Returns

A vx_reference[REQ].
Calling vxGetStatus with the reference as a parameter will return VX_SUCCESS if the function was successful[REQ].
Another value is given to indicate that there was an error[REQ].
On success, the reference count of the object in question is incremented[REQ].
An implementation may provide several different error codes to give useful diagnostic information in the event of failure to retrieve a reference, but these are not required to indicate possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.

Precondition

vxSetReferenceName was used to name the reference.

Postcondition

use ref vxReleaseReference or appropriate specific release function to release a reference obtained by this method.

VX_API_ENTRY vx_import VX_API_CALL vxImportObjectsFromMemory	(	vx_context	context,
		vx_size	numrefs,
		vx_reference *	refs,
		const vx_enum *	uses,
		const vx_uint8 *	ptr,
		vx_size	length
	)

Imports objects into a context from a vendor-specific format in memory.
.

This function imports objects from a memory blob previously created using vxExportObjectsToMemory[REQ].
A pointer to memory is given where a list of references is stored, together with the list of uses which describes how the references are used. The number of references given and the list of uses must match that given upon export, or this function will not be sucessful[REQ].
The uses array specifies how the objects in the corresponding refs array will be imported:

• VX_IX_USE_APPLICATION_CREATE
  The application must create the object and supply the reference; the meta-data of the object must match exactly the meta-data of the object when it was exported, except that the name need not match[REQ].
  If the supplied reference has a different name to that stored, the supplied name is used[REQ].
• VX_IX_USE_EXPORT_VALUES
  The implementation will create the object and set the data in it[REQ].
  Any data not defined at the time of export of the object will be set to a default value (zero in the absence of any other definition) upon import[REQ].
• VX_IX_USE_NO_EXPORT_VALUES
  The implementation will create the object and the importing application will set values as applicable[REQ].

References are obtained from the import API for those objects whose references were listed at the time of export. These are not the same objects; they are equivalent objects created by the framework at import time. The implementation guarantees that references will be available and valid for all objects listed at the time of export, or the import will fail[REQ].
The import operation will fail if more than one object whose reference is listed at refs has been given the same non-zero length name (via vxSetReferenceName)[REQ].
The import will be unsuccessful if any of the parameters supplied is NULL[REQ].
After completion of the function the memory at ptr may be deallocated by the application as it will not be used by any of the created objects[REQ].
Any delays imported with graphs for which they are registered for auto-aging remain registered for auto-aging[REQ].
After import, a graph must execute with exactly the same effect with respect to its visible parameters as before export[REQ].

Note

The refs array must be the correct length to hold all references of the import; this will be the same length that was supplied at the time of export. Only references for objects created by the application, where the corresponding uses entry is VX_IX_USE_APPLICATION_CREATE should be filled in by the application; all other entries will be supplied by the framework and may be initialised by the application to NULL. The uses array must have the identical length and content as given at the time of export, and the value of numrefs must also match; these measures increase confidence that the import contains the correct data.

Graph parameters may be changed after import by using the vxSetGraphParameterByIndex API, and images may also be changed by using the vxSwapImageHandle API. When vxSetGraphParameterByIndex is used, the framework will check that the new parameter is of the correct type to run with the graph, which cannot be re-verified. If the reference supplied is not suitable, an error will be returned, but there may be circumstances where changing graph parameters for unsuitable ones is not detected and could lead to implementation-dependent behaviour; one such circumstance is when the new parameters are images corresponding to overlapping regions of interest. The user should avoid these circumstances. In other words,

• The meta data of the new graph parameter must match the meta data of the graph parameter it replaces [REQ].
• A graph parameter must not be NULL [REQ].

Parameters

[in]	context	context into which to import objects, must be valid [REQ].
[in]	numrefs	number of references to import, must match export[REQ].
[in,out]	refs	references imported or application-created data which must match meta-data of the export[REQ]
[in]	uses	how to import the references, must match export values[REQ]
[in]	ptr	pointer to binary buffer containing a valid binary export[REQ]
[in]	length	number of bytes at *ptr, i.e. the length of the export[REQ]

Returns

A vx_import[REQ]. Calling vxGetStatus with the vx_import as a parameter will return VX_SUCCESS if the function was successful[REQ].
Another value is given to indicate that there was an error[REQ].
An implementation may provide several different error codes to give useful diagnostic information in the event of failure to import objects, but these are not required to indicate possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.

Postcondition

vxReleaseImport is used to release the import object.

Use vxReleaseReference or an appropriate specific release function to release the references in the array refs when they are no longer required.

VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory	(	vx_context	context,
		const vx_uint8 **	ptr
	)

Releases memory allocated for a binary export when it is no longer required.

This function releases memory allocated by vxExportObjectsToMemory[REQ].

Parameters

[in]	context	The context for which vxExportObjectsToMemory was called[REQ].
[in,out]	ptr	A pointer previously set by calling vxExportObjectsToMemory[REQ]. The function will fail if *ptr does not contain an address of memory previously allocated by vxExportObjectsToMemory[REQ].

Postcondition

After returning from sucessfully from this function *ptr is set to NULL[REQ].

Returns

A vx_status value.

Return values

VX_SUCCESS

If no errors occurred and the memory was sucessfully released[REQ]. An error is indicated when the return value is not VX_SUCCESS[REQ]. An implementation may provide several different return values to give useful diagnostic information in the event of failure to export, but these are not required to indicate possible recovery mechanisms, and for safety critical use assume errors are not recoverable.

Precondition

vxExportObjectsToMemory is used to allocate the memory.

VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport

(

vx_import *

import

)

Releases an import object when no longer required.
.

This function releases the reference to the import object [REQ].
Other objects including those imported at the time of creation of the import object are unaffected[REQ].

Parameters

[in,out]

import

The pointer to the reference to the import object[REQ].

Postcondition

After returning sucessfully from this function the reference is zeroed[REQ].

Returns

A vx_status value.

Return values

VX_SUCCESS

If no errors occurred and the import was sucessfully released[REQ]. An error is indicated when the return value is not VX_SUCCESS[REQ]. An implementation may provide several different return values to give useful diagnostic information in the event of failure to export, but these are not required to indicate possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.

Precondition

vxImportObjectsFromMemory is used to create an import object.