OpenVX EXPORT AND IMPORT EXTENSION  60cc946
 All Functions Typedefs Groups Pages
vx_import.h
1 /*
2  * Copyright (c) 2012-2017 The Khronos Group Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and/or associated documentation files (the
6  * "Materials"), to deal in the Materials without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Materials, and to
9  * permit persons to whom the Materials are furnished to do so, subject to
10  * the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included
13  * in all copies or substantial portions of the Materials.
14  *
15  * MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
16  * KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
17  * SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
18  * https://www.khronos.org/registry/
19  *
20  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
23  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
24  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
25  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
26  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
27  */
28 #ifndef _OPENVX_IMPORT_H_
29 #define _OPENVX_IMPORT_H_
30 /*!
31  * \file
32  * \brief The OpenVX Import API
33  * part of the OpenVX Export and Import extension API
34  * and also part of the OpenVX SC deployment feature set.
35  */
36 
37  /*! \brief An enumeration of export uses. See <tt>\ref vxExportObjectsToMemory</tt> and
38  * <tt>\ref vxImportObjectsFromMemory</tt>
39  * \ingroup vx_enum_e
40  */
41 #define VX_ENUM_IX_USE 0x18
42 /*! \brief How to export and import an object
43  * \ingroup group_import
44  */
45 #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. */
46 /*! \brief How to export and import an object
47  * \ingroup group_import
48  */
49 #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. */
50 /*! \brief How to export and import an object
51  * \ingroup group_import
52  */
53 #define VX_IX_USE_NO_EXPORT_VALUES (VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_IX_USE) + 0x2) /*!< \brief Data values are not exported. */
54 
55 /*=============================================================================
56 IMPORT
57 =============================================================================*/
58 /*! \brief The Import Object. Import is a container of OpenVX objects, which may be retreived
59  * by name
60  * \ingroup group_import
61  */
62 typedef struct _vx_import *vx_import;
63 
64 /*! \brief The Object Type Enumeration for import.
65  * \ingroup group_import
66  */
67 
68 #define VX_TYPE_IMPORT 0x814/*!< \brief A <tt>\ref vx_import</tt>. */
69 
70 /*! \brief Imports objects into a context from a vendor-specific format in memory.\n
71  *
72  * \details This function imports objects from a memory blob previously created using <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].\n
73  * A pointer to memory is given where a list of references is stored, together with the list
74  * of uses which describes how the references are used. The number of references given and the
75  * list of uses must match that given upon export, or this function will not be sucessful[*REQ*].\n
76  * The *uses* array specifies how the objects in the corresponding *refs* array will be imported:
77  * - <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt>\n
78  * The application must create the object and supply the reference; the
79  * meta-data of the object must match exactly the meta-data of the object when it was exported,
80  * except that the name need not match[*REQ*].\n
81  * If the supplied reference has a different name to that stored, the supplied name is used[*REQ*].
82  * - <tt>\ref VX_IX_USE_EXPORT_VALUES</tt>\n
83  * The implementation will create the object and set the data in it[*REQ*].\n
84  * Any data not defined at the time of export of the object will be set to a default value (zero in the
85  * absence of any other definition) upon import[*REQ*].
86  * - <tt>\ref VX_IX_USE_NO_EXPORT_VALUES</tt>\n
87  * The implementation will create the object and the importing application will set values as applicable[*REQ*].
88  *
89  * References are obtained from the import API for those objects whose references were listed at the time of export.
90  * These are not the same objects; they are equivalent objects created by the framework at import time.
91  * The implementation guarantees that references will be available and valid for all objects listed at the time
92  * of export, or the import will fail[*REQ*].\n
93  * The import operation will fail if more than one object whose reference is listed at *refs*
94  * has been given the same non-zero length name (via <tt>\ref vxSetReferenceName</tt>)[*REQ*].\n
95  * The import will be unsuccessful if any of the parameters supplied is NULL[*REQ*].\n
96  * After completion of the function the memory at *ptr* may be deallocated by the application as it will
97  * not be used by any of the created objects[*REQ*].\n
98  * Any delays imported with graphs for which they are registered for auto-aging remain registered
99  * for auto-aging[*REQ*].\n
100  * After import, a graph must execute with exactly the same effect with respect to its visible parameters
101  * as before export[*REQ*].
102  * \note The *refs* array must be the correct length to hold all references of the import; this will be the same length
103  * that was supplied at the time of export. Only references for objects created by the application, where the
104  * corresponding *uses* entry is <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt> should be filled in by the application;
105  * all other entries will be supplied by the framework and may be initialised by the application to NULL. The *uses* array
106  * must have the identical length and content as given at the time of export, and the value of *numrefs* must also match;
107  * these measures increase confidence that the import contains the correct data.
108 * \note Graph parameters may be changed after import by using the <tt>\ref vxSetGraphParameterByIndex</tt> API, and
109  * images may also be changed by using the <tt>\ref vxSwapImageHandle</tt> API.
110  * When <tt>\ref vxSetGraphParameterByIndex</tt> is used, the framework will check that the new parameter is of the
111  * correct type to run with the graph, which cannot be re-verified. If the reference supplied is not suitable, an error
112  * will be returned, but there may be circumstances where changing graph parameters for unsuitable ones is not detected
113  * and could lead to implementation-dependent behaviour; one such circumstance is when the new parameters are images
114  * corresponding to overlapping regions of interest. The user should avoid these circumstances.
115  * In other words,
116  * - The meta data of the new graph parameter must match the meta data of the graph parameter it replaces [*REQ*].
117  * - A graph parameter must not be NULL [*REQ*].
118  * \param [in] context context into which to import objects, must be valid [*REQ*].
119  * \param [in] numrefs number of references to import, must match export[*REQ*].
120  * \param [in,out] refs references imported or application-created data which must match
121  * meta-data of the export[*REQ*]
122  * \param [in] uses how to import the references, must match export values[*REQ*]
123  * \param [in] ptr pointer to binary buffer containing a valid binary export[*REQ*]
124  * \param [in] length number of bytes at \*ptr, i.e. the length of the export[*REQ*]
125  * \return A <tt>\ref vx_import</tt>[*REQ*].
126  * Calling <tt>\ref vxGetStatus</tt> with the vx_import as a parameter will return VX_SUCCESS if the
127  * function was successful[*REQ*].\n
128  * Another value is given to indicate that there was an error[*REQ*].\n
129  * An implementation may provide several different error codes to give useful diagnostic information
130  * in the event of failure to import objects, but these are not required to indicate
131  * possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.
132  * \post <tt>\ref vxReleaseImport</tt> is used to release the import object.
133  * \post Use <tt>\ref vxReleaseReference</tt> or an appropriate specific release function to release
134  * the references in the array refs when they are no longer required.
135  * \ingroup group_import
136  */
137 VX_API_ENTRY vx_import VX_API_CALL vxImportObjectsFromMemory(
138  vx_context context,
139  vx_size numrefs,
140  vx_reference *refs,
141  const vx_enum * uses,
142  const vx_uint8 * ptr,
143  vx_size length);
144 
145 /*! \brief Releases an import object when no longer required.\n
146  * \details This function releases the reference to the import object [*REQ*].\n
147  * Other objects including those imported at the time of creation of the import object are unaffected[*REQ*].\n
148  * \param [in,out] import The pointer to the reference to the import object[*REQ*].
149  * \post After returning sucessfully from this function the reference is zeroed[*REQ*].
150  * \return A <tt>\ref vx_status</tt> value.
151  * \retval VX_SUCCESS If no errors occurred and the import was sucessfully released[*REQ*].\n
152  * An error is indicated when the return value is not VX_SUCCESS[*REQ*].\n
153  * An implementation may provide several different return values to give useful diagnostic
154  * information in the event of failure to export, but these are not required to indicate
155  * possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.
156  * \pre <tt>\ref vxImportObjectsFromMemory</tt> is used to create an import object.
157  * \ingroup group_import
158  */
159 VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import);
160 /*! \brief Get a reference from the import object by name.\n
161  *
162  * \details All accessible references of the import object created using <tt>\ref vxImportObjectsFromMemory</tt> are
163  * in the array *refs*, which is populated partly by the application before import, and partly by the
164  * framework. However, it may be more convenient to access the references in the import object without
165  * referring to this array, for example if the import object is passed as a parameter to another function.
166  * In this case, references may be retreived by name, assuming that <tt>\ref vxSetReferenceName</tt>
167  * was called to assign a name to the reference.
168  * This function searches the given import for the given name and returns the associated reference[*REQ*].\n
169  * The reference may have been named either before export or after import[*REQ*].\n
170  * If more than one reference exists in the import with the given name, this is an error[*REQ*].\n
171  * Only references in the array *refs* after calling <tt>\ref vxImportObjectsFromMemory</tt> may be retrieved
172  * using this function[*REQ*].\n
173  * A reference to a named object may be obtained from a valid import object using this API even if all other
174  * references to the object have been released[*REQ*].
175  * \param [in] import The import object in which to find the name; the function will fail if this parameter
176  * is not valid[*REQ*].
177  * \param [in] name The name to find, points to a string of at least one and less than VX_MAX_REFERENCE_NAME bytes
178  * followed by a zero byte; the function will fail if this is not valid[*REQ*].
179  * \return A <tt>\ref vx_reference</tt>[*REQ*].\n
180  * Calling <tt>\ref vxGetStatus</tt> with the reference as a parameter will return VX_SUCCESS if the function
181  * was successful[*REQ*].\n
182  * Another value is given to indicate that there was an error[*REQ*].\n
183  * On success, the reference count of the object in question is incremented[*REQ*].\n
184  * An implementation may provide several different error codes to give useful diagnostic information
185  * in the event of failure to retrieve a reference, but these are not required to indicate
186  * possibly recovery mechanisms, and for safety critical use assume errors are not recoverable.
187  * \pre <tt>\ref vxSetReferenceName</tt> was used to name the reference.
188  * \post use <tt>ref vxReleaseReference</tt> or appropriate specific release function to release a reference
189  * obtained by this method.
190  * \ingroup group_import
191  */
192 VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName(vx_import import, const vx_char *name);
193 
194 #endif
struct _vx_import * vx_import
The Import Object. Import is a container of OpenVX objects, which may be retreived by name...
Definition: vx_import.h:62
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. .
VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import)
Releases an import object when no longer required. .
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. .