OpenVX User Kernel Tiling Extension  r29628
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
vx_khr_tiling.h
1 /*
2  * Copyright (c) 2012-2014 The Khronos Group Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and/or associated documentation files (the
6  * "Materials"), to deal in the Materials without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Materials, and to
9  * permit persons to whom the Materials are furnished to do so, subject to
10  * the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included
13  * in all copies or substantial portions of the Materials.
14  *
15  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
22  */
23 
24 #ifndef _VX_KHR_TILING_H_
25 #define _VX_KHR_TILING_H_
26 
27 /*!
28  * \file
29  * \brief The Khronos Extension for User Tiling Functions.
30  * \author Erik Rainey <erik.rainey@gmail.com>
31  * \author Shorin Kyo <shorin.kyo.wz@renasas.com>
32  * \author Thierry Lepley <thierry.lepley@st.com>
33  * \author Frank Brill <fbrill@nvidia.com>
34  *
35  * \defgroup group_tiling Extension: User Tiling API
36  * \brief The Khronos Extension for User Tiling Functions.
37  */
38 
39 #define OPENVX_KHR_TILING "vx_khr_tiling"
40 
41 #if defined(OPENVX_TILING_1_0)
42 #undef OPENVX_TILING_1_1
43 #endif
44 
45 #include <VX/vx.h>
46 
47 /*! \def VX_RESTRICT
48  * \brief A platform wrapper for the restrict keyword.
49  * \ingroup group_tiling
50  */
51 #if defined(WIN32)
52 #define VX_RESTRICT
53 #else
54 #if defined(__cplusplus) || defined(ANDROID)
55 #define VX_RESTRICT __restrict
56 #else
57 #define VX_RESTRICT restrict
58 #endif
59 #endif
60 
61 /*! \brief The User Tiling Function tile block size declaration.
62  * \details The author of a User Tiling Kernel will use this structure to define
63  * the dimensionality of the tile block.
64  * \ingroup group_tiling
65  */
66 typedef struct _vx_tile_block_size_t {
67  vx_int32 width; /*!< \brief Tile block width in pixels. */
68  vx_int32 height; /*!< \brief Tile block height in pixels. */
70 
71 /*! \brief The User Tiling Function Neighborhood declaration.
72  * \details The author of a User Tiling Kernel will use this structure to define
73  * the neighborhood surrounding the tile block.
74  * \ingroup group_tiling
75  */
76 typedef struct _vx_neighborhood_size_t {
77  vx_int32 left; /*!< \brief Left of the tile block. */
78  vx_int32 right; /*!< \brief Right of the tile block. */
79  vx_int32 top; /*!< \brief Top of the tile block. */
80  vx_int32 bottom; /*!< \brief Bottom of the tile block. */
82 
83 /*! \brief A structure which describes the tile's parent image.
84  * \ingroup group_tiling
85  */
86 typedef struct _vx_image_description_t {
87  vx_uint32 width; /*!< \brief Width of the image */
88  vx_uint32 height; /*!< \brief Height of the image */
89  vx_df_image format; /*!< \brief The <tt>\ref vx_df_image_e</tt> of the image */
90  vx_uint32 planes; /*!< \brief The number of planes in the image */
91  vx_enum range; /*!< \brief The <tt>\ref vx_channel_range_e</tt> enumeration. */
92  vx_enum space; /*!< \brief The <tt>\ref vx_color_space_e</tt> enumeration. */
94 
95 /*! \brief The maximum number of planes in a tiled image.
96  * \ingroup group_tiling
97  */
98 #define VX_MAX_TILING_PLANES (4)
99 
100 /*! \brief The tile structure declaration.
101  * \ingroup group_tiling
102  */
103 typedef struct _vx_tile_t {
104  /*! \brief The array of pointers to the tile's image plane. */
106  /*! \brief The top left X pixel index within the width dimension of the image. */
107  vx_uint32 tile_x;
108  /*! \brief The top left Y pixel index within the height dimension of the image. */
109  vx_uint32 tile_y;
110  /*! \brief The array of addressing structure to describe each plane. */
111  vx_imagepatch_addressing_t addr[VX_MAX_TILING_PLANES];
112  /*! \brief The output block size structure. */
114  /*! \brief The neighborhood definition. */
116  /*! \brief The description and attributes of the image. */
118 } vx_tile_t;
119 
120 #ifndef VX_TILE_ATTRIBUTES_DEFINITIONS
121 
122 /*!
123  * \brief The full height of the tile's parent image in pixels.
124  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
125  * \ingroup group_tiling
126  */
127 #define vxImageHeight(ptile) ((ptile))->image.height)
128 
129 /*!
130  * \brief The full width of the tile's parent image in pixels.
131  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
132  * \ingroup group_tiling
133  */
134 #define vxImageWidth(ptile) ((ptile))->image.width)
135 
136 /*!
137  * \brief The offset between the left edge of the image and the left edge of the tile, in pixels.
138  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
139  * \ingroup group_tiling
140  */
141 #define vxTileX(ptile) ((ptile)->tile_x)
142 
143 /*!
144  * \brief The offset between the top edge of the image and the top edge of the tile, in pixels.
145  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
146  * \ingroup group_tiling
147  */
148 #define vxTileY(ptile) ((ptile)->tile_y)
149 
150 /*!
151  * \brief The width of the tile in pixels.
152  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
153  * \param [in] index The plane index.
154  * \ingroup group_tiling
155  */
156 #define vxTileWidth(ptile, index) ((ptile)->addr[index].dim_x)
157 
158 /*!
159  * \brief The height of the tile in pixels.
160  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
161  * \param [in] index The plane index.
162  * \ingroup group_tiling
163  */
164 #define vxTileHeight(ptile, index) ((ptile)->addr[index].dim_y)
165 
166 /*!
167  * \brief The tile block height.
168  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
169  * \ingroup group_tiling
170  */
171 #define vxTileBlockHeight(ptile) ((ptile)->tile_block.height)
172 
173 /*!
174  * \brief The tile block width.
175  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
176  * \ingroup group_tiling
177  */
178 #define vxTileBlockWidth(ptile) ((ptile)->tile_block.width)
179 
180 /*!
181  * \brief The simple wrapper to access each image's neighborhood -X value.
182  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
183  * \ingroup group_tiling
184  */
185 #define vxNeighborhoodLeft(ptile) ((ptile)->neighborhood.left)
186 
187 /*!
188  * \brief The simple wrapper to access each image's neighborhood +X value.
189  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
190  * \ingroup group_tiling
191  */
192 #define vxNeighborhoodRight(ptile) ((ptile)->neighborhood.right)
193 
194 /*!
195  * \brief The simple wrapper to access each image's neighborhood -Y value.
196  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
197  * \ingroup group_tiling
198  */
199 #define vxNeighborhoodTop(ptile) ((ptile)->neighborhood.top)
200 
201 /*!
202  * \brief The simple wrapper to access each image's neighborhood +Y value.
203  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
204  * \ingroup group_tiling
205  */
206 #define vxNeighborhoodBottom(ptile) ((ptile)->neighborhood.bottom)
207 
208 #if 0
209 /*!
210  * \brief The simple wrapper to access each image's stride X value.
211  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
212  * \ingroup group_tiling
213  */
214 #define vxStrideSizeX(ptile, index) ((ptile)->addr[index].stride_x)
215 
216 /*!
217  * \brief The simple wrapper to access each image's stride Y value.
218  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
219  * \ingroup group_tiling
220  */
221 #define vxStrideSizeY(ptile, index) ((ptile)->addr[index].stride_y)
222 
223 /*!
224  * \brief The simple wrapper to access each image's step X value.
225  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
226  * \ingroup group_tiling
227  */
228 #define vxStepSizeX(ptile, index) ((ptile)->addr[index].step_x)
229 
230 /*!
231  * \brief The simple wrapper to access each image's step Y value.
232  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
233  * \ingroup group_tiling
234  */
235 #define vxStepSizeY(ptile, index) ((ptile)->addr[index].step_y)
236 #endif
237 
238 #endif
239 
240 /*! \brief The User Kernel Tiling Attributes.
241  * \ingroup group_tiling
242  */
244  /*! \brief This allows a tiling mode kernel to set its input neighborhood. */
245  VX_KERNEL_ATTRIBUTE_INPUT_NEIGHBORHOOD = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0x7,
246  /*! \brief This allows a tiling mode kernel to set its output tile block size. */
247  VX_KERNEL_ATTRIBUTE_OUTPUT_TILE_BLOCK_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0x8,
248  /*! \brief This allows the author to set the border mode on the tiling kernel. */
249  VX_KERNEL_ATTRIBUTE_BORDER = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0x9,
250  /*! \brief This determines the per tile memory allocation. */
251  VX_KERNEL_ATTRIBUTE_TILE_MEMORY_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0xA,
252 #if defined(OPENVX_TILING_1_1)
253  /*! \brief This allows a tiling mode kernel to set its input tile block size. */
254  VX_KERNEL_ATTRIBUTE_INPUT_TILE_BLOCK_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0xB,
255  /*! \brief This allows a tiling mode kernel to set its output neighborhood. */
256  VX_KERNEL_ATTRIBUTE_OUTPUT_NEIGHBORHOOD = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_KERNEL) + 0xC,
257 #endif
258 };
259 
260 /*! \brief The User Node Tiling Attributes.
261  * \note These are largely unusable by the tiling function, as it doesn't give you the node reference!
262  * \ingroup group_tiling
263  */
265  /*! \brief This allows a tiling mode node to get its input neighborhood. */
266  VX_NODE_ATTRIBUTE_INPUT_NEIGHBORHOOD = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0x7,
267  /*! \brief This allows a tiling mode node to get its output tile block size. */
268  VX_NODE_ATTRIBUTE_OUTPUT_TILE_BLOCK_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0x8,
269  /*! \brief This is the size of the tile local memory area. */
270  VX_NODE_ATTRIBUTE_TILE_MEMORY_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0xA,
271 #if defined(OPENVX_TILING_1_1)
272  /*! \brief This allows a tiling mode node to get its input tile block size. */
273  VX_NODE_ATTRIBUTE_INPUT_TILE_BLOCK_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0xB,
274  /*! \brief This allows a tiling mode node to get its output neighborhood. */
275  VX_NODE_ATTRIBUTE_OUTPUT_NEIGHBORHOOD = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_NODE) + 0xC,
276 #endif
277 };
278 
279 /*! \brief The tiling border mode extensions
280  * \ingroup group_tiling
281  */
283  /*! \brief This value indicates that the author of the tiling kernel wrote
284  * code to handle border conditions into the kernel itself. If this mode
285  * is set, it can not be overriden by a call to the \ref vxSetNodeAttribute
286  * with \ref VX_NODE_ATTRIBUTE_BORDER_MODE.
287  */
288  VX_BORDER_MODE_SELF = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_BORDER_MODE) + 0x3,
289 };
290 
291 /*! \typedef vx_tiling_kernel_f
292  * \brief Tiling Kernel function typedef for User Tiling Kernels.
293  * \note Tiles may come in any dimension and are not guaranteed to be delivered in
294  * any particular order.
295  * \param [in] parameters The array abstract pointers to parameters.
296  * \param [in] tile_memory The local tile memory pointer if requested, otherwise NULL.
297  * \param [in] tile_memory_size The size of the local tile memory, if not requested, 0.
298  * \ingroup group_tiling
299  */
300 #ifdef __cplusplus
301 typedef void (*vx_tiling_kernel_f)(void * VX_RESTRICT parameters[],
302  void * VX_RESTRICT tile_memory,
303  vx_size tile_memory_size);
304 #else
305 typedef void (*vx_tiling_kernel_f)(void * VX_RESTRICT parameters[VX_RESTRICT],
306  void * VX_RESTRICT tile_memory,
307  vx_size tile_memory_size);
308 #endif
309 
310 #ifndef VX_IMAGE_PIXEL_DEFINITION
311 
312 /*! \def vxImageOffset
313  * \brief Computes the offset within an image.
314  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
315  * \param [in] i The plane index.
316  * \param [in] x The Width Coordinates.
317  * \param [in] y The Height Coordinates.
318  * \param [in] ox The X offset.
319  * \param [in] oy The Y offset.
320  * \ingroup group_tiling
321  */
322 #define vxImageOffset(ptile, i, x, y, ox, oy) \
323  ((ptile)->addr[i].stride_y * (vx_int32)(((vx_int32)((oy)+(y)) * (vx_int32)(ptile)->addr[i].scale_y)/(vx_int32)VX_SCALE_UNITY)) + \
324  ((ptile)->addr[i].stride_x * (vx_int32)(((vx_int32)((ox)+(x)) * (vx_int32)(ptile)->addr[i].scale_x)/(vx_int32)VX_SCALE_UNITY))
325 
326 
327 /*! \def vxImagePixel
328  * \brief Accesses an image pixel as a type-cast indexed pointer dereference.
329  * \param [in] type The type of the image pixel. Example values are <tt>\ref vx_uint8</tt>, <tt>\ref vx_uint16</tt>, <tt>\ref vx_uint32</tt>, etc.
330  * \param [in] ptile The pointer to the \ref vx_tile_t structure.
331  * \param [in] i The plane index.
332  * \param [in] x The Center Pixel in Width Coordinates.
333  * \param [in] y The Center Pixel in Height Coordinates.
334  * \param [in] ox The X offset.
335  * \param [in] oy The Y offset.
336  * \ingroup group_tiling
337  */
338 #define vxImagePixel(type, ptile, i, x, y, ox, oy) \
339  *((type *)(&((vx_uint8 *)(ptile)->base[i])[vxImageOffset(ptile, i, x, y, ox, oy)]))
340 
341 #endif
342 
343 /*! \brief Allows a user to add a tile-able kernel to the OpenVX system.
344  * \param [in] context The handle to the implementation context.
345  * \param [in] name The string to be used to match the kernel.
346  * \param [in] enumeration The enumerated value of the kernel to be used by clients.
347  * \param [in] flexible_func_ptr The process-local flexible function pointer to be invoked.
348  * \param [in] fast_func_ptr The process-local fast function pointer to be invoked.
349  * \param [in] num_params The number of parameters for this kernel.
350  * \param [in] input The pointer to a function which will validate the
351  * input parameters to this kernel.
352  * \param [in] output The pointer to a function which will validate the
353  * output parameters to this kernel.
354  * \note Tiling Kernels do not have access to any of the normal node attributes listed
355  * in \ref vx_node_attribute_e.
356  * \post Call <tt>\ref vxAddParameterToKernel</tt> for as many parameters as the function has,
357  * then call <tt>\ref vxFinalizeKernel</tt>.
358  * \retval 0 Indicates that an error occurred when adding the kernel.
359  * Note that the fast or flexible formula, but not both, can be NULL.
360  * \ingroup group_tiling
361  */
362 VX_API_ENTRY vx_kernel VX_API_CALL vxAddTilingKernel(vx_context context,
363  vx_char name[VX_MAX_KERNEL_NAME],
364  vx_enum enumeration,
365  vx_tiling_kernel_f flexible_func_ptr,
366  vx_tiling_kernel_f fast_func_ptr,
367  vx_uint32 num_params,
368  vx_kernel_input_validate_f input,
369  vx_kernel_output_validate_f output);
370 
371 #endif
vx_uint32 height
Height of the image.
Definition: vx_khr_tiling.h:88
vx_uint32 planes
The number of planes in the image.
Definition: vx_khr_tiling.h:90
This is the size of the tile local memory area.
vx_int32 right
Right of the tile block.
Definition: vx_khr_tiling.h:78
This allows a tiling mode node to get its output tile block size.
The User Tiling Function tile block size declaration.
Definition: vx_khr_tiling.h:66
The tile structure declaration.
vx_kernel vxAddTilingKernel(vx_context context, vx_char name[(256)], vx_enum enumeration, vx_tiling_kernel_f flexible_func_ptr, vx_tiling_kernel_f fast_func_ptr, vx_uint32 num_params, vx_kernel_input_validate_f input, vx_kernel_output_validate_f output)
Allows a user to add a tile-able kernel to the OpenVX system.
This allows a tiling mode kernel to set its input neighborhood.
vx_uint32 tile_y
The top left Y pixel index within the height dimension of the image.
This allows a tiling mode node to get its input neighborhood.
#define VX_RESTRICT
A platform wrapper for the restrict keyword.
Definition: vx_khr_tiling.h:57
This determines the per tile memory allocation.
This allows the author to set the border mode on the tiling kernel.
vx_border_mode_tiling_e
The tiling border mode extensions.
This allows a tiling mode kernel to set its output tile block size.
vx_int32 left
Left of the tile block.
Definition: vx_khr_tiling.h:77
vx_kernel_attribute_tiling_e
The User Kernel Tiling Attributes.
vx_df_image format
The vx_df_image_e of the image.
Definition: vx_khr_tiling.h:89
This value indicates that the author of the tiling kernel wrote code to handle border conditions into...
vx_enum range
The vx_channel_range_e enumeration.
Definition: vx_khr_tiling.h:91
vx_neighborhood_size_t neighborhood
The neighborhood definition.
vx_enum space
The vx_color_space_e enumeration.
Definition: vx_khr_tiling.h:92
void(* vx_tiling_kernel_f)(void *restrict parameters[restrict], void *restrict tile_memory, vx_size tile_memory_size)
Tiling Kernel function typedef for User Tiling Kernels.
vx_uint32 tile_x
The top left X pixel index within the width dimension of the image.
vx_int32 bottom
Bottom of the tile block.
Definition: vx_khr_tiling.h:80
vx_int32 height
Tile block height in pixels.
Definition: vx_khr_tiling.h:68
vx_uint32 width
Width of the image.
Definition: vx_khr_tiling.h:87
A structure which describes the tile's parent image.
Definition: vx_khr_tiling.h:86
vx_tile_block_size_t tile_block
The output block size structure.
vx_node_attribute_tiling_e
The User Node Tiling Attributes.
vx_int32 top
Top of the tile block.
Definition: vx_khr_tiling.h:79
vx_int32 width
Tile block width in pixels.
Definition: vx_khr_tiling.h:67
#define VX_MAX_TILING_PLANES
The maximum number of planes in a tiled image.
Definition: vx_khr_tiling.h:98
vx_image_description_t image
The description and attributes of the image.
The User Tiling Function Neighborhood declaration.
Definition: vx_khr_tiling.h:76