OpenCL基础 -- clEnqueueNDRangeKernel 接口使用说明

clEnqueueNDRangeKernel 接口使用说明

clEnqueueNDRangeKernel 是 OpenCL 中一个关键的 API，用于将 OpenCL 的 kernel 提交到命令队列中执行。其基本作用是启动一个内核执行，并指定其工作项（Work-item）分布在多维度的 NDRange 上。

函数原型

cl_int clEnqueueNDRangeKernel(
    cl_command_queue command_queue, // 命令队列
    cl_kernel kernel,               // 要执行的内核
    cl_uint work_dim,               // 工作维度，范围是1到3
    const size_t *global_work_offset, // 全局工作项的偏移
    const size_t *global_work_size,   // 全局工作项的大小
    const size_t *local_work_size,    // 局部工作项的大小
    cl_uint num_events_in_wait_list,  // 依赖的事件数量
    const cl_event *event_wait_list,  // 依赖事件的列表
    cl_event *event                  // 返回的事件
);

参数解释

1. command_queue: OpenCL 的命令队列，指定在哪个设备上执行该 kernel。

2. kernel: 需要执行的 OpenCL kernel 对象。

3. work_dim: 工作维度，可以是 1、2 或 3 维度的工作区。

4. global_work_offset: 全局工作项的偏移量，可以设为 NULL，表示从(0,0,0)开始。

5. global_work_size: 全局工作区的大小。它定义了 NDRange 中每个维度的工作项数量。例如，global_work_size 为 {1024, 1, 1} 表示有 1024 个工作项（如果是 1 维），{1024, 1024, 1} 表示有 1024x1024 个工作项（如果是 2 维）。

6. local_work_size: 局部工作区大小，指定每个工作组中工作项的数量。如果设置为 NULL，OpenCL 将自动决定工作组大小。

7. num_events_in_wait_list: 需要等待完成的事件数量。如果没有依赖事件，则设置为 0。

8. event_wait_list: 需要等待的事件列表。如果没有依赖事件，则设置为 NULL。

9. event: 如果不为 NULL，会返回一个事件句柄，通过该句柄可以跟踪内核的执行状态。

示例代码

// 示例：执行一个二维的 kernel

cl_command_queue queue = /* 已创建的命令队列 */;
cl_kernel kernel = /* 已创建的内核对象 */;

size_t global_work_size[2] = {1024, 1024}; // 1024x1024 的全局工作区
size_t local_work_size[2] = {16, 16};      // 16x16 的局部工作区

// 启动 kernel
cl_int err = clEnqueueNDRangeKernel(
    queue,
    kernel,
    2,               // 2 维
    NULL,            // 全局偏移量设为 NULL
    global_work_size,// 全局工作区大小
    local_work_size, // 局部工作区大小
    0,               // 没有依赖的事件
    NULL,            // 没有依赖的事件列表
    NULL             // 不需要返回的事件句柄
);

if (err != CL_SUCCESS) {
    // 错误处理
}

注意事项

1. 局部工作区：如果设置了 local_work_size，它的每个维度必须能够整除相应维度的 global_work_size，否则会导致执行失败。

2. 性能优化：合理设置 local_work_size，可以优化性能，通常建议根据硬件特性来选择。

3. 事件依赖：如果有多个 kernel 之间有依赖关系，可以使用 event_wait_list 和 event 参数来控制执行顺序。