summaryrefslogtreecommitdiff
path: root/libavutil/opencl.h (plain)
blob: b709927c427397fa249c9e4780a2eb9260b4e552
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
48typedef struct {
49 int device_type;
50 char *device_name;
51 cl_device_id device_id;
52} AVOpenCLDeviceNode;
53
54typedef struct {
55 cl_platform_id platform_id;
56 char *platform_name;
57 int device_num;
58 AVOpenCLDeviceNode **device_node;
59} AVOpenCLPlatformNode;
60
61typedef struct {
62 int platform_num;
63 AVOpenCLPlatformNode **platform_node;
64} AVOpenCLDeviceList;
65
66typedef 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 */
85int 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 */
93void 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 */
112int 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 */
123int av_opencl_get_option(const char *key, uint8_t **out_val);
124
125/**
126 * Free option values of the global OpenCL context.
127 *
128 */
129void 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 */
138AVOpenCLExternalEnv *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 */
146void 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 */
154const 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 */
165int 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 */
174int 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 */
184cl_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 */
191cl_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 */
209int 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 */
219int 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 */
229int 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 */
244int 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 */
257int 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 */
266void 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 */
274void 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 */
289int64_t av_opencl_benchmark(AVOpenCLDeviceNode *device, cl_platform_id platform,
290 int64_t (*benchmark)(AVOpenCLExternalEnv *ext_opencl_env));
291
292#endif /* AVUTIL_OPENCL_H */
293
generated by cgit at 2024-05-17 06:08:23 (GMT)