C Specification

To query information about a mutable command object, call the function

// Provided by cl_khr_command_buffer_mutable_dispatch
cl_int clGetMutableCommandInfoKHR(
    cl_mutable_command_khr command,
    cl_mutable_command_info_khr param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);
clGetMutableCommandInfoKHR is provided by the cl_khr_command_buffer_mutable_dispatch extension.

Parameters

  • command specifies the mutable-command object being queried.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetMutableCommandInfoKHR is described in the Mutable Command Object Queries table.

  • param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of the return type specified in the Mutable Command Object Queries table. If param_value is NULL, it is ignored.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. Mutable Command Object Queries
Mutable Command Info Return Type Description

CL_MUTABLE_COMMAND_COMMAND_QUEUE_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_command_queue

Return the command-queue associated with command. If NULL was passed as the queue when command was recorded, then the queue associated with the command-buffer that command belongs to is returned.

CL_MUTABLE_COMMAND_COMMAND_BUFFER_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_command_buffer_khr

Return the command-buffer associated with command.

CL_MUTABLE_COMMAND_COMMAND_TYPE_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_command_type

Return the command-type associated with command.

The list of supported event command types defined by clGetEventInfo is used with the matching command.

CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_command_properties_khr[]

Return the properties argument specified on command recording.

If the properties argument specified on creation of command was not NULL, the implementation must return the values specified in the properties argument in the same order and without including additional properties.

If the properties argument specified on creation of command was NULL, the implementation must return param_value_size_ret equal to 0, indicating that there are no properties to be returned.

CL_MUTABLE_DISPATCH_KERNEL_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_kernel

Return the kernel associated with command when recorded with clCommandNDRangeKernelKHR.

If command was not recorded from a clCommandNDRangeKernelKHR command, the implementation must return param_value_size_ret equal to 0, indicating that the value returned in param_value is not valid.

CL_MUTABLE_DISPATCH_DIMENSIONS_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

cl_uint

Return the number of work-item dimensions specified when command was created.

If command was not recorded from a clCommandNDRangeKernelKHR command, the implementation must return param_value_size_ret equal to 0, indicating that the value returned in param_value is not valid.

CL_MUTABLE_DISPATCH_GLOBAL_WORK_OFFSET_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

size_t[]

Return the global work-item offset set on command creation, or from the most recent update via clUpdateMutableCommandsKHR where this value was modified. The output array contains work_dim values, where work_dim is returned by the query CL_MUTABLE_DISPATCH_DIMENSIONS_KHR. If a global work-item offset was not set, zero is returned for each element in the array.

If command was not recorded from a clCommandNDRangeKernelKHR command, the implementation must return param_value_size_ret equal to 0, indicating that the value returned in param_value is not valid.

CL_MUTABLE_DISPATCH_GLOBAL_WORK_SIZE_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

size_t[]

Return the global work-item size set on command creation, or from the most recent update via clUpdateMutableCommandsKHR where this value was modified. The output array contains work_dim values, where work_dim is returned by the query CL_MUTABLE_DISPATCH_DIMENSIONS_KHR. If a global work-item size was not set, zero is returned for each element in the array.

If command was not recorded from a clCommandNDRangeKernelKHR command, the implementation must return param_value_size_ret equal to 0, indicating that the value returned in param_value is not valid.

CL_MUTABLE_DISPATCH_LOCAL_WORK_SIZE_KHR

provided by the cl_khr_command_buffer_mutable_dispatch extension.

size_t[]

Return the local work-item size set on command creation, or from the most recent update via clUpdateMutableCommandsKHR where this value was modified. The output array contains work_dim values, where work_dim is returned by the query CL_MUTABLE_DISPATCH_DIMENSIONS_KHR. If a local work-item size was not set, zero is returned for each element in the array.

If command was not recorded from a clCommandNDRangeKernelKHR command, the implementation must return param_value_size_ret equal to 0, indicating that the value returned in param_value is not valid.

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

  • CL_INVALID_MUTABLE_COMMAND_KHR if command is not a valid mutable command object.

  • CL_INVALID_VALUE if param_name is not one of the supported values, or if the size in bytes specified by param_value_size is less than size of the return type specified in the Mutable Command Object Queries table and param_value is not 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_khr_command_buffer_mutable_dispatch, cl_mutable_command_info_khr, cl_mutable_command_khr

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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0