OpenVX EXPORT AND IMPORT  2b213f9
 All Functions Typedefs Enumerations Enumerator Groups Pages
Requirements

Import and Export of Objects

  • 2.1.1 Application must be able to specify which objects are to be exported.
  • 2.1.2 The framework will also export any other objects required; for example, if a graph is to be exported then all components of that graph will also be exported even if their references were not given.
  • 2.1.3 Upon Import, only those objects that were specified for export will be visible in the imported entity; all other objects may be present but are not directly accessible. For example, a pyramid object may be exported, in which case the levels of the pyramid will be available in the usual way. As another example, an image that is part of a pyramid is exported. Since an image has no API that allows accessing the pyramid of which it is part, then there is no requirement to export the rest of the pyramid.

Creation of Objects Upon Import

  • 2.2.1 To make it possible to implement certain scenarios, for example when an image needs to be created in a different way in the import environment than the export environment, certain objects may be created by the application and passed to the import routine. These objects need to be specified at the time of export, and provided again at the time of import.
  • 2.2.2 All other required objects will be created by the framework upon import.

Import and Export of Data Values For Objects To Be Created By The Framework

  • 2.3.1 Some objects may contain data values (as distinct from Meta Data) that require preservation across the export and import routines. The application can specify this at the time of export; those objects which are listed (by giving references) for export will then either be stripped of data values or have their data values entirely exported.
  • 2.3.2 For those objects which are not listed, the following rules apply:
    • 2.3.2.1 In any one graph, if an object is not connected as an output parameter then its data values will be exported (and imported).
    • 2.3.2.2 Where the object in (1) is a composite object such as a Pyramid or ObjectArray, then rule (1) applies to all sub-objects by definition.
    • 2.3.2.3 Where the object in (1) is a sub-object such as a Region Of Interest or member of an ObjectArray, and the composite object does not meet the conditions of rule (1), then rule (1) applies to the sub-object only.
    • 2.3.2.4 [Non-SC] When objects are imported, the exported data values are assigned. However, if parts of the data were not defined at the time of export, then there is no guarantee that upon import the same values will be present. For example, consider an image where values had been written only to some (rectangular) part of the image before export. After import, only this part of the image will be guaranteed to contain the same values; those parts which were undefined before will still be undefined and may contain different random values.
    • 2.3.2.5 [SC] All values are initialized upon import. If data was not defined, then it is set to the default value for the data field. In the absence of any other definition the default value is zero.
  • 2.3.3 For those objects which are listed, then:
    • 2.3.3.1 If the application requires, all defined values shall be exported.
    • 2.3.3.2 The application requires, no values need be exported. The behavior here is as though no values had been defined (written) for the object.
    • 2.3.3.3 Areas of undefined values will remain undefined (and possibly containing different random values) upon import.
    • 2.3.3.4 All values are initialized upon import. If data was not defined, then it is set to the default value for the data field. In the absence of any other definition the default value is zero.

Import and Export of Values For Objects To Be Created By The Application

  • 2.4.1 [SC] Objects created by the application before import of the binary object must have their data values defined by the application before the import operation.
  • 2.4.2 [SC] Sometimes changing the value stored in an object that is an input parameter of a verified graph will require that the graph is verified again before execution. If such an object is listed as to be supplied by the application, then the export operation will fail.
  • 2.4.3 [Non-SC] Sometimes changing the value stored in an object that is an input parameter of a verified graph will require that the graph is verified again before execution. If such a graph exists in an imported object and the value of the input parameter has been changed, then any attempts to execute the graph may result in a vendor-specific outcome.

Import and Export of Meta Data

  • 2.5.1 For all objects that are visible in the import, all query-able Meta Data must appear the same after import as before export.
  • 2.5.2 Objects created by the application before import and provided to the import API must match in type, size, etc. and therefore the export must export sufficient information for this check to be done.
  • 2.5.3 An Import may fail if the application-provided objects do not match those given at the time of export.
  • 2.5.4 Graphs with delays that are registered for auto-ageing at the time of export will be in the same condition after import of the objects.

Restrictions Upon What References May Be Exported

  • 2.6.1 Export will fail if a vx_context is given in a list to export.
  • 2.6.2 Export will fail if a vx_import is given in a list to export. (vx_import is the type of the object returned by the import functions).
  • 2.6.3 [SC] Export will fail if a reference to a virtual object is given in the list to export.
  • 2.6.4 [SC] Export will fail if a vx_node, vx_kernel, or vx_parameter is given in the list to export.
  • 2.6.5 Export is otherwise defined for “objects” in the OpenVX 1.1 specification.

Access To Object References In The Imported Object

  • 2.7.1 [Non-SC] 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 application should use the vxGetStatus() API to check the validity of references before use; the framework may give errors such as VX_ERROR_OPTIMIZED_AWAY if appropriate. Application designers should take care to ensure that these sorts of situations are tested before deployment.
  • 2.7.2 [SC] 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.
  • 2.7.3 References additionally may be obtained using a name given to an object before export.
  • 2.7.4 Before export, objects may be named for retrieval by name using the existing API vx_status vxSetReferenceName(vx_reference ref, const vx_char * name).
  • 2.7.5 [SC] Export will fail if duplicate names are found for listed references.
  • 2.7.6 [SC] Import will fail if duplicate names are found in the import object.
  • 2.7.7 [SC] If references are obtained by name, only those objects whose references were listed at the time of export can be found by name.
  • 2.7.8 [SC] A vx_node, vx_kernel, or vx_parameter cannot be obtained from the import object.

"Deployment" Feature Sub-set

The deployment feature subset consists of the following APIs: Import Objects API – From Memory, Release Import API, Get Import Reference API and their dependent requirements, and optionally Export Objects To URL and Import Objects From URL.

Future Directions

Sections Export And Import From URL, Export Objects To URL, and Import Objects From URL describe a mechanism whereby the source or destination of the data is under application control. In no part of this extension is the format of the data described; that is left to the implementation.

However, sections Export Objects To URL and Import Objects From URL do mention that the implementation may examine the url to determine what format to use. Currently we make no specification here. Possible future versions of this specification may make a requirement that if the url is formatted in a certain way, then the output or input should conform to a specific format. For this reason, queries starting with the string “khr” are reserved for future use. One possible application would be to allow export and import in a portable format such as xml.

In section Restrictions Upon What References May Be Exported we disallow the export of a vx_context. This restriction may be removed in future, but there will be many other associated changes, and it may be applicable only to certain clearly defined formats.