C Specification

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

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

Parameters

  • program must be a valid OpenCL program created from an intermediate format module (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 a module in an intermediate format (e.g. SPIR-V).

  • CL_​INVALID_​SPEC_​ID if spec_id is not a valid specialization constant 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.

  • 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

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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.