/*
* 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_API_H_
#define _OPENVX_API_H_
/*!
* \file
* \brief The API definition for OpenVX.
*/
#ifdef __cplusplus
extern "C" {
#endif
/*==============================================================================
CONTEXT
=============================================================================*/
/*! \brief Creates a \ref vx_context.
* \details This creates a top-level object context for OpenVX.
* \note This is required to do anything else.
* \returns The reference to the implementation context \ref vx_context. Any possible errors
* preventing a successful creation should be checked using \ref vxGetStatus.
* \ingroup group_context
* \post \ref vxReleaseContext
*/
VX_API_ENTRY vx_context VX_API_CALL vxCreateContext(void);
/*! \brief Releases the OpenVX object context.
* \details All reference counted objects are garbage-collected by the return of this call.
* No calls are possible using the parameter context after the context has been
* released until a new reference from \ref vxCreateContext is returned.
* All outstanding references to OpenVX objects from this context are invalid
* after this call.
* \param [in] context The pointer to the reference to the context.
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid \ref vx_context reference.
* \ingroup group_context
* \pre \ref vxCreateContext
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseContext(vx_context *context);
/*! \brief Retrieves the context from any reference from within a context.
* \param [in] reference The reference from which to extract the context.
* \ingroup group_context
* \return The overall context that created the particular
* reference. Any possible errors preventing a successful completion of this function
* should be checked using \ref vxGetStatus.
*/
VX_API_ENTRY vx_context VX_API_CALL vxGetContext(vx_reference reference);
/*! \brief Queries the context for some specific information.
* \param [in] context The reference to the context.
* \param [in] attribute The attribute to query. Use a \ref vx_context_attribute_e.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid \ref vx_context reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \retval VX_ERROR_NOT_SUPPORTED If the attribute is not supported on this implementation.
* \ingroup group_context
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryContext(vx_context context, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Sets an attribute on the context.
* \param [in] context The handle to the overall context.
* \param [in] attribute The attribute to set from \ref vx_context_attribute_e.
* \param [in] ptr The pointer to the data to which to set the attribute.
* \param [in] size The size in bytes of the data to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid \ref vx_context reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \retval VX_ERROR_NOT_SUPPORTED If the attribute is not settable.
* \ingroup group_context
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetContextAttribute(vx_context context, vx_enum attribute, const void *ptr, vx_size size);
/*! \brief Provides a generic API to give platform-specific hints to the implementation.
* \param [in] reference The reference to the object to hint at.
* This could be \ref vx_context, \ref vx_graph, \ref vx_node, \ref vx_image, \ref vx_array, or any other reference.
* \param [in] hint A \ref vx_hint_e \a hint to give to a \ref vx_context. This is a platform-specific optimization or implementation mechanism.
* \param [in] data Optional vendor specific data.
* \param [in] data_size Size of the data structure \p data.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE reference is not a valid \ref vx_reference reference.
* \retval VX_ERROR_NOT_SUPPORTED If the hint is not supported.
* \ingroup group_hint
*/
VX_API_ENTRY vx_status VX_API_CALL vxHint(vx_reference reference, vx_enum hint, const void* data, vx_size data_size);
/*! \brief Provides a generic API to give platform-specific directives to the implementations.
* \param [in] reference The reference to the object to set the directive on.
* This could be \ref vx_context, \ref vx_graph, \ref vx_node, \ref vx_image, \ref vx_array, or any other reference.
* \param [in] directive The directive to set. See \ref vx_directive_e.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE reference is not a valid \ref vx_reference reference.
* \retval VX_ERROR_NOT_SUPPORTED If the directive is not supported.
* \note The performance counter directives are only available for the reference \ref vx_context.
* Error VX_ERROR_NOT_SUPPORTED is returned when used with any other reference.
* \ingroup group_directive
*/
VX_API_ENTRY vx_status VX_API_CALL vxDirective(vx_reference reference, vx_enum directive);
/*! \brief Provides a generic API to return status values from Object constructors if they
* fail.
* \note Users do not need to strictly check every object creator as the errors
* should properly propagate and be detected during verification time or run-time.
* \code
* vx_image img = vxCreateImage(context, 639, 480, VX_DF_IMAGE_UYVY);
* vx_status status = vxGetStatus((vx_reference)img);
* // status == VX_ERROR_INVALID_DIMENSIONS
* vxReleaseImage(&img);
* \endcode
* \pre Appropriate Object Creator function.
* \post Appropriate Object Release function.
* \param [in] reference The reference to check for construction errors.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval * Some error occurred, please check enumeration list and constructor.
* \ingroup group_basic_features
*/
VX_API_ENTRY vx_status VX_API_CALL vxGetStatus(vx_reference reference);
/*!
* \brief Registers user-defined structures to the context.
* \param [in] context The reference to the implementation context.
* \param [in] size The size of user struct in bytes.
* \return A \ref vx_enum value that is a type given to the User
* to refer to their custom structure when declaring a \ref vx_array
* of that structure.
* \retval VX_TYPE_INVALID If the namespace of types has been exhausted.
* \note This call should only be used once within the lifetime of a context for
* a specific structure.
* \ingroup group_adv_array
*/
VX_API_ENTRY vx_enum VX_API_CALL vxRegisterUserStruct(vx_context context, vx_size size);
/*!
* \brief Allocates and registers user-defined kernel enumeration to a context.
* The allocated enumeration is from available pool of 4096 enumerations reserved
* for dynamic allocation from VX_KERNEL_BASE(VX_ID_USER,0).
* \param [in] context The reference to the implementation context.
* \param [out] pKernelEnumId pointer to return \ref vx_enum for user-defined kernel.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE If the context is not a valid \ref vx_context reference.
* \retval VX_ERROR_NO_RESOURCES The enumerations has been exhausted.
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxAllocateUserKernelId(vx_context context, vx_enum * pKernelEnumId);
/*!
* \brief Allocates and registers user-defined kernel library ID to a context.
*
* The allocated library ID is from available pool of library IDs (1..255)
* reserved for dynamic allocation. The returned libraryId can be used by
* user-kernel library developer to specify individual kernel enum IDs in
* a header file, shown below:
* \code
* #define MY_KERNEL_ID1(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 0);
* #define MY_KERNEL_ID2(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 1);
* #define MY_KERNEL_ID3(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 2);
* \endcode
* \param [in] context The reference to the implementation context.
* \param [out] pLibraryId pointer to \ref vx_enum for user-kernel libraryId.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_NO_RESOURCES The enumerations has been exhausted.
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxAllocateUserKernelLibraryId(vx_context context, vx_enum * pLibraryId);
/*! \brief Sets the default target of the immediate mode. Upon successful execution of this
* function any future execution of immediate mode function is attempted on the new default
* target of the context.
* \param [in] context The reference to the implementation context.
* \param [in] target_enum The default immediate mode target enum to be set
* to the \ref vx_context object. Use a \ref vx_target_e.
* \param [in] target_string The target name ASCII string. This contains a valid value
* when target_enum is set to \ref VX_TARGET_STRING, otherwise it is ignored.
* \ingroup group_context
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Default target set; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE If the context is not a valid \ref vx_context reference.
* \retval VX_ERROR_NOT_SUPPORTED If the specified target is not supported in this context.
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetImmediateModeTarget(vx_context context, vx_enum target_enum, const char* target_string);
/*==============================================================================
IMAGE
=============================================================================*/
/*! \brief Creates an opaque reference to an image buffer.
* \details Not guaranteed to exist until the \ref vx_graph containing it has been verified.
* \param [in] context The reference to the implementation context.
* \param [in] width The image width in pixels. The image in the formats of
* \ref VX_DF_IMAGE_NV12, \ref VX_DF_IMAGE_NV21, \ref VX_DF_IMAGE_IYUV,
* \ref VX_DF_IMAGE_UYVY, \ref VX_DF_IMAGE_YUYV must have even width.
* \param [in] height The image height in pixels. The image in the formats of
* \ref VX_DF_IMAGE_NV12, \ref VX_DF_IMAGE_NV21, \ref VX_DF_IMAGE_IYUV
* must have even height.
* \param [in] color The VX_DF_IMAGE (\ref vx_df_image_e) code that represents the format
* of the image and the color space.
* \returns An image reference \ref vx_image. Any possible errors preventing a successful
* creation should be checked using \ref vxGetStatus.
* \see vxMapImagePatch to obtain direct memory access to the image data.
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateImage(vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image color);
/*! \brief Creates an image from another image given a rectangle. This second
* reference refers to the data in the original image. Updates to this image
* updates the parent image. The rectangle must be defined within the pixel space
* of the parent image.
* \param [in] img The reference to the parent image.
* \param [in] rect The region of interest rectangle. Must contain points within
* the parent image pixel space.
* \returns An image reference \ref vx_image to the sub-image. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromROI(vx_image img, const vx_rectangle_t *rect);
/*! \brief Creates a reference to an image object that has a singular,
* uniform value in all pixels. The uniform image created is read-only.
* \param [in] context The reference to the implementation context.
* \param [in] width The image width in pixels. The image in the formats of
* \ref VX_DF_IMAGE_NV12, \ref VX_DF_IMAGE_NV21, \ref VX_DF_IMAGE_IYUV,
* \ref VX_DF_IMAGE_UYVY, \ref VX_DF_IMAGE_YUYV must have even width.
* \param [in] height The image height in pixels. The image in the formats of
* \ref VX_DF_IMAGE_NV12, \ref VX_DF_IMAGE_NV21,
* \ref VX_DF_IMAGE_IYUV must have even height.
* \param [in] color The VX_DF_IMAGE (\ref vx_df_image_e) code that represents the format of the image and the color space.
* \param [in] value The pointer to the pixel value to which to set all pixels. See \ref vx_pixel_value_t.
* \returns An image reference \ref vx_image. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \see vxMapImagePatch to obtain direct memory access to the image data.
* \note \ref vxMapImagePatch and \ref vxUnmapImagePatch may be called with
* a uniform image reference.
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateUniformImage(vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image color, const vx_pixel_value_t *value);
/*! \brief Creates an opaque reference to an image buffer with no direct
* user access. This function allows setting the image width, height, or format.
* \details Virtual data objects allow users to connect various nodes within a
* graph via data references without access to that data, but they also permit the
* implementation to take maximum advantage of possible optimizations. Use this
* API to create a data reference to link two or more nodes together when the
* intermediate data are not required to be accessed by outside entities. This API
* in particular allows the user to define the image format of the data without
* requiring the exact dimensions. Virtual objects are scoped within the graph
* they are declared a part of, and can't be shared outside of this scope.
* All of the following constructions of virtual images are valid.
* \code
* vx_context context = vxCreateContext();
* vx_graph graph = vxCreateGraph(context);
* vx_image virt[] = {
* vxCreateVirtualImage(graph, 0, 0, VX_DF_IMAGE_U8), // no specified dimension
* vxCreateVirtualImage(graph, 320, 240, VX_DF_IMAGE_VIRT), // no specified format
* vxCreateVirtualImage(graph, 640, 480, VX_DF_IMAGE_U8), // no user access
* };
* \endcode
* \param [in] graph The reference to the parent graph.
* \param [in] width The width of the image in pixels. A value of zero informs the interface
* that the value is unspecified. The image in the formats of \ref VX_DF_IMAGE_NV12,
* \ref VX_DF_IMAGE_NV21, \ref VX_DF_IMAGE_IYUV, \ref VX_DF_IMAGE_UYVY,
* \ref VX_DF_IMAGE_YUYV must have even width.
* \param [in] height The height of the image in pixels. A value of zero informs the interface
* that the value is unspecified. The image in the formats of \ref VX_DF_IMAGE_NV12,
* \ref VX_DF_IMAGE_NV21, \ref VX_DF_IMAGE_IYUV must have even height.
* \param [in] color The VX_DF_IMAGE (\ref vx_df_image_e) code that represents the format
* of the image and the color space. A value of \ref VX_DF_IMAGE_VIRT informs the
* interface that the format is unspecified.
* \returns An image reference \ref vx_image. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \note Passing this reference to \ref vxMapImagePatch will return an error.
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateVirtualImage(vx_graph graph, vx_uint32 width, vx_uint32 height, vx_df_image color);
/*! \brief Creates a reference to an image object that was externally allocated.
* \param [in] context The reference to the implementation context.
* \param [in] color See the \ref vx_df_image_e codes. This mandates the
* number of planes needed to be valid in the \a addrs and \a ptrs arrays based on the format given.
* \param [in] addrs[] The array of image patch addressing structures that
* define the dimension and stride of the array of pointers. See note below.
* \param [in] ptrs[] The array of platform-defined references to each plane. See note below.
* \param [in] memory_type \ref vx_memory_type_e. When giving \ref VX_MEMORY_TYPE_HOST
* the \a ptrs array is assumed to be HOST accessible pointers to memory.
* \returns An image reference \ref vx_image. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \note The user must call vxMapImagePatch prior to accessing the pixels of an image, even if the
* image was created via \ref vxCreateImageFromHandle. Reads or writes to memory referenced
* by ptrs[ ] after calling \ref vxCreateImageFromHandle without first calling
* \ref vxMapImagePatch will result in undefined behavior.
* The property of addr[] and ptrs[] arrays is kept by the caller (It means that the implementation will
* make an internal copy of the provided information. \a addr and \a ptrs can then simply be application's
* local variables).
* Only \a dim_x, \a dim_y, \a stride_x and \a stride_y fields of the \ref vx_imagepatch_addressing_t need to be
* provided by the application. Other fields (\a step_x, \a step_y, \a scale_x & \a scale_y) are ignored by this function.
* The layout of the imported memory must follow a row-major order. In other words, \a stride_x should be
* sufficiently large so that there is no overlap between data elements corresponding to different
* pixels, and \a stride_y >= \a stride_x * \a dim_x.
*
* In order to release the image back to the application we should use \ref vxSwapImageHandle.
*
* Import type of the created image is available via the image attribute \ref vx_image_attribute_e parameter.
*
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromHandle(vx_context context, vx_df_image color, const vx_imagepatch_addressing_t addrs[], void *const ptrs[], vx_enum memory_type);
/*! \brief Swaps the image handle of an image previously created from handle.
*
* This function sets the new image handle (i.e. pointer to all image planes)
* and returns the previous one.
*
* Once this function call has completed, the application gets back the
* ownership of the memory referenced by the previous handle. This memory
* contains up-to-date pixel data, and the application can safely reuse or
* release it.
*
* The memory referenced by the new handle must have been allocated
* consistently with the image properties since the import type,
* memory layout and dimensions are unchanged (see addrs, color, and
* memory_type in \ref vxCreateImageFromHandle).
*
* All images created from ROI or channel with this image as parent or ancestor
* will automatically use the memory referenced by the new handle.
*
* The behavior of \ref vxSwapImageHandle when called from a user node is undefined.
* \param [in] image The reference to an image created from handle
* \param [in] new_ptrs[] pointer to a caller owned array that contains
* the new image handle (image plane pointers)
* \arg new_ptrs is non NULL. new_ptrs[i] must be non NULL for each i such as
* 0 < i < nbPlanes, otherwise, this is an error. The address of the storage memory
* for image plane i is set to new_ptrs[i]
* \arg new_ptrs is NULL: the previous image storage memory is reclaimed by the
* caller, while no new handle is provided.
* \param [out] prev_ptrs[] pointer to a caller owned array in which
* the application returns the previous image handle
* \arg prev_ptrs is non NULL. prev_ptrs must have at least as many
* elements as the number of image planes. For each i such as
* 0 < i < nbPlanes , prev_ptrs[i] is set to the address of the previous storage
* memory for plane i.
* \arg prev_ptrs NULL: the previous handle is not returned.
* \param [in] num_planes Number of planes in the image. This must be set equal to the number of planes of the input image.
* The number of elements in new_ptrs and prev_ptrs arrays must be equal to or greater than num_planes.
* If either array has more than num_planes elements, the extra elements are ignored. If either array is smaller
* than num_planes, the results are undefined.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* reference.
* \retval VX_ERROR_INVALID_PARAMETERS The image was not created from handle or
* the content of new_ptrs is not valid.
* \retval VX_FAILURE The image was already being accessed.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxSwapImageHandle(vx_image image, void* const new_ptrs[], void* prev_ptrs[], vx_size num_planes);
/*! \brief Retrieves various attributes of an image.
* \param [in] image The reference to the image to query.
* \param [in] attribute The attribute to query. Use a \ref vx_image_attribute_e.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \retval VX_ERROR_NOT_SUPPORTED If the attribute is not supported on this implementation.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryImage(vx_image image, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Allows setting attributes on the image.
* \param [in] image The reference to the image on which to set the attribute.
* \param [in] attribute The attribute to set. Use a \ref vx_image_attribute_e enumeration.
* \param [in] ptr The pointer to the location from which to read the value.
* \param [in] size The size in bytes of the object pointed to by \a ptr.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetImageAttribute(vx_image image, vx_enum attribute, const void *ptr, vx_size size);
/*! \brief Initialize an image with the given pixel value.
* \param [in] image The reference to the image to initialize.
* \param [in] pixel_value The pointer to the constant pixel value to initialize all image pixels. See \ref vx_pixel_value_t.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors.
* \retval VX_ERROR_INVALID_REFERENCE If the image is a uniform image, a virtual image, or not a \ref vx_image.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \note All pixels of the entire image are initialized to the indicated pixel value, independently from the valid region.
* The valid region of the image is unaffected by this function. The image remains mutable after the call to this function,
* so its pixels and mutable attributes may be changed by subsequent functions.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetImagePixelValues(vx_image image, const vx_pixel_value_t *pixel_value);
/*! \brief Releases a reference to an image object.
* The object may not be garbage collected until its total reference count is zero.
*
* An implementation may defer the actual object destruction after its total
* reference count is zero (potentially until context destruction). Thus,
* releasing an image created from handle
* (see \ref vxCreateImageFromHandle) and all others objects that may
* reference it (nodes, ROI, or channel for instance) are not sufficient to get back the
* ownership of the memory referenced by the current image handle. The only way
* for this is to call \ref vxSwapImageHandle) before releasing the
* image.
*
* \param [in] image The pointer to the image to release.
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseImage(vx_image *image);
/*!
* \brief Accesses a specific indexed pixel in an image patch.
* \param [in] ptr The base pointer of the patch as returned from \ref vxMapImagePatch.
* \param [in] index The 0 based index of the pixel count in the patch. Indexes increase horizontally by 1 then wrap around to the next row.
* \param [in] addr The pointer to the addressing mode information returned from \ref vxMapImagePatch.
* \return void * Returns the pointer to the specified pixel.
* \pre \ref vxMapImagePatch
* \ingroup group_image
*/
VX_API_ENTRY void * VX_API_CALL vxFormatImagePatchAddress1d(void *ptr, vx_uint32 index, const vx_imagepatch_addressing_t *addr);
/*!
* \brief Accesses a specific pixel at a 2d coordinate in an image patch.
* \param [in] ptr The base pointer of the patch as returned from \ref vxMapImagePatch.
* \param [in] x The x dimension within the patch.
* \param [in] y The y dimension within the patch.
* \param [in] addr The pointer to the addressing mode information returned from \ref vxMapImagePatch.
* \return void * Returns the pointer to the specified pixel.
* \pre \ref vxMapImagePatch
* \ingroup group_image
*/
VX_API_ENTRY void * VX_API_CALL vxFormatImagePatchAddress2d(void *ptr, vx_uint32 x, vx_uint32 y, const vx_imagepatch_addressing_t *addr);
/*! \brief Retrieves the valid region of the image as a rectangle.
* \param [in] image The image from which to retrieve the valid region.
* \param [out] rect The destination rectangle.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS Invalid rect.
* \note This rectangle can be passed directly to \ref vxMapImagePatch to get
* the full valid region of the image.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxGetValidRegionImage(vx_image image, vx_rectangle_t *rect);
/*! \brief Allows the application to copy a rectangular patch from/into an image object plane.
* \param [in] image The reference to the image object that is the source or the
* destination of the copy.
* \param [in] image_rect The coordinates of the image patch. The patch must be within
* the bounds of the image. (start_x, start_y) gives the coordinates of the topleft
* pixel inside the patch, while (end_x, end_y) gives the coordinates of the bottomright
* element out of the patch. Must be 0 <= start < end <= number of pixels in the image dimension.
* \param [in] image_plane_index The plane index of the image object that is the source or the
* destination of the patch copy.
* \param [in] user_addr The address of a structure describing the layout of the
* user memory location pointed by user_ptr. In the structure, only dim_x, dim_y,
* stride_x and stride_y fields must be provided, other fields are ignored by the function.
* The layout of the user memory must follow a row major order:
* stride_x >= pixel size in bytes, and stride_y >= stride_x * dim_x.
* \param [in] user_ptr The address of the memory location where to store the requested data
* if the copy was requested in read mode, or from where to get the data to store into the image
* object if the copy was requested in write mode. The accessible memory must be large enough
* to contain the specified patch with the specified layout:
* accessible memory in bytes >= (end_y - start_y) * stride_y.
* \param [in] usage This declares the effect of the copy with regard to the image object
* using the \ref vx_accessor_e enumeration. For uniform images, only VX_READ_ONLY
* is supported. For other images, Only \ref VX_READ_ONLY and \ref VX_WRITE_ONLY are supported:
* \arg \ref VX_READ_ONLY means that data is copied from the image object into the application memory
* \arg \ref VX_WRITE_ONLY means that data is copied into the image object from the application memory
* \param [in] user_mem_type A \ref vx_memory_type_e enumeration that specifies
* the memory type of the memory referenced by the user_addr.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_OPTIMIZED_AWAY This is a reference to a virtual image that cannot be
* accessed by the application.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \note The application may ask for data outside the bounds of the valid region, but
* such data has an undefined value.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxCopyImagePatch(vx_image image, const vx_rectangle_t *image_rect, vx_uint32 image_plane_index, const vx_imagepatch_addressing_t *user_addr, void * user_ptr, vx_enum usage, vx_enum user_mem_type);
/*! \brief Allows the application to get direct access to a rectangular patch of an image object plane.
* \param [in] image The reference to the image object that contains the patch to map.
* \param [in] rect The coordinates of image patch. The patch must be within the
* bounds of the image. (start_x, start_y) gives the coordinate of the topleft
* element inside the patch, while (end_x, end_y) give the coordinate of
* the bottomright element out of the patch. Must be 0 <= start < end.
* \param [in] plane_index The plane index of the image object to be accessed.
* \param [out] map_id The address of a \ref vx_map_id variable where the function
* returns a map identifier.
* \arg (*map_id) must eventually be provided as the map_id parameter of a call to
* \ref vxUnmapImagePatch.
* \param [out] addr The address of a structure describing the memory layout of the
* image patch to access. The function fills the structure pointed by addr with the
* layout information that the application must consult to access the pixel data
* at address (*ptr). The layout of the mapped memory follows a row-major order:
* stride_x>0, stride_y>0 and stride_y >= stride_x * dim_x.
* If the image object being accessed was created via
* \ref vxCreateImageFromHandle, then the returned memory layout will be
* the identical to that of the addressing structure provided when
* \ref vxCreateImageFromHandle was called.
* \param [out] ptr The address of a pointer that the function sets to the
* address where the requested data can be accessed. This returned (*ptr) address
* is only valid between the call to this function and the corresponding call to
* \ref vxUnmapImagePatch.
* If image was created via \ref vxCreateImageFromHandle then the returned
* address (*ptr) will be the address of the patch in the original pixel buffer
* provided when image was created.
* \param [in] usage This declares the access mode for the image patch, using
* the \ref vx_accessor_e enumeration. For uniform images, only VX_READ_ONLY
* is supported.
* \arg \ref VX_READ_ONLY: after the function call, the content of the memory location
* pointed by (*ptr) contains the image patch data. Writing into this memory location
* is forbidden and its behavior is undefined.
* \arg \ref VX_READ_AND_WRITE: after the function call, the content of the memory
* location pointed by (*ptr) contains the image patch data; writing into this memory
* is allowed only for the location of pixels only and will result in a modification
* of the written pixels in the image object once the patch is unmapped. Writing into
* a gap between pixels (when addr->stride_x > pixel size in bytes or addr->stride_y > addr->stride_x*addr->dim_x)
* is forbidden and its behavior is undefined.
* \arg \ref VX_WRITE_ONLY: after the function call, the memory location pointed by (*ptr)
* contains undefined data; writing each pixel of the patch is required prior to
* unmapping. Pixels not written by the application before unmap will become
* undefined after unmap, even if they were well defined before map. Like for
* VX_READ_AND_WRITE, writing into a gap between pixels is forbidden and its behavior
* is undefined.
* \param [in] mem_type A \ref vx_memory_type_e enumeration that
* specifies the type of the memory where the image patch is requested to be mapped.
* \param [in] flags An integer that allows passing options to the map operation.
* Use the \ref vx_map_flag_e enumeration.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_OPTIMIZED_AWAY This is a reference to a virtual image that cannot be
* accessed by the application.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \note The user may ask for data outside the bounds of the valid region, but
* such data has an undefined value.
* \ingroup group_image
* \post \ref vxUnmapImagePatch with same (*map_id) value.
*/
VX_API_ENTRY vx_status VX_API_CALL vxMapImagePatch(vx_image image, const vx_rectangle_t *rect, vx_uint32 plane_index, vx_map_id *map_id, vx_imagepatch_addressing_t *addr, void **ptr, vx_enum usage, vx_enum mem_type, vx_uint32 flags);
/*! \brief Unmap and commit potential changes to a image object patch that were previously mapped.
* Unmapping an image patch invalidates the memory location from which the patch could
* be accessed by the application. Accessing this memory location after the unmap function
* completes has an undefined behavior.
* \param [in] image The reference to the image object to unmap.
* \param [out] map_id The unique map identifier that was returned by \ref vxMapImagePatch .
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \ingroup group_image
* \pre \ref vxMapImagePatch with same map_id value
*/
VX_API_ENTRY vx_status VX_API_CALL vxUnmapImagePatch(vx_image image, vx_map_id map_id);
/*! \brief Create a sub-image from a single plane channel of another image.
*
* The sub-image refers to the data in the original image. Updates to this image
* update the parent image and reversely.
*
* The function supports only channels that occupy an entire plane of a multi-planar
* images, as listed below. Other cases are not supported.
* VX_CHANNEL_Y from YUV4, IYUV, NV12, NV21
* VX_CHANNEL_U from YUV4, IYUV
* VX_CHANNEL_V from YUV4, IYUV
*
* \param [in] img The reference to the parent image.
* \param [in] channel The \ref vx_channel_e channel to use.
* \returns An image reference \ref vx_image to the sub-image. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \ingroup group_image
*/
VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromChannel(vx_image img, vx_enum channel);
/*! \brief Sets the valid rectangle for an image according to a supplied rectangle.
* \note Setting or changing the valid region from within a user node by means other than the call-back, for
* example by calling \ref vxSetImageValidRectangle, might result in an incorrect valid region calculation
* by the framework.
* \param [in] image The reference to the image.
* \param [in] rect The value to be set to the image valid rectangle. A NULL indicates that the valid region is the entire image.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid \ref vx_image reference.
* \retval VX_ERROR_INVALID_PARAMETERS The rect does not define a proper valid rectangle.
* \ingroup group_image
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetImageValidRectangle(vx_image image, const vx_rectangle_t *rect);
/*==============================================================================
KERNEL
=============================================================================*/
/*! \brief Loads a library of kernels, called module, into a context.
*
* The module must be a dynamic library with by convention, two exported functions
* named vxPublishKernels and vxUnpublishKernels.
*
* vxPublishKernels must have type \ref vx_publish_kernels_f,
* and must add kernels to the context by calling \ref vxAddUserKernel
* for each new kernel. vxPublishKernels is called by \ref vxLoadKernels.
*
* vxUnpublishKernels must have type \ref vx_unpublish_kernels_f,
* and must remove kernels from the context by calling \ref vxRemoveKernel
* for each kernel the vxPublishKernels has added.
* vxUnpublishKernels is called by \ref vxUnloadKernels.
*
* \note When all references to loaded kernels are released, the module
* may be automatically unloaded.
* \param [in] context The reference to the context the kernels must be added to.
* \param [in] module The short name of the module to load. On systems where
* there are specific naming conventions for modules, the name passed
* should ignore such conventions. For example: \c libxyz.so should be
* passed as just \c xyz and the implementation will do the right thing that
* the platform requires.
* \note This API uses the system pre-defined paths for modules.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid \ref vx_context reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \ingroup group_user_kernels
* \see vxGetKernelByName
*/
VX_API_ENTRY vx_status VX_API_CALL vxLoadKernels(vx_context context, const vx_char *module);
/*! \brief Unloads all kernels from the OpenVX context that had been loaded from
* the module using the \ref vxLoadKernels function.
*
* The kernel unloading is performed by calling the vxUnpublishKernels
* exported function of the module.
* \note vxUnpublishKernels is defined in the description of
* \ref vxLoadKernels.
*
* \param [in] context The reference to the context the kernels must be removed from.
* \param [in] module The short name of the module to unload. On systems where
* there are specific naming conventions for modules, the name passed
* should ignore such conventions. For example: \c libxyz.so should be
* passed as just \c xyz and the implementation will do the right thing
* that the platform requires.
* \note This API uses the system pre-defined paths for modules.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid \ref vx_context reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are
incorrect.
* \ingroup group_user_kernels
* \see vxLoadKernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxUnloadKernels(vx_context context, const vx_char *module);
/*! \brief Obtains a reference to a kernel using a string to specify the name.
* \details User Kernels follow a "dotted" heirarchical syntax. For example:
* "com.company.example.xyz". The following are strings specifying the kernel names:
* org.khronos.openvx.color_convert
* org.khronos.openvx.channel_extract
* org.khronos.openvx.channel_combine
* org.khronos.openvx.sobel_3x3
* org.khronos.openvx.magnitude
* org.khronos.openvx.phase
* org.khronos.openvx.scale_image
* org.khronos.openvx.table_lookup
* org.khronos.openvx.histogram
* org.khronos.openvx.equalize_histogram
* org.khronos.openvx.absdiff
* org.khronos.openvx.mean_stddev
* org.khronos.openvx.threshold
* org.khronos.openvx.integral_image
* org.khronos.openvx.dilate_3x3
* org.khronos.openvx.erode_3x3
* org.khronos.openvx.median_3x3
* org.khronos.openvx.box_3x3
* org.khronos.openvx.gaussian_3x3
* org.khronos.openvx.custom_convolution
* org.khronos.openvx.gaussian_pyramid
* org.khronos.openvx.accumulate
* org.khronos.openvx.accumulate_weighted
* org.khronos.openvx.accumulate_square
* org.khronos.openvx.minmaxloc
* org.khronos.openvx.convertdepth
* org.khronos.openvx.canny_edge_detector
* org.khronos.openvx.and
* org.khronos.openvx.or
* org.khronos.openvx.xor
* org.khronos.openvx.not
* org.khronos.openvx.multiply
* org.khronos.openvx.add
* org.khronos.openvx.subtract
* org.khronos.openvx.warp_affine
* org.khronos.openvx.warp_perspective
* org.khronos.openvx.harris_corners
* org.khronos.openvx.fast_corners
* org.khronos.openvx.optical_flow_pyr_lk
* org.khronos.openvx.remap
* org.khronos.openvx.halfscale_gaussian
* org.khronos.openvx.laplacian_pyramid
* org.khronos.openvx.laplacian_reconstruct
* org.khronos.openvx.non_linear_filter
* org.khronos.openvx.match_template
* org.khronos.openvx.lbp
* org.khronos.openvx.hough_lines_p
* org.khronos.openvx.tensor_multiply
* org.khronos.openvx.tensor_add
* org.khronos.openvx.tensor_subtract
* org.khronos.openvx.tensor_table_lookup
* org.khronos.openvx.tensor_transpose
* org.khronos.openvx.tensor_convert_depth
* org.khronos.openvx.tensor_matrix_multiply
* org.khronos.openvx.copy
* org.khronos.openvx.non_max_suppression
* org.khronos.openvx.scalar_operation
* org.khronos.openvx.hog_features
* org.khronos.openvx.hog_cells
* org.khronos.openvx.bilateral_filter
* org.khronos.openvx.select
* org.khronos.openvx.min
* org.khronos.openvx.max
* \param [in] context The reference to the implementation context.
* \param [in] name The string of the name of the kernel to get.
* \return A kernel reference. Any possible errors preventing a successful
* completion of the function should be checked using \ref vxGetStatus.
* \ingroup group_kernel
* \pre \ref vxLoadKernels if the kernel is not provided by the
* OpenVX implementation.
* \note User Kernels should follow a "dotted" hierarchical syntax. For example:
* "com.company.example.xyz".
*/
VX_API_ENTRY vx_kernel VX_API_CALL vxGetKernelByName(vx_context context, const vx_char *name);
/*! \brief Obtains a reference to the kernel using the \ref vx_kernel_e enumeration.
* \details Enum values above the standard set are assumed to apply to
* loaded libraries.
* \param [in] context The reference to the implementation context.
* \param [in] kernel A value from \ref vx_kernel_e or a vendor or client-defined value.
* \return A \ref vx_kernel reference. Any possible errors preventing a successful completion
* of the function should be checked using \ref vxGetStatus.
* \ingroup group_kernel
* \pre \ref vxLoadKernels if the kernel is not provided by the
* OpenVX implementation.
*/
VX_API_ENTRY vx_kernel VX_API_CALL vxGetKernelByEnum(vx_context context, vx_enum kernel);
/*! \brief This allows the client to query the kernel to get information about
* the number of parameters, enum values, etc.
* \param [in] kernel The kernel reference to query.
* \param [in] attribute The attribute to query. Use a \ref vx_kernel_attribute_e.
* \param [out] ptr The pointer to the location at which to store the resulting value.
* \param [in] size The size of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \retval VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
* \retval VX_ERROR_NOT_SUPPORTED If the attribute value is not supported in this implementation.
* \ingroup group_kernel
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryKernel(vx_kernel kernel, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Release the reference to the kernel.
* The object may not be garbage collected until its total reference count is zero.
* \param [in] kernel The pointer to the kernel reference to release.
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \ingroup group_kernel
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseKernel(vx_kernel *kernel);
/*! \brief Allows users to add custom kernels to a context at run-time.
* \param [in] context The reference to the context the kernel must be added to.
* \param [in] name The string to use to match the kernel.
* \param [in] enumeration The enumerated value of the kernel to be used by clients.
* \param [in] func_ptr The process-local function pointer to be invoked.
* \param [in] numParams The number of parameters for this kernel.
* \param [in] validate The pointer to \ref vx_kernel_validate_f, which validates
* parameters to this kernel.
* \param [in] init The kernel initialization function.
* \param [in] deinit The kernel de-initialization function.
* \return A \ref vx_kernel reference. Any possible errors
* preventing a successful creation should be checked using \ref vxGetStatus.
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_kernel VX_API_CALL vxAddUserKernel(vx_context context,
const vx_char name[VX_MAX_KERNEL_NAME],
vx_enum enumeration,
vx_kernel_f func_ptr,
vx_uint32 numParams,
vx_kernel_validate_f validate,
vx_kernel_initialize_f init,
vx_kernel_deinitialize_f deinit);
/*! \brief This API is called after all parameters have been added to the
* kernel and the kernel is \e ready to be used. Notice that the reference to the kernel created
* by vxAddUserKernel is still valid after the call to vxFinalizeKernel.
* If an error occurs, the kernel is not available for usage by the clients of OpenVX. Typically
* this is due to a mismatch between the number of parameters requested and given.
* \param [in] kernel The reference to the loaded kernel from \ref vxAddUserKernel.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \pre \ref vxAddUserKernel and \ref vxAddParameterToKernel
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxFinalizeKernel(vx_kernel kernel);
/*! \brief Allows users to set the signatures of the custom kernel.
* \param [in] kernel The reference to the kernel added with \ref vxAddUserKernel.
* \param [in] index The index of the parameter to add.
* \param [in] dir The direction of the parameter. This must be either \ref VX_INPUT or
* \ref VX_OUTPUT. \ref VX_BIDIRECTIONAL is not supported for this function.
* \param [in] data_type The type of parameter. This must be a value from \ref vx_type_e.
* \param [in] state The state of the parameter (required or not). This must be a value from \ref vx_parameter_state_e.
* \return A \ref vx_status_e enumerated value.
* \retval VX_SUCCESS Parameter is successfully set on kernel; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \retval VX_ERROR_INVALID_PARAMETERS If the parameter is not valid for any reason.
* \pre \ref vxAddUserKernel
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxAddParameterToKernel(vx_kernel kernel, vx_uint32 index, vx_enum dir, vx_enum data_type, vx_enum state);
/*! \brief Removes a custom kernel from its context and releases it.
* \param [in] kernel The reference to the kernel to remove. Returned from \ref vxAddUserKernel.
* \note Any kernel enumerated in the base standard
* cannot be removed; only kernels added through \ref vxAddUserKernel can
* be removed.
* \return A \ref vx_status_e enumeration. The function returns to the
* application full control over the memory resources provided at the kernel creation time.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \retval VX_ERROR_INVALID_PARAMETERS If a base kernel is passed in.
* \retval VX_FAILURE If the application has not released all references to the kernel
* object OR if the application has not released all references to a node that is using
* this kernel OR if the application has not released all references to a graph which
* has nodes that is using this kernel.
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxRemoveKernel(vx_kernel kernel);
/*! \brief Sets kernel attributes.
* \param [in] kernel The reference to the kernel.
* \param [in] attribute The enumeration of the attributes. See \ref vx_kernel_attribute_e.
* \param [in] ptr The pointer to the location from which to read the attribute.
* \param [in] size The size in bytes of the data area indicated by \a ptr in bytes.
* \note After a kernel has been passed to \ref vxFinalizeKernel, no attributes
* can be altered.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid \ref vx_kernel reference.
* \ingroup group_user_kernels
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetKernelAttribute(vx_kernel kernel, vx_enum attribute, const void *ptr, vx_size size);
/*! \brief Retrieves a \ref vx_parameter from a \ref vx_kernel.
* \param [in] kernel The reference to the kernel.
* \param [in] index The index of the parameter.
* \return A \ref vx_parameter reference. Any possible errors preventing a
* successful completion of the function should be checked using \ref vxGetStatus.
* \ingroup group_parameter
*/
VX_API_ENTRY vx_parameter VX_API_CALL vxGetKernelParameterByIndex(vx_kernel kernel, vx_uint32 index);
/*==============================================================================
GRAPH
=============================================================================*/
/*! \brief Creates an empty graph.
* \param [in] context The reference to the implementation context.
* \returns A graph reference \ref vx_graph. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \ingroup group_graph
*/
VX_API_ENTRY vx_graph VX_API_CALL vxCreateGraph(vx_context context);
/*! \brief Releases a reference to a graph.
* The object may not be garbage collected until its total reference count is zero.
* Once the reference count is zero, all node references in the graph are automatically
* released as well. Releasing the graph will only release the nodes if the nodes were
* not previously released by the application. Data referenced by those nodes may not
* be released as the user may still have references to the data.
* \param [in] graph The pointer to the graph to release.
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseGraph(vx_graph *graph);
/*! \brief Verifies the state of the graph before it is executed.
* This is useful to catch programmer errors and contract errors. If not verified,
* the graph verifies before being processed.
* \pre Memory for data objects is not guarenteed to exist before
* this call. \post After this call data objects exist unless
* the implementation optimized them out.
* \param [in] graph The reference to the graph to verify.
* \return A status code for graphs with more than one error; it is
* undefined which error will be returned. Register a log callback using \ref vxRegisterLogCallback
* to receive each specific error in the graph.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \retval VX_ERROR_MULTIPLE_WRITERS If the graph contains more than one writer
* to any data object.
* \retval VX_ERROR_INVALID_NODE If a node in the graph is invalid or failed be created.
* \retval VX_ERROR_INVALID_GRAPH If the graph contains cycles or some other invalid topology.
* \retval VX_ERROR_INVALID_TYPE If any parameter on a node is given the wrong type.
* \retval VX_ERROR_INVALID_VALUE If any value of any parameter is out of bounds of specification.
* \retval VX_ERROR_INVALID_FORMAT If the image format is not compatible.
* \ingroup group_graph
* \see vxProcessGraph
*/
VX_API_ENTRY vx_status VX_API_CALL vxVerifyGraph(vx_graph graph);
/*! \brief This function causes the synchronous processing of a graph. If the graph
* has not been verified, then the implementation verifies the graph
* immediately. If verification fails this function returns a status
* identical to what \ref vxVerifyGraph would return. After
* the graph verfies successfully then processing occurs. If the graph was
* previously verified via \ref vxVerifyGraph or \ref vxProcessGraph
* then the graph is processed. This function blocks until the graph is completed.
* \param [in] graph The graph to execute.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Graph has been processed; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \retval VX_FAILURE A catastrophic error occurred during processing.
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxProcessGraph(vx_graph graph);
/*! \brief Schedules a graph for future execution. If the graph
* has not been verified, then the implementation verifies the graph
* immediately. If verification fails this function returns a status
* identical to what \ref vxVerifyGraph would return. After
* the graph verfies successfully then processing occurs. If the graph was
* previously verified via \ref vxVerifyGraph or \ref vxProcessGraph
* then the graph is processed.
* \param [in] graph The graph to schedule.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS The graph has been scheduled; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \retval VX_ERROR_NO_RESOURCES The graph cannot be scheduled now.
* \retval VX_ERROR_NOT_SUFFICIENT The graph is not verified and has failed
* forced verification.
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxScheduleGraph(vx_graph graph);
/*! \brief Waits for a specific graph to complete. If the graph has been scheduled multiple
* times since the last call to vxWaitGraph, then vxWaitGraph returns only when the last
* scheduled execution completes.
* \param [in] graph The graph to wait on.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS The graph has successfully completed execution and its outputs are the
* valid results of the most recent execution; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \retval VX_FAILURE An error occurred or the graph was never scheduled. Output data of the
* graph is undefined.
* \pre \ref vxScheduleGraph
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxWaitGraph(vx_graph graph);
/*! \brief Allows the user to query attributes of the Graph.
* \param [in] graph The reference to the created graph.
* \param [in] attribute The \ref vx_graph_attribute_e type needed.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryGraph(vx_graph graph, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Allows the attributes of the Graph to be set to the provided value.
* \param [in] graph The reference to the graph.
* \param [in] attribute The \ref vx_graph_attribute_e type needed.
* \param [in] ptr The location from which to read the value.
* \param [in] size The size in bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference.
* \ingroup group_graph
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetGraphAttribute(vx_graph graph, vx_enum attribute, const void *ptr, vx_size size);
/*! \brief Adds the given parameter extracted from a \ref vx_node to the graph.
* \param [in] graph The graph reference that contains the node.
* \param [in] parameter The parameter reference to add to the graph from the node.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Parameter added to Graph; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference or parameter is not a valid \ref vx_parameter reference.
* \retval VX_ERROR_INVALID_PARAMETERS The parameter is of a node not in this
* graph.
* \ingroup group_graph_parameters
*/
VX_API_ENTRY vx_status VX_API_CALL vxAddParameterToGraph(vx_graph graph, vx_parameter parameter);
/*! \brief Sets a reference to the parameter on the graph. The implementation
* must set this parameter on the originating node as well.
* \param [in] graph The graph reference.
* \param [in] index The parameter index.
* \param [in] value The reference to set to the parameter.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Parameter set to Graph; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference or
* value is not a valid \ref vx_reference.
* \retval VX_ERROR_INVALID_PARAMETERS The parameter index is out of bounds or the
* dir parameter is incorrect.
* \ingroup group_graph_parameters
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetGraphParameterByIndex(vx_graph graph, vx_uint32 index, vx_reference value);
/*! \brief Retrieves a \ref vx_parameter from a \ref vx_graph.
* \param [in] graph The graph.
* \param [in] index The index of the parameter.
* \return \ref vx_parameter reference. Any possible errors preventing a successful
* function completion should be checked using \ref vxGetStatus.
* \ingroup group_graph_parameters
*/
VX_API_ENTRY vx_parameter VX_API_CALL vxGetGraphParameterByIndex(vx_graph graph, vx_uint32 index);
/*! \brief Returns a Boolean to indicate the state of graph verification.
* \param [in] graph The reference to the graph to check.
* \return A \ref vx_bool value.
* \retval vx_true_e The graph is verified.
* \retval vx_false_e The graph is not verified. It must be verified before
* execution either through \ref vxVerifyGraph or automatically through
* \ref vxProcessGraph or \ref vxScheduleGraph.
* \ingroup group_graph
*/
VX_API_ENTRY vx_bool VX_API_CALL vxIsGraphVerified(vx_graph graph);
/*==============================================================================
NODE
=============================================================================*/
/*! \brief Creates a reference to a node object for a given kernel.
* \details This node has no references assigned as parameters after completion.
* The client is then required to set these parameters manually by \ref vxSetParameterByIndex.
* When clients supply their own node creation functions (for use with User Kernels), this is the API
* to use along with the parameter setting API.
* \param [in] graph The reference to the graph in which this node exists.
* \param [in] kernel The kernel reference to associate with this new node.
* \returns A node reference \ref vx_node. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
* \note A call to this API sets all parameters to NULL.
* \ingroup group_adv_node
* \post Call \ref vxSetParameterByIndex for as many parameters as needed to be set.
*/
VX_API_ENTRY vx_node VX_API_CALL vxCreateGenericNode(vx_graph graph, vx_kernel kernel);
/*! \brief Allows a user to query information out of a node.
* \param [in] node The reference to the node to query.
* \param [in] attribute Use \ref vx_node_attribute_e value to query for information.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytesin bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
* \retval VX_ERROR_INVALID_PARAMETERS The type or size is incorrect.
* \ingroup group_node
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryNode(vx_node node, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Allows a user to set attribute of a node before Graph Validation.
* \param [in] node The reference to the node to set.
* \param [in] attribute Use \ref vx_node_attribute_e value to set the desired attribute.
* \param [in] ptr The pointer to the desired value of the attribute.
* \param [in] size The size in bytes of the objects to which \a ptr points.
* \note Some attributes are inherited from the \ref vx_kernel, which was used
* to create the node. Some of these can be overridden using this API, notably
* \ref VX_NODE_LOCAL_DATA_SIZE and \ref VX_NODE_LOCAL_DATA_PTR.
* \ingroup group_node
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS The attribute was set; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
* \retval VX_ERROR_INVALID_PARAMETERS size is not correct for the type needed.
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetNodeAttribute(vx_node node, vx_enum attribute, const void *ptr, vx_size size);
/*! \brief Releases a reference to a Node object.
* The object may not be garbage collected until its total reference count is zero.
* \param [in] node The pointer to the reference of the node to release.
* \ingroup group_node
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseNode(vx_node *node);
/*! \brief Removes a Node from its parent Graph and releases it.
* \param [in] node The pointer to the node to remove and release.
* \ingroup group_node
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
*/
VX_API_ENTRY vx_status VX_API_CALL vxRemoveNode(vx_node *node);
/*! \brief Assigns a callback to a node.
* If a callback already exists in this node, this function must return an error
* and the user may clear the callback by passing a NULL pointer as the callback.
* \param [in] node The reference to the node.
* \param [in] callback The callback to associate with completion of this
* specific node.
* \warning This must be used with extreme caution as it can \e ruin
* optimizations in the power/performance efficiency of a graph.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Callback assigned; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
* \ingroup group_node_callback
*/
VX_API_ENTRY vx_status VX_API_CALL vxAssignNodeCallback(vx_node node, vx_nodecomplete_f callback);
/*! \brief Retrieves the current node callback function pointer set on the node.
* \param [in] node The reference to the \ref vx_node object.
* \ingroup group_node_callback
* \return vx_nodecomplete_f The pointer to the callback function.
* \retval NULL No callback is set.
* \retval * The node callback function.
*/
VX_API_ENTRY vx_nodecomplete_f VX_API_CALL vxRetrieveNodeCallback(vx_node node);
/*! \brief Sets the node target to the provided value. A success invalidates the graph
* that the node belongs to (\ref vxVerifyGraph must be called before the next execution)
* \param [in] node The reference to the \ref vx_node object.
* \param [in] target_enum The target enum to be set to the \ref vx_node object.
* Use a \ref vx_target_e.
* \param [in] target_string The target name ASCII string. This contains a valid value
* when target_enum is set to \ref VX_TARGET_STRING, otherwise it is ignored.
* \ingroup group_node
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS Node target set; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference.
* \retval VX_ERROR_NOT_SUPPORTED If the node kernel is not supported by the specified target.
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetNodeTarget(vx_node node, vx_enum target_enum, const char* target_string);
/*! \brief Creates replicas of the same node first_node to process a set of objects
* stored in \ref vx_pyramid or \ref vx_object_array.
* first_node needs to have as parameter levels 0 of a \ref vx_pyramid or the index 0 of a \ref vx_object_array.
* Replica nodes are not accessible by the application through any means. An application request for removal of
* first_node from the graph will result in removal of all replicas. Any change of parameter or attribute of
* first_node will be propagated to the replicas. \ref vxVerifyGraph shall enforce consistency of parameters and attributes
* in the replicas.
* \param [in] graph The reference to the graph.
* \param [in] first_node The reference to the node in the graph that will be replicated.
* \param [in] replicate an array of size equal to the number of node parameters, vx_true_e for the parameters
* that should be iterated over (should be a reference to a vx_pyramid or a vx_object_array),
* vx_false_e for the parameters that should be the same across replicated nodes and for optional
* parameters that are not used. Should be vx_true_e for all output and bidirectional parameters.
* \param [in] number_of_parameters number of elements in the replicate array
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid \ref vx_graph reference, or first_node is not a
* valid \ref vx_node reference.
* \retval VX_ERROR_NOT_COMPATIBLE At least one of replicated parameters is not of level 0 of a pyramid or at index 0 of an object array.
* \retval VX_FAILURE If the node does not belong to the graph, or the number of objects in the parent objects of inputs and output are not the same.
* \ingroup group_node
*/
VX_API_ENTRY vx_status VX_API_CALL vxReplicateNode(vx_graph graph, vx_node first_node, vx_bool replicate[], vx_uint32 number_of_parameters);
/*==============================================================================
PARAMETER
=============================================================================*/
/*! \brief Retrieves a \ref vx_parameter from a \ref vx_node.
* \param [in] node The node from which to extract the parameter.
* \param [in] index The index of the parameter to which to get a reference.
* \return A parameter reference \ref vx_parameter. Any possible errors preventing a successful
* completion of the function should be checked using \ref vxGetStatus.
* \ingroup group_parameter
*/
VX_API_ENTRY vx_parameter VX_API_CALL vxGetParameterByIndex(vx_node node, vx_uint32 index);
/*! \brief Releases a reference to a parameter object.
* The object may not be garbage collected until its total reference count is zero.
* \param [in] param The pointer to the parameter to release.
* \ingroup group_parameter
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE param is not a valid \ref vx_parameter reference.
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseParameter(vx_parameter *param);
/*! \brief Sets the specified parameter data for a kernel on the node.
* \param [in] node The node that contains the kernel.
* \param [in] index The index of the parameter desired.
* \param [in] value The desired value of the parameter.
* \note A user may not provide a NULL value for a mandatory parameter of this API.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE node is not a valid \ref vx_node reference, or value
* is not a valid \ref vx_reference reference.
* \ingroup group_parameter
* \see vxSetParameterByReference
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetParameterByIndex(vx_node node, vx_uint32 index, vx_reference value);
/*! \brief Associates a parameter reference and a data reference with a kernel
* on a node.
* \param [in] parameter The reference to the kernel parameter.
* \param [in] value The value to associate with the kernel parameter.
* \note A user may not provide a NULL value for a mandatory parameter of this API.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE parameter is not a valid \ref vx_parameter reference,
* or value is not a valid \ref vx_reference reference..
* \ingroup group_parameter
* \see vxGetParameterByIndex
*/
VX_API_ENTRY vx_status VX_API_CALL vxSetParameterByReference(vx_parameter parameter, vx_reference value);
/*! \brief Allows the client to query a parameter to determine its meta-information.
* \param [in] parameter The reference to the parameter.
* \param [in] attribute The attribute to query. Use a \ref vx_parameter_attribute_e.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytes of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE parameter is not a valid \ref vx_parameter reference.
* \ingroup group_parameter
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryParameter(vx_parameter parameter, vx_enum attribute, void *ptr, vx_size size);
/*==============================================================================
SCALAR
=============================================================================*/
/*! \brief Creates a reference to a scalar object. Also see \ref sub_node_parameters.
* \param [in] context The reference to the system context.
* \param [in] data_type The type of data to hold. Must be greater than
* \ref VX_TYPE_INVALID and less than or equal to \ref VX_TYPE_VENDOR_STRUCT_END.
* Or must be a \ref vx_enum returned from \ref vxRegisterUserStruct.
* \param [in] ptr The pointer to the initial value of the scalar.
* \ingroup group_scalar
* \returns A scalar reference \ref vx_scalar. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
*/
VX_API_ENTRY vx_scalar VX_API_CALL vxCreateScalar(vx_context context, vx_enum data_type, const void *ptr);
/*! \brief Creates a reference to a scalar object. Also see \ref sub_node_parameters.
* \param [in] context The reference to the system context.
* \param [in] data_type The type of data to hold. Must be greater than
* \ref VX_TYPE_INVALID and less than or equal to \ref VX_TYPE_VENDOR_STRUCT_END.
* Or must be a \ref vx_enum returned from \ref vxRegisterUserStruct.
* \param [in] ptr The pointer to the initial value of the scalar.
* \param [in] size Size of data at ptr in bytes.
* \ingroup group_scalar
* \returns A scalar reference \ref vx_scalar. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
*/
VX_API_ENTRY vx_scalar VX_API_CALL vxCreateScalarWithSize(vx_context context, vx_enum data_type, const void *ptr, vx_size size);
/*! \brief Creates an opaque reference to a scalar object with no direct user access.
* \param [in] graph The reference to the parent graph.
* \param [in] data_type The type of data to hold. Must be greater than
* \ref VX_TYPE_INVALID and less than or equal to \ref VX_TYPE_VENDOR_STRUCT_END.
* Or must be a \ref vx_enum returned from \ref vxRegisterUserStruct.
* \see \ref vxCreateScalar
* \ingroup group_scalar
* \returns A scalar reference \ref vx_scalar. Any possible errors preventing a
* successful creation should be checked using \ref vxGetStatus.
*/
VX_API_ENTRY vx_scalar VX_API_CALL vxCreateVirtualScalar(vx_graph graph, vx_enum data_type);
/*! \brief Releases a reference to a scalar object.
* The object may not be garbage collected until its total reference count is zero.
* \param [in] scalar The pointer to the scalar to release.
* \ingroup group_scalar
* \post After returning from this function the reference is zeroed.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE scalar is not a valid \ref vx_scalar reference.
*/
VX_API_ENTRY vx_status VX_API_CALL vxReleaseScalar(vx_scalar *scalar);
/*! \brief Queries attributes from a scalar.
* \param [in] scalar The scalar object.
* \param [in] attribute The enumeration to query. Use a \ref vx_scalar_attribute_e enumeration.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size of the container to which \a ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE scalar is not a valid \ref vx_scalar reference.
* \ingroup group_scalar
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryScalar(vx_scalar scalar, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Allows the application to copy from/into a scalar object.
* \param [in] scalar The reference to the scalar object that is the source or the
* destination of the copy.
* \param [in] user_ptr The address of the memory location where to store the requested data
* if the copy was requested in read mode, or from where to get the data to store into the
* scalar object if the copy was requested in write mode. In the user memory, the scalar is
* a variable of the type corresponding to \ref VX_SCALAR_TYPE.
* The accessible memory must be large enough to contain this variable.
* \param [in] usage This declares the effect of the copy with regard to the scalar object
* using the \ref vx_accessor_e enumeration. Only \ref VX_READ_ONLY and \ref VX_WRITE_ONLY
* are supported:
* \arg \ref VX_READ_ONLY means that data are copied from the scalar object into the user memory.
* \arg \ref VX_WRITE_ONLY means that data are copied into the scalar object from the user memory.
* \param [in] user_mem_type A \ref vx_memory_type_e enumeration that specifies
* the memory type of the memory referenced by the user_addr.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE scalar is not a valid \ref vx_scalar reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \ingroup group_scalar
*/
VX_API_ENTRY vx_status VX_API_CALL vxCopyScalar(vx_scalar scalar, void *user_ptr, vx_enum usage, vx_enum user_mem_type);
/*! \brief Allows the application to copy from/into a scalar object with size.
* \param [in] scalar The reference to the scalar object that is the source or the
* destination of the copy.
* \param [in] size The size in bytes of the container to which \a user_ptr points.
* \param [in] user_ptr The address of the memory location where to store the requested data
* if the copy was requested in read mode, or from where to get the data to store into the
* scalar object if the copy was requested in write mode. In the user memory, the scalar is
* a variable of the type corresponding to \ref VX_SCALAR_TYPE.
* The accessible memory must be large enough to contain this variable.
* \param [in] usage This declares the effect of the copy with regard to the scalar object
* using the \ref vx_accessor_e enumeration. Only \ref VX_READ_ONLY and \ref VX_WRITE_ONLY
* are supported:
* \arg \ref VX_READ_ONLY means that data are copied from the scalar object into the user memory.
* \arg \ref VX_WRITE_ONLY means that data are copied into the scalar object from the user memory.
* \param [in] user_mem_type A \ref vx_memory_type_e enumeration that specifies
* the memory type of the memory referenced by the user_addr.
* \return A \ref vx_status_e enumeration.
* \retval VX_ERROR_INVALID_REFERENCE The scalar reference is not actually a scalar reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \ingroup group_scalar
*/
VX_API_ENTRY vx_status VX_API_CALL vxCopyScalarWithSize(vx_scalar scalar, vx_size size, void *user_ptr, vx_enum usage, vx_enum user_mem_type);
/*==============================================================================
REFERENCE
=============================================================================*/
/*! \brief Queries any reference type for some basic information like count or type.
* \param [in] ref The reference to query.
* \param [in] attribute The value for which to query. Use \ref vx_reference_attribute_e.
* \param [out] ptr The location at which to store the resulting value.
* \param [in] size The size in bytes of the container to which ptr points.
* \return A \ref vx_status_e enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE ref is not a valid \ref vx_reference reference.
* \ingroup group_reference
*/
VX_API_ENTRY vx_status VX_API_CALL vxQueryReference(vx_reference ref, vx_enum attribute, void *ptr, vx_size size);
/*! \brief Releases a reference. The reference may potentially refer to multiple OpenVX objects of different types.
* This function can be used instead of calling a specific release function for each individual object type
* (e.g. vxRelease