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