Commit | Line | Data |
---|---|---|
2ba45a60 DM |
1 | /* |
2 | * Copyright (C) 2012 Peng Gao <peng@multicorewareinc.com> | |
3 | * Copyright (C) 2012 Li Cao <li@multicorewareinc.com> | |
4 | * Copyright (C) 2012 Wei Gao <weigao@multicorewareinc.com> | |
5 | * Copyright (C) 2013 Lenny Wang <lwanghpc@gmail.com> | |
6 | * | |
7 | * This file is part of FFmpeg. | |
8 | * | |
9 | * FFmpeg is free software; you can redistribute it and/or | |
10 | * modify it under the terms of the GNU Lesser General Public | |
11 | * License as published by the Free Software Foundation; either | |
12 | * version 2.1 of the License, or (at your option) any later version. | |
13 | * | |
14 | * FFmpeg is distributed in the hope that it will be useful, | |
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
17 | * Lesser General Public License for more details. | |
18 | * | |
19 | * You should have received a copy of the GNU Lesser General Public | |
20 | * License along with FFmpeg; if not, write to the Free Software | |
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
22 | */ | |
23 | ||
24 | /** | |
25 | * @file | |
26 | * OpenCL wrapper | |
27 | * | |
28 | * This interface is considered still experimental and its API and ABI may | |
29 | * change without prior notice. | |
30 | */ | |
31 | ||
32 | #ifndef LIBAVUTIL_OPENCL_H | |
33 | #define LIBAVUTIL_OPENCL_H | |
34 | ||
35 | #include "config.h" | |
36 | #if HAVE_CL_CL_H | |
37 | #include <CL/cl.h> | |
38 | #else | |
39 | #include <OpenCL/cl.h> | |
40 | #endif | |
41 | #include <stdint.h> | |
42 | #include "dict.h" | |
43 | ||
44 | #include "libavutil/version.h" | |
45 | ||
46 | #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__ | |
47 | ||
48 | #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150 | |
49 | ||
50 | #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100 | |
51 | ||
52 | #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100 | |
53 | ||
54 | typedef struct { | |
55 | int device_type; | |
56 | char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE]; | |
57 | cl_device_id device_id; | |
58 | } AVOpenCLDeviceNode; | |
59 | ||
60 | typedef struct { | |
61 | cl_platform_id platform_id; | |
62 | char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE]; | |
63 | int device_num; | |
64 | AVOpenCLDeviceNode **device_node; | |
65 | } AVOpenCLPlatformNode; | |
66 | ||
67 | typedef struct { | |
68 | int platform_num; | |
69 | AVOpenCLPlatformNode **platform_node; | |
70 | } AVOpenCLDeviceList; | |
71 | ||
72 | #if FF_API_OLD_OPENCL | |
73 | typedef struct { | |
74 | cl_command_queue command_queue; | |
75 | cl_kernel kernel; | |
76 | char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE]; | |
77 | } AVOpenCLKernelEnv; | |
78 | #endif | |
79 | ||
80 | typedef struct { | |
81 | cl_platform_id platform_id; | |
82 | cl_device_type device_type; | |
83 | cl_context context; | |
84 | cl_device_id device_id; | |
85 | cl_command_queue command_queue; | |
86 | char *platform_name; | |
87 | } AVOpenCLExternalEnv; | |
88 | ||
89 | /** | |
90 | * Get OpenCL device list. | |
91 | * | |
92 | * It must be freed with av_opencl_free_device_list(). | |
93 | * | |
94 | * @param device_list pointer to OpenCL environment device list, | |
95 | * should be released by av_opencl_free_device_list() | |
96 | * | |
97 | * @return >=0 on success, a negative error code in case of failure | |
98 | */ | |
99 | int av_opencl_get_device_list(AVOpenCLDeviceList **device_list); | |
100 | ||
101 | /** | |
102 | * Free OpenCL device list. | |
103 | * | |
104 | * @param device_list pointer to OpenCL environment device list | |
105 | * created by av_opencl_get_device_list() | |
106 | */ | |
107 | void av_opencl_free_device_list(AVOpenCLDeviceList **device_list); | |
108 | ||
109 | /** | |
110 | * Set option in the global OpenCL context. | |
111 | * | |
112 | * This options affect the operation performed by the next | |
113 | * av_opencl_init() operation. | |
114 | * | |
115 | * The currently accepted options are: | |
116 | * - platform: set index of platform in device list | |
117 | * - device: set index of device in device list | |
118 | * | |
119 | * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4". | |
120 | * | |
121 | * @param key option key | |
122 | * @param val option value | |
123 | * @return >=0 on success, a negative error code in case of failure | |
124 | * @see av_opencl_get_option() | |
125 | */ | |
126 | int av_opencl_set_option(const char *key, const char *val); | |
127 | ||
128 | /** | |
129 | * Get option value from the global OpenCL context. | |
130 | * | |
131 | * @param key option key | |
132 | * @param out_val pointer to location where option value will be | |
133 | * written, must be freed with av_freep() | |
134 | * @return >=0 on success, a negative error code in case of failure | |
135 | * @see av_opencl_set_option() | |
136 | */ | |
137 | int av_opencl_get_option(const char *key, uint8_t **out_val); | |
138 | ||
139 | /** | |
140 | * Free option values of the global OpenCL context. | |
141 | * | |
142 | */ | |
143 | void av_opencl_free_option(void); | |
144 | ||
145 | /** | |
146 | * Allocate OpenCL external environment. | |
147 | * | |
148 | * It must be freed with av_opencl_free_external_env(). | |
149 | * | |
150 | * @return pointer to allocated OpenCL external environment | |
151 | */ | |
152 | AVOpenCLExternalEnv *av_opencl_alloc_external_env(void); | |
153 | ||
154 | /** | |
155 | * Free OpenCL external environment. | |
156 | * | |
157 | * @param ext_opencl_env pointer to OpenCL external environment | |
158 | * created by av_opencl_alloc_external_env() | |
159 | */ | |
160 | void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env); | |
161 | ||
162 | /** | |
163 | * Get OpenCL error string. | |
164 | * | |
165 | * @param status OpenCL error code | |
166 | * @return OpenCL error string | |
167 | */ | |
168 | const char *av_opencl_errstr(cl_int status); | |
169 | ||
170 | /** | |
171 | * Register kernel code. | |
172 | * | |
173 | * The registered kernel code is stored in a global context, and compiled | |
174 | * in the runtime environment when av_opencl_init() is called. | |
175 | * | |
176 | * @param kernel_code kernel code to be compiled in the OpenCL runtime environment | |
177 | * @return >=0 on success, a negative error code in case of failure | |
178 | */ | |
179 | int av_opencl_register_kernel_code(const char *kernel_code); | |
180 | ||
181 | /** | |
182 | * Initialize the run time OpenCL environment | |
183 | * | |
184 | * @param ext_opencl_env external OpenCL environment, created by an | |
185 | * application program, ignored if set to NULL | |
186 | * @return >=0 on success, a negative error code in case of failure | |
187 | */ | |
188 | int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env); | |
189 | ||
190 | #if FF_API_OLD_OPENCL | |
191 | /** | |
192 | * Create kernel object in the specified kernel environment. | |
193 | * | |
194 | * @param env pointer to kernel environment which is filled with | |
195 | * the environment used to run the kernel | |
196 | * @param kernel_name kernel function name | |
197 | * @return >=0 on success, a negative error code in case of failure | |
198 | * @deprecated, use clCreateKernel | |
199 | */ | |
200 | int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name); | |
201 | #endif | |
202 | ||
203 | /** | |
204 | * compile specific OpenCL kernel source | |
205 | * | |
206 | * @param program_name pointer to a program name used for identification | |
207 | * @param build_opts pointer to a string that describes the preprocessor | |
208 | * build options to be used for building the program | |
209 | * @return a cl_program object | |
210 | */ | |
211 | cl_program av_opencl_compile(const char *program_name, const char* build_opts); | |
212 | ||
213 | /** | |
214 | * get OpenCL command queue | |
215 | * | |
216 | * @return a cl_command_queue object | |
217 | */ | |
218 | cl_command_queue av_opencl_get_command_queue(void); | |
219 | ||
220 | /** | |
221 | * Create OpenCL buffer. | |
222 | * | |
223 | * The buffer is used to save the data used or created by an OpenCL | |
224 | * kernel. | |
225 | * The created buffer must be released with av_opencl_buffer_release(). | |
226 | * | |
227 | * See clCreateBuffer() function reference for more information about | |
228 | * the parameters. | |
229 | * | |
230 | * @param cl_buf pointer to OpenCL buffer | |
231 | * @param cl_buf_size size in bytes of the OpenCL buffer to create | |
232 | * @param flags flags used to control buffer attributes | |
233 | * @param host_ptr host pointer of the OpenCL buffer | |
234 | * @return >=0 on success, a negative error code in case of failure | |
235 | */ | |
236 | int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr); | |
237 | ||
238 | /** | |
239 | * Write OpenCL buffer with data from src_buf. | |
240 | * | |
241 | * @param dst_cl_buf pointer to OpenCL destination buffer | |
242 | * @param src_buf pointer to source buffer | |
243 | * @param buf_size size in bytes of the source and destination buffers | |
244 | * @return >=0 on success, a negative error code in case of failure | |
245 | */ | |
246 | int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size); | |
247 | ||
248 | /** | |
249 | * Read data from OpenCL buffer to memory buffer. | |
250 | * | |
251 | * @param dst_buf pointer to destination buffer (CPU memory) | |
252 | * @param src_cl_buf pointer to source OpenCL buffer | |
253 | * @param buf_size size in bytes of the source and destination buffers | |
254 | * @return >=0 on success, a negative error code in case of failure | |
255 | */ | |
256 | int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size); | |
257 | ||
258 | /** | |
259 | * Write image data from memory to OpenCL buffer. | |
260 | * | |
261 | * The source must be an array of pointers to image plane buffers. | |
262 | * | |
263 | * @param dst_cl_buf pointer to destination OpenCL buffer | |
264 | * @param dst_cl_buf_size size in bytes of OpenCL buffer | |
265 | * @param dst_cl_buf_offset the offset of the OpenCL buffer start position | |
266 | * @param src_data array of pointers to source plane buffers | |
267 | * @param src_plane_sizes array of sizes in bytes of the source plane buffers | |
268 | * @param src_plane_num number of source image planes | |
269 | * @return >=0 on success, a negative error code in case of failure | |
270 | */ | |
271 | int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset, | |
272 | uint8_t **src_data, int *plane_size, int plane_num); | |
273 | ||
274 | /** | |
275 | * Read image data from OpenCL buffer. | |
276 | * | |
277 | * @param dst_data array of pointers to destination plane buffers | |
278 | * @param dst_plane_sizes array of pointers to destination plane buffers | |
279 | * @param dst_plane_num number of destination image planes | |
280 | * @param src_cl_buf pointer to source OpenCL buffer | |
281 | * @param src_cl_buf_size size in bytes of OpenCL buffer | |
282 | * @return >=0 on success, a negative error code in case of failure | |
283 | */ | |
284 | int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num, | |
285 | cl_mem src_cl_buf, size_t cl_buffer_size); | |
286 | ||
287 | /** | |
288 | * Release OpenCL buffer. | |
289 | * | |
290 | * @param cl_buf pointer to OpenCL buffer to release, which was | |
291 | * previously filled with av_opencl_buffer_create() | |
292 | */ | |
293 | void av_opencl_buffer_release(cl_mem *cl_buf); | |
294 | ||
295 | #if FF_API_OLD_OPENCL | |
296 | /** | |
297 | * Release kernel object. | |
298 | * | |
299 | * @param env kernel environment where the kernel object was created | |
300 | * with av_opencl_create_kernel() | |
301 | * @deprecated, use clReleaseKernel | |
302 | */ | |
303 | void av_opencl_release_kernel(AVOpenCLKernelEnv *env); | |
304 | #endif | |
305 | ||
306 | /** | |
307 | * Release OpenCL environment. | |
308 | * | |
309 | * The OpenCL environment is effectively released only if all the created | |
310 | * kernels had been released with av_opencl_release_kernel(). | |
311 | */ | |
312 | void av_opencl_uninit(void); | |
313 | ||
314 | /** | |
315 | * Benchmark an OpenCL device with a user defined callback function. This function | |
316 | * sets up an external OpenCL environment including context and command queue on | |
317 | * the device then tears it down in the end. The callback function should perform | |
318 | * the rest of the work. | |
319 | * | |
320 | * @param device pointer to the OpenCL device to be used | |
321 | * @param platform cl_platform_id handle to which the device belongs to | |
322 | * @param benchmark callback function to perform the benchmark, return a | |
323 | * negative value in case of failure | |
324 | * @return the score passed from the callback function, a negative error code in case | |
325 | * of failure | |
326 | */ | |
327 | int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform, | |
328 | int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env)); | |
329 | ||
330 | #endif /* LIBAVUTIL_OPENCL_H */ |