OpenVX XML Schema Extension  r29754
 All Functions Typedefs Enumerations Enumerator Groups Pages
vx_khr_xml.h
1 /*
2  * Copyright (c) 2012-2014 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  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
22  */
23 
24 #ifndef _VX_KHR_XML_H_
25 #define _VX_KHR_XML_H_
26 
27 /*! \file
28  * \brief The OpenVX XML Schema Extension Header.
29  *
30  * \defgroup group_xml Extension: XML API
31  * \brief The Khronos Extension for OpenVX XML Import and Export Support.
32  */
33 
34 #define OPENVX_KHR_XML "vx_khr_xml"
35 
36 #include <VX/vx.h>
37 
38 /*! \brief Defines the maximum number of characters in a reference name string.
39  * \ingroup group_xml
40  * \see vxSetReferenceName
41  * \see vxGetImportReferenceByName
42  */
43 #define VX_MAX_REFERENCE_NAME (64)
44 
45 /*! \brief Extended reference attribute list.
46  * This extension adds new attributes that can be queried by the
47  * \ref <tt>vxQueryReference</tt> function.
48  * \ingroup group_xml
49  */
51  /*! \brief Used to query the reference for its name. Use a <tt>\ref *vx_char</tt> parameter. */
52  VX_REF_ATTRIBUTE_NAME = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_REFERENCE) + 0x2,
53 };
54 
55 /*! \brief The Object Type Enumeration for Imports.
56  * \ingroup group_xml
57  */
59  VX_TYPE_IMPORT = 0x814,/*!< \brief A <tt>\ref vx_import</tt> */
60 };
61 
62 /*! \brief The import type enumeration.
63  * \ingroup group_xml
64  * \see VX_IMPORT_ATTRIBUTE_TYPE
65  */
67  VX_IMPORT_TYPE_XML = 0,/*!< \brief The XML import type */
68 };
69 
70 /*! \brief The import attributes list
71  * \ingroup group_xml
72  * \see vxQueryImport
73  */
75  /*! \brief Returns the number of references in the import object. Use a <tt>\ref vx_uint32</tt> parameter.*/
76  VX_IMPORT_ATTRIBUTE_COUNT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMPORT) + 0x0,
77  /*! \brief Returns the type of import. Use a <tt>\ref vx_ext_import_types_e </tt> parameter */
78  VX_IMPORT_ATTRIBUTE_TYPE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMPORT) + 0x1,
79 };
80 
81 /*! \brief An abstract handle to an import object.
82  * \ingroup group_xml
83  * \extends vx_reference
84  */
85 typedef struct _vx_import *vx_import;
86 
87 
88 #ifdef __cplusplus
89 extern "C" {
90 #endif
91 
92 /*! \brief Exports all objects in the context to an XML file which uses the OpenVX
93  * XML Schema.
94  * \param [in] context The context to export.
95  * \param [in] xmlfile The file name to write the XML into.
96  * \note The reference numbers contained in the xml file can appear in any order but
97  * should be inclusive from index number 0 to [number of references - 1]. For example,
98  * if there are 20 references in the xml file, none of the reference indices should be >= 20.
99  * \return A <tt>\ref vx_status_e</tt> enumeration.
100  * \see https://www.khronos.org/registry/vx/schema/openvx-1-0.xsd
101  * \ingroup group_xml
102  */
103 VX_API_ENTRY vx_status VX_API_CALL vxExportToXML(vx_context context, vx_char xmlfile[]);
104 
105 
106 /*! \brief Imports all framework and data objects from an XML file into the given context.
107  * \param [in] context The context to import into.
108  * \param [in] xmlfile The XML file to read.
109  * \note The reference indices in the import object corresponds with the reference numbers in the
110  * XML file. It is assumed that the program has some means to know which references to use from
111  * imported list (either by name: <tt>\ref vxGetImportReferenceByName</tt>, or by index from looking at the XML
112  * file (debug use case): <tt>\ref vxGetImportReferenceByIndex</tt>). Alternativly, the program can use
113  * <tt>\ref vxGetImportReferenceByIndex</tt> in a loop and query each one to understand what was imported. After
114  * all references of interest have been retrieved, this import obects should be released using
115  * <tt>\ref vxReleaseImport</tt>.
116  * \return \ref vx_import object containing references to the imported objects in the context
117  * \see https://www.khronos.org/registry/vx/schema/openvx-1-0.xsd
118  * \ingroup group_xml
119  */
120 VX_API_ENTRY vx_import VX_API_CALL vxImportFromXML(vx_context context, vx_char xmlfile[]);
121 
122 /*! \brief Name a reference
123  * \ingroup group_xml
124  *
125  * This function is used to associate a name to a reference. This name
126  * can be used by the OpenVX implementation in log messages and any
127  * other reporting mechanisms. It is also intended to be used by
128  * <tt>\ref vxGetImportReferenceByName</tt> to retrieve a named reference from
129  * a \ref vx_import object.
130  *
131  * The OpenVX implementation will not check if the name is unique in
132  * the reference scope (context or graph). Several references can then
133  * have the same name.
134  *
135  * \param [in] ref The reference to name.
136  * \param [in] name Pointer to the '\0' terminated string that identifies
137  * the reference.
138  * The string is copied by the function so that it
139  * stays the property of the caller.
140  * NULL means that the reference is not named.
141  * \return A \ref vx_status_e enumeration.
142  * \retval VX_SUCCESS No errors.
143  * \retval VX_ERROR_INVALID_REFERENCE if reference is not valid.
144  */
145 VX_API_ENTRY vx_status VX_API_CALL vxSetReferenceName(vx_reference ref, const vx_char *name);
146 
147 /*! \brief Used to retrieve a reference by name from the import when the name is known beforehand. If
148  * multiple references have the same name, then *any* one of them may be returned.
149  * \param [in] import The reference to the import object.
150  * \param [in] name The reference string name.
151  * \return <tt>\ref vx_reference</tt>
152  * \retval 0 Invalid import object or name does not match a reference in the import object.
153  * \retval * The reference matching the requested name.
154  * \note Use <tt>\ref vxReleaseReference</tt> to release the reference before releasing the context.
155  * \pre <tt>\ref vxImportFromXML</tt>
156  * \ingroup group_xml
157  */
158 VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByName(vx_import import, const vx_char *name);
159 
160 /*! \brief Used to retrieve a reference by the index from the import.
161  * \param [in] import The reference to the import object.
162  * \param [in] index The index of the reference in the import object to return.
163  * \return <tt>\ref vx_reference</tt>
164  * \retval 0 Invalid import object or index.
165  * \retval * The reference at the requested index number.
166  * \note Use <tt>\ref vxQueryImport</tt> with <tt>\ref VX_IMPORT_ATTRIBUTE_COUNT</tt> to retrieve
167  * the upper limit of references in the import.
168  * \note Use <tt>\ref vxReleaseReference</tt> to release the reference before releasing the context.
169  * \pre <tt>\ref vxImportFromXML</tt>
170  * \ingroup group_xml
171  */
172 VX_API_ENTRY vx_reference VX_API_CALL vxGetImportReferenceByIndex(vx_import import, vx_uint32 index);
173 
174 /*! \brief Used to query the import about its properties.
175  * \param [in] import The reference to the import object.
176  * \param [in] attribute The <tt>\ref vx_import_attribute_e</tt> value to query for.
177  * \param [out] ptr The location at which the resulting value will be stored.
178  * \param [in] size The size of the container to which ptr points.
179  * \return A <tt>\ref vx_status_e</tt> enumeration.
180  * \pre <tt>\ref vxImportFromXML</tt>
181  * \ingroup group_xml
182  */
183 VX_API_ENTRY vx_status VX_API_CALL vxQueryImport(vx_import import, vx_enum attribute, void *ptr, vx_size size);
184 
185 /*! \brief Releases a reference to an import object.
186  * Also internally releases its references to its imported objects. These
187  * imported objects may not be garbage collected until their total reference
188  * counts are zero.
189  * \param [in] import The pointer to the import object to release.
190  * \return A <tt>\ref vx_status_e</tt> enumeration.
191  * \retval VX_SUCCESS No errors.
192  * \retval VX_ERROR_INVALID_REFERENCE If import is not a <tt>\ref vx_import</tt>.
193  * \note After returning from this function the reference will be zeroed.
194  * \pre <tt>\ref vxImportFromXML</tt>
195  * \ingroup group_xml
196  */
197 VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import);
198 
199 /*! \brief Releases a reference.
200  * The object may not be garbage collected until its total reference count is zero.
201  * \param [in] ref The pointer to the reference to release.
202  * \return A <tt>\ref vx_status_e</tt> enumeration.
203  * \retval VX_SUCCESS No errors.
204  * \retval VX_ERROR_INVALID_REFERENCE If reference is not a <tt>\ref vx_reference</tt>.
205  * \note After returning from this function the reference will be zeroed.
206  * \pre <tt>\ref vxGetImportReferenceByName</tt> or <tt>\ref vxGetImportReferenceByIndex</tt>
207  * \ingroup group_xml
208  */
209 VX_API_ENTRY vx_status VX_API_CALL vxReleaseReference(vx_reference *ref);
210 
211 #ifdef __cplusplus
212 }
213 #endif
214 
215 #endif
216