This repository has been archived by the owner on Feb 16, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 53
/
vx_api.h
3162 lines (2899 loc) · 182 KB
/
vx_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* 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 <tt>\ref vx_context</tt>.
* \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 <tt>\ref vx_context</tt>. Any possible errors
* preventing a successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \ingroup group_context
* \post <tt>\ref vxReleaseContext</tt>
*/
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 <tt>\ref vxCreateContext</tt> 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid <tt>\ref vx_context</tt> reference.
* \ingroup group_context
* \pre <tt>\ref vxCreateContext</tt>
*/
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 <tt>\ref vxGetStatus</tt>.
*/
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 <tt>\ref vx_context_attribute_e</tt>.
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid <tt>\ref vx_context</tt> 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 <tt>\ref vx_context_attribute_e</tt>.
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid <tt>\ref vx_context</tt> 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 <tt>\ref vx_context</tt>, <tt>\ref vx_graph</tt>, <tt>\ref vx_node</tt>, <tt>\ref vx_image</tt>, <tt>\ref vx_array</tt>, or any other reference.
* \param [in] hint A <tt>\ref vx_hint_e</tt> \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE reference is not a valid <tt>\ref vx_reference</tt> 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 <tt>\ref vx_context</tt>, <tt>\ref vx_graph</tt>, <tt>\ref vx_node</tt>, <tt>\ref vx_image</tt>, <tt>\ref vx_array</tt>, or any other reference.
* \param [in] directive The directive to set. See <tt>\ref vx_directive_e</tt>.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE reference is not a valid <tt>\ref vx_reference</tt> 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 <tt>\ref vx_status_e</tt> 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 <tt>\ref vx_enum</tt> value that is a type given to the User
* to refer to their custom structure when declaring a <tt>\ref vx_array</tt>
* 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 <tt>\ref vx_enum</tt> 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 <tt>\ref vx_context</tt> 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 <tt>\ref vx_enum</tt> 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 <tt>\ref vx_context</tt> object. Use a <tt>\ref vx_target_e</tt>.
* \param [in] target_string The target name ASCII string. This contains a valid value
* when target_enum is set to <tt>\ref VX_TARGET_STRING</tt>, otherwise it is ignored.
* \ingroup group_context
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS Default target set; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE If the context is not a valid <tt>\ref vx_context</tt> 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 <tt>\ref vx_graph</tt> 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
* <tt>\ref VX_DF_IMAGE_NV12</tt>, <tt>\ref VX_DF_IMAGE_NV21</tt>, <tt>\ref VX_DF_IMAGE_IYUV</tt>,
* <tt>\ref VX_DF_IMAGE_UYVY</tt>, <tt>\ref VX_DF_IMAGE_YUYV</tt> must have even width.
* \param [in] height The image height in pixels. The image in the formats of
* <tt>\ref VX_DF_IMAGE_NV12</tt>, <tt>\ref VX_DF_IMAGE_NV21</tt>, <tt>\ref VX_DF_IMAGE_IYUV</tt>
* must have even height.
* \param [in] color The VX_DF_IMAGE (<tt>\ref vx_df_image_e</tt>) code that represents the format
* of the image and the color space.
* \returns An image reference <tt>\ref vx_image</tt>. Any possible errors preventing a successful
* creation should be checked using <tt>\ref vxGetStatus</tt>.
* \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 <tt>\ref vx_image</tt> to the sub-image. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \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
* <tt>\ref VX_DF_IMAGE_NV12</tt>, <tt>\ref VX_DF_IMAGE_NV21</tt>, <tt>\ref VX_DF_IMAGE_IYUV</tt>,
* <tt>\ref VX_DF_IMAGE_UYVY</tt>, <tt>\ref VX_DF_IMAGE_YUYV</tt> must have even width.
* \param [in] height The image height in pixels. The image in the formats of
* <tt>\ref VX_DF_IMAGE_NV12</tt>, <tt>\ref VX_DF_IMAGE_NV21</tt>,
* <tt>\ref VX_DF_IMAGE_IYUV</tt> 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 <tt>\ref vx_pixel_value_t</tt>.
* \returns An image reference <tt>\ref vx_image</tt>. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* <tt>\see vxMapImagePatch</tt> to obtain direct memory access to the image data.
* \note <tt>\ref vxMapImagePatch</tt> and <tt>\ref vxUnmapImagePatch</tt> 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 <tt>\ref VX_DF_IMAGE_NV12</tt>,
* <tt>\ref VX_DF_IMAGE_NV21</tt>, <tt>\ref VX_DF_IMAGE_IYUV</tt>, <tt>\ref VX_DF_IMAGE_UYVY</tt>,
* <tt>\ref VX_DF_IMAGE_YUYV</tt> 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 <tt>\ref VX_DF_IMAGE_NV12</tt>,
* <tt>\ref VX_DF_IMAGE_NV21</tt>, <tt>\ref VX_DF_IMAGE_IYUV</tt> must have even height.
* \param [in] color The VX_DF_IMAGE (<tt>\ref vx_df_image_e</tt>) code that represents the format
* of the image and the color space. A value of <tt>\ref VX_DF_IMAGE_VIRT</tt> informs the
* interface that the format is unspecified.
* \returns An image reference <tt>\ref vx_image</tt>. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \note Passing this reference to <tt>\ref vxMapImagePatch</tt> 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 <tt>\ref vx_df_image_e</tt> 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 <tt>\ref vx_memory_type_e</tt>. When giving <tt>\ref VX_MEMORY_TYPE_HOST</tt>
* the \a ptrs array is assumed to be HOST accessible pointers to memory.
* \returns An image reference <tt>\ref vx_image</tt>. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \note The user must call vxMapImagePatch prior to accessing the pixels of an image, even if the
* image was created via <tt>\ref vxCreateImageFromHandle</tt>. Reads or writes to memory referenced
* by ptrs[ ] after calling <tt>\ref vxCreateImageFromHandle</tt> without first calling
* <tt>\ref vxMapImagePatch</tt> 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 <tt>\ref vx_imagepatch_addressing_t</tt> 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 <tt>\ref vxSwapImageHandle</tt>.
*
* Import type of the created image is available via the image attribute <tt>\ref vx_image_attribute_e</tt> 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 <tt>\ref vxCreateImageFromHandle</tt>).
*
* 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 <tt>\ref vxSwapImageHandle</tt> 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> 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 <tt>\ref vx_image_attribute_e</tt>.
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> 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 <tt>\ref vx_image_attribute_e</tt> 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> 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 <tt>\ref vx_pixel_value_t</tt>.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors.
* \retval VX_ERROR_INVALID_REFERENCE If the image is a uniform image, a virtual image, or not a <tt>\ref vx_image</tt>.
* \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 <tt>\ref vxCreateImageFromHandle</tt>) 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 <tt>\ref vxSwapImageHandle</tt>) 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> 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 <tt>\ref vxMapImagePatch</tt>.
* \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 <tt>\ref vxMapImagePatch</tt>.
* \return void * Returns the pointer to the specified pixel.
* \pre <tt>\ref vxMapImagePatch</tt>
* \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 <tt>\ref vxMapImagePatch</tt>.
* \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 <tt>\ref vxMapImagePatch</tt>.
* \return void * Returns the pointer to the specified pixel.
* \pre <tt>\ref vxMapImagePatch</tt>
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> reference.
* \retval VX_ERROR_INVALID_PARAMETERS Invalid rect.
* \note This rectangle can be passed directly to <tt>\ref vxMapImagePatch</tt> 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 <tt>\ref vx_accessor_e</tt> enumeration. For uniform images, only VX_READ_ONLY
* is supported. For other images, Only <tt>\ref VX_READ_ONLY</tt> and <tt>\ref VX_WRITE_ONLY</tt> are supported:
* \arg <tt>\ref VX_READ_ONLY</tt> means that data is copied from the image object into the application memory
* \arg <tt>\ref VX_WRITE_ONLY</tt> means that data is copied into the image object from the application memory
* \param [in] user_mem_type A <tt>\ref vx_memory_type_e</tt> enumeration that specifies
* the memory type of the memory referenced by the user_addr.
* \return A <tt>\ref vx_status_e</tt> 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 <tt>\ref vx_image</tt> 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 <tt>\ref vx_map_id</tt> variable where the function
* returns a map identifier.
* \arg (*map_id) must eventually be provided as the map_id parameter of a call to
* <tt>\ref vxUnmapImagePatch</tt>.
* \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
* <tt>\ref vxCreateImageFromHandle</tt>, then the returned memory layout will be
* the identical to that of the addressing structure provided when
* <tt>\ref vxCreateImageFromHandle</tt> 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
* <tt>\ref vxUnmapImagePatch</tt>.
* If image was created via <tt>\ref vxCreateImageFromHandle</tt> 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 <tt>\ref vx_accessor_e</tt> enumeration. For uniform images, only VX_READ_ONLY
* is supported.
* \arg <tt>\ref VX_READ_ONLY</tt>: 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 <tt>\ref VX_READ_AND_WRITE</tt>: 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 <tt>\ref VX_WRITE_ONLY</tt>: 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 <tt>\ref vx_memory_type_e</tt> 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 <tt>\ref vx_map_flag_e</tt> enumeration.
* \return A <tt>\ref vx_status_e</tt> 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 <tt>\ref vx_image</tt> 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 <tt>\ref vxUnmapImagePatch </tt> 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 <tt>\ref vxMapImagePatch</tt> .
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> reference.
* \retval VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
* \ingroup group_image
* \pre <tt>\ref vxMapImagePatch</tt> 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 <tt>\ref vx_channel_e</tt> channel to use.
* \returns An image reference <tt>\ref vx_image</tt> to the sub-image. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \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 <tt>\ref vxSetImageValidRectangle</tt>, 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE image is not a valid <tt>\ref vx_image</tt> 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 <tt>vxPublishKernels</tt> and <tt>vxUnpublishKernels</tt>.
*
* <tt>vxPublishKernels</tt> must have type <tt>\ref vx_publish_kernels_f</tt>,
* and must add kernels to the context by calling <tt>\ref vxAddUserKernel</tt>
* for each new kernel. <tt>vxPublishKernels</tt> is called by <tt>\ref vxLoadKernels</tt>.
*
* <tt>vxUnpublishKernels</tt> must have type <tt>\ref vx_unpublish_kernels_f</tt>,
* and must remove kernels from the context by calling <tt>\ref vxRemoveKernel</tt>
* for each kernel the <tt>vxPublishKernels</tt> has added.
* <tt>vxUnpublishKernels</tt> is called by <tt>\ref vxUnloadKernels</tt>.
*
* \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 <i>do the right thing</i> that
* the platform requires.
* \note This API uses the system pre-defined paths for modules.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid <tt>\ref vx_context</tt> 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 <tt>vxUnpublishKernels</tt>
* exported function of the module.
* \note <tt>vxUnpublishKernels</tt> is defined in the description of
* <tt>\ref vxLoadKernels</tt>.
*
* \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 <i>do the right thing</i>
* that the platform requires.
* \note This API uses the system pre-defined paths for modules.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE context is not a valid <tt>\ref vx_context</tt> 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 <tt>\ref vxGetStatus</tt>.
* \ingroup group_kernel
* \pre <tt>\ref vxLoadKernels</tt> 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 <tt>\ref vx_kernel_e</tt> 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 <tt>\ref vx_kernel_e</tt> or a vendor or client-defined value.
* \return A <tt>\ref vx_kernel</tt> reference. Any possible errors preventing a successful completion
* of the function should be checked using <tt>\ref vxGetStatus</tt>.
* \ingroup group_kernel
* \pre <tt>\ref vxLoadKernels</tt> 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 <tt>\ref vx_kernel_attribute_e</tt>.
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid <tt>\ref vx_kernel</tt> 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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid <tt>\ref vx_kernel</tt> 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 <tt>\ref vx_kernel_validate_f</tt>, which validates
* parameters to this kernel.
* \param [in] init The kernel initialization function.
* \param [in] deinit The kernel de-initialization function.
* \return A <tt>\ref vx_kernel</tt> reference. Any possible errors
* preventing a successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \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 <tt>\ref vxAddUserKernel</tt>.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid <tt>\ref vx_kernel</tt> reference.
* \pre <tt>\ref vxAddUserKernel</tt> and <tt>\ref vxAddParameterToKernel</tt>
* \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 <tt>\ref vxAddUserKernel</tt>.
* \param [in] index The index of the parameter to add.
* \param [in] dir The direction of the parameter. This must be either <tt>\ref VX_INPUT</tt> or
* <tt>\ref VX_OUTPUT</tt>. <tt>\ref VX_BIDIRECTIONAL</tt> is not supported for this function.
* \param [in] data_type The type of parameter. This must be a value from <tt>\ref vx_type_e</tt>.
* \param [in] state The state of the parameter (required or not). This must be a value from <tt>\ref vx_parameter_state_e</tt>.
* \return A <tt>\ref vx_status_e</tt> 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 <tt>\ref vx_kernel</tt> reference.
* \retval VX_ERROR_INVALID_PARAMETERS If the parameter is not valid for any reason.
* \pre <tt>\ref vxAddUserKernel</tt>
* \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 <tt>\ref vxAddUserKernel</tt>.
* \note Any kernel enumerated in the base standard
* cannot be removed; only kernels added through <tt>\ref vxAddUserKernel</tt> can
* be removed.
* \return A <tt>\ref vx_status_e</tt> 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 <tt>\ref vx_kernel</tt> 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 <tt>\ref vx_kernel_attribute_e</tt>.
* \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 <tt>\ref vxFinalizeKernel</tt>, no attributes
* can be altered.
* \return A <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE kernel is not a valid <tt>\ref vx_kernel</tt> 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 <tt>\ref vx_parameter</tt> from a <tt>\ref vx_kernel</tt>.
* \param [in] kernel The reference to the kernel.
* \param [in] index The index of the parameter.
* \return A <tt>\ref vx_parameter</tt> reference. Any possible errors preventing a
* successful completion of the function should be checked using <tt>\ref vxGetStatus</tt>.
* \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 <tt>\ref vx_graph</tt>. Any possible errors preventing a
* successful creation should be checked using <tt>\ref vxGetStatus</tt>.
* \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 <tt>\ref vx_status_e</tt> enumeration.
* \retval VX_SUCCESS No errors; any other value indicates failure.
* \retval VX_ERROR_INVALID_REFERENCE graph is not a valid <tt>\ref vx_graph</tt> 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,