Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.field.grid
Interface Grid3D

All Superinterfaces:
  java.io.Serializable

All Known Implementing Classes:
  AbstractGrid3D, DoubleGrid3D, IntGrid3D, ObjectGrid3D

    public interface Grid3D

extends java.io.Serializable

Define basic neighborhood functions for 3D Grids. The basic interface defines a width and a height (not all grids require a width and a height unless you're doing toroidal grids), and basic math for toroidal computation.

### Toroidal Computation

If you're using the Grid to define a toroidal (wrap-around) world, you can use the tx and ty and tz methods to simplify the math for you. For example, to increment in the x direction, including wrap-around, you can do: x = tx(x+1).

If you're sure that the values you'd pass into the toroidal functions would not wander off more than a grid dimension in either direction (height, width, length), you can use the slightly faster toroidal functions stx and sty and stz instead. For example, to increment in the x direction, including wrap-around, you can do: x = stx(x+1). See the documentation on these functions for when they're appropriate to use. Under most common situations, they're okay.

In HotSpot 1.4.1, stx, sty, and stz are inlined. In Hotspot 1.3.1, they are not (they contain if-statements).

While this interface defines various methods common to many grids, you should endeavor not to call these grids casted into this interface: it's slow. If you call the grids' methods directly by their class, their methods are almost certain to be inlined into your code, which is very fast.

Method Summary
`int` | `getHeight()` Get the height
`int` | `getLength()` Get the length
`void` | `getNeighborsHamiltonianDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)` Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) + abs(z-Z) <= dist.
`void` | `getNeighborsMaxDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)` Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y), abs(z-Z) ) <= dist.
`int` | `getWidth()` Get the width
`int` | `stx(int x)` Simple [and fast] toroidal x.
`int` | `sty(int y)` Simple [and fast] toroidal y.
`int` | `stz(int z)` Simple [and fast] toroidal z.
`int` | `tx(int x)` Toroidal x.
`int` | `ty(int y)` Toroidal y.
`int` | `tz(int z)` Toroidal z.

Method Detail

### getWidth

    int getWidth()

  Get the width

### getHeight

    int getHeight()

  Get the height

### getLength

    int getLength()

  Get the length

### tx

    int tx(int x)

  Toroidal x. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

### ty

    int ty(int y)

  Toroidal y. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

### tz

    int tz(int z)

  Toroidal z. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

### stx

    int stx(int x)

  Simple [and fast] toroidal x. Use this if the values you'd pass in never stray beyond (-width ... width * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int width = this.width; if (x >= 0) { if (x < width) return x; return x - width; } return x + width; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int width = this.width; is likely to be a little faster if most objects are usually within the toroidal region.

### sty

    int sty(int y)

  Simple [and fast] toroidal y. Use this if the values you'd pass in never stray beyond (-height ... height * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int height = this.height; if (y >= 0) { if (y < height) return y ; return y - height; } return y + height; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int height = this.height; is likely to be a little faster if most objects are usually within the toroidal region.

### stz

    int stz(int z)

  Simple [and fast] toroidal z. Use this if the values you'd pass in never stray beyond (-length ... length * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int length = this.length; if (z >= 0) { if (z < length) return z ; return z - length; } return z + length; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int length = this.length; is likely to be a little faster if most objects are usually within the toroidal region.

### getNeighborsMaxDistance

    void getNeighborsMaxDistance(int x,
                                 int y,
                                 int z,
                                 int dist,
                                 boolean toroidal,
                                 IntBag xPos,
                                 IntBag yPos,
                                 IntBag zPos)

  Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y), abs(z-Z) ) <= dist. This region forms a cube 2*dist+1 cells across, centered at (X,Y,Z). If dist==1, this is equivalent to the twenty-six neighbors surrounding (X,Y,Z), plus (X,Y) itself. Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first.

### getNeighborsHamiltonianDistance

    void getNeighborsHamiltonianDistance(int x,
                                         int y,
                                         int z,
                                         int dist,
                                         boolean toroidal,
                                         IntBag xPos,
                                         IntBag yPos,
                                         IntBag zPos)

  Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) + abs(z-Z) <= dist. This region forms an octohedron 2*dist+1 cells from point to opposite point inclusive, centered at (X,Y,Y). If dist==1 this is equivalent to the six neighbors above, below, left, and right, front, and behind (X,Y,Z)), plus (X,Y,Z) itself. Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD