Grids

A grid is simply a two-dimensional array. A grid has an integer width and height. The structure allows you to set and retrieve the value of cells in the grid by giving the index of it (which starts with 0 in both the x- and the y-direction). But you can also set the value in regions, add values, and retrieve the sum, max, min, and mean value over a region. The structure is useful to represent e.g. a playing field. Even though all functionality can also be achieved using two-dimensional arrays, the operations on regions are a lot faster. The following functions exist:

ds_grid_create(w, h) Creates a new grid with the indicated width and height. The function returns an integer as an id that must be used in all other functions to access the particular grid.
ds_grid_destroy(id) Destroys the grid with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_grid_copy(id, source) Copies the grid source into the grid with the given id.
ds_grid_resize(id, w, h) Resizes the grid to the new width and height. Existing cells keep their original value.
ds_grid_width(id) Returns the width of the grid with the indicated id.
ds_grid_height(id) Returns the height of the grid with the indicated id.
ds_grid_clear(id, val) Clears the grid with the given id, to the indicated value (can both be a number or a string).
ds_grid_set(id, x, y, val) Sets the indicated cell in the grid with the given id, to the indicated value (can both be a number or a string).
ds_grid_add(id, x, y, val) Add the value to the indicated cell in the grid with the given id. For strings this corresponds to concatenation.
ds_grid_multiply(id, x, y, val) Multiplies the value to the indicated cell in the grid with the given id. Is only valid for numbers.
ds_grid_set_region(id, x1, y1, x2, y2, val) Sets the all cells in the region in the grid with the given id, to the indicated value (can both be a number or a string).
ds_grid_add_region(id, x1, y1, x2, y2, val) Add the value to the cell in the region in the grid with the given id. For strings this corresponds to concatenation.
ds_grid_multiply_region(id, x1, y1, x2, y2, val) Multiplies the value to the cells in the region in the grid with the given id. Is only valid for numbers.
ds_grid_set_disk(id, xm, ym, r, val) Sets all cells in the disk with center (xm,ym) and radius r.
ds_grid_add_disk(id, xm, ym, r, val) Add the value to all cells in the disk with center (xm,ym) and radius r.
ds_grid_multiply_disk(id, xm, ym, r, val) Multiply the value to all cells in the disk with center (xm,ym) and radius r.
ds_grid_set_grid_region(id, source, x1, y1, x2, y2, xpos, ypos) Copies the contents of the cells in the region in grid source to grid id. xpos and ypos indicate the place where the region must be placed in the grid. (Can also be used to copy values from one place in a grid to another.)
ds_grid_add_grid_region(id, source, x1, y1, x2, y2, xpos, ypos) Adds the contents of the cells in the region in grid source to grid id. xpos and ypos indicate the place where the region must be added in the grid. (id and source can be the same.)
ds_grid_multiply_grid_region(id, source, x1, y1, x2, y2, xpos, ypos) Multiplies the contents of the cells in the region in grid source to grid id. xpos and ypos indicate the place where the region must be multiplied in the grid. (id and source can be the same.) Only valid for numbers.
ds_grid_get(id, x, y) Returns the value of the indicated cell in the grid with the given id.
ds_grid_get_sum(id, x1, y1, x2, y2) Returns the sum of the values of the cells in the region in the grid with the given id. Does only work when the cells contain numbers.
ds_grid_get_max(id, x1, y1, x2, y2) Returns the maximum of the values of the cells in the region in the grid with the given id. Does only work when the cells contain numbers.
ds_grid_get_min(id, x1, y1, x2, y2) Returns the minimum of the values of the cells in the region in the grid with the given id. Does only work when the cells contain numbers.
ds_grid_get_mean(id, x1, y1, x2, y2) Returns the mean of the values of the cells in the region in the grid with the given id. Does only work when the cells contain numbers.
ds_grid_get_disk_sum(id, xm, ym, r) Returns the sum of the values of the cells in the disk.
ds_grid_get_disk_min(id, xm, ym, r) Returns the min of the values of the cells in the disk.
ds_grid_get_disk_max(id, xm, ym, r) Returns the max of the values of the cells in the disk.
ds_grid_get_disk_mean(id, xm, ym, r) Returns the mean of the values of the cells in the disk.
ds_grid_value_exists(id, x1, y1, x2, y2, val) Returns whether the value appears somewhere in the region.
ds_grid_value_x(id, x1, y1, x2, y2, val) Returns the x-coordinate of the cell in which the value appears in the region.
ds_grid_value_y(id, x1, y1, x2, y2, val) Returns the y-coordinate of the cell in which the value appears in the region.
ds_grid_value_disk_exists(id, xm, ym, r, val) Returns whether the value appears somewhere in the disk.
ds_grid_value_disk_x(id, xm, ym, r, val) Returns the x-coordinate of the cell in which the value appears in the disk.
ds_grid_value_disk_y(id, xm, ym, r, val) Returns the y-coordinate of the cell in which the value appears in the disk.
ds_grid_shuffle(id) Shuffles the values in the grid such that they end up in a random order.
ds_grid_write(id) Turns the data structure into a string and returns this string. The string can then be used to e.g. save it to a file. This provides an easy mechanism for saving data structures.
ds_grid_read(id, str) Reads the data structure from the given string (as created by the previous call).