/* * Copyright (c) 2012-2017 The Khronos Group Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef _OPENVX_IMPORT_EXPORT_H_ #define _OPENVX_IMPORT_EXPORT_H_ /*! * \file * \brief The OpenVX Export and Import extension API. */ #define OPENVX_KHR_IX "vx_khr_ix" #include #ifdef __cplusplus extern "C" { #endif /*============================================================================= Export to host memory =============================================================================*/ /*! \brief Exports selected objects to memory in a vendor-specific format.\n * * \details A list of references in the given context is supplied to this function, and all information * required to re-create these is stored in memory in such a way that those objects may be re-created * with the corresponding import function, according to the usage specified by the *uses* parameter[*REQ*].\n * The information must be context independent in that it may be written to external storage for later * retreival with another instantiation of a compatible implementation[*REQ*].\n * The list of objects to export may contain only valid references (i.e. vxGetStatus() will return VX_SUCCESS) * to vx_graph and non-virtual data objects or the function will fail[*REQ*]. * (Specifically not vx_context, vx_import, vx_node, vx_kernel, vx_parameter or vx_meta_format)\n * Some node creation functions take C parameters rather than OpenVX data objects (such as the *gradient_size* * parameter of \ref vxHarrisCornersNode that is provided as a vx_int32), because these are intended * to be fixed at node creation time; nevertheless OpenVX data objects may be assigned to them, for example if * the \ref vxCreateGenericNode API is used. * A data object corresponding to a node parameter that is intended to be fixed at node creation time must not be * in the list of exported objects nor attached as a graph parameter or the export operation will fail[*REQ*].\n * The *uses* array specifies how the objects in the corresponding *refs* array will be exported. A data object * will always have its meta-data (e.g. dimensions and format of an image) exported, and optionally * may have its data (e.g. pixel values) exported, and additionally you can decide whether the importing * application will create data objects to replace those attached to graphs, or if the implementation will * automatically create them: * - \ref VX_IX_USE_APPLICATION_CREATE \n * Export sufficient data to check that an application-supplied * object is compatible when the data is later imported[*REQ*]. * \note This value must be given for images created from handles, or the the export operation * will fail[*REQ*] * - \ref VX_IX_USE_EXPORT_VALUES\n * Export complete information (for example image data or value of a * scalar)[*REQ*]. * - \ref VX_IX_USE_NO_EXPORT_VALUES\n * Export meta-data only; the importing application will set values * as applicable[*REQ*] * * The values in *uses* are applicable only for data objects and are ignored for vx_graph objects[*REQ*].\n * 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 * \note The implementation may also choose to re-verify any previously verified graphs and apply * optimisations based upon which references are to be exported and how.\n * Any data objects attached to a graph that are hidden, i.e. their references are not in the list *refs*, * may be treated by the implementation as virtual objects, since they can never be visible when the graph is * subsequently imported.\n * Note that imported graphs cannot become unverified. Attempts to change the * graph that might normally cause the graph to be unverified, e.g. calling * vxSetGraphParameterByIndex with an object with different metadata, will fail.\n * The implementation should make sure that all permissible changes of exported objects are possible * without re-verification. For example: * - A uniform image may be swapped for a non-uniform image, so corresponding optimisations should be * inhibited if a uniform image appears in the *refs* list * - An image that is a region of interest of another image may be similarly replaced by any other image of * matching size and format, and vice-versa * * If a graph is exported that has delays registered for auto-aging, then this information is also * exported[*REQ*].\n * If the function is called with NULL for any of its parameters, this is an error [*REQ*].\n * The reference counts of objects as visible to the calling application will not be affected * by calling this function [*REQ*].\n * The export operation will fail if more than one object whose reference is listed at *refs* * has been given the same non-zero length name (via \ref vxSetReferenceName)[*REQ*].\n * If a graph listed for export has any graph parameters not listed at *refs*, then the * export operation will fail[*REQ*]. * \note The order of the references supplied in the *refs* array will be the order in which the * framwork will supply references for the corresponding import operation with \ref vxImportObjectsFromMemory.\n * The same length of *uses* array, containing the same values, and the same value of *numrefs*, must be supplied * for the corresponding import operation. * * For objects not listed in *refs*, the following rules apply: * 1. In any one graph, if an object is not connected as an output of a node in a graph being exported * then its data values will be exported (for subsequent import)[*REQ*]. * 2. Where the object in (1) is a composite object (such as a pyramid) then rule (1) applies to * all of its sub-objects[*REQ*]. * 3. Where the object in (1) is a sub-object such as a region of interest, and the composite object * (in this case the parent image) does not meet the conditions of rule (1), then rule (1) applies * to the sub-object only[*REQ*]. * \param [in] context context from which to export objects, must be valid [*REQ*]. * \param [in] numrefs number of references to export [*REQ*]. * \param [in] refs references to export. This is an array of length numrefs populated with * the references to export[*REQ*]. * \param [in] uses how to export the references. This is an array of length numrefs containing * values as described above[*REQ*]. * \param [out] ptr returns pointer to binary buffer. On error this is set to NULL[*REQ*]. * \param [out] length number of bytes at \*ptr. On error this is set to zero[*REQ*]. * \return A \ref vx_status value. * \retval VX_SUCCESS If no errors occurred and the objects were sucessfully exported[*REQ*]. * An error is indicated when the return value is not VX_SUCCESS.\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 * possible recovery mechanisms, and for safety critical use assume errors are not recoverable. * \post \ref vxReleaseExportedMemory is used to deallocate the memory. * \ingroup group_import */ 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); /*! \brief Releases memory allocated for a binary export when it is no longer required. * \details This function releases memory allocated by \ref vxExportObjectsToMemory[*REQ*]. * \param [in] context The context for which \ref vxExportObjectsToMemory was called[*REQ*]. * \param [in,out] ptr A pointer previously set by calling \ref vxExportObjectsToMemory[*REQ*]. * The function will fail if *ptr does not contain an address of memory previously * allocated by \ref vxExportObjectsToMemory[*REQ*]. * \post After returning from sucessfully from this function \*ptr is set to NULL[*REQ*]. * \return A \ref vx_status value. * \retval VX_SUCCESS If no errors occurred and the memory 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 * possible recovery mechanisms, and for safety critical use assume errors are not recoverable. * \pre \ref vxExportObjectsToMemory is used to allocate the memory. * \ingroup group_import */ VX_API_ENTRY vx_status VX_API_CALL vxReleaseExportedMemory( vx_context context, const vx_uint8 ** ptr); #ifdef __cplusplus } #endif #endif