Name Strings

cl_intel_create_buffer_with_properties

Contact

Kris Kang, Intel (kris dot kang at intel dot com)

Contributors

Kris Kang, Intel
Michael Kinsner, Intel
Peter Yiannacouras, Intel
Ben Ashbaugh, Intel

Notice

Copyright (c) 2020-2023 Intel Corporation. All rights reserved.

Status

Final Draft

Version

Last Modified

2020-05-29

Revision

1

Dependencies

This extension is written against the OpenCL Specification Version 1.0, Revision 48.

This extension requires OpenCL 1.0 or later.

Overview

This extension allows OpenCL 1.x and 2.x devices to support the clCreateBufferWithProperties API that was added in OpenCL 3.0. This allows older OpenCL implementations to support other optional extensions or features that use the clCreateBufferWithProperties API to specify additional buffer properties, without recreating the API that is already part of OpenCL 3.0.

New API Functions

cl_mem CL_API_CALL clCreateBufferWithPropertiesINTEL(
    cl_context context,
    const cl_mem_properties_intel* properties,
    cl_mem_flags flags,
    size_t size,
    void* host_ptr,
    cl_int* errcode_ret);

New API Types

typedef cl_properties  cl_mem_properties_intel;

Modifications to the OpenCL API Specification

(Add to Section 5.2.1, Creating Buffer Objects)

A buffer object may also be created with additional properties using the function

cl_mem clCreateBufferWithPropertiesINTEL(
    cl_context context,
    const cl_mem_properties_intel* properties,
    cl_mem_flags flags,
    size_t size,
    void* host_ptr,
    cl_int* errcode_ret);

  • context is a valid OpenCL context used to create the buffer object.

  • properties is an optional list of properties for the buffer object and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with the special property 0. If no properties are required, properties may be NULL. This extension does not define any optional properties for buffers.

  • flags is a bit-field that is used to specify allocation and usage information such as the memory arena that should be used to allocate the buffer object and how it will be used. Table 5.3 describes the possible values for flags.

  • size is the size in bytes of the buffer memory object to be allocated.

  • host_ptr is a pointer to the buffer data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to size bytes.

  • errcode_ret may return an appropriate error code. If errcode_ret is NULL, no error code is returned.

clCreateBufferWithPropertiesINTEL returns a valid non-zero buffer object and errcode_ret is set to CL_SUCCESS if the buffer object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • CL_INVALID_CONTEXT if context is not a valid context.

  • CL_INVALID_VALUE if a property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once.

  • CL_INVALID_VALUE if values specified in flags are not valid as defined in table 5.3.

  • CL_INVALID_BUFFER_SIZE if size is 0.

  • CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in flags.

  • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for 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.

Issues

None.

Revision History

Rev Date Author Changes

1

2020-05-29

Kris Kang

Initial public release