Package com.aparapi

Class 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 Detail

      • MAX_GROUP_SIZE

        public static final int MAX_GROUP_SIZE
      • maxWorkGroupSize

        private int maxWorkGroupSize
      • maxWorkItemSize

        private int[] maxWorkItemSize
    • Constructor Detail

      • Range

        public Range​(Device _device,
                     int _dims)
        Minimal constructor
        Parameters:
        _device -
        _dims -
    • Method Detail

      • 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 && _localWidth > 0 && _localWidth < MAX_GROUP_SIZE && _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 && _localWidth < MAX_GROUP_SIZE && _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 && _globalHeight >0 && _localWidth>0 && _localHeight>0 && _localWidth*_localHeight < MAX_GROUP_SIZE && _globalWidth%_localWidth==0 && _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 && _globalHeight >0 && _localWidth>0 && _localHeight>0 && _localWidth*_localHeight < MAX_GROUP_SIZE && _globalWidth%_localWidth==0 && _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 ( <= 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 && _globalHeight >0 _globalDepth >0 && _localWidth>0 && _localHeight>0 && _localDepth>0 && _localWidth*_localHeight*_localDepth < MAX_GROUP_SIZE && _globalWidth%_localWidth==0 && _globalHeight%_localHeight==0 && _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 && _globalHeight >0 _globalDepth >0 && _localWidth>0 && _localHeight>0 && _localDepth>0 && _localWidth*_localHeight*_localDepth < MAX_GROUP_SIZE && _globalWidth%_localWidth==0 && _globalHeight%_localHeight==0 && _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 ( <= 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 java.lang.String toString()
        Override toString()
        Overrides:
        toString in class java.lang.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