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