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