aboutsummaryrefslogtreecommitdiffstats
path: root/libavutil/opencl.h
blob: 168461dc3447431f21c457a140b6ca1113e079a1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
/*
 * Copyright (C) 2012 Peng  Gao     <peng@multicorewareinc.com>
 * Copyright (C) 2012 Li    Cao     <li@multicorewareinc.com>
 * Copyright (C) 2012 Wei   Gao     <weigao@multicorewareinc.com>
 * Copyright (C) 2013 Lenny Wang    <lwanghpc@gmail.com>
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

/**
 * @file
 * OpenCL wrapper
 *
 * This interface is considered still experimental and its API and ABI may
 * change without prior notice.
 */

#ifndef LIBAVUTIL_OPENCL_H
#define LIBAVUTIL_OPENCL_H

#define CL_USE_DEPRECATED_OPENCL_1_2_APIS 1
#ifdef __APPLE__
#include <OpenCL/cl.h>
#else
#include <CL/cl.h>
#endif
#include <stdint.h>
#include "dict.h"

#include "libavutil/version.h"

#define AV_OPENCL_KERNEL( ... )# __VA_ARGS__

typedef struct {
    int device_type;
    char *device_name;
    cl_device_id device_id;
} AVOpenCLDeviceNode;

typedef struct {
    cl_platform_id platform_id;
    char *platform_name;
    int device_num;
    AVOpenCLDeviceNode **device_node;
} AVOpenCLPlatformNode;

typedef struct {
    int platform_num;
    AVOpenCLPlatformNode **platform_node;
} AVOpenCLDeviceList;

typedef struct {
    cl_platform_id platform_id;
    cl_device_type device_type;
    cl_context context;
    cl_device_id  device_id;
    cl_command_queue command_queue;
    char *platform_name;
} AVOpenCLExternalEnv;

/**
 * Get OpenCL device list.
 *
 * It must be freed with av_opencl_free_device_list().
 *
 * @param device_list pointer to OpenCL environment device list,
 *                    should be released by av_opencl_free_device_list()
 *
 * @return  >=0 on success, a negative error code in case of failure
 */
int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);

/**
  * Free OpenCL device list.
  *
  * @param device_list pointer to OpenCL environment device list
  *                       created by av_opencl_get_device_list()
  */
void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);

/**
 * Set option in the global OpenCL context.
 *
 * This options affect the operation performed by the next
 * av_opencl_init() operation.
 *
 * The currently accepted options are:
 * - platform: set index of platform in device list
 * - device: set index of device in device list
 *
 * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
 *
 * @param key                 option key
 * @param val                 option value
 * @return >=0 on success, a negative error code in case of failure
 * @see av_opencl_get_option()
 */
int av_opencl_set_option(const char *key, const char *val);

/**
 * Get option value from the global OpenCL context.
 *
 * @param key        option key
 * @param out_val  pointer to location where option value will be
 *                         written, must be freed with av_freep()
 * @return  >=0 on success, a negative error code in case of failure
 * @see av_opencl_set_option()
 */
int av_opencl_get_option(const char *key, uint8_t **out_val);

/**
 * Free option values of the global OpenCL context.
 *
 */
void av_opencl_free_option(void);

/**
 * Allocate OpenCL external environment.
 *
 * It must be freed with av_opencl_free_external_env().
 *
 * @return pointer to allocated OpenCL external environment
 */
AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);

/**
 * Free OpenCL external environment.
 *
 * @param ext_opencl_env pointer to OpenCL external environment
 *                       created by av_opencl_alloc_external_env()
 */
void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);

/**
 * Get OpenCL error string.
 *
 * @param status    OpenCL error code
 * @return OpenCL error string
 */
const char *av_opencl_errstr(cl_int status);

/**
 * Register kernel code.
 *
 *  The registered kernel code is stored in a global context, and compiled
 *  in the runtime environment when av_opencl_init() is called.
 *
 * @param kernel_code    kernel code to be compiled in the OpenCL runtime environment
 * @return  >=0 on success, a negative error code in case of failure
 */
int av_opencl_register_kernel_code(const char *kernel_code);

/**
 * Initialize the run time OpenCL environment
 *
 * @param ext_opencl_env external OpenCL environment, created by an
 *                       application program, ignored if set to NULL
 * @return >=0 on success, a negative error code in case of failure
 */
int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);

/**
 * compile specific OpenCL kernel source
 *
 * @param program_name  pointer to a program name used for identification
 * @param build_opts    pointer to a string that describes the preprocessor
 *                      build options to be used for building the program
 * @return a cl_program object
 */
cl_program av_opencl_compile(const char *program_name, const char* build_opts);

/**
 * get OpenCL command queue
 *
 * @return a cl_command_queue object
 */
cl_command_queue av_opencl_get_command_queue(void);

/**
 * Create OpenCL buffer.
 *
 * The buffer is used to save the data used or created by an OpenCL
 * kernel.
 * The created buffer must be released with av_opencl_buffer_release().
 *
 * See clCreateBuffer() function reference for more information about
 * the parameters.
 *
 * @param cl_buf       pointer to OpenCL buffer
 * @param cl_buf_size  size in bytes of the OpenCL buffer to create
 * @param flags        flags used to control buffer attributes
 * @param host_ptr     host pointer of the OpenCL buffer
 * @return >=0 on success, a negative error code in case of failure
 */
int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);

/**
 * Write OpenCL buffer with data from src_buf.
 *
 * @param dst_cl_buf        pointer to OpenCL destination buffer
 * @param src_buf           pointer to source buffer
 * @param buf_size          size in bytes of the source and destination buffers
 * @return >=0 on success, a negative error code in case of failure
 */
int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);

/**
 * Read data from OpenCL buffer to memory buffer.
 *
 * @param dst_buf           pointer to destination buffer (CPU memory)
 * @param src_cl_buf        pointer to source OpenCL buffer
 * @param buf_size          size in bytes of the source and destination buffers
 * @return >=0 on success, a negative error code in case of failure
 */
int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);

/**
 * Write image data from memory to OpenCL buffer.
 *
 * The source must be an array of pointers to image plane buffers.
 *
 * @param dst_cl_buf         pointer to destination OpenCL buffer
 * @param dst_cl_buf_size    size in bytes of OpenCL buffer
 * @param dst_cl_buf_offset  the offset of the OpenCL buffer start position
 * @param src_data           array of pointers to source plane buffers
 * @param src_plane_sizes    array of sizes in bytes of the source plane buffers
 * @param src_plane_num      number of source image planes
 * @return >=0 on success, a negative error code in case of failure
 */
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);

/**
 * Read image data from OpenCL buffer.
 *
 * @param dst_data           array of pointers to destination plane buffers
 * @param dst_plane_sizes    array of pointers to destination plane buffers
 * @param dst_plane_num      number of destination image planes
 * @param src_cl_buf         pointer to source OpenCL buffer
 * @param src_cl_buf_size    size in bytes of OpenCL buffer
 * @return >=0 on success, a negative error code in case of failure
 */
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);

/**
 * Release OpenCL buffer.
 *
 * @param cl_buf pointer to OpenCL buffer to release, which was
 *               previously filled with av_opencl_buffer_create()
 */
void av_opencl_buffer_release(cl_mem *cl_buf);

/**
 * Release OpenCL environment.
 *
 * The OpenCL environment is effectively released only if all the created
 * kernels had been released with av_opencl_release_kernel().
 */
void av_opencl_uninit(void);

/**
 * Benchmark an OpenCL device with a user defined callback function.  This function
 * sets up an external OpenCL environment including context and command queue on
 * the device then tears it down in the end.  The callback function should perform
 * the rest of the work.
 *
 * @param device            pointer to the OpenCL device to be used
 * @param platform          cl_platform_id handle to which the device belongs to
 * @param benchmark         callback function to perform the benchmark, return a
 *                          negative value in case of failure
 * @return the score passed from the callback function, a negative error code in case
 * of failure
 */
int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform,
                            int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env));

#endif /* LIBAVUTIL_OPENCL_H */