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  *
   6  * This file is part of FFmpeg.
   7  *
   8  * FFmpeg is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * FFmpeg is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with FFmpeg; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  21  */
  22
  23 /**
  24  * @file
  25  * OpenCL wrapper
  26  *
  27  * This interface is considered still experimental and its API and ABI may
  28  * change without prior notice.
  29  */
  30
  31 #ifndef LIBAVUTIL_OPENCL_H
  32 #define LIBAVUTIL_OPENCL_H
  33
  34 #include "config.h"
  35 #if HAVE_CL_CL_H
  36 #include <CL/cl.h>
  37 #else
  38 #include <OpenCL/cl.h>
  39 #endif
  40 #include "dict.h"
  41
  42 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
  43
  44 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
  45
  46 #define AV_OPENCL_MAX_DEVICE_NAME_SIZE 100
  47
  48 #define AV_OPENCL_MAX_PLATFORM_NAME_SIZE 100
  49
  50 typedef struct {
  51     int device_type;
  52     char device_name[AV_OPENCL_MAX_DEVICE_NAME_SIZE];
  53     cl_device_id device_id;
  54 } AVOpenCLDeviceNode;
  55
  56 typedef struct {
  57     cl_platform_id platform_id;
  58     char platform_name[AV_OPENCL_MAX_PLATFORM_NAME_SIZE];
  59     int device_num;
  60     AVOpenCLDeviceNode **device_node;
  61 } AVOpenCLPlatformNode;
  62
  63 typedef struct {
  64     int platform_num;
  65     AVOpenCLPlatformNode **platform_node;
  66 } AVOpenCLDeviceList;
  67
  68 typedef struct {
  69     cl_command_queue command_queue;
  70     cl_kernel kernel;
  71     char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
  72 } AVOpenCLKernelEnv;
  73
  74 typedef struct {
  75     cl_platform_id platform_id;
  76     cl_device_type device_type;
  77     cl_context context;
  78     cl_device_id  device_id;
  79     cl_command_queue command_queue;
  80     char *platform_name;
  81 } AVOpenCLExternalEnv;
  82
  83 /**
  84  * Get OpenCL device list.
  85  *
  86  * It must be freed with av_opencl_free_device_list().
  87  *
  88  * @param device_list pointer to OpenCL environment device list,
  89  *                    should be released by av_opencl_free_device_list()
  90  *
  91  * @return  >=0 on success, a negative error code in case of failure
  92  */
  93 int av_opencl_get_device_list(AVOpenCLDeviceList **device_list);
  94
  95 /**
  96   * Free OpenCL device list.
  97   *
  98   * @param device_list pointer to OpenCL environment device list
  99   *                       created by av_opencl_get_device_list()
 100   */
 101 void av_opencl_free_device_list(AVOpenCLDeviceList **device_list);
 102
 103 /**
 104  * Set option in the global OpenCL context.
 105  *
 106  * This options affect the operation performed by the next
 107  * av_opencl_init() operation.
 108  *
 109  * The currently accepted options are:
 110  * - build_options: set options to compile registered kernels code
 111  * - platform: set index of platform in device list
 112  * - device: set index of device in device list
 113  *
 114  * See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
 115  *
 116  * @param key                 option key
 117  * @param val                 option value
 118  * @return >=0 on success, a negative error code in case of failure
 119  * @see av_opencl_get_option()
 120  */
 121 int av_opencl_set_option(const char *key, const char *val);
 122
 123 /**
 124  * Get option value from the global OpenCL context.
 125  *
 126  * @param key        option key
 127  * @param out_val  pointer to location where option value will be
 128  *                         written, must be freed with av_freep()
 129  * @return  >=0 on success, a negative error code in case of failure
 130  * @see av_opencl_set_option()
 131  */
 132 int av_opencl_get_option(const char *key, uint8_t **out_val);
 133
 134 /**
 135  * Free option values of the global OpenCL context.
 136  *
 137  */
 138 void av_opencl_free_option(void);
 139
 140 /**
 141  * Allocate OpenCL external environment.
 142  *
 143  * It must be freed with av_opencl_free_external_env().
 144  *
 145  * @return pointer to allocated OpenCL external environment
 146  */
 147 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
 148
 149 /**
 150  * Free OpenCL external environment.
 151  *
 152  * @param ext_opencl_env pointer to OpenCL external environment
 153  *                       created by av_opencl_alloc_external_env()
 154  */
 155 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
 156
 157 /**
 158  * Get OpenCL error string.
 159  *
 160  * @param status    OpenCL error code
 161  * @return OpenCL error string
 162  */
 163 const char *av_opencl_errstr(cl_int status);
 164
 165 /**
 166  * Register kernel code.
 167  *
 168  *  The registered kernel code is stored in a global context, and compiled
 169  *  in the runtime environment when av_opencl_init() is called.
 170  *
 171  * @param kernel_code    kernel code to be compiled in the OpenCL runtime environment
 172  * @return  >=0 on success, a negative error code in case of failure
 173  */
 174 int av_opencl_register_kernel_code(const char *kernel_code);
 175
 176 /**
 177  * Initialize the run time OpenCL environment and compile the kernel
 178  * code registered with av_opencl_register_kernel_code().
 179  *
 180  * @param ext_opencl_env external OpenCL environment, created by an
 181  *                       application program, ignored if set to NULL
 182  * @return >=0 on success, a negative error code in case of failure
 183  */
 184  int av_opencl_init(AVOpenCLExternalEnv *ext_opencl_env);
 185
 186 /**
 187  * Create kernel object in the specified kernel environment.
 188  *
 189  * @param env              pointer to kernel environment which is filled with
 190  *                         the environment used to run the kernel
 191  * @param kernel_name      kernel function name
 192  * @return >=0 on success, a negative error code in case of failure
 193  */
 194 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
 195
 196 /**
 197  * Create OpenCL buffer.
 198  *
 199  * The buffer is used to save the data used or created by an OpenCL
 200  * kernel.
 201  * The created buffer must be released with av_opencl_buffer_release().
 202  *
 203  * See clCreateBuffer() function reference for more information about
 204  * the parameters.
 205  *
 206  * @param cl_buf       pointer to OpenCL buffer
 207  * @param cl_buf_size  size in bytes of the OpenCL buffer to create
 208  * @param flags        flags used to control buffer attributes
 209  * @param host_ptr     host pointer of the OpenCL buffer
 210  * @return >=0 on success, a negative error code in case of failure
 211  */
 212 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
 213
 214 /**
 215  * Write OpenCL buffer with data from src_buf.
 216  *
 217  * @param dst_cl_buf        pointer to OpenCL destination buffer
 218  * @param src_buf           pointer to source buffer
 219  * @param buf_size          size in bytes of the source and destination buffers
 220  * @return >=0 on success, a negative error code in case of failure
 221  */
 222 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
 223
 224 /**
 225  * Read data from OpenCL buffer to memory buffer.
 226  *
 227  * @param dst_buf           pointer to destination buffer (CPU memory)
 228  * @param src_cl_buf        pointer to source OpenCL buffer
 229  * @param buf_size          size in bytes of the source and destination buffers
 230  * @return >=0 on success, a negative error code in case of failure
 231  */
 232 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
 233
 234 /**
 235  * Write image data from memory to OpenCL buffer.
 236  *
 237  * The source must be an array of pointers to image plane buffers.
 238  *
 239  * @param dst_cl_buf         pointer to destination OpenCL buffer
 240  * @param dst_cl_buf_size    size in bytes of OpenCL buffer
 241  * @param dst_cl_buf_offset  the offset of the OpenCL buffer start position
 242  * @param src_data           array of pointers to source plane buffers
 243  * @param src_plane_sizes    array of sizes in bytes of the source plane buffers
 244  * @param src_plane_num      number of source image planes
 245  * @return >=0 on success, a negative error code in case of failure
 246  */
 247 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
 248                                  uint8_t **src_data, int *plane_size, int plane_num);
 249
 250 /**
 251  * Read image data from OpenCL buffer.
 252  *
 253  * @param dst_data           array of pointers to destination plane buffers
 254  * @param dst_plane_sizes    array of pointers to destination plane buffers
 255  * @param dst_plane_num      number of destination image planes
 256  * @param src_cl_buf         pointer to source OpenCL buffer
 257  * @param src_cl_buf_size    size in bytes of OpenCL buffer
 258  * @return >=0 on success, a negative error code in case of failure
 259  */
 260 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
 261                                 cl_mem src_cl_buf, size_t cl_buffer_size);
 262
 263 /**
 264  * Release OpenCL buffer.
 265  *
 266  * @param cl_buf pointer to OpenCL buffer to release, which was
 267  *               previously filled with av_opencl_buffer_create()
 268  */
 269 void av_opencl_buffer_release(cl_mem *cl_buf);
 270
 271 /**
 272  * Release kernel object.
 273  *
 274  * @param env kernel environment where the kernel object was created
 275  *            with av_opencl_create_kernel()
 276  */
 277 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
 278
 279 /**
 280  * Release OpenCL environment.
 281  *
 282  * The OpenCL environment is effectively released only if all the created
 283  * kernels had been released with av_opencl_release_kernel().
 284  */
 285 void av_opencl_uninit(void);
 286
 287 #endif /* LIBAVUTIL_OPENCL_H */