Windows Opencl clCreateBuffer()函数

Windows Opencl clCreateBuffer()函数

Creating Buffer Objects
函数原型

cl_mem    clCreateBuffer (cl_context context,
						  cl_mem_flags flags,
						  size_t size,
          				  void *host_ptr,
                   	 	  cl_int *errcode_ret) 

context 是用于创建缓冲区对象的有效OpenCL上下文。

flags是一个位字段，用于指定分配和使用信息，例如应该用于分配缓冲区对象的内存区域以及如何使用它。表5.3描述了标志的可能值：

cl_mem_flags	描述
CL_MEM_READ_WRITE	这个标志指定内存对象将由内核读写。这是默认值。
CL_MEM_WRITE_ONLY	这个标志指定内存对象将被内核写入但不被读取。 从内核中使用CL_MEM_WRITE_ONLY创建的缓冲区或映像对象读取数据是未定义的。
CL_MEM_READ_ONLY	此标志指定内存对象在内核中使用时是只读内存对象。 写入在内核中使用CL_MEM_READ_ONLY创建的缓冲区或映像对象是未定义的。
CL_MEM_USE_HOST_PTR	此标志仅在host_ptr 不为空时有效。如果指定，则表示应用程序希望OpenCL实现使用host_ptr 引用的内存作为内存对象的存储位。 OpenCL实现允许在设备内存中缓存host_ptr 指向的缓冲区内容。在设备上执行内核时，可以使用此缓存副本。 对多个操作的 OpenCL 命令的结果
CL_MEM_ALLOC_HOST_PTR	此标志指定应用程序希望OpenCL实现从主机可访问内存分配内存。 CL_MEM_ALLOC_HOST_PTR和CL_MEM_USE_HOST_PTR是互斥的。
CL_MEM_COPY_HOST_PTR	此标志仅在host_ptr 不为空时有效。如果指定，则表示应用程序希望OpenCL实现为内存对象分配内存，并从host_ptr 引用的内存中复制数据。 CL_MEM_COPY_HOST_PTR和CL_MEM_USE_HOST_PTR是互斥的 CL_MEM_COPY_HOST_PTR可与CL_MEM_ALLOC_HOST_PTR一起使用，以初始化使用主机可访问（e.g. PCIe）内存分配的cl_mem对象的内容。

表5.3 支持的cl_mem_flags值列表

size 是要分配的缓冲区内存对象的大小（以字节为单位）。

host_ptr 是指向可能已由应用程序分配的缓冲区数据的指针。host_ptr 指向的缓冲区大小必须大于等于size 字节。

errcode_ret将返回适当的错误代码。如果errcode_ret为空，则不返回错误代码。

clCreateBuffer返回有效的非零缓冲区对象，如果成功创建缓冲区对象，则errcode_ret 设置为CL_SUCCESS。否则，它将返回一个NULL，并在errcode_ret 中返回以下错误值之一：

1. CL_INVALID_CONTEXT 如果context 不是有效的上下文。
2. CL_INVALID_VALUE 如果flags 中指定的值无效
3. CL_INVALID_BUFFER_SIZE 如果size 为0或大于表4.3中为context 中所有设备指定的CL_DEVICE_MAX_MEM_ALLOC_size值。
4. CL_INVALID_HOST_PTR 如果host_ptr为空且CL_MEM_USE_HOST_PTR 或CL_MEM_COPY_HOST_PTR设置在标志中，或者如果host_ptr不为NULL，但在flags 中未设置CL_MEM_COPY_HOST_PTR或CL_MEM_USE_HOST_PTR。
5. CL_MEM_OBJECT_ALLOCATION_FAILURE 如果为缓冲区对象分配内存失败。
6. CL_OUT_OF_HOST_MEMORY 如果在主机上分配OpenCL实现所需的资源失败。