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 <CL/cl.h>
  35 #include "config.h"
  36 #include "dict.h"
  37
  38 #define AV_OPENCL_KERNEL( ... )# __VA_ARGS__
  39
  40 #define AV_OPENCL_MAX_KERNEL_NAME_SIZE 150
  41
  42 typedef struct {
  43     cl_command_queue command_queue;
  44     cl_kernel kernel;
  45     char kernel_name[AV_OPENCL_MAX_KERNEL_NAME_SIZE];
  46 } AVOpenCLKernelEnv;
  47
  48 typedef struct {
  49     cl_platform_id platform_id;
  50     cl_device_type device_type;
  51     cl_context context;
  52     cl_device_id *device_ids;
  53     cl_device_id  device_id;
  54     cl_command_queue command_queue;
  55     char *platform_name;
  56 } AVOpenCLExternalEnv;
  57
  58 /**
  59  * Allocate OpenCL external environment.
  60  *
  61  * It must be freed with av_opencl_free_external_env().
  62  *
  63  * @return pointer to allocated OpenCL external environment
  64  */
  65 AVOpenCLExternalEnv *av_opencl_alloc_external_env(void);
  66
  67 /**
  68  * Free OpenCL external environment.
  69  *
  70  * @param ext_opencl_env pointer to OpenCL external environment
  71  *                       created by av_opencl_alloc_external_env()
  72  */
  73 void av_opencl_free_external_env(AVOpenCLExternalEnv **ext_opencl_env);
  74
  75 /**
  76  * Register kernel code.
  77  *
  78  *  The registered kernel code is stored in a global context, and compiled
  79  *  in the runtime environment when av_opencl_init() is called.
  80  *
  81  * @param kernel_code    kernel code to be compiled in the OpenCL runtime environment
  82  * @return  >=0 on success, a negative error code in case of failure
  83  */
  84 int av_opencl_register_kernel_code(const char *kernel_code);
  85
  86 /**
  87  * Initialize the run time OpenCL environment and compile the kernel
  88  * code registered with av_opencl_register_kernel_code().
  89  *
  90  * Currently, the only accepted option is "build_options", used to set
  91  * options to compile registered kernels code. See reference "OpenCL
  92  * Specification Version: 1.2 chapter 5.6.4".
  93  *
  94  * @param options        dictionary of key/value options
  95  * @param ext_opencl_env external OpenCL environment, created by an
  96  *                       application program, ignored if set to NULL
  97  * @return >=0 on success, a negative error code in case of failure
  98  */
  99  int av_opencl_init(AVDictionary *options, AVOpenCLExternalEnv *ext_opencl_env);
 100
 101 /**
 102  * Create kernel object in the specified kernel environment.
 103  *
 104  * @param env              pointer to kernel environment which is filled with
 105  *                         the environment used to run the kernel
 106  * @param kernel_name      kernel function name
 107  * @return >=0 on success, a negative error code in case of failure
 108  */
 109 int av_opencl_create_kernel(AVOpenCLKernelEnv *env, const char *kernel_name);
 110
 111 /**
 112  * Create OpenCL buffer.
 113  *
 114  * The buffer is used to save the data used or created by an OpenCL
 115  * kernel.
 116  * The created buffer must be released with av_opencl_buffer_release().
 117  *
 118  * See clCreateBuffer() function reference for more information about
 119  * the parameters.
 120  *
 121  * @param cl_buf       pointer to OpenCL buffer
 122  * @param cl_buf_size  size in bytes of the OpenCL buffer to create
 123  * @param flags        flags used to control buffer attributes
 124  * @param host_ptr     host pointer of the OpenCL buffer
 125  * @return >=0 on success, a negative error code in case of failure
 126  */
 127 int av_opencl_buffer_create(cl_mem *cl_buf, size_t cl_buf_size, int flags, void *host_ptr);
 128
 129 /**
 130  * Write OpenCL buffer with data from src_buf.
 131  *
 132  * @param dst_cl_buf        pointer to OpenCL destination buffer
 133  * @param src_buf           pointer to source buffer
 134  * @param buf_size          size in bytes of the source and destination buffers
 135  * @return >=0 on success, a negative error code in case of failure
 136  */
 137 int av_opencl_buffer_write(cl_mem dst_cl_buf, uint8_t *src_buf, size_t buf_size);
 138
 139 /**
 140  * Read data from OpenCL buffer to memory buffer.
 141  *
 142  * @param dst_buf           pointer to destination buffer (CPU memory)
 143  * @param src_cl_buf        pointer to source OpenCL buffer
 144  * @param buf_size          size in bytes of the source and destination buffers
 145  * @return >=0 on success, a negative error code in case of failure
 146  */
 147 int av_opencl_buffer_read(uint8_t *dst_buf, cl_mem src_cl_buf, size_t buf_size);
 148
 149 /**
 150  * Write image data from memory to OpenCL buffer.
 151  *
 152  * The source must be an array of pointers to image plane buffers.
 153  *
 154  * @param dst_cl_buf         pointer to destination OpenCL buffer
 155  * @param dst_cl_buf_size    size in bytes of OpenCL buffer
 156  * @param dst_cl_buf_offset  the offset of the OpenCL buffer start position
 157  * @param src_data           array of pointers to source plane buffers
 158  * @param src_plane_sizes    array of sizes in bytes of the source plane buffers
 159  * @param src_plane_num      number of source image planes
 160  * @return >=0 on success, a negative error code in case of failure
 161  */
 162 int av_opencl_buffer_write_image(cl_mem dst_cl_buf, size_t cl_buffer_size, int dst_cl_offset,
 163                                  uint8_t **src_data, int *plane_size, int plane_num);
 164
 165 /**
 166  * Read image data from OpenCL buffer.
 167  *
 168  * @param dst_data           array of pointers to destination plane buffers
 169  * @param dst_plane_sizes    array of pointers to destination plane buffers
 170  * @param dst_plane_num      number of destination image planes
 171  * @param src_cl_buf         pointer to source OpenCL buffer
 172  * @param src_cl_buf_size    size in bytes of OpenCL buffer
 173  * @return >=0 on success, a negative error code in case of failure
 174  */
 175 int av_opencl_buffer_read_image(uint8_t **dst_data, int *plane_size, int plane_num,
 176                                 cl_mem src_cl_buf, size_t cl_buffer_size);
 177
 178 /**
 179  * Release OpenCL buffer.
 180  *
 181  * @param cl_buf pointer to OpenCL buffer to release, which was
 182  *               previously filled with av_opencl_buffer_create()
 183  */
 184 void av_opencl_buffer_release(cl_mem *cl_buf);
 185
 186 /**
 187  * Release kernel object.
 188  *
 189  * @param env kernel environment where the kernel object was created
 190  *            with av_opencl_create_kernel()
 191  */
 192 void av_opencl_release_kernel(AVOpenCLKernelEnv *env);
 193
 194 /**
 195  * Release OpenCL environment.
 196  *
 197  * The OpenCL environment is effectively released only if all the created
 198  * kernels had been released with av_opencl_release_kernel().
 199  */
 200 void av_opencl_uninit(void);
 201
 202 #endif /* LIBAVUTIL_OPENCL_H */