Module field2D
Field2D: an object representing a 2D densely packed array.
Functions
| field2D:set (value, x, y) | set the value of a cell, or of all cells. |
| field2D:get (x, y) | return the value of a cell If x or y is out of range of the field, it wraps around (positive modulo) If x or y are not integers, the fractional component is discarded (rounded down) |
| field2D:sample (x, y) | return the value at a normalized index (0..1 range maps to field dimensions) Uses linear interpolation between nearest cells. |
| field2D:update (value, x, y) | Update the field at a normalized (0..1) index Like field2D:set(), but uses linear interpolation to distribute the update between nearest cells (thus it is an inverse of field:sample()). |
| field2D:splat (value, x, y) | Add a value to the field at a normalized (0..1) index Uses linear interpolation to distribute the value between nearest cells, for accumulation. |
| field2D:scale (value, x, y) | Multiply the field by a value, optionally at a normalized (0..1) index If indices are not given, all cells are multipled by the value. |
| field2D:diffuse (sourcefield, diffusion, passes) | fill the field with a diffused (blurred) copy of another |
| field2D:map (func) | Apply a function to each cell of the field in turn The function arguments will be the current value of the cell and the x and y position, and the return value should be the new value of the cell (or nil to indicate no change). |
| field2D:normalize () | normalize the field values to a 0..1 range |
| field2D:sum () | return the sum of all cells |
| field2D:max () | return the maximum value of all cells |
| field2D:min () | return the minimum value of all cells |
| field2D:draw (x, y, w, h, unit) | Draw the field in greyscale from 0..1 |
| field2D:drawHueRange (range) | Draw the field as a Hue spectrum from red to blue |
| drawFlow (fx, fy) | draw two fields representing X and Y vector components |
| field2D:copy () | Create a copy of the field with the same dimensions and contents |
Functions
- field2D:set (value, x, y)
-
set the value of a cell, or of all cells.
If the x,y coordinate is not specified, it will apply the value for all cells.
If the value to set is a function, this function is called (passing the x, y coordinates as arguments). If the function returns a value, the cell is set to this value; otherwise the cell is left unchanged.
Parameters:
- value number or function to set
- x optional int coordinate (row) to set a single cell
- y optional int coordinate (column) to set a single cell
- field2D:get (x, y)
-
return the value of a cell
If x or y is out of range of the field, it wraps around (positive modulo)
If x or y are not integers, the fractional component is discarded (rounded down)
Parameters:
- x optional int coordinate (row) to get a single cell
- y optional int coordinate (column) to get a single cell
- field2D:sample (x, y)
-
return the value at a normalized index (0..1 range maps to field dimensions)
Uses linear interpolation between nearest cells.
Indices out of range will wrap.
Parameters:
- x coordinate (0..1) to sample
- y coordinate (0..1) to sample
- field2D:update (value, x, y)
-
Update the field at a normalized (0..1) index
Like field2D:set(), but uses linear interpolation to distribute the update between nearest cells (thus it is an inverse of field:sample()). If the index falls exactly in the center of one cell, it is equivalent to field:set(). Otherwise, the four nearest cells will be updated as a weighted average of their current and the new value.
If the value is a function, this function is called for each nearby cell to generate a new value. The function argument is the old value of the cell.
Indices out of range will wrap.
Parameters:
- value (number or function) the value to update the field
- x coordinate (0..1) to update
- y coordinate (0..1) to update
Returns:
-
self
- field2D:splat (value, x, y)
-
Add a value to the field at a normalized (0..1) index
Uses linear interpolation to distribute the value between nearest cells, for accumulation.
Indices out of range will wrap.
Parameters:
- value the value to add to the field
- x coordinate (0..1) to update
- y coordinate (0..1) to update
Returns:
-
self
- field2D:scale (value, x, y)
-
Multiply the field by a value, optionally at a normalized (0..1) index
If indices are not given, all cells are multipled by the value.
Otherwise, uses linear interpolation to distribute the value between nearest cells, for multiplication. If the position index is exactly in the center of a cell, it performs a normal multiplcation. Otherwise the four nearest cells are updated according to a weighted average of their current and modified value.
Indices out of range will wrap.
Parameters:
- value the value to scale to the field
- x coordinate (0..1) to update (optional)
- y coordinate (0..1) to update (optional)
Returns:
-
self
- field2D:diffuse (sourcefield, diffusion, passes)
-
fill the field with a diffused (blurred) copy of another
Parameters:
- sourcefield the field to be diffused
- diffusion the rate of diffusion
- passes ?int the number of iterations to improve numerical accuracy (default 10)
- field2D:map (func)
-
Apply a function to each cell of the field in turn
The function arguments will be the current value of the cell and the x and y position, and the return value should be the new value of the cell (or nil to indicate no change). E.g. to multiply all cells by 2: field:map(function(value, x, y) return value * 2 end)
Parameters:
- func the function to apply
Returns:
-
self
- field2D:normalize ()
-
normalize the field values to a 0..1 range
Returns:
-
self
- field2D:sum ()
-
return the sum of all cells
Returns:
-
sum
- field2D:max ()
-
return the maximum value of all cells
Returns:
-
max
- field2D:min ()
-
return the minimum value of all cells
Returns:
-
min
- field2D:draw (x, y, w, h, unit)
-
Draw the field in greyscale from 0..1
Parameters:
- x left coordinate (optional, defaults to 0)
- y bottom coordinate (optional, defaults to 0)
- w width (optional, defaults to 1)
- h height (optional, defaults to 1)
- unit texture unit to use (defaults to 0)
- field2D:drawHueRange (range)
-
Draw the field as a Hue spectrum from red to blue
Parameters:
- range the maximum field value (renders as blue)
- drawFlow (fx, fy)
-
draw two fields representing X and Y vector components
Parameters:
- fx X component field
- fy Y component field
- field2D:copy ()
- Create a copy of the field with the same dimensions and contents