KhronosGroup / KhronosGroup/OpenCL-Headers

Deprecated API Prefix and Suffix Defines

Open
#95 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
C
Stars
766
Forks
273
Avg merge
2d 2h
Merged PRs (30d)
3

Description

I'm a little confused by the prefix and suffix pre-processor defines for deprecated OpenCL APIs. I believe this is a summary of what is in the headers currently:

| API | Introduced In | Deprecated In | Prefix Define | Suffix Define |
|-------------------------------|-------------------|---------------|---------------------------------------|---------------------------------------|
| clSetCommandQueueProperty | OpenCL 1.0 | OpenCL 1.1 | (None!) | CL_EXT_SUFFIX__ VERSION_1_0_DEPRECATED |
| clCreateImage2D | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clCreateImage3D | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clEnqueueMarker | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clEnqueueWaitForEvents | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clEnqueueBarrier | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clUnloadCompiler | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clGetExtensionFunctionAddress | OpenCL 1.0 | OpenCL 1.2 | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clCreateCommandQueue | OpenCL 1.0 | OpenCL 2.0 | CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED |
| clCreateSampler | OpenCL 1.0 | OpenCL 2.0 | CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED |
| clEnqueueTask | OpenCL 1.0 | OpenCL 2.0 | CL_EXT_PREFIX__ VERSION_1_2_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_2_DEPRECATED |
| clCreateFromGLTexture2D | cl_khr_gl_sharing | OpenCL 1.2? | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clCreateFromGLTexture3D | cl_khr_gl_sharing | OpenCL 1.2? | CL_EXT_PREFIX__ VERSION_1_1_DEPRECATED | CL_EXT_SUFFIX__ VERSION_1_1_DEPRECATED |
| clGetKernelSubGroupInfoKHR | cl_khr_subgroups | OpenCL 2.1? | (None!) | CL_EXT_SUFFIX__ VERSION_2_0_DEPRECATED |

Should the define indicate:

* When the API was **added**?
* When the API was **last supported**?
* When the API was **deprecated**?
* Or something else entirely?

Right now it looks like we have a bit of a mix, though it looks like we have more usage of "last supported" than anything else.

I'm looking at this to ensure that if we deprecate `clSetProgramReleaseCallback` we do it consistently. Thanks!

Contributor guide

No contributing guide indexed for this repository

Research direction

Review the deprecated OpenCL API prefix and suffix defines in the headers, using the listed APIs and clSetProgramReleaseCallback as the comparison points. Determine which version meaning the defines should consistently express, then verify that the affected declarations follow that convention and document the resulting rule.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.