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>
6 * This file is part of FFmpeg.
8 * FFmpeg is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * FFmpeg is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with FFmpeg; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
27 * This interface is considered still experimental and its API and ABI may
28 * change without prior notice.
31 #ifndef LIBAVUTIL_OPENCL_H
32 #define LIBAVUTIL_OPENCL_H
38 #include <OpenCL/cl.h>
42 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
44 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
46 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
48 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
52 char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
53 cl_device_id device_id;
57 cl_platform_id platform_id;
58 char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
60 AVOpenCLDeviceNode **device_node;
61 } AVOpenCLPlatformNode;
65 AVOpenCLPlatformNode **platform_node;
69 cl_command_queue command_queue;
71 char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
75 cl_platform_id platform_id;
76 cl_device_type device_type;
78 cl_device_id device_id;
79 cl_command_queue command_queue;
81 } AVOpenCLExternalEnv;
84 * Get OpenCL device list.
86 * It must be freed with av_opencl_free_device_list().
88 * @param device_list pointer to OpenCL environment device list,
89 * should be released by av_opencl_free_device_list()
91 * @return >=0 on success, a negative error code in case of failure
93 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);
96 * Free OpenCL device list.
98 * @param device_list pointer to OpenCL environment device list
99 * created by av_opencl_get_device_list()
101 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);
104 * Set option in the global OpenCL context.
106 * This options affect the operation performed by the next
107 * av_opencl_init() operation.
109 * The currently accepted options are:
110 * - build_options: set options to compile registered kernels code
111 * - platform: set index of platform in device list
112 * - device: set index of device in device list
114 * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
116 * @param key option key
117 * @param val option value
118 * @return >=0 on success, a negative error code in case of failure
119 * @see av_opencl_get_option()
121 int av_opencl_set_option(const char *key, const char *val);
124 * Get option value from the global OpenCL context.
126 * @param key option key
127 * @param out_val pointer to location where option value will be
128 * written, must be freed with av_freep()
129 * @return >=0 on success, a negative error code in case of failure
130 * @see av_opencl_set_option()
132 int av_opencl_get_option(const char *key, uint8_t **out_val);
135 * Free option values of the global OpenCL context.
138 void av_opencl_free_option(void);
141 * Allocate OpenCL external environment.
143 * It must be freed with av_opencl_free_external_env().
145 * @return pointer to allocated OpenCL external environment
147 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
150 * Free OpenCL external environment.
152 * @param ext_opencl_env pointer to OpenCL external environment
153 * created by av_opencl_alloc_external_env()
155 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
158 * Register kernel code.
160 * The registered kernel code is stored in a global context, and compiled
161 * in the runtime environment when av_opencl_init() is called.
163 * @param kernel_code kernel code to be compiled in the OpenCL runtime environment
164 * @return >=0 on success, a negative error code in case of failure
166 int av_opencl_register_kernel_code(const char *kernel_code);
169 * Initialize the run time OpenCL environment and compile the kernel
170 * code registered with av_opencl_register_kernel_code().
172 * @param ext_opencl_env external OpenCL environment, created by an
173 * application program, ignored if set to NULL
174 * @return >=0 on success, a negative error code in case of failure
176 int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
179 * Create kernel object in the specified kernel environment.
181 * @param env pointer to kernel environment which is filled with
182 * the environment used to run the kernel
183 * @param kernel_name kernel function name
184 * @return >=0 on success, a negative error code in case of failure
186 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
189 * Create OpenCL buffer.
191 * The buffer is used to save the data used or created by an OpenCL
193 * The created buffer must be released with av_opencl_buffer_release().
195 * See clCreateBuffer() function reference for more information about
198 * @param cl_buf pointer to OpenCL buffer
199 * @param cl_buf_size size in bytes of the OpenCL buffer to create
200 * @param flags flags used to control buffer attributes
201 * @param host_ptr host pointer of the OpenCL buffer
202 * @return >=0 on success, a negative error code in case of failure
204 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
207 * Write OpenCL buffer with data from src_buf.
209 * @param dst_cl_buf pointer to OpenCL destination buffer
210 * @param src_buf pointer to source buffer
211 * @param buf_size size in bytes of the source and destination buffers
212 * @return >=0 on success, a negative error code in case of failure
214 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
217 * Read data from OpenCL buffer to memory buffer.
219 * @param dst_buf pointer to destination buffer (CPU memory)
220 * @param src_cl_buf pointer to source OpenCL buffer
221 * @param buf_size size in bytes of the source and destination buffers
222 * @return >=0 on success, a negative error code in case of failure
224 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
227 * Write image data from memory to OpenCL buffer.
229 * The source must be an array of pointers to image plane buffers.
231 * @param dst_cl_buf pointer to destination OpenCL buffer
232 * @param dst_cl_buf_size size in bytes of OpenCL buffer
233 * @param dst_cl_buf_offset the offset of the OpenCL buffer start position
234 * @param src_data array of pointers to source plane buffers
235 * @param src_plane_sizes array of sizes in bytes of the source plane buffers
236 * @param src_plane_num number of source image planes
237 * @return >=0 on success, a negative error code in case of failure
239 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
240 uint8_t **src_data, int *plane_size, int plane_num);
243 * Read image data from OpenCL buffer.
245 * @param dst_data array of pointers to destination plane buffers
246 * @param dst_plane_sizes array of pointers to destination plane buffers
247 * @param dst_plane_num number of destination image planes
248 * @param src_cl_buf pointer to source OpenCL buffer
249 * @param src_cl_buf_size size in bytes of OpenCL buffer
250 * @return >=0 on success, a negative error code in case of failure
252 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
253 cl_mem src_cl_buf, size_t cl_buffer_size);
256 * Release OpenCL buffer.
258 * @param cl_buf pointer to OpenCL buffer to release, which was
259 * previously filled with av_opencl_buffer_create()
261 void av_opencl_buffer_release(cl_mem *cl_buf);
264 * Release kernel object.
266 * @param env kernel environment where the kernel object was created
267 * with av_opencl_create_kernel()
269 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
272 * Release OpenCL environment.
274 * The OpenCL environment is effectively released only if all the created
275 * kernels had been released with av_opencl_release_kernel().
277 void av_opencl_uninit(void);
279 #endif /* LIBAVUTIL_OPENCL_H */