OpenCL Programming Step (V): Creating a Buffered Object

Cl_mem Clcreatebuffer (cl_context context, cl_mem_flags flags, size_t size, void *host_ptr, cl_int *errcode_ret) This function is used to create The Cache object. Context is the OPENCL context used to create the cached object. Flags is a bit field that indicates how and how the allocated cache objects are used. If the value of flags is zero, the default value of Cl_mem_read_write is used.

Cl_mem_flags

Cl_mem_read_write

Indicates that this memory object is readable and writable. This is the default value.

Cl_mem_write_only

Can only be written and unreadable, the read operation of this memory object is undefined. Cl_mem_read_write and cl_mem_read_only are mutually exclusive.

Cl_mem_read_only

The write operation to this memory object is undefined, and can only be read and not written. Cl_mem_read_write and cl_mem_write_only are mutually exclusive.

Cl_mem_use_host_ptr

Valid only if HOST_PTR is not null. It indicates that the application wants the OPENCL operation to use the memory referenced by Host_ptr to store the contents of the Memory object. The OpenCL operation can save a host_ptr referenced memory as a cache in device memory. This copy can be used when the kernel is executing on the device. If more than one cache object is created by the same host_ptr, or if there are overlapping areas, the OPENCL command operates on these cached objects, and the result is undefined. When you create a memory object with Cl_mem_use_host_ptr, the host_ptr must have an alignment rule.

Cl_mem_alloc_host_ptr

Indicates that the application wants an OPENCL operation to allocate memory in memory that the host can access. Mutually exclusive with CL_MEM_USE_HOST_PTR.

Cl_mem_copy_host_ptr

Valid only if HOST_PTR is not null. It indicates that the application wants the OPENCL operation to use the memory referenced by HOST_PTR to allocate memory for the memory object and copy the data. It is mutually exclusive with cl_mem_use_host_ptr. When used with cl_mem_alloc_host_ptr, it is possible to initialize a Cl_mem object that is allocated by the host accessible memory.

Cl_mem_host_write_only

Indicates that the host command writes to this memory image. Can be used to optimize the host's write operations.

Cl_mem_host_read_only

Indicates that the host command is reading this memory object. He is mutually exclusive with cl_mem_host_write_only.

Cl_mem_host_no_access

Indicates that the host does not read and write to this memory object. Cl_mem_host_write_only and cl_mem_host_read_only are mutually exclusive with cl_mem_host_no_access.

Size is the amount of cache object to allocate, in bytes. Host_ptr points to cached data that may already have been allocated by the application. It must be greater than or equal to size. The Errcode_ret is used to return an error code. If NULL, it is ignored. If Clcreatebuffer successfully created the cache object, the corresponding address is returned, and Errcode_ret is set to cl_success. Otherwise, NULL is returned, and Errcode_ret is placed as one of the following error codes: Cl_invalid_context, invalid context. The value of CL__INVALID_VALUE,FALGS is not a supported value. Cl_invalid_buffer_size, size is 0. Cl_invalid_host_ptr, if host_ptr is null, but cl_mem_use_hsot_ptr or cl_mem_copy_hsot_ptr is set in flags, or HOST_PTR is not NULL, However, cl_mem_use_host_ptr or cl_mem_copy_host_ptr are not set in flags. Cl_mem_object_allocation_failure, failed to allocate memory for cache object. Cl_out_of_resources, failed to allocate memory for the OPENCL operation on the device.
Cl_out_of_host_memory, failed to allocate memory for the OPENCL operation on the host.

2. Create a sub-buffer

Cl_mem Clcreatesubbuffer (cl_mem buffer, cl_mem_flags flags, Cl_buffer_create_type buffer_create_type, const void * Buffer_create_info, Cl_int *errcode_ret) This function can create a new cache object, called a sub-buffer object, by an existing cache object. Buffer must be a valid buffer object and cannot be a sub-buffer object. Flags is a bit field used to indicate if a memory object is allocated and used. Ibid. clcreatebuffer. Buffer_create_type and Buffer_create_info indicate the type of buffer object you want to create. Errcode_ret returns the error code. If NULL, it is ignored.

Cl_buffer_create_type

Cl_buffer_create_type_region

Creates a buffer object with a specific area in buffer. Buffer_create_info points to the following data structure: struct _cl_buffer_region { size_t origin; size_t size; }cl_buffer_region; (Origin, size) is the offset and number of bytes in buffer. If buffer is created with cl_mem_use_host_ptr, the host_ptr of the returned buffer object is HOST_PTR + origin. The buffer object returned refers to the data storage space allocated for buffer and points to a specific region (origin, size). If the region (origin, size) is out of bounds in buffer, Cl_invalid_value is returned in Errcode_ret. If SIZE is 0, Cl_invalid_buffer_size is returned. If no device's cl_device_mem_base_addr_align is aligned with Origin in the context associated with BUFFER, the Cl_misaligned_sub_buffer_offset is returned.

3. Querying information about memory objects

Cl_int Clgetmemobjectinfo (Cl_mem memobj, Cl_mem_info param_name, size_t param_value_size, void *param_value, size_t Param_value_size_ret) memobj Specifies the memory object that you want to query. PARAM_NAME Specifies the information that you want to query. Param_value points to the memory used to hold the query results. If NULL, it is ignored. Param_value_size is the size, in bytes, of the memory block that Param_value refers to. Its value must be greater than or equal to the size of the Param_name type. If NULL, it is ignored. Param_value_size_ret returns the actual size of the query results. If NULL, it is ignored.

Cl_mem_info	return type	Describe
Cl_mem_type	Cl_mem_object_type	Returns one of the following values: Cl_mem_object_buffer,memobj using Clcreate{buffer | Subbuffer} was created. Cl_image_desc.image_type, create with Clcreateimage
Cl_mem_flags	Cl_mem_flags	Return with Clcreate{buffer | Subbuffer} created the memobj when the parameter flags are drawn. If Memobj is a child buffer object, the memory access qualifier inherited by the parent object is also returned.
Cl_mem_size	size_t	Returns the actual size, in bytes, of the memory used for data storage in Memobj.
Cl_mem_host_ptr	void *	If Memobj is made by Clcreate{buffer | Image} is created, and Cl_mem_use_host_ptr is set in Mem_flags, the value of the parameter host_ptr is returned, otherwise null is returned. If Memobj is created by Clcreatesubbuffer, the Host_ptr+origin is returned. Otherwise, NULL is returned.
Cl_mem_map_cout	Cl_uint	The number of times the current buffer is mapped.
Cl_mem_reference_count	Cl_uint	Returns the reference technology for Memobj.
Cl_mem_context	Cl_context	Returns the context specified when the memory object was created.
Cl_mem_associated_memobject	Cl_mem	Returns the parent object of the Memobj. That is, the Clcreatesubbuffer parameter buffer. Otherwise, NULL is returned.
Cl_mem_offset	size_t	If Memobj is a self-buffering object created by Clcreatesubbuffer, its offset is returned, otherwise 0 is returned.

4. Read, write and copy buffer objects

Cl_int Clenqueuereadbuffer (cl_command_queue command_queue, Cl_mem buffer, Cl_bool blocking_read, size_t offset, size_t c b, void *ptr, Cl_uint mem_events_in_wait_list, const cl_event *event_wait_list