C Specification

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.

Parameters

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

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

  • 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_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.

Description

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.

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.

clSetProgramSpecializationConstant returns CL_SUCCESS if the function is executed successfully.

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_OPERATION if no devices associated with program support intermediate language programs.

  • 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.

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

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

  • 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.

See Also

CL_VERSION_2_2, cl_program, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0