<commit_before># OpenCL C 1.2 Language on Vulkan

## Overview

The OpenCL C 1.2 language provides an expressive variant of the C language with
which to program heterogeneous architectures.
There is already a significant body of code in the wild written in the OpenCL C
language - both in open source and proprietary software.
This document explains how the OpenCL C language is mapped onto an
implementation of the Vulkan standard for high-performance graphics and compute.

The following subjects are covered:

- Which SPIR-V features are used.
- How the Vulkan API makes use of the Vulkan variant of SPIR-V produced.
- How OpenCL C language constructs are mapped down onto Vulkan's variant of
  SPIR-V.
- Restrictions on the OpenCL C language as is to be consumed by a Vulkan
  implementation.

## SPIR-V Features

The SPIR-V as produced from the OpenCL C language can make use of the following
additional extensions:

- _SPV\_KHR\_variable\_pointers_ - to enable the support of more expressive
  pointers that the OpenCL C language can make use of.
- _SPV\_KHR\_storage\_buffer\_storage\_class_ - required by
  _SPV\_KHR\_variable\_pointers_, to enable use of the StorageBuffer storage
  class.

The SPIR-V as produced from the OpenCL C language can make use of the following
capabilities:

- `Shader` as we are targeting the OpenCL C language at a Vulkan implementation.
- If pointers are used such that the operations in the OpenCL C require the use
  of the _SPV\_KHR\_variable\_pointers_  extension:
  - From the _SPV\_KHR\_variable\_pointers_ extension, `VariablePointers`.

## Vulkan Interaction

A Vulkan implementation that is to consume the SPIR-V produced from the OpenCL C
language must conform to the following the rules:

- If the short/ushort types are used in the OpenCL C:
  - The `shaderInt16` field of `VkPhysicalDeviceFeatures` **must** be set to
    true.
- If images are used in the OpenCL C:
  - The `shaderStorageImageReadWithoutFormat` field of
    `VkPhysicalDeviceFeatures` **must** be set to true.
  - The `shaderStorageImageWriteWithoutFormat` field of
    `VkPhysicalDeviceFeatures` **must** be set to true.
- If pointers are used such that the operations in the OpenCL C require the use
  of the _VK\_KHR\_storage\_buffer\_storage\_class_ and
  _VK\_KHR\_variable\_pointers_  extensions:
  - A call to `vkCreateDevice()` where the `ppEnabledExtensionNames` field of
    `VkDeviceCreateInfo` contains extension strings
    _"VK\_KHR\_storage\_buffer\_storage\_class"_ and
    _"VK\_KHR\_variable\_pointers"_ **must** succeed.

### Descriptor Type Mappings

OpenCL C kernel argument types are mapped to Vulkan descriptor types in the
following way:

- If the argument to the kernel is a read only image, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE`.
- If the argument to the kernel is a write only image, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_IMAGE`.
- If the argument to the kernel is a sampler, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_SAMPLER`.
- If the argument to the kernel is a constant or global pointer type, the
  matching Vulkan descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER`.
- If the argument to the kernel is a plain-old-data type, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER`.

Note: If `-cluster-pod-kernel-args` is used, then all plain-old-data kernel
arguments are collected into a single structure to be passed in to the compute
shader as a single storage buffer resource.

## OpenCL C Modifications

Some OpenCL C language features that are not natively expressible in Vulkan's<commit_msg>Document unconditional extension dependencies<commit_after># OpenCL C 1.2 Language on Vulkan

## Overview

The OpenCL C 1.2 language provides an expressive variant of the C language with
which to program heterogeneous architectures.
There is already a significant body of code in the wild written in the OpenCL C
language - both in open source and proprietary software.
This document explains how the OpenCL C language is mapped onto an
implementation of the Vulkan standard for high-performance graphics and compute.

The following subjects are covered:

- Which SPIR-V features are used.
- How the Vulkan API makes use of the Vulkan variant of SPIR-V produced.
- How OpenCL C language constructs are mapped down onto Vulkan's variant of
  SPIR-V.
- Restrictions on the OpenCL C language as is to be consumed by a Vulkan
  implementation.

## SPIR-V Features

The SPIR-V as produced from the OpenCL C language can make use of the following
additional extensions:

- _SPV\_KHR\_variable\_pointers_ - to enable the support of more expressive
  pointers that the OpenCL C language can make use of.
- _SPV\_KHR\_storage\_buffer\_storage\_class_ - required by
  _SPV\_KHR\_variable\_pointers_, to enable use of the StorageBuffer storage
  class.

The SPIR-V as produced from the OpenCL C language can make use of the following
capabilities:

- `Shader` as we are targeting the OpenCL C language at a Vulkan implementation.
- `VariablePointers`, from the _SPV\_KHR\_variable\_pointers_ extension.
  - *Note*: The compiler always emits code that depends on `VariablePointers`
    even though there might some cases where it is not strictly needed.

## Vulkan Interaction

A Vulkan implementation that is to consume the SPIR-V produced from the OpenCL C
language must conform to the following the rules:

- If the short/ushort types are used in the OpenCL C:
  - The `shaderInt16` field of `VkPhysicalDeviceFeatures` **must** be set to
    true.
- If images are used in the OpenCL C:
  - The `shaderStorageImageReadWithoutFormat` field of
    `VkPhysicalDeviceFeatures` **must** be set to true.
  - The `shaderStorageImageWriteWithoutFormat` field of
    `VkPhysicalDeviceFeatures` **must** be set to true.
- The implementation **must** support extensions _VK\_KHR\_storage\_buffer\_storage\_class_ and
  _VK\_KHR\_variable\_pointers_:
  - A call to `vkCreateDevice()` where the `ppEnabledExtensionNames` field of
    `VkDeviceCreateInfo` contains extension strings
    _"VK\_KHR\_storage\_buffer\_storage\_class"_ and
    _"VK\_KHR\_variable\_pointers"_ **must** succeed.

### Descriptor Type Mappings

OpenCL C kernel argument types are mapped to Vulkan descriptor types in the
following way:

- If the argument to the kernel is a read only image, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE`.
- If the argument to the kernel is a write only image, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_IMAGE`.
- If the argument to the kernel is a sampler, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_SAMPLER`.
- If the argument to the kernel is a constant or global pointer type, the
  matching Vulkan descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER`.
- If the argument to the kernel is a plain-old-data type, the matching Vulkan
  descriptor set type is `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER`.

Note: If `-cluster-pod-kernel-args` is used, then all plain-old-data kernel
arguments are collected into a single structure to be passed in to the compute
shader as a single storage buffer resource.

## OpenCL C Modifications

Some OpenCL C language features that are not natively expressible in Vulkan's
{'fraction_non_alphanumeric': 0.05190217391304348, 'fraction_numerical': 0.0016304347826086956, 'mean_word_length': 4.303314121037464, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '735336', 'n_tokens_mistral': 2095, 'n_tokens_neox': 2014, 'n_words': 980}