This repository has been archived by the owner on Feb 16, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 53
/
vx_khr_ix.h
158 lines (147 loc) · 9.28 KB
/
vx_khr_ix.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
/*
* Copyright (c) 2012-2017 The Khronos Group Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _OPENVX_IMPORT_EXPORT_H_
#define _OPENVX_IMPORT_EXPORT_H_
/*!
* \file
* \brief The OpenVX Export and Import extension API.
*/
#define OPENVX_KHR_IX "vx_khr_ix"
#include <VX/vx_import.h>
#ifdef __cplusplus
extern "C" {
#endif
/*=============================================================================
Export to host memory
=============================================================================*/
/*! \brief Exports selected objects to memory in a vendor-specific format.\n
*
* \details 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*].\n
* 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*].\n
* 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)\n
* Some node creation functions take C parameters rather than OpenVX data objects (such as the *gradient_size*
* parameter of <tt>\ref vxHarrisCornersNode</tt> 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 <tt>\ref vxCreateGenericNode</tt> 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*].\n
* 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:
* - <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt> \n
* 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*]
* - <tt>\ref VX_IX_USE_EXPORT_VALUES</tt>\n
* Export complete information (for example image data or value of a
* scalar)[*REQ*].
* - <tt>\ref VX_IX_USE_NO_EXPORT_VALUES</tt>\n
* 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*].\n
* 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*].\n
* \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.\n
* 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.\n
* 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.\n
* 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*].\n
* If the function is called with NULL for any of its parameters, this is an error [*REQ*].\n
* The reference counts of objects as visible to the calling application will not be affected
* by calling this function [*REQ*].\n
* 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 <tt>\ref vxSetReferenceName</tt>)[*REQ*].\n
* 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 <tt>\ref vxImportObjectsFromMemory</tt>.\n
* 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*].
* \param [in] context context from which to export objects, must be valid [*REQ*].
* \param [in] numrefs number of references to export [*REQ*].
* \param [in] refs references to export. This is an array of length numrefs populated with
* the references to export[*REQ*].
* \param [in] uses how to export the references. This is an array of length numrefs containing
* values as described above[*REQ*].
* \param [out] ptr returns pointer to binary buffer. On error this is set to NULL[*REQ*].
* \param [out] length number of bytes at \*ptr. On error this is set to zero[*REQ*].
* \return A <tt>\ref vx_status</tt> value.
* \retval 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.\n
* 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.
* \post <tt>\ref vxReleaseExportedMemory</tt> is used to deallocate the memory.
* \ingroup group_import
*/
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);
/*! \brief Releases memory allocated for a binary export when it is no longer required.
* \details This function releases memory allocated by <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
* \param [in] context The context for which <tt>\ref vxExportObjectsToMemory</tt> was called[*REQ*].
* \param [in,out] ptr A pointer previously set by calling <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
* The function will fail if <code>*ptr</code> does not contain an address of memory previously
* allocated by <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
* \post After returning from sucessfully from this function \*ptr is set to NULL[*REQ*].
* \return A <tt>\ref vx_status</tt> value.
* \retval VX_SUCCESS If no errors occurred and the memory was sucessfully released[*REQ*].\n
* An error is indicated when the return value is not VX_SUCCESS[*REQ*].\n
* 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.
* \pre <tt>\ref vxExportObjectsToMemory</tt> is used to allocate the memory.
* \ingroup group_import
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory(
vx_context context, const vx_uint8 ** ptr);
#ifdef __cplusplus
}
#endif
#endif