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>
7 * This file is part of FFmpeg.
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.
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.
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
28 * This interface is considered still experimental and its API and ABI may
29 * change without prior notice.
32 #ifndef LIBAVUTIL_OPENCL_H
33 #define LIBAVUTIL_OPENCL_H
39 #include <OpenCL/cl.h>
43 #include "libavutil/version.h"
45 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
47 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
49 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
51 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
55 char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
56 cl_device_id device_id;
60 cl_platform_id platform_id;
61 char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
63 AVOpenCLDeviceNode **device_node;
64 } AVOpenCLPlatformNode;
68 AVOpenCLPlatformNode **platform_node;
73 cl_command_queue command_queue;
75 char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
80 cl_platform_id platform_id;
81 cl_device_type device_type;
83 cl_device_id device_id;
84 cl_command_queue command_queue;
86 } AVOpenCLExternalEnv;
89 * Get OpenCL device list.
91 * It must be freed with av_opencl_free_device_list().
93 * @param device_list pointer to OpenCL environment device list,
94 * should be released by av_opencl_free_device_list()
96 * @return >=0 on success, a negative error code in case of failure
98 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);
101 * Free OpenCL device list.
103 * @param device_list pointer to OpenCL environment device list
104 * created by av_opencl_get_device_list()
106 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);
109 * Set option in the global OpenCL context.
111 * This options affect the operation performed by the next
112 * av_opencl_init() operation.
114 * The currently accepted options are:
115 * - platform: set index of platform in device list
116 * - device: set index of device in device list
118 * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
120 * @param key option key
121 * @param val option value
122 * @return >=0 on success, a negative error code in case of failure
123 * @see av_opencl_get_option()
125 int av_opencl_set_option(const char *key, const char *val);
128 * Get option value from the global OpenCL context.
130 * @param key option key
131 * @param out_val pointer to location where option value will be
132 * written, must be freed with av_freep()
133 * @return >=0 on success, a negative error code in case of failure
134 * @see av_opencl_set_option()
136 int av_opencl_get_option(const char *key, uint8_t **out_val);
139 * Free option values of the global OpenCL context.
142 void av_opencl_free_option(void);
145 * Allocate OpenCL external environment.
147 * It must be freed with av_opencl_free_external_env().
149 * @return pointer to allocated OpenCL external environment
151 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
154 * Free OpenCL external environment.
156 * @param ext_opencl_env pointer to OpenCL external environment
157 * created by av_opencl_alloc_external_env()
159 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
162 * Get OpenCL error string.
164 * @param status OpenCL error code
165 * @return OpenCL error string
167 const char *av_opencl_errstr(cl_int status);
170 * Register kernel code.
172 * The registered kernel code is stored in a global context, and compiled
173 * in the runtime environment when av_opencl_init() is called.
175 * @param kernel_code kernel code to be compiled in the OpenCL runtime environment
176 * @return >=0 on success, a negative error code in case of failure
178 int av_opencl_register_kernel_code(const char *kernel_code);
181 * Initialize the run time OpenCL environment
183 * @param ext_opencl_env external OpenCL environment, created by an
184 * application program, ignored if set to NULL
185 * @return >=0 on success, a negative error code in case of failure
187 int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
189 #if FF_API_OLD_OPENCL
191 * Create kernel object in the specified kernel environment.
193 * @param env pointer to kernel environment which is filled with
194 * the environment used to run the kernel
195 * @param kernel_name kernel function name
196 * @return >=0 on success, a negative error code in case of failure
197 * @deprecated, use clCreateKernel
199 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
203 * compile specific OpenCL kernel source
205 * @param program_name pointer to a program name used for identification
206 * @param build_opts pointer to a string that describes the preprocessor
207 * build options to be used for building the program
208 * @return a cl_program object
210 cl_program av_opencl_compile(const char *program_name, const char* build_opts);
213 * get OpenCL command queue
215 * @return a cl_command_queue object
217 cl_command_queue av_opencl_get_command_queue(void);
220 * Create OpenCL buffer.
222 * The buffer is used to save the data used or created by an OpenCL
224 * The created buffer must be released with av_opencl_buffer_release().
226 * See clCreateBuffer() function reference for more information about
229 * @param cl_buf pointer to OpenCL buffer
230 * @param cl_buf_size size in bytes of the OpenCL buffer to create
231 * @param flags flags used to control buffer attributes
232 * @param host_ptr host pointer of the OpenCL buffer
233 * @return >=0 on success, a negative error code in case of failure
235 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
238 * Write OpenCL buffer with data from src_buf.
240 * @param dst_cl_buf pointer to OpenCL destination buffer
241 * @param src_buf pointer to source buffer
242 * @param buf_size size in bytes of the source and destination buffers
243 * @return >=0 on success, a negative error code in case of failure
245 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
248 * Read data from OpenCL buffer to memory buffer.
250 * @param dst_buf pointer to destination buffer (CPU memory)
251 * @param src_cl_buf pointer to source OpenCL buffer
252 * @param buf_size size in bytes of the source and destination buffers
253 * @return >=0 on success, a negative error code in case of failure
255 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
258 * Write image data from memory to OpenCL buffer.
260 * The source must be an array of pointers to image plane buffers.
262 * @param dst_cl_buf pointer to destination OpenCL buffer
263 * @param dst_cl_buf_size size in bytes of OpenCL buffer
264 * @param dst_cl_buf_offset the offset of the OpenCL buffer start position
265 * @param src_data array of pointers to source plane buffers
266 * @param src_plane_sizes array of sizes in bytes of the source plane buffers
267 * @param src_plane_num number of source image planes
268 * @return >=0 on success, a negative error code in case of failure
270 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
271 uint8_t **src_data, int *plane_size, int plane_num);
274 * Read image data from OpenCL buffer.
276 * @param dst_data array of pointers to destination plane buffers
277 * @param dst_plane_sizes array of pointers to destination plane buffers
278 * @param dst_plane_num number of destination image planes
279 * @param src_cl_buf pointer to source OpenCL buffer
280 * @param src_cl_buf_size size in bytes of OpenCL buffer
281 * @return >=0 on success, a negative error code in case of failure
283 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
284 cl_mem src_cl_buf, size_t cl_buffer_size);
287 * Release OpenCL buffer.
289 * @param cl_buf pointer to OpenCL buffer to release, which was
290 * previously filled with av_opencl_buffer_create()
292 void av_opencl_buffer_release(cl_mem *cl_buf);
294 #if FF_API_OLD_OPENCL
296 * Release kernel object.
298 * @param env kernel environment where the kernel object was created
299 * with av_opencl_create_kernel()
300 * @deprecated, use clReleaseKernel
302 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
306 * Release OpenCL environment.
308 * The OpenCL environment is effectively released only if all the created
309 * kernels had been released with av_opencl_release_kernel().
311 void av_opencl_uninit(void);
314 * Benchmark an OpenCL device with a user defined callback function. This function
315 * sets up an external OpenCL environment including context and command queue on
316 * the device then tears it down in the end. The callback function should perform
317 * the rest of the work.
319 * @param device pointer to the OpenCL device to be used
320 * @param platform cl_platform_id handle to which the device belongs to
321 * @param benchmark callback function to perform the benchmark, return a
322 * negative value in case of failure
323 * @return the score passed from the callback function, a negative error code in case
326 int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform,
327 int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env));
329 #endif /* LIBAVUTIL_OPENCL_H */