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