FFmpeg: libavutil/opencl.h Source File

FFmpeg
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 "dict.h"
42 
43 #include "libavutil/version.h"
44 
45  #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
46 
47  #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
48 
49  #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
50 
51  #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
52 
53  typedef struct {
54   int device_type;
55   char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
56   cl_device_id device_id;
57 } AVOpenCLDeviceNode;
58 
59  typedef struct {
60   cl_platform_id platform_id;
61   char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
62   int device_num;
63   AVOpenCLDeviceNode **device_node;
64 } AVOpenCLPlatformNode;
65 
66  typedef struct {
67   int platform_num;
68   AVOpenCLPlatformNode **platform_node;
69 } AVOpenCLDeviceList;
70 
71 #if FF_API_OLD_OPENCL
72 typedef struct {
73  cl_command_queue command_queue;
74  cl_kernel kernel;
75  char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
76 } AVOpenCLKernelEnv;
77 #endif
78 
79  typedef struct {
80   cl_platform_id platform_id;
81   cl_device_type device_type;
82   cl_context context;
83   cl_device_id device_id;
84   cl_command_queue command_queue;
85   char *platform_name;
86 } AVOpenCLExternalEnv;
87 
88 /**
89  * Get OpenCL device list.
90  *
91  * It must be freed with av_opencl_free_device_list().
92  *
93  * @param device_list pointer to OpenCL environment device list,
94  * should be released by av_opencl_free_device_list()
95  *
96  * @return >=0 on success, a negative error code in case of failure
97  */
98 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);
99 
100 /**
101  * Free OpenCL device list.
102  *
103  * @param device_list pointer to OpenCL environment device list
104  * created by av_opencl_get_device_list()
105  */
106 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);
107 
108 /**
109  * Set option in the global OpenCL context.
110  *
111  * This options affect the operation performed by the next
112  * av_opencl_init() operation.
113  *
114  * The currently accepted options are:
115  * - platform: set index of platform in device list
116  * - device: set index of device in device list
117  *
118  * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
119  *
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()
124  */
125 int av_opencl_set_option(const char *key, const char *val);
126 
127 /**
128  * Get option value from the global OpenCL context.
129  *
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()
135  */
136 int av_opencl_get_option(const char *key, uint8_t **out_val);
137 
138 /**
139  * Free option values of the global OpenCL context.
140  *
141  */
142 void av_opencl_free_option(void);
143 
144 /**
145  * Allocate OpenCL external environment.
146  *
147  * It must be freed with av_opencl_free_external_env().
148  *
149  * @return pointer to allocated OpenCL external environment
150  */
151 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
152 
153 /**
154  * Free OpenCL external environment.
155  *
156  * @param ext_opencl_env pointer to OpenCL external environment
157  * created by av_opencl_alloc_external_env()
158  */
159 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
160 
161 /**
162  * Get OpenCL error string.
163  *
164  * @param status OpenCL error code
165  * @return OpenCL error string
166  */
167 const char *av_opencl_errstr(cl_int status);
168 
169 /**
170  * Register kernel code.
171  *
172  * The registered kernel code is stored in a global context, and compiled
173  * in the runtime environment when av_opencl_init() is called.
174  *
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
177  */
178 int av_opencl_register_kernel_code(const char *kernel_code);
179 
180 /**
181  * Initialize the run time OpenCL environment
182  *
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
186  */
187 int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
188 
189 #if FF_API_OLD_OPENCL
190 /**
191  * Create kernel object in the specified kernel environment.
192  *
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
198  */
199 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
200 #endif
201 
202 /**
203  * compile specific OpenCL kernel source
204  *
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
209  */
210 cl_program av_opencl_compile(const char *program_name, const char* build_opts);
211 
212 /**
213  * get OpenCL command queue
214  *
215  * @return a cl_command_queue object
216  */
217 cl_command_queue av_opencl_get_command_queue(void);
218 
219 /**
220  * Create OpenCL buffer.
221  *
222  * The buffer is used to save the data used or created by an OpenCL
223  * kernel.
224  * The created buffer must be released with av_opencl_buffer_release().
225  *
226  * See clCreateBuffer() function reference for more information about
227  * the parameters.
228  *
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
234  */
235 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
236 
237 /**
238  * Write OpenCL buffer with data from src_buf.
239  *
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
244  */
245 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
246 
247 /**
248  * Read data from OpenCL buffer to memory buffer.
249  *
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
254  */
255 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
256 
257 /**
258  * Write image data from memory to OpenCL buffer.
259  *
260  * The source must be an array of pointers to image plane buffers.
261  *
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
269  */
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);
272 
273 /**
274  * Read image data from OpenCL buffer.
275  *
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
282  */
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);
285 
286 /**
287  * Release OpenCL buffer.
288  *
289  * @param cl_buf pointer to OpenCL buffer to release, which was
290  * previously filled with av_opencl_buffer_create()
291  */
292 void av_opencl_buffer_release(cl_mem *cl_buf);
293 
294 #if FF_API_OLD_OPENCL
295 /**
296  * Release kernel object.
297  *
298  * @param env kernel environment where the kernel object was created
299  * with av_opencl_create_kernel()
300  * @deprecated, use clReleaseKernel
301  */
302 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
303 #endif
304 
305 /**
306  * Release OpenCL environment.
307  *
308  * The OpenCL environment is effectively released only if all the created
309  * kernels had been released with av_opencl_release_kernel().
310  */
311 void av_opencl_uninit(void);
312 
313 /**
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.
318  *
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
324  * of failure
325  */
326 int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform,
327  int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env));
328 
329 #endif /* LIBAVUTIL_OPENCL_H */
Generated on Sun Mar 23 2014 23:50:15 for FFmpeg by   doxygen 1.8.2

AltStyle によって変換されたページ (->オリジナル) /