OpenVX EXPORT AND IMPORT EXTENSION  60cc946
 All Functions Typedefs Groups Pages
vx_khr_ix.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_EXPORT_H_
29 #define _OPENVX_IMPORT_EXPORT_H_
30 /*!
31  * \file
32  * \brief The OpenVX Export and Import extension API.
33  */
34 
35 #define OPENVX_KHR_IX "vx_khr_ix"
36 
37 #include <VX/vx_import.h>
38 /*=============================================================================
39 Export to host memory
40 =============================================================================*/
41 /*! \brief Exports selected objects to memory in a vendor-specific format.\n
42  *
43  * \details A list of references in the given context is supplied to this function, and all information
44  * required to re-create these is stored in memory in such a way that those objects may be re-created
45  * with the corresponding import function, according to the usage specified by the *uses* parameter[*REQ*].\n
46  * The information must be context independent in that it may be written to external storage for later
47  * retreival with another instantiation of a compatible implementation[*REQ*].\n
48  * The list of objects to export may contain only valid references (i.e. vxGetStatus() will return VX_SUCCESS)
49  * to vx_graph and non-virtual data objects or the function will fail[*REQ*].
50  * (Specifically not vx_context, vx_import, vx_node, vx_kernel, vx_parameter or vx_meta_format)\n
51  * Some node creation functions take C parameters rather than OpenVX data objects (such as the *gradient_size*
52  * parameter of <tt>\ref vxHarrisCornersNode</tt> that is provided as a vx_int32), because these are intended
53  * to be fixed at node creation time; nevertheless OpenVX data objects may be assigned to them, for example if
54  * the <tt>\ref vxCreateGenericNode</tt> API is used.
55  * A data object corresponding to a node parameter that is intended to be fixed at node creation time must not be
56  * in the list of exported objects nor attached as a graph parameter or the export operation will fail[*REQ*].\n
57  * The *uses* array specifies how the objects in the corresponding *refs* array will be exported. A data object
58  * will always have its meta-data (e.g. dimensions and format of an image) exported, and optionally
59  * may have its data (e.g. pixel values) exported, and additionally you can decide whether the importing
60  * application will create data objects to replace those attached to graphs, or if the implementation will
61  * automatically create them:
62  * - <tt>\ref VX_IX_USE_APPLICATION_CREATE</tt> \n
63  * Export sufficient data to check that an application-supplied
64  * object is compatible when the data is later imported[*REQ*].
65  * \note This value must be given for images created from handles, or the the export operation
66  * will fail[*REQ*]
67  * - <tt>\ref VX_IX_USE_EXPORT_VALUES</tt>\n
68  * Export complete information (for example image data or value of a
69  * scalar)[*REQ*].
70  * - <tt>\ref VX_IX_USE_NO_EXPORT_VALUES</tt>\n
71  * Export meta-data only; the importing application will set values
72  * as applicable[*REQ*]
73  *
74  * The values in *uses* are applicable only for data objects and are ignored for vx_graph objects[*REQ*].\n
75  * 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
76  * \note The implementation may also choose to re-verify any previously verified graphs and apply
77  * optimisations based upon which references are to be exported and how.\n
78  * Any data objects attached to a graph that are hidden, i.e. their references are not in the list *refs*,
79  * may be treated by the implementation as virtual objects, since they can never be visible when the graph is
80  * subsequently imported.\n
81  * Note that imported graphs cannot become unverified. Attempts to change the
82  * graph that might normally cause the graph to be unverified, e.g. calling
83  * vxSetGraphParameterByIndex with an object with different metadata, will fail.\n
84  * The implementation should make sure that all permissible changes of exported objects are possible
85  * without re-verification. For example:
86  * - A uniform image may be swapped for a non-uniform image, so corresponding optimisations should be
87  * inhibited if a uniform image appears in the *refs* list
88  * - An image that is a region of interest of another image may be similarly replaced by any other image of
89  * matching size and format, and vice-versa
90  *
91  * If a graph is exported that has delays registered for auto-aging, then this information is also
92  * exported[*REQ*].\n
93  * If the function is called with NULL for any of its parameters, this is an error [*REQ*].\n
94  * The reference counts of objects as visible to the calling application will not be affected
95  * by calling this function [*REQ*].\n
96  * The export operation will fail if more than one object whose reference is listed at *refs*
97  * has been given the same non-zero length name (via <tt>\ref vxSetReferenceName</tt>)[*REQ*].\n
98  * If a graph listed for export has any graph parameters not listed at *refs*, then the
99  * export operation will fail[*REQ*].
100  * \note The order of the references supplied in the *refs* array will be the order in which the
101  * framwork will supply references for the corresponding import operation with <tt>\ref vxImportObjectsFromMemory</tt>.\n
102  * The same length of *uses* array, containing the same values, and the same value of *numrefs*, must be supplied
103  * for the corresponding import operation.
104  *
105  * For objects not listed in *refs*, the following rules apply:
106  * 1. In any one graph, if an object is not connected as an output of a node in a graph being exported
107  * then its data values will be exported (for subsequent import)[*REQ*].
108  * 2. Where the object in (1) is a composite object (such as a pyramid) then rule (1) applies to
109  * all of its sub-objects[*REQ*].
110  * 3. Where the object in (1) is a sub-object such as a region of interest, and the composite object
111  * (in this case the parent image) does not meet the conditions of rule (1), then rule (1) applies
112  * to the sub-object only[*REQ*].
113  * \param [in] context context from which to export objects, must be valid [*REQ*].
114  * \param [in] numrefs number of references to export [*REQ*].
115  * \param [in] refs references to export. This is an array of length numrefs populated with
116  * the references to export[*REQ*].
117  * \param [in] uses how to export the references. This is an array of length numrefs containing
118  * values as described above[*REQ*].
119  * \param [out] ptr returns pointer to binary buffer. On error this is set to NULL[*REQ*].
120  * \param [out] length number of bytes at \*ptr. On error this is set to zero[*REQ*].
121  * \return A <tt>\ref vx_status</tt> value.
122  * \retval VX_SUCCESS If no errors occurred and the objects were sucessfully exported[*REQ*].
123  * An error is indicated when the return value is not VX_SUCCESS.\n
124  * An implementation may provide several different return values to give useful diagnostic
125  * information in the event of failure to export, but these are not required to indicate
126  * possible recovery mechanisms, and for safety critical use assume errors are not recoverable.
127  * \post <tt>\ref vxReleaseExportedMemory</tt> is used to deallocate the memory.
128  * \ingroup group_import
129  */
130 VX_API_ENTRY vx_status VX_API_CALL vxExportObjectsToMemory(
131  vx_context context,
132  vx_size numrefs,
133  const vx_reference *refs,
134  const vx_enum * uses,
135  const vx_uint8 ** ptr,
136  vx_size * length);
137 /*! \brief Releases memory allocated for a binary export when it is no longer required.
138  * \details This function releases memory allocated by <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
139  * \param [in] context The context for which <tt>\ref vxExportObjectsToMemory</tt> was called[*REQ*].
140  * \param [in,out] ptr A pointer previously set by calling <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
141  * The function will fail if <code>*ptr</code> does not contain an address of memory previously
142  * allocated by <tt>\ref vxExportObjectsToMemory</tt>[*REQ*].
143  * \post After returning from sucessfully from this function \*ptr is set to NULL[*REQ*].
144  * \return A <tt>\ref vx_status</tt> value.
145  * \retval VX_SUCCESS If no errors occurred and the memory was sucessfully released[*REQ*].\n
146  * An error is indicated when the return value is not VX_SUCCESS[*REQ*].\n
147  * An implementation may provide several different return values to give useful diagnostic
148  * information in the event of failure to export, but these are not required to indicate
149  * possible recovery mechanisms, and for safety critical use assume errors are not recoverable.
150  * \pre <tt>\ref vxExportObjectsToMemory</tt> is used to allocate the memory.
151  * \ingroup group_import
152  */
153 VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory(
154  vx_context context, const vx_uint8 ** ptr);
155 #endif
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.
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. .