Package com.aparapi

Class Range

java.lang.Object
com.aparapi.internal.jni.RangeJNI
com.aparapi.Range
public class Range extends RangeJNI
A representation of 1, 2 or 3 dimensional range of execution. This class uses factory methods to allow one, two or three dimensional ranges to be created.
For a Kernel operating over the linear range 0..1024 without a specified groups size we would create a one dimensional Range using 
Range.create(1024);
To request the same linear range but with a groupSize of 64 (range must be a multiple of group size!) we would use 
Range.create(1024,64);
To request a two dimensional range over a grid (0..width)x(0..height) where width==512 and height=256 we would use 
 int width=512;
 int height=256;
 Range.create2D(width,height)
Again the above does not specify the group size. One will be chosen for you. If you want to specify the groupSize (say 16x8; 16 wide by 8 high) use 
 int width=512;
 int height=256;
 int groupWidth=16;
 int groupHeight=8;
 Range.create2D(width, height, groupWidth, groupHeight);
Finally we can request a three dimensional range using 
 int width=512;
 int height=256;
 int depth=8;
 Range.create3D(width, height, depth);
And can specify a group size using 
  int width=512;
  int height=256;
  int depth=8;
  int groupWidth=8;
  int groupHeight=4;
  int groupDepth=2
  Range.create3D(width, height, depth, groupWidth, groupHeight, groupDepth);

  • Field Details

    • THREADS_PER_CORE

      public static final int THREADS_PER_CORE
      See Also:

    • MAX_OPENCL_GROUP_SIZE

      public static final int MAX_OPENCL_GROUP_SIZE
      See Also:

    • MAX_GROUP_SIZE

      public static final int MAX_GROUP_SIZE

    • device

      private OpenCLDevice device

    • maxWorkGroupSize

      private int maxWorkGroupSize

    • maxWorkItemSize

      private int[] maxWorkItemSize

  • Constructor Details

    • Range

      public Range(Device _device, int _dims)
      Minimal constructor
      Parameters:
      _device -
      _dims -

  • Method Details

    • create

      public static Range create(Device _device, int _globalWidth, int _localWidth)
      Create a one dimensional range 0.._globalWidth which is processed in groups of size _localWidth.
      Note that for this range to be valid :
      _globalWidth > 0 invalid input: '&'invalid input: '&' _localWidth > 0 invalid input: '&'invalid input: '&' _localWidth invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth % _localWidth==0
      Parameters:
      _globalWidth - the overall range we wish to process
      _localWidth - the size of the group we wish to process.
      Returns:
      A new Range with the requested dimensions

    • getFactors

      private static int[] getFactors(int _value, int _max)
      Determine the set of factors for a given value.
      Parameters:
      _value - The value we wish to factorize.
      _max - an upper bound on the value that can be chosen
      Returns:
      and array of factors of _value

    • create

      public static Range create(Device _device, int _globalWidth)
      Create a one dimensional range 0.._globalWidth with an undefined group size.
      Note that for this range to be valid :-
      _globalWidth > 0
      The groupsize will be chosen such that _localWidth > 0 invalid input: '&'invalid input: '&' _localWidth invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth % _localWidth==0 is true We extract the factors of _globalWidth and choose the highest value.
      Parameters:
      _globalWidth - the overall range we wish to process
      Returns:
      A new Range with the requested dimensions

    • create

      public static Range create(int _globalWidth, int _localWidth)

    • create

      public static Range create(int _globalWidth)

    • create2D

      public static Range create2D(Device _device, int _globalWidth, int _globalHeight, int _localWidth, int _localHeight)
      Create a two dimensional range 0.._globalWidth x 0.._globalHeight using a group which is _localWidth x _localHeight in size.
      Note that for this range to be valid _globalWidth > 0 invalid input: '&'invalid input: '&' _globalHeight >0 invalid input: '&'invalid input: '&' _localWidth>0 invalid input: '&'invalid input: '&' _localHeight>0 invalid input: '&'invalid input: '&' _localWidth*_localHeight invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth%_localWidth==0 invalid input: '&'invalid input: '&' _globalHeight%_localHeight==0.
      Parameters:
      _globalWidth - the overall range we wish to process
      Returns:

    • create2D

      public static Range create2D(Device _device, int _globalWidth, int _globalHeight)
      Create a two dimensional range 0.._globalWidth * 0.._globalHeight choosing suitable values for localWidth and localHeight.

      Note that for this range to be valid _globalWidth > 0 invalid input: '&'invalid input: '&' _globalHeight >0 invalid input: '&'invalid input: '&' _localWidth>0 invalid input: '&'invalid input: '&' _localHeight>0 invalid input: '&'invalid input: '&' _localWidth*_localHeight invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth%_localWidth==0 invalid input: '&'invalid input: '&' _globalHeight%_localHeight==0.

      To determine suitable values for _localWidth and _localHeight we extract the factors for _globalWidth and _globalHeight and then find the largest product ( invalid input: '<'= MAX_GROUP_SIZE) with the lowest perimeter.

      For example for MAX_GROUP_SIZE of 16 we favor 4x4 over 1x16.

      Parameters:
      _globalWidth - the overall range we wish to process
      Returns:

    • create2D

      public static Range create2D(int _globalWidth, int _globalHeight, int _localWidth, int _localHeight)

    • create2D

      public static Range create2D(int _globalWidth, int _globalHeight)

    • create3D

      public static Range create3D(Device _device, int _globalWidth, int _globalHeight, int _globalDepth, int _localWidth, int _localHeight, int _localDepth)
      Create a two dimensional range 0.._globalWidth * 0.._globalHeight *0../_globalDepth in groups defined by localWidth * localHeight * localDepth.

      Note that for this range to be valid _globalWidth > 0 invalid input: '&'invalid input: '&' _globalHeight >0 _globalDepth >0 invalid input: '&'invalid input: '&' _localWidth>0 invalid input: '&'invalid input: '&' _localHeight>0 invalid input: '&'invalid input: '&' _localDepth>0 invalid input: '&'invalid input: '&' _localWidth*_localHeight*_localDepth invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth%_localWidth==0 invalid input: '&'invalid input: '&' _globalHeight%_localHeight==0 invalid input: '&'invalid input: '&' _globalDepth%_localDepth==0.

      Parameters:
      _globalWidth - the width of the 3D grid we wish to process
      _globalHeight - the height of the 3D grid we wish to process
      _globalDepth - the depth of the 3D grid we wish to process
      _localWidth - the width of the 3D group we wish to process
      _localHeight - the height of the 3D group we wish to process
      _localDepth - the depth of the 3D group we wish to process
      Returns:

    • create3D

      public static Range create3D(Device _device, int _globalWidth, int _globalHeight, int _globalDepth)
      Create a three dimensional range 0.._globalWidth * 0.._globalHeight *0../_globalDepth choosing suitable values for localWidth, localHeight and localDepth.

      Note that for this range to be valid _globalWidth > 0 invalid input: '&'invalid input: '&' _globalHeight >0 _globalDepth >0 invalid input: '&'invalid input: '&' _localWidth>0 invalid input: '&'invalid input: '&' _localHeight>0 invalid input: '&'invalid input: '&' _localDepth>0 invalid input: '&'invalid input: '&' _localWidth*_localHeight*_localDepth invalid input: '<' MAX_GROUP_SIZE invalid input: '&'invalid input: '&' _globalWidth%_localWidth==0 invalid input: '&'invalid input: '&' _globalHeight%_localHeight==0 invalid input: '&'invalid input: '&' _globalDepth%_localDepth==0.

      To determine suitable values for _localWidth,_localHeight and _lodalDepth we extract the factors for _globalWidth,_globalHeight and _globalDepth and then find the largest product ( invalid input: '<'= MAX_GROUP_SIZE) with the lowest perimeter.

      For example for MAX_GROUP_SIZE of 64 we favor 4x4x4 over 1x16x16.

      Parameters:
      _globalWidth - the width of the 3D grid we wish to process
      _globalHeight - the height of the 3D grid we wish to process
      _globalDepth - the depth of the 3D grid we wish to process
      Returns:

    • create3D

      public static Range create3D(int _globalWidth, int _globalHeight, int _globalDepth)

    • create3D

      public static Range create3D(int _globalWidth, int _globalHeight, int _globalDepth, int _localWidth, int _localHeight, int _localDepth)

    • toString

      public String toString()
      Override toString()
      Overrides:
      toString in class Object

    • getLocalSize

      public int getLocalSize(int _dim)
      Get the localSize (of the group) given the requested dimension
      Parameters:
      _dim - 0=width, 1=height, 2=depth
      Returns:
      The size of the group give the requested dimension

    • getGlobalSize

      public int getGlobalSize(int _dim)
      Get the globalSize (of the range) given the requested dimension
      Parameters:
      _dim - 0=width, 1=height, 2=depth
      Returns:
      The size of the group give the requested dimension

    • getNumGroups

      public int getNumGroups(int _dim)
      Get the number of groups for the given dimension.

      This will essentially return globalXXXX/localXXXX for the given dimension (width, height, depth)

      Parameters:
      _dim - The dim we are interested in 0, 1 or 2
      Returns:
      the number of groups for the given dimension.

    • getWorkGroupSize

      public int getWorkGroupSize()
      Returns:
      The product of all valid localSize dimensions

    • getDevice

      public Device getDevice()

    • getGlobalSize_0

      public int getGlobalSize_0()
      Returns:
      the globalSize_0

    • setGlobalSize_0

      public void setGlobalSize_0(int globalSize_0)
      Parameters:
      globalSize_0 - the globalSize_0 to set

    • getLocalSize_0

      public int getLocalSize_0()
      Returns:
      the localSize_0

    • setLocalSize_0

      public void setLocalSize_0(int localSize_0)
      Parameters:
      localSize_0 - the localSize_0 to set

    • getGlobalSize_1

      public int getGlobalSize_1()
      Returns:
      the globalSize_1

    • setGlobalSize_1

      public void setGlobalSize_1(int globalSize_1)
      Parameters:
      globalSize_1 - the globalSize_1 to set

    • getLocalSize_1

      public int getLocalSize_1()
      Returns:
      the localSize_1

    • setLocalSize_1

      public void setLocalSize_1(int localSize_1)
      Parameters:
      localSize_1 - the localSize_1 to set

    • getGlobalSize_2

      public int getGlobalSize_2()
      Returns:
      the globalSize_2

    • setGlobalSize_2

      public void setGlobalSize_2(int globalSize_2)
      Parameters:
      globalSize_2 - the globalSize_2 to set

    • getLocalSize_2

      public int getLocalSize_2()
      Returns:
      the localSize_2

    • setLocalSize_2

      public void setLocalSize_2(int localSize_2)
      Parameters:
      localSize_2 - the localSize_2 to set

    • getDims

      public int getDims()
      Get the number of dims for this Range.
      Returns:
      0, 1 or 2 for one dimensional, two dimensional and three dimensional range respectively.

    • setDims

      public void setDims(int dims)
      Parameters:
      dims - the dims to set

    • isValid

      public boolean isValid()
      Returns:
      the valid

    • setValid

      public void setValid(boolean valid)
      Parameters:
      valid - the valid to set

    • isLocalIsDerived

      public boolean isLocalIsDerived()
      Returns:
      the localIsDerived

    • setLocalIsDerived

      public void setLocalIsDerived(boolean localIsDerived)
      Parameters:
      localIsDerived - the localIsDerived to set

    • getMaxWorkGroupSize

      public int getMaxWorkGroupSize()
      Returns:
      the maxWorkGroupSize

    • setMaxWorkGroupSize

      public void setMaxWorkGroupSize(int maxWorkGroupSize)
      Parameters:
      maxWorkGroupSize - the maxWorkGroupSize to set

    • getMaxWorkItemSize

      public int[] getMaxWorkItemSize()
      Returns:
      the maxWorkItemSize

    • setMaxWorkItemSize

      public void setMaxWorkItemSize(int[] maxWorkItemSize)
      Parameters:
      maxWorkItemSize - the maxWorkItemSize to set