sim.field.grid
Interface Grid2D

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
AbstractGrid2D, SparseGrid2D

public interface Grid2D
extends java.io.Serializable

Define basic neighborhood functions for 2D 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 and hex grid location.

Toroidal Computation

If you're using the Grid to define a toroidal (wrap-around) world, you can use the tx and ty 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), you can use the slightly faster toroidal functions stx and sty 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, and sty are inlined. In Hotspot 1.3.1, they are not (they contain if-statements).

Hex Grid Computation

Grids can be used for both squares and hex grids. Hex grids are stored in an ordinary rectangular array and are defined as follows:

        (0,0)            (2,0)            (4,0)            (6,0)            ...
                (1,0)            (3,0)            (5,0)            (7,0)            ...
        (0,1)            (2,1)            (4,1)            (6,1)            ...
                (1,1)            (3,1)            (5,1)            (7,1)            ...
        (0,2)            (2,2)            (4,2)            (6,2)            ...
                (1,2)            (3,2)            (5,2)            (7,2)            ...
        ...              ...              ...              ...              ...
                ...              ...              ...              ...              ...

The rules moving from a hex location (at CENTER) to another one are as follows:


                                                UP
                                                x
            UPLEFT				y - 1			UPRIGHT
            x - 1							x + 1
            ((x % 2) == 0) ? y - 1 : y		CENTER			((x % 2) == 0) ? y - 1 : y
                                                x
            DOWNLEFT				y			DOWNRIGHT
            x - 1							x + 1
            ((x % 2) == 0) ? y : y + 1		DOWN			((x % 2) == 0) ? y : y + 1
                                                x
                                                y + 1

NOTE: (x % 2 == 0) may be defined as the faster ((x & 1) == 0)

Because the math is a little hairy, we've provided the X math for the UPLEFT, UPRIGHT, DOWNLEFT, and DOWNRIGHT directions for you. For example, the UPLEFT location from [x,y] is at [ulx(x,y) , uly(x,y)]. Additionally, the toroidal methods can be used in conjunction with the hex methods to implement a toroidal hex grid. Be sure to To use a toroidal hex grid properly, you must ensure that height of the grid is an even number. For example, the toroidal UPLEFT X location is at tx(ulx(x,y)) and the UPLEFT Y location is at ty(uly(x,y)). Similarly, you can use stx and sty.

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 dlx(int x, int y)
          Hex downleft x.
 int dly(int x, int y)
          Hex downleft y.
 int downx(int x, int y)
          Hex down x.
 int downy(int x, int y)
          Hex down y.
 int drx(int x, int y)
          Hex downright x.
 int dry(int x, int y)
          Hex downright y.
 int getHeight()
          Get the height
 void getNeighborsHamiltonianDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
           
 void getNeighborsHexagonalDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
           
 void getNeighborsMaxDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
           
 int getWidth()
          Get the width
 int stx(int x)
          Simple [and fast] toroidal x.
 int sty(int y)
          Simple [and fast] toroidal y.
 int tx(int x)
          Toroidal x.
 int ty(int y)
          Toroidal y.
 int ulx(int x, int y)
          Hex upleft x.
 int uly(int x, int y)
          Hex upleft y.
 int upx(int x, int y)
          Hex up x.
 int upy(int x, int y)
          Hex up y.
 int urx(int x, int y)
          Hex upright x.
 int ury(int x, int y)
          Hex upright y.
 

Method Detail

getWidth

public int getWidth()
Get the width


getHeight

public int getHeight()
Get the height


tx

public int tx(int x)
Toroidal x. Defined as: (x%width+width)%width


ty

public int ty(int y)
Toroidal y. Defined as: (y%height+height)%height


stx

public 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:
{ if (x >= 0) { if (x < width) return x; return x - width; } return x + width; } ...produces the shortest code (28 bytes) and is inlined in Hotspot for 1.4.1.


sty

public 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:
{ if (y >= 0) { if (y < height) return y ; return y - height; } return y + height; } ...produces the shortest code (28 bytes) and is inlined in Hotspot for 1.4.1.


ulx

public int ulx(int x,
               int y)
Hex upleft x.


uly

public int uly(int x,
               int y)
Hex upleft y.


urx

public int urx(int x,
               int y)
Hex upright x.


ury

public int ury(int x,
               int y)
Hex upright y.


dlx

public int dlx(int x,
               int y)
Hex downleft x.


dly

public int dly(int x,
               int y)
Hex downleft y.


drx

public int drx(int x,
               int y)
Hex downright x.


dry

public int dry(int x,
               int y)
Hex downright y.


upx

public int upx(int x,
               int y)
Hex up x.


upy

public int upy(int x,
               int y)
Hex up y.


downx

public int downx(int x,
                 int y)
Hex down x.


downy

public int downy(int x,
                 int y)
Hex down y.


getNeighborsMaxDistance

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

getNeighborsHamiltonianDistance

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

getNeighborsHexagonalDistance

public void getNeighborsHexagonalDistance(int x,
                                          int y,
                                          int dist,
                                          boolean toroidal,
                                          IntBag xPos,
                                          IntBag yPos)