OpenCL™ C 6.15.1. 工作项函数

6.15.1. Work-Item Functions

6.15.1. 工作项函数

The following table describes the list of built-in work-item functions that can be used to query the number of dimensions, the global and local work size specified to clEnqueueNDRangeKernel, and the global and local identifier of each work-item when this kernel is being executed on a device.

下表描述了内置工作项函数的列表，这些函数可用于查询维度数量、指定给clEnqueueNDRangeKernel的全局和本地工作大小，以及在设备上执行此内核时每个工作项的全局和局部标识符。

Table 9. Built-in Work-Item Functions

表9 内置工作项函数

Function 函数	Description 描述
uint get_work_dim()	Returns the number of dimensions in use. This is the value given to the work_dim argument specified in clEnqueueNDRangeKernel. 返回正在使用的维度数。这是clEnqueueNDRangeKernel中指定的work_dim参数的值。
size_t get_global_size(uint dimindx)	Returns the number of global work-items specified for dimension identified by dimindx. This value is given by the global_work_size argument to clEnqueueNDRangeKernel. 返回为dimidx标识的维度指定的全局工作项的数量。此值由clEnqueueNDRangeKernel的global_work_size参数给出。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_global_size() returns 1. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_global_size（）返回1。
size_t get_global_id(uint dimindx)	Returns the unique global work-item ID value for dimension identified by dimindx. The global work-item ID specifies the work-item ID based on the number of global work-items specified to execute the kernel. 返回由dimidx标识的维度的唯一全局工作项ID值。全局工作项ID根据指定用于执行内核的全局工作项的数量指定工作项ID。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_global_id() returns 0. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_global_id（）返回0。
size_t get_local_size(uint dimindx)	Returns the number of local work-items specified in dimension identified by dimindx. This value is at most the value given by the local_work_size argument to clEnqueueNDRangeKernel if local_work_size is not NULL; otherwise the OpenCL implementation chooses an appropriate local_work_size value which is returned by this function. If the kernel is executed with a non-uniform work-group size [38], calls to this built-in from some work-groups may return different values than calls to this built-in from other work-groups. ​返回由dimidx标识的维度中指定的本地工作项的数量。如果local_work_size不为NULL，则此值最多为clEnqueueNDRangeKernel的local_work_size 参数给出的值；否则，OpenCL实现会选择此函数返回的适当的local_work_size值。如果内核以非均匀的工作组大小执行[38]，则从某些工作组调用此内置可能会返回与从其他工作组调用该内置不同的值。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_local_size() returns 1. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_loccal_size（）返回1。
size_t get_enqueued_local_size( uint dimindx)	Returns the same value as that returned by get_local_size(dimindx) if the kernel is executed with a uniform work-group size. 如果内核以统一的工作组大小执行，则返回与get_local_size（dimidx）返回的值相同的值。 If the kernel is executed with a non-uniform work-group size, returns the number of local work-items in each of the work-groups that make up the uniform region of the global range in the dimension identified by dimindx. If the local_work_size argument to clEnqueueNDRangeKernel is not NULL, this value will match the value specified in local_work_size[dimindx]. If local_work_size is NULL, this value will match the local size that the implementation determined would be most efficient at implementing the uniform region of the global range. 如果内核以非均匀的工作组大小执行，则返回每个工作组中构成dimidx标识的维度中全局范围均匀区域的局部工作项的数量。如果clEnqueueNDRangeKernel的local_work_size参数不为NULL，则此值将与local_work_size[dimidx]中指定的值匹配。如果local_work_size为NULL，则此值将与实现确定的在实现全局范围的统一区域时最有效的本地大小相匹配。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_enqueued_local_size() returns 1. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_enqueued_local_size（）返回1。 Requires support for OpenCL 2.0 or newer. 需要支持OpenCL 2.0或更高版本。
size_t get_local_id(uint dimindx)	Returns the unique local work-item ID, i.e. a work-item within a specific work-group for dimension identified by dimindx. 返回唯一的本地工作项ID，即dimidx标识的维度的特定工作组内的工作项。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_local_id() returns 0. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_loccal_id（）返回0。
size_t get_num_groups(uint dimindx)	Returns the number of work-groups that will execute a kernel for dimension identified by dimindx. 返回将为dimidx标识的维度执行内核的工作组数量。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_num_groups() returns 1. dimidx的有效值为0到get_work_dim（）-1。对于dimidx的其他值，get_num_groups（）返回1。
size_t get_group_id(uint dimindx)	get_group_id returns the work-group ID which is a number from 0 .. get_num_groups(dimindx) - 1. get_group_id返回工作组id，该id是0中的一个数字。。get_num_groups（dimidx）-1。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values, get_group_id() returns 0. dimidx的有效值为0到get_work_dim（）-1。对于其他值，get_group_id（）返回0。
size_t get_global_offset(uint dimindx)	get_global_offset returns the offset values specified in global_work_offset argument to clEnqueueNDRangeKernel. get_global_offset将global_work_offset参数中指定的偏移值返回给clEnqueueNDRangeKernel。 Valid values of dimindx are 0 to get_work_dim() - 1. For other values, get_global_offset() returns 0. dimidx的有效值为0到get_work_dim（）-1。对于其他值，get_global_offset（）返回0。 Requires support for OpenCL C 1.1 or newer. 需要支持OpenCL C 1.1或更高版本。
size_t get_global_linear_id()	Returns the work-items 1-dimensional global ID. 返回工作项的一维全局ID。 For 1D work-groups, it is computed as get_global_id(0) - get_global_offset(0). 对于1D工作组，它被计算为get_global_id（0）-get_global_foffset（0）。 For 2D work-groups, it is computed as (get_global_id(1) - get_global_offset(1)) * get_global_size(0) + (get_global_id(0) - get_global_offset(0)). 对于二维工作组，其计算公式为（get_global_id（1）-get_global_offset（1））*get_global_size（0）+（get_global_id（0）-get_global_offset）。 For 3D work-groups, it is computed as ((get_global_id(2) - get_global_offset(2)) * get_global_size(1) * get_global_size(0)) + ((get_global_id(1) - get_global_offset(1)) * get_global_size(0)) + (get_global_id(0) - get_global_offset(0)). 对于三维工作组，其计算公式为((get_global_id(2) - get_global_offset(2)) * get_global_size(1) * get_global_size(0)) + ((get_global_id(1) - get_global_offset(1)) * get_global_size(0)) + (get_global_id(0) - get_global_offset(0))。 Requires support for OpenCL 2.0 or newer. 需要支持OpenCL 2.0或更高版本。
size_t get_local_linear_id()	Returns the work-items 1-dimensional local ID. 返回工作项的一维局部ID。 For 1D work-groups, it is the same value as get_local_id(0). 对于1D工作组，其值与 get_local_id（0）。 For 2D work-groups, it is computed as get_local_id(1) * get_local_size(0) + get_local_id(0). 对于二维工作组，其计算公式为 get_local_id（1）*get_local_size（0）+get_local_id（0）。 For 3D work-groups, it is computed as (get_local_id(2) * get_local_size(1) * get_local_size(0)) + (get_local_id(1) * get_local_size(0)) + get_local_id(0). 对于三维工作组，其计算公式为 （get_local_id（2）*get_local_size（1）*get.local_size。 Requires support for OpenCL 2.0 or newer. 需要支持OpenCL 2.0或更高版本。

The functionality described in the following table requires support for the cl_khr_subgroups extension macro; or for OpenCL C 3.0 or newer and the __opencl_c_subgroups feature. ​下表中描述的函数需要支持cl_khr_subgroups扩展宏；或者用于OpenCL C 3.0或更高版本以及__opencl_c_subgroups功能。

The following table describes the list of built-in work-item functions that can be used to query the size of a sub-group, number of sub-groups per work-group, and identifier of the sub-group within a work-group and work-item within a sub-group when this kernel is being executed on a device.

下表描述了在设备上执行此内核时，可用于查询子组大小、每个工作组的子组数量以及工作组内子组和子组内工作项的标识符的内置工作项函数列表。

Table 10. Built-in Work-Item Functions for Sub-Groups

表10 子组的内置工作项函数

Function 函数	Description 描述
uint get_sub_group_size()	Returns the number of work-items in the sub-group. This value is no more than the maximum sub-group size and is implementation-defined based on a combination of the compiled kernel and the dispatch dimensions. This will be a constant value for the lifetime of the sub-group. 返回子组中的工作项数。此值不超过最大子组大小，并且是基于编译的内核和调度维度的组合定义的实现。这将是子组生命周期的恒定值。
uint get_max_sub_group_size()	Returns the maximum size of a sub-group within the dispatch. This value will be invariant for a given set of dispatch dimensions and a kernel object compiled for a given device. 返回调度中子组的最大大小。对于给定的调度维度集和为给定设备编译的内核对象，此值将保持不变。
uint get_num_sub_groups()	Returns the number of sub-groups that the current work-group is divided into. 返回当前工作组划分为的子组数。 This number will be constant for the duration of a work-group’s execution. If the kernel is executed with a non-uniform work-group size (i.e. the global_work_size values specified to clEnqueueNDRangeKernel are not evenly divisible by the local_work_size values for any dimension, calls to this built-in from some work-groups may return different values than calls to this built-in from other work-groups. 在工作组执行期间，此数字将保持不变。如果内核以非均匀的工作组大小执行（即指定给clEnqueueNDRangeKernel的global_work_size值不能被任何维度的local_work_size值整除），则某些工作组对此内置的调用可能会返回与其他工作组对此内建的调用不同的值。
uint get_enqueued_num_sub_groups()	Returns the same value as that returned by get_num_sub_groups if the kernel is executed with a uniform work-group size. 如果内核以统一的工作组大小执行，则返回与get_num_sub_groups返回的值相同的值。 If the kernel is executed with a non-uniform work-group size, returns the number of sub-groups in each of the work-groups that make up the uniform region of the global range. 如果内核以非均匀的工作组大小执行，则返回构成全局范围均匀区域的每个工作组中的子组数量。
uint get_sub_group_id()	get_sub_group_id returns the sub-group ID which is a number from 0 .. get_num_sub_groups() - 1. get_sub_group_id返回子组id，该子组id是0中的一个数字。。get_num_sub_groups（）-1。 For clEnqueueTask, this returns 0. 对于clEnqueueTask，这将返回0。
uint get_sub_group_local_id()	Returns the unique work-item ID within the current sub-group. The mapping from get_local_id(dimindx) to get_sub_group_local_id will be invariant for the lifetime of the work-group. 返回当前子组中唯一的工作项ID。从get_logal_id（dimidx）到get_sub_group_local_id的映射在工作组的生命周期内是不变的。