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