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  *
6  * This file is part of FFmpeg.
7  *
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.
12  *
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.
17  *
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
21  */
22 
23 /**
24  * @file
25  * OpenCL wrapper
26  *
27  * This interface is considered still experimental and its API and ABI may
28  * change without prior notice.
29  */
30 
31 #ifndef LIBAVUTIL_OPENCL_H
32 #define LIBAVUTIL_OPENCL_H
33 
34 #include "config.h"
35 #if HAVE_CL_CL_H
36 #include <CL/cl.h>
37 #else
38 #include <OpenCL/cl.h>
39 #endif
40 #include "dict.h"
41 
42 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
43 
44 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
45 
46 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
47 
48 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
49 
50 typedef struct {
52  char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
53  cl_device_id device_id;
55 
56 typedef struct {
57  cl_platform_id platform_id;
58  char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
62 
63 typedef struct {
67 
68 typedef struct {
69  cl_command_queue command_queue;
70  cl_kernel kernel;
71  char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
73 
74 typedef struct {
75  cl_platform_id platform_id;
76  cl_device_type device_type;
77  cl_context context;
78  cl_device_id device_id;
79  cl_command_queue command_queue;
82 
83 /**
84  * Get OpenCL device list.
85  *
86  * It must be freed with av_opencl_free_device_list().
87  *
88  * @param device_list pointer to OpenCL environment device list,
89  * should be released by av_opencl_free_device_list()
90  *
91  * @return >=0 on success, a negative error code in case of failure
92  */
94 
95 /**
96  * Free OpenCL device list.
97  *
98  * @param device_list pointer to OpenCL environment device list
99  * created by av_opencl_get_device_list()
100  */
102 
103 /**
104  * Set option in the global OpenCL context.
105  *
106  * This options affect the operation performed by the next
107  * av_opencl_init() operation.
108  *
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
113  *
114  * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
115  *
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()
120  */
121 int av_opencl_set_option(const char *key, const char *val);
122 
123 /**
124  * Get option value from the global OpenCL context.
125  *
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()
131  */
132 int av_opencl_get_option(const char *key, uint8_t **out_val);
133 
134 /**
135  * Free option values of the global OpenCL context.
136  *
137  */
138 void av_opencl_free_option(void);
139 
140 /**
141  * Allocate OpenCL external environment.
142  *
143  * It must be freed with av_opencl_free_external_env().
144  *
145  * @return pointer to allocated OpenCL external environment
146  */
148 
149 /**
150  * Free OpenCL external environment.
151  *
152  * @param ext_opencl_env pointer to OpenCL external environment
153  * created by av_opencl_alloc_external_env()
154  */
155 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
156 
157 /**
158  * Get OpenCL error string.
159  *
160  * @param status OpenCL error code
161  * @return OpenCL error string
162  */
163 const char *av_opencl_errstr(cl_int status);
164 
165 /**
166  * Register kernel code.
167  *
168  * The registered kernel code is stored in a global context, and compiled
169  * in the runtime environment when av_opencl_init() is called.
170  *
171  * @param kernel_code kernel code to be compiled in the OpenCL runtime environment
172  * @return >=0 on success, a negative error code in case of failure
173  */
174 int av_opencl_register_kernel_code(const char *kernel_code);
175 
176 /**
177  * Initialize the run time OpenCL environment and compile the kernel
178  * code registered with av_opencl_register_kernel_code().
179  *
180  * @param ext_opencl_env external OpenCL environment, created by an
181  * application program, ignored if set to NULL
182  * @return >=0 on success, a negative error code in case of failure
183  */
184  int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
185 
186 /**
187  * Create kernel object in the specified kernel environment.
188  *
189  * @param env pointer to kernel environment which is filled with
190  * the environment used to run the kernel
191  * @param kernel_name kernel function name
192  * @return >=0 on success, a negative error code in case of failure
193  */
194 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
195 
196 /**
197  * Create OpenCL buffer.
198  *
199  * The buffer is used to save the data used or created by an OpenCL
200  * kernel.
201  * The created buffer must be released with av_opencl_buffer_release().
202  *
203  * See clCreateBuffer() function reference for more information about
204  * the parameters.
205  *
206  * @param cl_buf pointer to OpenCL buffer
207  * @param cl_buf_size size in bytes of the OpenCL buffer to create
208  * @param flags flags used to control buffer attributes
209  * @param host_ptr host pointer of the OpenCL buffer
210  * @return >=0 on success, a negative error code in case of failure
211  */
212 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
213 
214 /**
215  * Write OpenCL buffer with data from src_buf.
216  *
217  * @param dst_cl_buf pointer to OpenCL destination buffer
218  * @param src_buf pointer to source buffer
219  * @param buf_size size in bytes of the source and destination buffers
220  * @return >=0 on success, a negative error code in case of failure
221  */
222 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
223 
224 /**
225  * Read data from OpenCL buffer to memory buffer.
226  *
227  * @param dst_buf pointer to destination buffer (CPU memory)
228  * @param src_cl_buf pointer to source OpenCL buffer
229  * @param buf_size size in bytes of the source and destination buffers
230  * @return >=0 on success, a negative error code in case of failure
231  */
232 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
233 
234 /**
235  * Write image data from memory to OpenCL buffer.
236  *
237  * The source must be an array of pointers to image plane buffers.
238  *
239  * @param dst_cl_buf pointer to destination OpenCL buffer
240  * @param dst_cl_buf_size size in bytes of OpenCL buffer
241  * @param dst_cl_buf_offset the offset of the OpenCL buffer start position
242  * @param src_data array of pointers to source plane buffers
243  * @param src_plane_sizes array of sizes in bytes of the source plane buffers
244  * @param src_plane_num number of source image planes
245  * @return >=0 on success, a negative error code in case of failure
246  */
247 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
248  uint8_t **src_data, int *plane_size, int plane_num);
249 
250 /**
251  * Read image data from OpenCL buffer.
252  *
253  * @param dst_data array of pointers to destination plane buffers
254  * @param dst_plane_sizes array of pointers to destination plane buffers
255  * @param dst_plane_num number of destination image planes
256  * @param src_cl_buf pointer to source OpenCL buffer
257  * @param src_cl_buf_size size in bytes of OpenCL buffer
258  * @return >=0 on success, a negative error code in case of failure
259  */
260 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
261  cl_mem src_cl_buf, size_t cl_buffer_size);
262 
263 /**
264  * Release OpenCL buffer.
265  *
266  * @param cl_buf pointer to OpenCL buffer to release, which was
267  * previously filled with av_opencl_buffer_create()
268  */
269 void av_opencl_buffer_release(cl_mem *cl_buf);
270 
271 /**
272  * Release kernel object.
273  *
274  * @param env kernel environment where the kernel object was created
275  * with av_opencl_create_kernel()
276  */
278 
279 /**
280  * Release OpenCL environment.
281  *
282  * The OpenCL environment is effectively released only if all the created
283  * kernels had been released with av_opencl_release_kernel().
284  */
285 void av_opencl_uninit(void);
286 
287 #endif /* LIBAVUTIL_OPENCL_H */