OpenCL™规范 5.8.3. 设置SPIR-V专业化常量

5.8.3. Setting SPIR-V Specialization Constants

5.8.3. 设置SPIR-V专业化常量

Specialization constants are missing before version 2.2. ​ 2.2版本之前缺少专业化常量。

To set the value of a specialization constant, call the function

要设置专门化常量的值，请调用函数

// Provided by CL_VERSION_2_2
cl_int clSetProgramSpecializationConstant(
    cl_program program,
    cl_uint spec_id,
    size_t spec_size,
    const void* spec_value);

clSetProgramSpecializationConstant is missing before version 2.2. clSetProgramSpecificationConstant在2.2版本之前缺失。

• program must be a valid OpenCL program created from an intermediate language (e.g. SPIR-V).

• program必须是由中间语言（如SPIR-V）创建的有效OpenCL程序。

• spec_id identifies the specialization constant whose value will be set.

• spec_id标识将设置其值的专门化常量。

• spec_size specifies the size in bytes of the data pointed to by spec_value. This should be 1 for boolean constants. For all other constant types this should match the size of the specialization constant in the module.

• spec_size指定spec_value指向的数据的字节大小。对于布尔常量，这应该是1。对于所有其他常量类型，这应该与模块中专门化常量的大小相匹配。

• spec_value is a pointer to the memory location that contains the value of the specialization constant. The data pointed to by spec_value are copied and can be safely reused by the application after clSetProgramSpecializationConstant returns. This specialization value will be used by subsequent calls to clBuildProgram until another call to clSetProgramSpecializationConstant changes it. If a specialization constant is a boolean constant, spec_value should be a pointer to a cl_uchar value. A value of zero will set the specialization constant to false; any other value will set it to true.

• ​spec_value是指向包含专门化常量值的内存位置的指针。spec_value指向的数据被复制，在clSetProgramSpecialization Constant返回后，应用程序可以安全地重用这些数据。此专门化值将由后续对clBuildProgram的调用使用，直到对clSetProgramSpecializationConstant的另一次调用更改它为止。如果专门化常量是布尔常量，则spec_value应该是指向cl_uchar值的指针。值为零会将专门化常量设置为false；任何其他值都会将其设置为true。

Calling this function multiple times for the same specialization constant shall cause the last provided value to override any previously specified value. The values are used by a subsequent clBuildProgram call for the program.

​对同一专门化常数多次调用此函数将导致最后提供的值覆盖任何先前指定的值。这些值由程序的后续clBuildProgram调用使用。

Application is not required to provide values for every specialization constant contained in the module. If the value is not set by this API call, default values will be used during the build.

应用程序不需要为模块中包含的每个专门化常量提供值。如果此API调用未设置该值，则在生成期间将使用默认值。

clSetProgramSpecializationConstant returns CL_SUCCESS if the function is executed successfully.

如果函数执行成功，clSetProgramSpecialization Constant将返回CL_SUCCESS。

Otherwise, it returns one of the following errors:

否则，它将返回以下错误之一：

• CL_INVALID_PROGRAM if program is not a valid program object created from an intermediate language (e.g. SPIR-V), or if the intermediate language does not support specialization constants.

• CL_INVALID_PROGRAM，如果program不是从中间语言（如SPIR-V）创建的有效程序对象，或者如果中间语言不支持专门化常量。

• CL_INVALID_OPERATION if no devices associated with program support intermediate language programs.

• 如果没有与程序关联的设备支持中间语言程序，则为CL_INVALID_OPERATION。

• CL_COMPILER_NOT_AVAILABLE if program is created with clCreateProgramWithIL and a compiler is not available, i.e. CL_DEVICE_COMPILER_AVAILABLE specified in the Device Queries table is set to CL_FALSE.

• 如果程序是使用clCreateProgramWithIL创建的，并且编译器不可用，即设备查询表中指定的CLD_COMPILER_AVAILABLE设置为CL_FALSE，则CL_COMPILER_NOT_AVAILABLE。

• CL_INVALID_SPEC_ID if spec_id is not a valid specialization constant identifier.

• CL_INVALID_SPEC_ID（如果spec_id不是有效的专门化常量标识符）。

• CL_INVALID_VALUE if spec_size does not match the size of the specialization constant in the module, or if spec_value is NULL.

• 如果spec_size与模块中的专门化常量的大小不匹配，或者spec_value为NULL，则返回CL_INVALID_VALUE。

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

• CL_OUT_OF_RESOURCES，如果无法在设备上分配OpenCL实现所需的资源。

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

• CL_OUT_OF_HOST_MEMORY，如果无法在主机上分配OpenCL实现所需的资源。