FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
opencl.h
Go to the documentation of this file.
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 {
56  char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
57  cl_device_id device_id;
59 
60 typedef struct {
61  cl_platform_id platform_id;
62  char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
66 
67 typedef struct {
71 
72 typedef struct {
73  cl_platform_id platform_id;
74  cl_device_type device_type;
75  cl_context context;
76  cl_device_id device_id;
77  cl_command_queue command_queue;
80 
81 /**
82  * Get OpenCL device list.
83  *
84  * It must be freed with av_opencl_free_device_list().
85  *
86  * @param device_list pointer to OpenCL environment device list,
87  * should be released by av_opencl_free_device_list()
88  *
89  * @return >=0 on success, a negative error code in case of failure
90  */
92 
93 /**
94  * Free OpenCL device list.
95  *
96  * @param device_list pointer to OpenCL environment device list
97  * created by av_opencl_get_device_list()
98  */
100 
101 /**
102  * Set option in the global OpenCL context.
103  *
104  * This options affect the operation performed by the next
105  * av_opencl_init() operation.
106  *
107  * The currently accepted options are:
108  * - platform: set index of platform in device list
109  * - device: set index of device in device list
110  *
111  * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
112  *
113  * @param key option key
114  * @param val option value
115  * @return >=0 on success, a negative error code in case of failure
116  * @see av_opencl_get_option()
117  */
118 int av_opencl_set_option(const char *key, const char *val);
119 
120 /**
121  * Get option value from the global OpenCL context.
122  *
123  * @param key option key
124  * @param out_val pointer to location where option value will be
125  * written, must be freed with av_freep()
126  * @return >=0 on success, a negative error code in case of failure
127  * @see av_opencl_set_option()
128  */
129 int av_opencl_get_option(const char *key, uint8_t **out_val);
130 
131 /**
132  * Free option values of the global OpenCL context.
133  *
134  */
135 void av_opencl_free_option(void);
136 
137 /**
138  * Allocate OpenCL external environment.
139  *
140  * It must be freed with av_opencl_free_external_env().
141  *
142  * @return pointer to allocated OpenCL external environment
143  */
145 
146 /**
147  * Free OpenCL external environment.
148  *
149  * @param ext_opencl_env pointer to OpenCL external environment
150  * created by av_opencl_alloc_external_env()
151  */
152 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
153 
154 /**
155  * Get OpenCL error string.
156  *
157  * @param status OpenCL error code
158  * @return OpenCL error string
159  */
160 const char *av_opencl_errstr(cl_int status);
161 
162 /**
163  * Register kernel code.
164  *
165  * The registered kernel code is stored in a global context, and compiled
166  * in the runtime environment when av_opencl_init() is called.
167  *
168  * @param kernel_code kernel code to be compiled in the OpenCL runtime environment
169  * @return >=0 on success, a negative error code in case of failure
170  */
171 int av_opencl_register_kernel_code(const char *kernel_code);
172 
173 /**
174  * Initialize the run time OpenCL environment
175  *
176  * @param ext_opencl_env external OpenCL environment, created by an
177  * application program, ignored if set to NULL
178  * @return >=0 on success, a negative error code in case of failure
179  */
180 int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
181 
182 /**
183  * compile specific OpenCL kernel source
184  *
185  * @param program_name pointer to a program name used for identification
186  * @param build_opts pointer to a string that describes the preprocessor
187  * build options to be used for building the program
188  * @return a cl_program object
189  */
190 cl_program av_opencl_compile(const char *program_name, const char* build_opts);
191 
192 /**
193  * get OpenCL command queue
194  *
195  * @return a cl_command_queue object
196  */
197 cl_command_queue av_opencl_get_command_queue(void);
198 
199 /**
200  * Create OpenCL buffer.
201  *
202  * The buffer is used to save the data used or created by an OpenCL
203  * kernel.
204  * The created buffer must be released with av_opencl_buffer_release().
205  *
206  * See clCreateBuffer() function reference for more information about
207  * the parameters.
208  *
209  * @param cl_buf pointer to OpenCL buffer
210  * @param cl_buf_size size in bytes of the OpenCL buffer to create
211  * @param flags flags used to control buffer attributes
212  * @param host_ptr host pointer of the OpenCL buffer
213  * @return >=0 on success, a negative error code in case of failure
214  */
215 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
216 
217 /**
218  * Write OpenCL buffer with data from src_buf.
219  *
220  * @param dst_cl_buf pointer to OpenCL destination buffer
221  * @param src_buf pointer to source buffer
222  * @param buf_size size in bytes of the source and destination buffers
223  * @return >=0 on success, a negative error code in case of failure
224  */
225 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
226 
227 /**
228  * Read data from OpenCL buffer to memory buffer.
229  *
230  * @param dst_buf pointer to destination buffer (CPU memory)
231  * @param src_cl_buf pointer to source OpenCL buffer
232  * @param buf_size size in bytes of the source and destination buffers
233  * @return >=0 on success, a negative error code in case of failure
234  */
235 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
236 
237 /**
238  * Write image data from memory to OpenCL buffer.
239  *
240  * The source must be an array of pointers to image plane buffers.
241  *
242  * @param dst_cl_buf pointer to destination OpenCL buffer
243  * @param dst_cl_buf_size size in bytes of OpenCL buffer
244  * @param dst_cl_buf_offset the offset of the OpenCL buffer start position
245  * @param src_data array of pointers to source plane buffers
246  * @param src_plane_sizes array of sizes in bytes of the source plane buffers
247  * @param src_plane_num number of source image planes
248  * @return >=0 on success, a negative error code in case of failure
249  */
250 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
251  uint8_t **src_data, int *plane_size, int plane_num);
252 
253 /**
254  * Read image data from OpenCL buffer.
255  *
256  * @param dst_data array of pointers to destination plane buffers
257  * @param dst_plane_sizes array of pointers to destination plane buffers
258  * @param dst_plane_num number of destination image planes
259  * @param src_cl_buf pointer to source OpenCL buffer
260  * @param src_cl_buf_size size in bytes of OpenCL buffer
261  * @return >=0 on success, a negative error code in case of failure
262  */
263 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
264  cl_mem src_cl_buf, size_t cl_buffer_size);
265 
266 /**
267  * Release OpenCL buffer.
268  *
269  * @param cl_buf pointer to OpenCL buffer to release, which was
270  * previously filled with av_opencl_buffer_create()
271  */
272 void av_opencl_buffer_release(cl_mem *cl_buf);
273 
274 /**
275  * Release OpenCL environment.
276  *
277  * The OpenCL environment is effectively released only if all the created
278  * kernels had been released with av_opencl_release_kernel().
279  */
280 void av_opencl_uninit(void);
281 
282 /**
283  * Benchmark an OpenCL device with a user defined callback function. This function
284  * sets up an external OpenCL environment including context and command queue on
285  * the device then tears it down in the end. The callback function should perform
286  * the rest of the work.
287  *
288  * @param device pointer to the OpenCL device to be used
289  * @param platform cl_platform_id handle to which the device belongs to
290  * @param benchmark callback function to perform the benchmark, return a
291  * negative value in case of failure
292  * @return the score passed from the callback function, a negative error code in case
293  * of failure
294  */
295 int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform,
296  int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env));
297 
298 #endif /* LIBAVUTIL_OPENCL_H */