update for 2.3.5
[ffmpeg.git] / libavutil / opencl.h
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 */