OpenVX EXPORT AND IMPORT  2b213f9
 All Functions Typedefs Enumerations Enumerator Groups Pages
vx_import_export.h
1 /*
2  * Copyright (c) 2012-2016 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 
29 #ifndef _OPENVX_IMPORT_EXPORT_H_
30 #define _OPENVX_IMPORT_EXPORT_H_
31 
32 /*!
33  * \file
34  * \brief The OpenVX Export and Import extension API.
35  */
36 
37 
38 /*! \brief For import to host memory.
39  * \ingroup group1_import_export_type
40  */
41 typedef struct _vx_import *vx_import;
42 
43 /*! \brief The Object Type Enumeration for import.
44  * \ingroup group1_import_export_type
45  */
47 {
48  VX_TYPE_IMPORT = 0x815,/*!< \brief A <tt>\ref vx_import</tt> */
49 };
50 
51 /*! \brief
52  * \ingroup group1_import_export_type
53  */
54 typedef enum _vx_export_use_e {
55  /*! \brief The application will create the object before import. */
57  /*! \brief Data values to be exported and restored on import. */
59  /*! \brief Data values will not be exported. */
61 };
62 
63 /*! \brief
64  * \param [in] context Context into which to import objects.
65  * \param [in] numrefs Number of references to import.
66  * \param [in, out] refs References imported.
67  * \param [in] uses To import the references, use vx_export_use_e.
68  * \param [in] ptr Where to get the data.
69  * \param [in] length Number of bytes at ptr.
70  * \return <tt>\ref vx_import</tt>
71  * \retval 0 Invalid index.
72  * \retval * An import reference.
73  * \ingroup group4_import_objects_api_from_memory
74 */
75 VX_API_ENTRY vx_import VX_API_CALL vxImportObjectsFromMemory(
76  vx_context context,
77  vx_size numrefs,
78  vx_reference *refs,
79  const vx_enum * uses,
80  const vx_uint8 * ptr,
81  vx_size length);
82 
83 
84 /*! \brief
85  * \param [in] context Context from which to export objects.
86  * \param [in] numrefs Number of references to export.
87  * \param [in] refs References to export.
88  * \param [in] uses How to export the references, use vx_export_use_e.
89  * \param [out] ptr Returns pointer to binary buffer.
90  * \param [out] length Number of bytes at *ptr
91  * \return <tt>\ref vx_status</tt> A vx_status_e enumeration.
92  * \ingroup group2_export_to_memory
93  */
94 VX_API_ENTRY vx_status VX_API_CALL vxExportObjectsToMemory(
95  vx_context context,
96  vx_size numrefs,
97  const vx_reference *refs,
98  const vx_enum * uses,
99  const vx_uint8 ** ptr,
100  vx_size * length);
101 
102 /*! \brief Used to release exported memory.
103  * \param [in] context Context from which to export objects.
104  * \param [in, out] ptr Pointer returned by vxExportObjectsToMemory.
105  * \return <tt>\ref vx_status</tt> A vx_status_e enumeration.
106  * \ingroup group3_release_exported_memory_api
107  */
108 VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory(
109  vx_context context,
110  const vx_uint8 ** ptr);
111 
112 /*! \brief To release an import object after use.
113  * \return <tt>\ref vx_status</tt> A vx_status_e enumeration.
114  * \ingroup group5_release_import_api
115  */
116 VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import);
117 
118 
119 
120 /*! \brief To get a reference from the import object by name.
121  * \return <tt>\ref vx_reference</tt> .
122  * \ingroup group6_get_import_reference_api
123  */
124 VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName(vx_import import, const vx_char *name);
125 
126 /*! \brief user specific object for URL related user callback functions.
127  * \ingroup group7_export_and_import_from_url
128  */
129 typedef struct _vx_url_handle * vx_url_handle;
130 
131 /*! \brief user callback function to create a url for export.
132  * \ingroup group7_export_and_import_from_url
133  */
134 typedef vx_url_handle (VX_CALLBACK * vx_url_create_f)(const vx_char * url);
135 
136 /*! \brief user callback function to open a url for import.
137  * \ingroup group7_export_and_import_from_url
138  */
139 typedef vx_url_handle (VX_CALLBACK * vx_url_open_f)(const vx_char * url);
140 
141 /*! \brief user callback function to write binary data into url.
142  * \ingroup group7_export_and_import_from_url
143  */
144 typedef vx_status (VX_CALLBACK * vx_url_write_f)(vx_url_handle h, const
145 vx_uint8 * ptr, vx_size size);
146 
147 /*! \brief user callback function to read binary data from url.
148  * \ingroup group7_export_and_import_from_url
149  */
150 typedef vx_status (VX_CALLBACK * vx_url_read_f)(vx_url_handle h, vx_uint8 *
151 ptr, vx_size size, vx_size * bytes_read);
152 
153 /*! \brief user callback function to close a url handle.
154  * \ingroup group7_export_and_import_from_url
155  */
156 typedef vx_status (VX_CALLBACK * vx_url_close_f)(vx_url_handle h);
157 
158 
159 /*! \brief Export objects to an arbitrary URL
160  \param [in] context Context from which to export objects.
161  \param [in] numrefs Number of references to export.
162  \param [in] refs References to export.
163  \param [in] uses How to export the references, use vx_export_use_e.
164  \param [in] url Url path .
165  \param [in] create_f Callback to create a url .
166  \param [in] write_f Callback to write a chunk to url .
167  \param [in] close_f Callback to close a url .
168  * \return <tt>\ref vx_status</tt> A vx_status_e enumeration.
169  \ingroup group8_export_objects_to_url
170  */
171 VX_API_ENTRY vx_status VX_API_CALL vxExportObjectsToURL(
172  vx_context context,
173  vx_size numrefs,
174  const vx_reference *refs,
175  const vx_enum * uses,
176  const vx_char * url,
177  vx_url_create_f create_f,
178  vx_url_write_f write_f,
179  vx_url_close_f close_f);
180 
181 
182 /*! \brief Import objects to an arbitrary URL
183  * \param [in] context Context into which to import objects.
184  * \param [in] numrefs Number of references to import.
185  * \param [in, out] refs References imported.
186  * \param [in] uses To import the references, use vx_export_use_e.
187  * \param [in] url Url path.
188  * \param [in] open_f Callback to open a url.
189  * \param [in] read_f Callback to read a chunk from url.
190  * \param [in] close_f Callback to close a url.
191  * \return <tt>\ref vx_import</tt>.
192  * \ingroup group9_import_objects_from_url
193  */
194 VX_API_ENTRY vx_import VX_API_CALL vxImportObjectsFromURL(
195  vx_context context,
196  vx_size numrefs,
197  vx_reference *refs,
198  const vx_enum * uses,
199  const vx_char * url,
200  vx_url_open_f open_f,
201  vx_url_read_f read_f,
202  vx_url_close_f close_f);
203 /*==============================================================================*/
204 #endif
struct _vx_url_handle * vx_url_handle
user specific object for URL related user callback functions.
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)
Data values to be exported and restored on import.
VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName(vx_import import, const vx_char *name)
To get a reference from the import object by name.
VX_API_ENTRY vx_import VX_API_CALL vxImportObjectsFromURL(vx_context context, vx_size numrefs, vx_reference *refs, const vx_enum *uses, const vx_char *url, vx_url_open_f open_f, vx_url_read_f read_f, vx_url_close_f close_f)
Import objects to an arbitrary URL.
VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory(vx_context context, const vx_uint8 **ptr)
Used to release exported memory.
VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import)
To release an import object after use.
The application will create the object before import.
vx_ext_import_type_e
The Object Type Enumeration for import.
vx_status(VX_CALLBACK * vx_url_read_f)(vx_url_handle h, vx_uint8 *ptr, vx_size size, vx_size *bytes_read)
user callback function to read binary data from url.
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)
_vx_export_use_e
vx_status(VX_CALLBACK * vx_url_close_f)(vx_url_handle h)
user callback function to close a url handle.
vx_url_handle(VX_CALLBACK * vx_url_create_f)(const vx_char *url)
user callback function to create a url for export.
vx_url_handle(VX_CALLBACK * vx_url_open_f)(const vx_char *url)
user callback function to open a url for import.
vx_status(VX_CALLBACK * vx_url_write_f)(vx_url_handle h, const vx_uint8 *ptr, vx_size size)
user callback function to write binary data into url.
struct _vx_import * vx_import
For import to host memory.
A vx_import
Data values will not be exported.
VX_API_ENTRY vx_status VX_API_CALL vxExportObjectsToURL(vx_context context, vx_size numrefs, const vx_reference *refs, const vx_enum *uses, const vx_char *url, vx_url_create_f create_f, vx_url_write_f write_f, vx_url_close_f close_f)
Export objects to an arbitrary URL.