Skip to content

clCreateSubBuffer.adoc

Latest commit

 

History

History
128 lines (77 loc) · 5.07 KB

clCreateSubBuffer.adoc

File metadata and controls

128 lines (77 loc) · 5.07 KB

clCreateSubBuffer

Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object.

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)

Parameters

buffer

A valid buffer object and cannot be a sub-buffer object.

flags

A bit-field that is used to specify allocation and usage information about the sub-buffer memory object being created and is described in the table below. If the CL_MEM_READ_WRITE, CL_MEM_READ_ONLY or CL_MEM_WRITE_ONLY values are not specified in flags, they are inherited from the corresponding memory access qualifers associated with buffer. The CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR and CL_MEM_COPY_HOST_PTR values cannot be specified in flags but are inherited from the corresponding memory access qualifiers associated with buffer. If CL_MEM_COPY_HOST_PTR is specified in the memory access qualifier values associated with buffer it does not imply any additional copies when the sub-buffer is created from buffer. If the CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS values are not specified in flags, they are inherited from the corresponding memory access qualifiers associated with buffer.

buffer_create_type and buffer_create_info

Describes the type of buffer object to be created. The list of supported values for buffer_create_type and corresponding descriptor that buffer_create_info points to is described below.

cl_buffer_create_type Description

CL_BUFFER_CREATE_TYPE_REGION

Create a buffer object that represents a specific region in buffer.

buffer_create_info is a pointer to the following structure:

typedef struct _cl_buffer_region {
    size_t origin;
    size_t size;
} cl_buffer_region;

(origin, size) defines the offset and size in bytes in buffer.

If buffer is created with CL_MEM_USE_HOST_PTR, the host_ptr associated with the buffer object returned is host_ptr + origin.

The buffer object returned references the data store allocated for buffer and points to a specific region given by (origin, size) in this data store.

CL_INVALID_VALUE is returned in errcode_ret if the region specified by (origin, size) is out of bounds in buffer.

CL_INVALID_BUFFER_SIZE if size is 0.

CL_MISALIGNED_SUB_BUFFER_OFFSET is returned in errcode_ret if there are no devices in context associated with buffer for which the origin value is aligned to the CL_DEVICE_MEM_BASE_ADDR_ALIGN value.

Notes

Concurrent reading from, writing to and copying between both a buffer object and its sub-buffer object(s) is undefined. Concurrent reading from, writing to and copying between overlapping sub-buffer objects created with the same buffer object is undefined. Only reading from both a buffer object and its sub-buffer objects or reading from multiple overlapping sub-buffer objects is defined.

Errors

Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors in errcode_ret

  • CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object or is a sub-buffer object.

  • CL_INVALID_VALUE if buffer was created with CL_MEM_WRITE_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_READ_ONLY, or if buffer was created with CL_MEM_READ_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY, or if flags specifies CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR.

  • CL_INVALID_VALUE if buffer was created with CL_MEM_HOST_WRITE_ONLY and flags specifies CL_MEM_HOST_READ_ONLY or if buffer was created with CL_MEM_HOST_READ_ONLY and flags specifies CL_MEM_HOST_WRITE_ONLY, or if buffer was created with CL_MEM_HOST_NO_ACCESS and flags specifies CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_WRITE_ONLY.

  • CL_INVALID_VALUE if value specified in buffer_create_type is not valid.

  • CL_INVALID_VALUE if value(s) specified in buffer_create_info (for a given buffer_create_type) is not valid or if buffer_create_info is NULL.

  • CL_INVALID_BUFFER_SIZE if size is 0.

  • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for sub-buffer object.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.