DS_bin Dll - Help
Made by Maarten Baert

This DLL adds a new data structure to Game Maker. A ds_bin looks a bit like a grid, but there are some differences:
- A ds_bin can use up to 3 dimensions.
- A ds_bin contains only unsigned integers.
- You can choose the number of bits for each entry. Because of this a ds_bin uses almost no memory, this means you can use huge grids without running out of memory.

Basic functions:

ds_bin_create(bits,size_x,size_y,size_z) - Creates a ds_bin. bits indicates the number of bits that are used for each entry. The possible values are 1, 2, 4, 8, 16 and 32. Returns the id of the ds_bin.
ds_bin_destroy(id) - Destroys a ds_bin.
ds_bin_clear(id,val) - Clears a ds_bin. This is faster than using the region functions.
ds_bin_select(id) - Selects a ds_bin. The cell and region functions work on the selected ds_bin.
ds_bin_get_x(), ds_bin_get_y(), ds_bin_get_z() - These functions are used to retrieve the result of some other functions, for example ds_bin_min_region.

ds_bin_serialize(id) - Serializes a ds_bin. This will convert the contents of the ds_bin to a string.
ds_bin_unserialize(id,data) - Unserializes a ds_bin. The size of the ds_bin should equal the size of the original ds_bin.
Other functions:

This DLL contains a lot of functions that are very similar, so I won't explain them one by one. Most of the time I will show pseudo-code to explain what a function does. The functions can be divided into the following categories:
Mathematical functions:
- Add: result = a + b
- Subtract: result = a - b
- Invsubtract: result = b - a
- Multiply: result = a * b
- Divide: result = a / b
- Invdivide: result = b / a
Expression functions:
- Equal: result = (a = b)
- Notequal: result = (a != b)
- Greaterthan: result = (a > b)
- Greaterthanorequal: result = (a >= b)
- Lessthan: result = (a < b)
- Lessthanorequal: result = (a <= b)
Replace-expression functions:
- Replaceequal: if(a = b) result = val
- Replacenotequal: if(a != b) result = val
- Replacegreaterthan: if(a > b) result = val
- Replacegreaterthanorequal: if(a >= b) result = val
- Replacelessthan: if(a < b) result = val
- Replacelessthanorequal: if(a <= b) result = val
Boolean functions
- Boolean_not: result = (!a)
- Boolean_and: result = (a and b)
- Boolean_or: result = (a or b)
- Boolean_xor: result = (a xor b)
- Boolean_nand: result = !(a and b)
- Boolean_nor: result = !(a or b)
- Boolean_nxor: result = !(a xor b)
Bitwise functions
- Bitwise_not: result = (~a)
- Bitwise_lshift: result = (a << bits)
- Bitwise_rshift: result = (a >> bits)
- Bitwise_and: result = (a & b)
- Bitwise_or: result = (a | b)
- Bitwise_xor: result = (a ^ b)
- Bitwise_nand: result = ~(a & b)
- Bitwise_nor: result = ~(a | b)
- Bitwise_nxor: result = ~(a ^ b)
A * after a function name indicates this is a 'fast' function, meaning it will not perform the operation cell by cell. As a result, the ds_bins must use the same number of bits.

For mathematical function, note that the result will be 'wrapped' if it is too high.

Not all of these functions exist for all types of functions. For example, most boolean functions make no sense when used with a fixed value.

Cell functions:

All cell functions will use the selected ds_bin.
ds_bin_get_cell(x,y,z) - Returns the value of a cell.
ds_bin_set_cell(x,y,z,val) - Changes the value of a cell.
All the other functions will change the value of a single cell: a = operation(a).
ds_bin_add_cell(x,y,z,val), ds_bin_subtract_cell(x,y,z,val), ds_bin_invsubtract_cell(x,y,z,val), ds_bin_multiply_cell(x,y,z,val), ds_bin_divide_cell(x,y,z,val), ds_bin_invdivide_cell(x,y,z,val), ds_bin_equal_cell(x,y,z,val,trueval,falseval), ds_bin_notequal_cell(x,y,z,val,trueval,falseval), ds_bin_greaterthan_cell(x,y,z,val,trueval,falseval), ds_bin_greaterthanorequal_cell(x,y,z,val,trueval,falseval), ds_bin_lessthan_cell(x,y,z,val,trueval,falseval), ds_bin_lessthanorequal_cell(x,y,z,val,trueval,falseval), ds_bin_replaceequal_cell(x,y,z,val,replaceval), ds_bin_replacenotequal_cell(x,y,z,val,replaceval), ds_bin_replacegreaterthan_cell(x,y,z,val,replaceval), ds_bin_replacegreaterthanorequal_cell(x,y,z,val,replaceval), ds_bin_replacelessthan_cell(x,y,z,val,replaceval), ds_bin_replacelessthanorequal_cell(x,y,z,val,replaceval), ds_bin_boolean_not_cell(x,y,z), ds_bin_bitwise_not_cell(x,y,z), ds_bin_bitwise_lshift_cell(x,y,z,bits), ds_bin_bitwise_rshift_cell(x,y,z,bits), ds_bin_bitwise_and_cell(x,y,z,val), ds_bin_bitwise_or_cell(x,y,z,val), ds_bin_bitwise_xor_cell(x,y,z,val), ds_bin_bitwise_nand_cell(x,y,z,val), ds_bin_bitwise_nor_cell(x,y,z,val), ds_bin_bitwise_nxor_cell(x,y,z,val)

Region functions:

All region functions will use the selected ds_bin.
ds_bin_min_region(x,y,z,size_x,size_y,size_z) - Returns the lowest value found in the specified region. The coordinates of this cell can be retrieved with get_x(), get_y() and get_z().
ds_bin_max_region(x,y,z,size_x,size_y,size_z) - Returns the highest value found in the specified region. The coordinates of this cell can be retrieved with get_x(), get_y() and get_z().
ds_bin_find_region(x,y,z,size_x,size_y,size_z,val) - Returns whether a cell with the given value was found in the specified region. The coordinates of the first cell can be retrieved with get_x(), get_y() and get_z().
ds_bin_find_region_continue(x,y,z,size_x,size_y,size_z,val) - Continues a search operation started by the previous function. Returns whether a cell was found. The coordinates of this cell can be retrieved with get_x(), get_y() and get_z().
ds_bin_sum_region(x,y,z,size_x,size_y,size_z) - Returns the sum of all values in the region specified.
ds_bin_weightedrandom_region(x,y,z,size_x,size_y,size_z,random) - Chooses a random cell from the selected region using the value of the cell as the 'weight'. This means cells with a higher value have a higher chance of being selected. Cells that have a value of 0 will never be selected. The coordinates of this cell can be retrieved with ds_bin_get_x(), ds_bin_get_y() and ds_bin_get_z().
ds_bin_set_region(x,y,z,size_x,size_y,size_z,val) - Changes the value of all cells in the region specified.
All other functions will change the value of all cells inside the region specified: a = operation(a).
ds_bin_add_region(x,y,z,size_x,size_y,size_z,val), ds_bin_subtract_region(x,y,z,size_x,size_y,size_z,val), ds_bin_invsubtract_region(x,y,z,size_x,size_y,size_z,val), ds_bin_multiply_region(x,y,z,size_x,size_y,size_z,val), ds_bin_divide_region(x,y,z,size_x,size_y,size_z,val), ds_bin_invdivide_region(x,y,z,size_x,size_y,size_z,val), ds_bin_equal_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_notequal_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_greaterthan_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_greaterthanorequal_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_lessthan_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_lessthanorequal_region(x,y,z,size_x,size_y,size_z,val,trueval,falseval), ds_bin_replaceequal_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_replacenotequal_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_replacegreaterthan_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_replacegreaterthanorequal_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_replacelessthan_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_replacelessthanorequal_region(x,y,z,size_x,size_y,size_z,val,replaceval), ds_bin_boolean_not_region(x,y,z,size_x,size_y,size_z), ds_bin_bitwise_not_region(x,y,z,size_x,size_y,size_z), ds_bin_bitwise_lshift_region(x,y,z,size_x,size_y,size_z,bits), ds_bin_bitwise_rshift_region(x,y,z,size_x,size_y,size_z,bits), ds_bin_bitwise_and_region(x,y,z,size_x,size_y,size_z,val), ds_bin_bitwise_or_region(x,y,z,size_x,size_y,size_z,val), ds_bin_bitwise_xor_region(x,y,z,size_x,size_y,size_z,val), ds_bin_bitwise_nand_region(x,y,z,size_x,size_y,size_z,val), ds_bin_bitwise_nor_region(x,y,z,size_x,size_y,size_z,val), ds_bin_bitwise_nxor_region(x,y,z,size_x,size_y,size_z,val)

Copy functions:

ds_bin_copy_direct(dest_id,src_id)* - Copies the contents of src to dest. This function is faster, but it can only be used for ds_bins that are identical (same number of bits and same size).
ds_bin_copy(dest_id,src_id) - Copies the contents of src to dest. The ds_bins must have the same size.
ds_bin_copy_part(dest_id,src_id,dest_x,dest_y,dest_z,src_x,src_y,src_z,size_x,size_y,size_z) - Copies a part of the contents of src to dest. This works also for ds_bins that don't have the same size.

'bin' functions:

These functions will perform an operation on a ds_bin, and store the result in another ds_bin: dest = operation(a). The ds_bins must have the same size.
ds_bin_boolean_not(dest_id,id), ds_bin_bitwise_not(dest_id,id)*, ds_bin_bitwise_lshift(dest_id,id,bits), ds_bin_bitwise_rshift(dest_id,id,bits)

'bin-val' functions:

These functions will perform an operation using a ds_bin and a fixed value, and store the result in another ds_bin: dest = operation(a,val). The ds_bins must have the same size.
ds_bin_val_add(dest_id,id,val), ds_bin_val_subtract(dest_id,id,val), ds_bin_val_invsubtract(dest_id,id,val), ds_bin_val_multiply(dest_id,id,val), ds_bin_val_divide(dest_id,id,val), ds_bin_val_invdivide(dest_id,id,val), ds_bin_val_equal(dest_id,id,val,trueval,falseval), ds_bin_val_notequal(dest_id,id,val,trueval,falseval), ds_bin_val_greaterthan(dest_id,id,val,trueval,falseval), ds_bin_val_greaterthanorequal(dest_id,id,val,trueval,falseval), ds_bin_val_lessthan(dest_id,id,val,trueval,falseval), ds_bin_val_lessthanorequal(dest_id,id,val,trueval,falseval), ds_bin_val_replaceequal(dest_id,id,val,replaceval), ds_bin_val_replacenotequal(dest_id,id,val,replaceval), ds_bin_val_replacegreaterthan(dest_id,id,val,replaceval), ds_bin_val_replacegreaterthanorequal(dest_id,id,val,replaceval), ds_bin_val_replacelessthan(dest_id,id,val,replaceval), ds_bin_val_replacelessthanorequal(dest_id,id,val,replaceval), ds_bin_val_bitwise_and(dest_id,id,val)*, ds_bin_val_bitwise_or(dest_id,id,val)*, ds_bin_val_bitwise_xor(dest_id,id,val)*, ds_bin_val_bitwise_nand(dest_id,id,val)*, ds_bin_val_bitwise_nor(dest_id,id,val)*, ds_bin_val_bitwise_nxor(dest_id,id,val)*

'bin-bin' functions:

These functions will perform an operation using two ds_bins, and store the result in another ds_bin: dest = operation(a,val). All ds_bins must have the same size.
ds_bin_bin_add(dest_id,id1,id2), ds_bin_bin_subtract(dest_id,id1,id2), ds_bin_bin_multiply(dest_id,id1,id2), ds_bin_bin_divide(dest_id,id1,id2), ds_bin_bin_equal(dest_id,id1,id2,trueval,falseval), ds_bin_bin_notequal(dest_id,id1,id2,trueval,falseval), ds_bin_bin_greaterthan(dest_id,id1,id2,trueval,falseval), ds_bin_bin_greaterthanorequal(dest_id,id1,id2,trueval,falseval), ds_bin_bin_lessthan(dest_id,id1,id2,trueval,falseval), ds_bin_bin_lessthanorequal(dest_id,id1,id2,trueval,falseval), ds_bin_bin_replaceequal(dest_id,id1,id2,replaceval), ds_bin_bin_replacenotequal(dest_id,id1,id2,replaceval), ds_bin_bin_replacegreaterthan(dest_id,id1,id2,replaceval), ds_bin_bin_replacegreaterthanorequal(dest_id,id1,id2,replaceval), ds_bin_bin_replacelessthan(dest_id,id1,id2,replaceval), ds_bin_bin_replacelessthanorequal(dest_id,id1,id2,replaceval), ds_bin_bin_boolean_and(dest_id,id1,id2), ds_bin_bin_boolean_or(dest_id,id1,id2), ds_bin_bin_boolean_xor(dest_id,id1,id2), ds_bin_bin_boolean_nand(dest_id,id1,id2), ds_bin_bin_boolean_nor(dest_id,id1,id2), ds_bin_bin_boolean_nxor(dest_id,id1,id2), ds_bin_bin_bitwise_and(dest_id,id1,id2)*, ds_bin_bin_bitwise_or(dest_id,id1,id2)*, ds_bin_bin_bitwise_xor(dest_id,id1,id2)*, ds_bin_bin_bitwise_nand(dest_id,id1,id2)*, ds_bin_bin_bitwise_nor(dest_id,id1,id2)*, ds_bin_bin_bitwise_nxor(dest_id,id1,id2)*

I added all functions I could think of. If you need another function, just PM me.

Good luck using this dll!