C Specification

To set the argument value for a specific argument of a kernel, call the function

// Provided by CL_VERSION_1_0
cl_int clSetKernelArg(
    cl_kernel kernel,
    cl_uint arg_index,
    size_t arg_size,
    const void* arg_value);

Parameters

  • kernel is a valid kernel object.

  • arg_index is the kernel argument index. Kernel arguments are referred to by indices that go from zero to n - 1, where n is the total number of arguments declared by the kernel.

  • arg_size specifies the size of the kernel argument value.

  • arg_value is a pointer to the data for the kernel argument. The argument data pointed to by arg_value is copied and the arg_value pointer can therefore be reused by the application after clSetKernelArg returns. The argument data is used by all API calls that enqueue the kernel until the argument is changed by another call to clSetKernelArg for the kernel.

Description

If the kernel argument being set is a pointer to the global or constant address space, then arg_value must point to a buffer memory object or NULL, or arg_value must be NULL. If arg_value is NULL or points to NULL, then the kernel argument will be set to NULL.

If the kernel argument being set is a pointer to the local address space, then arg_value must be NULL, and arg_size specifies the amount of local memory in bytes that are allocated for the kernel argument. Prior to OpenCL 3.1, arg_size must be greater than zero. For OpenCL 3.1 and newer, arg_size may be zero, indicating that no local memory is required for the kernel argument. [1]

If the kernel argument being set is an image object, then arg_value must point to an image memory object. Additionally:

  • If the kernel argument is a 1D image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE1D.

  • If the kernel argument is a 2D image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D.

  • If the kernel argument is a 3D image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE3D.

  • If the kernel argument is a 1D image buffer, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE1D_BUFFER.

  • If the kernel argument is a 1D image array, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE1D_ARRAY.

  • If the kernel argument is a 2D image array, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D_ARRAY.

  • If the kernel argument is a 2D depth image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D and image channel order CL_DEPTH.

  • If the kernel argument is a 2D depth image array, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D_ARRAY and image channel order CL_DEPTH.

  • If the kernel argument is a 2D MSAA image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D.

  • If the kernel argument is a 2D MSAA image array, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D_ARRAY.

  • If the kernel argument is a 2D MSAA depth image, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D and image channel order CL_DEPTH.

  • If the kernel argument is a 2D MSAA depth image array, then the image memory object must be of image type CL_MEM_OBJECT_IMAGE2D_ARRAY and image channel order CL_DEPTH.

Behavior is undefined if the same image memory object is passed as both a read_only image and a write_only image, or as a read_write image and either a read_only image or a write_only image.

If the kernel argument being set is a sampler, then arg_value must point to a sampler object.

If the kernel argument being set is a device queue, then arg_value must point to a device queue object.

If the kernel argument being set is a pipe, then arg_value must point to a pipe memory object.

For all other kernel arguments, arg_value points to the data that is used as the kernel argument value.

All OpenCL objects set as kernel arguments must be created from the same context as the kernel object.

A kernel object does not update the reference count for objects such as memory or sampler objects specified as argument values by clSetKernelArg. Users may not rely on a kernel object to retain objects specified as argument values to the kernel.

Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership rights on kernel args, that would make it impossible for users to tell with certainty when they may safely release user allocated resources associated with OpenCL objects such as the cl_mem backing store used with CL_MEM_USE_HOST_PTR.

clSetKernelArg returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_KERNEL

    • if kernel is not a valid kernel

  • CL_INVALID_ARG_INDEX

    • if arg_index is not a valid argument index

  • CL_INVALID_CONTEXT

    • if the context associated with kernel and an OpenCL object pointed to by arg_value are not the same

  • CL_INVALID_MEM_OBJECT

    • if arg_value is NULL and it must point to a valid memory object

    • if arg_value points to NULL and it must point to a valid memory object

    • if arg_value is not NULL, and does not point to NULL, and does not point to a valid memory object

    • if arg_value points to a valid memory object, but the memory object is not valid for the kernel argument specified by arg_index

  • CL_INVALID_SAMPLER

    • if the kernel argument is a sampler, but arg_value does not point to a valid sampler object

  • CL_INVALID_DEVICE_QUEUE

    • if the kernel argument is a device queue, but arg_value does not point to a valid device queue object. This error code is missing before version 2.0.

  • CL_INVALID_ARG_SIZE

    • if arg_value points to a memory object and arg_size is not equal to sizeof(cl_mem)

    • if arg_value points to a sampler object and arg_size is not equal to sizeof(cl_sampler)

    • if arg_value points to a device queue object and arg_size is not equal to sizeof(cl_command_queue)

    • if the kernel argument is a pointer to the local address space and arg_size is zero. This error condition does not apply if the platform associated with kernel is OpenCL 3.1 or newer.

    • if arg_value points to the data to be used as the kernel argument value and arg_size does not match the size of the data type for the argument

  • CL_INVALID_ARG_VALUE

    • if the argument is an image declared with the read_only qualifier and arg_value points to an image object created with the memory flag CL_MEM_WRITE_ONLY

    • if the argument is an image declared with the write_only qualifier and arg_value points to an image object created with the memory flag CL_MEM_READ_ONLY or CL_MEM_IMMUTABLE_EXT

  • CL_MAX_SIZE_RESTRICTION_EXCEEDED

    • if the size in bytes of the memory object (if the argument is a memory object) or arg_size (if the argument is declared with local qualifier) exceeds a language-specified maximum size restriction for this argument, such as the MaxByteOffset SPIR-V decoration. This error code is missing before version 2.2.

  • 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

When clSetKernelArg returns an error code different from CL_SUCCESS, the internal state of kernel may only be modified when that error code is CL_OUT_OF_RESOURCES or CL_OUT_OF_HOST_MEMORY. When the internal state of kernel is modified, it is implementation-defined whether:

  • The argument value that was previously set is kept so that it can be used in further kernel enqueues.

  • The argument value is unset such that a subsequent kernel enqueue fails with CL_INVALID_KERNEL_ARGS. [2]

See Also

CL_VERSION_1_0, cl_kernel, 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-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. When the size of a local argument is set to zero, the value of the pointer within the kernel is implementation-defined.
2. Implementations are encouraged to favor this option as it makes it more likely that errors will be managed by applications.