log: Remove redundant va_list creation from missing_feature_sample()
[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  *
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 <CL/cl.h>
35 #include "config.h"
36 #include "dict.h"
37
38 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
39
40 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
41
42 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
43
44 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
45
46 typedef struct {
47     int device_type;
48     char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
49     cl_device_id device_id;
50 } AVOpenCLDeviceNode;
51
52 typedef struct {
53     cl_platform_id platform_id;
54     char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
55     int device_num;
56     AVOpenCLDeviceNode **device_node;
57 } AVOpenCLPlatformNode;
58
59 typedef struct {
60     int platform_num;
61     AVOpenCLPlatformNode **platform_node;
62 } AVOpenCLDeviceList;
63
64 typedef struct {
65     cl_command_queue command_queue;
66     cl_kernel kernel;
67     char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
68 } AVOpenCLKernelEnv;
69
70 typedef struct {
71     cl_platform_id platform_id;
72     cl_device_type device_type;
73     cl_context context;
74     cl_device_id  device_id;
75     cl_command_queue command_queue;
76     char *platform_name;
77 } AVOpenCLExternalEnv;
78
79 /**
80  * Get OpenCL device list.
81  *
82  * It must be freed with av_opencl_free_device_list().
83  *
84  * @param device_list pointer to OpenCL environment device list,
85  *                    should be released by av_opencl_free_device_list()
86  *
87  * @return  >=0 on success, a negative error code in case of failure
88  */
89 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);
90
91 /**
92   * Free OpenCL device list.
93   *
94   * @param device_list pointer to OpenCL environment device list
95   *                       created by av_opencl_get_device_list()
96   */
97 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);
98
99 /**
100  * Set option in the global OpenCL context.
101  *
102  * This options affect the operation performed by the next
103  * av_opencl_init() operation.
104  *
105  * The currently accepted options are:
106  * - build_options: set options to compile registered kernels code
107  * - platform: set index of platform in device list
108  * - device: set index of device in device list
109  *
110  * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
111  *
112  * @param key                 option key
113  * @param val                 option value
114  * @return >=0 on success, a negative error code in case of failure
115  * @see av_opencl_get_option()
116  */
117 int av_opencl_set_option(const char *key, const char *val);
118
119 /**
120  * Get option value from the global OpenCL context.
121  *
122  * @param key        option key
123  * @param out_val  pointer to location where option value will be
124  *                         written, must be freed with av_freep()
125  * @return  >=0 on success, a negative error code in case of failure
126  * @see av_opencl_set_option()
127  */
128 int av_opencl_get_option(const char *key, uint8_t **out_val);
129
130 /**
131  * Free option values of the global OpenCL context.
132  *
133  */
134 void av_opencl_free_option(void);
135
136 /**
137  * Allocate OpenCL external environment.
138  *
139  * It must be freed with av_opencl_free_external_env().
140  *
141  * @return pointer to allocated OpenCL external environment
142  */
143 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
144
145 /**
146  * Free OpenCL external environment.
147  *
148  * @param ext_opencl_env pointer to OpenCL external environment
149  *                       created by av_opencl_alloc_external_env()
150  */
151 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
152
153 /**
154  * Register kernel code.
155  *
156  *  The registered kernel code is stored in a global context, and compiled
157  *  in the runtime environment when av_opencl_init() is called.
158  *
159  * @param kernel_code    kernel code to be compiled in the OpenCL runtime environment
160  * @return  >=0 on success, a negative error code in case of failure
161  */
162 int av_opencl_register_kernel_code(const char *kernel_code);
163
164 /**
165  * Initialize the run time OpenCL environment and compile the kernel
166  * code registered with av_opencl_register_kernel_code().
167  *
168  * @param ext_opencl_env external OpenCL environment, created by an
169  *                       application program, ignored if set to NULL
170  * @return >=0 on success, a negative error code in case of failure
171  */
172  int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
173
174 /**
175  * Create kernel object in the specified kernel environment.
176  *
177  * @param env              pointer to kernel environment which is filled with
178  *                         the environment used to run the kernel
179  * @param kernel_name      kernel function name
180  * @return >=0 on success, a negative error code in case of failure
181  */
182 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
183
184 /**
185  * Create OpenCL buffer.
186  *
187  * The buffer is used to save the data used or created by an OpenCL
188  * kernel.
189  * The created buffer must be released with av_opencl_buffer_release().
190  *
191  * See clCreateBuffer() function reference for more information about
192  * the parameters.
193  *
194  * @param cl_buf       pointer to OpenCL buffer
195  * @param cl_buf_size  size in bytes of the OpenCL buffer to create
196  * @param flags        flags used to control buffer attributes
197  * @param host_ptr     host pointer of the OpenCL buffer
198  * @return >=0 on success, a negative error code in case of failure
199  */
200 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
201
202 /**
203  * Write OpenCL buffer with data from src_buf.
204  *
205  * @param dst_cl_buf        pointer to OpenCL destination buffer
206  * @param src_buf           pointer to source buffer
207  * @param buf_size          size in bytes of the source and destination buffers
208  * @return >=0 on success, a negative error code in case of failure
209  */
210 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
211
212 /**
213  * Read data from OpenCL buffer to memory buffer.
214  *
215  * @param dst_buf           pointer to destination buffer (CPU memory)
216  * @param src_cl_buf        pointer to source OpenCL buffer
217  * @param buf_size          size in bytes of the source and destination buffers
218  * @return >=0 on success, a negative error code in case of failure
219  */
220 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
221
222 /**
223  * Write image data from memory to OpenCL buffer.
224  *
225  * The source must be an array of pointers to image plane buffers.
226  *
227  * @param dst_cl_buf         pointer to destination OpenCL buffer
228  * @param dst_cl_buf_size    size in bytes of OpenCL buffer
229  * @param dst_cl_buf_offset  the offset of the OpenCL buffer start position
230  * @param src_data           array of pointers to source plane buffers
231  * @param src_plane_sizes    array of sizes in bytes of the source plane buffers
232  * @param src_plane_num      number of source image planes
233  * @return >=0 on success, a negative error code in case of failure
234  */
235 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
236                                  uint8_t **src_data, int *plane_size, int plane_num);
237
238 /**
239  * Read image data from OpenCL buffer.
240  *
241  * @param dst_data           array of pointers to destination plane buffers
242  * @param dst_plane_sizes    array of pointers to destination plane buffers
243  * @param dst_plane_num      number of destination image planes
244  * @param src_cl_buf         pointer to source OpenCL buffer
245  * @param src_cl_buf_size    size in bytes of OpenCL buffer
246  * @return >=0 on success, a negative error code in case of failure
247  */
248 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
249                                 cl_mem src_cl_buf, size_t cl_buffer_size);
250
251 /**
252  * Release OpenCL buffer.
253  *
254  * @param cl_buf pointer to OpenCL buffer to release, which was
255  *               previously filled with av_opencl_buffer_create()
256  */
257 void av_opencl_buffer_release(cl_mem *cl_buf);
258
259 /**
260  * Release kernel object.
261  *
262  * @param env kernel environment where the kernel object was created
263  *            with av_opencl_create_kernel()
264  */
265 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
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 #endif /* LIBAVUTIL_OPENCL_H */