C Specification

To create a deep copy of the input command-buffer with the copied commands remapped to target devices of the passed command-queues, call the function

// Provided by cl_khr_command_buffer_multi_device
cl_command_buffer_khr clRemapCommandBufferKHR(
    cl_command_buffer_khr command_buffer,
    cl_bool automatic,
    cl_uint num_queues,
    const cl_command_queue* queues,
    cl_uint num_handles,
    const cl_mutable_command_khr* handles,
    cl_mutable_command_khr* handles_ret,
    cl_int* errcode_ret);
clRemapCommandBufferKHR is provided by the cl_khr_command_buffer_multi_device extension.

Parameters

  • command_buffer specifies the command-buffer to create a remapped deep copy of.

  • automatic indicates if the remapping is done explicitly by the user, or automatically by the OpenCL runtime. If automatic is CL_FALSE, then each element of queues will replace the queue used on command_buffer creation at the same index. If CL_TRUE and CL_COMMAND_BUFFER_PLATFORM_AUTOMATIC_REMAP_KHR is supported, then the OpenCL runtime will decide in a way it determines optimal which of the elements in queues each command in the returned command-buffer will be associated with.

  • num_queues is the number of command-queues listed in queues, must not be 0.

  • queues is a pointer to an ordered list of command-queues for the returned command-buffer to target, must be a non-NULL value.

  • num_handles is the number of command handles passed in both handles and handles_ret lists, may be 0.

  • handles is an ordered list of handles belonging to command_buffer to create remapped copies of, may be NULL.

  • handles_ret returns an ordered list of handles where each handle is equivalent to the handle at the same index in handles, but belonging to the returned command-buffer.

  • errcode_ret returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

The returned command-buffer has the same state as the input command-buffer, unless the input command-buffer is in the Pending state, in which case the returned command-buffer has state Executable.

clRemapCommandBufferKHR returns a valid command-buffer with errcode_ret set to CL_SUCCESS if the command-buffer is created successfully. Otherwise, it returns a NULL value without setting handles_ret, and with one of the following error values returned in errcode_ret:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_VALUE if num_queues is 0, or if queues is NULL.

  • CL_INVALID_VALUE if automatic is CL_FALSE and num_queues is not equal to the number of queues used on creation of command_buffer.

  • CL_INVALID_VALUE if handles or handles_ret is NULL and num_handles is > 0, or either handles or handles_ret is not NULL and num_handles is 0.

  • CL_INVALID_VALUE if any handle in handles is not a valid command handle belonging to command_buffer.

  • CL_INVALID_COMMAND_QUEUE if any command-queue in queues is not a valid command-queue.

  • CL_INVALID_CONTEXT if command_buffer and all the command-queues in queues do not have the same OpenCL context.

  • CL_INVALID_OPERATION if the platform does not support the CL_COMMAND_BUFFER_PLATFORM_REMAP_QUEUES_KHR flag.

  • CL_INVALID_OPERATION if the platform does not support the CL_COMMAND_BUFFER_PLATFORM_AUTOMATIC_REMAP_KHR flag and automatic is CL_TRUE.

  • Any error relating to device support that can be returned by a command recording entry-point may also be returned. As a command in command_buffer can have a configuration that is not supported by a device that is associated with the queue in queues the command is being remapped to.

  • 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_bool, cl_command_buffer_khr, cl_command_queue, cl_int, cl_khr_command_buffer_multi_device, cl_mutable_command_khr, 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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0