165 lines
4.6 KiB
ReStructuredText
Executable File
165 lines
4.6 KiB
ReStructuredText
Executable File
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)
|
|
|
|
|