HC/docs/SpatialHash.rst
2015-10-09 23:10:15 +02:00

165 lines
4.6 KiB
ReStructuredText

HC.spatialhash
==============
::
spatialhash = require 'HC.spatialhash'
A spatial hash implementation that supports scenes of arbitrary size. The hash
is sparse, which means that cells will only be created when needed.
.. class:: Spatialhash([cellsize = 100])
:param number cellsize: Width and height of a cell (optional).
Create a new spatial hash with a given cell size.
Choosing a good cell size depends on your application. To get a decent speedup,
the average cell should not contain too many objects, nor should a single
object occupy too many cells. A good rule of thumb is to choose the cell size
so that the average object will occupy only one cell.
.. note::
The syntax depends on used class system. The shown syntax works when using
the bundled `hump.class <http://vrld.github.com/hump/#hump.class>`_ or
`slither <https://bitbucket.org/bartbes/slither>`_.
**Example**::
Spatialhash = require 'hardoncollider.spatialhash'
hash = Spatialhash(150)
.. function:: Spatialhash:cellCoords(x,y)
:param numbers x, y: The position to query.
:returns: Coordinates of the cell which would contain ``x,y``.
Get coordinates of a given value, i.e. the cell index in which a given point
would be placed.
**Example**::
local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)
.. function:: Spatialhash:cell(i,k)
:param numbers i, k: The cell index.
:returns: Set of objects contained in the cell.
Get the cell with given coordinates.
A cell is a table which's keys and value are the objects stored in the cell,
i.e.::
cell = {
[obj1] = obj1,
[obj2] = obj2,
...
}
You can iterate over the objects in a cell using ``pairs()``::
for object in pairs(cell) do stuff(object) end
**Example**::
local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)
cell = hash:cell(cx, cy)
.. function:: Spatialhash:cellAt(x,y)
:param numbers x, y: The position to query.
:returns: Set of objects contained in the cell.
Get the cell that contains point x,y.
Same as ``hash:cell(hash:cellCoords(x,y))``
**Example**::
local mx,my = love.mouse.getPosition()
cell = hash:cellAt(mx, my)
.. function:: Spatialhash:shapes()
:returns: Set of all shapes in the hash.
Get *all* shapes that are recorded in the hash.
.. function:: Spatialhash:inSameCells(x1,y1, x2,y2)
:param numbers x1,y1: Upper left corner of the query bounding box.
:param numbers x2,y2: Lower right corner of the query bounding box.
:returns: Set of all shapes in the same cell as the bbox.
Get the shapes that are in the same cell as the defined bounding box.
.. function:: Spatialhash:register(obj, x1,y1, x2,y2)
:param mixed obj: Object to place in the hash. It can be of any type except `nil`.
:param numbers x1,y1: Upper left corner of the bounding box.
:param numbers x2,y2: Lower right corner of the bounding box.
Insert an object into the hash using a given bounding box.
**Example**::
hash:register(shape, shape:bbox())
.. function:: Spatialhash:remove(obj[, x1,y1[, x2,y2]])
:param mixed obj: The object to delete
:param numbers x1,y1: Upper left corner of the bounding box (optional).
:param numbers x2,y2: Lower right corner of the bounding box (optional).
Remove an object from the hash using a bounding box.
If no bounding box is given, search the whole hash to delete the object.
**Example**::
hash:remove(shape, shape:bbox())
hash:remove(object_with_unknown_position)
.. function:: Spatialhash:update(obj, x1,y1, x2,y2, x3,y3, x4,y4)
:param mixed obj: The object to be updated.
:param numbers x1,y1: Upper left corner of the bounding box before the object was moved.
:param numbers x2,y2: Lower right corner of the bounding box before the object was moved.
:param numbers x3,y3: Upper left corner of the bounding box after the object was moved.
:param numbers x4,y4: Lower right corner of the bounding box after the object was moved.
Update an objects position given the old bounding box and the new bounding box.
**Example**::
hash:update(shape, -100,-30, 0,60, -100,-70, 0,20)
.. function:: Spatialhash:draw(draw_mode[, show_empty = true[, print_key = false]])
:param string draw_mode: Either 'fill' or 'line'. See the LÖVE wiki.
:param boolean show_empty: Wether to draw empty cells (optional).
:param boolean print_key: Wether to print cell coordinates (optional).
Draw hash cells on the screen, mostly for debug purposes
**Example**::
love.graphics.setColor(160,140,100,100)
hash:draw('line', true, true)
hash:draw('fill', false)