-
Notifications
You must be signed in to change notification settings - Fork 0
/
vx_import.h
194 lines (187 loc) · 12 KB
/
vx_import.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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
/*
* Copyright (c) 2012-2017 The Khronos Group Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and/or associated documentation files (the
* "Materials"), to deal in the Materials without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Materials, and to
* permit persons to whom the Materials are furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Materials.
*
* MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
* KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
* SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
* https://www.khronos.org/registry/
*
* THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
*/
#ifndef _OPENVX_IMPORT_H_
#define _OPENVX_IMPORT_H_
/*!
* \file
* \brief The OpenVX Import API
* part of the OpenVX Export and Import extension API
* and also part of the OpenVX SC deployment feature set.
*/
/*! \brief An enumeration of export uses. See <tt>\ref vxExportObjectsToMemory</tt> and
* <tt>\ref vxImportObjectsFromMemory</tt>
* \ingroup vx_enum_e
*/
#define VX_ENUM_IX_USE 0x18
/*! \brief How to export and import an object
* \ingroup group_import
*/
#define VX_IX_USE_APPLICATION_CREATE (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x0) /*!< \brief The application will create the object before import. */
/*! \brief How to export and import an object
* \ingroup group_import
*/
#define VX_IX_USE_EXPORT_VALUES (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x1) /*!< \brief Data values are exported and restored upon import. */
/*! \brief How to export and import an object
* \ingroup group_import
*/
#define VX_IX_USE_NO_EXPORT_VALUES (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x2) /*!< \brief Data values are not exported. */
/*=============================================================================
IMPORT
=============================================================================*/
/*! \brief The Import Object. Import is a container of OpenVX objects, which may be retreived
* by name
* \ingroup group_import
*/
typedef struct _vx_import *vx_import;
/*! \brief The Object Type Enumeration for import.
* \ingroup group_import
*/
#define VX_TYPE_IMPORT 0x814/*!< \brief A <tt>\ref vx_import</tt>. */
/*! \brief Imports objects into a context from a vendor-specific format in memory.\n
*
* \details This function imports objects from a memory blob previously created using <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].\n
* 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*].\n
* The *uses* array specifies how the objects in the corresponding *refs* array will be imported:
* - <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt>\n
* 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*].\n
* If the supplied reference has a different name to that stored, the supplied name is used[*REQ*].
* - <tt>\ref VX_IX_USE_EXPORT_VALUES</tt>\n
* The implementation will create the object and set the data in it[*REQ*].\n
* 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*].
* - <tt>\ref VX_IX_USE_NO_EXPORT_VALUES</tt>\n
* 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*].\n
* 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 <tt>\ref vxSetReferenceName</tt>)[*REQ*].\n
* The import will be unsuccessful if any of the parameters supplied is NULL[*REQ*].\n
* 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*].\n
* Any delays imported with graphs for which they are registered for auto-aging remain registered
* for auto-aging[*REQ*].\n
* 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 <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt> 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.
* \note Graph parameters may be changed after import by using the <tt>\ref vxSetGraphParameterByIndex</tt> API, and
* images may also be changed by using the <tt>\ref vxSwapImageHandle</tt> API.
* When <tt>\ref vxSetGraphParameterByIndex</tt> 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*].
* \param [in] context context into which to import objects, must be valid [*REQ*].
* \param [in] numrefs number of references to import, must match export[*REQ*].
* \param [in,out] refs references imported or application-created data which must match
* meta-data of the export[*REQ*]
* \param [in] uses how to import the references, must match export values[*REQ*]
* \param [in] ptr pointer to binary buffer containing a valid binary export[*REQ*]
* \param [in] length number of bytes at \*ptr, i.e. the length of the export[*REQ*]
* \return A <tt>\ref vx_import</tt>[*REQ*].
* Calling <tt>\ref vxGetStatus</tt> with the vx_import as a parameter will return VX_SUCCESS if the
* function was successful[*REQ*].\n
* Another value is given to indicate that there was an error[*REQ*].\n
* 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.
* \post <tt>\ref vxReleaseImport</tt> is used to release the import object.
* \post Use <tt>\ref vxReleaseReference</tt> or an appropriate specific release function to release
* the references in the array refs when they are no longer required.
* \ingroup group_import
*/
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);
/*! \brief Releases an import object when no longer required.\n
* \details This function releases the reference to the import object [*REQ*].\n
* Other objects including those imported at the time of creation of the import object are unaffected[*REQ*].\n
* \param [in,out] import The pointer to the reference to the import object[*REQ*].
* \post After returning sucessfully from this function the reference is zeroed[*REQ*].
* \return A <tt>\ref vx_status</tt> value.
* \retval VX_SUCCESS If no errors occurred and the import 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
* possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.
* \pre <tt>\ref vxImportObjectsFromMemory</tt> is used to create an import object.
* \ingroup group_import
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import);
/*! \brief Get a reference from the import object by name.\n
*
* \details All accessible references of the import object created using <tt>\ref vxImportObjectsFromMemory</tt> 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 <tt>\ref vxSetReferenceName</tt>
* 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*].\n
* The reference may have been named either before export or after import[*REQ*].\n
* If more than one reference exists in the import with the given name, this is an error[*REQ*].\n
* Only references in the array *refs* after calling <tt>\ref vxImportObjectsFromMemory</tt> may be retrieved
* using this function[*REQ*].\n
* 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*].
* \param [in] import The import object in which to find the name; the function will fail if this parameter
* is not valid[*REQ*].
* \param [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*].
* \return A <tt>\ref vx_reference</tt>[*REQ*].\n
* Calling <tt>\ref vxGetStatus</tt> with the reference as a parameter will return VX_SUCCESS if the function
* was successful[*REQ*].\n
* Another value is given to indicate that there was an error[*REQ*].\n
* On success, the reference count of the object in question is incremented[*REQ*].\n
* 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.
* \pre <tt>\ref vxSetReferenceName</tt> was used to name the reference.
* \post use <tt>ref vxReleaseReference</tt> or appropriate specific release function to release a reference
* obtained by this method.
* \ingroup group_import
*/
VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName(vx_import import, const vx_char *name);
#endif