Range (Aparapi 1.2.0 API)

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 Summary

Fields
Modifier and Type Field and Description

static int MAX_GROUP_SIZE

static int MAX_OPENCL_GROUP_SIZE

static int THREADS_PER_CORE

Fields
Modifier and Type	Field and Description
`static int`	`MAX_GROUP_SIZE`
`static int`	`MAX_OPENCL_GROUP_SIZE`
`static int`	`THREADS_PER_CORE`

Constructor Summary

Constructors
Constructor and Description

Range(Device _device, int _dims)
Minimal constructor

Constructors
Constructor and Description
`Range(Device _device, int _dims)` Minimal constructor

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Range`	`create(Device _device, int _globalWidth)` Create a one dimensional range `0.._globalWidth` with an undefined group size.
`static Range`	`create(Device _device, int _globalWidth, int _localWidth)` Create a one dimensional range `0.._globalWidth` which is processed in groups of size _localWidth.
`static Range`	`create(int _globalWidth)`
`static Range`	`create(int _globalWidth, int _localWidth)`
`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`.
`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.
`static Range`	`create2D(int _globalWidth, int _globalHeight)`
`static Range`	`create2D(int _globalWidth, int _globalHeight, int _localWidth, int _localHeight)`
`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`.
`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`.
`static Range`	`create3D(int _globalWidth, int _globalHeight, int _globalDepth)`
`static Range`	`create3D(int _globalWidth, int _globalHeight, int _globalDepth, int _localWidth, int _localHeight, int _localDepth)`
`Device`	`getDevice()`
`int`	`getDims()` Get the number of dims for this Range.
`int`	`getGlobalSize_0()`
`int`	`getGlobalSize_1()`
`int`	`getGlobalSize_2()`
`int`	`getGlobalSize(int _dim)` Get the globalSize (of the range) given the requested dimension
`int`	`getLocalSize_0()`
`int`	`getLocalSize_1()`
`int`	`getLocalSize_2()`
`int`	`getLocalSize(int _dim)` Get the localSize (of the group) given the requested dimension
`int`	`getMaxWorkGroupSize()`
`int[]`	`getMaxWorkItemSize()`
`int`	`getNumGroups(int _dim)` Get the number of groups for the given dimension.
`int`	`getWorkGroupSize()`
`boolean`	`isLocalIsDerived()`
`boolean`	`isValid()`
`void`	`setDims(int dims)`
`void`	`setGlobalSize_0(int globalSize_0)`
`void`	`setGlobalSize_1(int globalSize_1)`
`void`	`setGlobalSize_2(int globalSize_2)`
`void`	`setLocalIsDerived(boolean localIsDerived)`
`void`	`setLocalSize_0(int localSize_0)`
`void`	`setLocalSize_1(int localSize_1)`
`void`	`setLocalSize_2(int localSize_2)`
`void`	`setMaxWorkGroupSize(int maxWorkGroupSize)`
`void`	`setMaxWorkItemSize(int[] maxWorkItemSize)`
`void`	`setValid(boolean valid)`
`String`	`toString()` Override `toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - THREADS_PER_CORE
```
public static final int THREADS_PER_CORE
```
    See Also:
    
    Constant Field Values
  - MAX_OPENCL_GROUP_SIZE
```
public static final int MAX_OPENCL_GROUP_SIZE
```
    See Also:
    
    Constant Field Values
  - MAX_GROUP_SIZE
```
public static final int MAX_GROUP_SIZE
```
- 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
  - 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 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

Class Range

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

THREADS_PER_CORE

MAX_OPENCL_GROUP_SIZE

MAX_GROUP_SIZE

Constructor Detail

Range

Method Detail

create

create

create

create

create2D

create2D

create2D

create2D

create3D

create3D

create3D

create3D

toString

getLocalSize

getGlobalSize

getNumGroups

getWorkGroupSize

getDevice

getGlobalSize_0

setGlobalSize_0

getLocalSize_0

setLocalSize_0

getGlobalSize_1

setGlobalSize_1

getLocalSize_1

setLocalSize_1

getGlobalSize_2

setGlobalSize_2

getLocalSize_2

setLocalSize_2

getDims

setDims

isValid

setValid

isLocalIsDerived

setLocalIsDerived

getMaxWorkGroupSize

setMaxWorkGroupSize

getMaxWorkItemSize

setMaxWorkItemSize