diff --git a/source/conf.py b/source/conf.py index d9d033ac..184709ca 100644 --- a/source/conf.py +++ b/source/conf.py @@ -212,6 +212,9 @@ def make_ref(ref_str, ref_view, ref_sufix): "Section 4.7.5", "#_parallel_for_hierarchical_invoke", ) + + make_ref( + "SYCL_SPEC_ND_RANGE", "Section 4.9.1.2", "#subsubsec:nd-range-class" + ) + make_ref( "SYCL_SPEC_ADDRESS_SPACE", "Section 4.7.7", "#_address_space_classes" ) @@ -255,7 +258,6 @@ def make_ref(ref_str, ref_view, ref_sufix): .. |SYCL_SPEC_GROUP| replace:: `SYCL Specification`_ Section 4.10.1.7 .. |SYCL_SPEC_H_ITEM| replace:: `SYCL Specification`_ Section 4.10.1.6 .. |SYCL_SPEC_ND_ITEM| replace:: `SYCL Specification`_ Section 4.10.1.5 -.. |SYCL_SPEC_ND_RANGE| replace:: `SYCL Specification`_ Section 4.10.1.2 .. |SYCL_SPEC_DEVICE_EVENT| replace:: `SYCL Specification`_ Section 4.7.8 .. |SYCL_SPEC_HANDLER| replace:: `SYCL Specification`_ Section 4.10.4 .. |SYCL_SPEC_KERNEL| replace:: `SYCL Specification`_ Section 4.12 diff --git a/source/iface/nd_range.rst b/source/iface/nd_range.rst index fa240662..3d760805 100644 --- a/source/iface/nd_range.rst +++ b/source/iface/nd_range.rst @@ -2,70 +2,81 @@ Copyright 2020 The Khronos Group Inc. SPDX-License-Identifier: CC-BY-4.0 -.. rst-class:: api-class - .. _nd_range: - -================== +****************** ``sycl::nd_range`` -================== +****************** :: - template - class nd_range; - - -The ``nd_range`` defines the index space for a work group as well as -the global index space. It is passed to :ref:`handler-parallel_for` to -execute a kernel on a set of work items. - + template + class nd_range; .. rubric:: Template parameters ================ === -``dimensions`` Number of dimensions +``Dimensions`` Number of dimensions in the ``sycl::nd_range``. ================ === +The ``sycl::nd_range`` class defines the iteration domain of both +the work-groups and the overall dispatch. + +A ``sycl::nd_range`` comprises two +:ref:`range` parameters: the whole range over which +the kernel is to be executed, and the range of each work group. + +The ``sycl::nd_range`` class template provides the :ref:`common-byval`. .. seealso:: |SYCL_SPEC_ND_RANGE| +============== (constructors) ============== :: - nd_range(sycl::range globalSize, sycl::range localSize, - sycl::id offset = sycl::id()); + nd_range( + sycl::range globalSize, + sycl::range localSize, + sycl::id offset = sycl::id()); + +Construct an ``sycl::nd_range`` from the local +and global constituent :ref:`range`. -Construct an ``nd_range``. +Supplying the option offset is deprecated in SYCL 2020. +If the offset is not provided it will default to no offset. .. rubric:: Parameters ================== === -``globalSize`` dimensions of the entire index space -``localSize`` dimensions of the work group -``offset`` Origin of the index space [deprecated in SYCL 2020] +``globalSize`` Dimensions of the entire index space. +``localSize`` Dimensions of the work group. +``offset`` Origin of the index space. [deprecated in SYCL 2020] ================== === + +================ +Member functions +================ + ``get_global_range`` ==================== :: - sycl::range get_global_range() const; + sycl::range get_global_range() const; -Returns a :ref:`range` defining the index space. +Return the constituent global :ref:`range`. ``get_local_range`` =================== :: - sycl::range get_local_range() const; + sycl::range get_local_range() const; -Returns a :ref:`range` defining the index space of a work group. +Return the constituent local :ref:`range`. ``get_group_range`` =================== @@ -74,7 +85,11 @@ Returns a :ref:`range` defining the index space of a work group. sycl::range get_group_range() const; -Returns a :ref:`range` defining the number of work groups in every dimension. +Returns a :ref:`range` representing the number of +groups in each dimension. + +This range would result from ``globalSize``/``localSize`` +as provided on construction. ``get_offset`` @@ -82,6 +97,8 @@ Returns a :ref:`range` defining the number of work groups in every dimension. :: - sycl::id get_offset() const; + sycl::id get_offset() const; + +Deprecated in SYCL 2020. Returns a :ref:`id` defining the offset.